@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/reclaim.d.ts

@@ -0,0 +1,333 @@
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type DrainOutcome, type DrainReservation, type ReclaimDrainStep, type ReservedDrainAttempt, type DrainTargetCommitment } from './claims.js';
+import { type CockpitId, type EnvironmentDiagnostic, type ExecutionFence, type ExecutionReceipt, type ExecutionStep, type FilesystemAncestorIdentity, type StackId } from './contract.js';
+import type { ResolvedExecutable } from './executable.js';
+import { type StateAddress, type StateRecord } from './state.js';
+type Executor = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+export interface DockerSelection {
+    readonly context: string;
+    readonly endpoint: string;
+}
+/** One complete discovery of a stack's runtime resources, as `discoverReclaim` observed it. */
+export interface ReclaimDiscovery extends ReclaimDiscoverySnapshot {
+    readonly startedAt: string;
+    readonly stackId: StackId;
+    readonly selection: DockerSelection;
+}
+/** What a person or the planner itself approved: the digest, and the discovery it was read from. */
+export interface ReclaimConsent {
+    readonly digest: string;
+    readonly observedAt: string;
+}
+/**
+ * The remaining committed target set of a drain after one action, carried from that action's plan
+ * to the next. `drain` is the attempt the action ran under, which the next plan matches against
+ * the record its outcome published; null until the action runs.
+ */
+export interface ReclaimContinuation {
+    readonly purpose: 'down' | 'reset';
+    readonly digest: string;
+    readonly completedTargetId: string;
+    readonly runtimeDigest: string;
+    readonly targetIds: readonly string[];
+    readonly removedTargetIds: readonly string[];
+    readonly targetIdentities: readonly ReclaimTargetIdentity[];
+    /** A discovery that plans the next action must start no earlier than this. */
+    readonly freshAfter: string;
+    readonly drain: ReclaimDrainStep | null;
+}
+/** The one removal a plan permits, executed only by `executeReclaimAction` under a reserved attempt. */
+export interface PlannedReclaimAction {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    /** Null when the interrupted target is already absent and only its removal is recorded. */
+    readonly step: ExecutionStep | null;
+    readonly coordinationRecord: StateRecord;
+    readonly continuation: ReclaimContinuation;
+    readonly observedAt: string;
+    /** For an absent target: the actionable target ids a later discovery still shows. */
+    readonly remainingTargets?: (discovery: ReclaimDiscovery) => Promise<readonly string[] | undefined>;
+}
+export type ReclaimTargetIdentity = ResetVolumeTargetIdentity | TeardownRuntimeTargetIdentity | PathTargetIdentity;
+interface ResetVolumeTargetIdentity {
+    readonly medium: 'runtime';
+    readonly scope: 'reset-volume';
+    readonly targetId: string;
+    readonly kind: 'volume';
+    readonly declaration: string;
+    readonly runtimeId: string;
+    readonly name: string;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly generation: string;
+}
+interface TeardownRuntimeTargetIdentity {
+    readonly medium: 'runtime';
+    readonly scope: 'teardown-runtime';
+    readonly targetId: string;
+    readonly kind: Exclude<ReclaimResourceKind, 'cache'>;
+    readonly runtimeId: string;
+    readonly name: string;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly referenced: boolean;
+    readonly dataBearing: boolean | null;
+    readonly generation: string | null;
+}
+interface PathTargetIdentity {
+    readonly medium: 'path';
+    readonly targetId: string;
+    readonly kind: 'host-path' | 'cache';
+    readonly declaration: string;
+    readonly root: string;
+    readonly path: string;
+    readonly type: 'directory' | 'file';
+    readonly dev: number;
+    readonly ino: number;
+    readonly birthtimeNs: string;
+    readonly ancestors: readonly FilesystemAncestorIdentity[];
+}
+export type ReclaimResourceKind = 'container' | 'network' | 'volume' | 'image' | 'build-cache' | 'cache';
+export type OwnershipEvidence = 'current' | 'stale-config' | 'foreign' | 'unknown' | 'malformed' | 'partial' | 'unlabelled';
+export type Reversibility = 'runtime' | 'regenerable-cache' | 'data-bearing';
+export type ReclaimAction = 'teardown' | 'reclaim' | 'reset-required' | 'report-only';
+export interface ReclaimResource {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: ReclaimResourceKind;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly referenced: boolean;
+    readonly bytes: number | null;
+    readonly dataBearing?: boolean;
+    readonly generation?: string;
+}
+export interface ReclaimDiscoverySnapshot {
+    readonly observedAt: string;
+    readonly producer: 'runtime-resource-discovery';
+    readonly resources: readonly ReclaimResource[];
+}
+export interface ClassifiedReclaimResource extends ReclaimResource {
+    readonly ownership: OwnershipEvidence;
+    readonly reversibility: Reversibility;
+    readonly action: ReclaimAction;
+    readonly evidence: readonly string[];
+    readonly reason: string;
+    readonly suggestion?: {
+        readonly command: string;
+        readonly risk: string;
+    };
+}
+export interface ClassifyReclaimInput {
+    readonly stackId: StackId;
+    readonly cockpitId: CockpitId;
+    readonly configSha256: string;
+    readonly coordinationRecord: StateRecord | null;
+    readonly declaredCacheIds: readonly string[];
+    readonly discovery: ReclaimDiscoverySnapshot;
+}
+export type ReclaimResult = {
+    readonly kind: 'complete';
+    readonly noop: boolean;
+    readonly resources: readonly ClassifiedReclaimResource[];
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export declare function classifyReclaim(rawInput: ClassifyReclaimInput): ReclaimResult;
+export interface KeptTeardownResource {
+    readonly kind: ReclaimResourceKind;
+    readonly id: string;
+    readonly name: string;
+    readonly reason: string;
+}
+/**
+ * The resources a finished `down` leaves behind although this stack's labels and coordinated state
+ * show they are its own, each with the reason teardown may not remove it. Volumes are left out:
+ * `down` keeps data by design, and only `reset` deletes it.
+ */
+export declare function keptTeardownResources(input: ClassifyReclaimInput): readonly KeptTeardownResource[] | undefined;
+/**
+ * Name an inspection chunk that the per-object budget cannot hold, so the operator learns which
+ * resources to look at instead of a generic unobservable precondition.
+ */
+export declare function inspectionOverflow(step: ExecutionStep, outcome: ExecuteProbeOutcome): string | undefined;
+export interface ReclaimDiscoveryInput {
+    readonly executable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly stackId: StackId;
+    readonly cockpitId: CockpitId;
+    readonly timeoutMs: number;
+    readonly context: string;
+    /** A local DOCKER_HOST, selected through Docker's `default` context, which reports it exactly. */
+    readonly host?: string;
+}
+type DiscoveryRefusal = {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+/**
+ * Lists and inspects this stack's runtime resources on the selected Docker context. Discovery
+ * lists resources and then inspects what it listed, and a listed resource can vanish in between,
+ * as Compose replacing one of this stack's containers does; the round then fails closed on an id
+ * that no longer exists, and inside a reserved drain that left the attempt for repair. One more
+ * complete round covers that race without admitting partial evidence.
+ */
+export declare function discoverReclaim(input: ReclaimDiscoveryInput, execute: Executor): Promise<ReclaimDiscovery | DiscoveryRefusal | undefined>;
+export interface ResetTargetInput {
+    readonly kind: 'container' | 'volume' | 'host-path';
+    readonly identity: string;
+    readonly declaration: string;
+    readonly labels?: Readonly<Record<string, string>>;
+}
+interface HostPathDeclaration {
+    readonly root: string;
+    readonly path: string;
+    readonly declaration: string;
+}
+export interface DependencyCacheDeclaration {
+    readonly cacheId: string;
+    readonly root: string;
+    readonly path: string;
+}
+export interface PlanResetInput extends ClassifyReclaimInput {
+    readonly discovery: ReclaimDiscovery;
+    readonly expectedCoordinationRevision: number;
+    readonly requesterHolderId: string | null;
+    /** Compose volume keys, matched within `composeProject`; Docker's volume name is not one. */
+    readonly resettableVolumes: readonly string[];
+    readonly composeProject: string;
+    readonly generatedHostPaths: readonly HostPathDeclaration[];
+    readonly runtimeExecutable: ResolvedExecutable;
+    readonly pathExecutable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly confirmationDigest?: string;
+    readonly consent?: ReclaimConsent;
+    readonly coordinationAddress?: StateAddress;
+    readonly continuation?: ReclaimContinuation;
+    /** A recovered reservation whose reclaim try failed, which plans its remaining committed targets. */
+    readonly recoveredReservation?: DrainReservation;
+    readonly operatorApproval?: ResetPreview;
+}
+export interface ResetPreview {
+    readonly kind: 'preview';
+    readonly digest: string;
+    readonly coordinationRevision: number;
+    readonly targets: readonly ResetTargetInput[];
+    readonly noop: boolean;
+    readonly consent: ReclaimConsent;
+    /** The exact targets the digest commits, which the drain reservation records. */
+    readonly envelope: ReclaimTargetEnvelope;
+}
+export type ResetPlanResult = {
+    readonly kind: 'complete';
+    readonly action: PlannedReclaimAction | null;
+    readonly remaining: number;
+    readonly noop: boolean;
+    readonly digest: string;
+    readonly envelope: ReclaimTargetEnvelope;
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export interface PlanTeardownInput extends ClassifyReclaimInput {
+    readonly discovery: ReclaimDiscovery;
+    readonly executable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly dependencyCaches?: readonly DependencyCacheDeclaration[];
+    readonly pathExecutable?: ResolvedExecutable;
+    readonly expectedDiscoveryDigest?: string;
+    readonly consent?: ReclaimConsent;
+    readonly continuation?: ReclaimContinuation;
+    readonly coordinationAddress?: StateAddress;
+    /** A recovered reservation whose reclaim try failed, which plans its remaining committed targets. */
+    readonly recoveredReservation?: DrainReservation;
+}
+export type TeardownPlanResult = {
+    readonly kind: 'complete';
+    readonly action: PlannedReclaimAction | null;
+    readonly remaining: number;
+    readonly noop: boolean;
+    readonly discoveryDigest: string;
+    readonly byteAccounting: {
+        readonly observed: ByteClasses;
+        readonly reclaimable: ByteClasses;
+        readonly action: {
+            readonly resourceId: string;
+            readonly observedBytes: number | null;
+        } | null;
+        readonly actuallyReclaimed: number | null;
+    };
+    readonly consent: ReclaimConsent | null;
+    readonly envelope: ReclaimTargetEnvelope;
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export declare function planReset(input: PlanResetInput): Promise<ResetPreview | ResetPlanResult>;
+type ByteClasses = Readonly<Record<'orphans' | 'images' | 'buildCache' | 'staleNetworks', number | null>>;
+export declare function planTeardown(input: PlanTeardownInput): Promise<TeardownPlanResult>;
+export interface ReclaimTargetCommitment extends DrainTargetCommitment {
+    readonly targetId: string;
+}
+export interface ReclaimTargetEnvelope {
+    readonly purpose: 'reset' | 'down';
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly planDigest: string;
+    readonly commitments: readonly ReclaimTargetCommitment[];
+}
+/** A removal the attempt admitted, with the attempt it ran under and what it observed. */
+export interface ExecutedReclaimAction {
+    readonly action: PlannedReclaimAction;
+    readonly reservation: DrainReservation;
+    readonly attempt: NonNullable<DrainReservation['attempt']>;
+    readonly drain: ReclaimDrainStep;
+    /** Null for an already-absent target, which runs nothing. */
+    readonly receipt: ExecutionReceipt | null;
+    readonly fence: ExecutionFence | null;
+}
+export type ReclaimActionExecution = {
+    readonly kind: 'executed';
+    readonly executed: ExecutedReclaimAction;
+}
+/** The removal provably never started; its failure is settled and ready to publish, and the same target may be retried. */
+ | {
+    readonly kind: 'not-started';
+    readonly code: Extract<ExecuteProbeOutcome, {
+        kind: 'refusal';
+    }>['code'];
+    readonly outcome: DrainOutcome;
+    readonly fence: ExecutionFence;
+    readonly continuation: ReclaimContinuation;
+} | {
+    readonly kind: 'unavailable';
+};
+/**
+ * Runs the planned removal under the reserved attempt: the attempt must name exactly this target
+ * of the committed target set, and the step runs fenced to the attempt's validity window.
+ */
+export declare function executeReclaimAction(input: {
+    readonly action: PlannedReclaimAction;
+    readonly attempt: ReservedDrainAttempt;
+    readonly execute: Executor;
+}): Promise<ReclaimActionExecution>;
+export type ReconcileReclaimActionResult = {
+    readonly kind: 'complete';
+    readonly outcome: DrainOutcome;
+    readonly continuation: ReclaimContinuation | null;
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+/**
+ * Settles an executed removal from a discovery read after it: every completed target must be
+ * absent and every remaining committed target unchanged, or the attempt stays for repair.
+ */
+export declare function reconcileReclaimAction(input: {
+    readonly executed: ExecutedReclaimAction;
+    readonly discovery: ReclaimDiscovery;
+}): Promise<ReconcileReclaimActionResult>;
+export {};