Exports

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:set_owner(3) - Set a new owner for the connection
gun:ping(3) - Check the health or RTT of the connection
gun:shutdown(3) - Gracefully close the connection
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:headers(3) - Initiate the given request
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:update_flow(3) - Update a stream’s flow control value
gun:cancel(3) - Cancel the given stream
gun:stream_info(3) - Obtain information about a stream

Websocket:

gun:ws_upgrade(3) - Upgrade to Websocket
gun:ws_send(3) - Send Websocket frames

Messages

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_tunnel_up(3) - The tunnel is up
gun_down(3) - The connection is down
gun_notify(3) - Optional event notification
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.

Types

connect_destination()

connect_destination() :: #{
    host      := inet:hostname() | inet:ip_address(),
    port      := inet:port_number(),

    username  => iodata(),
    password  => iodata(),
    protocols => protocols(),
    transport => tcp | tls,

    tls_opts              => [ssl:tls_client_option()],
    tls_handshake_timeout => timeout()
}

Destination of a CONNECT request.

The default value, if any, is given next to the option name:

host, port: 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.
username, password: Proxy authorization credentials. They are only sent when both options are provided.
protocols - see below: Ordered list of preferred protocols. Please refer to the protocols() type documentation for details.

Defaults to [http] when the transport is tcp, and [http2, http] when the transport is tls.
transport (tcp): Transport that will be used for tunneled requests.
tls_opts ([]): Options to use for tunneled TLS connections.
tls_handshake_timeout (infinity): Handshake timeout for tunneled TLS connections.

http_opts()

http_opts() :: #{
    closing_timeout             => timeout(),
    cookie_ignore_informational => boolean(),
    flow                        => pos_integer(),
    keepalive                   => timeout(),
    transform_header_name       => fun((binary()) -> binary()),
    version                     => 'HTTP/1.1' | 'HTTP/1.0'
}

Configuration for the HTTP protocol.

The default value is given next to the option name:

closing_timeout (15000): Time to wait before brutally closing the connection when a graceful shutdown was requested via a call to gun:shutdown(3).
cookie_ignore_informational (false): Whether cookies received inside informational responses (1xx status code) must be ignored.
flow - see below: The initial flow control value for all HTTP/1.1 streams. By default flow control is disabled.
keepalive (infinity): 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. Disabled by default due to potential incompatibilities.
transform_header_name - see below: 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.
version ('HTTP/1.1'): HTTP version to use.

http2_opts()

http2_opts() :: #{
    closing_timeout             => timeout(),
    cookie_ignore_informational => boolean(),
    flow                        => pos_integer(),
    keepalive                   => timeout(),
    keepalive_tolerance         => non_neg_integer(),
    notify_settings_changed     => boolean(),

    %% HTTP/2 state machine configuration.
    connection_window_margin_size  => 0..16#7fffffff,
    connection_window_update_threshold => 0..16#7fffffff,
    enable_connect_protocol        => boolean(),
    initial_connection_window_size => 65535..16#7fffffff,
    initial_stream_window_size     => 0..16#7fffffff,
    max_concurrent_streams         => non_neg_integer() | infinity,
    max_connection_window_size     => 0..16#7fffffff,
    max_decode_table_size          => non_neg_integer(),
    max_encode_table_size          => non_neg_integer(),
    max_fragmented_header_block_size => 16384..16#7fffffff,
    max_frame_size_received        => 16384..16777215,
    max_frame_size_sent            => 16384..16777215 | infinity,
    max_stream_window_size         => 0..16#7fffffff,
    preface_timeout                => timeout(),
    settings_timeout               => timeout(),
    stream_window_data_threshold   => 0..16#7fffffff,
    stream_window_margin_size      => 0..16#7fffffff,
    stream_window_update_threshold => 0..16#7fffffff
}

Configuration for the HTTP/2 protocol.

The default value is given next to the option name:

closing_timeout (15000): Time to wait before brutally closing the connection when a graceful shutdown was requested either via a call to gun:shutdown(3) or by the server.
cookie_ignore_informational (false): Whether cookies received inside informational responses (1xx status code) must be ignored.
flow - see below: The initial flow control value for all HTTP/2 streams. By default flow control is disabled.
keepalive (infinity): Time between pings in milliseconds.
keepalive_tolerance - see below: The number of unacknowledged pings in flight that are tolerated before the connection is closed. By default this mechanism is disabled even if keepalive is enabled.
notify_settings_changed (false): Whether Gun should send a gun_notify(3) message to the user when settings are changed by the server.

