Package com.tnsai.quality.sandbox

Interface SandboxFactory

All Known Implementing Classes:
ContainerSandboxFactory, ProcessSandboxFactory, WasmSandboxFactory
public interface SandboxFactory
SPI for creating Sandbox instances (TNS-296). Implementations are discovered via ServiceLoader; the framework ships ProcessSandboxFactory as the portable default.

Choosing a backend

Most consumers use preferred() which auto-selects the highest-priority factory available on the classpath. Production deployments can pin a specific backend by passing it directly: 

 Sandbox sb = SandboxFactory.preferred().create(spec);
 

 SandboxFactory factory = ServiceLoader.load(SandboxFactory.class).stream()
         .map(ServiceLoader.Provider::get)
         .filter(f -> f.id().equals("container"))
         .findFirst().orElseThrow();
Since:
0.10.0 (TNS-296)

  • Method Details

    • id

      String id()
      Stable backend identifier ("process", "container", "wasm", "firecracker", …). Used by callers pinning a specific backend.

    • priority

      int priority()
      Higher = preferred. The framework's default ProcessSandboxFactory reports 10; container reports 50; firecracker reports 100. preferred() picks the highest available.

    • available

      boolean available()
      true if this factory's runtime is reachable on the current host (e.g. ContainerSandboxFactory.available() returns true when docker is on the PATH). Factories that cannot probe cheaply (slow shell-out, network call) should return true and surface the failure at create(com.tnsai.quality.sandbox.SandboxSpec) time.

    • create

      Sandbox create(SandboxSpec spec)
      Create a Sandbox from spec. Implementations MUST reject specs they cannot honour (e.g. a backend that doesn't support NetPolicy.AllowList throws here rather than silently downgrading) — silent relaxation is the accidental-blast-radius footgun this layer exists to prevent.
      Throws:
      SandboxException - when the backend cannot honour the spec or the runtime is unreachable

    • preferred

      static SandboxFactory preferred()
      The highest-priority SandboxFactory that reports available() = true. Falls back to a deterministic process-only factory if no SPI provider is registered (which is the case in stripped-down embedded deployments).
      Throws:
      SandboxException - if no factory is available

    • byId

      static SandboxFactory byId(String id)
      Find a factory by its id() (case-insensitive). Useful for explicit backend selection from configuration.
      Throws:
      SandboxException - if no factory with that id is registered