Class: Kobako::Sandbox

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/kobako/sandbox.rb

Overview

Kobako::Sandbox — the user-facing entry point for executing guest mruby scripts inside a wasmtime-hosted Wasm module.

The Sandbox owns the Kobako::Runtime, the per-Sandbox Kobako::Catalog::Handles, the per-instance Kobako::Catalog::Namespaces (which receives the Catalog::Handles by injection so guest→host dispatch and host→guest auto-wrap share one allocator), and the dispatch Proc / yield_to_guest lambda installed on the Runtime via Runtime#on_dispatch=. The underlying wasmtime Engine and compiled Module are cached at process scope by the native ext and never surface to Ruby — constructing many Sandboxes amortises both costs automatically.

Output capture policy: the per-channel cap (stdout_limit / stderr_limit) is enforced inside the WASI pipe — the host buffer stops growing at the cap, subsequent guest writes on that channel fail or are dropped, and #run still returns normally. #stdout / #stderr return the captured prefix as a UTF-8 String; the byte content never carries a truncation sentinel. #stdout_truncated? / #stderr_truncated? are the only way to observe that the cap was hit.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil, timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS, memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT) ⇒ Sandbox

Build a fresh Sandbox.

wasm_path is the absolute path to the Guest Binary; defaults to the gem-bundled data/kobako.wasm. The four caps (stdout_limit, stderr_limit, timeout, memory_limit) are forwarded verbatim to Kobako::SandboxOptions, which owns their DEFAULT fallback and normalisation. The constructed SandboxOptions is exposed as #options and the four caps remain readable directly on Sandbox via Forwardable delegation.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/kobako/sandbox.rb', line 92

def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil,
               timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
               memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
  @wasm_path = wasm_path || Kobako::Runtime.default_path
  @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
                                stderr_limit: stderr_limit)
  @handler = Catalog::Handles.new
  @services = Kobako::Catalog::Namespaces.new(handler: @handler)
  @snippets = Catalog::Snippets.new
  @runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
                                       @options.stdout_limit, @options.stderr_limit)
  install_dispatch_proc!
  reset_invocation_state!
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the value of attribute options.



39
40
41
 
# File 'lib/kobako/sandbox.rb', line 39

def options
  @options
end

#usage ⇒ Object (readonly)

Returns the Kobako::Usage value object for the most recent invocation. Carries wall_time (Float seconds the guest export call spent inside wasmtime) and memory_peak (Integer bytes, high-water of the per-invocation memory.grow delta past the entry-time baseline). Returns Kobako::Usage::EMPTY before any invocation; populated on every outcome — including TrapError — so the Host App can read it after rescuing a trap to diagnose budget consumption.



81
82
83
 
# File 'lib/kobako/sandbox.rb', line 81

def usage
  @usage
end

#wasm_path ⇒ Object (readonly)

Returns the value of attribute wasm_path.



39
40
41
 
# File 'lib/kobako/sandbox.rb', line 39

def wasm_path
  @wasm_path
end

Instance Method Details

#define(name) ⇒ Object

Declare or retrieve the Namespace named name on this Sandbox. name must be a Symbol or String in constant form. Returns the Kobako::Namespace.

Raises ArgumentError when called after the first invocation, or when name does not match the constant-name pattern.



113
114
115
 
# File 'lib/kobako/sandbox.rb', line 113

def define(name)
  @services.define(name)
end

#eval(code) ⇒ Object

Execute a guest mruby source string in a fresh mrb_state. code is the mruby source as a UTF-8 String. Returns the deserialized last expression of the source.

Source delivery uses the WASI stdin three-frame protocol (docs/wire-codec.md Invocation channels): Frame 1 carries the msgpack-encoded preamble (Namespace / Member registry snapshot), Frame 2 carries the user source UTF-8 bytes, and Frame 3 carries the snippet table registered via #preload. Each frame is prefixed by a 4-byte big-endian u32 length; Frame 3 is mandatory-presence — an empty snippet table sends an empty msgpack array, never an absent frame.

The first invocation seals the Service registry and snippet table; subsequent #define / #preload calls raise ArgumentError.

Raises Kobako::TrapError on a Wasm trap or wire-violation fallback; Kobako::SandboxError when the guest ran to completion but failed (including when code is nil or not a String, or when a preloaded snippet’s replay raises); Kobako::ServiceError on an unrescued Service capability failure.

Raises:



188
189
190
191
192
193
194
 
