@wringer/core 0.1.0 → 0.1.1

package/src/answer-supervisor-connection.ts

@@ -0,0 +1,117 @@
+import { createInterface } from 'node:readline';
+import type { Duplex } from 'node:stream';
+import { finished } from 'node:stream/promises';
+import { supervisorRequestSchema } from './supervisor-protocol.ts';
+import type { SupervisorRequest, SupervisorResponse } from './supervisor-protocol.ts';
+import { toWringerError } from './to-wringer-error.ts';
+
+export type SupervisorRequestHandler = (
+  request: SupervisorRequest,
+  signal: AbortSignal,
+) => Promise<unknown>;
+
+export interface SupervisorConnectionOptions {
+  readonly answerRequest: SupervisorRequestHandler;
+
+  // A connection that fails, such as one the client resets, ends that connection only.
+  readonly onTransportError: (error: unknown) => void;
+}
+
+// Answers the first line, then ends the connection, and settles once the answer has flushed. Every
+// failure is caught here. When `closing` aborts, a connection that sent no request yet ends at once,
+// so it cannot keep the process alive.
+export async function answerSupervisorConnection(
+  connection: Duplex,
+  options: SupervisorConnectionOptions,
+  closing: AbortSignal,
+): Promise<void> {
+  let reported: unknown = null;
+
+  // The line reader rejects with the error the connection emitted, so each is reported once.
+  const fail = (error: unknown): void => {
+    if (error !== reported) {
+      reported = error;
+
+      options.onTransportError(error);
+    }
+
+    connection.destroy();
+  };
+
+  // A connection error with no listener is thrown, and would end the supervisor.
+  connection.on('error', fail);
+
+  const caller = new AbortController();
+
+  // A caller that gives up, such as at its deadline, closes the connection before the answer.
+  connection.once('close', () => {
+    caller.abort();
+  });
+
+  const lines = createInterface({ input: connection });
+
+  // readline re-emits the connection's errors, also after the loop below has stopped listening,
+  // such as an EPIPE once the caller left.
+  lines.on('error', fail);
+
+  let answering = false;
+
+  // A destroyed connection never ends the line loop, so the reader closes too.
+  const endIdle = (): void => {
+    if (!answering) {
+      lines.close();
+      connection.destroy();
+    }
+  };
+
+  closing.addEventListener('abort', endIdle, { once: true });
+
+  if (closing.aborted) {
+    endIdle();
+  }
+
+  try {
+    for await (const line of lines) {
+      answering = true;
+
+      const response = await answerLine(line, options.answerRequest, caller.signal);
+
+      connection.end(`${response}\n`);
+
+      await finished(connection, { readable: false });
+
+      break;
+    }
+  } catch (error) {
+    fail(error);
+  } finally {
+    closing.removeEventListener('abort', endIdle);
+  }
+}
+
+// A service may return a value JSON cannot hold, such as a bigint, so the result is serialized
+// inside the try and its failure reaches the caller as an error response.
+async function answerLine(
+  line: string,
+  handle: SupervisorRequestHandler,
+  signal: AbortSignal,
+): Promise<string> {
+  try {
+    const request = supervisorRequestSchema.parse(JSON.parse(line));
+
+    const result = await handle(request, signal);
+
+    const response: SupervisorResponse = { ok: true, result: result ?? null };
+
+    return JSON.stringify(response);
+  } catch (error) {
+    const failure = toWringerError(error);
+
+    const response: SupervisorResponse = {
+      ok: false,
+      error: { code: failure.code, message: failure.message, hint: failure.hint ?? null },
+    };
+
+    return JSON.stringify(response);
+  }
+}

package/src/app-machine.ts

