Interface IsolationProvider

All Superinterfaces:
AutoCloseable
public interface IsolationProvider extends AutoCloseable
First-party J7M isolation provider SPI.

Providers are thread-safe after construction unless documented otherwise. They own any child processes, provider work directories, capture buffers, and admission-control counters they allocate. close() stops accepting new work and must clean up provider-owned resources; status methods remain safe and redacted after close.

Methods may block for local process launch, process termination, and output-drain completion. Callers should use bounded request timeouts and bounded IsolationExecutionHandle.await(Duration) calls. Failures map to MiddlewareException error codes through IsolationException. Public status and audit data are redacted summaries, never full internal process state or raw command/environment/output secrets.

This SPI is not a container runtime, not an OCI runtime, and not a guarantee of kernel-level sandboxing. Implementations must report advisory, policy-only, enforced, and unsupported resource limits truthfully.

  • Method Details

    • id

      IsolationProviderId id()
      Returns the stable provider identifier.
      Returns:
      provider identifier

    • type

      IsolationProviderType type()
      Returns the provider type.
      Returns:
      provider type

    • supportedModes

      Set<IsolationMode> supportedModes()
      Returns supported execution modes.
      Returns:
      immutable supported mode set

    • start

      IsolationExecutionHandle start(IsolationExecutionRequest request)
      Starts an isolated execution.
      Parameters:
      request - execution request
      Returns:
      live execution handle
      Throws:
      IsolationException - when the provider is closed, request is invalid, policy denies start, or capacity is exhausted

    • execute

      default IsolationExecutionResult execute(IsolationExecutionRequest request)
      Runs an isolated execution to completion using the request timeout.
      Parameters:
      request - execution request
      Returns:
      terminal result
      Throws:
      IsolationException - when start or execution fails before a result can be produced

    • evaluateFileSystem

      IsolationPolicyDecision evaluateFileSystem(IsolationSubject subject, FileSystemPolicy policy, FileSystemAccess access, Path path)
      Evaluates filesystem policy for a normalized path.
      Parameters:
      subject - subject requesting access
      policy - filesystem policy
      access - access type
      path - requested path
      Returns:
      safe policy decision

    • evaluateNetworkEgress

      IsolationPolicyDecision evaluateNetworkEgress(IsolationSubject subject, NetworkEgressPolicy policy, URI destination)
      Evaluates network egress policy for a destination URI.
      Parameters:
      subject - subject requesting egress
      policy - network policy
      destination - destination URI
      Returns:
      safe policy decision

    • evaluateEnvironment

      IsolationPolicyDecision evaluateEnvironment(IsolationSubject subject, EnvironmentPolicy policy, String name, String value)
      Evaluates environment policy for one variable.
      Parameters:
      subject - subject requesting environment access
      policy - environment policy
      name - variable name
      value - variable value
      Returns:
      safe policy decision

    • metrics

      IsolationMetricsSnapshot metrics()
      Returns provider metrics.
      Returns:
      immutable metrics snapshot

    • health

      IsolationHealth health()
      Returns provider health.
      Returns:
      health summary

    • auditEvents

      List<IsolationAuditEvent> auditEvents()
      Returns recent safe audit events.
      Returns:
      immutable audit event list

    • recoveryReport

      IsolationRecoveryReport recoveryReport()
      Returns startup recovery and cleanup summary.
      Returns:
      recovery report

    • close

      void close()
      Closes this provider.
      Specified by:
      close in interface AutoCloseable