@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/runtime-probe-residue.js

@@ -0,0 +1,148 @@
+import { hasErrorCode } from './contract.js';
+/**
+ * Owns the leftovers of a `runtime measure` that was killed before the probe could clean up: the
+ * probe's containers, network and volume on the daemon, and the private `cockpit-runtime-measure-*`
+ * directory in the temp directory. The next measure removes what it can prove belongs to a dead
+ * measure of this cockpit and says what it removed; whatever it cannot prove dead it leaves and
+ * names. It never spawns a process itself: every Docker call crosses the supplied `run`, and liveness crosses `observe`.
+ */
+import { lstat, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isProcessGone, isProcessStart } from './claims.js';
+export const MEASURE_DIRECTORY_PREFIX = 'cockpit-runtime-measure-';
+const OWNER_FILE = 'owner';
+// A directory with no owner file was killed between creation and its first write, or is being
+// created right now; only age tells them apart, and a probe never outlives its five-minute window.
+const UNOWNED_STALE_MS = 10 * 60_000;
+const PROBE_LABEL = 'dev.b0dea.cockpit.probe';
+/** Names the measure process that created a probe resource, as `<pid>` or `<pid>@<start identity>`. */
+export const PROBE_OWNER_LABEL = 'dev.b0dea.cockpit.probe-owner';
+const OWNER = /^([1-9][0-9]{0,9})(?:@(\S+))?$/;
+const DOCKER_ID = /^[a-f0-9]{12,64}$/;
+const DOCKER_NAME = /^[a-z0-9][a-z0-9_.-]{0,200}$/;
+const MEASURE_DIRECTORY_NAME = new RegExp(`^${MEASURE_DIRECTORY_PREFIX}[A-Za-z0-9]{6}$`);
+/** Mark a freshly created measure directory as owned by `owner` (see `PROBE_OWNER_LABEL`), so a later measure can tell it is alive. */
+export async function claimMeasureDirectory(directory, owner) {
+    await writeFile(join(directory, OWNER_FILE), `${owner}\n`, { mode: 0o600 });
+}
+export function isProbeOwner(owner) {
+    const match = OWNER.exec(owner);
+    return match !== null && Number(match[1]) <= 2_147_483_647 && (match[2] === undefined || isProcessStart(match[2]));
+}
+// Only proof that the owner is gone marks it dead: a missing or malformed owner, a reused pid or a
+// failed check keeps what it owns.
+async function ownerGone(owner, observe) {
+    if (!isProbeOwner(owner))
+        return false;
+    const [, pid, start] = OWNER.exec(owner);
+    return isProcessGone(start, await observe(Number(pid)));
+}
+// One measure's directory, containers, network and volume share an owner; observe it once per sweep.
+function cachedOwnerGone(observe) {
+    const gone = new Map();
+    return (owner) => {
+        let known = gone.get(owner);
+        if (known === undefined) {
+            known = ownerGone(owner, observe);
+            gone.set(owner, known);
+        }
+        return known;
+    };
+}
+async function measureDirectories(temporaryDirectory, uid, gone) {
+    const names = (await readdir(temporaryDirectory)).filter((name) => MEASURE_DIRECTORY_NAME.test(name));
+    const judged = await Promise.all(names.map(async (name) => {
+        const path = join(temporaryDirectory, name);
+        const status = await lstat(path);
+        // Only a real directory of this user: a symlink or someone else's directory is not ours to judge or delete.
+        if (!status.isDirectory() || status.isSymbolicLink() || (uid !== undefined && status.uid !== uid))
+            return undefined;
+        let owner;
+        try {
+            owner = (await readFile(join(path, OWNER_FILE), 'utf8')).trim();
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+        }
+        const alive = owner === undefined ? Date.now() - status.mtimeMs < UNOWNED_STALE_MS : !await gone(owner);
+        return { path, alive };
+    }));
+    return judged.filter((directory) => directory !== undefined);
+}
+const LISTING_FORMAT = (handle) => `{{.${handle}}}\t{{.Label "com.docker.compose.project"}}\t{{.Label "${PROBE_LABEL}"}}\t{{.Label "${PROBE_OWNER_LABEL}"}}`;
+const LISTINGS = [
+    ['container', ['ps', '-a', '--no-trunc'], 'ID', DOCKER_ID],
+    ['network', ['network', 'ls', '--no-trunc'], 'ID', DOCKER_ID],
+    ['volume', ['volume', 'ls'], 'Name', DOCKER_NAME],
+];
+async function discover(run) {
+    // The listings are independent reads; the results are walked in listing order so the first refusal named is stable.
+    const listings = await Promise.all(LISTINGS.map(([kind, command, handle]) => run(`runtime:measure:residue:${kind}`, [...command, '--filter', `label=${PROBE_LABEL}`, '--format', LISTING_FORMAT(handle)])));
+    const found = [];
+    for (const [index, listed] of listings.entries()) {
+        const [kind, , , valid] = LISTINGS[index];
+        if (listed.kind !== 'complete')
+            return `listing leftover probe ${kind}s failed (${listed.detail})`;
+        for (const line of listed.text.split('\n').filter(Boolean)) {
+            const [handle = '', project = '', batchLabel = '', owner = ''] = line.split('\t');
+            if (!valid.test(handle))
+                return `docker listed a probe ${kind} with an unexpected identity`;
+            found.push({ kind, handle, project, batchLabel, owner });
+        }
+    }
+    return found;
+}
+/**
+ * Remove this cockpit's probe resources left by a dead measure. A resource is the probe's only if
+ * it carries the probe label and a Compose project named `<projectPrefix>-probe-<batch>` (Compose
+ * appends the stack hash) whose batch matches the label, so a different cockpit's probe, or any other stack, is never touched.
+ * It is dead only when the measure its owner label names is provably gone. Liveness is read from
+ * the label on the shared daemon, not from the temp directory: agent tools give each session its
+ * own TMPDIR, so a concurrent measure's directory is invisible, and judging by it removed that
+ * measure's running probe. Anything not provably dead may be running now and is only reported.
+ */
+export async function sweepProbeResidue(input) {
+    const gone = cachedOwnerGone(input.observe);
+    const directories = (await measureDirectories(input.temporaryDirectory, input.uid, gone)).filter(({ path }) => path !== input.ownDirectory);
+    const projectPattern = new RegExp(`^${input.projectPrefix.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')}-probe-([0-9a-f]{32})(?:-[0-9a-f]{12})?$`);
+    const discovered = await discover(input.run);
+    if (typeof discovered === 'string')
+        return { kind: 'refusal', reason: discovered, removed: [] };
+    const removed = [];
+    const left = [];
+    const failed = [];
+    const owned = discovered.flatMap((item) => {
+        const batch = projectPattern.exec(item.project)?.[1];
+        // The probe's own label must agree with its project, so a resource merely named like one is not removed.
+        return batch === undefined || batch !== item.batchLabel ? [] : [{ ...item, batch }];
+    });
+    const label = (item) => `${item.kind} ${item.kind === 'volume' ? item.handle : item.handle.slice(0, 12)} (project ${item.project})`;
+    const dead = await Promise.all(owned.map((item) => gone(item.owner)));
+    const doomed = owned.filter((_, index) => dead[index]);
+    for (const item of owned)
+        if (!doomed.includes(item))
+            left.push(label(item));
+    // Containers first: a network or volume a container still uses cannot be removed.
+    for (const kind of ['container', 'network', 'volume']) {
+        for (const item of doomed.filter((candidate) => candidate.kind === kind)) {
+            const args = kind === 'container' ? ['container', 'rm', '--force', '--volumes', item.handle]
+                : kind === 'network' ? ['network', 'rm', item.handle] : ['volume', 'rm', item.handle];
+            const outcome = await input.run(`runtime:measure:residue:rm-${kind}`, args);
+            if (outcome.kind === 'complete')
+                removed.push(label(item));
+            else
+                failed.push(`${label(item)}: ${outcome.detail}`);
+        }
+    }
+    if (failed.length > 0) {
+        return { kind: 'refusal', removed, reason: `a leftover from an interrupted measure could not be removed: ${failed.join('; ')}; remove it, then measure again` };
+    }
+    for (const directory of directories) {
+        if (directory.alive)
+            continue;
+        await rm(directory.path, { recursive: true, force: true });
+        removed.push(`temporary directory ${directory.path}`);
+    }
+    return { kind: 'complete', removed, left };
+}

