Skip to main content

Exchange

Trait Exchange 

pub trait Exchange {
    type Error: Error + Classify + 'static;

    // Required method
    async fn exchange(
        &self,
        route: Route,
        request: Vec<u8>,
    ) -> Result<Vec<u8>, Self::Error>;
}
Expand description

Sends one request on a route and returns the reply: one round trip.

This is the !Send flavour and the one to bind in generic code; a transport that can cross threads implements SendExchange and gets this for free (ADR-0001). The Durable Object’s stub, which holds a JsValue, cannot be Send, and a native HTTP client wants to be.

§What an implementation promises

  • One round trip. The reply is the far side’s answer to this request, paired by the transport — the response to the request it sent, or the message on the matching return route — never a buffer from another call.
  • route reaches the far side, which passes it to serve_sync with the bytes (ADR-0097).
  • A failure the far side reported, or the transport met, comes back as Error stating its own class (SY-36). An HTTP transport reads that class back from the status serve_sync’s error was mapped to.
  • The reply is bounded. A transport caps the reply body it will read at about the declared max_batch_bytes plus the envelope’s overhead, and refuses a longer one rather than buffering it: the bytes come from a peer, and RemoteSyncPeer decodes whatever it is handed.
  • The round trip is bounded in time. A transport puts a timeout on the request and returns a failure when it expires, so a far side that never answers cannot hold a pull or a push open forever.

Required Associated Types§

type Error: Error + Classify + 'static

How the transport fails, each failure stating its class. No Send bound, for the reason SyncPeer::Error has none.

Required Methods§

async fn exchange( &self, route: Route, request: Vec<u8>, ) -> Result<Vec<u8>, Self::Error>

Sends request on route and returns the reply’s bytes.

request is owned because the transport consumes it: an HTTP body or a message to post takes the buffer, and a borrow would make it copy.

§Errors

The transport’s error, for a failure to deliver the request, a failure to read the reply, or a refusal the far side reported.

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§

§

impl<TraitVariantBlanketType: SendExchange> Exchange for TraitVariantBlanketType

§

type Error = <TraitVariantBlanketType as SendExchange>::Error