@wringer/core 0.0.0 → 0.1.1

package/src/builtins/pick-stop-plan.ts

@@ -0,0 +1,32 @@
+import type { RunView } from '../build-run-view.ts';
+import type { SupervisorReach } from './call-run-supervisor.ts';
+import type { StopData } from './stop-data-schema.ts';
+
+export interface StopInput {
+  readonly runID: string | undefined;
+  readonly status: RunView['status'] | undefined;
+  readonly reach: SupervisorReach;
+}
+
+export interface StopPlan {
+  readonly data: StopData;
+  readonly markCrashed: boolean;
+  readonly clearPointer: boolean;
+}
+
+// A supervisor that answered the stop ended the run itself. One that is gone left a run that still
+// reads as live, so the run is marked crashed and its log ends in a final status.
+export function pickStopPlan(input: StopInput): StopPlan {
+  if (input.runID === undefined) {
+    return { data: { run: null, stopped: false }, markCrashed: false, clearPointer: false };
+  }
+
+  const stopped = input.reach === 'answered';
+  const live = input.status === 'running' || input.status === 'starting';
+
+  return {
+    data: { run: input.runID, stopped },
+    markCrashed: !stopped && live,
+    clearPointer: true,
+  };
+}

package/src/builtins/start-run.ts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+import type { RunView } from '../build-run-view.ts';
+import { findOwnValue } from '../find-own-value.ts';
+import { readDefaultBase } from '../read-default-base.ts';
+import { readFingerprint } from '../read-fingerprint.ts';
+import { supervisorServiceName } from '../supervisor-protocol.ts';
+import { toWringerError } from '../to-wringer-error.ts';
+import type { BuiltinContext } from '../types.ts';
+import { WringerError } from '../wringer-error.ts';
+import { writeLateFailure } from '../write-late-failure.ts';
+import { callRunSupervisor, isSupervisorGone } from './call-run-supervisor.ts';
+import { pickStartAction } from './pick-start-action.ts';
+import type { StartFacts } from './pick-start-action.ts';
+
+export const runDataSchema = z.strictObject({
+  run: z.string(),
+  target: z.string(),
+  status: z.enum(['starting', 'running', 'crashed', 'ended']),
+  endpoints: z.record(z.string(), z.string()),
+  services: z.array(z.string()),
+  reused: z.boolean(),
+});
+
+export type RunData = z.infer<typeof runDataSchema>;
+
+export interface StartRunRequest {
+  readonly command: 'up' | 'attach';
+  readonly restart: boolean;
+  readonly readyTimeoutMs: number;
+}
+
+// `up` and `attach` hold the target's lock across check-and-create, so two at once never start two
+// supervisors. A live run is reused, keeping its doctor pass, unless the caller asks for a restart.
+export function startRun(ctx: BuiltinContext, request: StartRunRequest): Promise<RunData> {
+  return ctx.state.withTargetLock(ctx.targetName, async () => {
+    const pointers = await ctx.state.readPointers();
+
+    const currentID = findOwnValue(pointers.currentRun, ctx.targetName);
+    const current = currentID === undefined ? undefined : await ctx.state.readRun(currentID);
+
+    const reused = await settleCurrentRun(ctx, current, request.restart);
+
+    if (reused !== null) {
+      ctx.bindRun(reused.runID);
+
+      return toRunData(reused, true);
+    }
+
+    const runID = buildRunID(ctx.now());
+
+    ctx.bindRun(runID);
+
+    const base = await readDefaultBase(ctx.session.repoHost, ctx.session.root);
+
+    const fingerprint = await readFingerprint(ctx.session.repoHost, {
+      cwd: ctx.session.root,
+      base,
+      exclude: [ctx.wringer.stateDir],
+    });
+
+    // The caller has its timeout already once the deadline passes, so no run starts after it.
+    if (ctx.signal.aborted) {
+      throw new WringerError('timeout', {
+        message: `The command's deadline passed before run ${runID} started.`,
+        hint: 'Pass a longer `--timeout-ms`, then run `up` again.',
+      });
+    }
+
+    await ctx.state.appendEvent(runID, {
+      type: 'run-started',
+      at: ctx.now().toISOString(),
+      target: ctx.targetName,
+      mode: ctx.target.mode,
+      fingerprint,
+    });
+
+    await ctx.state.writePointers((latest) => ({
+      ...latest,
+      currentRun: { ...latest.currentRun, [ctx.targetName]: runID },
+    }));
+
+    try {
+      await ctx.session.supervisor.start({ runID, target: ctx.targetName });
+    } catch (error) {
+      // A run whose supervisor never started can never finish starting, so it ends here.
+      await ctx.state.appendEvent(runID, {
+        type: 'crashed',
+        at: ctx.now().toISOString(),
+        reason: `the supervisor could not start: ${toWringerError(error).message}`,
+      });
+
+      throw error;
+    }
+
+    try {
+      const ready = await waitForReady(ctx, runID, request.readyTimeoutMs);
+
+      return toRunData(ready, false);
+    } catch (error) {
+      await stopAbandonedRun(ctx, runID, request.command);
+
+      throw error;
+    }
+  });
+}
+
+// Carries out what `pickStartAction` asks for until the current run is reused or out of the way.
+// Resolves the run to reuse, or null once a new run may start. A ping that times out rejects, so a
+// slow supervisor is never taken for a dead one.
+async function settleCurrentRun(
+  ctx: BuiltinContext,
+  current: RunView | undefined,
+  restart: boolean,
+): Promise<RunView | null> {
+  let facts: StartFacts = { status: current?.status ?? null, restart, ping: null, stop: null };
+
+  for (;;) {
+    const action = pickStartAction(facts);
+
+    if (current === undefined || action === 'start') {
+      return null;
+    }
+
+    if (action === 'reuse') {
+      return current;
+    }
+
+    if (action === 'mark-crashed') {
+      await ctx.state.appendEvent(current.runID, {
+        type: 'crashed',
+        at: ctx.now().toISOString(),
+        reason: "the run's supervisor stopped answering",
+      });
+
+      return null;
+    }
+
+    facts =
+      action === 'ping'
+        ? {
+            ...facts,
+            ping: await callRunSupervisor(
+              ctx.session.supervisor,
+              current,
+              'ping',
+              makePingSignal(ctx),
+            ),
+          }
+        : {
+            ...facts,
+            stop: await callRunSupervisor(ctx.session.supervisor, current, 'stop', ctx.signal),
+          };
+  }
+}
+
+const pingTimeoutMs = 2000;
+
+function makePingSignal(ctx: BuiltinContext): AbortSignal {
+  return AbortSignal.any([ctx.signal, AbortSignal.timeout(pingTimeoutMs)]);
+}
+
+function toRunData(view: RunView, reused: boolean): RunData {
+  return {
+    run: view.runID,
+    target: view.target,
+    status: view.status,
+    endpoints: view.endpoints,
+    services: [...view.services],
+    reused,
+  };
+}
+
+function buildRunID(date: Date): string {
+  const random = Math.floor(Math.random() * 36 ** 4)
+    .toString(36)
+    .padStart(4, '0');
+
+  return `${date.getTime().toString(36)}-${random}`;
+}
+
+const readyPollMs = 50;
+
+async function waitForReady(
+  ctx: BuiltinContext,
+  runID: string,
+  timeoutMs: number,
+): Promise<RunView> {
+  const deadline = ctx.now().getTime() + timeoutMs;
+
+  while (ctx.now().getTime() < deadline) {
+    if (ctx.signal.aborted) {
+      throw new WringerError('timeout', {
+        message: `The command's deadline passed while run ${runID} started.`,
+        hint: 'Pass a longer `--timeout-ms`, then run `up` again.',
+      });
+    }
+
+    const view = await ctx.state.readRun(runID);
+
+    if (view?.status === 'running') {
+      return view;
+    }
+
+    if (view?.status === 'crashed' || view?.status === 'ended') {
+      throw new WringerError('environment', {
+        message: `Run ${runID} stopped while it started: ${view.crashReason ?? 'it ended'}.`,
+        hint: `Read .wringer/runs/${runID}/children/app.log and supervisor.log.`,
+      });
+    }
+
+    await ctx.wait(readyPollMs);
+  }
+
+  throw new WringerError('timeout', {
+    message: `Run ${runID} was not ready within ${timeoutMs} ms.`,
+    hint: `Read .wringer/runs/${runID}/children/app.log, then run \`up\` again.`,
+  });
+}
+
+// A run that missed its deadline must not keep its app and services up behind the error. The stop
+// waits for a socket the supervisor may not have opened yet, and as the command's own error answers
+// first, a failed stop can only go to the run's log.
+async function stopAbandonedRun(
+  ctx: BuiltinContext,
+  runID: string,
+  command: StartRunRequest['command'],
+): Promise<void> {
+  const socket = await readSupervisorSocket(ctx, runID);
+
+  if (socket === null) {
+    return;
+  }
+
+  await writeLateFailure(callSupervisorStop(ctx, socket), {
+    state: ctx.state,
+    runID,
+    command,
+    answered: null,
+    now: ctx.now,
+  });
+}
+
+const socketWaitMs = 10_000;
+
+// Resolves null once the run has ended, or when its supervisor never opens a socket.
+async function readSupervisorSocket(ctx: BuiltinContext, runID: string): Promise<string | null> {
+  const deadline = ctx.now().getTime() + socketWaitMs;
+
+  while (ctx.now().getTime() < deadline) {
+    const view = await ctx.state.readRun(runID);
+
+    if (view === undefined || view.status === 'crashed' || view.status === 'ended') {
+      return null;
+    }
+
+    if (view.supervisor !== null) {
+      return view.supervisor.socket;
+    }
+
+    await ctx.wait(readyPollMs);
+  }
+
+  return null;
+}
+
+const stopTimeoutMs = 15_000;
+
+// A supervisor that is already gone is the state the stop wants.
+async function callSupervisorStop(ctx: BuiltinContext, socket: string): Promise<void> {
+  try {
+    await ctx.session.supervisor.call({
+      socket,
+      request: { service: supervisorServiceName, method: 'stop', args: null },
+      signal: AbortSignal.timeout(stopTimeoutMs),
+    });
+  } catch (error) {
+    if (!isSupervisorGone(error)) {
+      throw error;
+    }
+  }
+}

