From e714b99fecb1923cfc4182d2c439fb0bd3943ac6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 17 Sep 2018 15:47:31 +0200
Subject: Document gun:connect/2,3,4

---
 doc/src/manual/gun.asciidoc | 61 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

(limited to 'doc/src/manual/gun.asciidoc')

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 7e1f343..29ca3ea 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -32,6 +32,10 @@ Requests:
 * link:man:gun:request(3)[gun:request(3)] - Perform the given request
 * link:man:gun:data(3)[gun:data(3)] - Stream the body of a request
 
+Proxies:
+
+* link:man:gun:connect(3)[gun:connect(3)] - Establish a tunnel to the origin server
+
 Messages:
 
 * link:man:gun:await(3)[gun:await(3)] - Wait for a response
@@ -79,6 +83,59 @@ process.
 
 == Types
 
+=== connect_destination()
+
+[source,erlang]
+----
+connect_destination() :: #{
+    host      := inet:hostname() | inet:ip_address(),
+    port      := inet:port_number(),
+
+    username  => iodata(),
+    password  => iodata(),
+    protocol  => http | http2,
+    transport => tcp | tls,
+
+    tls_opts              => [ssl:connect_option()],
+    tls_handshake_timeout => timeout()
+}
+----
+
+Destination of a CONNECT request.
+
+The default value, if any, is given next to the option name:
+
+host, port::
+
+Destination hostname and port number. Mandatory.
++
+Upon successful completion of the CONNECT request, Gun will
+begin using these as the host and port of the origin server
+for subsequent requests.
+
+username, password::
+
+Proxy authorization credentials. They are only sent when
+both options are provided.
+
+protocol (http)::
+
+Protocol that will be used for tunneled requests.
+
+transport (tcp)::
+
+Transport that will be used for tunneled requests. Note that
+due to Erlang/OTP limitations it is not possible to tunnel
+a TLS connection inside a TLS tunnel.
+
+tls_opts ([])::
+
+Options to use for tunneled TLS connections.
+
+tls_handshake_timeout (infinity)::
+
+Handshake timeout for tunneled TLS connections.
+
 === http_opts()
 
 [source,erlang]
@@ -246,6 +303,10 @@ server that ultimately decides. Defaults to false.
 
 // @todo Document default_protocol, protocols and user_opts.
 
+== Changelog
+
+* *1.2*: Introduce the type `connect_destination()`.
+
 == See also
 
 link:man:gun(7)[gun(7)]
-- 
cgit v1.2.3