Add flow control

Flow control is disabled by default. The initial flow value
must be set to enable it (either for the entire connection
or on a per-request basis). Flow applies to all HTTP streams
as well as Websocket. HTTP/2 pushed streams receive the same
value as their originating stream.

2 files changed, 95 insertions, 0 deletions

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index da5548b..acc1454 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -46,6 +46,7 @@ Messages:
 
 Streams:
 
+* link:man:gun:update_flow(3)[gun:update_flow(3)] - Update a stream's flow control value
 * link:man:gun:cancel(3)[gun:cancel(3)] - Cancel the given stream
 * link:man:gun:stream_info(3)[gun:stream_info(3)] - Obtain information about a stream
 
@@ -143,6 +144,7 @@ Handshake timeout for tunneled TLS connections.
 [source,erlang]
 ----
 http_opts() :: #{
+    flow                  => pos_integer(),
     keepalive             => timeout(),
     transform_header_name => fun((binary()) -> binary()),
     version               => 'HTTP/1.1' | 'HTTP/1.0'
@@ -155,6 +157,11 @@ The default value is given next to the option name:
 
 // @todo Document content_handlers and gun_sse_h.
 
+flow - see below::
+
+The initial flow control value for all HTTP/1.1 streams.
+By default flow control is disabled.
+
 keepalive (infinity)::
 
 Time between pings in milliseconds. Since the HTTP protocol has
@@ -181,6 +188,7 @@ HTTP version to use.
 [source,erlang]
 ----
 http2_opts() :: #{
+    flow      => pos_integer(),
     keepalive => timeout()
 }
 ----
@@ -191,6 +199,11 @@ The default value is given next to the option name:
 
 // @todo Document content_handlers and gun_sse_h.
 
+flow - see below::
+
+The initial flow control value for all HTTP/2 streams.
+By default flow control is disabled.
+
 keepalive (5000)::
 
 Time between pings in milliseconds.
@@ -328,6 +341,7 @@ Request headers.
 [source,erlang]
 ----
 req_opts() :: #{
+    flow     => pos_integer(),
     reply_to => pid()
 }
 ----
@@ -336,6 +350,11 @@ Configuration for a particular request.
 
 The default value is given next to the option name:
 
+flow - see below::
+
+The initial flow control value for the stream. By default
+flow control is disabled.
+
 reply_to (`self()`)::
 
 The pid of the process that will receive the response messages.
@@ -346,6 +365,7 @@ The pid of the process that will receive the response messages.
 ----
 ws_opts() :: #{
     compress  => boolean(),
+    flow      => pos_integer(),
     protocols => [{binary(), module()}]
 }
 ----
@@ -360,6 +380,11 @@ Whether to enable permessage-deflate compression. This does
 not guarantee that compression will be used as it is the
 server that ultimately decides. Defaults to false.
 
+flow - see below::
+
+The initial flow control value for the Websocket connection.
+By default flow control is disabled.
+
 protocols ([])::
 
 A non-empty list enables Websocket protocol negotiation. The
@@ -378,6 +403,9 @@ undocumented and must be set to `gun_ws_h`.
          implement different reconnect strategies.
 * *2.0*: The `transport_opts` option has been split into
          two options: `tcp_opts` and `tls_opts`.
+* *2.0*: Function `gun:update_flow/3` introduced. The `flow`
+         option was added to request options and HTTP/1.1,
+         HTTP/2 and Websocket options as well.
 * *2.0*: Introduce the type `req_headers()` and extend the
          types accepted for header names for greater
          interoperability. Header names are automatically
diff --git a/doc/src/manual/gun.update_flow.asciidoc b/doc/src/manual/gun.update_flow.asciidoc
new file mode 100644
index 0000000..c7990f2
--- /dev/null
+++ b/doc/src/manual/gun.update_flow.asciidoc
@@ -0,0 +1,67 @@
+= gun:update_flow(3)
+
+== Name
+
+gun:update_flow - Update a stream's flow control value
+
+== Description
+
+[source,erlang]
+----
+update_flow(ConnPid, StreamRef, Flow) -> ok
+
+ConnPid   :: pid()
+StreamRef :: reference()
+Flow      :: pos_integer()
+----
+
+Update a stream's flow control value.
+
+The flow value can only ever be incremented.
+
+This function does nothing for streams that have flow
+control disabled (which is the default).
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+StreamRef::
+
+Identifier of the stream for the original request.
+
+Flow::
+
+Flow control value increment.
+
+== Return value
+
+The atom `ok` is returned.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Update a stream's flow control value
+[source,erlang]
+----
+gun:update_flow(ConnPid, StreamRef, 10).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:get(3)[gun:get(3)],
+link:man:gun:head(3)[gun:head(3)],
+link:man:gun:options(3)[gun:options(3)],
+link:man:gun:patch(3)[gun:patch(3)],
+link:man:gun:post(3)[gun:post(3)],
+link:man:gun:put(3)[gun:put(3)],
+link:man:gun:delete(3)[gun:delete(3)],
+link:man:gun:headers(3)[gun:headers(3)],
+link:man:gun:request(3)[gun:request(3)],
+link:man:gun:ws_upgrade(3)[gun:ws_upgrade(3)]