runtime

type Backend interface {
	// Capabilities reports the backend's supported features.
	Capabilities(ctx context.Context) Capabilities
	// Validate checks that the seat's requested runtime, enforcement and
	// lifecycle features are available. It returns a typed *Error otherwise.
	Validate(ctx context.Context, s *Seat) error
	// PublishManifest writes the seat's read-only manifest files.
	PublishManifest(ctx context.Context, s *Seat, files map[string]string) error
	// Ensure validates the seat and converges its objects with the desired
	// replica count (0 or 1). On validation failure it creates no workload,
	// scales an existing one to zero and returns the typed error.
	Ensure(ctx context.Context, s *Seat, replicas int32) (*Status, error)
	// Status observes the seat's backend instance.
	Status(ctx context.Context, s *Seat) (*Status, error)
	// Quiesce asks the running Pod to stop at a safe boundary (graceful
	// termination; the runner checkpoints on SIGTERM). It never force-deletes.
	Quiesce(ctx context.Context, s *Seat, pod string) error
	// Stop sets the desired replicas to zero.
	Stop(ctx context.Context, s *Seat) error
	// PodGone confirms with a live read that no Pod with the UID exists.
	PodGone(ctx context.Context, s *Seat, uid string) (bool, error)
	// Cleanup removes the runtime objects. With RetainData the workspace
	// volume is kept. It returns done=false while removal is in progress.
	Cleanup(ctx context.Context, s *Seat, retention Retention) (done bool, err error)
	// VerifyEnforcement runs (or returns the cached result of) the network
	// policy enforcement probe.
	VerifyEnforcement(ctx context.Context, p EnforcementProbe) (ProbeResult, error)
}

type Capabilities struct {
	Backend  string
	Features []string
	// Enforcement lists the sandbox enforcement features the backend can provide.
	Enforcement []string
}

type EnforcementProbe struct {
	Namespace string
	// ProfileDigest identifies the sandbox profile contents.
	ProfileDigest string
	// Seat is a seat using the profile; the probe runs under its policy.
	Seat *Seat
	// Nonce forces a fresh probe when it differs from the cached result's nonce.
	Nonce string
}

type Error struct {
	Kind    ErrorKind
	Feature string
	Message string
}

type ErrorKind string

type PodStatus struct {
	Name        string
	UID         string
	Revision    string
	Phase       string
	Ready       bool
	Terminating bool
	// Waiting is the container waiting reason (e.g. CrashLoopBackOff, ImagePullBackOff).
	Waiting   string
	StartTime *time.Time
	NodeName  string
}

type ProbeResult struct {
	State  ProbeState
	Detail string
	Nonce  string
	Time   time.Time
}

type ProbeState string

type Retention string

type Seat struct {
	Namespace string
	// Name is the deterministic base name (pkg/names.Seat).
	Name           string
	OrgKey         string
	OrgID          string
	SeatKey        string
	SeatID         string
	ConfigRevision string
	// Manifest is the effective seat manifest (harness, execution and sandbox profiles).
	Manifest compile.SeatManifest
	// Owner, if set, owns every seat object except the workspace volume.
	Owner *metav1.OwnerReference
	// AdoptFrom is the retired seat ID whose retained workspace may be adopted.
	AdoptFrom string
}

type Status struct {
	// BackendRef identifies the backend instance, e.g. statefulset/<name>.
	BackendRef string
	Exists     bool
	// Replicas is the desired replica count currently set on the backend.
	Replicas int32
	Pods     []PodStatus
	// StorageHandle is the workspace volume claim.
	StorageHandle string
	StorageExists bool
	StoragePhase  string
	// ManifestRevision is the config revision of the published manifest, if any.
	ManifestRevision string
}