@@ -0,0 +1,174 @@
+import { match } from 'ts-pattern';
+import { assign, fromPromise, setup } from 'xstate';
+import type { Endpoints } from './run-events.ts';
+import { toWringerError } from './to-wringer-error.ts';
+import { WringerError } from './wringer-error.ts';
+
+// The process and log work of one launched app, which the machine runs as actions and actors.
+interface AppMachineInput {
+  readonly readyTimeoutMs: number;
+
+  // Tells the run the app failed after its start, so the run stops.
+  readonly reportCrash: (reason: string) => void;
+
+  // Kills what is left of the app's process group once the app itself has exited.
+  readonly killGroup: () => void;
+
+  // Runs the stop command, signals the app, waits for it, then waits a bounded time for its log.
+  readonly stopApp: () => Promise<void>;
+}
+
+export type AppStart =
+  | { readonly kind: 'pending' }
+  | { readonly kind: 'ready'; readonly endpoints: Endpoints }
+  | { readonly kind: 'failed'; readonly failure: WringerError };
+
+interface AppContext extends AppMachineInput {
+  readonly start: AppStart;
+
+  // Why the app's output could not reach its log, at any point of its life.
+  readonly logFailure: string | null;
+  readonly stopFailure: WringerError | null;
+}
+
+type AppEvent =
+  | { readonly type: 'ready'; readonly endpoints: Endpoints }
+  | { readonly type: 'exited'; readonly exitCode: number }
+  | { readonly type: 'log.failed'; readonly reason: string }
+  | { readonly type: 'abort' }
+  | { readonly type: 'stop' };
+
+const appTypes: { context?: AppContext; events?: AppEvent; input?: AppMachineInput } = {};
+const stoppedBeforeReady = 'The run stopped before the app was ready.';
+
+// An exit or a lost log fails a start that is not ready, and is a crash the run hears of once after
+// it. Each stop waits for the app and its log. The caller waits for the tags: `settled` once the
+// start is decided, and `done` once the app is down.
+export const appMachine = setup({
+  types: appTypes,
+  actors: {
+    stopApp: fromPromise<null, { readonly run: () => Promise<void> }>(async (args) => {
+      await args.input.run();
+
+      return null;
+    }),
+  },
+  delays: {
+    readyTimeout: (args) => args.context.readyTimeoutMs,
+  },
+  actions: {
+    keepEndpoints: assign({
+      start: (args): AppStart =>
+        args.event.type === 'ready'
+          ? { kind: 'ready', endpoints: args.event.endpoints }
+          : args.context.start,
+    }),
+    keepLogFailure: assign({
+      logFailure: (args) =>
+        args.event.type === 'log.failed' ? args.event.reason : args.context.logFailure,
+    }),
+    failStart: assign({
+      start: (args): AppStart => ({
+        kind: 'failed',
+        failure: new WringerError('environment', { message: describeFailure(args.event) }),
+      }),
+    }),
+    failStartOnTimeout: assign({
+      start: (args): AppStart => ({
+        kind: 'failed',
+        failure: new WringerError('timeout', {
+          message: `The app printed no ready line within ${args.context.readyTimeoutMs} ms.`,
+        }),
+      }),
+    }),
+    reportCrash: (args) => {
+      args.context.reportCrash(describeFailure(args.event));
+    },
+    killGroup: (args) => {
+      args.context.killGroup();
+    },
+  },
+}).createMachine({
+  context: (args) => ({
+    ...args.input,
+    start: { kind: 'pending' },
+    logFailure: null,
+    stopFailure: null,
+  }),
+  initial: 'starting',
+  states: {
+    starting: {
+      after: { readyTimeout: { target: 'failingStart', actions: 'failStartOnTimeout' } },
+      on: {
+        ready: { target: 'running', actions: 'keepEndpoints' },
+        exited: { target: 'failingStart', actions: ['killGroup', 'failStart', 'reportCrash'] },
+
+        // The start failure names this log failure; only a later one fails the stop as well.
+        'log.failed': { target: 'failingStart', actions: ['failStart', 'reportCrash'] },
+        abort: { target: 'failingStart', actions: 'failStart' },
+      },
+    },
+    failingStart: {
+      invoke: {
+        // oxlint-disable-next-line zgeoff/no-abbreviated-names -- xstate names this key `src`
+        src: 'stopApp',
+        input: (args) => ({ run: args.context.stopApp }),
+        onDone: 'startFailed',
+        onError: {
+          target: 'startFailed',
+          actions: assign({ stopFailure: (args) => toWringerError(args.event.error) }),
+        },
+      },
+      on: {
+        exited: { actions: 'killGroup' },
+        'log.failed': { actions: 'keepLogFailure' },
+      },
+    },
+    startFailed: { tags: ['settled', 'done'], type: 'final' },
+    running: {
+      tags: ['settled'],
+      on: {
+        exited: { target: 'crashed', actions: ['killGroup', 'reportCrash'] },
+        'log.failed': { target: 'crashed', actions: ['keepLogFailure', 'reportCrash'] },
+        stop: 'stopping',
+      },
+    },
+    crashed: {
+      tags: ['settled'],
+      on: {
+        exited: { actions: 'killGroup' },
+        'log.failed': { actions: 'keepLogFailure' },
+        stop: 'stopping',
+      },
+    },
+    stopping: {
+      tags: ['settled'],
+      invoke: {
+        // oxlint-disable-next-line zgeoff/no-abbreviated-names -- xstate names this key `src`
+        src: 'stopApp',
+        input: (args) => ({ run: args.context.stopApp }),
+        onDone: 'stopped',
+        onError: {
+          target: 'stopped',
+          actions: assign({ stopFailure: (args) => toWringerError(args.event.error) }),
+        },
+      },
+      on: {
+        exited: { actions: 'killGroup' },
+        'log.failed': { actions: 'keepLogFailure' },
+      },
+    },
+    stopped: { tags: ['settled', 'done'], type: 'final' },
+  },
+});
+
+function describeFailure(event: AppEvent): string {
+  return match(event)
+    .with({ type: 'exited' }, (exited) => `The app exited with code ${exited.exitCode}.`)
+    .with(
+      { type: 'log.failed' },
+      (failed) => `The app's output could not be logged: ${failed.reason}`,
+    )
+    .with({ type: 'ready' }, { type: 'abort' }, { type: 'stop' }, () => stoppedBeforeReady)
+    .exhaustive();
+}

