Fix for basic_parser::skip(true) and docs

fix #742

CHANGELOG.md

@@ -3,6 +3,10 @@ Version 106:
 * Dynamic buffer input areas are mutable
 * Add flat_static_buffer::reset
 
+HTTP:
+
+* Fix for basic_parser::skip(true) and docs
+
 WebSocket:
 
 * websocket test improvements

doc/qbk/05_http_examples.qbk

@@ -78,7 +78,11 @@ The
 [@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request]
 method indicates to the server that the client wishes to receive the
 entire header that would be delivered if the method was GET, except
-that the body is omitted.
+that the body is omitted. When a client wishes to receive the response
+to a HEAD request, it is necessary to inform the parser not to expect
+a body. This is done by calling
+[link beast.ref.boost__beast__http__basic_parser.skip `basic_parser::skip`]
+with the value `true`, as shown in this example:
 
 [example_http_do_head_request]
 

example/doc/http_examples.hpp

@@ -411,11 +411,18 @@ do_head_request(
         return {};
 
     // Create a parser to read the response.
-    // Responses to HEAD requests MUST NOT include
-    // a body, so we use the `empty_body` type and
-    // only attempt to read the header.
-    parser<false, empty_body> p;
-    read_header(stream, buffer, p, ec);
+    // We use the `empty_body` type since
+    // a response to a HEAD request MUST NOT
+    // include a body.
+    response_parser<empty_body> p;
+
+    // Inform the parser that there will be no body.
+    p.skip(true);
+
+    // Read the message. Even though fields like
+    // Content-Length or Transfer-Encoding may be
+    // set, the message will not contain a body.
+    read(stream, buffer, p, ec);
     if(ec)
         return {};
 

include/boost/beast/http/impl/basic_parser.ipp

@@ -587,10 +587,8 @@ finish_header(error_code& ec, std::false_type)
         //        treat the message as not having a body.
         //        https://github.com/boostorg/beast/issues/692
         state_ = state::complete;
-        return;
     }
-
-    if(f_ & flagContentLength)
+    else if(f_ & flagContentLength)
     {
         if(len_ > body_limit_)
         {

test/beast/http/basic_parser.cpp

@@ -325,8 +325,8 @@ public:
                     "GET / HTTP/1.1\r\n"
                     "f: " + s + "\r\n"
                     "\r\n";
-                parsegrind<parser<true, string_body>>(m,
-                    [&](parser<true, string_body> const& p)
+                parsegrind<request_parser<string_body>>(m,
+                    [&](request_parser<string_body> const& p)
                     {
                         BEAST_EXPECT(p.get()["f"] == value);
                     });

test/beast/http/read.cpp

@@ -385,7 +385,7 @@ public:
           "0\r\n\r\n";
         error_code ec;
         flat_buffer fb;
-        parser<false, dynamic_body> p;
+        response_parser<dynamic_body> p;
         read(c.server, fb, p, ec);
         BEAST_EXPECTS(! ec, ec.message());
     }