Document gun:connect/2,3,4

2 files changed, 176 insertions, 0 deletions

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)]
diff --git a/doc/src/manual/gun.connect.asciidoc b/doc/src/manual/gun.connect.asciidoc
new file mode 100644
index 0000000..a1acaa5
--- /dev/null
+++ b/doc/src/manual/gun.connect.asciidoc
@@ -0,0 +1,115 @@
+= gun:connect(3)
+
+== Name
+
+gun:connect - Establish a tunnel to the origin server
+
+== Description
+
+[source,erlang]
+----
+connect(ConnPid, Destination)
+    -> connect(ConnPid, Destination, [], #{}).
+
+connect(ConnPid, Destination, Headers)
+    -> connect(ConnPid, Destination, Headers, #{}).
+
+connect(ConnPid, Destination, Headers, ReqOpts)
+    -> StreamRef
+
+ConnPid     :: pid()
+Destination :: gun:connect_destination()
+Headers     :: [{binary(), iodata()}]
+ReqOpts     :: gun:req_opts()
+StreamRef   :: reference()
+----
+
+Establish a tunnel to the origin server.
+
+This feature is currently only available for HTTP/1.1 connections.
+Upon successful completion of the CONNECT request a tunnel is
+established and subsequent requests will go through the tunnel.
+
+Gun will not automatically re-issue the CONNECT request upon
+reconnection to the proxy server. The `gun_up` message can
+be used to know when the tunnel needs to be established again.
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Destination::
+
+Destination of the CONNECT request.
+
+Headers::
+
+Additional request headers.
+
+ReqOpts::
+
+Request options.
+
+== Return value
+
+A reference that identifies the newly created stream is
+returned. It is this reference that must be passed in
+subsequent calls and will be received in messages related
+to this new stream.
+
+== Changelog
+
+* *1.2*: Function introduced.
+
+== Examples
+
+.Establish a tunnel
+[source,erlang]
+----
+{ok, ConnPid} = gun:open("proxy.example.org", 1080),
+{ok, http} = gun:await_up(ConnPid),
+StreamRef = gun:connect(ConnPid, #{
+    host => "origin-server.example.org",
+    port => 80
+}),
+{response, fin, 200, _} = gun:await(ConnPid, StreamRef),
+%% Subsequent requests will be sent to origin-server.example.org.
+----
+
+.Establish a tunnel for a secure HTTP/2 connection
+[source,erlang]
+----
+{ok, ConnPid} = gun:open("proxy.example.org", 1080),
+{ok, http} = gun:await_up(ConnPid),
+StreamRef = gun:connect(ConnPid, #{
+    host => "origin-server.example.org",
+    port => 80,
+    protocol => http2,
+    transport => tls
+}),
+{response, fin, 200, _} = gun:await(ConnPid, StreamRef),
+%% Subsequent requests will be sent to origin-server.example.org.
+----
+
+.Establish a tunnel using proxy authorization
+[source,erlang]
+----
+{ok, ConnPid} = gun:open("proxy.example.org", 1080),
+{ok, http} = gun:await_up(ConnPid),
+StreamRef = gun:connect(ConnPid, #{
+    host => "origin-server.example.org",
+    port => 80,
+    username => "essen",
+    password => "myrealpasswordis"
+}),
+{response, fin, 200, _} = gun:await(ConnPid, StreamRef),
+%% Subsequent requests will be sent to origin-server.example.org.
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_up(3)[gun_up(3)]