Rename the 3-arity gun_socks_up to gun_tunnel_up

1 files changed, 68 insertions, 0 deletions

diff --git a/doc/src/manual/gun_tunnel_up.asciidoc b/doc/src/manual/gun_tunnel_up.asciidoc
new file mode 100644
index 0000000..5fc753e
--- /dev/null
+++ b/doc/src/manual/gun_tunnel_up.asciidoc
@@ -0,0 +1,68 @@
+= gun_tunnel_up(3)
+
+== Name
+
+gun_tunnel_up - The tunnel is up
+
+// @todo Update with StreamRef
+
+== Description
+
+[source,erlang]
+----
+{gun_tunnel_up, ConnPid, Protocol}
+
+ConnPid  :: pid()
+Protocol :: http | http2 | socks
+----
+
+The Socks connection is up.
+
+This message informs the owner/calling 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_tunnel_up(3)[gun_tunnel_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_tunnel_up message in a gen_server
+[source,erlang]
+----
+handle_info({gun_tunnel_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)]