Struct quiche::h3::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 without a body. To include a body, set fin as false and subsequently call send_body() with the same conn and stream_id.

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.

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 send_dgram(
    &mut self,
    conn: &mut Connection,
    flow_id: u64,
    buf: &[u8]
) -> Result<()>

Sends an HTTP/3 DATAGRAM with the specified flow ID.

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

Reads a DATAGRAM into the provided buffer.

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

On success the DATAGRAM data is returned, with length and Flow ID and length of the Flow ID.

Done is returned if there is no data to read.

BufferTooShort is returned if the provided buffer is too small for the data.

pub fn dgram_max_writable_len(
    &self,
    conn: &Connection,
    flow_id: u64
) -> Option<usize>

Returns the maximum HTTP/3 DATAGRAM payload that can be sent.

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 Datagram returns a dummy value of 0, this should be ignored by the application.

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.