Struct PreparedSession 

pub struct PreparedSession { /* private fields */ }

A session that has been configured but not yet created on the CLI.

Returned by Client::prepare_session and Client::prepare_resume_session. Its purpose is to make the session’s event stream observable before any protocol activity starts: subscribe installs a receiver on the same broadcast channel the eventual Session uses, so events the runtime emits while session.create / session.resume is still in flight are delivered rather than dropped for lack of a receiver.

Lifecycle

A prepared handle is inert. It holds only a broadcast sender, a cancellation token, the client handle, and the config — it performs no router registration, spawns no task, and writes nothing to the wire until start is first polled.

• Dropping it without starting leaves no client-side or server-side state, and closes every subscription taken from it.
• Dropping the start future mid-flight cancels the session token, unregisters the session from the router if it was registered, and closes early subscriptions. A retry with the same session ID succeeds. Cleanup of already-spawned tasks is signalled, not awaited: Drop is synchronous and cannot await, so the event loop terminates promptly but not synchronously.
• A startup error from start performs the same cleanup and preserves the ErrorKind the equivalent Client::create_session / Client::resume_session call has always returned.

start consumes self and the type is deliberately not Clone, so a prepared session can be started at most once and can never produce two event loops.

Buffering

The broadcast buffer is finite — DEFAULT_EVENT_BUFFER_CAPACITY unless SessionConfig::event_buffer_capacity / ResumeSessionConfig::event_buffer_capacity overrides it. Subscribers that fall behind observe Lagged instead of applying backpressure to the event loop. Consumers that need a lossless view of a large startup burst must either configure a capacity that covers it or drain the subscription concurrently with start.

Server-assigned session IDs

For cloud sessions without a caller-supplied session ID, the CLI assigns the ID and the SDK can only register the session on its notification router once the session.create response arrives. Notifications the server emits before that point are not routable to any session and are therefore not observable. The guarantee this type provides is narrower and precise: routed events are never dropped for lack of an installed receiver. Pin SessionConfig::session_id to get registration before the RPC and full pre-response coverage.

Implementations

impl PreparedSession

pub fn subscribe(&self) -> EventSubscription

Subscribe to this session’s events before it starts.

The returned EventSubscription is backed by the same broadcast channel Session::subscribe returns after start succeeds, so a subscription taken here observes the full event stream from the session’s first routed event onward — including ephemeral events such as session.idle that Session::get_messages cannot recover.

May be called any number of times, and each subscriber receives its own copy of the stream — subject to the buffering contract above. A subscriber that falls further behind than the configured capacity observes Lagged and skips the events it missed, rather than stalling the session’s event loop. Subscriptions taken here close if the prepared session is dropped without starting, or if startup fails.

pub async fn start(self) -> Result<Session, Error>

Create or resume the session on the CLI.

This is where all protocol activity happens: config validation, router registration, the session.create / session.resume RPC, and the event loop spawn. Nothing observable occurs until this future is first polled.

Errors

Returns the same errors as Client::create_session / Client::resume_session — including ErrorKind::InvalidConfig for invalid configs, transport and RPC failures, and SessionIdMismatch when the CLI returns a different session ID than the one requested. Every error path unregisters the session and closes subscriptions taken from this handle.