Struct Connection 

pub struct Connection { /* private fields */ }

One open connection, as a Stream of its frames.

Yields Ok frames as Mode selects, and ends after the server’s close, after the end of the stream, or after the one Err a failed read yields. Frames kept while a request awaited its answer come out first, in the order they arrived. The server’s pings are answered as the stream is read.

The server’s close is answered: the RFC 6455 close reply is flushed before the stream yields its last item, so it goes out even when the caller never reads again (DRIFT R3). Once the stream has ended on the close, closed says with what code and reason, as a Kind::Closed error.

The basis is one socket crate’s bare-tier poll_next (src/client.rs) and its frame classifier, with the queue two other socket crates’ former bare tiers drained first and the former close capture of one of those two (record_close and closed_error); all five socket crates read through this type since Stories 4.6 to 4.10. Two divergence rows stay with each venue: what counts as liveness (D5), which Mode::All and last_inbound let a venue decide, and what a Binary frame means (D12): one venue decodes it as text, and the others skip it.

Implementations

impl Connection

pub fn new(socket: BoxSocket, mode: Mode) -> Self

Read socket in mode, on the target’s default runtime.

pub fn with_runtime( socket: BoxSocket, mode: Mode, runtime: Arc<dyn Runtime>, ) -> Self

Read socket in mode, on runtime: its clock stamps the frames, and it paces and bounds the connection’s requests.

pub fn runtime(&self) -> &Arc<dyn Runtime>

The runtime this connection runs on, for a protocol’s own timers.

pub fn mode(&self) -> Mode

Which frames this connection yields.

pub fn last_inbound(&self) -> Instant

When the last frame of any kind arrived, pings, pongs and frames read while awaiting an answer included; when the connection was made, if none has.

pub fn closed(&self) -> Option<WsError>

The server’s close, once the stream has ended on it: a Kind::Closed with the close frame’s code and reason, or with no code and an empty reason when the stream ended without a close frame. A close frame without a code reads the same. None while the connection is open, and after a failed read, whose error the stream yielded.

pub async fn send(&mut self, message: Message) -> Result<(), WsError>

Send one frame and flush it.

pub async fn close(&mut self) -> Result<(), WsError>

Close the connection: send a close frame and flush it. On a connection the server already closed, flush the reply if it has not gone out yet; there is nothing else to send. A connection whose read failed is already gone, so closing it does nothing.

impl Connection

Requests and their answers.

Ids count from 1. A request is sent no sooner than its minimum interval after the previous one, when one is set, and then reads until the caller’s matcher recognises its answer. Every other frame read meanwhile is kept and yielded by the stream afterwards, in the order it arrived; an answer to another request is dropped. With an answer timeout set, a request whose send and wait together outlast it fails as Kind::NoAnswer, so a peer that stops reading cannot hang it; without one, it waits as long as the connection stays open. A server close while waiting fails the request with the close, as does any request after it, and a request after a failed read fails as Kind::AlreadyClosed without sending.

The envelope is the caller’s: a builder writes the request for its id, and a matcher reads each frame. Neither request nor its wait is cancel-safe, and after a NoAnswer the server’s state is unknown: replace the connection rather than reuse it.

The basis is one socket crate’s former request and await_answer (its bare tier’s, on this correlation since Story 4.7), with its 10 s answer timeout and 200 ms pacing, and another socket crate’s former take_id and await_response (ws/client.rs, Story 4.6), which set neither.

pub fn min_request_interval(self, interval: Duration) -> Self

Send requests no sooner than interval apart. Only request and take_paced_id are paced: a frame sent with send, under an id from take_id or not, neither waits nor counts.

pub fn answer_timeout(self, timeout: Duration) -> Self

Give up on a request after timeout, its send and its wait for the answer together, and on await_answer’s wait.

pub fn next_id(&self) -> u64

The id the next request will take.

pub fn take_id(&mut self) -> u64

Take the next id, for a request sent another way. A request sent that way is not paced by min_request_interval, and does not delay the next paced one.

pub fn take_paced_id(&mut self) -> Option<u64>

Take the next id for a request that is sent now and paced like request, without waiting: for a synchronous hook such as a protocol’s ping, which cannot await.

None, taking no id, while min_request_interval has not passed since the last paced send on the connection’s runtime clock. Otherwise the next id, and now is recorded as the last paced send, so the next request waits from it. The caller must send the frame it builds for the id; an id taken and not sent still delays the next paced request. With no interval set, or one too long to add (never reached, as for request), it always takes the id.

pub async fn request<A>( &mut self, build: impl FnOnce(u64) -> Message, answer: impl FnMut(u64, &Message) -> Correlated<A>, ) -> Result<A, WsError>

Send the request build writes for the next id, and read until answer recognises its answer.

pub async fn await_answer<A>( &mut self, answer: impl FnMut(&Message) -> Correlated<A>, ) -> Result<A, WsError>

Read until answer recognises a frame as the answer awaited, keeping pushes for the stream, within the answer timeout when one is set.

For an answer to something request did not send, such as a protocol ping’s pong.

Trait Implementations

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Stream for Connection

type Item = Result<Message, WsError>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.