+htp #18929 add withSizeLimit directive (#20760)

withSizeLimit and withoutSizeLimit directives added

akka-docs/rst/java/code/docs/http/javadsl/server/directives/MiscDirectivesExamplesTest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 2016-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.http.javadsl.server.directives;
+
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.server.Route;
+import akka.http.javadsl.server.Unmarshaller;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+import org.junit.Test;
+
+import java.util.Arrays;
+import java.util.function.Function;
+
+public class MiscDirectivesExamplesTest extends JUnitRouteTest {
+
+  @Test
+  public void testWithSizeLimit() {
+    //#withSizeLimitExample
+    final Route route = withSizeLimit(500, () ->
+      entity(Unmarshaller.entityToString(), (entity) ->
+        complete("ok")
+      )
+    );
+
+    Function<Integer, HttpRequest> withEntityOfSize = (sizeLimit) -> {
+      char[] charArray = new char[sizeLimit];
+      Arrays.fill(charArray, '0');
+      return HttpRequest.POST("/").withEntity(new String(charArray));
+    };
+
+    // tests:
+    testRoute(route).run(withEntityOfSize.apply(500))
+      .assertStatusCode(StatusCodes.OK);
+
+    testRoute(route).run(withEntityOfSize.apply(501))
+      .assertStatusCode(StatusCodes.BAD_REQUEST);
+    //#withSizeLimitExample
+  }
+
+  @Test
+  public void testWithoutSizeLimit() {
+    //#withoutSizeLimitExample
+    final Route route = withoutSizeLimit(() ->
+      entity(Unmarshaller.entityToString(), (entity) ->
+        complete("ok")
+      )
+    );
+
+    Function<Integer, HttpRequest> withEntityOfSize = (sizeLimit) -> {
+      char[] charArray = new char[sizeLimit];
+      Arrays.fill(charArray, '0');
+      return HttpRequest.POST("/").withEntity(new String(charArray));
+    };
+
+    // tests:
+    // will work even if you have configured akka.http.parsing.max-content-length = 500
+    testRoute(route).run(withEntityOfSize.apply(501))
+      .assertStatusCode(StatusCodes.OK);
+    //#withoutSizeLimitExample
+  }
+
+}

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

@@ -139,6 +139,7 @@ Directive                                        Description
 :ref:`-uploadedFile-java-`                       Streams one uploaded file from a multipart request to a file on disk
 :ref:`-validate-java-`                           Checks a given condition before running its inner route
 :ref:`-withoutRequestTimeout-java-`              Disables :ref:`request timeouts <request-timeout-java>` for a given route.
+:ref:`-withoutSizeLimit-java-`                   Skips request entity size check
 :ref:`-withExecutionContext-java-`               Runs its inner route with the given alternative ``ExecutionContext``
 :ref:`-withMaterializer-java-`                   Runs its inner route with the given alternative ``Materializer``
 :ref:`-withLog-java-`                            Runs its inner route with the given alternative ``LoggingAdapter``
@@ -146,5 +147,6 @@ Directive                                        Description
 :ref:`-withRequestTimeout-java-`                 Configures the :ref:`request timeouts <request-timeout-java>` for a given route.
 :ref:`-withRequestTimeoutResponse-java-`         Prepares the ``HttpResponse`` that is emitted if a request timeout is triggered. ``RequestContext => RequestContext`` function
 :ref:`-withSettings-java-`                       Runs its inner route with the given alternative ``RoutingSettings``
+:ref:`-withSizeLimit-java-`                      Applies request entity size check
 ================================================ ============================================================================
 

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

@@ -12,3 +12,5 @@ MiscDirectives
    requestEntityPresent
    selectPreferredLanguage
    validate
+   withoutSizeLimit
+   withSizeLimit

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

@@ -0,0 +1,20 @@
+.. _-withSizeLimit-java-:
+
+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-java-` for skipping request entity size check.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MiscDirectivesExamplesTest.java#withSizeLimitExample

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

@@ -0,0 +1,19 @@
+.. _-withoutSizeLimit-java-:
+
+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-java-` for setting request entity size limit.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MiscDirectivesExamplesTest.java#withSizeLimitExample