Update the migration guide and the gun(3) manual

2 files changed, 98 insertions, 37 deletions

diff --git a/doc/src/guide/migrating_from_1.3.asciidoc b/doc/src/guide/migrating_from_1.3.asciidoc
index a20a058..aa7d26b 100644
--- a/doc/src/guide/migrating_from_1.3.asciidoc
+++ b/doc/src/guide/migrating_from_1.3.asciidoc
@@ -1,12 +1,16 @@
 [appendix]
 == Migrating from Gun 1.3 to 2.0
 
-Gun 2.0 adds many features including graceful shutdown,
-flow control for data messages, event handlers, support
-for tunneling TLS connections through TLS proxies, Socks
-proxy support, and much more. It has only a limited
-number of breaking changes compared to the previous
-version.
+Gun 2.0 includes state of the art tunnel support. With
+Gun 2.0 it is possible to make request or data go through
+any number of proxy endpoints using any combination of
+TCP or TLS transports and HTTP/1.1, HTTP/2 or SOCKS5
+protocols. All combinations of the scenario Proxy1 ->
+Proxy2 -> Origin are tested and known to work.
+
+Gun 2.0 adds many more features such as Websocket over
+HTTP/2, a built-in cookie store, graceful shutdown, flow
+control for data messages, event handlers and more.
 
 Gun 2.0 greatly improves the HTTP/2 performance when it
 comes to receiving large response bodies; and when receiving
@@ -63,21 +67,21 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   timeout options for each of the steps, and the transport
   options had to be split into `tcp_opts` and `tls_opts`.
 
-* Gun can connect through any number of HTTP, HTTPS, Socks
-  or secure Socks proxies, including when Socks proxies are
-  located after the HTTP(S) proxies. The ultimate endpoint
+* Gun now supports connecting through SOCKS proxies,
+  including secure SOCKS proxies. Both unauthenticated
+  and username/password authentication are supported.
+
+* Gun can connect through any number of HTTP, HTTPS, SOCKS
+  or secure SOCKS proxies, including SOCKS proxies
+  located after HTTP(S) proxies. The ultimate endpoint
   may be using any protocol, including plain TCP, TLS,
   HTTP/1.1 or HTTP/2.
 
-* Gun now supports connecting through Socks5 proxies,
-  including secure Socks proxies. Both unauthenticated
-  and username/password authentication are supported.
-
 * When specifying which protocols to use, options can
   now be provided specific to those protocols. It is
   now possible to have separate HTTP options for an
   HTTP proxy and the origin HTTP server, for example.
-  See the new `protocols()` type for details.
+  See the new `gun:protocols()` type for details.
 
 * Gun can now be used to send and receive raw data,
   as if it was just a normal socket. This can be
@@ -91,6 +95,8 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
 
 * Header names may now be provided as binary, string or atom.
 
+* Gun now automatically lowercases provided header names.
+
 * Many HTTP/2 options have been added, allowing great
   control over how Gun and the remote endpoint are
   using the HTTP/2 connection. They can be used to
@@ -100,9 +106,9 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
 * It is now possible to send many Websocket frames in
   a single `gun:ws_send/2` call.
 
-* Gun will now send Websocket ping frames automatically
+* Gun may now send Websocket ping frames automatically
   at intervals determined by the `keepalive` option. It
-  defaults to 5 seconds.
+  is disabled by default.
 
 * A new `silence_pings` option can be set to `false` to
   receive all ping and pong frames when using Websocket.
@@ -124,13 +130,13 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   connection without using Gun's supervisor. It defaults
   to `true`.
 
-* Gun now automatically lowercases provided header names.
-
 * Many improvements have been done to postpone or reject
   requests and other operations while in the wrong state
   (for example during state transitions when switching
   protocols or connecting to proxies).
 
+* Update Cowlib to 2.10.0.
+
 === Features removed
 
 * Gun used to reject operations by processes that were not
@@ -143,8 +149,8 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   removed. It was previously deprecated in favor of `protocols`.
 
 * The `keepalive` timeout is now disabled by default
-  for HTTP/1.1. To be perfectly clear, this is unrelated
-  to the HTTP/1.1 keep-alive mechanism.
+  for HTTP/1.1 and HTTP/2. To be perfectly clear, this
+  is unrelated to the HTTP/1.1 keep-alive mechanism.
 
 === Functions added
 
@@ -161,20 +167,28 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
 
 === Functions modified
 
-* The function `gun:info/1` now returns the owner of the connection.
+* The function `gun:info/1` now returns the owner of the
+  connection as well as the cookie store.
 
 * The functions `gun:await/2,3,4`, `gun:await_body/2,3,4` and
   `gun:await_up/1,2,3` now distinguish the error types. They
   can be a timeout, a connection error, a stream error or a
   down error (when the Gun process exited while waiting).
 
-* The functions `gun:await/2,3,4` will now receive upgrade and
-  Websocket messages and return them.
+* The functions `gun:await/2,3,4` will now receive upgrades,
+  tunnel up and Websocket messages and return them.
+
+* Requests may now include the `tunnel` option to send the
+  request on a specific tunnel.
 
 * The functions `gun:request/4,5,6` have been replaced with
   `gun:headers/4,5` and `gun:request/5,6`. This provides a
   cleaner separation between requests that are followed by
-  a body separately from those that don't.
+  a body and those that don't.
+
+=== Messages added
+
+* The `gun_tunnel_up` message has been added.
 
 === Messages modified
 