package/src/append-run-event.ts

@@ -0,0 +1,131 @@
+import { dirname } from 'node:path';
+import { withFileLock } from '@zgeoff/std/with-file-lock';
+import { match } from 'ts-pattern';
+import type { StateFileSystem } from './create-node-state-file-system.ts';
+import { getLockValue } from './get-lock-value.ts';
+import { parseRunLog } from './parse-run-log.ts';
+import type { RunEvent, RunEventType } from './run-events.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface AppendRunEventRequest {
+  readonly fs: StateFileSystem;
+  readonly logPath: string;
+  readonly lockPath: string;
+  readonly lockTimeoutMs: number;
+  readonly line: string;
+  readonly event: RunEvent;
+
+  // Decides from the log as it stands under the lock whether the event may still be written.
+  readonly refuse: ((events: readonly RunEvent[]) => WringerError | null) | null;
+}
+
+// The only writer of a run's log, under the run's lock. Resolves whether it wrote, and rejects
+// with the refusal when `refuse` returns one.
+export async function appendRunEvent(request: AppendRunEventRequest): Promise<boolean> {
+  await request.fs.createDirectory(dirname(request.lockPath));
+
+  const result = await withFileLock(
+    request.lockPath,
+    async () => {
+      const read = await request.fs.readText(request.logPath);
+
+      const text = read ?? '';
+      const refusal = request.refuse === null ? null : request.refuse(parseRunLog(text));
+
+      if (refusal !== null) {
+        return refusal;
+      }
+
+      const plan = pickLogAppend(text, request.event);
+
+      if (plan.truncateBytes !== null) {
+        await request.fs.truncateFile(request.logPath, plan.truncateBytes);
+      }
+
+      if (plan.append) {
+        await request.fs.appendText(request.logPath, request.line);
+      }
+
+      return plan.append;
+    },
+    { waitMs: request.lockTimeoutMs },
+  );
+
+  const written = getLockValue(request.lockPath, result);
+
+  if (written instanceof WringerError) {
+    throw written;
+  }
+
+  return written;
+}
+
+interface LogAppendPlan {
+  readonly truncateBytes: number | null;
+  readonly append: boolean;
+}
+
+// A writer killed mid-line leaves a torn last line, which is cut so the new event starts a line of
+// its own. An event whose status move the table refuses, such as a late `crashed` after
+// `run-ended`, is dropped.
+function pickLogAppend(text: string, event: RunEvent): LogAppendPlan {
+  const whole = text.slice(0, text.lastIndexOf('\n') + 1);
+  const truncateBytes = whole.length < text.length ? Buffer.byteLength(whole) : null;
+  const status = foldRunStatus(parseRunLog(whole));
+  const move = findRunStatusMove(event.type);
+
+  return {
+    truncateBytes,
+    append: status === null || move === null || canMoveRunStatus(status, move),
+  };
+}
+
+export type RunStatus = 'starting' | 'running' | 'crashed' | 'ended';
+
+// Null for a log that has not started yet.
+function foldRunStatus(events: readonly RunEvent[]): RunStatus | null {
+  const [first, ...rest] = events;
+
+  if (first?.type !== 'run-started') {
+    return null;
+  }
+
+  return rest.reduce<RunStatus>((status, event) => {
+    const move = findRunStatusMove(event.type);
+
+    return move !== null && canMoveRunStatus(status, move) ? move : status;
+  }, 'starting');
+}
+
+export function findRunStatusMove(eventType: RunEventType): RunStatus | null {
+  return match(eventType)
+    .returnType<RunStatus | null>()
+    .with('run-ready', () => 'running')
+    .with('crashed', () => 'crashed')
+    .with('run-ended', () => 'ended')
+    .with(
+      'run-started',
+      'supervisor-ready',
+      'launch-ready',
+      'service-ready',
+      'doctor-passed',
+      'doctor-failed',
+      'envelope',
+      'internal-error',
+      'late-failure',
+      () => null,
+    )
+    .exhaustive();
+}
+
+// A run's status lives only in its log, as events. These are the moves an event may make.
+const runStatusMoves: Readonly<Record<RunStatus, readonly RunStatus[]>> = {
+  starting: ['running', 'crashed', 'ended'],
+  running: ['crashed', 'ended'],
+  crashed: ['ended'],
+  ended: [],
+};
+
+export function canMoveRunStatus(from: RunStatus, to: RunStatus): boolean {
+  return runStatusMoves[from].includes(to);
+}

