Trait ApplicationOverQuic

pub trait ApplicationOverQuic: Send + 'static {
    // Required methods
    fn on_conn_established(
        &mut self,
        qconn: &mut QuicheConnection,
        handshake_info: &HandshakeInfo,
    ) -> QuicResult<()>;
    fn should_act(&self) -> bool;
    fn buffer(&mut self) -> &mut [u8] ;
    fn wait_for_data(
        &mut self,
        qconn: &mut QuicheConnection,
    ) -> impl Future<Output = QuicResult<()>> + Send;
    fn process_reads(&mut self, qconn: &mut QuicheConnection) -> QuicResult<()>;
    fn process_writes(&mut self, qconn: &mut QuicheConnection) -> QuicResult<()>;

    // Provided method
    fn on_conn_close<M: Metrics>(
        &mut self,
        qconn: &mut QuicheConnection,
        metrics: &M,
        connection_result: &QuicResult<()>,
    ) { ... }
}

A trait to implement an application served over QUIC.

The application is driven by an internal worker task, which also handles I/O for the connection. The worker feeds inbound packets into the [quiche::Connection], calls ApplicationOverQuic::process_reads followed by ApplicationOverQuic::process_writes, and then flushes any pending outbound packets to the network. This repeats in a loop until either the connection is closed or the ApplicationOverQuic returns an error.

In between loop iterations, the worker yields until a new packet arrives, a timer expires, or ApplicationOverQuic::wait_for_data resolves. Implementors can interact with the underlying connection via the mutable reference passed to trait methods.

Required Methods

fn on_conn_established( &mut self, qconn: &mut QuicheConnection, handshake_info: &HandshakeInfo, ) -> QuicResult<()>

Callback to customize the ApplicationOverQuic after the QUIC handshake completed successfully.

Errors

Returning an error from this method immediately stops the worker loop and transitions to the connection closing stage.

fn should_act(&self) -> bool

Determines whether the application’s methods will be called by the worker.

The function is checked in each iteration of the worker loop. Only on_conn_established() and buffer() bypass this check.

fn buffer(&mut self) -> &mut [u8]

A borrowed buffer for the worker to write outbound packets into.

This method allows sharing a buffer between the worker and the application, efficiently using the allocated memory while the application is inactive. It can also be used to artificially restrict the size of outbound network packets.

Any data in the buffer may be overwritten by the worker. If necessary, the application should save the contents when this method is called.

fn wait_for_data( &mut self, qconn: &mut QuicheConnection, ) -> impl Future<Output = QuicResult<()>> + Send

Waits for an event to trigger the next iteration of the worker loop.

The returned future is awaited in parallel to inbound packets and the connection’s timers. Any one of those futures resolving triggers the next loop iteration, so implementations should not rely on wait_for_data for the bulk of their processing. Instead, after wait_for_data resolves, process_writes should be used to pull all available data out of the event source (for example, a channel).

As for any future, it is very important that this method does not block the runtime. If it does, the other concurrent futures will be starved.

Errors

Returning an error from this method immediately stops the worker loop and transitions to the connection closing stage.

fn process_reads(&mut self, qconn: &mut QuicheConnection) -> QuicResult<()>

Processes data received on the connection.

This method is only called if should_act() returns true and any packets were received since the last worker loop iteration. It should be used to read from the connection’s open streams.

Errors

Returning an error from this method immediately stops the worker loop and transitions to the connection closing stage.

fn process_writes(&mut self, qconn: &mut QuicheConnection) -> QuicResult<()>

Adds data to be sent on the connection.

Unlike process_reads, this method is called on every iteration of the worker loop (provided should_act() returns true). It is called after process_reads and immediately before packets are pushed to the socket. The main use case is providing already-buffered data to the [quiche::Connection].

Errors

Returning an error from this method immediately stops the worker loop and transitions to the connection closing stage.

Provided Methods

fn on_conn_close<M: Metrics>( &mut self, qconn: &mut QuicheConnection, metrics: &M, connection_result: &QuicResult<()>, )

Callback to inspect the result of the worker task, before a final packet with a CONNECTION_CLOSE frame is flushed to the network.

connection_result is Ok only if the connection was closed without any local error. Otherwise, the state of qconn depends on the error type and application behavior.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<H: DriverHooks> ApplicationOverQuic for H3Driver<H>