diff options
author | Loïc Hoguin <[email protected]> | 2013-08-27 14:50:36 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2013-08-27 14:50:36 +0200 |
commit | d9a37f7398deb10fb4493b20644f721e0e9fa953 (patch) | |
tree | 43e1586de17a7ca59c2dab4fb932161f555f494c | |
parent | ed2c689592d6a7f4b4a8f0ed05648effeff832ac (diff) | |
download | gun-d9a37f7398deb10fb4493b20644f721e0e9fa953.tar.gz gun-d9a37f7398deb10fb4493b20644f721e0e9fa953.tar.bz2 gun-d9a37f7398deb10fb4493b20644f721e0e9fa953.zip |
Add a manual
-rw-r--r-- | manual/gun.md | 258 | ||||
-rw-r--r-- | manual/gun_app.md | 22 | ||||
-rw-r--r-- | manual/toc.md | 7 |
3 files changed, 287 insertions, 0 deletions
diff --git a/manual/gun.md b/manual/gun.md new file mode 100644 index 0000000..ea624ea --- /dev/null +++ b/manual/gun.md @@ -0,0 +1,258 @@ +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. + +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 = [{iodata(), iodata()}] +> * StreamRef = reference() +> +> Delete a resource. + +### get(ServerPid, Path) -> delete(ServerPid, Path, []) +### get(ServerPid, Path, Headers) -> StreamRef + +> Types: +> * ServerPid = pid() +> * Path = iodata() +> * Headers = [{iodata(), iodata()}] +> * StreamRef = reference() +> +> Fetch a resource. + +### head(ServerPid, Path) -> delete(ServerPid, Path, []) +### head(ServerPid, Path, Headers) -> StreamRef + +> Types: +> * ServerPid = pid() +> * Path = iodata() +> * Headers = [{iodata(), 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 = [{iodata(), 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 = [{iodata(), 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 = [{iodata(), 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 = [{iodata(), 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 = [{iodata(), 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 = [{iodata(), iodata()}] +> +> Upgrade the connection to Websocket. + +### ws_send(ServerPid, Frames) -> ok + +> Types: +> * ServerPid = pid() +> * Frames = ws_frame() | [ws_frame()] +> +> Send a Websocket frame. diff --git a/manual/gun_app.md b/manual/gun_app.md new file mode 100644 index 0000000..448145b --- /dev/null +++ b/manual/gun_app.md @@ -0,0 +1,22 @@ +The Gun Application +=================== + +Asynchronous SPDY, HTTP and Websocket client. + +Dependencies +------------ + +The `gun` application uses the Erlang applications `ranch` +for abstracting TCP and SSL over a common interface, and +the applications `asn1`, `public_key` and `ssl` for using +the SSL transport. These dependencies must be loaded for +the `gun` application to work. In an embedded environment +this means that they need to be started with the +`application:start/{1,2}` function before the `gun` +application is started. + +Environment +----------- + +The `gun` application does not define any application +environment configuration parameters. diff --git a/manual/toc.md b/manual/toc.md new file mode 100644 index 0000000..7765afc --- /dev/null +++ b/manual/toc.md @@ -0,0 +1,7 @@ +Gun Function Reference +====================== + +The function reference documents the public interface of Gun. + + * [The Gun Application](gun_app.md) + * [gun](gun.md) |