1 files changed, 115 insertions, 0 deletions
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)]