-spec cancel_stream_deadline(Conn, StreamId) -> ok | {error, term()}
                                when Conn :: pid(), StreamId :: non_neg_integer().

Cancel a stream deadline. Returns ok if the deadline was cancelled, or {error, not_found} if no deadline exists.

-spec close(Conn) -> ok when Conn :: pid().

Close a QUIC connection with normal reason.

-spec close(Conn, Reason) -> ok when Conn :: pid(), Reason :: non_neg_integer() | term().

Close a QUIC connection with the given reason. An integer is treated as an application error code (RFC 9000 §19.19) and sent verbatim in the CONNECTION_CLOSE frame; any other term keeps its historical pass-through behaviour.

-spec close(Conn, ErrorCode, Reason) -> ok
               when Conn :: pid(), ErrorCode :: 0..4611686018427387903, Reason :: binary().

Close a QUIC connection with application error code and reason phrase. ErrorCode is a 62-bit unsigned integer (RFC 9000). Reason is the reason phrase sent in the CONNECTION_CLOSE frame.

-spec connect(Host, Port, Opts, Owner) -> {ok, pid()} | {error, term()}
                 when
                     Host :: binary() | string(),
                     Port :: inet:port_number(),
                     Opts :: map(),
                     Owner :: pid().

Connect to a QUIC server. Returns {ok, Conn} on success where Conn is a pid(). The owner process will receive {quic, Conn, {connected, Info}} when the connection is established.

Options:

• socket - Use an existing UDP socket (gen_udp:socket())
• extra_socket_opts - Options for socket creation (e.g., [{ip, Addr}])
• verify - Verify server certificate (default: false)
• alpn - ALPN protocols (default: [<<"h3">>])
• server_name - Server Name Indication (default: Host)

-spec datagram_max_size(Conn) -> non_neg_integer() | {error, term()} when Conn :: pid().

Get maximum datagram payload size. Returns 0 if peer doesn't support datagrams (RFC 9221). The returned size is the peer's advertised max_datagram_frame_size.

-spec datagram_stats(Conn) ->
                        #{delivered := non_neg_integer(),
                          dropped_recv := non_neg_integer(),
                          sent := non_neg_integer(),
                          dropped_send := non_neg_integer()}
                        when Conn :: pid().

Get datagram accounting counters. Returns delivered / dropped_recv / sent / dropped_send counters so callers can detect back-pressure when datagram_recv_queue_len has been set to a finite value.

-spec get_fd(gen_udp:socket()) -> {ok, integer()} | {error, term()}.

Get the file descriptor from a gen_udp socket. This can be used to pass an existing UDP socket to connect/4 via the socket_fd option.

-spec get_mtu(Conn) -> {ok, pos_integer()} | {error, term()} when Conn :: pid().

Get the current MTU for a connection.

Returns the effective MTU discovered via DPLPMTUD (RFC 8899). The MTU starts at 1200 bytes (QUIC minimum) and is probed up to the peer's max_udp_payload_size or local configuration.

Returns {ok, MTU} where MTU is the current maximum packet size, or {error, not_found} if the connection doesn't exist.

-spec get_peer_transport_params(Conn) -> {ok, map()} | {error, term()} when Conn :: pid().

Get the peer's transport parameters.

Returns the transport parameters received from the peer during handshake. Useful for verifying peer capabilities such as WebTransport support (e.g., checking for reset_stream_at transport parameter).

Returns {ok, TransportParams} where TransportParams is a map of the peer's advertised transport parameters.

-spec get_send_queue_info(Conn) -> {ok, send_queue_info()} | {error, term()} when Conn :: pid().

Get send queue information for a connection. This can be used by distribution controllers or other high-level protocols to implement backpressure based on queue state.

Returns a map with: - bytes: Current bytes in send queue - cwnd: Congestion window size - in_flight: Bytes sent but not acknowledged - in_recovery: Whether in congestion recovery - congested: Whether backpressure should be applied

See quic_dist_controller for usage example.

-spec get_server_connections(Name) -> {ok, [pid()]} | {error, not_found} when Name :: atom().

Get the list of connection PIDs for a named server.

-spec get_server_info(Name) -> {ok, map()} | {error, not_found} when Name :: atom().

Get information about a named server.

Returns a map containing:

• pid - Server supervisor PID
• port - Listening port
• opts - Server options
• started_at - Start timestamp in milliseconds

-spec get_server_port(Name) -> {ok, inet:port_number()} | {error, not_found} when Name :: atom().

Get the listening port of a named server.

Useful when the server was started with port 0 (ephemeral port).

-spec get_stats(Conn) -> {ok, map()} | {error, term()} when Conn :: pid().

Get connection statistics for liveness detection.

Returns packet counts that can be used by net_kernel for tick checking. Any QUIC packet (ACK, PING, data) counts as proof of peer liveness.

