diff options
-rw-r--r-- | Makefile | 36 | ||||
-rw-r--r-- | doc/src/manual/gun.asciidoc | 578 | ||||
-rw-r--r-- | doc/src/manual/gun_app.asciidoc | 24 | ||||
-rw-r--r-- | manual/gun.md | 340 | ||||
-rw-r--r-- | manual/gun_app.md | 22 | ||||
-rw-r--r-- | manual/toc.md | 7 |
6 files changed, 632 insertions, 375 deletions
@@ -21,10 +21,34 @@ include erlang.mk # AsciiDoc. -asciidoc: - a2x -v -f pdf doc/src/guide/book.asciidoc && mv doc/src/guide/book.pdf doc/guide.pdf - a2x -v -f chunked doc/src/guide/book.asciidoc && mv doc/src/guide/book.chunked/* doc/ - rmdir doc/src/guide/book.chunked +.PHONY: asciidoc asciidoc-guide asciidoc-manual clean-asciidoc + +MAN_INSTALL_PATH ?= /usr/local/share/man +MAN_SECTIONS ?= 3 7 -clean:: - $(gen_verbose) rm doc/guide.pdf doc/*.html doc/*.css +asciidoc: clean-asciidoc asciidoc-guide asciidoc-manual + +asciidoc-guide: + a2x -v -f pdf doc/src/guide/book.asciidoc && mv doc/src/guide/book.pdf doc/guide.pdf + a2x -v -f chunked doc/src/guide/book.asciidoc && mv doc/src/guide/book.chunked/ doc/html/ + +asciidoc-manual: + for f in doc/src/manual/*.asciidoc ; do \ + a2x -v -f manpage $$f ; \ + done + for s in $(MAN_SECTIONS); do \ + mkdir -p doc/man$$s/ ; \ + mv doc/src/manual/*.$$s doc/man$$s/ ; \ + gzip doc/man$$s/*.$$s ; \ + done + +clean:: clean-asciidoc + +clean-asciidoc: + $(gen_verbose) rm -rf doc/html/ doc/guide.pdf doc/man3/ doc/man7/ + +install-docs: + for s in $(MAN_SECTIONS); do \ + mkdir -p $(MAN_INSTALL_PATH)/man$$s/ ; \ + install -g 0 -o 0 -m 0644 doc/man$$s/*.gz $(MAN_INSTALL_PATH)/man$$s/ ; \ + done diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc new file mode 100644 index 0000000..14641ee --- /dev/null +++ b/doc/src/manual/gun.asciidoc @@ -0,0 +1,578 @@ += gun(3) + +== Name + +gun - asynchronous HTTP client + +== Description + +The `gun` module provides an asynchronous interface for +connecting and communicating with Web servers over SPDY, +HTTP or Websocket. + +== Types + +=== opts() = [opt()] + +Configuration for the connection. + +@todo Should be a map. + +With opt(): + +keepalive => pos_integer():: + Time between pings in milliseconds. + Defaults to 5000. +retry => non_neg_integer():: + Number of times Gun will try to reconnect on failure before giving up. + Defaults to 5. +retry_timeout => pos_integer():: + Time between retries in milliseconds. + Defaults to 5000. +type => ssl | tcp | tcp_spdy:: + Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP. + The default varies depending on the port used. Port 443 defaults + to ssl. Port 6121 defaults to tcp_spdy (@todo). All other ports + default to tcp. (@todo) + +@todo We want to separate protocol and transport options. + +@todo We need to document Websocket options. + +== Messages + +Calling functions from this module may result in the following +messages being sent. + +=== {gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers} + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream initiated by the owner process. +NewStreamRef = reference():: Identifier of the stream being pushed. +URI = binary():: URI of the resource. +Headers = [{binary(), binary()}]:: Headers @todo + +A resource pushed alongside an HTTP response. + +This message can only be sent when the protocol is SPDY. + +@todo we probably want a function to know what protocol we connected +@todo with or perhaps a message on connect that tells us that + +@todo I fear we also need the scheme; resource is identified by URI +@todo Perhaps we really should send the URI entirely, because cache +@todo relies on URI to work and this feature is for caching... +@todo Not sure why Method is there, spec says it is only for GET + +=== {gun_response, ConnPid, StreamRef, IsFin, Status, Headers} + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream initiated by the owner process. +IsFin = fin | nofin:: Whether this message terminates the response. +Status = binary():: Status line for the response. +Headers = [{binary(), binary()}]:: Headers sent with the response. + +A response to an HTTP request. + +=== {gun_data, ConnPid, StreamRef, IsFin, Data} + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream this data belongs to. +IsFin = fin | nofin:: Whether this message terminates the response. +Data = binary():: Data from the stream. + +Data associated with a stream. + +The stream in question can be either one initiated by the owner +process or a stream initiated by the server through the push +mechanism. In any case a `gun_response` or a `gun_push` message +will be sent before any `gun_data` message. + +=== {gun_error, ConnPid, StreamRef, Reason} + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream this error relates to. +Reason = any():: Error reason. + +Stream-specific error. + +=== {gun_error, ConnPid, Reason} + +ConnPid = pid():: The pid of the Gun connection process. +Reason = any():: Error reason. + +General error. + +=== {gun_ws_upgrade, ConnPid, ok} + +ConnPid = pid():: The pid of the Gun connection process. + +Successful upgrade to the Websocket protocol. + +@todo Yeah we need the headers. + +=== {gun_ws_upgrade, ConnPid, error, IsFin, Status, Headers} + +ConnPid = pid():: The pid of the Gun connection process. +IsFin = fin | nofin:: Whether this message terminates the response. +Status = binary():: Status line for the response. +Headers = [{binary(), binary()}]:: Headers sent with the response. + +Failed upgrade to the Websocket protocol. + +=== {gun_ws, ConnPid, Frame} + +ConnPid = pid():: The pid of the Gun connection process. +Frame = @todo:: Frame. + +Websocket frame. + +== Exports + +=== open(Host, Port) -> open(Host, Port, []) + +Alias of `gun:open/3`. + +=== open(Host, Port, Opts) -> {ok, ConnPid} | {error, Reason} + +Host = inet:hostname():: Host to connect to. +Port = inet:port_number():: Port to connect to. +Opts = opts():: Options for this connection. +ConnPid = pid():: The pid of the Gun connection process. +Reason = any():: Error reason. @todo really any? + +Open a connection to the given host and port. + +=== close(ConnPid) -> ok + +ConnPid = pid():: The pid of the Gun connection process. + +Brutally close the connection. + +=== shutdown(ConnPid) -> ok + +ConnPid = pid():: The pid of the Gun connection process. + +Gracefully close the connection. + +A monitor can be used to be notified when the connection is +effectively closed. + +=== delete(ConnPid, Path) -> delete(ConnPid, Path, []) + +Alias of `gun:delete/3`. + +=== delete(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Delete a resource. + +=== get(ConnPid, Path) -> get(ConnPid, Path, []) + +Alias of `gun:get/3`. + +=== get(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Get a resource. + +=== head(ConnPid, Path) -> head(ConnPid, Path, []) + +Alias of `gun:head/3`. + +=== head(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Get headers of a resource. + +This function performs the same operation as `get/{2,3}` except +the server will not send the resource representation, only the +response's status line and headers. + +While servers should send the same headers they would if the +request was a GET, like `content-length`, it is not always +the case and differences may exist. + +=== options(ConnPid, Path) -> options(ConnPid, Path, []) + +Alias of `gun:options/3`. + +=== options(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Obtain information about the capabilities of the server or of 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(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Request that a set of changes be applied to the resource. + +This function expects either `content-length` or `content-type` +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible. + +The body sent in this request should be a patch document +with instructions on how to update the resource. + +You can use the `gun:data/4` function to send the body, if any. + +=== patch(ConnPid, Path, Headers, Body) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +Body = iodata():: Body of the request. +StreamRef = reference():: Identifier of the stream for this request. + +Request that a set of changes be applied to the resource. + +It is highly recommended to set the `content-type` header +to inform the server what media type the body contains. +Gun will automatically set the `content-length` header. + +The body sent in this request should be a patch document +with instructions on how to update the resource. + +The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it. + +=== post(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Process the enclosed representation according to the resource's own semantics. + +This function expects either `content-length` or `content-type` +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible. + +The body sent in this request will be processed +according to the resource's own semantics. A new +resource may be created as a result, and may be +located at a different URI. + +You can use the `gun:data/4` function to send the body, if any. + +=== post(ConnPid, Path, Headers, Body) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +Body = iodata():: Body of the request. +StreamRef = reference():: Identifier of the stream for this request. + +Process the enclosed representation according to the resource's own semantics. + +It is highly recommended to set the `content-type` header +to inform the server what media type the body contains. +Gun will automatically set the `content-length` header. + +The body sent in this request will be processed +according to the resource's own semantics. A new +resource may be created as a result, and may be +located at a different URI. + +The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it. + +=== put(ConnPid, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Create or replace a resource. + +The body of the request is the entire representation of the resource. + +This function expects either `content-length` or `content-type` +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible. + +You can use the `gun:data/4` function to send the body, if any. + +=== put(ConnPid, Path, Headers, Body) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +Body = iodata():: Body of the request. +StreamRef = reference():: Identifier of the stream for this request. + +Create or replace a resource. + +The body of the request is the entire representation of the resource. + +It is highly recommended to set the `content-type` header +to inform the server what media type the body contains. +Gun will automatically set the `content-length` header. + +The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it. + +=== request(ConnPid, Method, Path, Headers) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Method = iodata():: Request method. +Path = iodata():: Path of the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +StreamRef = reference():: Identifier of the stream for this request. + +Perform the given request. + +This is a general purpose function that should only be used +when existing method-specific functions don't apply. + +This function expects either `content-length` or `content-type` +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible. + +You can use the `gun:data/4` function to send the body, if any. + +=== request(ConnPid, Method, Path, Headers, Body) -> StreamRef + +ConnPid = pid():: The pid of the Gun connection process. +Method = iodata():: Request method. +Path = iodata():: Path of the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +Body = iodata():: Body of the request. +StreamRef = reference():: Identifier of the stream for this request. + +Perform the given request. + +This is a general purpose function that should only be used +when existing method-specific functions don't apply. + +It is highly recommended to set the `content-type` header +to inform the server what media type the body contains. +Gun will automatically set the `content-length` header. + +The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it. + +=== data(ConnPid, StreamRef, IsFin, Data) -> ok + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream this data belongs to. +IsFin = fin | nofin:: Whether this message terminates the request. +Data = iodata():: Data to be sent with the request. + +Stream the body of a request. + +@todo empty chunks + +This function can only be used if the request identified by +`StreamRef` came with headers indicating the presence of a +body and that body not being given when creating the request. + +All calls to this function must use `nofin` except for the +last which must use `fin` to indicate the end of the request +body. + +Empty data is allowed regardless of the value of `IsFin`. +Gun will not send empty data chunks unless required to +indicate the request body is finished, however. + +=== await(ConnPid, StreamRef) -> await(ConnPid, StreamRef, 5000, MonitorRef) + +Alias of `gun:await/4`. + +A monitor `MonitorRef` is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates. + +=== await(ConnPid, StreamRef, MonitorRef) -> await(ConnPid, StreamRef, 5000, MonitorRef) + +Alias of `gun:await/4`. + +=== await(ConnPid, StreamRef, Timeout) -> await(ConnPid, StreamRef, Timeout, MonitorRef) + +Alias of `gun:await/4`. + +A monitor `MonitorRef` is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates. + +=== await(ConnPid, StreamRef, Timeout, MonitorRef) -> tuple() -- see below + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream to await messages from. +Timeout = timeout():: How long this function will wait for messages. +MonitorRef = reference():: Monitor reference for the Gun connection process. + +Wait for a response message. + +This function can be used when a synchronous handling of +responses is desired. It will only return when a message +for the given stream is received, on error or on timeout. + +The return values are described in the next few subsections. + +==== {response, IsFin, Status, Headers} + +IsFin = fin | nofin:: Whether this message terminates the response. +Status = binary():: Status line for the response. +Headers = [{binary(), binary()}]:: Headers sent with the response. + +Equivalent of a `gun_response` message. + +==== {data, IsFin, Data} + +IsFin = fin | nofin:: Whether this message terminates the response. +Data = binary():: Data from the stream. + +Equivalent of a `gun_data` message. + +==== {push, NewStreamRef, URI, Headers} + +NewStreamRef = reference():: Identifier of the stream being pushed. +URI = binary():: URI of the resource. +Headers = [{binary(), binary()}]:: Headers @todo + +Equivalent of a `gun_push` message. + +@todo Same changes as gun_push + +==== {error, Reason} + +Reason = any():: Error reason. @todo any? + +Equivalent of a `gun_error` message. + +@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error + +=== await_body(ConnPid, StreamRef) -> await_body(ConnPid, StreamRef, 5000, MonitorRef) + +Alias of `gun:await_body/4`. + +A monitor `MonitorRef` is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates. + +=== await_body(ConnPid, StreamRef, MonitorRef) -> await_body(ConnPid, StreamRef, 5000, MonitorRef) + +Alias of `gun:await_body/4`. + +=== await_body(ConnPid, StreamRef, Timeout) -> await_body(ConnPid, StreamRef, Timeout, MonitorRef) + +Alias of `gun:await_body/4`. + +A monitor `MonitorRef` is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates. + +=== await_body(ConnPid, StreamRef, Timeout, MonitorRef) -> {ok, Body} | {error, Reason} + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream to await messages from. +Timeout = timeout():: How long this function will wait for each message. +MonitorRef = reference():: Monitor reference for the Gun connection process. +Body = binary():: Body for the given stream. +Reason = any():: Error reason. @todo any? + +Wait for a response body. + +This function can be used when a synchronous handling of +responses is desired. It will only return when it has +finished fetching the entire response body. + +The timeout value is *per message*. The actual function call +can last much longer for large bodies. + +@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error + +@todo guide might be a little incorrect about await/await_body + +=== flush(ConnPid) -> ok + +ConnPid = pid():: The pid of the Gun connection process. + +Flush all messages from the Gun connection process from the mailbox. + +=== flush(StreamRef) -> ok + +StreamRef = reference():: Stream identifier. + +Flush all messages related to the given stream. + +=== cancel(ConnPid, StreamRef) -> ok + +ConnPid = pid():: The pid of the Gun connection process. +StreamRef = reference():: Identifier of the stream to cancel. + +Cancel the given stream. + +HTTP/1.1 streams can't be cancelled. Gun will simply silence +the stream and stop relaying messages. + +@todo Depending on the length +@todo of a response Gun may also attempt to reconnect rather than +@todo receive the entire response body. + +SPDY streams can however be cancelled at any time. + +=== ws_upgrade(ConnPid, Path) -> ws_upgrade(ConnPid, Path, [], #{}) + +Alias of `gun:ws_upgrade/4`. + +=== ws_upgrade(ConnPid, Path, Headers) -> ws_upgrade(ConnPid, Path, Headers, #{}) + +Alias of `gun:ws_upgrade/4`. + +=== ws_upgrade(ConnPid, Path, Headers, Opts) -> ok + +ConnPid = pid():: The pid of the Gun connection process. +Path = iodata():: Path to the resource. +Headers = [{binary(), iodata()}]:: Additional request headers. +Opts = map():: Options for the Websocket connection. + +Request the connection to be upgraded to the Websocket protocol. + +@todo Only possible for HTTP. + +=== ws_send(ConnPid, Frames) -> ok + +ConnPid = pid():: The pid of the Gun connection process. +Frames = @todo:: @todo + +Send one or more Websocket frames. + +This function can only be used following a successful `ws_upgrade` call. diff --git a/doc/src/manual/gun_app.asciidoc b/doc/src/manual/gun_app.asciidoc new file mode 100644 index 0000000..e4447d6 --- /dev/null +++ b/doc/src/manual/gun_app.asciidoc @@ -0,0 +1,24 @@ += gun(7) + +== Name + +gun - Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket. + +== Dependencies + +The `gun` application uses the Erlang applications `ranch` +for abstracting TCP and TLS over a common interface, and +the `ssl` application for TLS support, required for HTTPS +and SPDY support. In addition, Gun requires the `crypto` +application (a dependency of `ssl`) for Websocket. + +These dependencies must be started 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/gun.md b/manual/gun.md deleted file mode 100644 index 611abf0..0000000 --- a/manual/gun.md +++ /dev/null @@ -1,340 +0,0 @@ -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) -> get(ServerPid, Path, []) -### get(ServerPid, Path, Headers) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> -> Fetch a resource. - -### head(ServerPid, Path) -> head(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) -> options(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. diff --git a/manual/gun_app.md b/manual/gun_app.md deleted file mode 100644 index 448145b..0000000 --- a/manual/gun_app.md +++ /dev/null @@ -1,22 +0,0 @@ -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 deleted file mode 100644 index 7765afc..0000000 --- a/manual/toc.md +++ /dev/null @@ -1,7 +0,0 @@ -Gun Function Reference -====================== - -The function reference documents the public interface of Gun. - - * [The Gun Application](gun_app.md) - * [gun](gun.md) |