# _base URL: /pounce/api/protocols/_base/ Section: protocols Description: 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. --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/protocols/_base/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fprotocols%2F_base%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fprotocols%2F_base%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fprotocols%2F_base%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fprotocols%2F_base%2Findex.txt) 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` 5 ▼ Sans-I/O contract for HTTP/1.1 wire protocol handlers. Defines the request-response cycle interfac… Bases: `Protocol` Sans-I/O contract for HTTP/1.1 wire protocol handlers. Defines the request-response cycle interface: parse inbound bytes via`receive_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` (/pounce/api/protocols/h2/#H2Connection)) and WebSocket (`WSProtocol` (/pounce/api/protocols/ws/#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.py`respectively. #### 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_informational` 2 `bytes` ▼ Serialize a 1xx informational response (e.g. 103 Early Hints). Informational r… `def send_informational(self, status: int, headers: list[tuple[bytes, bytes]]) -> bytes` Serialize a 1xx informational response (e.g. 103 Early Hints). Informational responses do not terminate the request-response cycle, so the final response is still serialized and sent afterwards. ##### Parameters Name Type Description `status` `—` 1xx 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.