gun
===

The `gun` module provides an asynchronous interface for
connecting and communicating with Web servers over SPDY,
HTTP or Websocket.

Types
-----

### opts() = [{keepalive, pos_integer()}
	| {retry, non_neg_integer()}
	| {retry_timeout, pos_integer()}
	| {type, ssl | tcp | tcp_spdy}].

> Configuration for the connection.

Option descriptions
-------------------

The default value is given next to the option name.

 -  keepalive (5000)
   -  Time between pings in milliseconds.
 -  retry (5)
   -  Number of times Gun will try to reconnect on failure before giving up.
 -  retry_timeout (5000)
   -  Time between retries in milliseconds.
 -  type (ssl)
   -  Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP.

Messages
--------

Calling functions from this module may result in the following
messages being sent.

### {gun_push, ServerPid, StreamRef, AssocToStreamRef,
	Method, Host, Path, Headers}

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = AssocToStreamRef = reference()
>  *  Method = binary()
>  *  Host = binary()
>  *  Path = binary()
>  *  Headers = [{binary(), binary()}]
>
> A resource pushed alongside an HTTP response.

### {gun_response, ServerPid, StreamRef, IsFin, Status, Headers}

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = reference()
>  *  IsFin = fin | nofin
>  *  Status = binary()
>  *  Headers = [{binary(), binary()}]
>
> A response to an HTTP request.

### {gun_data, ServerPid, StreamRef, IsFin, Data}

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = reference()
>  *  IsFin = fin | nofin
>  *  Data = binary()
>
> Data associated with a response or pushed resource.

### {gun_error, ServerPid, StreamRef, Reason}

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = reference()
>  *  Reason = any()
>
> An error specific to a particular stream.

### {gun_error, ServerPid, Reason}

> Types:
>  *  ServerPid = pid()
>  *  Reason = any()
>
> A general error.

### {gun_ws_upgrade, ServerPid, ok}

> Types:
>  *  ServerPid = pid()
>
> Websocket upgrade success.

### {gun_ws_upgrade, ServerPid, error, IsFin, Status, Headers}

> Types:
>  *  ServerPid = pid()
>  *  IsFin = fin | nofin
>  *  Status = binary()
>  *  Headers = [{binary(), binary()}]
>
> Websocket upgrade failure, with the HTTP response received.

### {gun_ws, ServerPid, Frame}

> Types:
>  *  ServerPid = pid()
>  *  Frame = ws_frame()
>
> A Websocket frame just received.

Exports
-------

### open(Host, Port) -> open(Host, Port, [])
### open(Host, Port, Opts) -> {ok, ServerPid} | {error, any()}

> Types:
>  *  Host = inet:hostname()
>  *  Port = inet:port_number()
>  *  Opts = opts()
>  *  ServerPid = pid()
>
> Open a connection to the given host.

### close(ServerPid) -> ok

> Types:
>  *  ServerPid = pid()
>
> Brutally close the connection.

### shutdown(ServerPid) -> ok

> Types:
>  *  ServerPid = pid()
>
> Gracefully close the connection.
>
> A monitor can be used to be notified when the connection is
> effectively closed.

### delete(ServerPid, Path) -> delete(ServerPid, Path, [])
### delete(ServerPid, Path, Headers) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>
> Delete a resource.

### get(ServerPid, Path) -> delete(ServerPid, Path, [])
### get(ServerPid, Path, Headers) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>
> Fetch a resource.

### head(ServerPid, Path) -> delete(ServerPid, Path, [])
### head(ServerPid, Path, Headers) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>
> Fetch a resource's headers.
>
> The server will not send the resource content, only headers.

### options(ServerPid, Path) -> delete(ServerPid, Path, [])
### options(ServerPid, Path, Headers) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>
> Obtain information about the capabilities of the server or a resource.
>
> The special path "*" can be used to obtain information about
> the server as a whole. Any other path will return information
> about the resource only.

### patch(ServerPid, Path, Headers) -> StreamRef
### patch(ServerPid, Path, Headers, Body) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>  *  Body = iodata()
>
> Partially update a resource.
>
> Always set the content-type header so that Gun and the server
> can be made aware that a body is going to be sent. Also try
> to set the content-length header when possible.
>
> If a body is given, even an empty one, it is expected to be
> the full resource.
>
> If not, Gun will assume there is no body if content-type
> isn't set, and otherwise will expect you to stream the body.

### post(ServerPid, Path, Headers) -> StreamRef
### post(ServerPid, Path, Headers, Body) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>  *  Body = iodata()
>
> Create or update a resource.
>
> The resource may be created at a different URL than the one
> given.
>
> Always set the content-type header so that Gun and the server
> can be made aware that a body is going to be sent. Also try
> to set the content-length header when possible.
>
> If a body is given, even an empty one, it is expected to be
> the full resource.
>
> If not, Gun will assume there is no body if content-type
> isn't set, and otherwise will expect you to stream the body.

### put(ServerPid, Path, Headers) -> StreamRef
### put(ServerPid, Path, Headers, Body) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>  *  Body = iodata()
>
> Create or update a resource.
>
> The resource will be created at this exact URL.
>
> Always set the content-type header so that Gun and the server
> can be made aware that a body is going to be sent. Also try
> to set the content-length header when possible.
>
> If a body is given, even an empty one, it is expected to be
> the full resource.
>
> If not, Gun will assume there is no body if content-type
> isn't set, and otherwise will expect you to stream the body.

### request(ServerPid, Method, Path, Headers) -> StreamRef
### request(ServerPid, Method, Path, Headers, Body) -> StreamRef

> Types:
>  *  ServerPid = pid()
>  *  Method = iodata()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>  *  StreamRef = reference()
>  *  Body = iodata()
>
> Perform the given request on a resource.
>
> This is a general purpose function that should only be used
> when no other function can be used.
>
> Method names are case sensitive.
>
> Always set the content-type header so that Gun and the server
> can be made aware that a body is going to be sent. Also try
> to set the content-length header when possible.
>
> If a body is given, even an empty one, it is expected to be
> the full resource.
>
> If not, Gun will assume there is no body if content-type
> isn't set, and otherwise will expect you to stream the body.

### data(ServerPid, StreamRef, IsFin, Data) -> ok

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = reference()
>  *  IsFin = fin | nofin
>  *  Data = iodata()
>
> Stream data.
>
> The `StreamRef` argument is the one returned by any of the
> request functions beforehand and uniquely identifies a request.
>
> Use `nofin` for all chunks except the last which should be `fin`.
> The last chunk may be empty.

### cancel(ServerPid, StreamRef) -> ok

> Types:
>  *  ServerPid = pid()
>  *  StreamRef = reference()
>
> Cancel the given stream.
>
> The `StreamRef` argument is the one returned by any of the
> request functions beforehand and uniquely identifies a request.
>
> This function will do a best effort at canceling the stream,
> depending on the capabilities of the protocol.

### ws_upgrade(ServerPid, Path) -> ws_upgrade(ServerPid, Path, [])
### ws_upgrade(ServerPid, Path, Headers) -> ok

> Types:
>  *  ServerPid = pid()
>  *  Path = iodata()
>  *  Headers = [{binary(), iodata()}]
>
> Upgrade the connection to Websocket.

### ws_send(ServerPid, Frames) -> ok

> Types:
>  *  ServerPid = pid()
>  *  Frames = ws_frame() | [ws_frame()]
>
> Send a Websocket frame.