Struct RemoteParticipantHandle 

pub struct RemoteParticipantHandle<S> { /* private fields */ }

Remote participant entrypoint backed by protocol-crate state and canonical LPCR storage.

Records are deliberately not promised as generally successful: the reduced-B1 server surface fails fully authorized RecordAdmission and Leave closed until live claim-frontier acquisition lands (docs/design/LP-GAP-CLOSURE-GOAL.md:145).

Implementations

impl<S: ParticipantResumeStore> RemoteParticipantHandle<S>

pub fn recover_expected_operation( &self, ) -> Result<RemoteExpectedOperationRecovery, RemoteParticipantError>

Releases one unissued operation from committed cold-restored state.

Errors

Returns RemoteParticipantError::StateUnavailable after a prior fatal durability failure.

pub fn resolve_lost_operation_authority( &self, ) -> Result<RemoteLostOperationResolution, RemoteParticipantError>

Consumes operation-domain lost-authority testimony exactly once.

Errors

Returns LPCR encode or storage failures while checkpointing the decision.

pub fn take_restored_operation_abandonment( &self, ) -> Result<Option<RestoredExpectedOperationAbandonment>, RemoteParticipantError>

Takes a durable tokenless abandonment so its exact request can be re-recorded.

Errors

Returns LPCR encode or storage failures while durably recording the take.

pub fn record_transport_fate( &self, ) -> Result<RemoteReconnectPermitOutcome, RemoteParticipantError>

Records established-connection fate and returns at most one reconnect permit.

Errors

Returns LPCR encode or storage failures while checkpointing the event.

pub fn record_online_transition( &self, ) -> Result<RemoteReconnectPermitOutcome, RemoteParticipantError>

Records a proved online transition as a crate fresh event.

Errors

Returns LPCR encode or storage failures while checkpointing issued authority.

pub fn record_explicit_reconnect( &self, ) -> Result<RemoteReconnectPermitOutcome, RemoteParticipantError>

Records explicit caller action as a crate fresh event, with no timer arm.

Errors

Returns LPCR encode or storage failures while checkpointing issued authority.

pub fn recover_reconnect_permit( &self, ) -> Result<RemoteReconnectPermitRecovery, RemoteParticipantError>

Releases one unissued reconnect permit from committed cold-restored state.

Errors

Returns RemoteParticipantError::StateUnavailable after a prior fatal failure.

pub fn resolve_lost_reconnect_authority( &self, ) -> Result<RemoteLostReconnectResolution, RemoteParticipantError>

Consumes reconnect-domain lost-authority testimony exactly once.

Errors

Returns LPCR encode or storage failures while checkpointing the resolution.

pub fn reconnect( &self, permit: RemoteReconnectPermit, ) -> Result<RemoteReconnectAttemptOutcome, RemoteParticipantError>

Redeems one permit before opening one real transport connection.

Errors

Returns LPCR encode or storage failures before or after the real attempt.

pub fn record_established_transport_loss( &self, ) -> Result<RemoteTransportLossOutcome, RemoteParticipantError>

Records response and connection fates after an established transport loss.

Errors

Returns LPCR encode or storage failures while checkpointing both decisions.

pub fn replay_detach( &self, ) -> Result<RemoteDetachReplayOutcome, RemoteParticipantError>

Starts and sends the exact parked detach replay selected by the crate.

Errors

Returns LPCR, storage, or state failures. Socket failure is a typed send outcome.

impl<S: ParticipantResumeStore> RemoteParticipantHandle<S>

pub fn apply_attach( &self, attach: AttachBound, ) -> Result<RemoteReplayApplyOutcome<AttachBound>, RemoteParticipantError>

Delegates an attach supersession input with the held one-use correlation.

Errors

Returns when no response authority exists or persistence fails.

pub fn apply_leave_durable( &self, leave: LeaveCommitted, ) -> Result<RemoteReplayApplyOutcome<LeaveCommitted>, RemoteParticipantError>

Delegates a durable Leave supersession input with held correlation.

Errors

Returns when no response authority exists or persistence fails.

pub fn apply_detach_outcome( &self, outcome: DetachReplayOutcome, ) -> Result<RemoteReplayApplyOutcome<DetachReplayOutcome>, RemoteParticipantError>

Delegates one typed terminal detach outcome with held correlation.

Errors

Returns when no response authority exists or persistence fails.

impl<S: ParticipantResumeStore> RemoteParticipantHandle<S>

pub fn new( config: &RemoteConfig, store: S, ) -> Result<Self, RemoteParticipantError>

Creates and durably checkpoints a fresh unbound participant.

Errors

Returns a typed encode or storage error before the handle is exposed.

pub fn restore( config: &RemoteConfig, store: S, canonical_lpcr: &[u8], ) -> Result<Self, RemoteParticipantError>

