Skip to main content

Sandbox

Struct Sandbox 

Source
pub struct Sandbox {
    pub id: String,
    pub name: String,
    pub commands: Commands,
    pub files: Files,
    /* private fields */
}
Expand description

A handle to one sandbox. Cloning is cheap; clones refer to the same sandbox. The sandbox runs one command at a time: concurrent calls queue in the plane.

Deleting is explicit: call Sandbox::kill, or use Sandbox::with, which deletes the sandbox when its closure returns. Dropping a Sandbox leaves the sandbox running (it parks when idle and is discarded after 5 days).

Fields§

§id: String

The short ID (8 hex characters), usable with Sandbox::connect.

§name: String

The full resource name (instances/<org>/sessions/<id>).

§commands: Commands

Runs commands in the sandbox.

§files: Files

Reads and writes the sandbox’s filesystem.

Implementations§

Source§

impl Sandbox

Source

pub async fn create(o: CreateOptions) -> Result<Sandbox>

Starts a new sandbox and returns when it can run commands (about 8–20 seconds). On failure it deletes anything it created. A session the plane places on a host that never starts is deleted and recreated (up to three attempts).

Source

pub async fn with<T, F>(o: CreateOptions, f: F) -> Result<T>
where F: AsyncFnOnce(&Sandbox) -> Result<T>,

Creates a sandbox, runs f with it, and deletes the sandbox afterwards, whether f succeeds or fails. If the returned future is dropped early or f panics, the delete is started in the background instead.

use chainguard_sandbox::{CreateOptions, Sandbox};
let out = Sandbox::with(CreateOptions::default(), async |sbx| {
    Ok(sbx.commands.run("echo hi").await?.stdout)
})
.await?;
Source

pub async fn connect(id: &str, o: ConnectOptions) -> Result<Sandbox>

Returns a handle to an existing sandbox by short ID, display name or resource name. A paused sandbox resumes on its first command.

Source

pub async fn kill(&self) -> Result<bool>

Deletes the sandbox and everything in it, and returns once it is gone, so the session slot is free for a new sandbox. Returns false if the sandbox was already gone. If it still exists 30 seconds after the delete request (or its disappearance can’t be confirmed), the error is Error::Timeout with op “kill”: the deletion was requested but the slot may not be free yet.

Source

pub async fn pause(&self) -> Result<()>

Snapshots the sandbox (memory and disk) and stops it. Running processes, including background commands, resume where they were on the next command or file operation.

Source

pub async fn keep_alive(&self, d: Duration) -> Result<()>

Asks the plane to hold the sandbox running (not park it when idle) for d. An idle sandbox parks after about 10 minutes, and a parked one is discarded after 5 days.

Source

pub async fn get_info(&self) -> Result<Info>

Fetches the sandbox’s current state.

Source

pub async fn is_running(&self) -> Result<bool>

Whether the sandbox is running (not paused, stopped or still starting).

Source

pub fn client(&self) -> &Client

The underlying Workspaces client, for anything this API doesn’t wrap.

Trait Implementations§

Source§

impl Clone for Sandbox

Source§

fn clone(&self) -> Sandbox

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Sandbox

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoRequest<T> for T

§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
§

impl<L> LayerExt<L> for L

§

fn named_layer<S>(&self, service: S) -> Layered<<L as Layer<S>>::Service, S>
where L: Layer<S>,

Applies the layer to a service and wraps it in [Layered].
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more