From 9d5fcabbd69d23c25748e0d4dc8bda453a09fb9e Mon Sep 17 00:00:00 2001 From: Konrad Malawski Date: Sun, 13 Dec 2015 16:17:20 +0000 Subject: [PATCH] =htc,doc more docs on EntityStreamSizeException --- akka-docs-dev/rst/scala/http/common/http-model.rst | 3 ++- .../scala/akka/http/scaladsl/model/ErrorInfo.scala | 13 ++++++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/akka-docs-dev/rst/scala/http/common/http-model.rst b/akka-docs-dev/rst/scala/http/common/http-model.rst index c1a3f15144..1e6a0c2cd9 100644 --- a/akka-docs-dev/rst/scala/http/common/http-model.rst +++ b/akka-docs-dev/rst/scala/http/common/http-model.rst @@ -166,6 +166,7 @@ them. This check makes sure that the total entity size is less than or equal to However, a single global limit for all requests (or responses) is often too inflexible for applications that need to allow large limits for *some* requests (or responses) but want to clamp down on all messages not belonging into that group. + In order to give you maximum flexibility in defining entity size limits according to your needs the ``HttpEntity`` features a ``withSizeLimit`` method, which lets you adjust the globally configured maximum size for this particular entity, be it to increase or decrease any previously set value. @@ -173,7 +174,7 @@ This means that your application will receive all requests (or responses) from t ``Content-Length`` exceeds the configured limit (because you might want to increase the limit yourself). Only when the actual data stream ``Source`` contained in the entity is materialized will the boundary checks be actually applied. In case the length verification fails the respective stream will be terminated with an -``EntityStreamException`` either directly at materialization time (if the ``Content-Length`` is known) or whenever more +:class:`EntityStreamSizeException` either directly at materialization time (if the ``Content-Length`` is known) or whenever more data bytes than allowed have been read. When called on ``Strict`` entities the ``withSizeLimit`` method will return the entity itself if the length is within diff --git a/akka-http-core/src/main/scala/akka/http/scaladsl/model/ErrorInfo.scala b/akka-http-core/src/main/scala/akka/http/scaladsl/model/ErrorInfo.scala index 019510c581..aef5eb4917 100644 --- a/akka-http-core/src/main/scala/akka/http/scaladsl/model/ErrorInfo.scala +++ b/akka-http-core/src/main/scala/akka/http/scaladsl/model/ErrorInfo.scala @@ -72,8 +72,19 @@ object EntityStreamException { def apply(summary: String, detail: String = ""): EntityStreamException = apply(ErrorInfo(summary, detail)) } +/** + * This exception is thrown when the size of the HTTP Entity exceeds the configured limit. + * It is possible to configure the limit using configuration options `akka.http.parsing.max-content-length` + * or specifically for the server or client side by setting `akka.http.[server|client].parsing.max-content-length`. + * + * The limit can also be configured in code, by calling [[HttpEntity#withSizeLimit]] + * on the entity before materializing its `dataBytes` stream. + */ case class EntityStreamSizeException(limit: Long, actualSize: Option[Long] = None) extends RuntimeException { - override def toString = s"EntityStreamSizeException($limit, $actualSize)" + override def toString = + s"EntityStreamSizeException: actual entity size ($actualSize) exceeded content length limit ($limit bytes)! " + + s"You can configure this by setting `akka.http.[server|client].parsing.max-content-length` or calling `HttpEntity.withSizeLimit` " + + s"before materializing the dataBytes stream." } case class RequestTimeoutException(request: HttpRequest, message: String) extends RuntimeException(message)