security_box 0.2.0 → 0.5.0

data/lib/security_box/runtime.rb

@@ -41,6 +41,23 @@ module SecurityBox
         end
       end
 
+      # Builds a dedicated (not memoized) Engine + Module pair prepared for
+      # use across Ractors: the epoch timer is started and the precompile
+      # key is touched BEFORE freezing, then both artifacts are made
+      # Ractor-shareable (stage-3 Q2 "Plan C"). The pair is not stored in the
+      # class memos — freezing shared artifacts would affect every Sandbox —
+      # so each RactorPool pays one module deserialize (~0.5s via the disk
+      # cache). Callers must treat the returned pair as immutable.
+      def build_shareable(image_path:, epoch_interval_ms:)
+        engine = build_engine(epoch_interval_ms)
+        module_ = ModuleCache.load_module(engine, image_path) ||
+                  ModuleCache.compile_and_store(engine, image_path)
+        engine.precompile_compatibility_key # touch before make_shareable
+        Ractor.make_shareable(engine)
+        Ractor.make_shareable(module_)
+        [engine, module_]
+      end
+
       private
 
       def build_engine(epoch_interval_ms)

data/lib/security_box/sandbox.rb

@@ -1,161 +1,50 @@
 # frozen_string_literal: true
 
-require "json"
-require "securerandom"
-require "tmpdir"
+require_relative "eval_run"
 
 module SecurityBox
   # :oneshot mode sandbox — one wasm instance per #eval.
   #
-  # Flow:
-  #   1. exclusive tmpdir mounted as /work (read-write)
-  #   2. user code written to /work/code.rb
-  #   3. a per-eval random token is passed via ENV (SB_TOKEN); the guest
-  #      prelude captures it and scrubs ENV before user code runs
-  #   4. guest (/src/main.rb) evaluates the code and writes /work/out.json,
-  #      embedding the token (stdout sentinel fallback does the same)
-  #   5. host reads the envelope, validates schema + token (untrusted results
-  #      become a sandbox failure) and returns a Result
+  # The sandbox itself is stateless and cheap: it holds references to the
+  # shared runtime artifacts (Engine + compiled Module, both memoized in
+  # Runtime) and a WASI Linker. Each #eval runs the shared EvalRun core: an
+  # exclusive tmpdir mounted as /work, a per-eval token, fuel + epoch
+  # deadlines, and a validated result envelope.
+  #
+  # Thread safety: Engine/Module/Linker are thread-safe and the eval core is
+  # self-contained, so a single Sandbox can be used from multiple threads
+  # (evals serialize on the GVL — see RactorPool for real parallelism).
   class Sandbox
-    GUEST_ENTRYPOINT = "/src/main.rb"
-    RESULT_FILE = "out.json"
-    CODE_FILE = "code.rb"
-    TOKEN_ENV_VAR = "SB_TOKEN"
-
     def initialize(configuration = Configuration.build)
       @config = configuration
       @engine = Runtime.engine(epoch_interval_ms: @config.epoch_interval_ms)
       @module = Runtime.module_for(@engine, @config.image_path)
+      @linker_mutex = Mutex.new
     end
 
     # Runs `code` in the sandbox and returns a Result.
     # Per-call options (derived from the configuration without mutating it):
-    #   timeout_ms:, fuel:, memory_size:, stdout_limit:, stderr_limit:
+    #   timeout_ms:, fuel:, fuel_ms:, memory_size:, stdout_limit:, stderr_limit:,
+    #   mounts: (replaces the configuration's mounts, like env:)
     def eval(code, **overrides)
       raise ArgumentError, "code is required" if code.nil? || code.empty?
 
       config = overrides.empty? ? @config : @config.with(**overrides)
-      stdout = +""
-      stderr = +""
+      # SecureRandom is not guaranteed Ractor-safe; EvalRun callers generate
+      # the token in the main Ractor/thread.
       token = SecureRandom.hex(16)
