# `Quiver.Conn.HTTP3`
[🔗](https://github.com/edlontech/quiver/blob/main/lib/quiver/conn/http3.ex#L1)

HTTP/3 connection wrapper.

Holds a `quic_h3` pid plus per-stream tracking. Implements `Quiver.Conn`
by delegating to `:quic_h3` calls. Not a process itself; the calling
process is the H3 connection's owner.

Used standalone (synchronous connect) or by `Quiver.Pool.HTTP3.Connection`
(which manages an async-connect worker and only uses `open_request`,
`stream`, `cancel`, `close`).

# `t`

```elixir
@type t() :: %Quiver.Conn.HTTP3{
  h3_conn: pid() | nil,
  host: String.t(),
  peer_max_streams: non_neg_integer(),
  port: :inet.port_number(),
  recv_timeout: timeout(),
  ref_to_stream_id: %{required(reference()) => non_neg_integer()},
  scheme: :https,
  stream_id_to_ref: %{required(non_neg_integer()) => reference()}
}
```

# `build_headers`

```elixir
@spec build_headers(
  atom(),
  String.t(),
  Quiver.Conn.headers(),
  {atom(), String.t(), :inet.port_number()},
  keyword()
) :: {:ok, [{binary(), binary()}]} | {:error, term()}
```

Builds the HTTP/3 header list for a request: pseudo-headers in the
required order followed by user headers (lowercased). Rejects
connection-specific headers forbidden by RFC 9114 §4.2.

The origin is a `{scheme, host, port}` tuple. Authority omits the
default port for the scheme (`443` for `:https`, `80` for `:http`).

Pseudo-header order: `:method, :protocol?, :scheme, :path, :authority`.
The `:protocol` pseudo-header (RFC 8441 / 9220) is emitted only when a
non-nil `:protocol` opt is provided — typically with `method == :connect`
for extended CONNECT (WebTransport, Connect-UDP, MASQUE).

# `query_peer_max_streams`

```elixir
@spec query_peer_max_streams(pid(), non_neg_integer()) :: non_neg_integer()
```

Returns the peer's advertised initial-max-streams-bidi limit, falling
back to the supplied integer if the underlying `:quic` runtime does
not expose `get_peer_transport_params/1` (older versions).

# `resolve_candidates`

```elixir
@spec resolve_candidates(String.t()) :: [:inet.ip_address()]
```

Resolves a host to at most one address per family, IPv6 first (RFC 8305 §4
preference), for the direct-connect path. A literal IP is returned as-is.
Shared with `Quiver.Pool.HTTP3.Connection`.

# `to_h3_headers`

```elixir
@spec to_h3_headers(atom(), String.t(), Quiver.Conn.headers(), t()) ::
  {:ok, [{binary(), binary()}]} | {:error, term()}
```

Backwards-compatible wrapper around `build_headers/4` for a
`%Quiver.Conn.HTTP3{}` struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*