Callbacks

Event handlers implement the following interface. Because types are tied to specific events, they are documented alongside them. All event types are exported and can be referred to as gun_event:Type().

The events are ordered by the order they are likely to be triggered, with the most frequent events listed first.

init

init_event() :: #{
    owner := pid(),
    transport := tcp | tls,
    origin_scheme := binary(),
    origin_host := inet:hostname() | inet:ip_address(),
    origin_port := inet:port_number(),
    opts := gun:opts()
}

init(init_event(), State) -> State

Gun is initializing.

domain_lookup_start

domain_lookup_event() :: #{
    host := inet:hostname() | inet:ip_address(),
    port := inet:port_number(),
    tcp_opts := [gen_tcp:connect_option()],
    timeout := timeout(),
    lookup_info => gun_tcp:lookup_info(),
    error => any()
}

domain_lookup_start(domain_lookup_event(), State) -> State

Gun is starting to resolve the host address.

The lookup_info and error keys are never set for this event.

domain_lookup_end

domain_lookup_end(domain_lookup_event(), State) -> State

Gun has finished resolving the host address.

The lookup_info key is only set when the lookup is successful. The error key is set otherwise.

connect_start

connect_event() :: #{
    lookup_info := gun_tcp:lookup_info(),
    timeout := timeout(),
    socket => inet:socket(),
    protocol => http | http2 | socks | raw,
    error => any()
}

connect_start(connect_event(), State) -> State

Gun is starting to connect to the host address and port.

The socket, protocol and error keys are never set for this event.

connect_end

connect_end(connect_event(), State) -> State

Gun has finished connecting to the host address and port.

The socket key is set on connect success. The error key is set otherwise.

The protocol key is only set when the transport is tcp and the connection is successful. The protocol is only known in the tls_handshake_end event otherwise.

tls_handshake_start

tls_handshake_event() :: #{
    stream_ref => gun:stream_ref(),
    reply_to => pid(),
    socket := inet:socket() | ssl:sslsocket() | pid(), %% The socket before/after will be different.
    tls_opts := [ssl:tls_client_option()],
    timeout := timeout(),
    protocol => http | http2 | socks | raw,
    error => any()
}

tls_handshake_start(tls_handshake_event(), State) -> State

Gun has started a TLS handshake.

This and the tls_handshake_end event only occur when connecting to a TLS server or when upgrading the connection or a stream to use TLS, for example when using CONNECT or when connecting to a secure SOCKS server.

The stream_ref and reply_to keys are only set when the TLS handshake occurs as a result of a CONNECT request or inside an existing CONNECT tunnel.

The protocol and error keys are never set for this event.

tls_handshake_end

tls_handshake_end(tls_handshake_event(), State) -> State

Gun has finished a TLS handshake.

The protocol key is set on TLS handshake success. The error key is set otherwise.

request_start

request_start_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    function := headers | request | ws_upgrade | connect,
    method := iodata(),
    scheme => binary(),
    authority := iodata(),
    path => iodata(),
    headers := [{binary(), iodata()}]
}

request_start(request_start_event(), State) -> State

Gun is starting to send a request.

The scheme and path keys are never set when the function is set to connect.

request_headers

request_headers(request_start_event(), State) -> State

Gun has finished sending the request headers.

request_end

request_end_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid()
}

request_end(request_end_event(), State) -> State

Gun has finished sending the request.

push_promise_start

push_promise_start_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid()
}

push_promise_start(push_promise_start_event(), State) -> State

Gun has begun receiving a promised request (server push).

push_promise_end

push_promise_end_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    promised_stream_ref => gun:stream_ref(),
    method := binary(),
    uri := binary(),
    headers := [{binary(), iodata()}]
}

push_promise_end(push_promise_end_event(), State) -> State

Gun has finished receiving a promised request (server push). Promised requests never include a body.

Promised requests received during the graceful shutdown of the connection get canceled immediately.

response_start

response_start_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid()
}

response_start(response_start_event(), State) -> State

Gun has begun receiving a response.

response_inform

response_headers_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    status := non_neg_integer(),
    headers := [{binary(), binary()}]
}

response_inform(response_headers_event(), State) -> State