# File 'lib/kobako/sandbox.rb', line 188

def eval(code)
  raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)

  invoke!(:eval) do
    @runtime.eval(@services.encode, code.b, @snippets.encode)
  end
end

#preload(code: nil, name: nil, binary: nil) ⇒ Object

Register a snippet on this Sandbox in one of two forms:

* +preload(code: source, name: Name)+ — +source+ is mruby source
  as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. The +name+
  becomes the snippet's +(snippet:Name)+ backtrace filename and
  is the dedupe key that rejects a duplicate +code:+ snippet.
* +preload(binary: bytes)+ — +bytes+ is precompiled RITE
  bytecode as a +String+. The canonical name, when present,
  lives in the bytecode's embedded +debug_info+ and is resolved
  by the guest at load time; the host treats the bytes as
  opaque. Structural failures surface as +Kobako::BytecodeError+
  on the first invocation.

Subsequent invocations (#eval or #run) replay every registered snippet — in insertion order — against the fresh mrb_state before per-invocation source or entrypoint resolution.

Returns self to allow chaining.

Raises ArgumentError when neither form’s keyword set is supplied, when both forms are mixed (e.g., code: and binary: together, or binary: paired with name:), when code / bytes is not a String, when name does not match the constant pattern, when name duplicates an already-registered code: form snippet, or when called after the first invocation has sealed the snippet table.

Raises:

  • (ArgumentError) 


143
144
145
146
147
148
 
# File 'lib/kobako/sandbox.rb', line 143

def preload(code: nil, name: nil, binary: nil)
  raise ArgumentError, "cannot preload after first Sandbox invocation" if @services.sealed?

  @snippets.register(code: code, name: name, binary: binary)
  self
end

#reset_invocation_state! ⇒ Object

Reset all per-invocation observable state to its pre-invocation sentinels — both per-channel captures and the per-last-invocation usage record. Shared by #initialize (first-time setup) and #begin_invocation! (between-invocation reset) so both paths agree on what “pre-invocation state” means; Kobako::Pool calls it at checkout so a pooled Sandbox hands over empty output buffers.



202
203
204
205
206
 
# File 'lib/kobako/sandbox.rb', line 202

def reset_invocation_state!
  @stdout_capture = Capture::EMPTY
  @stderr_capture = Capture::EMPTY
  @usage = Usage::EMPTY
end

#run(target, *args, **kwargs) ⇒ Object

Dispatch into a preloaded entrypoint constant. Delegates host pre-flight and wire encoding to Kobako::Transport::Run / Kobako::Transport::Run#encode: a non-Symbol/String target raises TypeError, while a target failing the constant pattern, a forged Kobako::Handle in args / kwargs, or a non-Symbol kwargs key raise ArgumentError. The guest resolves target as a top-level constant, calls #call on it with args / kwargs, and returns the deserialized result. The first invocation seals the Service registry and snippet table. Runtime errors follow the same three-class taxonomy as #eval.



160
161
162
163
164
165
 
# File 'lib/kobako/sandbox.rb', line 160

def run(target, *args, **kwargs)
  run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
  invoke!(:run) do
    @runtime.run(@services.encode, @snippets.encode, run_envelope.encode(@handler))
  end
end

#stderr ⇒ Object

Returns the bytes the guest wrote to stderr during the most recent invocation as a UTF-8 String, clipped at stderr_limit. Empty before any invocation. Mirror of #stdout.



56
57
58
 
# File 'lib/kobako/sandbox.rb', line 56

def stderr
  @stderr_capture.bytes
end

#stderr_truncated? ⇒ Boolean

Returns true iff stderr capture during the most recent invocation exceeded stderr_limit. Mirror of #stdout_truncated?.

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/kobako/sandbox.rb', line 69

def stderr_truncated?
  @stderr_capture.truncated?
end

#stdout ⇒ Object

Returns the bytes the guest wrote to stdout during the most recent invocation as a UTF-8 String, clipped at stdout_limit. Empty before any invocation; the byte content never contains a truncation sentinel, so use #stdout_truncated? to observe overflow.



49
50
51
 
# File 'lib/kobako/sandbox.rb', line 49

def stdout
  @stdout_capture.bytes
end

#stdout_truncated? ⇒ Boolean

Returns true iff stdout capture during the most recent invocation exceeded stdout_limit. Resets to false at the start of the next invocation.

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/kobako/sandbox.rb', line 63

def stdout_truncated?
  @stdout_capture.truncated?
end