@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/application/logs.d.ts

@@ -0,0 +1,45 @@
+import type { ExecuteProbeOutcome } from '../../environment-exec/execute.js';
+import { type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type ExecutionStep } from '../contract.js';
+import type { RuntimeAdapterAuthority } from '../runtime.js';
+import { type LogRecord, type LogRequest, type RestartWindow } from '../logs.js';
+export interface LogsCommandInput {
+    readonly configPath: string;
+    readonly service: string;
+    readonly since: string;
+    readonly tail: number;
+    readonly follow: boolean;
+    readonly json: boolean;
+}
+export type LogRequestBase = Omit<LogRequest, 'since' | 'tail' | 'follow'>;
+export interface LogObservation {
+    readonly ownComposeAuthority?: Extract<RuntimeAdapterAuthority, {
+        ownComposeFiles: true;
+    }>;
+    readonly request: LogRequestBase;
+    readonly restart?: RestartWindow;
+}
+export interface LogsCommandAdapters {
+    readonly observe: (input: {
+        readonly configPath: string;
+        readonly service: string;
+    }) => Promise<LogObservation>;
+    readonly execute: (step: ExecutionStep, options: {
+        readonly signal?: AbortSignal;
+    }) => Promise<ExecuteProbeOutcome>;
+    readonly signal?: AbortSignal;
+}
+export type LogsCommandResult = EnvironmentCommandOutcome<Readonly<{
+    readonly json: boolean;
+    readonly records: readonly LogRecord[];
+    readonly truncated: boolean;
+}>> | Readonly<{
+    kind: 'cancelled';
+    status: 130;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: Readonly<{
+        json: boolean;
+        records: readonly LogRecord[];
+        truncated: boolean;
+    }>;
+}>;
+export declare function runLogs(input: LogsCommandInput, adapters: LogsCommandAdapters): Promise<LogsCommandResult>;

package/dist/environment/application/logs.js

