Package com.tnsai.quality.sandbox

Interface Sandbox

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
ContainerSandbox, ObservedSandbox, ProcessSandbox, SandboxPool.Lease
public interface Sandbox extends AutoCloseable
A live sandbox instance (TNS-296). Implementations execute untrusted code through their backend's strongest available boundary (process, container, microVM, WASM); the consumer interacts through a single contract regardless of backend. Backend-specific guarantees and limitations remain part of each implementation's contract.

Lifecycle

  1. SandboxFactory.create(com.tnsai.quality.sandbox.SandboxSpec) returns a Sandbox in the started state — the backend has reserved resources but no process is running yet.
  2. execute(com.tnsai.quality.sandbox.Command) runs one command to completion (or to the ResourceLimits.timeout budget). May be called repeatedly inside the same sandbox lifetime — useful for interactive runners and pool-warmed sandboxes.
  3. stop() performs a graceful shutdown — the backend sends SIGTERM (or equivalent) and waits a short grace period before terminating.
  4. terminate() forcibly kills the sandbox and releases its resources. Idempotent; safe to call from a finally block.

Concurrency

A Sandbox is NOT thread-safe — execute must not be called concurrently on the same instance. Callers needing concurrency use a SandboxPool.
Since:
0.10.0 (TNS-296)

  • Method Details

    • spec

      SandboxSpec spec()
      The SandboxSpec this instance was created from. Useful for downstream tooling (audit, observability) that needs to record the configured policy alongside the result.

    • execute

      SandboxResult execute(Command command)
      Run command to completion (or until the sandbox kills it for exceeding ResourceLimits.timeout). Always returns a SandboxResult; failures inside the sandbox are reflected in SandboxResult.exitCode and SandboxResult.stderr, not thrown.

      Throws if the sandbox itself has been terminated, or if the backend layer cannot dispatch the command (image missing, runtime crash). Those are infrastructure failures, distinct from "the user's command exited non-zero".

      Throws:
      SandboxException - when the backend layer can't run the command (terminated sandbox, runtime crash, …)

    • stop

      void stop()
      Graceful shutdown. Backends SHOULD send SIGTERM (or the platform equivalent), wait a short grace period, then promote to terminate() if the process is still running.

    • terminate

      void terminate()
      Forcibly kill the sandbox and release its resources. Idempotent — calling on an already-terminated sandbox is a no-op. Safe in finally blocks.

    • close

      default void close()
      AutoCloseable = terminate().
      Specified by:
      close in interface AutoCloseable