diff options
Diffstat (limited to 'docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc')
| -rw-r--r-- | docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc | 75 |
1 files changed, 49 insertions, 26 deletions
diff --git a/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc b/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc index a20a0582..0afd19eb 100644 --- a/docs/en/gun/2.0/guide/migrating_from_1.3.asciidoc +++ b/docs/en/gun/2.0/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 @@ -98,11 +104,11 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater. example. * It is now possible to send many Websocket frames in - a single `gun:ws_send/2` call. + a single `gun:ws_send/3` 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,32 @@ 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. + +* The function `gun:ws_send/2` has been replaced with the + function `gun:ws_send/3`. The stream reference for the + corresponding Websocket upgrade request must now be given. + +=== Messages added + +* The `gun_tunnel_up` message has been added. === Messages modified @@ -189,6 +207,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 +219,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 +241,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. |