package/dist/environment/runtime-probe.d.ts

@@ -0,0 +1,72 @@
+import { ENVIRONMENT_CODES, type StackId } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+import { type ActiveStackInventoryResult } from './claims.js';
+import { type StateRecord, type StateResult } from './state.js';
+export interface RuntimeProbeRequest {
+    readonly executable: ResolvedExecutable;
+    readonly gitExecutable: ResolvedExecutable;
+    readonly cwd: string;
+    /** The measuring cockpit's name; the probe's Compose project carries it so its resources are attributable. */
+    readonly projectPrefix: string;
+    /** The measuring process, labelled on every probe resource so a later measure can tell whether it still runs. */
+    readonly owner: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly composeFloor: string;
+    readonly measuredOn: string;
+    readonly timeoutMs: number;
+    readonly image: {
+        readonly reference: string;
+        readonly id: string;
+    };
+    readonly installedModule: {
+        readonly canonicalPath: string;
+        readonly sha256: string;
+    };
+}
+export interface RuntimeProbeEvidence {
+    readonly batchId: string;
+    readonly installedModuleSha256: string;
+    readonly runtimeExecutableSha256: string;
+    readonly candidateSha256: string;
+    readonly brokenControlSha256: string;
+    readonly projectName: string;
+    readonly runtimePath: string;
+    readonly runtimeVersion: string | null;
+    readonly composeVersion: string | null;
+    readonly operatingSystem: string;
+    readonly architecture: string;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly expiresAt: string;
+    readonly candidateChecks: Readonly<Record<string, boolean>>;
+    readonly brokenControlRejected: boolean;
+    readonly cleanup: {
+        readonly ownedSurvivors: readonly string[];
+        readonly resourcesEqual: boolean;
+        readonly claimsEqual: boolean;
+        readonly leasesEqual: boolean;
+    };
+}
+export interface RuntimeProbeVerdict {
+    readonly status: 'supported' | 'unavailable';
+    readonly runtime: {
+        readonly name: string;
+        readonly version: string;
+    } | null;
+    readonly composeVersion: string | null;
+    readonly composeFloor: string;
+    readonly measuredOn: string;
+    readonly candidate: 'passed' | 'failed';
+    readonly brokenControl: 'rejected' | 'accepted' | 'inconclusive';
+    readonly evidence: RuntimeProbeEvidence | null;
+    readonly operatorAction: null | {
+        readonly required: true;
+        readonly code: typeof ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE | typeof ENVIRONMENT_CODES.RUNTIME_PROBE_TIMEOUT;
+        readonly reason: string;
+    };
+}
+export declare function currentCoordinationCleanupVerdict(beforeClaims: ActiveStackInventoryResult, afterClaims: ActiveStackInventoryResult, beforeLease: StateResult<StateRecord>, afterLease: StateResult<StateRecord>, stackId: StackId): Readonly<{
+    claimsEqual: boolean;
+    leasesEqual: boolean;
+}>;
+export declare function probeRuntimeSupport(rawInput: RuntimeProbeRequest): Promise<RuntimeProbeVerdict>;