package/src/bind-drivers.ts

@@ -0,0 +1,33 @@
+import type {
+  ActionDefinition,
+  AnyDrivers,
+  CheckDefinition,
+  CommandSpec,
+  TargetDefinition,
+} from './types.ts';
+
+export interface BoundHelpers<Ds extends AnyDrivers> {
+  readonly drivers: Ds;
+  readonly defineAction: <Input, Data>(
+    action: ActionDefinition<Input, Data, Ds>,
+  ) => ActionDefinition<Input, Data, Ds>;
+  readonly defineTarget: <Target extends TargetDefinition<Ds>>(target: Target) => Target;
+  readonly defineCommand: <Args, Data>(
+    spec: CommandSpec<Args, Data, Ds>,
+  ) => CommandSpec<Args, Data, Ds>;
+  readonly defineCheck: <Input, Data>(
+    check: CheckDefinition<Input, Data, Ds>,
+  ) => CheckDefinition<Input, Data, Ds>;
+}
+
+// The repo binds its helpers once, in its drivers file, so every action, target, command and check
+// it defines elsewhere is typed against its own drivers without naming them again.
+export function bindDrivers<const Ds extends AnyDrivers>(drivers: Ds): BoundHelpers<Ds> {
+  return {
+    drivers,
+    defineAction: (action) => action,
+    defineTarget: (target) => target,
+    defineCommand: (spec) => spec,
+    defineCheck: (check) => check,
+  };
+}