-      t0 = monotonic_ms
-
-      Dir.mktmpdir("security_box") do |workdir|
-        File.write(File.join(workdir, CODE_FILE), code)
-        envelope = nil
-        status = nil
-        fuel_used = nil
-
-        store = Wasmtime::Store.new(
-          @engine,
-          wasi_p1_config: build_wasi(workdir, stdout, stderr, config, token),
-          limits: { memory_size: config.memory_size }
-        )
-        begin
-          store.set_fuel(config.fuel)
-          instance = build_linker.instantiate(store, @module)
-          store.set_epoch_deadline(epoch_ticks(config))
-          status = invoke_guest(instance, store)
-          fuel_used = config.fuel - store.get_fuel
-          envelope = read_envelope(workdir, stdout, token)
-        ensure
-          store.close
-        end
-
-        build_result(status, envelope, stdout, stderr, fuel_used, monotonic_ms - t0)
-      end
+      EvalRun.run(engine: @engine, module_: @module, linker: linker,
+                  config: config, code: code, token: token)
     end
 
     private
 
-    def build_wasi(workdir, stdout, stderr, config, token)
-      Wasmtime::WasiConfig.new
-        .set_stdin_string("")
-        .set_stdout_buffer(stdout, config.stdout_limit)
-        .set_stderr_buffer(stderr, config.stderr_limit)
-        .set_argv(["ruby", GUEST_ENTRYPOINT])
-        .set_env(config.env.merge(TOKEN_ENV_VAR => token))
-        .set_mapped_directory(workdir, "/work", :read_write)
-    end
-
-    def build_linker
-      @linker ||= Wasmtime::Linker.new(@engine).tap do |linker|
-        Wasmtime::WASI::P1.add_to_linker_sync(linker)
-      end
-    end
-
-    def epoch_ticks(config)
-      [config.timeout_ms / config.epoch_interval_ms + 1, 1].max
-    end
-
-    def invoke_guest(instance, store)
-      instance.invoke("_start")
-      :ok
-    rescue Wasmtime::WasiExit => e
-      handle_wasi_exit(e, store)
-    rescue Wasmtime::Trap => e
-      map_trap(e, store)
-    rescue Wasmtime::Error
-      # Unexpected runtime error (non-trap): treated as a sandbox failure.
-      :sandbox_error
-    end
-
-    def handle_wasi_exit(exit_error, store)
-      # The guest rescues SystemExit; a WasiExit here means exit! or a guest crash
-      # before the envelope was written.
-      store.linear_memory_limit_hit? ? :memory_limit : :sandbox_error
-    end
-
-    def map_trap(trap, store)
-      case trap.code
-      when :interrupt then :timeout
-      when :out_of_fuel then :fuel_exhausted
-      when :memory_out_of_bounds then :memory_limit
-      else
-        store.linear_memory_limit_hit? ? :memory_limit : :sandbox_error
-      end
-    end
-
-    def read_envelope(workdir, stdout, token)
-      # Preferred channel: /work/out.json. Fallback: sentinel line on stdout.
-      # Both go through the same strict validation (schema + token).
-      Envelope.parse(read_result_file(workdir), token) ||
-        Envelope.from_stdout(stdout, token)
-    end
-
-    def read_result_file(workdir)
-      File.read(File.join(workdir, RESULT_FILE))
-    rescue SystemCallError
-      nil
-    end
-
-    def build_result(status, envelope, stdout, stderr, fuel_used, duration_ms)
-      if envelope.nil?
-        status = :sandbox_error if status == :ok
-        return Result.new(
-          status: status, stdout: stdout, stderr: stderr,
-          fuel_used: fuel_used, duration_ms: duration_ms
-        )
-      end
-
-      guest_error = envelope["error"]
-      if envelope["ok"]
-        Result.new(
-          status: status, value: envelope["value"], stdout: stdout, stderr: stderr,
-          fuel_used: fuel_used, duration_ms: duration_ms,
-          guest_duration_ms: envelope["duration_ms"]
-        )
-      else
-        Result.new(
-          status: :error, error: guest_error, stdout: stdout, stderr: stderr,
-          fuel_used: fuel_used, duration_ms: duration_ms,
-          guest_duration_ms: envelope["duration_ms"]
-        )
+    def linker
+      @linker_mutex.synchronize do
+        @linker ||= Wasmtime::Linker.new(@engine).tap do |linker|
+          Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        end
       end
     end
