@b00dea/cockpit 0.0.0-stage → 0.1.0

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/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 {};