@@ -0,0 +1,127 @@
+import { ENVIRONMENT_CODES, errorCause } from '../contract.js';
+import { DeclarationRefusalError } from '../declaration.js';
+import { collectLogs, planLogs } from '../logs.js';
+import { applicationDiagnostic } from './health.js';
+import { ownDataValues } from './shared.js';
+function logsRefusal(code, message) {
+    return {
+        kind: 'refusal', status: 2, result: null,
+        diagnostics: [applicationDiagnostic(code, message, 'logs')],
+    };
+}
+const logRequestBaseKeys = Object.freeze([
+    'runtime', 'executable', 'cwd', 'stackId', 'configSha256', 'batchId', 'containerId',
+    'runtimeVersion', 'composeVersion', 'projectName', 'composeFiles', 'services', 'service',
+    'timeoutMs', 'outputLimitBytes', 'env',
+]);
+const logService = /^[a-z0-9][a-z0-9_.-]{0,127}$/;
+const relativeLogSince = /^\d+(?:\.\d+)?[smhd]$/;
+const absoluteLogSince = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|([+-])(\d{2}):(\d{2}))$/;
+function validAbsoluteLogSince(value) {
+    const match = absoluteLogSince.exec(value);
+    if (!match)
+        return false;
+    const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
+    const calendar = new Date(`${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`);
+    if (Number.isNaN(calendar.valueOf()) || calendar.getUTCFullYear() !== year || calendar.getUTCMonth() + 1 !== month
+        || calendar.getUTCDate() !== day || calendar.getUTCHours() !== hour || calendar.getUTCMinutes() !== minute
+        || calendar.getUTCSeconds() !== second)
+        return false;
+    const offsetHour = match[8] === 'Z' ? 0 : Number(match[10]);
+    const offsetMinute = match[8] === 'Z' ? 0 : Number(match[11]);
+    return offsetHour <= 14 && offsetMinute <= 59 && (offsetHour !== 14 || offsetMinute === 0)
+        && Number.isFinite(Date.parse(value));
+}
+function validPublicLogOptions(service, since, tail) {
+    return logService.test(service) && since.length <= 64
+        && (relativeLogSince.test(since) || validAbsoluteLogSince(since))
+        && Number.isInteger(tail) && tail >= 1 && tail <= 10_000;
+}
+function logsCancelled(json) {
+    return {
+        kind: 'cancelled', status: 130, diagnostics: [],
+        result: { json, records: [], truncated: false },
+    };
+}
+function logsTruncated(service, shown, step) {
+    return [{
+            severity: 'warning',
+            code: 'LOGS_TRUNCATED',
+            message: `the logs of service ${service} exceeded the output limit of ${step.stdoutLimitBytes} bytes of stdout and ${step.stderrLimitBytes} of stderr, so only the newest ${shown} record${shown === 1 ? '' : 's'} are shown and older records in the requested range are not`,
+            target: 'logs',
+            fix: 'lower --tail to the number of recent records you need, or read the older records from the container runtime directly',
+        }];
+}
+export async function runLogs(input, adapters) {
+    let captured;
+    let signal;
+    let observe;
+    let execute;
+    try {
+        captured = ownDataValues(input, ['configPath', 'service', 'since', 'tail', 'follow', 'json']);
+        signal = adapters.signal;
+        observe = adapters.observe;
+        execute = adapters.execute;
+    }
+    catch (error) {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `log request must be readable: ${errorCause(error)}`);
+    }
+    const configPath = captured?.configPath;
+    const service = captured?.service;
+    const since = captured?.since;
+    const tail = captured?.tail;
+    const follow = captured?.follow;
+    const json = captured?.json;
+    if (typeof configPath !== 'string' || typeof service !== 'string' || typeof since !== 'string'
+        || typeof tail !== 'number' || typeof follow !== 'boolean' || typeof json !== 'boolean'
+        || typeof observe !== 'function' || typeof execute !== 'function') {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, 'log request must contain exact public options');
+    }
+    if (!validPublicLogOptions(service, since, tail)) {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, 'log service, time range, and tail must be valid and bounded');
+    }
+    if (follow && signal === undefined) {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, 'follow logs require a cancellation signal');
+    }
+    if (signal?.aborted)
+        return logsCancelled(json);
+    let observation;
+    try {
+        observation = await observe({ configPath, service });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            return logsCancelled(json);
+        if (error instanceof DeclarationRefusalError)
+            return { kind: 'refusal', status: 2, result: null,
+                diagnostics: [error.diagnostic] };
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `log observation is unavailable for service ${service}: ${errorCause(error)}`);
+    }
+    if (signal?.aborted)
+        return logsCancelled(json);
+    const observed = ownDataValues(observation, ['request'], ['restart', 'ownComposeAuthority']);
+    const request = ownDataValues(observed?.request, logRequestBaseKeys, ['restartBatches']);
+    if (!request || request.service !== service) {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `log observation does not match service ${service}`);
+    }
+    const resolvedRequest = { ...request, since, tail, follow };
+    const plan = planLogs(resolvedRequest, observed?.ownComposeAuthority);
+    if (plan.kind !== 'planned')
+        return logsRefusal(plan.code, plan.reason);
+    let collected;
+    try {
+        collected = await collectLogs(plan, execute, signal, observed?.restart);
+    }
+    catch (error) {
+        return logsRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `log collection failed for service ${service}: ${errorCause(error)}`);
+    }
+    if (collected.kind === 'unavailable') {
+        return logsRefusal(collected.code, `the logs of service ${service} are unavailable: ${collected.reason}`);
+    }
+    const diagnostics = collected.truncated
+        ? logsTruncated(service, collected.records.length, plan.step) : [];
+    const result = { json, records: collected.records, truncated: collected.truncated };
+    if (collected.kind === 'cancelled')
+        return { kind: 'cancelled', status: 130, diagnostics, result };
+    return { kind: 'complete', status: 0, diagnostics, result };
+}

package/dist/environment/application/services.d.ts

