+htp #18929 add withSizeLimit directive (#20760)

withSizeLimit and withoutSizeLimit directives added

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

@@ -218,6 +218,7 @@ Directive                                   Description
 :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-scala>` for a given route.
+:ref:`-withoutSizeLimit-`                   Skips request entity size check
 :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``
@@ -227,4 +228,5 @@ Directive                                   Description
 :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``
+:ref:`-withSizeLimit-`                      Applies request entity size check
 =========================================== ============================================================================

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

@@ -11,4 +11,6 @@ MiscDirectives
    requestEntityEmpty
    requestEntityPresent
    selectPreferredLanguage
-   validate
+   validate
+   withoutSizeLimit
+   withSizeLimit

akka-docs/rst/scala/http/routing-dsl/directives/misc-directives/withSizeLimit.rst

@@ -0,0 +1,40 @@
+.. _-withSizeLimit-:
+
+withSizeLimit
+===============
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala
+   :snippet: withSizeLimit
+
+Description
+-----------
+Fails the stream with ``EntityStreamSizeException`` if its request entity size exceeds given limit. Limit given
+as parameter overrides limit configured with ``akka.http.parsing.max-content-length``.
+
+The whole mechanism of entity size checking is intended to prevent certain Denial-of-Service attacks.
+So suggested setup is to have ``akka.http.parsing.max-content-length`` relatively low and use ``withSizeLimit``
+directive for endpoints which expects bigger entities.
+
+See also :ref:`-withoutSizeLimit-` for skipping request entity size check.
+
+Examples
+--------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+  :snippet: withSizeLimit-example
+
+Beware that request entity size check is executed when entity is consumed. Therefore in the following example
+even request with entity greater than argument to ``withSizeLimit`` will succeed (because this route
+does not consume entity):
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+  :snippet: withSizeLimit-execution-moment-example
+
+Directive ``withSizeLimit`` is implemented in terms of ``HttpEntity.withSizeLimit`` which means that in case of
+nested ``withSizeLimit`` directives the innermost is applied:
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+  :snippet: withSizeLimit-nested-example

akka-docs/rst/scala/http/routing-dsl/directives/misc-directives/withoutSizeLimit.rst

@@ -0,0 +1,26 @@
+.. _-withoutSizeLimit-:
+
+withoutSizeLimit
+================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala
+   :snippet: withoutSizeLimit
+
+Description
+-----------
+Skips request entity size verification.
+
+The whole mechanism of entity size checking is intended to prevent certain Denial-of-Service attacks.
+So suggested setup is to have ``akka.http.parsing.max-content-length`` relatively low and use ``withoutSizeLimit``
+directive just for endpoints for which size verification should not be performed.
+
+See also :ref:`-withSizeLimit-` for setting request entity size limit.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+  :snippet: withoutSizeLimit-example