View Source Messages to the owner process

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

Messages to Stream Owner

start_completed

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() }

active received data

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()} }

properties:

absolute_offset: absolute offset in this stream
len: byte size of the binary
flags: recv flags:
1. 'QUIC_RECEIVE_FLAG_NONE' Default, none
2. 'QUIC_RECEIVE_FLAG_0_RTT'
3. 'QUIC_RECEIVE_FLAG_FIN' Last piece of data from stream, implies a remote closing stream (send)

send_complete

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_send_shutdown

Peer has sent all the data and wants to shutdown gracefully.

{quic, peer_send_shutdown, stream_handle(), undefined}

@TODO mask

peer_send_aborted

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

peer_receive_aborted

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

send_shutdown_complete

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()}

shutdown_completed, stream is closed

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()
                                         }

idea_send_buffer_size

@TODO

peer_accepted

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

continue for passive receive

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}

passive mode

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}

Messages to Connection Owner

Connection connected

{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 ).

Transport Shutdown

Connection has been shutdown by the transport locally, such as idle timeout.

{quic, transport_shutdown, connection_handle(), #{ status := atom_reason()
                                                  , error := error_code()
                                                  }

Shutdown initiated by PEER

Peer side initiated connection shutdown.

{quic, shutdown, connection_handle(), ErrorCode :: error_code()}

Shutdown Complete

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()
                                      }}

Local Address Changed

Connection local addr is changed.

{quic, local_address_changed, connection_handle(), NewAddr :: string()}.

Peer Address Changed

Connection peer addr is changed.

{quic, peer_address_changed, connection_handle(), NewAddr :: string()}.

New stream started from peer

{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).

Streams available

More streams are available due to flow control from the peer.

Available = Max - Used

{quic, streams_available, connection_handle(), #{ bidi_streams := integer()
                                                 , unidi_streams := integer()
                                                 }}

Peer Needs Streams

Peer wants to open more streams but cannot due to flow control

{quic, peer_needs_streams, connection_handle(), unidi_streams | bidi_streams}

Ideal processor changed

@TODO, move owner close to the same core.

DATAGRAM state changed

{quic, dgram_state_changed, connection_handle(), #{ dgram_send_enabled := boolean(), dgram_max_len := uint64()}}

DATAGRAM received data

with connection handle and integer flag

{quic, binary(), connection_handle(), flag :: non_neg_integer()}

DATAGRAM send completed, success or fail.

{quic, dgram_send_state, connection_handle(), #{state := datagram_send_state()}}

Connection resumed

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.

New Session Ticket

Client Only The client received the NST`` (new session ticket) from the server ifQUICERCONNECTION_EVENT_MASK_NSThad been set in connection optquic_event_maskwhen client starts the connection. ``` erlang {quic, nst_received, connection_handle(), Ticket::binary()} ``` TheNSTcould be used by Client for 0-RTT handshake with a connection opt ```erlang {ok, ConnResumed} = quicer:connect("localhost", Port, [{nst, NST}], 5000), ``` ### Stream's connection is closed **Acceptor Only** Indicating the connection that the stream acceptor is accepting is closed. The stream acceptor will no longer get new incoming stream. ```erlang {quic, closed, undefined, undefined} ``` ## Messages to Listener Owner ### New incoming connection ``` erlang {quic, new_conn, connection_handle(), ConnecionInfo :: #{ 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. #### Properties 1. version: QUIC version 1. local_addr: local addr in IP:Port 1. remote_addr: remote addr in IP:Port 1. server_name: Server name 1. alpns: List of alpn, negotiated 1. client_alpns: Client provided alpns 1.crypto_buffer: TLS crypto_buffer in initial packet ### Listener Stopped ```erlang {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.

← Previous Page LICENSE

Next Page → Terminology

Settings View Source Messages to the owner process

properties:

View Source Messages to the owner process