opts()

opts() :: #{
    connect_timeout       => timeout(),
    cookie_store          => gun_cookies:store(),
    domain_lookup_timeout => timeout(),
    http_opts             => http_opts(),
    http2_opts            => http2_opts(),
    protocols             => protocols(),
    retry                 => non_neg_integer(),
    retry_fun             => fun(),
    retry_timeout         => pos_integer(),
    supervise             => boolean(),
    tcp_opts              => [gen_tcp:connect_option()],
    tls_handshake_timeout => timeout(),
    tls_opts              => [ssl:tls_client_option()],
    trace                 => boolean(),
    transport             => tcp | tls,
    ws_opts               => ws_opts()
}

Configuration for the connection.

The default value is given next to the option name:

connect_timeout (infinity): Connection timeout.
cookie_store - see below: The cookie store that Gun will use for this connection. When configured, Gun will query the store for cookies and include them in the request headers; and add cookies found in response headers to the store.

By default no cookie store will be used.
domain_lookup_timeout (infinity): Domain lookup timeout.
http_opts (#{}): Options specific to the HTTP protocol.
http2_opts (#{}): Options specific to the HTTP/2 protocol.
protocols - see below: Ordered list of preferred protocols. Please refer to the protocols() type documentation for details.

Defaults to [http] when the transport is tcp, and [http2, http] when the transport is tls.
retry (5): Number of times Gun will try to reconnect on failure before giving up.
retry_fun - see below: A fun that will be called before every reconnect attempt. It receives the current number of retries left and the Gun options. It returns the next number of retries left and the timeout to apply before reconnecting.

The default fun will remove one to the number of retries and set the timeout to the retry_timeout value.

The fun must be defined as follow:

fun ((non_neg_integer(), opts()) -> #{
    retries => non_neg_integer(),
    timeout => pos_integer()
})

The fun will never be called when the retry option is set to 0. When this function returns 0 in the retries value, Gun will do one last reconnect attempt before giving up.

retry_timeout (5000): Time between retries in milliseconds.
supervise (true): Whether the Gun process should be started under the gun_sup supervisor. Set to false to use your own supervisor.
tcp_opts (DefaultOpts): TCP options used when establishing the connection. By default Gun enables send timeouts with the options [{send_timeout, 15000}, {send_timeout_close, true}].
tls_handshake_timeout (infinity): TLS handshake timeout.
tls_opts ([]): TLS options used for the TLS handshake after the connection has been established, when the transport is set to tls.
trace (false): Whether to enable dbg tracing of the connection process. Should only be used during debugging.
transport - see below: 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.
ws_opts (#{}): Options specific to the Websocket protocol.

protocols()

Protocol :: http | {http, http_opts()}
          | http2 | {http2, http2_opts()}
          | raw | {raw, raw_opts()}
          | socks | {socks, socks_opts()}

protocols() :: [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 be used, except when the list of preferred protocols is set to only accept socks.

Defaults to [http] when the transport is tcp, and [http2, http] when the transport is tls.

raw_opts()

raw_opts() :: #{
}

Configuration for the "raw" protocol.

req_headers()

req_headers() :: [{binary() | string() | atom(),   iodata()}]
               | #{binary() | string() | atom() => iodata()}

Request headers.

req_opts()

req_opts() :: #{
    flow     => pos_integer(),
    reply_to => pid() | {module(), atom(), list()}
                      | fun((_) -> _) | {fun(), list()},
    tunnel   => gun:stream_ref()
}

Configuration for a particular request.

The default value is given next to the option name:

flow - see below: The initial flow control value for the stream. By default flow control is disabled.
reply_to (self()): The pid of the process that will receive the response messages, or a function that will be called with the message as argument.

socks_opts()

socks_opts() :: #{
    host := inet:hostname() | inet:ip_address(),
    port := inet:port_number(),

    auth      => [{username_password, binary(), binary()} | none],
    protocols => protocols(),
    transport => tcp | tls,
    version   => 5,

    tls_opts              => [ssl:tls_client_option()],
    tls_handshake_timeout => timeout()
}

