pub struct Sandbox { /* private fields */ }Expand description
A loaded, ready-to-run sandbox over a single guest module, bound to one
Subject.
Constructing a Sandbox binds it to a Subject; every call on it runs as that
Subject. Two Sandboxes bound to different Subjects keep independent Store
identity (no shared global/thread-local state) — see the subject_isolation
test.
This is the GENERIC Profile-A core: call_export ships a
byte payload to a named guest export over the guest’s alloc/memory ABI. Language
profile crates (e.g. hyprstream-workers-python) build typed APIs on top of it.
Implementations§
Source§impl Sandbox
impl Sandbox
Sourcepub fn from_bytes(wasm: &[u8]) -> Result<Self>
pub fn from_bytes(wasm: &[u8]) -> Result<Self>
Load a guest module from raw wasm bytes, bound to the anonymous subject.
Sourcepub fn from_bytes_for(wasm: &[u8], subject: Subject) -> Result<Self>
pub fn from_bytes_for(wasm: &[u8], subject: Subject) -> Result<Self>
Load a guest module from raw wasm bytes, bound to subject.
Sourcepub fn with_vfs(self, handle: VfsProxyHandle) -> Self
pub fn with_vfs(self, handle: VfsProxyHandle) -> Self
Grant this sandbox a Subject-scoped VFS capability (env::vfs_*).
The handle should be a vfs::VfsProxyHandle from
spawn_vfs_proxy(ns, subject) with the SAME subject the sandbox is bound to,
so the capability is scoped to this sandbox’s identity. Builder-style.
Sourcepub fn call_export(&self, name: &str, input: &[u8], fuel: u64) -> Result<i32>
pub fn call_export(&self, name: &str, input: &[u8], fuel: u64) -> Result<i32>
Call the named guest export with input shipped into guest memory, under the
given fuel budget.
This is the GENERIC Profile-A entry point. It instantiates a fresh guest
instance, allocates a buffer via the guest’s alloc export, writes input
into it, calls export(ptr, len) -> i32, then deallocs the buffer. Returns
the export’s i32 status on normal completion, or Err if the guest TRAPPED
(e.g. ran out of fuel, or reached an un-granted, trap-wired import).
Deterministic (fuel-bounded); the building block profile modules call.
The guest must export alloc(i32)->i32, dealloc(i32,i32), memory, and the
named export with signature (i32,i32)->i32.
Sourcepub fn engine(&self) -> &Engine
pub fn engine(&self) -> &Engine
The engine backing this sandbox. Spawn an EpochTimer on it to enable the
wall-clock bound used by epoch-deadline call paths (e.g.
Sandbox::call_export_with_epoch).
Sourcepub fn call_export_with_epoch(
&self,
name: &str,
input: &[u8],
ticks: u64,
) -> Result<i32>
pub fn call_export_with_epoch( &self, name: &str, input: &[u8], ticks: u64, ) -> Result<i32>
Like call_export but bounded by a WALL-CLOCK epoch
deadline of ticks epoch increments instead of fuel.
This is the PRODUCTION DoS bound: paired with an EpochTimer spawned on
engine ticking every t, the guest traps with “interrupt”
after roughly ticks * t of wall time. Fuel is set effectively infinite so the
epoch (not fuel) is the limiter. The caller owns the EpochTimer; this method
does not start one. Generic over the named (i32,i32)->i32 export — language
profiles (e.g. python eval) drive their entry through it.
Sourcepub fn open_instance(&self, per_call_fuel: u64) -> Result<PersistentInstance>
pub fn open_instance(&self, per_call_fuel: u64) -> Result<PersistentInstance>
Open a PERSISTENT guest instance over this sandbox for the packed-op ABI.
Unlike call_export (a fresh instance per call), the
returned PersistentInstance holds ONE long-lived Store + Instance, so
guest interpreter state survives across calls. This is the generic substrate a
language profile (e.g. the python shell’s persistent interpreter, whose
/lang/python/vars + /defs semantics depend on persistence) builds on.
per_call_fuel is applied per PersistentInstance::call_op (a fresh budget
each invocation); the store itself is reused. The epoch is pushed out (fuel is
the limiter for this path). The guest must export alloc(i32)->i32,
dealloc(i32,i32), memory, and the packed-op export named in call_op.
Sourcepub fn probe_vfs(&self, op: i32, path: &str, body: &[u8]) -> Result<VfsReply>
pub fn probe_vfs(&self, op: i32, path: &str, body: &[u8]) -> Result<VfsReply>
Drive the guest’s vfs_probe export: make the GUEST call an env::vfs_*
host fn, proving the capability is real end-to-end (guest -> host fn ->
Subject-scoped proxy -> Namespace).
op: 0=cat, 1=ls, 2=echo, 3=ctl. path + optional body (echo/ctl). Returns
the decoded [status][payload] reply the host fn produced — the minimal
“a guest call against a VFS path goes through the Mount” exercise of the
env::vfs_* capability.
Auto Trait Implementations§
impl Freeze for Sandbox
impl !RefUnwindSafe for Sandbox
impl Send for Sandbox
impl Sync for Sandbox
impl Unpin for Sandbox
impl UnsafeUnpin for Sandbox
impl !UnwindSafe for Sandbox
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> GetSetFdFlags for T
impl<T> GetSetFdFlags for T
§fn get_fd_flags(&self) -> Result<FdFlags, Error>where
T: AsFilelike,
fn get_fd_flags(&self) -> Result<FdFlags, Error>where
T: AsFilelike,
self file descriptor.§fn new_set_fd_flags(&self, fd_flags: FdFlags) -> Result<SetFdFlags<T>, Error>where
T: AsFilelike,
fn new_set_fd_flags(&self, fd_flags: FdFlags) -> Result<SetFdFlags<T>, Error>where
T: AsFilelike,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more