+htp #18929 add withSizeLimit directive (#20760)

withSizeLimit and withoutSizeLimit directives added

akka-docs/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala

@@ -22,6 +22,7 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "Client's ip is 192.168.3.12"
     }
   }
+
   "rejectEmptyResponse-example" in {
     val route = rejectEmptyResponse {
       path("even" / IntNumber) { i =>
@@ -42,6 +43,7 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "Number 28 is even."
     }
   }
+
   "requestEntityEmptyPresent-example" in {
     val route =
       requestEntityEmpty {
@@ -59,6 +61,7 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "request entity empty"
     }
   }
+
   "selectPreferredLanguage-example" in {
     val request = Get() ~> `Accept-Language`(
       Language("en-US"),
@@ -78,6 +81,7 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       }
     } ~> check { responseAs[String] shouldEqual "de-DE" }
   }
+
   "validate-example" in {
     val route =
       extractUri { uri =>
@@ -94,4 +98,84 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       rejection shouldEqual ValidationRejection("Path too long: '/abcdefghijkl'", None)
     }
   }
+
+  "withSizeLimit-example" in {
+    val route = withSizeLimit(500) {
+      entity(as[String]) { _ ⇒
+        complete(HttpResponse())
+      }
+    }
+
+    // tests:
+    def entityOfSize(size: Int) =
+      HttpEntity(ContentTypes.`text/plain(UTF-8)`, "0" * size)
+
+    Post("/abc", entityOfSize(500)) ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+
+    Post("/abc", entityOfSize(501)) ~> Route.seal(route) ~> check {
+      status shouldEqual StatusCodes.BadRequest
+    }
+
+  }
+
+  "withSizeLimit-execution-moment-example" in {
+    val route = withSizeLimit(500) {
+      complete(HttpResponse())
+    }
+
+    // tests:
+    def entityOfSize(size: Int) =
+      HttpEntity(ContentTypes.`text/plain(UTF-8)`, "0" * size)
+
+    Post("/abc", entityOfSize(500)) ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+
+    Post("/abc", entityOfSize(501)) ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+  }
+
+  "withSizeLimit-nested-example" in {
+    val route =
+      withSizeLimit(500) {
+        withSizeLimit(800) {
+          entity(as[String]) { _ ⇒
+            complete(HttpResponse())
+          }
+        }
+      }
+
+    // tests:
+    def entityOfSize(size: Int) =
+      HttpEntity(ContentTypes.`text/plain(UTF-8)`, "0" * size)
+    Post("/abc", entityOfSize(800)) ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+
+    Post("/abc", entityOfSize(801)) ~> Route.seal(route) ~> check {
+      status shouldEqual StatusCodes.BadRequest
+    }
+  }
+
+  "withoutSizeLimit-example" in {
+    val route =
+      withoutSizeLimit {
+        entity(as[String]) { _ ⇒
+          complete(HttpResponse())
+        }
+      }
+
+    // tests:
+    def entityOfSize(size: Int) =
+      HttpEntity(ContentTypes.`text/plain(UTF-8)`, "0" * size)
+
+    // will work even if you have configured akka.http.parsing.max-content-length = 500
+    Post("/abc", entityOfSize(501)) ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+  }
+
 }

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