package/src/builtins/stop-data-schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const stopDataSchema = z.strictObject({
+  run: z.string().nullable(),
+  stopped: z.boolean(),
+});
+
+export type StopData = z.infer<typeof stopDataSchema>;

package/src/builtins/stop-run.ts

@@ -0,0 +1,49 @@
+import { findOwnValue } from '../find-own-value.ts';
+import type { BuiltinContext } from '../types.ts';
+import { callRunSupervisor } from './call-run-supervisor.ts';
+import { pickStopPlan } from './pick-stop-plan.ts';
+import type { StopData } from './stop-data-schema.ts';
+
+// `down` and `detach` end the target's current run and clear its pointer, as `pickStopPlan`
+// decides. A stop call that fails other than with a gone supervisor rejects, and leaves the run and
+// its pointer for the next `down`.
+export function stopRun(ctx: BuiltinContext): Promise<StopData> {
+  return ctx.state.withTargetLock(ctx.targetName, async () => {
+    const pointers = await ctx.state.readPointers();
+
+    const runID = findOwnValue(pointers.currentRun, ctx.targetName);
+    const view = runID === undefined ? undefined : await ctx.state.readRun(runID);
+
+    if (runID !== undefined) {
+      ctx.bindRun(runID);
+    }
+
+    const reach =
+      view === undefined
+        ? 'gone'
+        : await callRunSupervisor(ctx.session.supervisor, view, 'stop', ctx.signal);
+
+    const plan = pickStopPlan({ runID, status: view?.status, reach });
+
+    if (runID !== undefined && plan.markCrashed) {
+      await ctx.state.appendEvent(runID, {
+        type: 'crashed',
+        at: ctx.now().toISOString(),
+        reason: "the run's supervisor was gone when the run was stopped",
+      });
+
+      await ctx.state.writeManifest(runID);
+    }
+
+    if (plan.clearPointer) {
+      await ctx.state.writePointers((latest) => ({
+        ...latest,
+        currentRun: Object.fromEntries(
+          Object.entries(latest.currentRun).filter(([target]) => target !== ctx.targetName),
+        ),
+      }));
+    }
+
+    return plan.data;
+  });
+}

