+doc,htp #19896 directives for RequestTimeout and docs

akka-docs/rst/scala/http/client-side/connection-level.rst

@@ -65,7 +65,12 @@ Timeouts
 
 Currently Akka HTTP doesn't implement client-side request timeout checking itself as this functionality can be regarded
 as a more general purpose streaming infrastructure feature.
-However, akka-stream should soon provide such a feature.
+
+It should be noted that Akka Streams provide various timeout functionality so any API that uses a streams can benefit
+from the stream stages such as ``idleTimeout``, ``completionTimeout``, ``initialTimeout`` and even ``throttle``.
+To learn more about these refer to their documentation in Akka Streams (and Scala Doc).
+
+For more details about timeout support in Akka HTTP in general refer to :ref:`http-timeouts`.
 
 
 .. _http-client-layer:

akka-docs/rst/scala/http/common/index.rst

@@ -18,4 +18,5 @@ which are specific to one side only.
    unmarshalling
    de-coding
    json-support
-   xml-support
+   xml-support
+   timeouts

akka-docs/rst/scala/http/common/timeouts.rst

@@ -0,0 +1,76 @@
+.. _http-timeouts:
+
+Akka HTTP Timeouts
+==================
+
+Akka HTTP comes with a variety of built-in timeout mechanisms to protect your servers from malicious attacks or
+programming mistakes. Some of these are simply configuration options (which may be overriden in code) while others
+are left to the streaming APIs and are easily implementable as patterns in user-code directly.
+
+Common timeouts
+---------------
+
+Idle timeouts
+^^^^^^^^^^^^^
+
+The ``idle-timeout`` is a global setting which sets the maximum inactivity time of a given connection.
+In other words, if a connection is open but no request/response is being written to it for over ``idle-timeout`` time,
+the connection will be automatically closed.
+
+The setting works the same way for all connections, be it server-side or client-side, and it's configurable
+independently for each of those using the following keys::
+
+    akka.http.server.idle-timeout
+    akka.http.client.idle-timeout
+    akka.http.http-connection-pool.idle-timeout
+    akka.http.http-connection-pool.client.idle-timeout
+
+.. note::
+  For the connection pooled client side the idle period is counted only when the pool has no pending requests waiting.
+
+
+Server timeouts
+---------------
+
+.. _request-timeout:
+
+Request timeout
+^^^^^^^^^^^^^^^
+
+Request timeouts are a mechanism that limits the maximum time it may take to produce an ``HttpResponse`` from a route.
+If that deadline is not met the server will automatically inject a Service Unavailable HTTP response and close the connection
+to prevent it from leaking and staying around indefinitely (for example if by programming error a Future would never complete,
+never sending the real response otherwise).
+
+The default ``HttpResponse`` that is written when a request timeout is exceeded looks like this:
+
+.. includecode2:: /../../akka-http-core/src/main/scala/akka/http/impl/engine/server/HttpServerBluePrint.scala
+   :snippet: default-request-timeout-httpresponse
+
+A default request timeout is applied globally to all routes and can be configured using the
+``akka.http.server.request-timeout`` setting (which defaults to 20 seconds).
+
+.. note::
+  Please note that if multiple requests (``R1,R2,R3,...``) were sent by a client (see "HTTP pipelining")
+  using the same connection and the ``n-th`` request triggers a request timeout the server will reply with an Http Response
+  and close the connection, leaving the ``(n+1)-th`` (and subsequent requests on the same connection) unhandled.
+
+The request timeout can be configured at run-time for a given route using the any of the :ref:`TimeoutDirectives`.
+
+Bind timeout
+^^^^^^^^^^^^
+
+The bind timeout is the time period within which the TCP binding process must be completed (using any of the ``Http().bind*`` methods).
+It can be configured using the ``akka.http.server.bind-timeout`` setting.
+
+Client timeouts
+---------------
+
+Connecting timeout
+^^^^^^^^^^^^^^^^^^
+
+The connecting timeout is the time period within which the TCP connecting process must be completed.
+Tweaking it should rarely be required, but it allows erroring out the connection in case a connection
+is unable to be established for a given amount of time.
+
+it can be configured using the ``akka.http.client.connecting-timeout`` setting.

akka-docs/rst/scala/http/routing-dsl/directives/alphabetically.rst

@@ -210,10 +210,14 @@ Directive                                   Description
 :ref:`-tprovide-`                           Injects a given tuple of values into a directive
 :ref:`-uploadedFile-`                       Streams one uploaded file from a multipart request to a file on disk
 :ref:`-validate-`                           Checks a given condition before running its inner route
+:ref:`-withoutRequestTimeout-`              Disables :ref:`request timeouts <request-timeout>` for a given route.
 :ref:`-withExecutionContext-`               Runs its inner route with the given alternative ``ExecutionContext``
 :ref:`-withMaterializer-`                   Runs its inner route with the given alternative ``Materializer``
 :ref:`-withLog-`                            Runs its inner route with the given alternative ``LoggingAdapter``
 :ref:`-withRangeSupport-`                   Adds ``Accept-Ranges: bytes`` to responses to GET requests, produces partial
                                             responses if the initial request contained a valid ``Range`` header
