API reference¶
The whole public surface of zttp. It's small on purpose. Everything here is
importable straight from zttp (e.g. from zttp import Connection).
Connection¶
zttp.Connection is a factory. Constructing one returns the subtype for the
protocol you picked - an H1Connection (the default), an H2Connection, or an
H3Connection - so the surface you get matches the wire. Connection itself
isn't a usable instance type and can't be subclassed; only next_event() is
common to all three, because the read/write byte surface is transport-specific
(HTTP/1.1 and HTTP/2 read receive_data; HTTP/3 reads receive_datagram).
A factory for a protocol-specific connection, and the shared read API.
Constructing a Connection returns the subtype for the protocol you pick -
H1Connection (the default), H2Connection, or H3Connection - so the send
surface matches the wire. Connection itself is not instantiable directly and
cannot be subclassed; only next_event() is common to every transport, since
the read/write byte surface is transport-specific (HTTP/1.1 and HTTP/2 are
byte streams; HTTP/3 rides UDP datagrams).
Return the next parse event, or the NEED_DATA sentinel if more bytes are needed.
Bases: Connection
An HTTP/1.1 connection: a byte-stream transport with a message-scoped API.
Return the next parse event, or the NEED_DATA sentinel if more bytes are needed.
Append received bytes to the parse buffer (empty bytes signals EOF).
Serialize a request head (client role).
Serialize a response head; the reason phrase is derived from status and the version is 1.1.
Serialize an interim 1xx response; the real response still follows.
Serialize a run of body bytes (chunk-framed if the head declared chunked).
End the outgoing message, with optional trailers (chunked bodies only).
Whether the connection must close after this message (Connection: close / HTTP/1.0).
The request's Upgrade token if it asked to upgrade (Connection: upgrade), else None.
Bases: Connection
An HTTP/2 connection: many streams multiplexed over one byte stream.
Attributes:
| Name | Type | Description |
|---|---|---|
send_window |
int
|
The connection-level send window in bytes (may go negative
after a |
Return the next parse event, or the NEED_DATA sentinel if more bytes are needed.
Append received bytes to the parse buffer (empty bytes signals EOF).
Emit the connection preface (client preface + SETTINGS, or the server's SETTINGS) now.
Open a request stream and return its Stream (client role).
Seed an h2c-upgraded connection: replay the parsed HTTP/1.1 request as stream 1.
Return the Stream handle for stream_id - the send surface for that stream.
Whether any stream still has body bytes (or a FIN) parked for the send window.
Bases: Connection
An HTTP/3 connection: the same streams over a from-scratch QUIC transport.
Fed UDP datagrams with receive_datagram rather than a byte stream, and
data_to_send() returns a datagram per element (QUIC datagram boundaries are
semantic). Responses go through a Stream handle, exactly as on HTTP/2. Server
credentials default to an ephemeral local identity; now is the integrator's
monotonic clock, in the unit later fed to handle_timeout.
Return the next parse event, or the NEED_DATA sentinel if more bytes are needed.
Return and clear the pending outgoing UDP datagrams, one per list element.
Feed one received UDP datagram. peer_address is an opaque key for path validation.
Like data_to_send, but as (datagram, peer_address) pairs.
Queue a QUIC PATH_CHALLENGE to a peer address (data must be 8 unpredictable bytes).
Switch outgoing packets to a peer-issued NEW_CONNECTION_ID sequence.
Queue a QUIC NEW_CONNECTION_ID for a local connection ID.
Advance the QUIC 1-RTT send keys; the next packet carries the new key phase.
Open the control stream and send SETTINGS now, rather than lazily on the first response.
Open a request stream and return its Stream (client role).
send_session_ticket(ticket, lifetime=..., age_add=..., nonce=..., extensions=..., max_early_data_size=...)
Queue a TLS NewSessionTicket on a confirmed server connection; returns its PSK when available.
Queue a QUIC NEW_TOKEN address-validation token (server role).
The TLS session tickets received from the peer, as SessionTickets.
The NEW_TOKEN address-validation tokens received, for reuse on a future connection.
Send a QUIC CONNECTION_CLOSE. app=True sends an HTTP/3 application close.
The next idle/loss/PTO deadline (same clock as now), or None if no timer is armed.
Fire the timer at time now: close on idle timeout, or re-queue loss probes.
Whether the connection was silently closed by the idle timeout (RFC 9000 10.1).
The peer's HTTP/3 SETTINGS as a dict, or None until its SETTINGS frame arrives.
The id of a GOAWAY received from the peer (RFC 9114 5.2), or None.
A Stream is the per-stream send handle on HTTP/2 and HTTP/3 connections; see
HTTP/2 and HTTP/3.
A borrowed, re-validated handle to one stream - the single send surface for
HTTP/2 and HTTP/3. Obtained via conn.stream(stream_id).
Attributes:
| Name | Type | Description |
|---|---|---|
stream_id |
int
|
The stream this handle sends on. |
send_window |
int | None
|
The stream's remaining send window in bytes, or |
pending_bytes |
int | None
|
Body bytes parked waiting for flow-control credit, or |
Roles and protocols¶
A Connection's role and protocol are fixed at construction:
zttp.SERVER: you receive requests, send responses.zttp.CLIENT: you send requests, receive responses.zttp.HTTP1(default): one message at a time; you send on the connection.zttp.HTTP2: multiplexed streams; you send on aStream.zttp.HTTP3: the same streams over QUIC; you feed UDP datagrams withreceive_datagram(see HTTP/3).
For HTTP/3, a server's TLS identity is passed as
credentials=TlsCredentials(...) and a resumption secret
as resumption=SessionResumption(...) - typed value
objects, so the same-typed bytes pairs can't be transposed (omit credentials
and the server uses an ephemeral local identity). zttp supplies the QUIC
transport defaults internally; the remaining constructor fields
(transport_params, connection_id, random, ephemeral_seed, ...) are
advanced overrides for deterministic tests and interoperability work.
HTTP/3 value objects¶
Passed to the HTTP/3 constructor; both are keyword-only frozen dataclasses so the
same-typed bytes fields can't be swapped.
dataclass
¶
dataclass
¶
Events¶
next_event returns one of these. On HTTP/2 and
HTTP/3 each also carries a .stream_id.
A parsed request head: the request line and all headers.
Yielded by next_event() on a server connection once the head is complete,
before any body Data. Every value is raw bytes, exactly as received - zttp
does not percent-decode the target.
Attributes:
| Name | Type | Description |
|---|---|---|
method |
bytes
|
The request method, e.g. |
target |
bytes
|
The raw request-target, e.g. |
path |
bytes
|
|
query |
bytes
|
|
http_version |
bytes
|
The version, e.g. |
headers |
list[tuple[bytes, bytes]]
|
The header fields as |
stream_id |
int
|
The stream the request arrived on ( |
expect_continue |
bool
|
Whether the client sent |
A parsed response head: the status line and all headers.
Yielded by next_event() on a client connection once the head is complete,
before any body Data.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
int
|
The status code, e.g. |
reason |
bytes
|
The reason phrase, e.g. |
http_version |
bytes
|
The version, e.g. |
headers |
list[tuple[bytes, bytes]]
|
The header fields as |
stream_id |
int
|
The stream the response arrived on ( |
A run of decoded body bytes.
One or more Data events arrive between the head and EndOfMessage; chunked
and content-length bodies both surface the same way, already decoded.
Attributes:
| Name | Type | Description |
|---|---|---|
data |
bytes
|
The body bytes, copied out of the parse buffer (safe to keep). |
stream_id |
int
|
The stream the body belongs to ( |
HTTP/2 control events¶
An HTTP/2 connection also surfaces the protocol's control frames. zttp acts on the ones that matter on its own; they're here when you want visibility.
An HTTP/2 SETTINGS frame from the peer. zttp acks it for you.
Attributes:
| Name | Type | Description |
|---|---|---|
params |
list[tuple[int, int]]
|
The settings as |
An HTTP/2 RST_STREAM: the peer abruptly cancelled a stream.
Attributes:
| Name | Type | Description |
|---|---|---|
stream_id |
int
|
The cancelled stream. |
error_code |
int
|
The RFC 9113 error code the peer sent. |
An HTTP/2 GOAWAY: the peer is shutting the connection down.
Attributes:
| Name | Type | Description |
|---|---|---|
last_stream_id |
int
|
The highest stream the peer will still process. |
error_code |
int
|
The RFC 9113 error code. |
debug |
bytes
|
Optional opaque debug data, or |
The integer ids in a Settings event's params have names (RFC 9113 6.5.2):
Bases: IntEnum
The HTTP/2 SETTINGS parameter identifiers (RFC 9113 6.5.2).
Names the integer ids carried in a Settings event's params,
so they can be read without magic numbers.
HTTP/3 results¶
Returned by an H3Connection's introspection methods.
dataclass
¶
A TLS session ticket received from the peer (RFC 8446 4.6.1).
dataclass
¶
Sentinels¶
| Value | Meaning |
|---|---|
zttp.NEED_DATA |
No complete event yet; feed more bytes. Compare with is. |
zttp.CONNECTION_CLOSED |
The peer closed the connection. Compare with is. |
Exceptions¶
Bases: Exception
Base class for the two protocol errors. Catch this to handle both.
Bases: ProtocolError
The peer sent something malformed. Raised from next_event().
Bases: ProtocolError
You used the send API in a way that cannot produce a valid message.