Configuration for the Socks protocol.

The default value, if any, is given next to the option name:

host, port: Destination hostname and port number. Mandatory.

Upon successful completion of the Socks connection, Gun will begin using these as the host and port of the origin server for subsequent requests.
auth ([none]): Authentication methods Gun advertises to the Socks proxy.
protocols - see below: Ordered list of preferred protocols. Please refer to the protocols() type documentation for details.

Defaults to [http] when the transport is tcp, and [http2, http] when the transport is tls.
transport (tcp): Transport that will be used for tunneled requests.
tls_opts ([]): Options to use for tunneled TLS connections.
tls_handshake_timeout (infinity): Handshake timeout for tunneled TLS connections.
version (5): Version of the Socks protocol to use.

stream_ref()

stream_ref() - see below

Unique identifier for a stream.

The exact type is considered to be an implementation detail.

ws_opts()

ws_opts() :: #{
    closing_timeout  => timeout(),
    compress         => boolean(),
    default_protocol => module(),
    flow             => pos_integer(),
    keepalive        => timeout(),
    protocols        => [{binary(), module()}],
    silence_pings    => boolean(),
    user_opts        => any()
}

Configuration for the Websocket protocol.

The default value is given next to the option name:

closing_timeout (15000): Time to wait before brutally closing the connection when a graceful shutdown was requested either via a call to gun:shutdown(3) or by the server.
compress (false): 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.
default_protocol (gun_ws_h): Default protocol module when no Websocket subprotocol is negotiated.
flow - see below: The initial flow control value for the Websocket connection. By default flow control is disabled.
keepalive (infinity): Time between pings in milliseconds.
protocols ([]): A non-empty list enables Websocket protocol negotiation. The list of protocols will be sent in the sec-websocket-protocol request header. The given module must follow the gun_ws_protocol(3) interface. Gun comes with a default interface in gun_ws_h that may be reused for negotiated protocols.
silence_pings (true): Whether the ping and pong frames should be sent to the user. In all cases Gun will automatically send a pong frame back when receiving a ping.
user_opts - see below: Additional options that are not in use by Gun unless a custom Websocket subprotocol is configured and negotiated. By default no user option is defined.

Changelog

2.2: The notify_settings_changed option for HTTP/2 was documented.
2.2: The reply_to option now accepts functions.
2.1: The HTTP/2 option list was updated with new options.
2.0: The default_protocol and user_opts Websocket options were added.
2.0: The stream_ref() type was added.
2.0: The option cookie_store was added. It can be used to configure a cookie store that Gun will use automatically. A related option, cookie_ignore_informational, was added to both http_opts() and http2_opts().
2.0: The types protocols() and socks_opts() have been added. Support for the Socks protocol has been added in every places where protocol selection is available. In addition it is now possible to specify separate HTTP options for the CONNECT proxy and the origin server.
2.0: The connect_timeout option has been split into three options: domain_lookup_timeout, connect_timeout and when applicable tls_handshake_timeout.
2.0: The option retry_fun was added. It can be used to implement different reconnect strategies.
2.0: The transport_opts option has been split into two options: tcp_opts and tls_opts.
2.0: Function gun:update_flow/3 introduced. The flow option was added to request options and HTTP/1.1, HTTP/2 and Websocket options as well.
2.0: Introduce the type req_headers() and extend the types accepted for header names for greater interoperability. Header names are automatically lowercased as well.
2.0: Function gun:headers/4,5 introduced.
2.0: The keepalive option is now set to infinity by default for all protocols. This means it is disabled.
2.0: Websocket options keepalive and silence_pings introduced.
2.0: Remove the protocol option from connect_destination().
1.3: Add the CONNECT destination’s protocols option and deprecate the previously introduced protocol option.
1.2: Introduce the type connect_destination().

Name

Description

Exports

Messages

Types

connect_destination()

http_opts()

http2_opts()

opts()

protocols()

raw_opts()

req_headers()

req_opts()

socks_opts()

stream_ref()

ws_opts()

Changelog

See also