gun_event - Events
The gun_event module provides the callback interface and types for implementing event handlers.
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_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_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_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_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_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_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_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_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_start_event(), State) -> State
Gun has finished sending the request headers.
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_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_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_event() :: #{
stream_ref := gun:stream_ref(),
reply_to := pid()
}
response_start(response_start_event(), State) -> State
Gun has begun receiving a response.
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_event(), State) -> State
Gun has finished receiving response headers.
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_event() :: #{
stream_ref := gun:stream_ref(),
reply_to := pid()
}
response_end(response_end_event(), State) -> State
Gun has finished receiving a response.
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_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_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_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_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_event(), State) -> State
Gun has finished sending a Websocket frame.
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_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_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_event() :: #{
reason := normal | closed | {error, any()}
}
disconnect(disconnect_event(), State) -> State
Gun has been disconnected from the server.
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.
Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:
Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.