package/src/build-commands.ts

@@ -0,0 +1,104 @@
+import { prepareArgs } from './prepare-args.ts';
+import type {
+  ActionDefinition,
+  AnyDrivers,
+  BuiltinCommandSpec,
+  CheckDefinition,
+  CommandSpec,
+  DriveContext,
+  DriverClients,
+  RegisteredCommand,
+  RunnableRepoCheck,
+} from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+// Each function here closes over one command's own types and hands the registry an erased entry,
+// so commands of every argument type share one map without a type assertion.
+export function buildBuiltinCommand<Args, Data>(
+  spec: BuiltinCommandSpec<Args, Data>,
+): RegisteredCommand {
+  return {
+    kind: 'builtin',
+    info: spec,
+    prepare: (raw) =>
+      prepareArgs(spec.args, raw, (args) => ({
+        effect: spec.effect ?? 'write',
+        run: (ctx) => spec.run(args, ctx),
+      })),
+  };
+}
+
+export function buildRepoCommand<Args, Data, Ds extends AnyDrivers>(
+  spec: CommandSpec<Args, Data, Ds>,
+  targets: readonly string[] | undefined,
+  driverNames: readonly string[],
+): RegisteredCommand {
+  return {
+    kind: 'repo',
+    info: spec,
+    targets,
+    prepare: (raw) =>
+      prepareArgs(spec.args, raw, (args) => ({
+        effect: spec.decideEffect?.(args) ?? spec.effect ?? 'write',
+        run: (ctx: DriveContext) => spec.run(args, toTypedDriveContext<Ds>(ctx, driverNames)),
+      })),
+  };
+}
+
+export function buildActionCommand<Input, Data, Ds extends AnyDrivers>(
+  action: ActionDefinition<Input, Data, Ds>,
+  driverNames: readonly string[],
+): RegisteredCommand {
+  return buildRepoCommand<Input, Data, Ds>(
+    {
+      path: ['action', action.name],
+      summary: action.summary,
+      args: action.input,
+      data: action.data,
+      effect: action.effect,
+      timeoutMs: action.timeoutMs,
+      run: action.run,
+    },
+    action.targets,
+    driverNames,
+  );
+}
+
+export function buildRepoCheck<Input, Data, Ds extends AnyDrivers>(
+  check: CheckDefinition<Input, Data, Ds>,
+  driverNames: readonly string[],
+): RunnableRepoCheck {
+  return {
+    name: check.name,
+    timeoutMs: check.timeoutMs,
+    run: async (ctx) => {
+      const typed = toTypedDriveContext<Ds>(ctx, driverNames);
+
+      const data = await check.run(check.input.parse({}), typed);
+
+      check.data.parse(data);
+    },
+  };
+}
+
+// Dispatch puts a client for every registered driver in `drivers`, and a target that gives a driver
+// no config gets a client that refuses each call, so every name the repo typed is present.
+function toTypedDriveContext<Ds extends AnyDrivers>(
+  ctx: DriveContext,
+  driverNames: readonly string[],
+): DriveContext<Ds> {
+  const clients = ctx.drivers;
+
+  if (!hasDriverClients<Ds>(clients, driverNames)) {
+    throw new WringerError('internal', { message: 'The drive context lacks a driver client.' });
+  }
+
+  return { ...ctx, drivers: clients };
+}
+
+function hasDriverClients<Ds extends AnyDrivers>(
+  clients: DriveContext['drivers'],
+  driverNames: readonly string[],
+): clients is DriverClients<Ds> {
+  return driverNames.every((name) => Object.hasOwn(clients, name));
+}

