conformance

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

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
	// EphemeralStorageProbe, when non-nil, is called by the ephemeral-disk case
	// with the ref of a sandbox admitted under a DELIBERATELY OVERSIZED disk
	// limit. It must read that sandbox's own accepted resource requests back from
	// the substrate (k8s: `pods: get`) and assert the request is the small fixed
	// floor, NEVER a copy of the limit — the one assertion that catches an
	// API-server defaulting the driver's own unit tests cannot see. Injected for
	// DefaultRouteProbe's reason: only the substrate knows how to read its own
	// object. Nil ⇒ that sub-case is skipped.
	EphemeralStorageProbe func(t *testing.T, ref string)
	// AgentUserImage, when set, is SandboxImage run as uid 1000 — the identity
	// the image contract gives every agent image. The managed-files case runs
	// on it and then requires the probe to report uid 1000, because a root
	// probe can rename, chmod and rewrite a root-owned file without any
	// capability and so proves nothing about immutability. Empty ⇒ the case
	// runs on SandboxImage, asserting those refusals only when the probe is not
	// root (the Kubernetes substrate runs the agent as uid 1000 whatever the
	// image's USER) and logging them otherwise.
	AgentUserImage string
	// UserDrives, when non-nil, is the substrate's user-drive fixture: a drive
	// its ceiling allows and drives it must refuse. Nil ⇒ the UserDrives case
	// is skipped (the must-pass floor in scripts/test-report.sh reddens that
	// skip on a real substrate). See UserDriveFixture.
	UserDrives *UserDriveFixture
	// ExecState, when non-nil, returns the substrate's own record of the exec
	// Exec returned (running, exit code, pid). Diagnostic only: the Wait
	// exit-code case logs it when the code is wrong, and asserts nothing on it.
	ExecState func(ctx context.Context, execID string) string
}

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
	// MutateSpec, when non-nil, edits the recording sandbox's spec after the
	// confinement class is pinned and before CreateSandbox. A recording
	// driver's proxy needs a control plane to upload the cast to, which
	// minimalSpec does not carry; the caller supplies it here.
	MutateSpec func(*runner.SandboxSpec)
}

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

type RefusedDrive struct {
	Name  string
	Mount types.DriveMount
	// WantErr is a substring the refusal must carry, so a failure for an
	// unrelated reason (an image pull, a missing network) cannot pass as the
	// drive refusal.
	WantErr string
	// Allowing, when non-nil, is the same substrate configured so that THIS
	// drive is inside its ceiling. The case mounts it there first and
	// requires the agent to write it: the positive control that makes the
	// refusal attributable to the ceiling rather than to anything else about
	// the fixture (a missing directory, an unmountable path).
	Allowing runner.Runner
}

type RoutingOptions struct {
	// Timeout bounds each subtest's calls; zero means 30 seconds.
	Timeout time.Duration
	// Image is the OCI image a honoured placement creates.
	Image string
	// Offline, when set, is a registered runner substrate whose link is down.
	Offline substrate.Substrate
}

type UserDriveFixture struct {
	// Mount is a drive inside the ceiling. The case binds it and requires the
	// agent (uid 1000) to write and read it back.
	Mount types.DriveMount
	// Lock makes UserDriveLockedDir at the drive's root, holding
	// UserDriveLockedFile, mode 0700 and owned by an identity other than uid
	// 1000. Called AFTER the sandbox holding Mount exists: on kubernetes that
	// create is what provisions the storage.
	Lock func(t *testing.T)
	// ReadBack, when non-nil, returns a file at the drive's root as seen from
	// OUTSIDE any sandbox (the host directory a docker share binds). It is
	// what proves the bind landed in the allowed directory and not on some
	// other storage that happens to be writable.
	ReadBack func(t *testing.T, name string) string
	// Refused are drives outside the ceiling; CreateSandbox must refuse each.
	Refused []RefusedDrive
	// Also, when set, is a second drive at its own derived path (below
	// runner.DrivesRoot or runner.SharedRoot). The case mounts it beside Mount
	// in one sandbox and requires the agent to write and read back both, then
	// requires a second drive at Mount's own target to be refused.
	Also *types.DriveMount
}