From 5b810c924da242632a04a2c44772cb892aa1b7c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 2 Jun 2018 22:44:16 +0200
Subject: Revamp the manual, one page per function/message

---
 doc/src/manual/gun.asciidoc | 791 +++++++++-----------------------------------
 1 file changed, 161 insertions(+), 630 deletions(-)

(limited to 'doc/src/manual/gun.asciidoc')

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)]
-- 
cgit v1.2.3

