Trait Protocol 

pub trait Protocol:
    Send
    + Sized
    + 'static {
    type Event: Send + 'static;
    type Error: Error + From<WsError> + Send + 'static;
    type Membership: Send + 'static;
    type Change: Send + 'static;
    type Ack: Send + 'static;

    // Required methods
    fn handshake(&mut self) -> Result<Request, Self::Error>;
    fn replay(
        &mut self,
        connection: &mut Connection,
        membership: &Self::Membership,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
    fn apply(
        &mut self,
        connection: &mut Connection,
        membership: &mut Self::Membership,
        change: Self::Change,
    ) -> impl Future<Output = Result<Self::Ack, Self::Error>> + Send;
    fn decode(&mut self, frame: &Message) -> Decoded<Self::Event, Self::Error>;
    fn is_live(
        &self,
        frame: &Message,
        decoded: &Decoded<Self::Event, Self::Error>,
    ) -> bool;
    fn delivered(
        &self,
        frame: &Message,
        decoded: &Decoded<Self::Event, Self::Error>,
    ) -> bool;
    fn ping(&mut self, connection: &mut Connection) -> Option<Message>;
    fn is_retriable(err: &Self::Error) -> bool;
    fn reconnected(&mut self) -> Self::Event;
    fn queue(&self) -> Queue;

    // Provided methods
    fn connect(
        &mut self,
        timeout: Duration,
    ) -> impl Future<Output = Result<Socket, Self::Error>> + Send { ... }
    fn configure(&self, connection: Connection) -> Connection { ... }
    fn record(
        &mut self,
        membership: &mut Self::Membership,
        change: Self::Change,
    ) -> Offline<Self::Change, Self::Ack, Self::Error> { ... }
    fn wanted(membership: &Self::Membership) -> bool { ... }
    fn recover(&self, err: &Self::Error) -> Recovery { ... }
    fn retry_after(&self, err: &Self::Error) -> Option<Duration> { ... }
    fn disconnected(
        &mut self,
        outage: Outage<Self::Error>,
    ) -> Option<Self::Event> { ... }
    fn reset(&mut self) { ... }
    fn stalled(silent: Duration) -> Self::Error { ... }
    fn stopped() -> Self::Error { ... }
}

A venue’s socket protocol, as the Supervisor drives it.

The supervisor owns the rules every venue shares (AD-11): pings on the wall clock, staleness, backoff, rotation, the outage markers and the consumer’s queue. A protocol says what is its own, and each divergence row stays here, at the venue:

• D4, the ping: ping, sent every Timing::ping_interval whatever the traffic.
• D5, liveness: is_live, which restarts the staleness window.
• D6, a delivered connection: delivered, which resets the backoff when the connection ends.
• D8, outage markers: disconnected, or none.
• D19 and the rest of recovery: recover.

The hooks that talk to the server, replay and apply, borrow the Connection, so they use its request correlation. A request is not cancel-safe, so the supervisor bounds each by Timing::stale_after and replaces a connection that outlives it.

The trait is generic only, and its async hooks return impl Future + Send.

Required Associated Types

type Event: Send + 'static

What the stream yields.

type Error: Error + From<WsError> + Send + 'static

What the stream and the membership calls fail with. Every socket failure arrives as a WsError first.

type Membership: Send + 'static

What the connection carries, such as its subscriptions.

type Change: Send + 'static

One change to the membership.

type Ack: Send + 'static

The answer to a change.

Required Methods

fn handshake(&mut self) -> Result<Request, Self::Error>

The handshake request for one connection attempt, built afresh for each, so any authentication in it is recomputed.

fn replay( &mut self, connection: &mut Connection, membership: &Self::Membership, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Put the membership on a fresh connection, paced as the venue requires. A failure is recovered as a failed attempt.

fn apply( &mut self, connection: &mut Connection, membership: &mut Self::Membership, change: Self::Change, ) -> impl Future<Output = Result<Self::Ack, Self::Error>> + Send

Make one change on a live connection, and record it in the membership as far as it took effect. The caller gets the answer; an error keeps the connection, unless the request outlived the staleness window.

fn decode(&mut self, frame: &Message) -> Decoded<Self::Event, Self::Error>

What one frame means: Text, Binary, Ping, Pong or Close.

fn is_live( &self, frame: &Message, decoded: &Decoded<Self::Event, Self::Error>, ) -> bool

Whether this frame, decoded so, proves the connection alive and restarts the staleness window (D5).

fn delivered( &self, frame: &Message, decoded: &Decoded<Self::Event, Self::Error>, ) -> bool

Whether this frame, decoded so, makes the connection one that delivered something, which resets the backoff when it ends (D6).

fn ping(&mut self, connection: &mut Connection) -> Option<Message>

The ping to send at a ping tick, or None for none (D4). It is sent without awaiting an answer; the answer is a frame like any other.

fn is_retriable(err: &Self::Error) -> bool

Whether reconnecting can help after this error. Required, since only the venue knows its classes; it is what recover reads by default.

fn reconnected(&mut self) -> Self::Event

The event ending an outage, yielded exactly once per outage: after a fresh connection has replayed the membership, or when the membership stopped being wanted during the outage.

fn queue(&self) -> Queue

The queue between the task and the consumer.

Provided Methods

fn connect( &mut self, timeout: Duration, ) -> impl Future<Output = Result<Socket, Self::Error>> + Send

Open the connection for one attempt, within timeout.

The Supervisor calls it for every attempt, the first and each reconnect, with Timing::connect_timeout. By default it builds handshake’s request first, so a failure there is the attempt’s, and dials it with the kit’s connect. A protocol that dials its venue a step at a time, such as a venue that tries each resolved address in turn, overrides it: it bounds each step by timeout itself, upgrades with connect_over, and may keep handshake for the request it upgrades with. An error is a failed attempt, which recover decides on.

fn configure(&self, connection: Connection) -> Connection

Shape each fresh connection before anything is sent on it, such as with Connection::min_request_interval for a venue that paces its requests. By default the connection is left as it is.

fn record( &mut self, membership: &mut Self::Membership, change: Self::Change, ) -> Offline<Self::Change, Self::Ack, Self::Error>

What becomes of a change made during an outage. By default it is held and apply’d once a connection is up.

fn wanted(membership: &Self::Membership) -> bool

Whether the membership still wants a connection. One that stops being wanted on a healthy connection closes it politely, with no marker, and ends the stream; during an outage it ends the outage with reconnected and then the stream.

fn recover(&self, err: &Self::Error) -> Recovery

What to do after this error: by default Reconnect exactly when is_retriable says so, and Stop otherwise.

fn retry_after(&self, err: &Self::Error) -> Option<Duration>

How long the server asked the client to wait after this error, such as a refused upgrade’s Retry-After; None by default.

The reconnect that follows waits at least this, clamped to Timing::max_backoff, and never less than the backoff’s own step: a server’s wait only extends the delay (DRIFT R11). A venue answers it from its error’s class, the one place that reads the header.

fn disconnected(&mut self, outage: Outage<Self::Error>) -> Option<Self::Event>

The event announcing an outage, or None for a protocol that declares none (the default). Called at most once per outage.

fn reset(&mut self)

Forget what belongs to the previous connection, before a fresh one replays the membership.

fn stalled(silent: Duration) -> Self::Error

The error for a membership change, or a connection attempt, that the server left unanswered for the staleness window. By default a Kind::NoAnswer.

fn stopped() -> Self::Error

The error for a membership change, or a Supervised::close, once the task has stopped. By default a Kind::AlreadyClosed.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors