Skip to main content

Sandbox

alien_sdk::traits

Trait Sandbox 

Source 
pub trait Sandbox: Binding {

Show 18 methods    // Required methods
    fn capabilities(&self) -> SandboxCapabilities;
    fn create<'life0, 'async_trait>(
        &'life0 self,
        request: CreateSessionRequest,
    ) -> Pin<Box<dyn Future<Output = Result<SandboxSession, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<SandboxSession>, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn get_or_create<'life0, 'async_trait>(
        &'life0 self,
        request: CreateSessionRequest,
    ) -> Pin<Box<dyn Future<Output = Result<SandboxSession, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn list<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<SandboxSession>, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn run_command<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        request: RunCommandRequest,
    ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<CommandOutput, AlienError<ErrorData>>> + Send>>, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn start_job<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        request: RunCommandRequest,
    ) -> Pin<Box<dyn Future<Output = Result<JobStart, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn poll_job<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        job_id: &'life2 str,
        since_seq: Option<u64>,
    ) -> Pin<Box<dyn Future<Output = Result<JobPoll, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait;
    fn cancel_job<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        job_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait;
    fn read_file<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        path: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait;
    fn write_files<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        files: BTreeMap<String, Vec<u8>>,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn mkdir<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        path: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait;
    fn preview<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        port: u16,
    ) -> Pin<Box<dyn Future<Output = Result<PreviewCapability, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn suspend<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn resume<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn snapshot<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn terminate<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn as_any(&self) -> &(dyn Any + 'static);

}
Expand description

A sandbox binding: create sessions, run untrusted code in them, and tear them down.

Capabilities differ per platform. Call capabilities() and branch, or call and handle the typed error — an unsupported capability is never a silent no-op.

Required Methods§

Source

fn capabilities(&self) -> SandboxCapabilities

What this platform’s backend supports.

Source

fn create<'life0, 'async_trait>( &'life0 self, request: CreateSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<SandboxSession, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Creates a session that can already take work.

Returning before the session can serve pushes a readiness poll into every caller for a condition only the backend can observe, and the resulting race fails a fraction of the time rather than every time. A backend whose start API returns early waits here.

Source

fn get<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<SandboxSession>, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Fetches a session by id, or None if it does not exist.

Requires reconnect. None means the session does not exist; a backend that cannot answer the question returns the typed error instead, so an absent session and an unreachable one are never the same result.

Source

fn get_or_create<'life0, 'async_trait>( &'life0 self, request: CreateSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<SandboxSession, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Fetches a session, creating it if absent.

Source

fn list<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<SandboxSession>, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Lists sessions belonging to this sandbox’s parent.

Offered only where the backend has a verb for it and the grant covers it — GCP lists under its engine. AWS and Azure raise OperationNotSupported: enumerating there costs an account-wide grant the session role deliberately withholds. Reaching a known id is get.

Source

fn run_command<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, request: RunCommandRequest, ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<CommandOutput, AlienError<ErrorData>>> + Send>>, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Runs a command, streaming output frames until exactly one terminal frame.

The stream carries backpressure: a consumer that stops reading stops the sandbox’s writer, rather than buffering without bound.

Source

fn start_job<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, request: RunCommandRequest, ) -> Pin<Box<dyn Future<Output = Result<JobStart, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Starts a command as a job, which outlives the call that started it. Requires jobs.

A start that goes unanswered is SANDBOX_OUTCOME_UNKNOWN and not retryable: the sandbox may have taken the command, and repeating it would run it twice.

Source

fn poll_job<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, job_id: &'life2 str, since_seq: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<JobPoll, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Reads a job’s output after since_seq, and its ending once it has one. Requires jobs.

None reads from the first frame. Repeating a poll costs nothing and changes nothing, so a sandbox that cannot be reached is SANDBOX_UNREACHABLE and retryable.

Source

fn cancel_job<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, job_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Cancels a job, stopping its command. Requires jobs.

Classified like poll_job: a cancel that is repeated stops nothing a second time.

Source

fn read_file<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, path: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Reads a file out of the sandbox. Requires files. Paths are normalised and may not escape the root.

Source

fn write_files<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, files: BTreeMap<String, Vec<u8>>, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Writes files into the sandbox. Requires files.

Source

fn mkdir<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, path: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Creates a directory inside the sandbox. Requires files.

Source

fn preview<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, port: u16, ) -> Pin<Box<dyn Future<Output = Result<PreviewCapability, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Mints a capability to reach a declared port. Requires preview.

Source

fn suspend<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Suspends a session, preserving state. Requires suspendResume.

Source

fn resume<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Resumes a suspended session. Requires suspendResume.

Source

fn snapshot<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Captures full session state and returns its identifier. Requires snapshot.

Source

fn terminate<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), AlienError<ErrorData>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Terminates a session. Idempotent: terminating an absent session succeeds.

Source

fn as_any(&self) -> &(dyn Any + 'static)

Get a reference to this object as Any for dynamic casting

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§