diff options
Diffstat (limited to 'doc/src/manual/gun.asciidoc')
| -rw-r--r-- | doc/src/manual/gun.asciidoc | 791 |
1 files changed, 161 insertions, 630 deletions
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index 98fbabe..77253ba 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -2,7 +2,7 @@ == Name -gun - asynchronous HTTP client +gun - Asynchronous HTTP client == Description @@ -10,711 +10,242 @@ The `gun` module provides an asynchronous interface for connecting and communicating with Web servers over HTTP, HTTP/2 or Websocket. -== Types - -=== opts() = map() - -Configuration for the connection. - -The following keys are defined: - -connect_timeout => timeout():: - Connection timeout. Defaults to `infinity`. -http_opts => http_opts():: - Options specific to the HTTP protocol. See below. -http2_opts => http2_opts():: - Options specific to the HTTP/2 protocol. See below. -protocols => [http | http2]:: - Ordered list of preferred protocols. When the transport is tcp, - this list must contain exactly one protocol. When the transport - is ssl, this list must contain at least one protocol and will be - used using the ALPN protocol negotiation method. When the server - does not support ALPN then http will always be used. Defaults to - [http] when the transport is tcp, and [http2, http] when the - transport is ssl. -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. -trace => boolean():: - Whether to enable `dbg` tracing of the connection process. Should - only be used during debugging. Defaults to false. -transport => tcp | ssl:: - Whether to use SSL or plain TCP. The default varies depending on the - port used. Port 443 defaults to ssl. All other ports default to tcp. -transport_opts => proplists:proplist():: - Transport options. They are TCP options or SSL options depending on - the selected transport. -ws_opts => ws_opts():: - Options specific to the Websocket protocol. See below. - -// @todo better spec for transport_opts - -=== http_opts() = map() - -Configuration for the HTTP protocol. - -The following keys are defined: - -keepalive => timeout():: - Time between pings in milliseconds. Since the HTTP protocol has - no standardized way to ping the server, Gun will simply send an - empty line when the connection is idle. Gun only makes a best - effort here as servers usually have configurable limits to drop - idle connections. Use `infinity` to disable. Defaults to 5000. -transform_header_name => fun((LowercaseName :: binary()) -> TransformedName :: binary()) | undefined:: - A function that will be applied to all header names before they - are sent to the server. Gun assumes that all header names are in - lower case. This function is useful if you, for example, need to - re-case header names in the event that the server incorrectly - considers header name case to be significant. -version => 'HTTP/1.1' | 'HTTP/1.0':: - HTTP version to use. Defaults to 'HTTP/1.1'. - -=== http2_opts() = map() - -Configuration for the HTTP/2 protocol. - -The following keys are defined: - -keepalive => pos_integer():: - Time between pings in milliseconds. Defaults to 5000. - -=== req_opts() = map() - -Configuration for a particular request. - -The following keys are defined: - -reply_to => pid():: - The pid of a process that is responsible for the response handling. - -=== ws_opts() = map() - -Configuration for the Websocket protocol. - -The following keys are defined: - -compress => boolean():: - Whether to enable permessage-deflate compression. This does - not guarantee that compression will be used as it is the - server that ultimately decides. Defaults to false. - -== Messages - -Calling functions from this module may result in the following -messages being sent. - -=== {gun_up, ConnPid, Protocol} - -ConnPid = pid():: The pid of the Gun connection process. -Protocol = http | http2:: The protocol selected for this connection. - -The connection is up. - -This message informs the owner process that the connection or -reconnection completed. - -The protocol selected during the connection is sent in this -message. It can be used to determine the capabilities of the -server. - -Gun will now 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. - -=== {gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams} - -ConnPid = pid():: The pid of the Gun connection process. -Protocol = http | http2 | ws:: The protocol in use when the connection was lost. -Reason = normal | closed | {error, atom()}:: The reason for the loss of the connection. -KilledStreams = [reference()]:: List of streams that have been brutally terminated. -UnprocessedStreams = [reference()]:: List of streams that have not been processed by the server. - -The connection is down. - -This message informs the owner process that the connection is -currently down. Gun will automatically attempt to reconnect -depending on the `retry` and `retry_timeout` options. - -The reason of the termination is there for debugging purposes -only. You should not rely on this value to know what streams -were processed or completed. - -The _killed streams_ are the active streams that did not complete -before the closing of the connection. Whether they can be retried -safely depends on the protocol used and the idempotence property -of the requests. - -The _unprocessed streams_ are streams that the server did not -start processing yet. They may be retried safely depending on -what streams were killed before. - -When the connection goes back up, Gun will not attempt to retry -requests. It will also not upgrade to Websocket automatically -if that was the protocol in use when the connection was lost. - -=== {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 HTTP/2. - -@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, Headers} - -ConnPid = pid():: The pid of the Gun connection process. -Headers = [{binary(), binary()}]:: Headers sent with the response. - -Successful 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() | inet:ipaddress():: Host or IP 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/4`. - -=== delete(ConnPid, Path, Headers) -> delete(ConnPid, Path, Headers, #{}) - -Alias of `gun:delete/4`. - -=== delete(ConnPid, Path, Headers, ReqOpts) -> StreamRef - -ConnPid = pid():: The pid of the Gun connection process. -Path = iodata():: Path to the resource. -Headers = [{binary(), iodata()}]:: Additional request headers. -ReqOpts = req_opts():: Request options. -StreamRef = reference():: Identifier of the stream for this request. - -Delete a resource. - -=== get(ConnPid, Path) -> get(ConnPid, Path, [], #{}) +Connection: -Alias of `gun:get/4`. +* link:man:gun:open(3)[gun:open(3)] - Open a connection to the given host and port +* link:man:gun:open_unix(3)[gun:open_unix(3)] - Open a connection to the given Unix domain socket +// @todo * link:man:gun:shutdown(3)[gun:shutdown(3)] - Gracefully close the connection +* link:man:gun:close(3)[gun:close(3)] - Brutally close the connection +* link:man:gun:info(3)[gun:info(3)] - Obtain information about the connection -=== get(ConnPid, Path, Headers) -> get(ConnPid, Path, Headers, #{}) +Requests: -Alias of `gun:get/4`. +* link:man:gun:get(3)[gun:get(3)] - Get a resource representation +* link:man:gun:head(3)[gun:head(3)] - Get headers of a resource representation +* link:man:gun:options(3)[gun:options(3)] - Query the capabilities of the server or a resource +* link:man:gun:patch(3)[gun:patch(3)] - Apply a set of changes to a resource +* link:man:gun:post(3)[gun:post(3)] - Process the enclosed representation according to a resource's own semantics +* link:man:gun:put(3)[gun:put(3)] - Create or replace a resource +* link:man:gun:delete(3)[gun:delete(3)] - Delete a resource +* link:man:gun:request(3)[gun:request(3)] - Perform the given request +* link:man:gun:data(3)[gun:data(3)] - Stream the body of a request -=== get(ConnPid, Path, Headers, ReqOpts) -> StreamRef +Messages: -ConnPid = pid():: The pid of the Gun connection process. -Path = iodata():: Path to the resource. -Headers = [{binary(), iodata()}]:: Additional request headers. -ReqOpts = req_opts():: Request options. -StreamRef = reference():: Identifier of the stream for this request. +* link:man:gun:await(3)[gun:await(3)] - Wait for a response +* link:man:gun:await_body(3)[gun:await_body(3)] - Wait for the complete response body +* link:man:gun:await_up(3)[gun:await(3)] - Wait for the connection to be up +* link:man:gun:flush(3)[gun:flush(3)] - Flush all messages related to a connection or a stream -Get a resource. +Streams: -=== head(ConnPid, Path) -> head(ConnPid, Path, [], #{}) +* link:man:gun:cancel(3)[gun:cancel(3)] - Cancel the given stream -Alias of `gun:head/4`. +Websocket: -=== head(ConnPid, Path, Headers) -> head(ConnPid, Path, Headers, #{}) +* link:man:gun:ws_upgrade(3)[gun:ws_upgrade(3)] - Upgrade to Websocket +* link:man:gun:ws_send(3)[gun:ws_send(3)] - Send one or more Websocket frame(s) -Alias of `gun:head/4`. - -=== head(ConnPid, Path, Headers, ReqOpts) -> StreamRef - -ConnPid = pid():: The pid of the Gun connection process. -Path = iodata():: Path to the resource. -Headers = [{binary(), iodata()}]:: Additional request headers. -ReqOpts = req_opts():: Request options. -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/4`. - -=== options(ConnPid, Path, Headers) -> options(ConnPid, Path, Headers, #{}) - -Alias of `gun:options/4`. - -=== options(ConnPid, Path, Headers, ReqOpts) -> StreamRef - -ConnPid = pid():: The pid of the Gun connection process. -Path = iodata():: Path to the resource. -Headers = [{binary(), iodata()}]:: Additional request headers. -ReqOpts = req_opts():: Request options. -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) -> patch(ConnPid, Path, Headers, Body, #{}) - -Alias of `gun:patch/5`. - -=== patch(ConnPid, Path, Headers, Body, ReqOpts) -> 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. -ReqOpts = req_opts():: Request options. -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) -> post(ConnPid, Path, Headers, Body, #{}) - -Alias of `gun:post/5`. - -=== post(ConnPid, Path, Headers, Body, ReqOpts) -> 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. -ReqOpts = req_opts():: Request options. -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) -> put(ConnPid, Path, Headers, Body, #{}) - -Alias of `gun:put/5`. - -=== put(ConnPid, Path, Headers, Body, ReqOpts) -> 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. -ReqOpts = req_opts():: Request options. -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) -> request(ConnPid, Method, Path, Headers, Body, #{}) - -Alias of `gun:request/6`. - -=== request(ConnPid, Method, Path, Headers, Body, ReqOpts) -> 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. -ReqOpts = req_opts():: Request options. -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. +== Messages -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. +Gun will inform the calling process of events asynchronously +by sending any of the following messages: -=== await(ConnPid, StreamRef) -> await(ConnPid, StreamRef, 5000, MonitorRef) +Connection: -Alias of `gun:await/4`. +* link:man:gun_up(3)[gun_up(3)] - The connection is up +* link:man:gun_down(3)[gun_down(3)] - The connection is down +* link:man:gun_upgrade(3)[gun_upgrade(3)] - Successful protocol upgrade +* link:man:gun_error(3)[gun_error(3)] - Stream or connection-wide error -A monitor `MonitorRef` is automatically created for the duration of -this call and an error will be returned if the Gun connection process -terminates. +Responses: -=== await(ConnPid, StreamRef, MonitorRef) -> await(ConnPid, StreamRef, 5000, MonitorRef) +* link:man:gun_push(3)[gun_push(3)] - Server-initiated push +* link:man:gun_inform(3)[gun_inform(3)] - Informational response +* link:man:gun_response(3)[gun_response(3)] - Response +* link:man:gun_data(3)[gun_data(3)] - Response body +* link:man:gun_trailers(3)[gun_trailers(3)] - Response trailers -Alias of `gun:await/4`. +Websocket: -=== await(ConnPid, StreamRef, Timeout) -> await(ConnPid, StreamRef, Timeout, MonitorRef) +* link:man:gun_ws(3)[gun_ws(3)] - Websocket frame -Alias of `gun:await/4`. +The response messages will be sent to the process that opened +the connection by default. The `reply_to` request option can +be used to redirect request-specific messages to a different +process. -A monitor `MonitorRef` is automatically created for the duration of -this call and an error will be returned if the Gun connection process -terminates. +== Types -=== await(ConnPid, StreamRef, Timeout, MonitorRef) -> tuple() -- see below +=== http_opts() -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. +[source,erlang] +---- +http_opts() :: #{ + keepalive => timeout(), + transform_header_name => fun((binary()) -> binary()), + version => 'HTTP/1.1' | 'HTTP/1.0' +} +---- -Wait for a response message. +Configuration for the HTTP protocol. -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 default value is given next to the option name: -The return values are described in the next few subsections. +// @todo Document content_handlers and gun_sse. -==== {response, IsFin, Status, Headers} +keepalive (5000):: -IsFin = fin | nofin:: Whether this message terminates the response. -Status = binary():: Status line for the response. -Headers = [{binary(), binary()}]:: Headers sent with the response. +Time between pings in milliseconds. Since the HTTP protocol has +no standardized way to ping the server, Gun will simply send an +empty line when the connection is idle. Gun only makes a best +effort here as servers usually have configurable limits to drop +idle connections. Use `infinity` to disable. -Equivalent of a `gun_response` message. +transform_header_name - see below:: -==== {data, IsFin, Data} +A function that will be applied to all header names before they +are sent to the server. Gun assumes that all header names are in +lower case. This function is useful if you, for example, need to +re-case header names in the event that the server incorrectly +considers the case of header names to be significant. -IsFin = fin | nofin:: Whether this message terminates the response. -Data = binary():: Data from the stream. +version (`'HTTP/1.1'`):: -Equivalent of a `gun_data` message. +HTTP version to use. -==== {push, NewStreamRef, URI, Headers} +=== http2_opts() -NewStreamRef = reference():: Identifier of the stream being pushed. -URI = binary():: URI of the resource. -Headers = [{binary(), binary()}]:: Headers @todo +[source,erlang] +---- +http2_opts() :: #{ + keepalive => timeout() +} +---- -Equivalent of a `gun_push` message. +Configuration for the HTTP/2 protocol. -@todo Same changes as gun_push +The default value is given next to the option name: -==== {error, Reason} +// @todo Document content_handlers and gun_sse. -Reason = any():: Error reason. @todo any? +keepalive (5000):: -Equivalent of a `gun_error` message. +Time between pings in milliseconds. -@todo I think we want to distinguish a stream error, a general error, -@todo a DOWN and a timeout error +// @todo Allow and document max_frame_size_sent. -=== await_body(ConnPid, StreamRef) -> await_body(ConnPid, StreamRef, 5000, MonitorRef) +=== opts() -Alias of `gun:await_body/4`. +[source,erlang] +---- +opts() :: #{ + connect_timeout => timeout(), + http_opts => http_opts(), + http2_opts => http2_opts(), + protocols => [http | http2], + retry => non_neg_integer(), + retry_timeout => pos_integer(), + trace => boolean(), + transport => tcp | ssl, + transport_opts => [gen_tcp:connect_option()] | [ssl:connect_option()] + ws_opts => ws_opts() +} +---- -A monitor `MonitorRef` is automatically created for the duration of -this call and an error will be returned if the Gun connection process -terminates. +Configuration for the connection. -=== await_body(ConnPid, StreamRef, MonitorRef) -> await_body(ConnPid, StreamRef, 5000, MonitorRef) +The default value is given next to the option name: -Alias of `gun:await_body/4`. +connect_timeout (infinity):: -=== await_body(ConnPid, StreamRef, Timeout) -> await_body(ConnPid, StreamRef, Timeout, MonitorRef) +Connection timeout. -Alias of `gun:await_body/4`. +http_opts (#{}):: -A monitor `MonitorRef` is automatically created for the duration of -this call and an error will be returned if the Gun connection process -terminates. +Options specific to the HTTP protocol. -=== await_body(ConnPid, StreamRef, Timeout, MonitorRef) -> {ok, Body} | {error, Reason} +http2_opts (#{}):: -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? +Options specific to the HTTP/2 protocol. -Wait for a response body. +protocols - see below:: -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. +Ordered list of preferred protocols. When the transport is `tcp`, +this list must contain exactly one protocol. When the transport +is `ssl`, this list must contain at least one protocol and will be +used to negotiate a protocol via ALPN. When the server does not +support ALPN then `http` will always be used. Defaults to +`[http]` when the transport is `tcp`, and `[http2, http]` when the +transport is `ssl`. -The timeout value is *per message*. The actual function call -can last much longer for large bodies. +retry (5):: -@todo I think we want to distinguish a stream error, a general error, -@todo a DOWN and a timeout error +Number of times Gun will try to reconnect on failure before giving up. -@todo guide might be a little incorrect about await/await_body +retry_timeout (5000):: -=== flush(ConnPid) -> ok +Time between retries in milliseconds. -ConnPid = pid():: The pid of the Gun connection process. +trace (false):: -Flush all messages from the Gun connection process from the mailbox. +Whether to enable `dbg` tracing of the connection process. Should +only be used during debugging. -=== flush(StreamRef) -> ok +transport - see below:: -StreamRef = reference():: Stream identifier. +Whether to use SSL or plain TCP. The default varies depending on the +port used. Port 443 defaults to `ssl`. All other ports default to `tcp`. -Flush all messages related to the given stream. +transport_opts ([]):: -=== cancel(ConnPid, StreamRef) -> ok +Transport options. They are TCP options or SSL options depending on +the selected transport. -ConnPid = pid():: The pid of the Gun connection process. -StreamRef = reference():: Identifier of the stream to cancel. +ws_opts (#{}):: -Cancel the given stream. +Options specific to the Websocket protocol. -HTTP/1.1 streams can't be cancelled. Gun will simply silence -the stream and stop relaying messages. +=== req_opts() -@todo Depending on the length -@todo of a response Gun may also attempt to reconnect rather than -@todo receive the entire response body. +[source,erlang] +---- +req_opts() :: #{ + reply_to => pid() +} +---- -HTTP/2 streams can however be cancelled at any time. +Configuration for a particular request. -=== ws_upgrade(ConnPid, Path) -> ws_upgrade(ConnPid, Path, []) +The default value is given next to the option name: -Alias of `gun:ws_upgrade/3`. +reply_to (`self()`):: -=== ws_upgrade(ConnPid, Path, Headers) -> StreamRef +The pid of the process that will receive the response messages. -Similar to `gun:ws_upgrade/4`, except `WsOpts` is taken from -the options given in the `gun:open/{2,3}` call when opening -the connection. +=== ws_opts() -=== ws_upgrade(ConnPid, Path, Headers, WsOpts) -> StreamRef +[source,erlang] +---- +ws_opts() :: #{ + compress => boolean() +} +---- -ConnPid = pid():: The pid of the Gun connection process. -Path = iodata():: Path to the resource. -Headers = [{binary(), iodata()}]:: Additional request headers. -WsOpts = map():: Options for the Websocket connection. +Configuration for the Websocket protocol. -Request the connection to be upgraded to the Websocket protocol. +The default value is given next to the option name: -This function can only be used when the current protocol is `http`. +compress => boolean():: -=== ws_send(ConnPid, Frames) -> ok +Whether to enable permessage-deflate compression. This does +not guarantee that compression will be used as it is the +server that ultimately decides. Defaults to false. -ConnPid = pid():: The pid of the Gun connection process. -Frames = @todo:: @todo +// @todo Document default_protocol, protocols and user_opts. -Send one or more Websocket frames. +== See also -This function can only be used following a successful `ws_upgrade` call. +link:man:gun(7)[gun(7)] |