Gun has received an informational response (1xx status code).

A status with value 101 indicates that the response has concluded as the stream will be upgraded to a new protocol.

response_headers

response_headers(response_headers_event(), State) -> State

Gun has finished receiving response headers.

response_trailers

response_trailers_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    headers := [{binary(), binary()}]
}

response_trailers(response_trailers_event(), State) -> State

Gun has received response trailers.

response_end

response_end_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid()
}

response_end(response_end_event(), State) -> State

Gun has finished receiving a response.

ws_upgrade

ws_upgrade_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    opts := gun:ws_opts()
}

ws_upgrade(ws_upgrade_event(), State) -> State

A Websocket upgrade was requested.

Success is indicated by a response (101 informational if HTTP/1.1, 2xx if HTTP/2) followed by a protocol_changed event.

ws_recv_frame_start

ws_recv_frame_start_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    frag_state := cow_ws:frag_state(),
    extensions := cow_ws:extensions()
}

ws_recv_frame_start(ws_recv_frame_start_event(), State) -> State

Gun has begun receiving a Websocket frame.

ws_recv_frame_header

ws_recv_frame_header_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    frag_state := cow_ws:frag_state(),
    extensions := cow_ws:extensions(),
    type := cow_ws:frame_type(),
    rsv := cow_ws:rsv(),
    len := non_neg_integer(),
    mask_key := cow_ws:mask_key()
}

ws_recv_frame_header(ws_recv_frame_header_event(), State) -> State

Gun has received the header part of a Websocket frame.

It will be immediately be followed by the frame’s payload.

ws_recv_frame_end

ws_recv_frame_end_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    extensions := cow_ws:extensions(),
    close_code := undefined | cow_ws:close_code(),
    payload := binary()
}

ws_recv_frame_end(ws_recv_frame_end_event(), State) -> State

Gun has finished receiving a Websocket frame.

ws_send_frame_start

ws_send_frame_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    extensions := cow_ws:extensions(),
    frame := gun:ws_frame()
}

ws_send_frame_start(ws_send_frame_event(), State) -> State

Gun has started sending a Websocket frame.

ws_send_frame_end

ws_send_frame_end(ws_send_frame_event(), State) -> State

Gun has finished sending a Websocket frame.

protocol_changed

protocol_changed_event() :: #{
    stream_ref := gun:stream_ref(),
    protocol := http | http2 | socks | raw | ws
}

protocol_changed(protocol_changed_event(), State) -> State

The protocol has changed for either the entire Gun connection or for a specific stream.

The stream_ref key is only set when the protocol has changed for a specific stream or inside a CONNECT tunnel.

This event occurs during successful Websocket upgrades, as a result of successful CONNECT requests or after a SOCKS tunnel was successfully established.

origin_changed

origin_changed_event() :: #{
    stream_ref => gun:stream_ref(),
    type := connect | socks5,
    origin_scheme := binary(),
    origin_host := inet:hostname() | inet:ip_address(),
    origin_port := inet:port_number()
}

origin_changed(origin_changed_event(), State) -> State

The origin server has changed for either the Gun connection or for a specific stream.

The stream_ref key is only set when the origin has changed for a specific stream or inside a CONNECT tunnel.

cancel

cancel_event() :: #{
    stream_ref := gun:stream_ref(),
    reply_to := pid(),
    endpoint := local | remote,
    reason := atom()
}

cancel(cancel_event(), State) -> State

A stream has been canceled.

HTTP/1.1 streams can’t be canceled at the protocol level. In this case Gun will silence the stream for the user but events may still occur.

HTTP/2 streams can be canceled both by the client and the server. Events may still occur for a short time after the stream has been canceled.

disconnect

disconnect_event() :: #{
    reason := normal | closed | {error, any()}
}

disconnect(disconnect_event(), State) -> State

Gun has been disconnected from the server.

terminate

terminate_event() :: #{
    state := not_connected
        | domain_lookup | connecting | initial_tls_handshake | tls_handshake
        | connected | connected_data_only | connected_ws_only,
    reason := normal | shutdown | {shutdown, any()} | any()
}

terminate(terminate_event(), State) -> State

Gun is terminating.

Name

Description