package/src/call-supervisor.ts

@@ -0,0 +1,109 @@
+import { createConnection } from 'node:net';
+import { createInterface } from 'node:readline';
+import { isErrorCode } from './is-error-code.ts';
+import { supervisorResponseSchema } from './supervisor-protocol.ts';
+import type { SupervisorRequest } from './supervisor-protocol.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface SupervisorCall {
+  readonly socket: string;
+  readonly request: SupervisorRequest;
+  readonly signal: AbortSignal;
+}
+
+export async function callSupervisor(call: SupervisorCall): Promise<unknown> {
+  const line = await exchangeLine(call);
+
+  const response = supervisorResponseSchema.parse(JSON.parse(line));
+
+  if (!response.ok) {
+    throw new WringerError(response.error.code, {
+      message: response.error.message,
+      ...(response.error.hint === null ? {} : { hint: response.error.hint }),
+    });
+  }
+
+  return response.result;
+}
+
+// The longest a call waits for the supervisor's answer once the caller's signal aborts.
+export const supervisorCancelWaitMs = 2000;
+
+async function exchangeLine(call: SupervisorCall): Promise<string> {
+  // An abort that came before the listener never fires it, so a late call would still run.
+  if (call.signal.aborted) {
+    throw buildLateError();
+  }
+
+  const connection = createConnection({ path: call.socket });
+  const lines = createInterface({ input: connection });
+  const reply = Promise.withResolvers<string>();
+  let giveUp: ReturnType<typeof setTimeout> | undefined;
+
+  // The supervisor cancels the call itself before the caller's deadline, and its answer tells the
+  // caller the cancelled work has stopped, so the caller waits a bounded time for that answer.
+  const onAbort = (): void => {
+    giveUp = setTimeout(() => {
+      connection.destroy();
+
+      const failure =
+        call.request.deadlineAt === undefined ? buildLateError() : buildUnconfirmedError();
+
+      reply.reject(failure);
+    }, supervisorCancelWaitMs);
+  };
+
+  call.signal.addEventListener('abort', onAbort, { once: true });
+
+  // readline re-emits its input's errors, so both need a listener.
+  connection.on('error', (error) => {
+    reply.reject(toConnectionError(error));
+  });
+
+  lines.on('error', (error) => {
+    reply.reject(toConnectionError(error));
+  });
+
+  lines.once('line', (line) => {
+    reply.resolve(line);
+  });
+
+  lines.once('close', () => {
+    reply.reject(new WringerError('environment', { message: 'The supervisor closed the socket.' }));
+  });
+
+  connection.write(`${JSON.stringify(call.request)}\n`);
+
+  try {
+    return await reply.promise;
+  } finally {
+    clearTimeout(giveUp);
+
+    call.signal.removeEventListener('abort', onAbort);
+    lines.close();
+    connection.destroy();
+  }
+}
+
+function buildLateError(): WringerError {
+  return new WringerError('timeout', { message: 'The supervisor did not answer in time.' });
+}
+
+// A timeout tells the caller the cancelled work stopped, so a cancel the supervisor never answered
+// fails with an environment error.
+export function buildUnconfirmedError(): WringerError {
+  return new WringerError('environment', {
+    message: `The run's supervisor did not confirm within ${supervisorCancelWaitMs} ms that the cancelled call stopped, so its work may still run.`,
+    hint: 'Run `up --restart` to start a new run.',
+  });
+}
+
+function toConnectionError(error: Error): WringerError {
+  const dead = isErrorCode(error, 'ECONNREFUSED') || isErrorCode(error, 'ENOENT');
+  const code = dead ? 'not-running' : 'environment';
+
+  return new WringerError(code, {
+    message: `The run's supervisor is not reachable: ${error.message}`,
+    hint: 'Run `up --restart`, or `attach` again, to start a new run.',
+  });
+}

