aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/book.asciidoc2
-rw-r--r--doc/src/guide/migrating_from_1.0.asciidoc2
-rw-r--r--doc/src/guide/migrating_from_1.1.asciidoc4
-rw-r--r--doc/src/guide/migrating_from_1.2.asciidoc2
-rw-r--r--doc/src/guide/migrating_from_1.3.asciidoc220
5 files changed, 226 insertions, 4 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index b374c7a..46109ac 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -20,6 +20,8 @@ include::websocket.asciidoc[Using Websocket]
= Additional information
+include::migrating_from_1.3.asciidoc[Migrating from Gun 1.3 to 2.0]
+
include::migrating_from_1.2.asciidoc[Migrating from Gun 1.2 to 1.3]
include::migrating_from_1.1.asciidoc[Migrating from Gun 1.1 to 1.2]
diff --git a/doc/src/guide/migrating_from_1.0.asciidoc b/doc/src/guide/migrating_from_1.0.asciidoc
index 8057683..3a11cfd 100644
--- a/doc/src/guide/migrating_from_1.0.asciidoc
+++ b/doc/src/guide/migrating_from_1.0.asciidoc
@@ -4,7 +4,7 @@
Gun 1.1 updates the Cowlib dependency to 2.5.1 and fixes a
few problems with experimental features.
-== Features added
+=== Features added
* Update Cowlib to 2.5.1
diff --git a/doc/src/guide/migrating_from_1.1.asciidoc b/doc/src/guide/migrating_from_1.1.asciidoc
index bc2097f..7e0acf9 100644
--- a/doc/src/guide/migrating_from_1.1.asciidoc
+++ b/doc/src/guide/migrating_from_1.1.asciidoc
@@ -4,7 +4,7 @@
Gun 1.2 adds support for the CONNECT request over HTTP/1.1
connections.
-== Features added
+=== Features added
* CONNECT requests can now be issued on HTTP/1.1 connections.
The tunneled connection can use any of the protocols Gun
@@ -22,7 +22,7 @@ connections.
* Update Cowlib to 2.6.0
-== Functions added
+=== Functions added
* The functions `gun:connect/2,3,4` have been added. They can
be used to initiate CONNECT requests on HTTP/1.1 connections.
diff --git a/doc/src/guide/migrating_from_1.2.asciidoc b/doc/src/guide/migrating_from_1.2.asciidoc
index a870858..3b31092 100644
--- a/doc/src/guide/migrating_from_1.2.asciidoc
+++ b/doc/src/guide/migrating_from_1.2.asciidoc
@@ -5,7 +5,7 @@ Gun 1.3 improves the support for CONNECT requests
introduced in the previous version and documents
Websocket protocol negotiation.
-== Features added
+=== Features added
* The `protocols` CONNECT destination option has been added
as a replacement for the now deprecated `protocol` option.
diff --git a/doc/src/guide/migrating_from_1.3.asciidoc b/doc/src/guide/migrating_from_1.3.asciidoc
new file mode 100644
index 0000000..1e2b894
--- /dev/null
+++ b/doc/src/guide/migrating_from_1.3.asciidoc
@@ -0,0 +1,220 @@
+[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 greatly improves the HTTP/2 performance when it
+comes to receiving large response bodies; and when receiving
+response bodies from many separate requests concurrently.
+
+Gun now shares much of its HTTP/2 code with Cowboy,
+including the HTTP/2 state machine. Numerous issues were
+fixed as a result because the Cowboy implementation was
+much more advanced.
+
+The Gun connection process is now implemented using `gen_statem`.
+
+Gun 2.0 requires Erlang/OTP 20.0 or greater.
+
+=== Features added
+
+* Graceful shutdown has been implemented. Graceful shutdown
+ can be initiated on the client side by calling the new
+ function `gun:shutdown/1` or when the owner process goes
+ away; or on the peer side via the connection: close HTTP/1.1
+ header, the HTTP/2 GOAWAY frame or the Websocket close frame.
+ Gun will try to complete existing streams when possible;
+ other streams get canceled immediately. The `closing_timeout`
+ option controls how long we are willing to wait at most
+ before closing the connection.
+
+* Flow control has been added. It allows limiting the number
+ of data/Websocket messages Gun sends to the calling process.
+ Gun will stop reading from the socket or stop updating the
+ protocol's flow control window when applicable as well, to
+ apply some backpressure to the remote endpoint(s). It is
+ disabled by default and can be applied on a per-request
+ basis if necessary.
+
+* An event handler interface has been added providing access
+ to many internal Gun events. This can be used for a variety
+ of purposes including logging, tracing or otherwise
+ instrumenting a Gun connection.
+
+* In order to get separate events when connecting, the domain
+ lookup, connection and TLS handshakes are now performed
+ separately by Gun. As a result, there exists three separate
+ 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
+ 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.
+
+* Gun can now be used to send and receive raw data,
+ as if it was just a normal socket. This can be
+ useful when needing to connect through a number
+ of HTTP/Socks proxies, allowing the use of Gun's
+ great proxying capabilities (including TLS over TLS)
+ for any sort of protocols. This can also be useful
+ when performing HTTP/1.1 Upgrade to custom protocols.
+
+* Headers can now be provided as a map. Header names may now
+ be provided as binary, string or atom.
+
+* Header names may now be provided as binary, string or atom.
+
+* 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
+ improve performance or lower the memory usage, for
+ example.
+
+* 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
+ at intervals determined by the `keepalive` option. It
+ defaults to 5 seconds.
+
+* A new `silence_pings` option can be set to `false` to
+ receive all ping and pong frames when using Websocket.
+ They are typically not needed and therefore silent by
+ default.
+
+* The `reply_to` option has been added to `gun:ws_upgrade/4`.
+ The option applies to both the response and subsequent
+ Websocket frames.
+
+* The `reply_to` option is also propagated to messages
+ following a CONNECT request when the protocol requested
+ is not HTTP.
+
+* A new option `retry_fun` can be used to implement
+ different backoff strategies when reconnecting.
+
+* A new option `supervise` can be used to start a Gun
+ 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).
+
+=== Features removed
+
+* Gun used to reject operations by processes that were not
+ the owner of the connection. This behavior has been removed.
+ In general the caller of a request or other operation will
+ receive the relevant messages unless the `reply_to` option
+ is used.
+
+* The `connect_destination()` option `protocol` has been
+ 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.
+
+=== Functions added
+
+* The function `gun:set_owner/2` has been added. It allows
+ changing the owner of a connection process. Only the current
+ owner can do this operation.
+
+* The function `gun:shutdown/1` has been added. It initiates
+ the graceful shutdown of the connection, followed by the
+ termination of the Gun process.
+
+* The function `gun:stream_info/2` has been added. It provides
+ information about a specific HTTP stream.
+
+=== Functions modified
+
+* The function `gun:info/1` now returns the owner of the connection.
+
+* 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: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.
+
+=== Messages modified
+
+* The `gun_down` message no longer has its final element
+ documented as `UnprocessedStreams`. It never worked and
+ was always an empty list.
+
+=== Bugs fixed
+
+* *POTENTIAL SECURITY VULNERABILITY*: Fix transfer-encoding
+ precedence over content-length in responses. This bug may
+ contribute to a response smuggling security vulnerability
+ when Gun is used inside a proxy.
+
+* Gun will no longer send duplicate connection-wide `gun_error`
+ messages to the same process.
+
+* Gun no longer crashes when trying to upgrade to Websocket
+ over a connection restricted to HTTP/1.0.
+
+* The default value for the preferred protocols when using
+ CONNECT over TLS has been corrected. It was mistakenly not
+ enabling HTTP/2.
+
+* Gun will no longer send an empty HTTP/2 DATA frame when
+ there is no request body. It was not necessary.
+
+* Gun will no longer error out when the owner process exits.
+ The error reason will now be a `shutdown` tuple instead.
+
+* The host header was set incorrectly during Websocket upgrades
+ when the host was configured with an IP address, resulting
+ in a crash. This has been corrected.
+
+* A completed stream could be found in the `gun_down` message when
+ the response contained a connection: close header. This is no
+ longer the case.
+
+* Hostnames can now be provided as atom as stated by the
+ documentation.
+
+* 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.
+
+* Gun now always retries connecting immediately when the
+ connection goes down.
+
+* The default port number for the HTTP and HTTPS schemes is
+ no longer sent in the host header.
+
+* An invalid stream reference was sent on failed Websocket
+ upgrade responses. This has been corrected.