+:ref:`-withRequestTimeout-`                 Configures the :ref:`request timeouts <request-timeout>` for a given route.
+:ref:`-withRequestTimeoutResponse-`         Prepares the ``HttpResponse`` that is emitted if a request timeout is triggered.
+                                            ``RequestContext => RequestContext`` function
 :ref:`-withSettings-`                       Runs its inner route with the given alternative ``RoutingSettings``
 =========================================== ============================================================================

akka-docs/rst/scala/http/routing-dsl/directives/by-trait.rst

@@ -74,6 +74,9 @@ Directives creating or transforming the response
 :ref:`BasicDirectives` and :ref:`MiscDirectives`
   Directives handling or transforming response properties.
 
+:ref:`TimeoutDirectives`
+  Configure request timeouts and automatic timeout responses.
+
 
 List of predefined directives by trait
 --------------------------------------
@@ -104,3 +107,4 @@ List of predefined directives by trait
    scheme-directives/index
    security-directives/index
    websocket-directives/index
+   timeout-directives/index

akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/index.rst

@@ -0,0 +1,11 @@
+.. _TimeoutDirectives:
+
+TimeoutDirectives
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   withRequestTimeout
+   withoutRequestTimeout
+   withRequestTimeoutResponse

akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.rst

@@ -0,0 +1,49 @@
+.. _-withRequestTimeout-:
+
+withRequestTimeout
+==================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/TimeoutDirectives.scala
+   :snippet: withRequestTimeout
+
+Description
+-----------
+
+This directive enables "late" (during request processing) control over the :ref:`request-timeout` feature in Akka HTTP.
+
+The timeout can be either loosened or made more tight using this directive, however one should be aware that it is
+inherently racy (which may especially show with very tight timeouts) since a timeout may already have been triggered
+when this directive executes.
+
+In case of pipelined HTTP requests (multiple requests being accepted on the same connection before sending the first response)
+a the request timeout failure of the ``n-th`` request *will shut down the connection* causing the already enqueued requests
+to be dropped. This is by-design, as the request timeout feature serves as a "safety net" in case of programming errors
+(e.g. a Future that never completes thus potentially blocking the entire connection forever) or malicious attacks on the server.
+
+Optionally, a timeout handler may be provided in which is called when a time-out is triggered and must produce an
+``HttpResponse`` that will be sent back to the client instead of the "too late" response (in case it'd ever arrive).
+See also :ref:`-withRequestTimeoutResponse-` if only looking to customise the timeout response without changing the timeout itself.
+
+.. warning::
+  Please note that setting the timeout from within a directive is inherently racy (as the "point in time from which
+  we're measuring the timeout" is already in the past (the moment we started handling the request), so if the existing
+  timeout already was triggered before your directive had the chance to change it, an timeout may still be logged.
+
+  It is recommended to use a larger statically configured timeout (think of it as a "safety net" against programming errors
+  or malicious attackers) and if needed tighten it using the directives – not the other way around.
+
+For more information about various timeouts in Akka HTTP see :ref:`http-timeouts`.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/TimeoutDirectivesExamplesSpec.scala
+   :snippet: withRequestTimeout-plain
+
+With setting the handler at the same time:
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/TimeoutDirectivesExamplesSpec.scala
+   :snippet: withRequestTimeout-with-handler

akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.rst

@@ -0,0 +1,34 @@
+.. _-withRequestTimeoutResponse-:
+
+withRequestTimeoutResponse
+==========================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/TimeoutDirectives.scala
+   :snippet: withRequestTimeoutResponse
+
+Description
+-----------
+
+Allows customising the ``HttpResponse`` that will be sent to clients in case of a :ref:`request-timeout`.
+
+See also :ref:`-withRequestTimeout-` or :ref:`-withoutRequestTimeout-` if interested in dynamically changing the timeout
+for a given route instead.
+
+.. warning::
+  Please note that setting handler is inherently racy as the timeout is measured from starting to handle the request
+  to its deadline, thus if the timeout triggers before the ``withRequestTimeoutResponse`` executed it would have emitted
+  the default timeout HttpResponse.
+
+  In practice this can only be a problem with very tight timeouts, so with default settings
+  of request timeouts being measured in seconds it shouldn't be a problem in reality (though certainly a possibility still).
+
+To learn more about various timeouts in Akka HTTP and how to configure them see :ref:`http-timeouts`.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/TimeoutDirectivesExamplesSpec.scala
+   :snippet: withRequestTimeoutResponse

akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.rst

@@ -0,0 +1,31 @@
+.. _-withoutRequestTimeout-:
+
+withoutRequestTimeout
+=====================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/TimeoutDirectives.scala
+   :snippet: withoutRequestTimeout
+
+Description
+-----------
+
+This directive enables "late" (during request processing) control over the :ref:`request-timeout` feature in Akka HTTP.
+
+It is not recommended to turn off request timeouts using this method as it is inherently racy and disabling request timeouts
+basically turns off the safety net against programming mistakes that it provides.
+
+.. warning::
+  Please note that setting the timeout from within a directive is inherently racy (as the "point in time from which
+  we're measuring the timeout" is already in the past (the moment we started handling the request), so if the existing
+  timeout already was triggered before your directive had the chance to change it, an timeout may still be logged.
+
+For more information about various timeouts in Akka HTTP see :ref:`http-timeouts`.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/TimeoutDirectivesExamplesSpec.scala
+   :snippet: withoutRequestTimeout