Trait Datagrams 

pub trait Datagrams<P: Protocol>: Send + Sync
where
    P::Request: 'static,
    P::Response: 'static,
{
    // Required methods
    fn max_datagram_size(&self) -> Option<u32>;
    fn send_datagram_bytes<'life0, 'async_trait>(
        &'life0 self,
        bytes: Bytes,
    ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn recv_datagram_bytes<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Bytes, SessionError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn send_request_datagram<'life0, 'async_trait>(
        &'life0 self,
        frame: Frame<P::Request>,
    ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn send_response_datagram<'life0, 'async_trait>(
        &'life0 self,
        frame: Frame<P::Response>,
    ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

The optional unordered channel belonging to a session.

r[impl jetstream.session.datagrams] Datagrams may be dropped, may arrive in any order, and are never retransmitted by JetStream.

r[impl jetstream.session.datagrams.not-a-lane] This is deliberately not a ClientTransport: a datagram channel is not a lane, and none of the lane ordering requirements apply to it.

A transport implements the three raw methods; the four framed ones are provided. That is deliberate. Every framed method has to check the path limit before sending and reject a datagram carrying anything after its frame, and when each transport wrote those out itself the two implementations drifted — iroh rejected trailing bytes and QUIC accepted them. Encoding and decoding belong to the model, not to the transport.

r[impl jetstream.session.symmetric] The channel belongs to the connection, so both directions exist at both ends. A session is not fixed to a role — the peer that opens a lane is the caller on that lane — so a datagram API that only sent requests and only received responses was wrong at whichever end was serving: a callee encoded its answers as questions, and decoded its peer’s questions as answers. Sending therefore names the direction. Receiving cannot, and does not: see recv_datagram_bytes.

Required Methods

fn max_datagram_size(&self) -> Option<u32>

The largest frame the path will carry, if the transport knows it.

fn send_datagram_bytes<'life0, 'async_trait>( &'life0 self, bytes: Bytes, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send one already-encoded datagram, or fail. Never fragmented, never retried.

fn recv_datagram_bytes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Bytes, SessionError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Receive the next datagram that arrived intact.

r[impl jetstream.session.datagrams] Receiving is deliberately untyped, and deliberately singular. The channel is one unordered queue belonging to the connection, so every reader competes for the same packets — a typed recv_request and a typed recv_response used at once would each take datagrams meant for the other, fail to decode them, and discard them for good. Nothing in a datagram says which direction it is; the frame’s message type does, but only a protocol that partitions the type space can be read that way, and Protocol does not require it.

So a session hands out the bytes and the caller says what it expects, with decode_datagram. A peer that receives in one role — which is the usual case — writes one turbofish. A peer that receives in both needs a discriminator of its own, and the API says so by not pretending otherwise.

Provided Methods

fn send_request_datagram<'life0, 'async_trait>( &'life0 self, frame: Frame<P::Request>, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send a request, as the caller.

fn send_response_datagram<'life0, 'async_trait>( &'life0 self, frame: Frame<P::Response>, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send a response, as the callee.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors