Struct Connection 

pub struct Connection<B: BidiBinding> { /* private fields */ }

A handle to one open bidirectional subscription. Writing to the wire is the actor’s job; this only submits commands and reads events. Generic over the backend BidiBinding. The backend module supplies the concrete alias.

Implementations

impl Connection<BackendBinding>

pub async fn open<A>(api: &A, initial: Update) -> Result<Self, A::Error>

where A: XmtpMlsBidiStreams, A::SubscribeStream: 'static,

Open the backend subscription with the initial topic update.

impl<B: BidiBinding> Connection<B>

pub async fn mutate(&self, mutate: B::Mutate) -> Result<(), BidiError>

Add/remove subscriptions in place. Awaits a free command slot (backpressure is right for a state change); returns Closed once the actor has stopped — the command receiver dies with it.

pub fn try_mutate( &self, mutate: B::Mutate, ) -> Result<(), TryMutateError<B::Mutate>>

Non-blocking Self::mutate: accept the update into the command buffer or hand it straight back. Exists for callers that must never park on this handle — a consumer that is also the sole drainer of Self::next and awaits mutate while events back up can deadlock against the actor (each side blocked on the channel only the other drains). Such callers keep their own retry queue and stay free to drain.

Full returns the mutate for the caller to retry; Closed returns it for a post-mortem (re-open and re-subscribe from durable cursors).

pub async fn finish(&self) -> Result<(), BidiError>

Half-close the request half — signal that we are done sending. The outbound stream ends, so mutate and probe thereafter return Closed; any live delivery already in flight keeps arriving until the server closes its side. Half-close ends the session. It does not wait for catch-up targets. Use the returned targets to decide when to cancel a bounded sync.

pub async fn probe(&self) -> Result<(), BidiError>

Probe the link (e.g. right after the process resumes) with the default deadline: N × the server’s advertised keepalive interval (a 30s-derived fallback until Started arrives). Resolves Ok on the matching Pong, Closed if the link is already torn down, or ProbeTimedOut if no pong arrives in time — the half-open case this whole mechanism exists to catch.

pub async fn probe_within(&self, timeout: Duration) -> Result<(), BidiError>

Probe with an explicit deadline. A latency-sensitive caller — say a push notification handler that must decide in a couple of seconds whether to reuse the connection or re-open — passes a bound far below the default. A tight bound trades occasional false ProbeTimedOuts for speed, which is safe: re-opening replays from durable cursors and discards duplicates.

The timeout covers the whole probe — submitting the ping (so a stalled wire backpressuring the command queue can’t park us) and awaiting the pong. We deliberately don’t fail-fast on a full command queue: a transient burst of mutates is “busy,” not “dead.”

pub async fn next( &mut self, ) -> Option<Event<B::GroupMessage, B::WelcomeMessage>>

Next event, in wire order. None means the connection ended (server close, network death, watchdog teardown, or reap) — resume from durable cursors on a fresh connection.

Only resolves on an event or end-of-stream, but a half-open link cannot leave it pending forever: the actor’s silence watchdog tears the connection down after [PROBE_TIMEOUT_MULTIPLIER] keepalive intervals with no inbound frame (one watchdog ping in between), and that teardown surfaces here as None. Self::probe remains for callers that need an answer faster than the watchdog budget — e.g. a notification handler deciding within seconds whether to reuse the connection.

pub fn failure(&self) -> Option<Arc<ConnectionFailure>>

Trait Implementations

impl<B: BidiBinding> Drop for Connection<B>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.