Http3Connection class

Manages an HTTP/3 connection over a QUIC transport.

An Http3Connection maps HTTP/3 semantics (requests, responses, headers, and settings) onto QUIC streams and frames. Per RFC 9114, the first client-initiated bidirectional stream (stream ID 0) is reserved as the control stream, where SETTINGS and GOAWAY frames are exchanged. All other streams carry individual request/response exchanges.

Use sendRequest to initiate an outbound request, getResponse to read a received response, and close to send a GOAWAY and gracefully terminate the connection. The underlying QUIC transport is exposed via quicConnection for advanced use cases.

Example

final quicConn = await endpoint.connect(remoteAddress, remotePort);
final http3 = Http3Connection(quicConnection: quicConn);

final request = Http3Request(
  method: 'GET',
  path: '/index.html',
  headers: {'host': 'example.com'},
);
final streamId = await http3.sendRequest(request);

// Later, when the response arrives...
final response = http3.getResponse(streamId);
print('Status: ${response?.statusCode}');

http3.close();

Constructors

Http3Connection({required Object quicConnection, Http3SettingsFrame? localSettings}): Creates an Http3Connection over quicConnection.

Properties

alternativeOrigins → List<String>: Alternative origins received via ORIGIN frames.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasSentGoaway → bool: True once a GOAWAY frame has been sent.
no setter
isClosing → bool: True once a GOAWAY frame has been received.
no setter
isConnectProtocolEnabled → bool: True if the peer has enabled Extended CONNECT (RFC 9220).
no setter
isH3DatagramEnabled → bool: True if the peer has enabled HTTP Datagrams (RFC 9297).
no setter
lastAcceptedStreamId → int: The last accepted stream ID.
no setter
localSettings → Http3SettingsFrame: Local SETTINGS that will be sent to the peer on the control stream.
no setter
maxPushId → int: The maximum Push ID advertised by the peer via MAX_PUSH_ID frames. Returns -1 if no MAX_PUSH_ID has been received.
no setter
peerSettings → Http3SettingsFrame: SETTINGS received from the peer.
no setter
pendingDecoderInstructions → List<DecoderInstruction>: Pending QPACK decoder-stream instructions staged for transmission.
no setter
pendingPriorityUpdates → List<PriorityUpdateFrame>: Pending PRIORITY_UPDATE frames staged for transmission.
no setter
pendingQuicPackets → List<Uint8List>: QUIC packets built by HTTP/3 operations (e.g., GOAWAY) that are waiting to be sent by the transport layer.
no setter
pendingSettings → Http3SettingsFrame?: Pending SETTINGS frame to be sent on the control stream.
no setter
qpackDecoder → QpackDecoder: QPACK decoder used for request/response headers on this connection.
final
qpackEncoder → QpackEncoder: QPACK encoder used for request/response headers on this connection.
final
quicConnection → Object: The underlying QUIC connection.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sentGoawayFrames → List<Http3GoawayFrame>: GOAWAY frames that have been sent on this connection.
no setter
settingsExchanged → bool: True once the peer's SETTINGS frame has been received.
no setter
streamScheduler ↔ StreamScheduler?: Optional stream scheduler for priority-aware stream selection.
getter/setter pair
webTransportSessions → Map<int, WebTransportSession>: Active WebTransport sessions keyed by stream ID.
no setter

Methods

close() → void: Gracefully close the HTTP/3 connection.
createWebTransportSession(WebTransportConnectRequest request) → Future<WebTransportSession>: Create a WebTransport session by sending an Extended CONNECT request.
flushQpackDecoderInstructions() → Future<int?>: Flush pending QPACK decoder instructions to the decoder stream.
flushQpackEncoderInstructions() → Future<int?>: Flush pending QPACK encoder instructions to the encoder stream.
getBody(int streamId) → Uint8List?: Concatenate all DATA frame payloads for streamId into a single buffer.
getPendingData(int streamId) → List<DataFrame>: Pending DATA frames for a given stream.
getPendingHeaders(int streamId) → HeadersFrame?: Pending HEADERS frame for a given stream.
getPendingPushPromises(int streamId) → List<Http3PushPromiseFrame>: Returns the push promises staged for transmission on streamId.
getPushPromise(int pushId) → Http3PushPromiseFrame?: Returns the registered push promise frame for pushId, or null if no promise with that push ID has been registered.
getPushResponse(int pushId) → Http3Response?: Returns the push response delivered for pushId, or null if no push stream carrying that push ID has been received yet.
getPushStreamId(int pushId) → int?: Returns the QUIC stream ID allocated for the push stream carrying pushId, or null if the server has not yet sent a push response for that push ID.
getResponse(int streamId) → Http3Response?: Return a decoded Http3Response if headers were received for streamId.
hasBody(int streamId) → bool: True if the stream has pending DATA frames.
hasPushPromise(int pushId) → bool: Check if a push promise with pushId is registered.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onCapsuleReceived(int sessionId, Capsule capsule) → void: Process an incoming capsule belonging to sessionId.
onOriginFrameReceived(OriginFrame frame) → void: Process a received ORIGIN frame and store the advertised origins.
onPriorityUpdateReceived(PriorityUpdateFrame frame) → void: Process a received PRIORITY_UPDATE frame.
onPushStreamData(int streamId, Uint8List data) → void: Process incoming data on a server push stream.
onSettingsReceived(Http3SettingsFrame settings) → void: Process a received SETTINGS frame from the peer's control stream.
onStreamFrame(int streamId, Http3Frame frame) → void: Process received frames on a QUIC stream.
onUnidirectionalStreamData(int streamId, Uint8List data) → void: Process received data on a unidirectional stream.
openQpackStreams() → Future<void>: Open the QPACK encoder and decoder unidirectional streams.
openStream() → Future<Http3QuicStream>: Open a new bidirectional stream and return a wrapper for sending data.
registerPushPromise(int pushId, Http3PushPromiseFrame frame) → void: Register a push promise manually.
sendBody(int streamId, Uint8List body) → Future<void>: Break body into DATA frames and store them for streamId.
sendCapsule(int sessionId, Capsule capsule) → void: Send a capsule for sessionId as DATA frames on the control stream.
sendDatagram(int sessionId, Uint8List data) → void: Send an unreliable datagram for sessionId using the QUIC connection.
sendExtendedConnect(ExtendedConnectRequest request) → Future<int>: Send an Extended CONNECT request (RFC 9220) on a new bidirectional stream.
sendPriorityUpdate(int streamId, String priority) → void: Stage a PRIORITY_UPDATE frame for transmission.
sendPushPromise(int pushId, Http3Request promisedRequest, {required int requestStreamId}) → Http3PushPromiseFrame: Send a PUSH_PROMISE frame on the client's request stream (requestStreamId) reserving pushId for a server push of promisedRequest.
sendPushResponse(int pushId, Http3Response response) → Future<int>: Send a push response for pushId by creating a server-initiated push stream and transmitting the response as HEADERS (and optional DATA) frames on it.
sendRequest(Http3Request request) → Future<int>: Send an HTTP/3 request on a new client-initiated bidirectional stream.
sendResponse(int streamId, Http3Response response) → void: Send an HTTP/3 response on streamId and store the encoded headers.
sendSettings() → Http3SettingsFrame: Initiate the HTTP/3 connection by sending a SETTINGS frame on the control stream.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited