Trait Handler 

pub trait Handler {
    type Rin: 'static;
    type Rout: 'static;
    type Win: 'static;
    type Wout: 'static;

    // Required methods
    fn name(&self) -> &str;
    fn handle_read(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
        msg: Self::Rin,
    );
    fn poll_write(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
    ) -> Option<Self::Wout>;

    // Provided methods
    fn transport_active(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
    ) { ... }
    fn transport_inactive(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
    ) { ... }
    fn handle_timeout(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
        now: Instant,
    ) { ... }
    fn poll_timeout(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
        eto: &mut Instant,
    ) { ... }
    fn handle_eof(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
    ) { ... }
    fn handle_error(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
        err: Box<dyn Error>,
    ) { ... }
    fn handle_close(
        &mut self,
        ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>,
    ) { ... }
}

Handler and context types for building protocol pipelines A handler processes messages flowing through a pipeline.

The Handler trait defines bidirectional message processing with strict type safety. Each handler transforms messages from one type to another, enabling complex protocol stacks to be built from simple, composable components.

Type Parameters

• Rin: Read input - what this handler receives (inbound direction)
• Rout: Read output - what this handler produces (inbound direction)
• Win: Write input - what this handler receives (outbound direction)
• Wout: Write output - what this handler produces (outbound direction)

Design Pattern

Handlers follow the Intercepting Filter pattern:

1. Receive messages from one direction
2. Transform the message (decode, encode, validate, etc.)
3. Forward to the next handler in the pipeline
4. Optionally handle events (timeouts, errors, lifecycle)

Example

See the module-level documentation for complete examples.

Required Associated Types

type Rin: 'static

Read input message type.

This is the type of messages this handler receives from the previous handler in the pipeline (inbound direction).

type Rout: 'static

Read output message type.

This is the type of messages this handler produces for the next handler in the pipeline (inbound direction).

type Win: 'static

Write input message type.

This is the type of messages this handler receives from the next handler in the pipeline (outbound direction).

type Wout: 'static

Write output message type.

This is the type of messages this handler produces for the previous handler in the pipeline (outbound direction).

Required Methods

fn name(&self) -> &str

Returns the handler’s name.

Used for debugging, logging, and error messages. Should be unique within a pipeline to help identify which handler is being referenced.

Example

fn name(&self) -> &str {
    "MyProtocolHandler"
}

fn handle_read( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, msg: Self::Rin, )

Handles an inbound message.

This is the primary method for processing incoming data. The handler receives a message of type Rin, processes it, and can forward transformed messages of type Rout to the next handler via ctx.fire_handle_read(msg).

Parameters

• ctx: Context for interacting with the pipeline
• msg: The incoming message to process

Example

fn handle_read(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, msg: Self::Rin) {
    // Transform the message
    let transformed = msg.to_uppercase();
    // Forward to next handler
    ctx.fire_handle_read(transformed);
}

fn poll_write( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, ) -> Option<Self::Wout>

Polls for an outbound message.

This method is called to retrieve messages that should be written to the transport. Handlers typically:

1. Poll the next handler via ctx.fire_poll_write()
2. Transform received messages or generate their own
3. Return messages of type Wout

Returns None when no message is available.

Parameters

• ctx: Context for interacting with the pipeline

Returns

• Some(Wout): A message ready to be written
• None: No message available

Example

fn poll_write(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>) -> Option<Self::Wout> {
    // First check next handler
    if let Some(msg) = ctx.fire_poll_write() {
        return Some(msg);
    }
    // Then check our own queue
    self.queue.pop_front()
}

Provided Methods

fn transport_active( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, )

Called when the transport becomes active (connected).

This event is triggered when a connection is established. Handlers can use this to initialize state, start timers, or perform handshakes.

The default implementation propagates the event to the next handler.

Parameters

• ctx: Context for interacting with the pipeline

Example

fn transport_active(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>) {
    self.connected = true;
    println!("Connection established!");
    // Propagate to next handler
    ctx.fire_transport_active();
}

fn transport_inactive( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, )

Called when the transport becomes inactive (disconnected).

This event is triggered when a connection is closed. Handlers can use this to clean up resources, cancel timers, or save state.

The default implementation propagates the event to the next handler.

Parameters

• ctx: Context for interacting with the pipeline

fn handle_timeout( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, now: Instant, )

Handles a timeout event.

Called periodically to allow handlers to perform time-based operations like:

• Sending keepalive messages
• Timing out pending operations
• Retransmitting lost packets

The default implementation propagates the event to the next handler.

Parameters

• ctx: Context for interacting with the pipeline
• now: The current timestamp

fn poll_timeout( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, eto: &mut Instant, )

Polls for the next timeout deadline.

Handlers can update eto (earliest timeout) to indicate when they next need handle_timeout to be called. The pipeline will call the handler with the minimum timeout across all handlers.

The default implementation propagates the poll to the next handler.

Parameters

• ctx: Context for interacting with the pipeline
• eto: Mutable reference to the earliest timeout. Update this to request an earlier timeout.

Example

fn poll_timeout(&mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, eto: &mut Instant) {
    // Request timeout for our keepalive
    if let Some(deadline) = self.next_keepalive {
        if deadline < *eto {
            *eto = deadline;
        }
    }
    // Also check next handler
    ctx.fire_poll_timeout(eto);
}

fn handle_eof( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, )

Handles an end-of-file (EOF) event.

Called when the input stream reaches EOF (e.g., remote peer closed their write side). Handlers can use this to flush buffers or initiate graceful shutdown.

The default implementation propagates the event to the next handler.

Parameters

• ctx: Context for interacting with the pipeline

fn handle_error( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, err: Box<dyn Error>, )

Handles an error event.

Called when an error occurs in the pipeline. Handlers can:

• Log the error
• Attempt recovery
• Transform the error
• Propagate it to the next handler

The default implementation propagates the error to the next handler.

Parameters

• ctx: Context for interacting with the pipeline
• err: The error that occurred

fn handle_close( &mut self, ctx: &Context<Self::Rin, Self::Rout, Self::Win, Self::Wout>, )

Handles a close event.

Called when the pipeline is being closed. Handlers should clean up resources, flush buffers, and prepare for shutdown.

The default implementation propagates the event to the next handler.

Parameters

• ctx: Context for interacting with the pipeline

Implementors