`http.h2.connection`

import http.h2.connection

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.h2.connection.* needs import http.h2.connection.

One HTTP/2 connection and the streams multiplexed over it.

Http2Connection owns the connection-level state: the settings exchange, flow-control windows, and the HPACK contexts shared by every stream. Http2Stream is one request/response pair within it, and Http2Writer serialises frames so that concurrent streams cannot interleave mid-frame.

Classes

`Http2Stream`

class http.h2.Http2Stream

One HTTP/2 stream: a request and its response, multiplexed with others over a single connection.

Fields

Field	Type	Description
`id`	`int`	The stream identifier.
`fields`	`list`	The decoded header fields, in the order they arrived.
`data`	`bytes`	The request or response body received so far.
`ended`	`bool`	Whether the peer has finished sending on this stream.
`headers_done`	`bool`	Whether the header block is complete - that is, whether an END_HEADERS flag has been seen.
`closed`	`bool`	Whether this endpoint has finished sending on this stream.
`send_window`	`number`	How many bytes may still be sent on this stream before the peer has to grant more.
`consumed`	`number`	How much of this stream’s receive window has been consumed since the last WINDOW_UPDATE.
`trailers`	`list`	The trailer fields, if any arrived after the body.
`fragment`

Constructor

http.h2.Http2Stream(id, send_window)

`Http2Connection`

class http.h2.Http2Connection

An HTTP/2 connection, in either role.

On the server side, serve() reads the preface, exchanges settings, and then runs the frame loop, handing each completed request to the HttpServer it was given and writing the response back. On the client side, start_client() performs the same handshake and send_request()/await_response() carry one exchange.

Streams are multiplexed on the wire but handled in the order they complete: this is one thread reading one socket, so a request that arrives while another is being handled is read, buffered, and answered next rather than in parallel. That is a throughput property, not a correctness one - the framing, flow control and header state are all maintained exactly as the protocol requires.

Fields

Field	Type	Description
`is_server`	`bool`	Whether this endpoint is the server.
`max_body_size`	`number`	The largest request body accepted on one stream, in bytes.

Constructor

http.h2.Http2Connection(connection, is_server: bool)

Parameters

connection (Connection) — the transport, already connected and (for h2) already through its TLS handshake
is_server (bool)

`Http2Connection.start_server()`

http.h2.Http2Connection.start_server(already_read)

Reads the client connection preface and sends this endpoint’s SETTINGS. Server side.

Parameters

already_read (?bytes) — preface bytes a caller consumed while working out which protocol this was

Raises ProtocolError if the preface is not what HTTP/2 requires

`Http2Connection.start_client()`

http.h2.Http2Connection.start_client()

Sends the client connection preface and this endpoint’s SETTINGS. Client side.

`Http2Connection.serve()`

http.h2.Http2Connection.serve(server)

Runs the connection until the peer goes away, handing every completed request to server.

Parameters

server (HttpServer)

`Http2Connection.send_data()`

http.h2.Http2Connection.send_data(stream, data, end_stream)

Sends data on stream as DATA frames, respecting both the stream’s and the connection’s send windows and the peer’s maximum frame size.

When a window is exhausted this reads frames until the peer grants more, which is what makes flow control actually work rather than simply be accounted for.

Parameters

stream (Http2Stream)
data (bytes)
end_stream (bool)

`Http2Connection.send_request()`

http.h2.Http2Connection.send_request(request, payload) -> Http2Stream

Opens a stream and sends request on it. Client side.

Parameters

request (HttpRequest)
payload (?bytes) — the request body

Returns Http2Stream

`Http2Connection.await_response()`

http.h2.Http2Connection.await_response(stream, request) -> HttpResponse

Reads frames until stream is finished and returns the response it carried. Client side.

Parameters

stream (Http2Stream)
request (HttpRequest)

Returns HttpResponse

Raises ProtocolError if the response is malformed

Raises ConnectionError if the connection ends first

`Http2Connection.is_usable()`

http.h2.Http2Connection.is_usable() -> bool

Whether the connection is still usable for another request.

Returns bool

`Http2Connection.close()`

http.h2.Http2Connection.close(error_code)

Sends GOAWAY and closes the transport.

Parameters

error_code (?int) — defaults to NO_ERROR

`Http2Writer`

class http.h2.Http2Writer

The writer a streaming response body gets on an HTTP/2 connection. Same shape as the HTTP/1.1 one, so a handler never has to know which version it is answering.

Constructor

http.h2.Http2Writer(connection, stream)

`Http2Writer.write()`

http.h2.Http2Writer.write(data)

Sends part of the body.

Parameters

data (bytes|string)

`Http2Writer.flush()`

http.h2.Http2Writer.flush()

Pushes what has been written out to the socket. DATA frames are already flushed as they go, so this is here for interface parity with the HTTP/1.1 writer.

`Http2Writer.finish()`

http.h2.Http2Writer.finish()

Ends the body with an empty END_STREAM frame.

2026, Richard Ore and Zuri contributors

Keyboard shortcuts

The Zuri Standard Library