+doc #15497 document encoding response entities of HEAD requests

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
 ------------

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
 ------------