Quic (elixir_quic v1.0.0-rc.9)

Copy Markdown View Source

Certificate-based QUIC v1 reliable streams with bounded pull consumption.

See docs/consumer-contract.md for ownership, generation handles, deadlines, admission outcomes and limitations. ALPN is metadata; application protocols are provided by consumers.

Endpoints created with listen/1 or client/1 accept idle_timeout as positive milliseconds (default 30_000) or :infinity. The latter advertises a disabled local idle limit; both endpoints must disable their limits to avoid a finite idle timer. A peer's finite limit still applies. Handshake, operation, closing and draining deadlines remain finite. info/1 and ready metadata expose idle_timeout with local_ms, peer_ms, negotiated_ms, and effective_ms (milliseconds or :infinity); the effective period includes a three-PTO floor. Callers can use ping/2 at a finite cadence below the peer limit. Admission is not a peer ACK, and repeated sends without processing peer packets cannot postpone local idle expiry indefinitely. No automatic keepalive task is created.

Summary

Types

failure()
operation_options()

Functions

accept(endpoint, timeout_or_opts \\ 5000)
attach(connection_handle, consumer, opts \\ [])
capabilities()
client(opts)
close(connection_handle, code \\ 0, reason \\ <<>>, opts \\ [])
connect(endpoint, remote, opts \\ [])
events(connection_handle, max \\ 32, opts \\ [])
info(connection_handle)
listen(opts)
local(endpoint)
open_stream(connection_handle, kind, opts \\ [])
operation_status(endpoint, ref)
ping(connection_handle, opts \\ [])

Admit one QUIC PING for caller-managed keepalive.

read(stream_handle, max, opts \\ [])
read_datagrams(connection_handle, max \\ 32, opts \\ [])
ready(connection_handle)
reset_stream(stream_handle, code, opts \\ [])
send_datagram(connection_handle, data, opts \\ [])
send_stream(stream_handle, data, fin \\ false, opts \\ [])
stop_stream(stream_handle, code, opts \\ [])

Types

failure()

@type failure() :: {:error, term()} | {:blocked, term()} | {:unknown, reference()}

operation_options()

@type operation_options() :: keyword()

Functions

accept(endpoint, timeout_or_opts \\ 5000)

@spec accept(pid(), non_neg_integer() | operation_options()) ::
  {:ok, Quic.Runtime.ConnectionHandle.t()} | failure()

attach(connection_handle, consumer, opts \\ [])

@spec attach(Quic.Runtime.ConnectionHandle.t(), pid(), keyword()) :: :ok | failure()

capabilities()

@spec capabilities() :: %{
  datagram: true,
  delivery: :pull,
  http3: false,
  io: [:external | :standalone, ...],
  max_write_bytes: 16384,
  migration: %{peer: [:server, ...], local: []},
  resumption: false,
  streams: [:bidi | :uni, ...],
  version: 1
}

client(opts)

@spec client(keyword()) :: GenServer.on_start()

close(connection_handle, code \\ 0, reason \\ <<>>, opts \\ [])

@spec close(
  Quic.Runtime.ConnectionHandle.t(),
  non_neg_integer(),
  binary(),
  operation_options()
) ::
  :ok | failure()

connect(endpoint, remote, opts \\ [])

@spec connect(pid(), {:inet.ip_address(), :inet.port_number()}, operation_options()) ::
  {:ok, Quic.Runtime.ConnectionHandle.t()} | failure()

events(connection_handle, max \\ 32, opts \\ [])

@spec events(Quic.Runtime.ConnectionHandle.t(), pos_integer(), operation_options()) ::
  {:ok, list()} | failure()

info(connection_handle)

@spec info(Quic.Runtime.ConnectionHandle.t()) :: {:ok, map()} | failure()

listen(opts)

@spec listen(keyword()) :: GenServer.on_start()

local(endpoint)

@spec local(pid()) :: {:inet.ip_address(), :inet.port_number()} | {:error, term()}

open_stream(connection_handle, kind, opts \\ [])

@spec open_stream(
  Quic.Runtime.ConnectionHandle.t(),
  :bidi | :uni,
  operation_options()
) ::
  {:ok, Quic.Runtime.StreamHandle.t()} | failure()

operation_status(endpoint, ref)

@spec operation_status(Quic.Runtime.ConnectionHandle.t() | pid(), reference()) ::
  map() | :unknown | failure()

ping(connection_handle, opts \\ [])

@spec ping(Quic.Runtime.ConnectionHandle.t(), operation_options()) ::
  {:ok, reference()} | failure()

Admit one QUIC PING for caller-managed keepalive.

Uses the same finite operation deadlines, deduplication, bounded send queue and recovery as stream sends. {:ok, ref} reports admission, not peer receipt or ACK. Choose a finite cadence below the peer's advertised idle limit, available in info/1. Sending without successfully processing peer packets cannot postpone local idle expiry indefinitely. No periodic task or timer is created.

read(stream_handle, max, opts \\ [])

@spec read(Quic.Runtime.StreamHandle.t(), pos_integer(), operation_options()) ::
  {:ok, list()} | failure()

read_datagrams(connection_handle, max \\ 32, opts \\ [])

@spec read_datagrams(
  Quic.Runtime.ConnectionHandle.t(),
  pos_integer(),
  operation_options()
) ::
  {:ok, [binary()]} | failure()

ready(connection_handle)

@spec ready(Quic.Runtime.ConnectionHandle.t()) :: :ready | :pending | failure()

reset_stream(stream_handle, code, opts \\ [])

@spec reset_stream(
  Quic.Runtime.StreamHandle.t(),
  non_neg_integer(),
  operation_options()
) ::
  {:ok, reference()} | failure()

send_datagram(connection_handle, data, opts \\ [])

@spec send_datagram(Quic.Runtime.ConnectionHandle.t(), binary(), operation_options()) ::
  {:ok, reference()} | failure()

send_stream(stream_handle, data, fin \\ false, opts \\ [])

@spec send_stream(
  Quic.Runtime.StreamHandle.t(),
  binary(),
  boolean(),
  operation_options()
) ::
  {:ok, reference()} | failure()

stop_stream(stream_handle, code, opts \\ [])

@spec stop_stream(
  Quic.Runtime.StreamHandle.t(),
  non_neg_integer(),
  operation_options()
) ::
  {:ok, reference()} | failure()