This doc describes the messages that the owner of QUIC resources (listener, connection, stream) will receive.
The message is a fixed 4 elements tuple formatted as
{quic, EventName, ResourceHandle, EventProps}.
where
quic ::
The mark of quic messages, distinguishing TCP or SSL transport messages
EventName :: atom() | binary()
The name of event from the stack.
Event could be the event of the transport layer in atom() or the actual data in binary().
ResourceHandle :: handle()
The handle of the resource that generates the event.
EventProps :: undefined | map() | integer() | any()
The properties of the event.
The properties provide extra info for the event that usually cannot be ignored.
For the types() used in this doc pls refer to
Some events could be enabled/disabled by either:
- Set/unset the options while opening/starting the resources
%% Use 'start_flag' option indicating owner wants to receive `peer_accepted` event
{quicer:start_stream(Conn, [ {active, 3},
{start_flag, ?QUIC_STREAM_START_FLAG_INDICATE_PEER_ACCEPT}
]),
- Use the quic_event_mask, set in mask to enable receiving.
{quicer:start_stream(Conn, [{active, 3}, {quic_event_mask, ?QUICER_STREAM_EVENT_MASK_START_COMPLETE}]),
@TODO TBD: if we should have a strict rule that event is enabled in resource options but masked out in quic_event_mask
The stream initiated locally is started regardless of success/fail or sync/async.
The only event that will be delivered to the owner if start fails with atom status.
When 'QUIC_STREAM_START_FLAG_FAIL_BLOCKED' is set in stream 'start_flag', stream start will fail and the owner will get this event with status 'stream_limit_reached' if peer has flow control preventing initiating new stream. Otherwise, start stream will be queued. Also see peer_accepted
{quic, start_completed, stream_handle(), #{ status := atom_status()
, stream_id := integer()
, is_peer_accepted := boolean() }Stream data received in binary format with stream handle
also see [DATAGRAM received data].
{quic, binary(), stream_handle(), #{ absolute_offset := integer()
, len := integer()
, flags := integer()} }- absolute_offset: absolute offset in this stream
- len: byte size of the binary
- flags: recv flags:
- 'QUIC_RECEIVE_FLAG_NONE' Default, none
- 'QUIC_RECEIVE_FLAG_0_RTT'
- 'QUIC_RECEIVE_FLAG_FIN' Last piece of data from stream, implies a remote closing stream (send)
Send call is handled by stack, caller is ok to release the send buffer
This message is for sync send only.
IsSendCanceled: Peer abort receive
{quic, send_complete, stream_handle(), IsSendCanceled :: boolean()}Peer has sent all the data and wants to shutdown gracefully.
{quic, peer_send_shutdown, stream_handle(), undefined}@TODO mask
Received a RESET_STREAM Frame.
Peer terminated the sending part of the stream abruptly. The receiver can discard any data that it already received on the stream.
{quic, peer_send_aborted, stream_handle(), ErrorCode::integer()}where 'ErrorCode' is application layer error code
Received a RESET_STREAM Frame. The peer (receiver) abortively shut down the stream. The sender may assume the data sent is either handled or not handled.
{quic, peer_receive_aborted, stream_handle(), ErrorCode::integer()}where 'ErrorCode' is application layer error code
The send has been completely shut down. This will happen immediately on an abortive send or after a graceful stream send shutdown has been acknowledged by the peer.
{quic, send_shutdown_complete, stream_handle(), IsGraceful::boolean()}Both endpoints of sending and receiving of the stream have been shut down.
{quic, stream_closed, stream_handle(), #{ is_conn_shutdown := boolean()
, is_app_closing := boolean()
, is_shutdown_by_app := boolean()
, is_closed_remotely := boolean()
, status := atom_reason()
, error := error_code()
}@TODO
The stream which was not accepted due to peer flow control is now accepted by the peer.
To receive this event, the 'QUIC_STREAM_START_FLAG_INDICATE_PEER_ACCEPT' must be set
in start_flag while starting the stream.
{quic, peer_accepted, stream_handle(), undefined}Also see start_complete
This is for passive recv only, this is used to notify caller that new data is ready in recv buffer. The data in the recv buffer will be pulled by NIF function instead of by sending the erlang messages
see usage in: quicer:recv/2
{quic, continue, stream_handle(), undefined}Running out of active_n, stream now is in passive mode.
Should call setopt active_n to make it back to active mode again
Or use quicer:recv/2 to receive in passive mode
{quic, passive, stream_handle(), undefined}{quic, connected, connection_handle(), #{ is_resumed := boolean()
, alpns := string() | undefined
}}This message notifies the connection owner that quic connection is established ( the TLS handshake is done ).
Connection has been shutdown by the transport locally, such as idle timeout.
{quic, transport_shutdown, connection_handle(), #{ status := atom_reason()
, error := error_code()
}Peer side initiated connection shutdown.
{quic, shutdown, connection_handle(), ErrorCode :: error_code()}The connection has completed the shutdown process and is ready to be safely cleaned up.
{quic, closed, connection_handle(), #{ is_handshake_completed := boolean()
, is_peer_acked := boolean()
, is_app_closing := boolean()
}} Connection local addr is changed.
{quic, local_address_changed, connection_handle(), NewAddr :: string()}.
Connection peer addr is changed.
{quic, peer_address_changed, connection_handle(), NewAddr :: string()}.
{quic, new_stream, stream_handle(), #{ flags := stream_open_flags()
, is_orphan := boolean()
}}This message is sent to notify the process that the process becomes the owner of the stream.
When is_orphan is false, the process is selected as the owner because it is in the new stream acceptor list.
When is_orphan is true, the connection owner process is selected because there is no available stream acceptor
and the stream active mode is set to false (passive mode).
More streams are available due to flow control from the peer.
If you don't want this event, set 'QUICER_CONNECTION_EVENT_MASK_NO_STREAMS_AVAILABLE'
Available = Max - Used
{quic, streams_available, connection_handle(), #{ bidi_streams := integer()
, unidi_streams := integer()
}}Peer wants to open more streams but cannot due to flow control
{quic, peer_needs_streams, connection_handle(), unidi_streams | bidi_streams}@TODO, move owner close to the same core.
{quic, dgram_state_changed, connection_handle(), #{ dgram_send_enabled := boolean(), dgram_max_len := uint64()}}with connection handle and integer flag
{quic, binary(), connection_handle(), Flags :: non_neg_integer()}{quic, dgram_send_state, connection_handle(), #{state := datagram_send_state()}} Server only, connection is resumed with session ticket
{quic, connection_resumed, connection_handle(), SessionData :: false | binary() }Connection is resumed with binary session data or with 'false' means empty session data.
Client Only The client received the NST (new session ticket) from the server if QUICER_CONNECTION_EVENT_MASK_NST had been
set in connection opt quic_event_mask when client starts the connection.
{quic, nst_received, connection_handle(), Ticket::binary()}The NST could be used by Client for 0-RTT handshake with a connection opt
{ok, ConnResumed} = quicer:connect("localhost", Port, [{nst, NST}], 5000),Acceptor Only Indicating the connection that the stream acceptor is accepting is closed. The stream acceptor will no longer get new incoming stream.
{quic, closed, undefined, undefined}{quic, new_conn, connection_handle(), ConnectionInfo :: #{ version := integer()
, local_addr := string()
, remote_addr := string()
, server_name := binary()
, alpns := binary()
, client_alpns := binary()
, crypto_buffer:= binary()
}}This message is sent to the process who is accepting new connections.
The process becomes the connection owner.
To complete the TLS handshake, quicer:handshake/1,2 should be called.
- version: QUIC version
- local_addr: local addr in IP:Port
- remote_addr: remote addr in IP:Port
- server_name: Server name
- alpns: List of alpn, negotiated
- client_alpns: Client provided alpns
crypto_buffer: TLS crypto_buffer in initial packet
{quic, listener_stopped, listener_handle(), is_app_closing::boolean()}This message is sent to the listener owner process, indicating the listener is stopped and closed.
is_app_closing: handle is closed in the stack and in quicer we should never get true
because quicer close handle in resource dtor.