@@ -0,0 +1,60 @@
+import type { ExecuteProbeOutcome, ForegroundProcessInput, ForegroundProcessOutcome } from '../../environment-exec/execute.js';
+import { type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type ExecutionStep, type LifecycleProgress } from '../contract.js';
+import { type RuntimeServiceState, type RuntimeTopologyEvidence } from '../runtime.js';
+export interface ServiceObservation {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly completedServices: LifecycleProgress['completedServices'];
+    /** Records the container a rebuild put in place of the one the stack was started with. */
+    readonly recordContainer: (service: string, containerId: string) => Promise<readonly EnvironmentDiagnostic[]>;
+}
+export interface ServiceCommandAdapters {
+    readonly observe: (input: {
+        readonly configPath: string;
+    }) => Promise<ServiceObservation>;
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+    readonly executeForeground: (input: ForegroundProcessInput) => Promise<ForegroundProcessOutcome>;
+}
+export declare function runServicePs(input: Readonly<{
+    configPath: string;
+}>, adapters: ServiceCommandAdapters): Promise<EnvironmentCommandOutcome<Readonly<{
+    services: readonly RuntimeServiceState[];
+}>>>;
+/**
+ * `restart` restarts the container in place; `rebuild` builds the service's image and replaces its
+ * container, for a change baked into the image. Both then wait for the service as `up` does and
+ * report its logs when it does not become healthy.
+ */
+export declare function runServiceRestart(input: Readonly<{
+    configPath: string;
+    service: string;
+    verb: 'restart' | 'rebuild';
+}>, adapters: ServiceCommandAdapters): Promise<EnvironmentCommandOutcome<Readonly<{
+    service: string;
+    containerId: string;
+    change: 'restarted' | 'rebuilt';
+}>>>;
+type ServiceExecResult = Readonly<{
+    kind: 'complete';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: Readonly<{
+        exitCode: number;
+        signal: NodeJS.Signals | null;
+    }>;
+}> | Readonly<{
+    kind: 'refusal';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+}>;
+/**
+ * Runs a command inside one service's container in the foreground. A command that exits nonzero
+ * is the command's answer, not a cockpit failure, so its status passes through as `session` does.
+ */
+export declare function runServiceExec(input: Readonly<{
+    configPath: string;
+    service: string;
+    argv: readonly [string, ...string[]];
+    tty: boolean;
+}>, adapters: ServiceCommandAdapters): Promise<ServiceExecResult>;
+export {};

package/dist/environment/application/services.js

@@ -0,0 +1,89 @@
+// One-service verbs on this checkout's own running stack: `ps`, `restart`, `rebuild` and `exec`. Each
+// reaches the stack through the topology its runtime readiness authenticated, so the agent never names
+// the hashed Compose project, its files or its profiles, and every step is one the runtime owner plans.
+import { constants as osConstants } from 'node:os';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { ENVIRONMENT_CODES, errorCause, forwardedRefusal } from '../contract.js';
+import { DeclarationRefusalError, serviceNotDeclared } from '../declaration.js';
+import { admitRuntimeServiceHealth, observeRuntimeServiceStates, planRuntimeServiceExec, restartRuntimeService, startRuntimeService, } from '../runtime.js';
+import { collectFailureLogs } from './lifecycle.js';
+import { lifecycleRefusal } from './shared.js';
+async function observeStack(verb, configPath, adapters, service) {
+    let observed;
+    try {
+        observed = await adapters.observe({ configPath });
+    }
+    catch (error) {
+        if (error instanceof DeclarationRefusalError)
+            return forwardedRefusal([error.diagnostic]);
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `${verb} could not reach this checkout's running stack: ${errorCause(error)}`, verb, `start the stack with ${cockpitCommand('up', { config: configPath })}, then rerun ${verb}`);
+    }
+    const declared = observed.topology.services.map(({ id }) => id);
+    if (service !== undefined && !declared.includes(service)) {
+        return forwardedRefusal([serviceNotDeclared(service, declared)]);
+    }
+    return observed;
+}
+export async function runServicePs(input, adapters) {
+    const observed = await observeStack('ps', input.configPath, adapters);
+    if ('kind' in observed)
+        return observed;
+    const states = await observeRuntimeServiceStates({ topology: observed.topology, execute: adapters.execute });
+    if (states.kind !== 'complete')
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `the stack's service states are unavailable: ${states.reason}`, 'ps');
+    return { kind: 'complete', status: 0, diagnostics: [], result: { services: states.services } };
+}
+/**
+ * `restart` restarts the container in place; `rebuild` builds the service's image and replaces its
+ * container, for a change baked into the image. Both then wait for the service as `up` does and
+ * report its logs when it does not become healthy.
+ */
+export async function runServiceRestart(input, adapters) {
+    const observed = await observeStack(input.verb, input.configPath, adapters, input.service);
+    if ('kind' in observed)
+        return observed;
+    const run = { topology: observed.topology, service: input.service, execute: adapters.execute };
+    const outcome = input.verb === 'rebuild' ? await startRuntimeService({ ...run, rebuild: true }) : await restartRuntimeService(run);
+    const evidence = outcome.kind === 'observed' ? admitRuntimeServiceHealth(outcome.observation) : undefined;
+    if (!evidence) {
+        const logs = await collectFailureLogs(outcome.kind === 'observed' ? outcome.observation
+            : outcome.kind === 'failure' ? outcome.logs : undefined, input.service, adapters);
+        return forwardedRefusal([
+            { severity: 'error', code: ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, target: input.service,
+                message: `service ${input.service} did not become healthy after ${input.verb}`,
+                fix: `fix the error in the log excerpt, then rerun ${input.verb}` },
+            ...logs
+        ]);
+    }
+    const recorded = observed.completedServices.find(({ service }) => service === input.service);
+    if (recorded && recorded.containerId !== evidence.containerId) {
+        const refused = await observed.recordContainer(input.service, evidence.containerId);
+        if (refused.length > 0)
+            return forwardedRefusal(refused);
+    }
+    return { kind: 'complete', status: 0, diagnostics: [],
+        result: { service: input.service, containerId: evidence.containerId, change: input.verb === 'rebuild' ? 'rebuilt' : 'restarted' } };
+}
+/**
+ * Runs a command inside one service's container in the foreground. A command that exits nonzero
+ * is the command's answer, not a cockpit failure, so its status passes through as `session` does.
+ */
+export async function runServiceExec(input, adapters) {
+    const observed = await observeStack('exec', input.configPath, adapters, input.service);
+    if ('kind' in observed)
+        return observed;
+    const planned = planRuntimeServiceExec({ topology: observed.topology, service: input.service, argv: input.argv, tty: input.tty });
+    if (!planned)
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `the command for service ${input.service} could not be planned from the stack's topology`, input.service);
+    const child = await adapters.executeForeground(planned);
+    if (child.kind === 'refusal')
+        return { kind: 'refusal', status: child.code === ENVIRONMENT_CODES.EXECUTION_ABORTED ? 130 : 2, result: null,
+            diagnostics: [{ severity: 'error', code: child.code, target: input.service,
+                    message: `the command in service ${input.service} could not be run to completion` }] };
+    const signalNumber = child.signal ? osConstants.signals[child.signal] : undefined;
+    const status = signalNumber !== undefined ? 128 + signalNumber : child.exitCode;
+    return { kind: 'complete', status, diagnostics: status === 0 ? [] : [{
+                severity: 'error', code: ENVIRONMENT_CODES.EXECUTION_STEP_FAILED, target: input.service,
+                message: `the command in service ${input.service} ${child.signal ? `was terminated by ${child.signal}` : `exited with status ${child.exitCode}`}`,
+            }], result: { exitCode: child.exitCode, signal: child.signal } };
+}

