Package com.tnsai.quality.sandbox

Class ObservedSandbox

java.lang.Object

com.tnsai.quality.sandbox.ObservedSandbox

All Implemented Interfaces:

Sandbox, AutoCloseable

public final class ObservedSandbox
extends Object
implements Sandbox

Decorator wrapping a Sandbox so every execute(com.tnsai.quality.sandbox.Command) call also produces a SandboxExecutionEvent on the configured SandboxExecutionListener (TNS-296).

Listener calls are wrapped in try/catch — observability outages never break the execution hot path. The actual sandbox failure (timeout, infrastructure error) still propagates as expected.

Since:

0.10.0 (TNS-296)

Constructor Summary

Constructors

Constructor	Description
ObservedSandbox(Sandbox delegate, SandboxExecutionListener listener, String backend)

Method Summary

Modifier and Type	Method	Description
SandboxResult	execute(Command command)	Run command to completion (or until the sandbox kills it for exceeding ResourceLimits.timeout).
SandboxSpec	spec()	The SandboxSpec this instance was created from.
void	stop()	Graceful shutdown.
void	terminate()	Forcibly kill the sandbox and release its resources.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.tnsai.quality.sandbox.Sandbox

close

Constructor Details

ObservedSandbox

public ObservedSandbox(Sandbox delegate,
 SandboxExecutionListener listener,
 String backend)

Method Details

spec

public SandboxSpec spec()

Description copied from interface: Sandbox

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

Specified by:

spec in interface Sandbox

execute

public SandboxResult execute(Command command)

Description copied from interface: Sandbox

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".

Specified by:

execute in interface Sandbox

stop

public void stop()

Description copied from interface: Sandbox

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

Specified by:

stop in interface Sandbox

terminate

public void terminate()

Description copied from interface: Sandbox

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

Specified by:

terminate in interface Sandbox