Struct Connection

pub struct Connection { /* private fields */ }

An HTTP/3 connection.

Implementations

impl Connection

pub fn with_transport( conn: &mut Connection, config: &Config, ) -> Result<Connection>

Creates a new HTTP/3 connection using the provided QUIC connection.

This will also initiate the HTTP/3 handshake with the peer by opening all control streams (including QPACK) and sending the local settings.

On success the new connection is returned.

The StreamLimit error is returned when the HTTP/3 control stream cannot be created due to stream limits.

The InternalError error is returned when either the underlying QUIC connection is not in a suitable state, or the HTTP/3 control stream cannot be created due to flow control limits.

pub fn send_request<T: NameValue>( &mut self, conn: &mut Connection, headers: &[T], fin: bool, ) -> Result<u64>

Sends an HTTP/3 request.

The request is encoded from the provided list of headers without a body, and sent on a newly allocated stream. To include a body, set fin as false and subsequently call send_body() with the same conn and the stream_id returned from this method.

On success the newly allocated stream ID is returned.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_response<T: NameValue>( &mut self, conn: &mut Connection, stream_id: u64, headers: &[T], fin: bool, ) -> Result<()>

Sends an HTTP/3 response on the specified stream with default priority.

This method sends the provided headers as a single initial response without a body.

To send a non-final 1xx, then a final 200+ without body:

• send_response() with fin set to false.
• send_additional_headers() with fin set to true using the same stream_id value.

To send a non-final 1xx, then a final 200+ with body:

• send_response() with fin set to false.
• send_additional_headers() with fin set to false and same stream_id value.
• send_body() with same stream_id.

To send a final 200+ with body:

• send_response() with fin set to false.
• send_body() with same stream_id.

Additional headers can only be sent during certain phases of an HTTP/3 message exchange, see [Section 4.1 of RFC 9114]. The [FrameUnexpected] error is returned if this method, or send_response_with_priority(), are called multiple times with the same stream_id value.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_response_with_priority<T: NameValue>( &mut self, conn: &mut Connection, stream_id: u64, headers: &[T], priority: &Priority, fin: bool, ) -> Result<()>

Sends an HTTP/3 response on the specified stream with specified priority.

The priority parameter represents Extensible Priority parameters. If the urgency is outside the range 0-7, it will be clamped to 7.

This method sends the provided headers as a single initial response without a body.

To send a non-final 1xx, then a final 200+ without body:

• send_response_with_priority() with fin set to false.
• send_additional_headers() with fin set to true using the same stream_id value.

To send a non-final 1xx, then a final 200+ with body:

• send_response_with_priority() with fin set to false.
• send_additional_headers() with fin set to false and same stream_id value.
• send_body() with same stream_id.

To send a final 200+ with body:

• send_response_with_priority() with fin set to false.
• send_body() with same stream_id.

Additional headers can only be sent during certain phases of an HTTP/3 message exchange, see [Section 4.1 of RFC 9114]. The FrameUnexpected error is returned if this method, or send_response(), are called multiple times with the same stream_id value.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_additional_headers<T: NameValue>( &mut self, conn: &mut Connection, stream_id: u64, headers: &[T], is_trailer_section: bool, fin: bool, ) -> Result<()>

Sends additional HTTP/3 headers.

After the initial request or response headers have been sent, using send_request() or send_response() respectively, this method can be used send an additional HEADERS frame. For example, to send a single instance of trailers after a request with a body, or to issue another non-final 1xx after a preceding 1xx, or to issue a final response after a preceding 1xx.

Additional headers can only be sent during certain phases of an HTTP/3 message exchange, see Section 4.1 of RFC 9114. The FrameUnexpected error is returned when this method is called during the wrong phase, such as before initial headers have been sent, or if trailers have already been sent.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_body( &mut self, conn: &mut Connection, stream_id: u64, body: &[u8], fin: bool, ) -> Result<usize>

Sends an HTTP/3 body chunk on the given stream.

On success the number of bytes written is returned, or Done if no bytes could be written (e.g. because the stream is blocked).

Note that the number of written bytes returned can be lower than the length of the input buffer when the underlying QUIC stream doesn’t have enough capacity for the operation to complete.

When a partial write happens (including when Done is returned) the application should retry the operation once the stream is reported as writable again.

pub fn dgram_enabled_by_peer(&self, conn: &Connection) -> bool

Returns whether the peer enabled HTTP/3 DATAGRAM frame support.

Support is signalled by the peer’s SETTINGS, so this method always returns false until they have been processed using the poll() method.

pub fn extended_connect_enabled_by_peer(&self) -> bool

Returns whether the peer enabled extended CONNECT support.

Support is signalled by the peer’s SETTINGS, so this method always returns false until they have been processed using the poll() method.

pub fn recv_body( &mut self, conn: &mut Connection, stream_id: u64, out: &mut [u8], ) -> Result<usize>

Reads request or response body data into the provided buffer.

Applications should call this method whenever the poll() method returns a Data event.

On success the amount of bytes read is returned, or Done if there is no data to read.

pub fn send_priority_update_for_request( &mut self, conn: &mut Connection, stream_id: u64, priority: &Priority, ) -> Result<()>

Sends a PRIORITY_UPDATE frame on the control stream with specified request stream ID and priority.

The priority parameter represents Extensible Priority parameters. If the urgency is outside the range 0-7, it will be clamped to 7.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn take_last_priority_update( &mut self, prioritized_element_id: u64, ) -> Result<Vec<u8>>

Take the last PRIORITY_UPDATE for a prioritized element ID.

When the poll() method returns a PriorityUpdate event for a prioritized element, the event has triggered and will not rearm until applications call this method. It is recommended that applications defer taking the PRIORITY_UPDATE until after poll() returns Done.

On success the Priority Field Value is returned, or Done if there is no PRIORITY_UPDATE to read (either because there is no value to take, or because the prioritized element does not exist).

pub fn poll(&mut self, conn: &mut Connection) -> Result<(u64, Event)>

Processes HTTP/3 data received from the peer.

On success it returns an Event and an ID, or Done when there are no events to report.

Note that all events are edge-triggered, meaning that once reported they will not be reported again by calling this method again, until the event is re-armed.

The events Headers, Data and Finished return a stream ID, which is used in methods recv_body(), send_response() or send_body().

The event GoAway returns an ID that depends on the connection role. A client receives the largest processed stream ID. A server receives the the largest permitted push ID.

The event PriorityUpdate only occurs at servers. It returns a prioritized element ID that is used in the method take_last_priority_update(), which rearms the event for that ID.

If an error occurs while processing data, the connection is closed with the appropriate error code, using the transport’s close() method.

pub fn send_goaway(&mut self, conn: &mut Connection, id: u64) -> Result<()>

Sends a GOAWAY frame to initiate graceful connection closure.

When quiche is used in the server role, the id parameter is the stream ID of the highest processed request. This can be any valid ID between 0 and 2^62-4. However, the ID cannot be increased. Failure to satisfy these conditions will return an error.

This method does not close the QUIC connection. Applications are required to call close() themselves.

pub fn peer_settings_raw(&self) -> Option<&[(u64, u64)]>

Gets the raw settings from peer including unknown and reserved types.

The order of settings is the same as received in the SETTINGS frame.

pub fn stats(&self) -> Stats

Collects and returns statistics about the connection.