Implement flow control for HTTP/1.1

We now stop reading from the socket unless asked to,
when we reach the request body. The option
initial_stream_flow_size controls how much data
we read without being asked, as an optimization.
We may also have received additional data along
with the request headers.

This commit also reworks the timeout handling for HTTP/1.1
because the stray timeout message was easily reproducible
after implementing the flow control. The issue should be
gone for good this time.

doc/src/guide/migrating_from_2.6.asciidoc

@@ -63,6 +63,13 @@ Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
   willing to accept. By default it will accept 10
   stream resets every 10 seconds.
 
+* Flow control for incoming data has been implemented
+  for HTTP/1.1. Cowboy will now wait for the user code
+  to ask for the request body before reading it from
+  the socket. The option `initial_stream_flow_size`
+  controls how much data Cowboy will read without
+  being asked.
+
 * The HTTP/1.1 and HTTP/2 option `logger` is now
   documented.
 
@@ -154,7 +161,9 @@ Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
   was waiting for more data.
 
 * It was possible for Cowboy to receive stray timeout messages
-  for HTTP/1.1 connections. This has been addressed.
+  for HTTP/1.1 connections, resulting in crashes. The timeout
+  handling in HTTP/1.1 has been reworked and the issue should
+  no longer occur.
 
 * The type for the Req object has been updated to accept
   custom fields as was already documented.

doc/src/manual/cowboy_http.asciidoc

@@ -17,25 +17,26 @@ as a Ranch protocol.
 [source,erlang]
 ----
 opts() :: #{
-    chunked                 => boolean(),
-    connection_type         => worker | supervisor,
-    http10_keepalive        => boolean(),
-    idle_timeout            => timeout(),
-    inactivity_timeout      => timeout(),
-    linger_timeout          => timeout(),
-    logger                  => module(),
-    max_empty_lines         => non_neg_integer(),
-    max_header_name_length  => non_neg_integer(),
-    max_header_value_length => non_neg_integer(),
-    max_headers             => non_neg_integer(),
-    max_keepalive           => non_neg_integer(),
-    max_method_length       => non_neg_integer(),
-    max_request_line_length => non_neg_integer(),
-    max_skip_body_length    => non_neg_integer(),
-    proxy_header            => boolean(),
-    request_timeout         => timeout(),
-    sendfile                => boolean(),
-    stream_handlers         => [module()]
+    chunked                  => boolean(),
+    connection_type          => worker | supervisor,
+    http10_keepalive         => boolean(),
+    idle_timeout             => timeout(),
+    inactivity_timeout       => timeout(),
+    initial_stream_flow_size => non_neg_integer(),
+    linger_timeout           => timeout(),
+    logger                   => module(),
+    max_empty_lines          => non_neg_integer(),
+    max_header_name_length   => non_neg_integer(),
+    max_header_value_length  => non_neg_integer(),
+    max_headers              => non_neg_integer(),
+    max_keepalive            => non_neg_integer(),
+    max_method_length        => non_neg_integer(),
+    max_request_line_length  => non_neg_integer(),
+    max_skip_body_length     => non_neg_integer(),
+    proxy_header             => boolean(),
+    request_timeout          => timeout(),
+    sendfile                 => boolean(),
+    stream_handlers          => [module()]
 }
 ----
 
@@ -79,6 +80,12 @@ inactivity_timeout (300000)::
 
 Time in ms with nothing received at all before Cowboy closes the connection.
 
+initial_stream_flow_size (65535)::
+
+Amount of data in bytes Cowboy will read from the socket
+right after a request was fully received. This is a soft
+limit.
+
 linger_timeout (1000)::
 
 Time in ms that Cowboy will wait when closing the connection. This is
@@ -144,7 +151,7 @@ Ordered list of stream handlers that will handle all stream events.
 
 == Changelog
 
-* *2.7*: The `logger` option was added.
+* *2.7*: The `initial_stream_flow_size` and `logger` options were added.
 * *2.6*: The `chunked`, `http10_keepalive`, `proxy_header` and `sendfile` options were added.
 * *2.5*: The `linger_timeout` option was added.
 * *2.2*: The `max_skip_body_length` option was added.