Returns a map with: - packets_received: Total QUIC packets successfully received - packets_sent: Total QUIC packets sent - data_received: Total bytes of application data received - data_sent: Total bytes of application data sent

See quic_dist_controller for usage in distribution tick checking.

-spec get_stream_deadline(Conn, StreamId) ->
                             {ok, {non_neg_integer() | infinity, reset | notify | both}} |
                             {error, term()}
                             when Conn :: pid(), StreamId :: non_neg_integer().

Get the remaining time for a stream deadline. Returns {ok, {RemainingMs, Action}} where RemainingMs is milliseconds until expiry. Returns {error, no_deadline} if no deadline is set.

-spec get_stream_priority(Conn, StreamId) -> {ok, {0..7, boolean()}} | {error, term()}
                             when Conn :: pid(), StreamId :: non_neg_integer().

Get the priority for a stream. Returns {ok, {Urgency, Incremental}} or {error, not_found}.

-spec handle_timeout(Conn, NowMs) -> non_neg_integer() | infinity
                        when Conn :: pid(), NowMs :: non_neg_integer().

Handle connection timeout. Should be called when timer expires. Returns next timeout in ms or 'infinity'.

-spec is_available() -> boolean().

Check if QUIC support is available. Always returns true for pure Erlang implementation.

-spec migrate(Conn) -> ok | {error, term()} when Conn :: pid().

Trigger connection migration to a new local address. This initiates path validation on a new network path. The connection will send PATH_CHALLENGE and wait for PATH_RESPONSE.

-spec migrate(Conn, Opts) -> ok | {error, term()}
                 when Conn :: pid(), Opts :: #{timeout => pos_integer()}.

Trigger connection migration with options. This initiates path validation on a new network path. The connection will send PATH_CHALLENGE and wait for PATH_RESPONSE.

Options:

• timeout - Timeout in milliseconds for the gen_statem call (default: 5000)

-spec open_stream(Conn) -> {ok, non_neg_integer()} | {error, term()} when Conn :: pid().

Open a new bidirectional stream. Returns {ok, StreamId} on success.

-spec open_unidirectional_stream(Conn) -> {ok, non_neg_integer()} | {error, term()} when Conn :: pid().

Open a new unidirectional stream. Returns {ok, StreamId} on success. Unidirectional streams are send-only for the initiator.

-spec peercert(Conn) -> {ok, binary()} | {error, term()} when Conn :: pid().

Get the peer certificate. Returns the DER-encoded certificate of the peer if available.

-spec peername(Conn) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}
                  when Conn :: pid().

Get the remote address of the connection.

-spec process(Conn) -> ok when Conn :: pid().

Process pending QUIC events. This is called automatically by the connection process.

-spec reset_stream(Conn, StreamId, ErrorCode) -> ok | {error, term()}
                      when Conn :: pid(), StreamId :: non_neg_integer(), ErrorCode :: non_neg_integer().

Reset a stream with an error code.

-spec reset_stream_at(Conn, StreamId, ErrorCode, ReliableSize) -> ok | {error, term()}
                         when
                             Conn :: pid(),
                             StreamId :: non_neg_integer(),
                             ErrorCode :: non_neg_integer(),
                             ReliableSize :: non_neg_integer().

Reset a stream with reliable delivery up to specified size. Data up to ReliableSize will be delivered before the reset takes effect. Requires peer support for the reliable stream reset extension (draft-ietf-quic-reliable-stream-reset-07). ReliableSize must be less than or equal to the amount of data already sent.

-spec send_data(Conn, StreamId, Data, Fin) -> ok | {error, term()}
                   when Conn :: pid(), StreamId :: non_neg_integer(), Data :: iodata(), Fin :: boolean().

Send data on a stream. Fin indicates if this is the final frame on the stream.

-spec send_data(Conn, StreamId, Data, Fin, Timeout) -> ok | {error, term()}
                   when
                       Conn :: pid(),
                       StreamId :: non_neg_integer(),
                       Data :: iodata(),
                       Fin :: boolean(),
                       Timeout :: timeout().

Send data on a stream with a timeout. Fin indicates if this is the final frame on the stream. Timeout is in milliseconds; if the operation takes longer, returns {error, timeout}.

-spec send_data_async(Conn, StreamId, Data, Fin) -> ok
                         when
                             Conn :: pid(),
                             StreamId :: non_neg_integer(),
                             Data :: iodata(),
                             Fin :: boolean().

Send data on a stream asynchronously (fire-and-forget). This is faster than send_data/4 because it uses cast instead of call, avoiding the round-trip latency. However, errors are silently dropped. Use this for high-throughput scenarios where occasional dropped data is acceptable.

-spec send_datagram(Conn, Data) -> ok | {error, term()} when Conn :: pid(), Data :: iodata().

Send a datagram on the connection. Datagrams are unreliable and may be lost.

-spec send_ping(Conn) -> ok | {error, term()} when Conn :: pid().

