Module

protocols._base

Protocol contracts — event types and handler interface.

Defines the structural interface that all protocol handlers (H1, H2, WS) must conform to, and the typed events they produce. The worker layer interacts with any protocol handler through this interface without knowing which wire protocol is active.

Sans-I/O: protocol handlers consume bytes and produce bytes. No socket access, no asyncio imports. The worker feeds data in and reads data out.

8Classes

Classes

RequestReceived 4 ▼
A complete HTTP request head has been parsed.

A complete HTTP request head has been parsed.

Attributes

Name Type Description
method bytes

HTTP method as bytes (e.g., b"GET").
target bytes

Request target as bytes (e.g., b"/api/users?page=1").
headers tuple[tuple[bytes, bytes], ...]

Header pairs as a tuple of (name, value) byte pairs.
http_version str

HTTP version string (e.g., "1.1").
BodyReceived 2 ▼
A chunk of request body data.

A chunk of request body data.

Attributes

Name Type Description
data bytes

The body bytes for this chunk.
more bool

True if more body chunks are expected.
ConnectionClosed 1 ▼
The connection has been closed by the client or due to an error.

The connection has been closed by the client or due to an error.

Attributes

Name Type Description
reason str

Human-readable reason for the closure.
Upgraded 1 ▼
The connection has been upgraded to a different protocol.

The connection has been upgraded to a different protocol.

Attributes

Name Type Description
protocol str

The protocol being upgraded to (e.g., "websocket", "h2c").
WebSocketConnected 1 ▼
WebSocket handshake completed successfully.

WebSocket handshake completed successfully.

Attributes

Name Type Description
subprotocol str | None

The negotiated subprotocol (if any).
WebSocketDataReceived 1 ▼
A WebSocket data frame has been received.

A WebSocket data frame has been received.

Attributes

Name Type Description
data bytes | str

The message payload (bytes for binary, str for text).
WebSocketDisconnected 2 ▼
The WebSocket connection has been closed.

The WebSocket connection has been closed.

Attributes

Name Type Description
code int

The WebSocket close status code.
reason str

Human-readable reason for the closure.
ProtocolHandler 4 ▼
Sans-I/O contract for HTTP/1.1 wire protocol handlers. Defines the request-response cycle interfac…

Sans-I/O contract for HTTP/1.1 wire protocol handlers.

Defines the request-response cycle interface: parse inbound bytes viareceive_data(), serialize outbound responses via send_response() and send_body(), and reset via start_new_cycle()for keep-alive connections.

Implementations:

  • H1Protocol (h11) — pure Python HTTP/1.1
  • H1HttpToolsProtocol (httptools) — C-accelerated HTTP/1.1

Note: HTTP/2 (H2Connection) and WebSocket (WSProtocol) have fundamentally different interfaces (stream IDs, message framing) and do not implement this Protocol. They have their own APIs in protocols/h2.py and protocols/ws.pyrespectively.

Methods

receive_data 1 list[ProtocolEvent] ▼
Feed raw bytes from the socket, return parsed protocol events.
def receive_data(self, data: bytes) -> list[ProtocolEvent]
Parameters
Name Type Description
data —

Raw bytes received from the network.
Returns
list[ProtocolEvent] List of protocol events parsed from the input.
send_response 2 bytes ▼
Serialize a response start (status + headers) into bytes.
def send_response(self, status: int, headers: list[tuple[bytes, bytes]]) -> bytes
Parameters
Name Type Description
status —

HTTP status code.
headers —

Response headers as (name, value) byte pairs.
Returns
bytes Serialized bytes to write to the socket.
send_body 2 bytes ▼
Serialize a response body chunk into bytes.
def send_body(self, data: bytes, more: bool = False) -> bytes
Parameters
Name Type Description
data —

Body bytes to send.
more —

True if more body chunks will follow.

Default:False
Returns
bytes Serialized bytes to write to the socket.
start_new_cycle 0 ▼
Reset the protocol handler for a new request on keep-alive. Called after a com…
def start_new_cycle(self) -> None

Reset the protocol handler for a new request on keep-alive.

Called after a complete request-response cycle to prepare for the next request on the same connection.