Decodes, validates, restores, and durably records crash testimony before exposure.

Errors

Returns typed LPCR decode/restore, encode, or storage errors.

pub fn unavailability_cause(&self) -> Option<SdkError>

Returns the store failure that made this handle unavailable, if that is why it is unavailable.

RemoteParticipantError::StateUnavailable names a CONDITION and carries no cause: a handle reports it on every call after a durability failure bricked it, long after the failure itself was returned to the one caller who happened to make the failing call. Every later caller sees an unavailability it cannot attribute, and the only thing distinguishing a store-originated hold from any other was the rendered text of an error nobody still holds.

A Some names the exact SdkError the caller’s own store returned, so a hold can be attributed by matching a typed value. A None means the handle is either live or unavailable for a reason that did not originate in the store — which is itself the discrimination this exists to provide.

This is deliberately an accessor rather than a payload on StateUnavailable. Carrying the source on the variant is the better shape and remains the intended destination, but these enums are exhaustive by a standing ruling so a consumer can match them and be told when a case is added; changing that variant is therefore a breaking change and not this lane’s to make.

pub fn record_operation( &self, request: ClientRequest, ) -> Result<RemoteOperationRecordOutcome, RemoteParticipantError>

Runs record_operation -> commit -> LPCR persist -> into_parts exactly.

Errors

Returns typed resume encoding or storage failures. A failed post-commit persistence leaves the handle unavailable and releases no authority.

pub fn send_operation( &self, operation: RemoteParticipantOperation, ) -> Result<RemoteParticipantSendOutcome, RemoteParticipantError>

Persists issued state, writes the exact operation, and retains correlation.

Errors

Returns typed state, LPCR, or storage failures. Transport failures are returned as a typed outcome after crate fate delegation.

pub fn receive( &self, ) -> Result<RemoteParticipantInbound, RemoteParticipantError>

Receives one real participant frame and delegates every ServerValue to the crate.

The contract, and why it is this one

THIS IS THE REPLY-OWED DOOR. It blocks for up to the transport’s full response deadline (60 s), because the caller it is written for has just sent a request and is waiting for the correlated answer — and there, a quiet connection means a slow server, not a dead one. Ending that wait early is the 2026-08-10 outage’s client-side mechanism, so this method keeps the deadline unchanged and unconditionally.

A consumer PUMPING an idle connection — looping to collect whatever the server pushes next, where silence is a normal state rather than a fault — must use receive_within or try_receive instead. That is not a preference: a drain loop built on this method waits out the full deadline on every quiet read, which is how a 30 s boot gate blows on a healthy server.

The split is by CALLER INTENT and cannot be anything else. At a clean frame boundary with an empty buffer, a pump read and an outage-shaped reply-owed read are byte-for-byte identical states; only the caller knows which one it is making, so only the caller’s choice of method can carry it. Inferring it from buffered bytes, or from whether an operation is outstanding, would silently shorten the deadline for some class of genuinely reply-owed read and re-open the outage for it.

Pushed deliveries are at-least-once: the same (conversation_id, delivery_seq) may arrive more than once on one healthy connection, byte-identical each time — deduplicate on the pair (participant contract R-C3, amendment A3).

Errors

Returns transport, direction, LPCR encoding, or storage failures.

pub fn receive_within( &self, budget: Duration, ) -> Result<Option<RemoteParticipantInbound>, RemoteParticipantError>

Receives one participant frame if one arrives within budget, reporting a quiet connection as Ok(None) instead of an error.

THE PUMP DOOR — the lawful read for a consumer that is owed nothing. Ok(None) means “no frame within this window”, which is a normal state on a healthy connection and never a fault; a real transport failure still returns Err, and a quiet window never surfaces a raw errno.

budget is the CALLER’S bound and is spent across as many transport read windows as it takes. It never shortens anything else: a caller that uses this method to await a correlated answer simply names its own deadline, and passing one at or above the transport’s 60 s response deadline reproduces receive’s patience with a typed silence at the end instead of an error.

Duration::ZERO polls only what has already decoded, without arming a read. Bytes of a partly-arrived frame stay buffered across an Ok(None), so a frame that was mid-flight when the budget expired is never lost — the next call resumes on it.

Errors

Returns transport, direction, LPCR encoding, or storage failures. A quiet window is NOT one of them.

pub fn try_receive( &self, ) -> Result<Option<RemoteParticipantInbound>, RemoteParticipantError>

One PARTICIPANT_PUMP_WINDOW of patience, then Ok(None).

The drain-loop convenience over receive_within: a consumer that wants “give me the next frame, or tell me the connection is quiet” without choosing a number. Loop it until it answers Ok(None) and the backlog is drained.

Errors

As receive_within.

Trait Implementations

impl<S> Debug for RemoteParticipantHandle<S>

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

Formats the value using the given formatter.