quicer (quicer v0.4.3)
View SourceSummary
Functions
Return ABI version of the library.
Accept new Connection (Server)
Accept new Connection (Server) with timeout
Accept new stream on a existing connection with stream opts
Accept new stream on a existing connection with stream opts with timeout
Accept new stream on a existing connection with stream opts
Async variant of close_connection/4
async variant of close_stream/1, prefer to use async_shutdown_stream/4
Initiate New Connection (Client)
Send data over a new local stream in the connection, return new stream handle if success.
Complete TLS handshake after accepted a Connection.
Complete TLS handshake after accepted a Connection. also set connection options which override the default listener options.
async variant of send/2 Caller should NOT expect to receive
async variant of send/3 If QUICER_SEND_FLAG_SYNC is set , the caller should expect to receive {quic, send_complete, Stream, send_complete_flag()} note, check send_complete_flag() to ensure it is delivered or not.
Sending Unreliable Datagram. Caller should handle the async signals for the send results
Async starts the shutdown process and caller should expect for connection down message {quic, close, Conn}
async variant of shutdown_stream/2
async variant of shutdown_stream/4 Caller should expect to receive
Close connection with flag specified and application reason code.
Close connection with flag specified and application reason code with timeout
Close library.
close listener with listener handle
close a registration.
Normal shutdown stream with infinity timeout.
Normal shutdown (App errno=0) Stream gracefully with timeout.
Another name of shutdown stream for migration from tcp/ssl.
Initiate New Connection (Client)
set controlling process for Connection/Stream. For Stream, also flush the sig buffer to old owner if failed or new owner if succeeded. mimic ssl:controlling_process/2
Pop out continuous data from the buffer start from the offset.
Get a list connections under global registration
Get a list of connections under registration handle
Get a list listeners under global registration
Get a list of listeners under registration handle
get registration name
get registration reference count
get stream id with stream handle
Get connection/stream/listener opts mimic ssl:getopts/2
Get connection/stream/listener opts mimic ssl:getopt/2
get connection state mimic ssl:getstat/2
handoff_stream without post handoff data. see handoff_stream/3
Used by Old stream owner to handoff to the new stream owner.
Complete TLS handshake after accepted a Connection with 5s timeout (Server)
Complete TLS handshake after accepted a Connection
Check if the bit mask is set in the integer.
Return true if stream open flags has unidirectional flag set
Start listen on Port or "HOST:PORT".
List listener with app name
list all listeners
Returns the protocol negotiated through ALPN or NPN extensions.
Create a new registration.
Quicer library must be opened before any use.
Peer Cert in DER-encoded binary mimic ssl:peername/1
Peer name mimic ssl:peername/1
get QUIC stack performance counters
Probe conn state with 0 len dgram.
Convert quic data event to quic_data for fpbuffer
Recv Data (Passive mode) Passive recv data from stream.
close Registraion. Reserved for future upgrade, don't use it.
GRegistraion should be opened before calling traffic APIs.
Registraion should be opened before calling traffic APIs. Registraion creates application context, worker threads shared for all the connections
Send binary data over stream, blocking until send request is handled by the transport worker. either succeeded or cancelled
Send binary data over stream with send flags either succeeded or cancelled
Sending Unreliable Datagram return error only if sending could not be scheduled such as not_enough_mem, connection is already closed or wrong args. otherwise, it is fire and forget.
Set connection/stream/listener opts mimic ssl:setopt/2
Starts the shutdown process on a connection and block until it is finished.
Starts the shutdown process on a connection and block until it is finished. but with a timeout
Starts the shutdown process on a connection with shutdown flag and applications error with 5s timeout
Starts the shutdown process on a connection with shutdown flag and applications error with timeout
Shutdown a registration.
Shutdown a registration with error code and silent flag.
Shutdown stream gracefully, with infinity timeout
Shutdown stream gracefully, with app_errno 0
Start shutdown Stream process with flags and application specified error code.
Get socket name mimic ssl:sockname/1
start a listener process under supervisor tree
Start a stopped listener with listener handle with new Options.
Start new stream in connection, return new stream handle.
Stop a started listener which could be closed or restarted later.
terminate a listener process under supervisor tree
update fpbuffer and return *next* continuous data.
Used by new stream owner to wait for stream handoff complete. Use this for handoff the orphan stream *only*.
Types
-type acceptor_opts() :: #{active => boolean(), max_bytes_per_key => uint64(), handshake_idle_timeout_ms => uint64(), idle_timeout_ms => uint64(), tls_client_max_send_buffer => uint32(), tls_server_max_send_buffer => uint32(), stream_recv_window_default => uint32(), stream_recv_buffer_default => uint32(), conn_flow_control_window => uint32(), max_stateless_operations => uint32(), initial_window_packets => uint32(), send_idle_timeout_ms => uint32(), initial_rtt_ms => uint32(), max_ack_delay_ms => uint32(), disconnect_timeout_ms => uint32(), keep_alive_interval_ms => uint32(), congestion_control_algorithm => uint16(), peer_bidi_stream_count => uint16(), peer_unidi_stream_count => uint16(), retry_memory_limit => uint16(), load_balancing_mode => uint16(), max_operations_per_drain => uint8(), send_buffering_enabled => uint8(), pacing_enabled => uint8(), migration_enabled => uint8(), datagram_receive_enabled => uint8(), server_resumption_level => uint8(), minimum_mtu => uint16(), maximum_mtu => uint16(), mtu_discovery_search_complete_timeout_us => uint64(), mtu_discovery_missing_probe_count => uint8(), max_binding_stateless_operations => uint16(), stateless_operation_expiration_ms => uint16()}.
-type alpn() :: string().
-type app_errno() :: non_neg_integer().
-type atom_reason() ::
success | pending | continue | out_of_memory | invalid_parameter | invalid_state |
not_supported | not_found | buffer_too_small | handshake_failure | aborted | address_in_use |
connection_timeout | connection_idle | internal_error | connection_refused | protocol_error |
ver_neg_error | unreachable | tls_error | user_canceled | alpn_neg_failure |
stream_limit_reached.
-type cert() :: binary().
-type cert_and_chain() :: {cert(), cert_chain()}.
-type cert_chain() :: [cert()].
-type conf_handle() :: reference().
-type conn_opts() :: #{alpn := [string()], conn_callback => module(), custom_verify => boolean(), handle => connection_handle(), nst => binary(), handshake_idle_timeout_ms => non_neg_integer(), quic_event_mask => uint32(), disable_1rtt_encryption => boolean(), local_address => string(), local_bidi_stream_count => uint16(), local_peer_unidi_stream_count => uint16(), cert => file:filename(), certfile => file:filename(), key => file:filename(), keyfile => file:filename(), password => string(), verify => none | peer | verify_peer | verify_none, cacertfile => file:filename(), sslkeylogfile => file:filename(), max_bytes_per_key => uint64(), handshake_idle_timeout_ms => uint64(), idle_timeout_ms => uint64(), tls_client_max_send_buffer => uint32(), tls_server_max_send_buffer => uint32(), stream_recv_window_default => uint32(), stream_recv_buffer_default => uint32(), conn_flow_control_window => uint32(), max_stateless_operations => uint32(), initial_window_packets => uint32(), send_idle_timeout_ms => uint32(), initial_rtt_ms => uint32(), max_ack_delay_ms => uint32(), disconnect_timeout_ms => uint32(), keep_alive_interval_ms => uint32(), congestion_control_algorithm => uint16(), peer_bidi_stream_count => uint16(), peer_unidi_stream_count => uint16(), retry_memory_limit => uint16(), load_balancing_mode => uint16(), max_operations_per_drain => uint8(), send_buffering_enabled => uint8(), pacing_enabled => uint8(), migration_enabled => uint8(), datagram_receive_enabled => uint8(), server_resumption_level => uint8(), minimum_mtu => uint16(), maximum_mtu => uint16(), mtu_discovery_search_complete_timeout_us => uint64(), mtu_discovery_missing_probe_count => uint8(), max_binding_stateless_operations => uint16(), stateless_operation_expiration_ms => uint16(), dynamic() => dynamic()}.
-type conn_shutdown_flag() :: 0 | 1.
-type connection_handle() :: reference().
-type csend_flags() :: 0 | 1 | 2 | 4 | 8 | 16.
-type error_code() :: non_neg_integer().
-type execution_profile() ::
quic_execution_profile_low_latency | quic_execution_profile_max_throughput |
quic_execution_profile_scavenger | quic_execution_profile_real_time.
-type fpbuffer() :: #{next_offset := non_neg_integer(), buffer := quic_data_buffer()}.
-type global_handle() :: quic_global.
-type handle() :: global_handle() | listener_handle() | connection_handle() | stream_handle() | conf_handle() | reg_handle().
-type ifrag() :: {Index :: non_neg_integer(), quic_data()}.
-type listen_on() :: inet:port_number() | string().
-type listen_opts() :: #{alpn := [alpn()], allow_insecure => boolean(), quic_registration => reg_handle(), conn_acceptors => non_neg_integer(), cert => file:filename(), certfile => file:filename(), key => file:filename(), keyfile => file:filename(), password => string(), verify => none | peer | verify_peer | verify_none, cacertfile => file:filename(), sslkeylogfile => file:filename(), max_bytes_per_key => uint64(), handshake_idle_timeout_ms => uint64(), idle_timeout_ms => uint64(), tls_client_max_send_buffer => uint32(), tls_server_max_send_buffer => uint32(), stream_recv_window_default => uint32(), stream_recv_buffer_default => uint32(), conn_flow_control_window => uint32(), max_stateless_operations => uint32(), initial_window_packets => uint32(), send_idle_timeout_ms => uint32(), initial_rtt_ms => uint32(), max_ack_delay_ms => uint32(), disconnect_timeout_ms => uint32(), keep_alive_interval_ms => uint32(), congestion_control_algorithm => uint16(), peer_bidi_stream_count => uint16(), peer_unidi_stream_count => uint16(), retry_memory_limit => uint16(), load_balancing_mode => uint16(), max_operations_per_drain => uint8(), send_buffering_enabled => uint8(), pacing_enabled => uint8(), migration_enabled => uint8(), datagram_receive_enabled => uint8(), server_resumption_level => uint8(), minimum_mtu => uint16(), maximum_mtu => uint16(), mtu_discovery_search_complete_timeout_us => uint64(), mtu_discovery_missing_probe_count => uint8(), max_binding_stateless_operations => uint16(), stateless_operation_expiration_ms => uint16()}.
-type listener_handle() :: reference().
-type listener_opts() :: quicer_listener:listener_opts().
-type new_stream_props() :: #{is_orphan := boolean(), flags := stream_open_flags()}.
-type optlevel() :: false | quic_global | quic_registration | quic_configuration | quic_tls.
-type optname() :: optname_global() | optname_listener() | optname_conn() | optname_stream() | optname_reg() | optname_configuration() | optname_tls().
-type optname_configuration() :: settings | ticket_keys.
-type optname_conn() ::
quic_version | local_address | remote_address | ideal_processor | settings | statistics |
statistics_plat | share_udp_binding | local_bidi_stream_count | local_unidi_stream_count |
max_stream_ids | close_reason_phrase | stream_scheduling_scheme | datagram_receive_enabled |
datagram_send_enabled | disable_1rtt_encryption | resumption_ticket | peer_certificate_valid |
local_interface.
-type optname_global() ::
retry_memory_percent | supported_versions | load_balacing_mode | perf_counters |
global_settings | global_version.
-type optname_listener() :: local_address | stats | cibir_id.
-type optname_reg() :: cid_prefix.
-type optname_stream() ::
active | controlling_process | stream_id | '0rtt_length' | ideal_send_buffer_size | priority.
-type optname_tls() :: schannel_context_attribute_w | handshake_info | negotiated_alpn.
-type peer_accepted_props() :: #{is_conn_shutdown := boolean(), is_app_closing := boolean(), is_shutdown_by_app := boolean(), is_closed_remotely := boolean(), status := atom_reason(), error := error_code()}.
-type quic_data() :: #quic_data{offset :: non_neg_integer(), size :: non_neg_integer(), flags :: integer(), bin :: binary()}.
-type quic_data_buffer() :: ordsets:ordset(ifrag()).
-type quic_handle_level() :: quic_tls | quic_configuration | false.
-type quicer_addr() :: string().
-type reg_handle() :: reference().
-type registration_profile() :: execution_profile().
-type send_flags() :: csend_flags() | 4096.
-type stream_closed_props() :: map().
-type stream_handle() :: reference().
-type stream_open_flags() :: 0 | 1 | 2.
-type stream_opts() :: #{active := active_n(), open_flag => stream_open_flags(), start_flag => stream_start_flags(), event_mask => uint32(), disable_fpbuffer => boolean(), stream_id => uint62(), priority => uint16(), ideal_send_buffer_size => uint64(), '0rtt_length' => uint64(), dynamic() => dynamic()}.
-type stream_shutdown_flags() :: 0 | 1 | 2 | 4 | 6 | 8.
-type stream_start_flags() :: 0 | 1 | 2 | 4 | 8.
-type streams_available_props() :: #{unidi_streams := non_neg_integer(), bidi_streams := non_neg_integer()}.
-type transport_shutdown_props() :: #{is_conn_shutdown := boolean(), is_app_closing := boolean(), is_shutdown_by_app := boolean(), is_closed_remotely := boolean(), status := atom_reason(), error := error_code()}.
-type uint8() :: 0..1 bsl 8 - 1.
-type uint16() :: 0..1 bsl 16 - 1.
-type uint32() :: 0..1 bsl 32 - 1.
-type uint62() :: 0..1 bsl 62 - 1.
-type uint64() :: 0..1 bsl 64 - 1.
Functions
-spec abi_version() -> quicer_nif:abi_version().
Return ABI version of the library.
-spec accept(listener_handle(), acceptor_opts()) -> {ok, connection_handle()} | {error, any()}.
Accept new Connection (Server)
Accept new connection from listener_handle().
Calling process becomes the owner of the connection.
-spec accept(listener_handle(), acceptor_opts(), timeout()) -> {ok, connection_handle()} | {error, badarg | param_error | not_enough_mem | badpid} | {error, timeout}.
Accept new Connection (Server) with timeout
See also: accept/2.
-spec accept_stream(connection_handle(), stream_opts()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {erro, timeout}.
Accept new stream on a existing connection with stream opts
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered. (@TODO may not be default)
-spec accept_stream(connection_handle(), stream_opts(), timeout()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {erro, timeout}.
Accept new stream on a existing connection with stream opts with timeout
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered.
See also: async_accept_stream/2.
-spec async_accept(listener_handle(), acceptor_opts()) -> {ok, listener_handle()} | {error, badarg | param_error | not_enough_mem | badpid}.
-spec async_accept_stream(connection_handle(), proplists:proplist() | map()) -> {ok, connection_handle()} | {error, any()}.
Accept new stream on a existing connection with stream opts
Calling process become the owner of the new stream and it get monitored by NIF.
Once the Calling process is dead, closing stream will be triggered.
Caller process should expect to receive
{quic, new_stream, stream_handle(), new_stream_props()}note, it returns
{ok, connection_handle()}.NOT
{ok, stream_handle()}.See also: async_accept_stream/2.
-spec async_close_connection(connection_handle()) -> ok.
-spec async_close_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok.
Async variant of close_connection/4
See also: async_close_connection/3.
-spec async_close_stream(stream_handle()) -> ok | {error, badarg}.
async variant of close_stream/1, prefer to use async_shutdown_stream/4
See also: async_shutdown_stream/4, close_stream/4.
-spec async_connect(inet:hostname() | inet:ip_address(), inet:port_number(), conn_opts()) -> {ok, connection_handle()} | {error, conn_open_error | config_error | conn_start_error}.
Initiate New Connection (Client)
Async variant of connect/4
See also: connect/4.
-spec async_csend(connection_handle(), iodata(), stream_opts(), send_flags()) -> {ok, stream_handle()} | {error, any()} | {error, stm_open_error, atom_reason()} | {error, stream_send_error, atom_reason()}.
Send data over a new local stream in the connection, return new stream handle if success.
-spec async_handshake(connection_handle()) -> ok | {error, any()}.
Complete TLS handshake after accepted a Connection.
See also: async_handshake/2, handshake/2.
-spec async_handshake(connection_handle(), conn_opts()) -> ok | {error, any()}.
Complete TLS handshake after accepted a Connection. also set connection options which override the default listener options.
See also: async_handshake/1, handshake/2.
-spec async_send(stream_handle(), iodata()) -> {ok, BytesSent :: pos_integer()} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
async variant of send/2 Caller should NOT expect to receive
{quic, send_complete, Stream, send_complete_flag()}note, check send_complete_flag() to ensure it is delivered or not.
-spec async_send(stream_handle(), iodata(), non_neg_integer()) -> {ok, BytesSent :: pos_integer()} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
async variant of send/3 If QUICER_SEND_FLAG_SYNC is set , the caller should expect to receive {quic, send_complete, Stream, send_complete_flag()} note, check send_complete_flag() to ensure it is delivered or not.
-spec async_send_dgram(connection_handle(), binary()) -> {ok, non_neg_integer()} | {error, badarg | not_enough_mem | invalid_parameter | closed} | {error, dgram_send_error, atom_reason()}.
Sending Unreliable Datagram. Caller should handle the async signals for the send results
ref: https://datatracker.ietf.org/doc/html/rfc9221
See also: send/2, send_dgram/2.
-spec async_shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, badarg | closed}.
Async starts the shutdown process and caller should expect for connection down message {quic, close, Conn}
-spec async_shutdown_stream(stream_handle()) -> ok | {error, badarg | atom_reason()}.
async variant of shutdown_stream/2
See also: async_shutdown_stream/3.
-spec async_shutdown_stream(stream_handle(), stream_shutdown_flags(), app_errno()) -> ok | {error, badarg}.
async variant of shutdown_stream/4 Caller should expect to receive
{quic, stream_closed, Stream, Flags}-spec close_connection(connection_handle()) -> ok | {error, badarg}.
-spec close_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, badarg | timeout}.
Close connection with flag specified and application reason code.
See also: shutdown_connection/3.
-spec close_connection(connection_handle(), conn_shutdown_flag(), app_errno(), timeout()) -> ok | {error, badarg | timeout}.
Close connection with flag specified and application reason code with timeout
See also: shutdown_connection/4.
-spec close_lib() -> ok.
Close library.
This is reserved for upgrade support
Danger! Do not use it!
-spec close_listener(listener_handle()) -> ok | {error, badarg | closed | timeout}.
close listener with listener handle
-spec close_listener(listener_handle(), timeout()) -> ok | {error, badarg | closed | timeout}.
-spec close_registration(reg_handle()) -> ok.
close a registration.
-spec close_stream(stream_handle()) -> ok | {error, badarg | timeout}.
Normal shutdown stream with infinity timeout.
See also: close_stream/2.
-spec close_stream(stream_handle(), timeout()) -> ok | {error, badarg | timeout}.
Normal shutdown (App errno=0) Stream gracefully with timeout.
See also: close_stream/4.
-spec close_stream(stream_handle(), stream_shutdown_flags(), app_errno(), timeout()) -> ok | {error, badarg | timeout}.
Another name of shutdown stream for migration from tcp/ssl.
See also: close_stream/1, shutdown_stream/4.
-spec complete_cert_validation(connection_handle(), boolean(), integer()) -> ok | {error, any()}.
-spec connect(inet:hostname() | inet:ip_address(), inet:port_number(), conn_opts(), timeout()) -> {ok, connection_handle()} | {ok, connection_handle(), cert_and_chain()} | {error, conn_open_error | config_error | conn_start_error | timeout | nst_not_found} | {error, transport_down, transport_shutdown_props()}.
Initiate New Connection (Client)
Initiate new connection to remote endpoint with connection opts specified.
See also: async_connect/3.
-spec controlling_process(connection_handle() | stream_handle(), pid()) -> ok | {error, closed | badarg | owner_dead | not_owner}.
set controlling process for Connection/Stream. For Stream, also flush the sig buffer to old owner if failed or new owner if succeeded. mimic ssl:controlling_process/2
See also: handoff_stream/2, wait_for_handoff/2.
-spec count_reg_conns(reg_handle() | global) -> non_neg_integer().
-spec defrag_fpbuffer(Offset :: non_neg_integer(), quic_data_buffer()) -> {NewOffset :: non_neg_integer(), NewBuffer :: quic_data_buffer(), Res :: [quic_data()]}.
Pop out continuous data from the buffer start from the offset.
-spec get_conn_owner(connection_handle()) -> quicer_nif:get_owner().
-spec get_conn_rid(connection_handle()) -> {ok, non_neg_integer()} | {error, any()}.
-spec get_connections() -> quicer_nif:get_connections().
Get a list connections under global registration
-spec get_connections(reg_handle() | global) -> quicer_nif:get_connections().
Get a list of connections under registration handle
-spec get_listener_owner(listener_handle()) -> quicer_nif:get_owner().
-spec get_listeners() -> quicer_nif:get_listeners().
Get a list listeners under global registration
-spec get_listeners(reg_handle() | global) -> quicer_nif:get_listeners().
Get a list of listeners under registration handle
-spec get_registration_name(reg_handle()) -> quicer_nif:get_registration_name().
get registration name
-spec get_registration_refcnt(global | reg_handle()) -> quicer_nif:get_registration_refcnt().
get registration reference count
-spec get_stream_id(Stream :: stream_handle()) -> {ok, integer()} | {error, any()} | not_found.
get stream id with stream handle
-spec get_stream_owner(stream_handle()) -> quicer_nif:get_owner().
-spec get_stream_rid(stream_handle()) -> {ok, non_neg_integer()} | {error, any()}.
Get connection/stream/listener opts mimic ssl:getopts/2
-spec getopt(handle(), optname(), optlevel()) -> not_found | {ok, [any()]} | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
Get connection/stream/listener opts mimic ssl:getopt/2
-spec getstat(connection_handle(), [inet:stat_option()]) -> {ok, list()} | {error, any()}.
get connection state mimic ssl:getstat/2
-spec handoff_stream(stream_handle(), pid()) -> ok | {error, any()}.
handoff_stream without post handoff data. see handoff_stream/3
-spec handoff_stream(stream_handle(), pid(), term()) -> ok | {error, any()}.
Used by Old stream owner to handoff to the new stream owner.
1. The Stream will be put into passive mode so the data is paused.
2. The Stream signal buffer will be enabled, so the signal is paused.
3. Stream messages (for both data and sig )in the current owners process messages queue will be forwarded to the New Owner's mailbox in the same recv order.
4. Set the control process of the stream to the new owner, signal buffer will be flushed to new owner if succeed, otherwise to the old owner
5. A signal msg {handoff_done, Stream, PostHandoff} will be sent to the new owner. The new owner should block for this message before handle any stream data to ensure the ordering.
6. Revert stream active mode whatever handoff fail or success. also @see wait_for_handoff/2 also @see controlling_process/2
-spec handshake(connection_handle()) -> {ok, connection_handle()} | {error, any()}.
Complete TLS handshake after accepted a Connection with 5s timeout (Server)
See also: accept/3, handshake/2.
-spec handshake(connection_handle(), timeout()) -> {ok, connection_handle()} | {ok, connection_handle(), cert_and_chain()} | {error, any()}.
-spec handshake(connection_handle(), conn_opts(), timeout()) -> {ok, connection_handle()} | {error, any()}.
Complete TLS handshake after accepted a Connection
See also: async_handshake/1, handshake/2.
Check if the bit mask is set in the integer.
-spec is_unidirectional(stream_open_flags()) -> boolean().
Return true if stream open flags has unidirectional flag set
-spec listen(listen_on(), listen_opts()) -> {ok, listener_handle()} | {error, quic_tls} | {error, cacertfile} | {error, quic_registration} | {error, badarg} | {error, listener_open_error, atom_reason()} | {error, listener_start_error, atom_reason()}.
Start listen on Port or "HOST:PORT".
listener_handle() is used for accepting new connection. notes,
1. Port binding is done in NIF context, thus you cannot see it from inet:i().
2. ListenOn can either be integer() for Port or be String for HOST:PORT
3. There is no address binding even HOST is specified.
-spec listener(quicer_listener:listener_name() | {quicer_listener:listener_name(), quicer:listen_on()}) -> {ok, pid()} | {error, not_found}.
List listener with app name
-spec listeners() -> [{{quicer_listener:listener_name(), quicer:listen_on()}, pid()}].
list all listeners
-spec merge_quic_datalist([quic_data()]) -> {iolist(), Size :: non_neg_integer(), Flag :: integer()}.
-spec negotiated_protocol(Conn :: connection_handle()) -> {ok, Protocol :: binary()} | {error, Reason :: any()}.
Returns the protocol negotiated through ALPN or NPN extensions.
-spec new_fpbuffer() -> fpbuffer().
-spec new_registration(string(), registration_profile()) -> quicer_nif:new_registration().
Create a new registration.
-spec open_connection() -> {ok, connection_handle()} | {error, atom_reason()}.
-spec open_lib() -> {ok, true} | {ok, false} | {ok, debug} | {ok, fake} | {error, open_failed, atom_reason()}.
Quicer library must be opened before any use.
This is called automatically while quicer application is started
-spec peercert(connection_handle() | stream_handle()) -> {ok, cert()} | {error, any()}.
Peer Cert in DER-encoded binary mimic ssl:peername/1
-spec peername(connection_handle() | stream_handle()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, any()}.
Peer name mimic ssl:peername/1
get QUIC stack performance counters
-spec probe(connection_handle(), timeout()) -> probe_res().
Probe conn state with 0 len dgram.
-spec quic_data({quic, binary(), stream_handle(), recv_data_props()}) -> quic_data().
Convert quic data event to quic_data for fpbuffer
-spec recv(stream_handle(), Count :: non_neg_integer()) -> {ok, binary()} | {error, any()}.
Recv Data (Passive mode) Passive recv data from stream.
If Len = 0, return all data in recv buffer if it is not empty. if buffer is empty, blocking for a Quic msg from stack to arrive and return all data in that msg.
If Len > 0, desired bytes will be returned, other data would be left in recv buffer.
Suggested to use Len=0 if caller want to buffer or reassemble the data on its own.
note, the requested Len cannot exceed the 'stream_recv_window_default' specified in connection opts otherwise the function will never return
-spec reg_close() -> ok.
close Registraion. Reserved for future upgrade, don't use it.
See also: reg_open/1.
GRegistraion should be opened before calling traffic APIs.
This is called automatically when quicer application starts with app env: profile
See also: reg_close/0, reg_open/1.
-spec reg_open(execution_profile()) -> ok | {error, badarg}.
Registraion should be opened before calling traffic APIs. Registraion creates application context, worker threads shared for all the connections
Currently only support one application.
See also: reg_close/0, reg_open/1.
-spec send(stream_handle(), iodata()) -> {ok, BytesSent :: pos_integer()} | {error, cancelled} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
Send binary data over stream, blocking until send request is handled by the transport worker. either succeeded or cancelled
-spec send(stream_handle(), iodata(), non_neg_integer()) -> {ok, BytesSent :: pos_integer()} | {error, cancelled} | {error, badarg | not_enough_mem | closed} | {error, stream_send_error, atom_reason()}.
Send binary data over stream with send flags either succeeded or cancelled
-spec send_dgram(connection_handle(), binary()) -> {ok, BytesSent :: non_neg_integer()} | {error, badarg | not_enough_mem | invalid_parameter | closed} | {error, dgram_send_error, atom_reason()}.
Sending Unreliable Datagram return error only if sending could not be scheduled such as not_enough_mem, connection is already closed or wrong args. otherwise, it is fire and forget.
%% ref: https://datatracker.ietf.org/doc/html/rfc9221
See also: async_send_dgram/2, send/2.
-spec setopt(handle(), optname(), any()) -> ok | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
Set connection/stream/listener opts mimic ssl:setopt/2
-spec setopt(handle(), optname(), any(), quic_handle_level()) -> ok | {error, badarg | param_error | internal_error | not_enough_mem} | {error, atom_reason()}.
-spec shutdown_connection(connection_handle()) -> ok | {error, timeout | closed}.
Starts the shutdown process on a connection and block until it is finished.
See also: shutdown_connection/4.
-spec shutdown_connection(connection_handle(), timeout()) -> ok | {error, timeout | badarg}.
Starts the shutdown process on a connection and block until it is finished. but with a timeout
See also: shutdown_connection/4.
-spec shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno()) -> ok | {error, timeout | badarg}.
Starts the shutdown process on a connection with shutdown flag and applications error with 5s timeout
-spec shutdown_connection(connection_handle(), conn_shutdown_flag(), app_errno(), timeout()) -> ok | {error, timeout | badarg}.
Starts the shutdown process on a connection with shutdown flag and applications error with timeout
See also: shutdown_connection/1, shutdown_connection/2, shutdown_connection/3.
-spec shutdown_registration(reg_handle()) -> quicer_nif:shutdown_registration().
Shutdown a registration.
-spec shutdown_registration(reg_handle(), boolean(), uint64()) -> quicer_nif:shutdown_registration().
Shutdown a registration with error code and silent flag.
-spec shutdown_stream(stream_handle()) -> ok | {error, badarg}.
Shutdown stream gracefully, with infinity timeout
See also: shutdown_stream/1.
-spec shutdown_stream(stream_handle(), timeout()) -> ok | {error, badarg} | {error, timeout}.
Shutdown stream gracefully, with app_errno 0
returns when both endpoints closed the stream
See also: shutdown_stream/4.
-spec shutdown_stream(stream_handle(), stream_shutdown_flags(), app_errno(), timeout()) -> ok | {error, badarg} | {error, timeout}.
Start shutdown Stream process with flags and application specified error code.
returns when stream closing is confirmed in the stack (Blocking).
Flags could be used to control the behavior like half-close.
See also: async_shutdown_stream/3.
-spec sockname(listener_handle() | connection_handle() | stream_handle()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, any()}.
Get socket name mimic ssl:sockname/1
-spec spawn_listener(Appname :: atom() | listener_handle(), listen_on(), listener_opts()) -> {ok, pid()} | {error, any()}.
start a listener process under supervisor tree
-spec start_listener(listener_handle(), listen_on(), listen_opts()) -> ok | {error, any()}.
Start a stopped listener with listener handle with new Options.
-spec start_stream(connection_handle(), stream_opts()) -> {ok, stream_handle()} | {error, badarg | internal_error | bad_pid | owner_dead} | {error, stream_open_error, atom_reason()} | {error, stream_start_error, atom_reason()}.
Start new stream in connection, return new stream handle.
Calling process becomes the owner of the stream.
Both client and server could start the stream.
-spec stop_listener(listener_handle()) -> ok | {error, any()}.
Stop a started listener which could be closed or restarted later.
-spec terminate_listener(atom() | listener_handle()) -> ok.
terminate a listener process under supervisor tree
update fpbuffer and return *next* continuous data.
-spec wait_for_handoff(From :: pid(), stream_handle()) -> {error, owner_down} | {ok, PostInfo :: term()}.
Used by new stream owner to wait for stream handoff complete. Use this for handoff the orphan stream *only*.
See also: controlling_process/2, handoff_stream/3.