Document Socks support

Also correct various Socks related types. This commit also
adds a new gun:protocols/0 type as a simpler way of describing
preferred protocols. The protocol/opts tuple is also documented.

This commit also fixes an issue with the default value for the
preferred protocols when using CONNECT over TLS. It was
mistakenly not enabling http2 by default.

9 files changed, 186 insertions, 27 deletions

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index b9fbbc2..7b54666 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -63,6 +63,7 @@ by sending any of the following messages:
 Connection:
 
 * link:man:gun_up(3)[gun_up(3)] - The connection is up
+* link:man:gun_socks_up(3)[gun_socks_up(3)] - The Socks connection is up
 * link:man:gun_down(3)[gun_down(3)] - The connection is down
 * link:man:gun_upgrade(3)[gun_upgrade(3)] - Successful protocol upgrade
 * link:man:gun_error(3)[gun_error(3)] - Stream or connection-wide error
@@ -96,7 +97,7 @@ connect_destination() :: #{
 
     username  => iodata(),
     password  => iodata(),
-    protocols => [http | http2],
+    protocols => protocols(),
     transport => tcp | tls,
 
     tls_opts              => [ssl:tls_client_option()],
@@ -121,15 +122,17 @@ username, password::
 Proxy authorization credentials. They are only sent when
 both options are provided.
 
-protocol (http)::
+protocols - see below::
 
-Protocol that will be used for tunneled requests.
+Ordered list of preferred protocols. Please refer to the
+`protocols()` type documentation for details.
++
+Defaults to `[http]` when the transport is `tcp`,
+and `[http2, http]` when the transport is `tls`.
 
 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.
+Transport that will be used for tunneled requests.
 
 tls_opts ([])::
 
@@ -233,7 +236,7 @@ opts() :: #{
     domain_lookup_timeout => timeout(),
     http_opts             => http_opts(),
     http2_opts            => http2_opts(),
-    protocols             => [http | http2],
+    protocols             => protocols(),
     retry                 => non_neg_integer(),
     retry_fun             => fun(),
     retry_timeout         => pos_integer(),
@@ -269,13 +272,11 @@ Options specific to the HTTP/2 protocol.
 
 protocols - see below::
 
-Ordered list of preferred protocols. When the transport is `tcp`,
-this list must contain exactly one protocol. When the transport
-is `tls`, this list must contain at least one protocol and will be
-used to negotiate a protocol via ALPN. When the server does not
-support ALPN then `http` will always be used. Defaults to
-`[http]` when the transport is `tcp`, and `[http2, http]` when the
-transport is `tls`.
+Ordered list of preferred protocols. Please refer to the
+`protocols()` type documentation for details.
++
+Defaults to `[http]` when the transport is `tcp`,
+and `[http2, http]` when the transport is `tls`.
 
 retry (5)::
 
@@ -340,6 +341,25 @@ ws_opts (#{})::
 
 Options specific to the Websocket protocol.
 
+=== protocols()
+
+[source,erlang]
+----
+protocols() :: http | {http, http_opts()}
+             | http2 | {http2, http2_opts()}
+             | socks | {socks, socks_opts()}
+----
+
+Ordered list of preferred protocols. When the transport is `tcp`,
+this list must contain exactly one protocol. When the transport
+is `tls`, this list must contain at least one protocol and will be
+used to negotiate a protocol via ALPN. When the server does not
+support ALPN then `http` will be used, except when the list of
+preferred protocols is set to only accept `socks`.
+
+Defaults to `[http]` when the transport is `tcp`,
+and `[http2, http]` when the transport is `tls`.
+
 === req_headers()
 
 [source,erlang]
@@ -373,6 +393,64 @@ reply_to (`self()`)::
 
 The pid of the process that will receive the response messages.
 
+=== socks_opts()
+
+[source,erlang]
+----
+socks_opts() :: #{
+    host := inet:hostname() | inet:ip_address(),
+    port := inet:port_number(),
+
+    auth      => [{username_password, binary(), binary()} | none],
+    protocols => protocols(),
+    transport => tcp | tls,
+    version   => 5,
+
+    tls_opts              => [ssl:tls_client_option()],
+    tls_handshake_timeout => timeout()
+}
+----
+
+Configuration for the Socks protocol.
+
+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 Socks connection, Gun will
+begin using these as the host and port of the origin server
+for subsequent requests.
+
+auth ([none])::
+
+Authentication methods Gun advertises to the Socks proxy.
+
+protocols - see below::
+
+Ordered list of preferred protocols. Please refer to the
+`protocols()` type documentation for details.
++
+Defaults to `[http]` when the transport is `tcp`,
+and `[http2, http]` when the transport is `tls`.
+
+transport (tcp)::
+
+Transport that will be used for tunneled requests.
+
+tls_opts ([])::
+
+Options to use for tunneled TLS connections.
+
+tls_handshake_timeout (infinity)::
+
+Handshake timeout for tunneled TLS connections.
+
+version (5)::
+
+Version of the Socks protocol to use.
+
 === ws_opts()
 
 [source,erlang]
