gun - Asynchronous HTTP client
The gun module provides an asynchronous interface for
connecting and communicating with Web servers over HTTP,
HTTP/2 or Websocket.
Connection:
gun:open(3) - Open a connection to the given host and port
gun:open_unix(3) - Open a connection to the given Unix domain socket
gun:close(3) - Brutally close the connection
gun:info(3) - Obtain information about the connection
Requests:
gun:get(3) - Get a resource representation
gun:head(3) - Get headers of a resource representation
gun:options(3) - Query the capabilities of the server or a resource
gun:patch(3) - Apply a set of changes to a resource
gun:post(3) - Process the enclosed representation according to a resource’s own semantics
gun:put(3) - Create or replace a resource
gun:delete(3) - Delete a resource
gun:request(3) - Perform the given request
gun:data(3) - Stream the body of a request
Proxies:
gun:connect(3) - Establish a tunnel to the origin server
Messages:
gun:await(3) - Wait for a response
gun:await_body(3) - Wait for the complete response body
gun:await_up(3) - Wait for the connection to be up
gun:flush(3) - Flush all messages related to a connection or a stream
Streams:
gun:cancel(3) - Cancel the given stream
Websocket:
gun:ws_upgrade(3) - Upgrade to Websocket
gun:ws_send(3) - Send Websocket frames
Gun will inform the calling process of events asynchronously by sending any of the following messages:
Connection:
gun_up(3) - The connection is up
gun_down(3) - The connection is down
gun_upgrade(3) - Successful protocol upgrade
gun_error(3) - Stream or connection-wide error
Responses:
gun_push(3) - Server-initiated push
gun_inform(3) - Informational response
gun_response(3) - Response
gun_data(3) - Response body
gun_trailers(3) - Response trailers
Websocket:
gun_ws(3) - Websocket frame
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.
Destination of a CONNECT request.
The default value, if any, is given next to the option name:
Destination hostname and port number. Mandatory.
Upon successful completion of the CONNECT request, Gun will begin using these as the host and port of the origin server for subsequent requests.
Proxy authorization credentials. They are only sent when both options are provided.
Protocol that will be used for tunneled requests.
Transport that will be used for tunneled requests. Note that due to Erlang/OTP limitations it is not possible to tunnel a TLS connection inside a TLS tunnel.
Options to use for tunneled TLS connections.
Handshake timeout for tunneled TLS connections.
Configuration for the HTTP protocol.
The default value is given next to the option name:
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.
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.
'HTTP/1.1')
HTTP version to use.
Configuration for the HTTP/2 protocol.
The default value is given next to the option name:
Time between pings in milliseconds.
Configuration for the connection.
The default value is given next to the option name:
Connection timeout.
Options specific to the HTTP protocol.
Options specific to the HTTP/2 protocol.
Ordered list of preferred protocols. When the transport is tcp,
this list must contain exactly one protocol. When the transport
is tls, 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 tls.
Number of times Gun will try to reconnect on failure before giving up.
Time between retries in milliseconds.
Whether to enable dbg tracing of the connection process. Should
only be used during debugging.
Whether to use TLS or plain TCP. The default varies depending on the
port used. Port 443 defaults to tls. All other ports default to tcp.
Transport options. They are TCP options or TLS options depending on the selected transport.
Options specific to the Websocket protocol.
Configuration for a particular request.
The default value is given next to the option name:
self())
The pid of the process that will receive the response messages.
Configuration for the Websocket protocol.
The default value is given next to the option name:
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.
A non-empty list enables Websocket protocol negotiation. The
list of protocols will be sent in the sec-websocket-protocol
request header. The handler module interface is currently
undocumented and must be set to gun_ws_h.
1.3: Add the CONNECT destination’s protocols option and
deprecate the previously introduced protocol option.
1.2: Introduce the type connect_destination().