@@ -189,6 +203,8 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   contribute to a response smuggling security vulnerability
   when Gun is used inside a proxy.
 
+* Gun will now better detect connection closes in some cases.
+
 * Gun will no longer send duplicate connection-wide `gun_error`
   messages to the same process.
 
@@ -199,6 +215,9 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   CONNECT over TLS has been corrected. It was mistakenly not
   enabling HTTP/2.
 
+* Protocol options provided for a tunnel destination were
+  sometimes ignored. This should no longer be the case.
+
 * Gun will no longer send an empty HTTP/2 DATA frame when
   there is no request body. It was not necessary.
 
@@ -218,7 +237,7 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
 
 * Gun will no longer attempt to send empty data chunks. When
   using HTTP/1.1 chunked transfer-encoding this caused the
-  request body to terminated, even when `nofin` was given.
+  request body to end, even when `nofin` was given.
 
 * Gun now always retries connecting immediately when the
   connection goes down.
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 8cf46cc..d130d62 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -148,11 +148,12 @@ Handshake timeout for tunneled TLS connections.
 [source,erlang]
 ----
 http_opts() :: #{
-    closing_timeout       => timeout(),
-    flow                  => pos_integer(),
-    keepalive             => timeout(),
-    transform_header_name => fun((binary()) -> binary()),
-    version               => 'HTTP/1.1' | 'HTTP/1.0'
+    closing_timeout             => timeout(),
+    cookie_ignore_informational => boolean(),
+    flow                        => pos_integer(),
+    keepalive                   => timeout(),
+    transform_header_name       => fun((binary()) -> binary()),
+    version                     => 'HTTP/1.1' | 'HTTP/1.0'
 }
 ----
 
@@ -168,6 +169,11 @@ Time to wait before brutally closing the connection when a
 graceful shutdown was requested via a call to
 link:man:gun:shutdown(3)[gun:shutdown(3)].
 
+cookie_ignore_informational (false)::
+
+Whether cookies received inside informational responses
+(1xx status code) must be ignored.
+
 flow - see below::
 
 The initial flow control value for all HTTP/1.1 streams.
@@ -199,9 +205,10 @@ HTTP version to use.
 [source,erlang]
 ----
 http2_opts() :: #{
-    closing_timeout => timeout(),
-    flow            => pos_integer(),
-    keepalive       => timeout(),
+    closing_timeout             => timeout(),
+    cookie_ignore_informational => boolean(),
+    flow                        => pos_integer(),
+    keepalive                   => timeout(),
 
     %% HTTP/2 state machine configuration.
     connection_window_margin_size  => 0..16#7fffffff,
@@ -236,6 +243,11 @@ Time to wait before brutally closing the connection when a
 graceful shutdown was requested either via a call to
 link:man:gun:shutdown(3)[gun:shutdown(3)] or by the server.
 
+cookie_ignore_informational (false)::
+
+Whether cookies received inside informational responses
+(1xx status code) must be ignored.
+
 flow - see below::
 
 The initial flow control value for all HTTP/2 streams.
@@ -373,9 +385,12 @@ Options specific to the Websocket protocol.
 
 [source,erlang]
 ----
-protocols() :: http | {http, http_opts()}
-             | http2 | {http2, http2_opts()}
-             | socks | {socks, socks_opts()}
+Protocol :: http | {http, http_opts()}
+          | http2 | {http2, http2_opts()}
+          | raw | {raw, raw_opts()}
+          | socks | {socks, socks_opts()}
+
+protocols() :: [Protocol]
 ----
 
 Ordered list of preferred protocols. When the transport is `tcp`,
@@ -388,6 +403,18 @@ preferred protocols is set to only accept `socks`.
 Defaults to `[http]` when the transport is `tcp`,
 and `[http2, http]` when the transport is `tls`.
 
+=== raw_opts()
+
+[source,erlang]
+----
+raw_opts() :: #{
+}
+----
+
+Configuration for the "raw" protocol.
+
+// The default value is given next to the option name:
+
 === req_headers()
 
 [source,erlang]
@@ -479,6 +506,18 @@ version (5)::
 
 Version of the Socks protocol to use.
 
+=== stream_ref()
+
+[source,erlang]
+----
+stream_ref() - see below
+----
+
+Unique identifier for a stream.
+
+The exact type is considered to be an implementation
+detail.
+
 === ws_opts()
 
 [source,erlang]
@@ -535,9 +574,11 @@ when receiving a ping.
 
 == Changelog
 
+* *2.0*: The `stream_ref()` type was added.
 * *2.0*: The option `cookie_store` was added. It can be used
          to configure a cookie store that Gun will use
-         automatically.
+         automatically. A related option, `cookie_ignore_informational`,
+         was added to both `http_opts()` and `http2_opts()`.
 * *2.0*: The types `protocols()` and `socks_opts()` have been
          added. Support for the Socks protocol has been added
          in every places where protocol selection is available.
@@ -561,6 +602,7 @@ when receiving a ping.
 * *2.0*: The `keepalive` option is now set to `infinity` by
          default for all protocols. This means it is disabled.
 * *2.0*: Websocket options `keepalive` and `silence_pings` introduced.
+* *2.0*: Remove the `protocol` option from `connect_destination()`.
 * *1.3*: Add the CONNECT destination's `protocols` option and
          deprecate the previously introduced `protocol` option.
 * *1.2*: Introduce the type `connect_destination()`.