package/dist/environment/application/setup.d.ts

@@ -0,0 +1,129 @@
+import type { ExecutePlanOutcome } from '../../environment-exec/execute.js';
+import { type CheckoutId, type ConfigSourceSnapshot, type EnvironmentCommandOutcome, type ExecutionPlan, type EnvironmentDiagnostic, type HolderId, type SetupExecutionEvidence, type SetupRefusalEvidence, type SourceProvenance, type StackId } from '../contract.js';
+import { type SetupObservation, type SetupResult } from '../setup.js';
+import type { InstructionPointerResult } from '../instruction-pointer.js';
+import type { SiblingInstructionFilesResult } from '../sibling-instructions.js';
+import { type ResolvedExecutable } from '../executable.js';
+import type { InstallPolicy, Sibling } from '../../schema.js';
+import { type StateNamespace } from '../state.js';
+import type { LifecycleHistoryTransition } from '../lifecycle-stage.js';
+import type { EnvironmentSeedPlan, EnvironmentSeedResult } from '../templates.js';
+import type { InstallPolicyLockfileObservation, InstallPolicyProjection } from '../install-policy-observation.js';
+import type { InstallPolicyResolution, ResolvedInstallPolicyBinding } from '../install-policy.js';
+import { type EnvironmentIgnoreRefusal, type ConsumedSetupCheckoutObservation, type SetupCheckoutProjection } from '../setup-observation.js';
+import type { LoadedConfigProjection } from '../../config/load.js';
+export interface SetupCommandInput {
+    configPath: string;
+    writeInstructionPointers?: boolean;
+    writeInstructionFiles?: boolean;
+    env?: Readonly<Record<string, string | undefined>>;
+    gitExecutable?: ResolvedExecutable;
+}
+export interface SetupCommandResult {
+    source: SourceProvenance;
+    siblings: readonly SetupResult[];
+    environmentFiles?: readonly Extract<EnvironmentSeedResult, {
+        kind: 'created' | 'unchanged';
+    }>[];
+    installPolicies?: readonly ResolvedInstallPolicyBinding[];
+}
+export interface SetupRunContext {
+    readonly source: SourceProvenance;
+    readonly mainCheckoutPath: string;
+    readonly siblingsRoot: string;
+    readonly siblings: readonly Sibling[];
+    readonly policyCatalog: readonly InstallPolicy[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly gitExecutable: ResolvedExecutable;
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly writeInstructionPointers: boolean;
+    readonly writeInstructionFiles: boolean;
+}
+export interface SetupRunContextInput {
+    readonly checkout: SetupCheckoutProjection;
+    readonly configuration: LoadedConfigProjection;
+    readonly env: Readonly<Record<string, string>>;
+    readonly gitExecutable: ResolvedExecutable;
+    readonly namespace: StateNamespace;
+    readonly observedAt: string;
+    readonly currentCheckoutPath: string;
+    readonly mainCheckoutPath: string;
+    readonly cockpitId: ConsumedSetupCheckoutObservation['cockpitId'];
+    readonly checkoutId: CheckoutId;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly sessionId: string;
+    readonly writeInstructionPointers?: boolean;
+    readonly writeInstructionFiles?: boolean;
+}
+export declare function issueSetupRunContext(input: SetupRunContextInput): EnvironmentCommandOutcome<SetupRunContext>;
+interface SiblingOperationInput {
+    readonly context: SetupRunContext;
+    readonly siblingIndex: number;
+    readonly sibling: Sibling;
+}
+interface TimedSiblingOperationInput extends SiblingOperationInput {
+    readonly observedAt: string;
+}
+export interface SetupCommandAdapters {
+    load(input: SetupCommandInput): Promise<EnvironmentCommandOutcome<SetupRunContext>>;
+    observedAt(): string;
+    observeGit(input: SiblingOperationInput): Promise<SetupObservation>;
+    planGit(input: SiblingOperationInput & {
+        readonly observation: SetupObservation;
+    }): Promise<EnvironmentCommandOutcome<SetupResult>>;
+    syncInstructionPointer?(input: Readonly<{
+        cockpitRoot: string;
+        siblingRoot: string;
+        write: boolean;
+    }>): Promise<InstructionPointerResult>;
+    syncInstructionFiles(input: Readonly<{
+        siblingRoot: string;
+        write: boolean;
+    }>): Promise<SiblingInstructionFilesResult>;
+    execute(plan: ExecutionPlan): Promise<ExecutePlanOutcome>;
+    observeSource(path: string): Promise<ConfigSourceSnapshot>;
+    recordStarted(input: Pick<SetupRunContext, 'namespace' | 'stackId' | 'holderId'> & {
+        readonly observedAt: string;
+    }): Promise<LifecycleHistoryTransition>;
+    withIgnore<T>(input: TimedSiblingOperationInput & {
+        readonly environmentFileIndex: number;
+        readonly environmentFile: NonNullable<Sibling['environment_files']>[number];
+    }, use: () => T extends PromiseLike<unknown> ? never : T): Promise<(T extends PromiseLike<unknown> ? never : T) | EnvironmentIgnoreRefusal | undefined>;
+    planSeed(input: SiblingOperationInput & {
+        readonly environmentFileIndex: number;
+        readonly environmentFile: NonNullable<Sibling['environment_files']>[number];
+    }): Promise<EnvironmentSeedPlan>;
+    seed(plan: EnvironmentSeedPlan): EnvironmentSeedResult;
+    observePolicy(input: TimedSiblingOperationInput & {
+        readonly checkoutRoot: string;
+        readonly checkoutId: CheckoutId;
+    }): Promise<InstallPolicyLockfileObservation>;
+    withPolicy<T>(observation: InstallPolicyLockfileObservation, input: TimedSiblingOperationInput & {
+        readonly checkoutRoot: string;
+        readonly checkoutId: CheckoutId;
+    }, use: (projection: InstallPolicyProjection) => T extends PromiseLike<unknown> ? never : T): Promise<(T extends PromiseLike<unknown> ? never : T) | undefined>;
+    resolvePolicy(input: SiblingOperationInput & {
+        readonly checkoutRoot: string;
+        readonly checkoutId: CheckoutId;
+        readonly projection?: InstallPolicyProjection;
+    }): InstallPolicyResolution;
+}
+export interface SetupApplicationResult extends SetupCommandResult {
+    execution?: SetupExecutionEvidence;
+}
+export type SetupApplicationOutcome = Exclude<EnvironmentCommandOutcome<SetupApplicationResult>, {
+    kind: 'refusal';
+}> | {
+    kind: 'refusal';
+    status: 2;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+    evidence?: SetupRefusalEvidence;
+    plan?: never;
+};
+export declare function setupEnvironment(input?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>> | undefined;
+export declare function runSetup(input: SetupCommandInput, adapters: SetupCommandAdapters): Promise<SetupApplicationOutcome>;
+export {};