@@ -417,6 +495,11 @@ undocumented and must be set to `gun_ws_h`.
 
 == Changelog
 
+* *2.0*: The types `protocols()` and `socks_opts()` have been
+         added. Support for the Socks protocol has been added
+         in every places where protocol selection is available.
+         In addition it is now possible to specify separate
+         HTTP options for the CONNECT proxy and the origin server.
 * *2.0*: The `connect_timeout` option has been split into
          three options: `domain_lookup_timeout`, `connect_timeout`
          and when applicable `tls_handshake_timeout`.
diff --git a/doc/src/manual/gun.await_up.asciidoc b/doc/src/manual/gun.await_up.asciidoc
index dfd4da9..d9934b5 100644
--- a/doc/src/manual/gun.await_up.asciidoc
+++ b/doc/src/manual/gun.await_up.asciidoc
@@ -23,7 +23,7 @@ await_up(ConnPid, Timeout, MonitorRef)
 ConnPid    :: pid()
 MonitorRef :: reference()
 Timeout    :: timeout()
-Protocol   :: http | http2
+Protocol   :: http | http2 | socks
 Reason     :: {down, any()} | timeout
 ----
 
@@ -71,4 +71,5 @@ may also be returned when a timeout or an error occur.
 link:man:gun(3)[gun(3)],
 link:man:gun:open(3)[gun:open(3)],
 link:man:gun:open_unix(3)[gun:open_unix(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_up(3)[gun_up(3)]
diff --git a/doc/src/manual/gun.info.asciidoc b/doc/src/manual/gun.info.asciidoc
index afb2333..cf861c9 100644
--- a/doc/src/manual/gun.info.asciidoc
+++ b/doc/src/manual/gun.info.asciidoc
@@ -14,7 +14,7 @@ ConnPid :: pid()
 Info :: #{
     socket         => inet:socket() | ssl:sslsocket(),
     transport      => tcp | tls,
-    protocol       => http | http2 | ws,
+    protocol       => http | http2 | socks | ws,
     sock_ip        => inet:ip_address(),
     sock_port      => inet:port_number(),
     origin_host    => inet:hostname() | inet:ip_address(),
@@ -22,11 +22,11 @@ Info :: #{
     intermediaries => [Intermediary]
 }
 Intermediary :: #{
-    type      => connect,
+    type      => connect | socks5,
     host      => inet:hostname() | inet:ip_address(),
     port      => inet:port_number(),
     transport => tcp | tls,
-    protocol  => http | http2
+    protocol  => http | http2 | socks
 }
 ----
 
diff --git a/doc/src/manual/gun.open.asciidoc b/doc/src/manual/gun.open.asciidoc
index 79a9d54..63bb3f8 100644
--- a/doc/src/manual/gun.open.asciidoc
+++ b/doc/src/manual/gun.open.asciidoc
@@ -14,7 +14,9 @@ open(Host, Port, Opts) -> {ok, pid()} | {error, Reason}
 Host    :: inet:hostname() | inet:ip_address()
 Port    :: inet:port_number()
 Opts    :: gun:opts()
-Reason  :: {options, OptName} | {options, {http | http2, OptName}} | any()
+Reason  :: {options, OptName}
+         | {options, {http | http2 | socks | ws, OptName}}
+         | any()
 OptName :: atom()
 ----
 
@@ -71,4 +73,5 @@ message will be sent for that.
 link:man:gun(3)[gun(3)],
 link:man:gun:open_unix(3)[gun:open_unix(3)],
 link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_up(3)[gun_up(3)]
diff --git a/doc/src/manual/gun.open_unix.asciidoc b/doc/src/manual/gun.open_unix.asciidoc
index 4ea8d2b..441bfa8 100644
--- a/doc/src/manual/gun.open_unix.asciidoc
+++ b/doc/src/manual/gun.open_unix.asciidoc
@@ -12,7 +12,9 @@ open_unix(SocketPath, Opts) -> {ok, pid()} | {error, Reason}
 
 SocketPath :: string()
 Opts       :: gun:opts()
-Reason     :: {options, OptName} | {options, {http | http2, OptName}} | any()
+Reason     :: {options, OptName}
+            | {options, {http | http2 | socks | ws, OptName}}
+            | any()
 OptName    :: atom()
 ----
 
@@ -59,4 +61,5 @@ message will be sent for that.
 link:man:gun(3)[gun(3)],
 link:man:gun:open(3)[gun:open(3)],
 link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_up(3)[gun_up(3)]
