From 516933f9dd2722329b3886c495d5242308958fe1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 22 Jul 2019 16:17:10 +0200
Subject: Split domain lookup/connect/TLS handshake and add events

This changes the way we connect to servers entirely. We now have
three states when connecting (domain_lookup, connect and
tls_handshake when applicable) and as a result three corresponding
timeout options. Each state has a start/end event associated and
the event data was tweaked to best match each event. Since the
TLS handshake is separate, the transport_opts option was also
split into two: tcp_opts and tls_opts.
---
 doc/src/manual/gun.asciidoc | 52 +++++++++++++++++++++++++++++++--------------
 1 file changed, 36 insertions(+), 16 deletions(-)

(limited to 'doc')

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 3f8d43f..cd34537 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -202,17 +202,20 @@ Time between pings in milliseconds.
 [source,erlang]
 ----
 opts() :: #{
-    connect_timeout => timeout(),
-    http_opts       => http_opts(),
-    http2_opts      => http2_opts(),
-    protocols       => [http | http2],
-    retry           => non_neg_integer(),
-    retry_timeout   => pos_integer(),
-    supervise       => boolean(),
-    trace           => boolean(),
-    transport       => tcp | tls,
-    transport_opts  => [gen_tcp:connect_option()] | [ssl:connect_option()],
-    ws_opts         => ws_opts()
+    connect_timeout       => timeout(),
+    domain_lookup_timeout => timeout(),
+    http_opts             => http_opts(),
+    http2_opts            => http2_opts(),
+    protocols             => [http | http2],
+    retry                 => non_neg_integer(),
+    retry_timeout         => pos_integer(),
+    supervise             => boolean(),
+    tcp_opts              => [gen_tcp:connect_option()],
+    tls_handshake_timeout => timeout(),
+    tls_opts              => [ssl:connect_option()],
+    trace                 => boolean(),
+    transport             => tcp | tls,
+    ws_opts               => ws_opts()
 }
 ----
 
@@ -224,6 +227,10 @@ connect_timeout (infinity)::
 
 Connection timeout.
 
+domain_lookup_timeout (infinity)::
+
+Domain lookup timeout.
+
 http_opts (#{})::
 
 Options specific to the HTTP protocol.
@@ -255,6 +262,19 @@ supervise (true)::
 Whether the Gun process should be started under the `gun_sup`
 supervisor. Set to `false` to use your own supervisor.
 
+tcp_opts ([])::
+
+TCP options used when establishing the connection.
+
+tls_handshake_timeout (infinity)::
+
+TLS handshake timeout.
+
+tls_opts ([])::
+
+TLS options used for the TLS handshake after the connection
+has been established, when the transport is set to `tls`.
+
 trace (false)::
 
 Whether to enable `dbg` tracing of the connection process. Should
@@ -265,11 +285,6 @@ transport - see below::
 Whether to use TLS or plain TCP. The default varies depending on the
 port used. Port 443 defaults to `tls`. All other ports default to `tcp`.
 
-transport_opts ([])::
-
-Transport options. They are TCP options or TLS options depending on
-the selected transport.
-
 ws_opts (#{})::
 
 Options specific to the Websocket protocol.
@@ -332,6 +347,11 @@ undocumented and must be set to `gun_ws_h`.
 
 == Changelog
 
+* *2.0*: The `connect_timeout` option has been split into
+         three options: `domain_lookup_timeout`, `connect_timeout`
+         and when applicable `tls_handshake_timeout`.
+* *2.0*: The `transport_opts` option has been split into
+         two options: `tcp_opts` and `tls_opts`.
 * *2.0*: Introduce the type `req_headers()` and extend the
          types accepted for header names for greater
          interoperability. Header names are automatically
-- 
cgit v1.2.3