=htc #368 document the guarantees of max-connections (#473)

* =htc #368 document the guarantees of `max-connections` Actually providing better guarantees turned out to be difficult, so being clear about the limit being an approximate one seems to be the best solution for now. See also the discussions in #371. Fixes #368. * =htc #368 be more accurate about `max-connections` To find out whether the materialization for one connection has finished bindAndHandle will now use two `watchTermination` combinators. As explained in the Scaladoc this will still not provide 100 percent guarantee that all of the flow will have finished but it is hopefully more accurate than before.
akka · Nov 7, 2016 · c7ac641 · c7ac641
1 parent 05f4c01
commit c7ac641
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 11 deletions.
diff --git a/akka-http-core/src/main/resources/reference.conf b/akka-http-core/src/main/resources/reference.conf
@@ -38,6 +38,13 @@ akka.http {
     #
     # This setting doesn't apply to the `Http().bind` method which will still
     # deliver an unlimited backpressured stream of incoming connections.
+    #
+    # Note, that this setting limits the number of the connections on a best-effort basis.
+    # It does *not* strictly guarantee that the number of established TCP connections will never
+    # exceed the limit (but it will be approximately correct) because connection termination happens
+    # asynchronously. It also does *not* guarantee that the number of concurrently active handler
+    # flow materializations will never exceed the limit for the reason that it is impossible to reliably
+    # detect when a materialization has ended.
     max-connections = 1024
 
     # The maximum number of requests that are accepted (and dispatched to

diff --git a/akka-http-core/src/main/scala/akka/http/javadsl/Http.scala b/akka-http-core/src/main/scala/akka/http/javadsl/Http.scala
@@ -161,7 +161,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].
@@ -182,7 +183,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].
@@ -205,7 +207,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].
@@ -224,7 +227,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].
@@ -247,7 +251,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].
@@ -266,7 +271,8 @@ class Http(system: ExtendedActorSystem) extends akka.actor.Extension {
    * [[akka.stream.javadsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * The server will be bound using HTTPS if the [[ConnectHttp]] object is configured with an [[HttpsConnectionContext]],
    * or the [[defaultServerHttpContext]] has been configured to be an [[HttpsConnectionContext]].

diff --git a/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala b/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala
@@ -91,6 +91,11 @@ class HttpExt(private val config: Config)(implicit val system: ActorSystem) exte
         Flow[HttpRequest]
           .watchTermination()(Keep.right)
           .viaMat(handler)(Keep.left)
+          .watchTermination() { (termWatchBefore, termWatchAfter) ⇒
+            // flag termination when the user handler has gotten (or has emitted) termination
+            // signals in both directions
+            termWatchBefore.flatMap(_ ⇒ termWatchAfter)(ExecutionContexts.sameThreadExecutionContext)
+          }
           .joinMat(baseFlow)(Keep.left)
       )
     )
@@ -151,7 +156,8 @@ class HttpExt(private val config: Config)(implicit val system: ActorSystem) exte
    * [[akka.stream.scaladsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * To configure additional settings for a server started using this method,
    * use the `akka.http.server` config section or pass in a [[akka.http.scaladsl.settings.ServerSettings]] explicitly.
@@ -176,8 +182,7 @@ class HttpExt(private val config: Config)(implicit val system: ActorSystem) exte
               // As far as it is known currently, these errors can only happen if a TCP error bubbles up
               // from the TCP layer through the HTTP layer to the Http.IncomingConnection.flow.
               // See https://github.com/akka/akka/issues/17992
-              case NonFatal(ex) ⇒
-                Done
+              case NonFatal(ex) ⇒ Done
             }(ExecutionContexts.sameThreadExecutionContext)
         } catch {
           case NonFatal(e) ⇒
@@ -195,7 +200,8 @@ class HttpExt(private val config: Config)(implicit val system: ActorSystem) exte
    * [[akka.stream.scaladsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * To configure additional settings for a server started using this method,
    * use the `akka.http.server` config section or pass in a [[akka.http.scaladsl.settings.ServerSettings]] explicitly.
@@ -213,7 +219,8 @@ class HttpExt(private val config: Config)(implicit val system: ActorSystem) exte
    * [[akka.stream.scaladsl.Flow]] for processing all incoming connections.
    *
    * The number of concurrently accepted connections can be configured by overriding
-   * the `akka.http.server.max-connections` setting.
+   * the `akka.http.server.max-connections` setting. Please see the documentation in the reference.conf for more
+   * information about what kind of guarantees to expect.
    *
    * To configure additional settings for a server started using this method,
    * use the `akka.http.server` config section or pass in a [[akka.http.scaladsl.settings.ServerSettings]] explicitly.