-
-    def monotonic_ms
-      Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
-    end
   end
 end

data/lib/security_box/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecurityBox
-  VERSION = "0.2.0"
+  VERSION = "0.5.0"
 end

data/lib/security_box.rb

@@ -3,11 +3,15 @@
 require_relative "security_box/version"
 require_relative "security_box/errors"
 require_relative "security_box/configuration"
+require_relative "security_box/registry"
 require_relative "security_box/result"
 require_relative "security_box/module_cache"
 require_relative "security_box/runtime"
 require_relative "security_box/envelope"
 require_relative "security_box/sandbox"
+require_relative "security_box/eval_run"
+require_relative "security_box/pool"
+require_relative "security_box/ractor_pool"
 
 module SecurityBox
   # Convenience shortcut:
@@ -17,6 +21,48 @@ module SecurityBox
     Sandbox.new.eval(code, **overrides)
   end
 
+  # Registers a named, reusable profile (see Registry).
+  #   SecurityBox.register(:lean, from: :default) { |c| c.fuel 5_000_000 }
+  def self.register(name, from: nil, &block)
+    Registry.register(name, from: from, &block)
+  end
+
+  # Builds a Sandbox from a registered profile, a Configuration, or the
+  # defaults:
+  #   SecurityBox.spawn(:lean)                  # named profile
+  #   SecurityBox.spawn(:lean, fuel: 1_000)     # profile + per-call overrides
+  #   SecurityBox.spawn(my_config)              # explicit configuration
+  #   SecurityBox.spawn                         # default configuration
+  def self.spawn(profile = nil, **overrides)
+    config = case profile
+             when nil then Configuration.build(**overrides)
+             when Symbol, String
+               resolved = Registry.resolve(profile)
+               overrides.empty? ? resolved : resolved.with(**overrides)
+             when Configuration
+               overrides.empty? ? profile : profile.with(**overrides)
+             else
+               raise ArgumentError,
+                     "profile must be a registered name or a Configuration, got #{profile.class}"
+             end
+    Sandbox.new(config)
+  end
+
+  # Builds a Pool of :oneshot sandboxes (bounded concurrency on threads).
+  # NOTE: evals serialize on the GVL — see RactorPool for parallelism.
+  #   SecurityBox.pool(:lean, size: 4).eval("1 + 1")
+  def self.pool(profile = nil, size: 4, **overrides)
+    Pool.new(profile, size: size, **overrides)
+  end
+
+  # Builds a RactorPool (real parallelism: worker Ractors sharing one
+  # Engine+Module). Costs one module deserialize at creation (~0.5s via the
+  # disk cache); each eval still pays the guest boot (~240ms).
+  #   SecurityBox.ractor_pool(:lean, size: 4).eval("1 + 1")
+  def self.ractor_pool(profile = nil, size: 4, **overrides)
+    RactorPool.new(profile, size: size, **overrides)
+  end
+
   # Prepares the shared runtime artifacts (Engine + compiled Module) ahead of
   # time so the first #eval skips the cold module compilation (~15s per
   # process). #eval warms these caches lazily on first use, so calling

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -41,9 +41,13 @@ files:
 - lib/security_box/configuration.rb
 - lib/security_box/envelope.rb
 - lib/security_box/errors.rb
+- lib/security_box/eval_run.rb
 - lib/security_box/guest/main.rb
 - lib/security_box/guest/prelude.rb
 - lib/security_box/module_cache.rb
+- lib/security_box/pool.rb
+- lib/security_box/ractor_pool.rb
+- lib/security_box/registry.rb
 - lib/security_box/result.rb
 - lib/security_box/runtime.rb
 - lib/security_box/sandbox.rb