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,
        transport: Arc<dyn SocketTransport>,
        runtime: Arc<dyn Runtime>,
        timeout: Duration,
    ) -> impl Future<Output = Result<BoxSocket, 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 follow_up(&mut self) -> Option<Message> { ... }
    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, transport: Arc<dyn SocketTransport>, runtime: Arc<dyn Runtime>, timeout: Duration, ) -> impl Future<Output = Result<BoxSocket, Self::Error>> + Send

Open the connection for one attempt, within timeout.

The Supervisor calls it for every attempt, the first and each reconnect, with its SocketTransport and runtime and Timing::connect_timeout. By default it builds handshake’s request first, so a failure there is the attempt’s, and dials it through the transport. A protocol that wants another dial injects a transport that makes it, such as one that tries each resolved address in turn (TungsteniteTransport::per_address). It overrides this for either of two reasons: to shape the transport’s error, or to read the transport’s capabilities before it dials, since this is the one hook that is handed the transport. A protocol that sends a frame of its own to keep a connection alive, because the transport cannot send a protocol ping, reads capabilities() here to learn whether it needs to. 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 follow_up(&mut self) -> Option<Message>

A frame to send right after a frame was decoded, or None for none (the default): how a protocol asks the server for something its last frame showed it needs, such as the state of a stream it can no longer trust.

The supervisor calls it once after each decode that leaves the connection up: not after a decode error that reconnects or stops, and not on a connection that has already ended, such as after the server’s close frame. What it returns is sent on the same connection, one frame for each call, within Timing::stale_after, and the answer is not awaited: it is a frame like any other. A send that fails, or outlives that window, ends the connection as a failed ping does, and recover decides what follows.

A protocol with several frames to send returns one for each call, so the rest go out after later frames. Every frame the connection yields is decoded, the server’s pings, pongs and unsolicited answers included, so a held frame goes out after the next frame of any kind, and on a connection that receives nothing it waits. What it still holds when the connection ends stays with it, and is cleared in reset.

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