diff --git a/doc/src/manual/gun_down.asciidoc b/doc/src/manual/gun_down.asciidoc
index 67c7796..6c72898 100644
--- a/doc/src/manual/gun_down.asciidoc
+++ b/doc/src/manual/gun_down.asciidoc
@@ -11,7 +11,7 @@ gun_down - The connection is down
 {gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}
 
 ConnPid            :: pid()
-Protocol           :: http | http2 | ws
+Protocol           :: http | http2 | socks | ws
 Reason             :: any()
 KilledStreams      :: [reference()]
 UnprocessedStreams :: [reference()]
@@ -83,4 +83,5 @@ link:man:gun(3)[gun(3)],
 link:man:gun:open(3)[gun:open(3)],
 link:man:gun:open_unix(3)[gun:open_unix(3)],
 link:man:gun_up(3)[gun_up(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_error(3)[gun_error(3)]
diff --git a/doc/src/manual/gun_error.asciidoc b/doc/src/manual/gun_error.asciidoc
index a43d32b..ac278fd 100644
--- a/doc/src/manual/gun_error.asciidoc
+++ b/doc/src/manual/gun_error.asciidoc
@@ -64,4 +64,5 @@ handle_info({gun_error, ConnPid, _StreamRef, _Reason},
 
 link:man:gun(3)[gun(3)],
 link:man:gun_up(3)[gun_up(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_down(3)[gun_down(3)]
diff --git a/doc/src/manual/gun_socks_up.asciidoc b/doc/src/manual/gun_socks_up.asciidoc
new file mode 100644
index 0000000..e74f1a9
--- /dev/null
+++ b/doc/src/manual/gun_socks_up.asciidoc
@@ -0,0 +1,66 @@
+= gun_socks_up(3)
+
+== Name
+
+gun_socks_up - The Socks connection is up
+
+== Description
+
+[source,erlang]
+----
+{gun_socks_up, ConnPid, Protocol}
+
+ConnPid  :: pid()
+Protocol :: http | http2 | socks
+----
+
+The Socks connection is up.
+
+This message informs the owner process that the connection
+completed through the configured Socks proxy.
+
+If Gun is configured to connect to another Socks server, then the
+connection is not usable yet. One or more
+link:man:gun_socks_up(3)[gun_socks_up(3)] messages will follow.
+
+Otherwise, Gun will start processing the messages it received while
+waiting for the connection to be up. If this is a reconnection,
+then this may not be desirable for all requests. Those requests
+should be cancelled when the connection goes down, and any
+subsequent messages ignored.
+
+== Elements
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Protocol::
+
+The protocol selected for this connection. It can be used
+to determine the capabilities of the server.
+
+== Changelog
+
+* *2.0*: Message introduced.
+
+== Examples
+
+.Receive a gun_socks_up message in a gen_server
+[source,erlang]
+----
+handle_info({gun_socks_up, ConnPid, _Protocol},
+            State=#state{conn_pid=ConnPid}) ->
+    %% Do something.
+    {noreply, State}.
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:open(3)[gun:open(3)],
+link:man:gun:open_unix(3)[gun:open_unix(3)],
+link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_up(3)[gun_up(3)],
+link:man:gun_down(3)[gun_down(3)],
+link:man:gun_error(3)[gun_error(3)]
diff --git a/doc/src/manual/gun_up.asciidoc b/doc/src/manual/gun_up.asciidoc
index a103594..db09fca 100644
--- a/doc/src/manual/gun_up.asciidoc
+++ b/doc/src/manual/gun_up.asciidoc
@@ -11,7 +11,7 @@ gun_up - The connection is up
 {gun_up, ConnPid, Protocol}
 
 ConnPid  :: pid()
-Protocol :: http | http2
+Protocol :: http | http2 | socks
 ----
 
 The connection is up.
@@ -19,16 +19,16 @@ The connection is up.
 This message informs the owner process that the connection or
 reconnection completed.
 
-Gun will now start processing the messages it received while
+If Gun is configured to connect to a Socks server, then the
+connection is not usable yet. One or more
+link:man:gun_socks_up(3)[gun_socks_up(3)] messages will follow.
+
+Otherwise, Gun will start processing the messages it received while
 waiting for the connection to be up. If this is a reconnection,
 then this may not be desirable for all requests. Those requests
 should be cancelled when the connection goes down, and any
 subsequent messages ignored.
 
-// @todo Gun doesn't process messages immediately if it
-// is using the socks protocol, there are gun_socks_connected
-// messages coming up before reaching HTTP.
-
 == Elements
 
 ConnPid::
@@ -61,5 +61,6 @@ link:man:gun(3)[gun(3)],
 link:man:gun:open(3)[gun:open(3)],
 link:man:gun:open_unix(3)[gun:open_unix(3)],
 link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_socks_up(3)[gun_socks_up(3)],
 link:man:gun_down(3)[gun_down(3)],
 link:man:gun_error(3)[gun_error(3)]