Struct Session 

pub struct Session { /* private fields */ }

The control API of one running MicroVM.

Clone shares the transport, including the cached proxy token, so a clone moved into a background task (a keepalive) sees the same refresh a resume triggers.

Implementations

impl Session

pub async fn run_to_completion( &self, request: StartRequest, options: CompletionOptions, on_output: Option<OutputSink>, ) -> Result<ExecResult, Error>

Starts request and drives it to exactly one result. See the module docs.

impl Session

pub fn agent_token(&self) -> &str

The bearer this session authenticates with.

Public because a caller who launched with a minted token needs to read it back to reattach later (the Python oracle’s Session.agent_token property, and what the CLI’s run envelope publishes for microvm exec --agent-token). The value is still kept out of Debug — readable on purpose is different from printed by accident.

pub async fn connect( endpoint: impl Into<String>, agent_token: impl Into<String>, minter: Arc<dyn TokenMinter>, ) -> Result<Session, Error>

A session against endpoint, minting proxy tokens through minter.

Does not talk to the VM. Constructing a session is free and re-doable, and a constructor that probed would make “do I have a session” mean “is the VM up”, which are different questions with different answers during a launch.

pub async fn attach( region: Region, microvm_id: impl Into<String>, endpoint: impl Into<String>, agent_token: impl Into<String>, port: Option<u16>, request_timeout: Option<Duration>, ) -> Result<Self, Error>

Reattach to an existing AWS VM using a privately retained agent token.

Resolves AWS credentials but does not probe the guest or bootstrap it again. The returned session is independent of any sandbox lock: use a separate attach with a short request timeout for supervisor keepalives during long transfers. Keep agent_token in private encrypted storage, never in public job status.

pub fn direct( endpoint: impl Into<String>, agent_token: impl Into<String>, ) -> Result<Session, Error>

A session with no proxy auth, for a daemon reached directly.

The conformance path and every local-binary test go through here. See Transport::proxy on why this is a supported shape rather than a test-only escape hatch.

pub fn builder( endpoint: impl Into<String>, agent_token: impl Into<String>, ) -> SessionBuilder

A builder, for the cases that need a port, a timeout, or a custom backend.

pub fn endpoint(&self) -> &str

The endpoint this session addresses.

pub fn egress_posture(&self) -> EgressPosture

The egress posture of the launch this session addresses (BIND-12).

The value the CLI envelope’s egressPosture reports for the same launch options, set by crate::sandbox::Sandbox::run from crate::control::egress_posture_for. A session that does not hold its launch options (attached, direct, or adopted) reports unsealed, the weakest true claim. Never sealed: see crate::control::egress_posture_for for the evidence that needs.

pub fn port(&self) -> u16

The port the proxy token is scoped to.

pub fn proxy_auth(&self) -> Option<&Arc<ProxyAuth>>

The proxy auth, for a caller that needs the mint count or an invalidation.

pub async fn connect_headers( &self, port: u16, ) -> Result<Vec<(String, String)>, Error>

Both proxy headers for port, minted through this session’s token cache.

The {url, headers} half of a port-endpoint resolution: pair these with Self::endpoint and a caller can open its own connection with no knowledge of how the token is minted or when it refreshes.

Empty for a direct session, which is the correct answer rather than a missing one: a daemon reached directly takes no proxy headers, so an empty set is exactly what its requests carry today (see Transport::proxy).

The auth value is a bearer credential and this returns it. Nothing in this crate logs or stores the result.

pub async fn connect_subprotocols( &self, port: u16, ) -> Result<Option<[String; 3]>, Error>

The three WebSocket subprotocols for port, minted through this session’s token cache.

None for a direct session, and that is deliberately not an empty list: the subprotocol form exists only because a request through the endpoint proxy cannot set headers, so there is nothing for a directly-reached daemon to offer, and a caller handed ["lambda-microvms"] with no token would open a handshake that is refused for a reason naming neither.

See ProxyAuth::subprotocols for the wire format and for the platform’s stripping behaviour. The middle value carries the credential.

pub fn rebind(&mut self, endpoint: String)

Points the session at a new endpoint and drops the cached proxy token (STATE-8).

The measured behaviour is that the endpoint URL does not change across suspend/resume, so this is usually a no-op on the URL — but the token drop is not: a token minted against the pre-suspend instance may no longer validate, and that rejection reads exactly like a dead daemon.

Takes &mut self because it changes where the session points, which is not something a shared reference should be able to do mid-request. The invalidation itself is &self on ProxyAuth, so a resume path holding only the auth can still drop the token.

pub async fn health(&self) -> Result<Health, Error>

Unauthenticated liveness. bootstrapped is the useful field.

Reachable through the endpoint at all implies bootstrapped in practice — the platform forwards no external traffic until the run hook returns 200 — but a caller inside the VM, or one talking to the daemon directly, can observe the pre-bootstrap state.

pub async fn keep_awake( &self, policy: &KeepAwake, stop: impl Future<Output = ()>, ) -> Result<KeepAwakeReport, Error>

Keeps the VM awake by polling health until stop resolves or the policy ends it.

See keepalive: idleness is inbound traffic only, so this is the supported way to hold a VM up while an exec works without client traffic.

pub async fn wait_until_ready(&self, timeout: Duration) -> Result<Health, Error>

Polls health until the daemon reports bootstrapped.

Connection errors are expected here rather than exceptional: a VM that has just reached RUNNING commonly refuses a connection or two before the proxy path is wired up, and a mint failure is retryable by construction. A fatal error ends the wait immediately — retrying a 401 until the deadline is one of the two mistakes the retryable split exists to prevent.

pub async fn run(&self, req: StartRequest) -> Result<ExecHandle, Error>

Starts a command and returns its handle. Does not wait.

The exec_id on the request is the idempotency key. The daemon returns success for a known id without spawning a second child, so a caller whose retry must be safe across its own restart supplies a stable one.

pub fn exec(&self, exec_id: impl Into<String>) -> ExecHandle

A handle for an exec started earlier, possibly by another process.

pub async fn run_sync( &self, req: StartRequest, timeout: Duration, ) -> Result<ExecResult, Error>

Start, wait, ack. The one-shot shape, for when output is all you want.

pub async fn kill(&self, exec_id: &str) -> Result<bool, Error>

Signals an exec’s whole process group. Returns whether anything was signalled.

pub async fn procs(&self) -> Result<ProcsResponse, Error>

Process accounting: every registered exec with its group’s live pids.

The daemon reads /proc itself, so this works against a guest with no ps. child_exited: true beside a non-empty pids is a command that finished while something it backgrounded did not; the exec_id beside it is what Self::kill takes. Bearer-guarded, unlike Self::health: the answer names every pid in the guest, and a caller without the token has no business with it.

pub async fn upload_file( &self, path: &str, data: &[u8], mode: Option<&str>, ) -> Result<(), Error>

Writes one file, creating parents. mode is octal as a string.

pub async fn download_file(&self, path: &str) -> Result<Vec<u8>, Error>

Reads one file.

pub async fn file_exists(&self, path: &str) -> Result<bool, Error>

Whether a path exists, distinguishing absence from every other refusal.

pub async fn upload_tar( &self, remote: &str, archive: &[u8], ) -> Result<(), Error>

Extracts pre-built tar bytes under remote.

pub async fn download_tar(&self, remote: &str) -> Result<Vec<u8>, Error>

The raw tar bytes of a remote tree.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

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

Formats the value using the given formatter.