From ba7181babe3176676b89f409ea8383218a8ca81c Mon Sep 17 00:00:00 2001 From: Johannes Rudolph Date: Tue, 21 Jul 2015 13:47:16 +0200 Subject: [PATCH] +doc #15497 document encoding response entities of HEAD requests --- akka-docs-dev/rst/java/http/http-model.rst | 23 +++++++++++++++++++ .../rst/scala/http/common/http-model.rst | 22 ++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/akka-docs-dev/rst/java/http/http-model.rst b/akka-docs-dev/rst/java/http/http-model.rst index 07dca91e1f..ce52320bfb 100644 --- a/akka-docs-dev/rst/java/http/http-model.rst +++ b/akka-docs-dev/rst/java/http/http-model.rst @@ -159,6 +159,29 @@ entity regardless of its concrete subtype. Therefore you must make sure that you always consume the entity data, even in the case that you are not actually interested in it! +Special processing for HEAD requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`RFC 7230`_ defines very clear rules for the entity length of HTTP messages. + +Especially this rule requires special treatment in Akka HTTP: + + Any response to a HEAD request and any response with a 1xx + (Informational), 204 (No Content), or 304 (Not Modified) status + code is always terminated by the first empty line after the + header fields, regardless of the header fields present in the + message, and thus cannot contain a message body. + +Responses to HEAD requests introduce the complexity that `Content-Length` or `Transfer-Encoding` headers +can be present but the entity is empty. This is modeled by allowing `HttpEntityDefault` and `HttpEntityChunked` +to be used for HEAD responses with an empty data stream. + +Also, when a HEAD response has an `HttpEntityCloseDelimited` entity the Akka HTTP implementation will *not* close the +connection after the response has been sent. This allows the sending of HEAD responses without `Content-Length` +header across persistent HTTP connections. + +.. _RFC 7230: http://tools.ietf.org/html/rfc7230#section-3.3.3 + Header Model ------------ 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 4679c7ffac..39dbd13d79 100644 --- a/akka-docs-dev/rst/scala/http/common/http-model.rst +++ b/akka-docs-dev/rst/scala/http/common/http-model.rst @@ -156,6 +156,28 @@ concrete subtype. Therefore you must make sure that you always consume the entity data, even in the case that you are not actually interested in it! +Special processing for HEAD requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`RFC 7230`_ defines very clear rules for the entity length of HTTP messages. + +Especially this rule requires special treatment in Akka HTTP: + + Any response to a HEAD request and any response with a 1xx + (Informational), 204 (No Content), or 304 (Not Modified) status + code is always terminated by the first empty line after the + header fields, regardless of the header fields present in the + message, and thus cannot contain a message body. + +Responses to HEAD requests introduce the complexity that `Content-Length` or `Transfer-Encoding` headers +can be present but the entity is empty. This is modeled by allowing `HttpEntity.Default` and `HttpEntity.Chunked` +to be used for HEAD responses with an empty data stream. + +Also, when a HEAD response has an `HttpEntity.CloseDelimited` entity the Akka HTTP implementation will *not* close the +connection after the response has been sent. This allows the sending of HEAD responses without `Content-Length` +header across persistent HTTP connections. + +.. _RFC 7230: http://tools.ietf.org/html/rfc7230#section-3.3.3 Header Model ------------