conformance

Documentation

Overview

Package conformance is the driver-agnostic parity gate for runner.Runner implementations. Call Run(t, r) from driver-specific test files.

Contract assertions enforced here:

1. Capabilities sanity: if ConfinementClasses is non-empty, CreateSandbox must honour the strongest class and must never silently downgrade it.
2. Create → Status → Stop idempotency: a second StopSandbox on a stopped sandbox must return nil.
3. KillSandbox on a missing/unknown ref must return nil.
4. L0 assertion hook: if StructuralEgress is declared, an injectable probe (DefaultRouteProbe) asserts that no default route is reachable from the sandbox.
5. Wait exit-code propagation: Exec'ing a short-lived command, Wait must block until it exits and return its exit code (incl. a non-zero code).

Index

• func CheckRecordingCapability(t *testing.T, r runner.Runner, opts RecordingOptions)
• func Run(t *testing.T, r runner.Runner, opts Options)
• type DefaultRouteProbe
• type Options
• type RecordingOptions
• type RecordingProbe

Functions

func CheckRecordingCapability

func CheckRecordingCapability(t *testing.T, r runner.Runner, opts RecordingOptions)

CheckRecordingCapability is the recording-capability honesty gate. It is an ADDITIVE, standalone helper (NOT part of Run) so existing driver suites are unaffected: a driver opts in by calling it explicitly.

The contract it enforces, fail-closed both ways:

• A driver that declares SessionRecording=true MUST honour the recording contract. When opts.RecordingProbe is supplied, the suite creates a sandbox, execs a (recorded) command, and delegates to the probe, which asserts a real recording artifact exists. A driver that "declares but does not produce" therefore fails. If no probe is injected the check is marked pending (skipped with a notice) rather than passing silently.

• A driver that declares SessionRecording=false MUST NOT pretend to record. The suite asserts the honest-empty posture: the driver makes no recording claim, and (when a probe IS supplied for a non-recording driver, which is a misuse) refuses to run it — a false-declaring driver cannot smuggle a "recording happened" result past the gate.

Drivers that declare no ConfinementClasses (honest stubs) cannot create a sandbox, so the artifact-producing half is necessarily skipped for them; the declaration-honesty assertion still runs and must pass.

func Run

func Run(t *testing.T, r runner.Runner, opts Options)

Run executes the full conformance suite against r. It is the single entry-point called from driver-specific _test files.

Types

type DefaultRouteProbe

type DefaultRouteProbe func(t *testing.T, ref string)

DefaultRouteProbe is called by Run when the driver declares StructuralEgress. Implementations should verify that no default-route connectivity exists from within the sandbox identified by ref, and call t.Errorf if one is found. The probe is injected so that the conformance library does not itself require network access or a running sandbox substrate.

type Options

type Options struct {
	// DefaultRouteProbe is called when StructuralEgress is declared. If nil
	// and StructuralEgress is true the suite marks the L0 check as skipped.
	DefaultRouteProbe DefaultRouteProbe
	// SandboxImage is the OCI image used for CreateSandbox calls. If empty,
	// "scratch" is used (drivers that cannot pull scratch should substitute
	// their own minimal image).
	SandboxImage string
	// Timeout is applied to each individual operation. Defaults to 30s.
	Timeout time.Duration
	// ExitArgv, when non-nil, builds the argv for a short-lived in-sandbox
	// command that exits with the given code. It gates the Wait exit-code
	// conformance case: when nil (or the driver declares no ConfinementClasses)
	// the case is skipped, because the suite cannot otherwise run a real process
	// inside SandboxImage. Drivers supply something like
	// {"sh", "-c", fmt.Sprintf("exit %d", code)} for their minimal image.
	ExitArgv func(code int) []string
}

Options controls optional behaviour of the conformance suite.

type RecordingOptions

type RecordingOptions struct {
	Options
	// RecordingProbe is invoked when the driver declares SessionRecording. If
	// the driver declares recording but RecordingProbe is nil, the check is
	// marked pending (skipped with a notice) — the same fail-soft posture
	// DefaultRouteProbe uses, so a driver CI without a recorder substrate does
	// not hard-fail, but a driver CI that wires the probe verifies the contract.
	RecordingProbe RecordingProbe
}

RecordingOptions controls CheckRecordingCapability. It embeds Options for the SandboxImage/Timeout/ExitArgv fields the recording case shares with Run's suite; it is intentionally a SEPARATE type from Options so that adding the recording gate does not change the signature or behaviour of Run / the existing driver suites — only RecordingOptions literal construction (embedding changes neither).

type RecordingProbe

type RecordingProbe func(t *testing.T, ref string)

RecordingProbe is called by CheckRecordingCapability when the driver declares SessionRecording. Implementations should verify that the driver actually honoured the recording contract for the sandbox identified by ref — i.e. a cast/recording artifact was genuinely produced (uploaded through the proxy's brokered route or written to the shared-mount fallback) — and call t.Errorf if it was not. Like DefaultRouteProbe, the probe is injected so the conformance library itself needs no recorder substrate.