package/src/cap-data.ts

@@ -0,0 +1,43 @@
+import { createEvidenceWriter } from './create-evidence-writer.ts';
+import type { Evidence } from './envelope.ts';
+import { toWringerError } from './to-wringer-error.ts';
+import type { EvidenceFiles } from './types.ts';
+import type { WringerError } from './wringer-error.ts';
+
+export const dataCapBytes = 32 * 1024;
+
+export interface CapRequest {
+  readonly root: string;
+  readonly directory: string;
+  readonly now: () => Date;
+  readonly files: EvidenceFiles;
+}
+
+export interface CappedData {
+  readonly data: unknown;
+  readonly evidence: readonly Evidence[];
+  readonly truncatedPath: string | null;
+  readonly failure: WringerError | null;
+}
+
+// Over the cap, the full data goes to an evidence file and the envelope carries its path. Data
+// that fails to serialize or to write still yields an envelope, one that carries the failure.
+export async function capData(data: unknown, request: CapRequest): Promise<CappedData> {
+  try {
+    const text = JSON.stringify(data ?? null);
+
+    if (Buffer.byteLength(text) <= dataCapBytes) {
+      return { data, evidence: [], truncatedPath: null, failure: null };
+    }
+
+    const evidence = await createEvidenceWriter(request).writer.writeFile(
+      'payload',
+      'payload.json',
+      text,
+    );
+
+    return { data: null, evidence: [evidence], truncatedPath: evidence.path, failure: null };
+  } catch (error) {
+    return { data: null, evidence: [], truncatedPath: null, failure: toWringerError(error) };
+  }
+}

