diff options
Diffstat (limited to 'docs/en/gun/1.0/guide/connect.asciidoc')
-rw-r--r-- | docs/en/gun/1.0/guide/connect.asciidoc | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/docs/en/gun/1.0/guide/connect.asciidoc b/docs/en/gun/1.0/guide/connect.asciidoc new file mode 100644 index 00000000..c2e887c1 --- /dev/null +++ b/docs/en/gun/1.0/guide/connect.asciidoc @@ -0,0 +1,154 @@ +== Connection + +This chapter describes how to open, monitor and close +a connection using the Gun client. + +=== Gun connections + +Gun is designed with the SPDY and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +SPDY or in the form of messages for Websocket. + +A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the _owner_ of the connection, and is +managed by the supervision tree of the `gun` application. + +The owner process communicates with the Gun connection +by calling functions from the module `gun`. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed. + +When the remote endpoint closes the connection, Gun attempts +to reconnect automatically. + +=== Opening a new connection + +The `gun:open/{2,3}` function must be used to open a connection. + +.Opening a connection to example.org on port 443 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443). + +If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL. + +For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol. + +The transport and protocol used can be overriden using +options. The manual documents all available options. + +Options can be provided as a third argument, and take the +form of a map. + +.Opening an SSL connection to example.org on port 8443 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}). + +=== Waiting for the connection to be established + +When Gun successfully connects to the server, it sends a +`gun_up` message with the protocol that has been selected +for the connection. + +Gun provides the functions `gun:await_up/{1,2,3}` that wait +for the `gun_up` message. They can optionally take a monitor +reference and/or timeout value. If no monitor is provided, +one will be created for the duration of the function call. + +.Synchronous opening of a connection + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443), +{ok, Protocol} = gun:await_up(ConnPid). + +=== Handling connection loss + +When the connection is lost, Gun will send a `gun_down` +message indicating the current protocol, the reason the +connection was lost and two list of stream references. + +The first list indicates open streams that _may_ have been +processed by the server. The second list indicates open +streams that the server did not process. + +=== Monitoring the connection process + +@todo Gun should detect the owner process being killed + +Because software errors are unavoidable, it is important to +detect when the Gun process crashes. It is also important +to detect when it exits normally. Erlang provides two ways +to do that: links and monitors. + +Gun leaves you the choice as to which one will be used. +However, if you use the `gun:await/{2,3}` or `gun:await_body/{2,3}` +functions, a monitor may be used for you to avoid getting +stuck waiting for a message that will never come. + +If you choose to monitor yourself you can do it on a permanent +basis rather than on every message you will receive, saving +resources. Indeed, the `gun:await/{3,4}` and `gun:await_body/{3,4}` +functions both accept a monitor argument if you have one already. + +.Monitoring the connection process + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 443). +MRef = monitor(process, ConnPid). + +This monitor reference can be kept and used until the connection +process exits. + +.Handling `DOWN` messages + +[source,erlang] +receive + %% Receive Gun messages here... + {'DOWN', Mref, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason); +end. + +What to do when you receive a `DOWN` message is entirely up to you. + +=== Closing the connection abruptly + +The connection can be stopped abruptly at any time by calling +the `gun:close/1` function. + +.Immediate closing of the connection + +[source,erlang] +gun:close(ConnPid). + +The process is stopped immediately without having a chance to +perform the protocol's closing handshake, if any. + +=== Closing the connection gracefully + +The connection can also be stopped gracefully by calling the +`gun:shutdown/1` function. + +.Graceful shutdown of the connection + +[source,erlang] +gun:shutdown(ConnPid). + +Gun will refuse any new requests or messages after you call +this function. It will however continue to send you messages +for existing streams until they are all completed. + +For example if you performed a GET request just before calling +`gun:shutdown/1`, you will still receive the response before +Gun closes the connection. + +If you set a monitor beforehand, you will receive a message +when the connection has been closed. |