package/src/build-envelope-json-schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { envelopeSchema, streamEventSchema } from './envelope.ts';
+
+// zod leaves the envelope's two refinements out of the JSON Schema, so they are written here: an
+// envelope has an error exactly when it is not ok, and `truncated` comes with `truncatedPath`.
+const envelopeRules = {
+  oneOf: [
+    { type: 'object', properties: { ok: { const: true }, error: { type: 'null' } } },
+    { type: 'object', properties: { ok: { const: false }, error: { type: 'object' } } },
+  ],
+  dependentRequired: { truncated: ['truncatedPath'], truncatedPath: ['truncated'] },
+};
+
+// The published schema covers both lines a command can write: an NDJSON event of a streaming
+// command, and the one envelope that ends every command.
+export function buildEnvelopeJSONSchema(): Record<string, unknown> {
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/@wringer/core/envelope.schema.json',
+    title: 'wringer envelope',
+    $defs: {
+      envelope: { ...buildSubschema(envelopeSchema), ...envelopeRules },
+      streamEvent: buildSubschema(streamEventSchema),
+    },
+    $ref: '#/$defs/envelope',
+  };
+}
+
+// Only the root of a JSON Schema document may name its dialect.
+function buildSubschema(schema: z.ZodType): Record<string, unknown> {
+  const { $schema: _dialect, ...subschema } = z.toJSONSchema(schema, { io: 'output' });
+
+  return subschema;
+}

package/src/build-envelope.ts

@@ -0,0 +1,40 @@
+import { envelopeVersion } from './envelope-version.ts';
+import type { Envelope, Evidence } from './envelope.ts';
+import type { WringerError } from './wringer-error.ts';
+
+export interface EnvelopeInput {
+  readonly command: string;
+  readonly target: string | null;
+  readonly instance: string | null;
+  readonly feature: string | null;
+  readonly sha: string | null;
+  readonly durationMs: number;
+  readonly data: unknown;
+  readonly evidence: readonly Evidence[];
+  readonly cursors: Readonly<Record<string, number>>;
+  readonly truncatedPath: string | null;
+  readonly error: WringerError | null;
+}
+
+export function buildEnvelope(input: EnvelopeInput): Envelope {
+  return {
+    wringer: envelopeVersion,
+    ok: input.error === null,
+    command: input.command,
+    target: input.target,
+    instance: input.instance,
+    feature: input.feature,
+    sha: input.sha,
+    durationMs: Math.max(0, Math.round(input.durationMs)),
+    data: input.data ?? null,
+    evidence: [...input.evidence],
+    cursors: { ...input.cursors },
+    ...(input.truncatedPath === null
+      ? {}
+      : { truncated: true, truncatedPath: input.truncatedPath }),
+    error:
+      input.error === null
+        ? null
+        : { code: input.error.code, message: input.error.message, hint: input.error.hint ?? null },
+  };
+}

package/src/build-launch-guard.ts

@@ -0,0 +1,5 @@
+// setpriv asks the kernel to kill the app when the supervisor dies; hosts without setpriv, such as
+// macOS, run the app without that guard.
+export function buildLaunchGuard(setprivPath: string | null): readonly string[] {
+  return setprivPath === null ? [] : ['setpriv', '--pdeathsig', 'KILL', '--'];
+}

package/src/build-manifest-write.ts

@@ -0,0 +1,26 @@
+import type { RunView } from './build-run-view.ts';
+
+export interface ManifestWrite {
+  readonly path: string;
+  readonly text: string;
+}
+
+// A run with no log yet gets no manifest.
+export function buildManifestWrite(path: string, view: RunView | undefined): ManifestWrite | null {
+  if (view === undefined) {
+    return null;
+  }
+
+  const manifest = {
+    target: view.target,
+    instance: view.runID,
+    mode: view.mode,
+    fingerprint: view.fingerprint,
+    status: view.status,
+    doctor: { state: view.doctor, results: view.doctorResults },
+    startedAt: view.startedAt,
+    endedAt: view.endedAt,
+  };
+
+  return { path, text: `${JSON.stringify(manifest, null, 2)}\n` };
+}