package/src/collect-driver-configs.ts

@@ -0,0 +1,36 @@
+import type { ConfiguredDriver, DriverConfigContext, TargetDefinition, Wringer } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface ConfiguredEntry {
+  readonly name: string;
+  readonly serviceNames: readonly string[];
+  readonly configured: ConfiguredDriver;
+}
+
+// A driver works on a target only when the target gives it a config. The target's config function
+// sees the run's endpoints, so the config is built per run.
+export function collectDriverConfigs(
+  wringer: Wringer,
+  target: TargetDefinition,
+  ctx: DriverConfigContext,
+): readonly ConfiguredEntry[] {
+  return wringer.drivers.flatMap((driver) => {
+    const build = target.drivers?.[driver.name];
+
+    if (build === undefined) {
+      return [];
+    }
+
+    const configured = driver.configure(build(ctx));
+
+    if (!configured.ok) {
+      throw new WringerError('usage', {
+        message: `The ${driver.name} config of target ${ctx.target} is not valid: ${configured.message}`,
+      });
+    }
+
+    return [
+      { name: driver.name, serviceNames: driver.serviceNames, configured: configured.prepared },
+    ];
+  });
+}

package/src/create-directory.ts

@@ -0,0 +1,6 @@
+import { mkdir } from 'node:fs/promises';
+
+// Creates the folder and every missing parent; a folder that exists is no error.
+export async function createDirectory(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+}

package/src/create-evidence-writer.ts

@@ -0,0 +1,82 @@
+import { basename, join, relative } from 'node:path';
+import type { Evidence } from './envelope.ts';
+import type { EvidenceFiles, EvidenceWriter } from './types.ts';
+
+export interface EvidenceWriterOptions {
+  readonly root: string;
+  readonly directory: string;
+  readonly now: () => Date;
+  readonly files: EvidenceFiles;
+}
+
+export interface CollectingEvidenceWriter {
+  readonly writer: EvidenceWriter;
+  readonly collected: readonly Evidence[];
+}
+
+// Each path in an envelope is relative to the worktree root, so it reads the same from any folder.
+export function createEvidenceWriter(options: EvidenceWriterOptions): CollectingEvidenceWriter {
+  const collected: Evidence[] = [];
+
+  const record = (kind: string, path: string, content: Uint8Array): Evidence => {
+    const evidence = {
+      kind,
+      path: relative(options.root, path),
+      sha256: new Bun.CryptoHasher('sha256').update(content).digest('hex'),
+    };
+
+    collected.push(evidence);
+
+    return evidence;
+  };
+
+  return {
+    collected,
+    writer: {
+      directory: options.directory,
+      writeFile: async (kind, name, content) => {
+        const bytes = typeof content === 'string' ? Buffer.from(content) : content;
+
+        await options.files.createDirectory(options.directory);
+
+        const path = await writeNumberedFile(
+          options.files,
+          options.directory,
+          `${formatStamp(options.now())}-${basename(name)}`,
+          bytes,
+        );
+
+        return record(kind, path, bytes);
+      },
+      addFile: async (kind, path) => {
+        const bytes = await options.files.readBytes(path);
+
+        return record(kind, path, bytes);
+      },
+    },
+  };
+}
+
+// Two writes in one millisecond, from this process or another, can share a name, so the write
+// creates the file exclusively and numbers the name until one is free.
+async function writeNumberedFile(
+  files: EvidenceFiles,
+  directory: string,
+  name: string,
+  bytes: Uint8Array,
+): Promise<string> {
+  for (let attempt = 0; ; attempt += 1) {
+    const numbered = attempt === 0 ? name : `${attempt}-${name}`;
+    const path = join(directory, numbered);
+
+    const created = await files.writeNewFile(path, bytes);
+
+    if (created) {
+      return path;
+    }
+  }
+}
+
+function formatStamp(date: Date): string {
+  return date.toISOString().replaceAll(/[:.]/gu, '-');
+}