Send a PING frame on the connection.

PING frames are transport-level frames that bypass congestion control. They elicit an ACK from the peer and can be used for liveness checking. This is useful for distribution tick messages that must get through even when the connection is congested.

Returns ok if the PING was sent, or {error, Reason} if it failed.

-spec server_spec(Name, Port, Opts) -> supervisor:child_spec()
                     when Name :: atom(), Port :: inet:port_number(), Opts :: map().

Return a child spec for embedding a QUIC server in your own supervisor.

This allows you to supervise QUIC servers within your application's supervision tree instead of using the built-in server management.

Example:

  init([]) ->
      Spec = quic:server_spec(my_quic, 4433, #{
          cert => CertDer,
          key => KeyTerm,
          alpn => [<<"h3">>]
      }),
      {ok, {#{strategy => one_for_one}, [Spec]}}.

-spec set_congestion_control(Conn, Algorithm) -> ok | {error, term()}
                                when Conn :: pid(), Algorithm :: newreno | bbr | cubic.

Set the congestion control algorithm for a connection. This changes the algorithm on a live connection. The new algorithm starts fresh (cwnd, ssthresh reset to defaults). Only works in connected state.

Algorithm: newreno | bbr | cubic

-spec set_owner(Conn, NewOwner) -> ok | {error, term()} when Conn :: pid(), NewOwner :: pid().

Set the owner process for a connection. Similar to gen_tcp:controlling_process/2.

-spec set_owner_sync(Conn, NewOwner) -> ok | {error, term()} when Conn :: pid(), NewOwner :: pid().

Set the owner process for a connection (synchronous). Use this when you need to ensure ownership is transferred before continuing.

-spec set_stream_deadline(Conn, StreamId, TimeoutMs) -> ok | {error, term()}
                             when
                                 Conn :: pid(),
                                 StreamId :: non_neg_integer(),
                                 TimeoutMs :: pos_integer().

Set a deadline for a stream. TimeoutMs is the number of milliseconds from now until the deadline expires. When the deadline expires, the stream will be reset and/or the owner will be notified. Default action is 'both' (notify + reset).

-spec set_stream_deadline(Conn, StreamId, TimeoutMs, Opts) -> ok | {error, term()}
                             when
                                 Conn :: pid(),
                                 StreamId :: non_neg_integer(),
                                 TimeoutMs :: pos_integer(),
                                 Opts ::
                                     #{action => reset | notify | both, error_code => non_neg_integer()}.

Set a deadline for a stream with options. TimeoutMs is the number of milliseconds from now until the deadline expires.

Options: - action: What to do when deadline expires: - notify: Send {quic, Conn, {stream_deadline, StreamId}} to owner - reset: Send RESET_STREAM and clean up - both (default): Notify AND reset - error_code: Error code for RESET_STREAM (default: 16#FF)

-spec set_stream_priority(Conn, StreamId, Urgency, Incremental) -> ok | {error, term()}
                             when
                                 Conn :: pid(),
                                 StreamId :: non_neg_integer(),
                                 Urgency :: 0..7,
                                 Incremental :: boolean().

Set the priority for a stream. Urgency: 0-7 (lower = more urgent, default 3) Incremental: boolean (data can be processed incrementally, default false) Per RFC 9218 (Extensible Priorities for HTTP).

-spec setopts(Conn, Opts) -> ok | {error, term()} when Conn :: pid(), Opts :: [{atom(), term()}].

Set connection options.

-spec sockname(Conn) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}
                  when Conn :: pid().

Get the local address of the connection.

-spec start_server(Name, Port, Opts) -> {ok, pid()} | {error, term()}
                      when Name :: atom(), Port :: inet:port_number(), Opts :: map().

Start a named QUIC server on the specified port.

Creates a listener pool that accepts incoming QUIC connections. Multiple named servers can run on different ports.

Options:

• cert - DER-encoded certificate (required)
• key - Private key term (required)
• alpn - List of ALPN protocols (default: [<<"h3">>])
• pool_size - Number of listener processes (default: 1)
• connection_handler - Fun(Conn) -> {ok, HandlerPid} where Conn is the pid

Example:

  {ok, _} = quic:start_server(my_server, 4433, #{
      cert => CertDer,
      key => KeyTerm,
      alpn => [<<"h3">>],
      pool_size => 4
  }).

-spec stop_sending(Conn, StreamId, ErrorCode) -> ok | {error, term()}
                      when Conn :: pid(), StreamId :: non_neg_integer(), ErrorCode :: non_neg_integer().

Request peer to stop sending on a stream. Sends a STOP_SENDING frame (RFC 9000 Section 19.5).

-spec stop_server(Name) -> ok | {error, term()} when Name :: atom().

Stop a named QUIC server.

Stops the server and all its connections. The port will be freed for reuse.

-spec which_servers() -> [atom()].

List all running server names.