@prismatic-io/lux 0.0.1

package/src/orchestrator/run-dir.ts

@@ -0,0 +1,209 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream, type WriteStream } from "node:fs";
+import { chmod, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { EvalCase, RunEvent } from "../core/index.js";
+import {
+  DEFAULT_RUN_TRACE_LIMITS,
+  type RunTraceLimitFailure,
+  type RunTraceLimits,
+  runTraceLimitDiagnostic,
+  runTraceLimitFailure,
+  terminalDiagnosticReserveBytes,
+} from "./trace-limits.js";
+
+const isoTimestampSafe = (d: Date): string => d.toISOString().replace(/[:.]/g, "-");
+
+export const slugifyCaseId = (id: string): string =>
+  id
+    .replace(/[^a-zA-Z0-9-_/]/g, "-")
+    .replace(/\/+/g, "/")
+    .replace(/-{2,}/g, "-");
+
+export type OpenedRunDir = {
+  path: string;
+  artifactsDir: string;
+  events: EventsAppender;
+  /** In-memory mirror of the appended event stream. Used by assertions. */
+  recorded: RunEvent[];
+  /** Write a JSON file into the run dir. */
+  writeJson: (relPath: string, value: unknown) => Promise<void>;
+  close: () => Promise<void>;
+};
+
+export type EventsAppender = {
+  append: (event: RunEvent) => RunTraceLimitFailure | null;
+  onLimitExceeded: (listener: (failure: RunTraceLimitFailure) => void) => () => void;
+  drain: () => Promise<void>;
+  flush: () => Promise<void>;
+};
+
+export const writeRunBundleJson = async (path: string, value: unknown): Promise<void> => {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+};
+
+type EventsAppenderOptions = {
+  limits?: RunTraceLimits;
+  onEvent?: (event: RunEvent) => void;
+};
+
+const validateTraceLimits = (limits: RunTraceLimits): void => {
+  if (!Number.isSafeInteger(limits.maxEvents) || limits.maxEvents < 1) {
+    throw new Error("run trace maxEvents must be a positive safe integer");
+  }
+  if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 1) {
+    throw new Error("run trace maxBytes must be a positive safe integer");
+  }
+  if (limits.maxBytes < terminalDiagnosticReserveBytes(limits)) {
+    throw new Error("run trace maxBytes must fit its terminal diagnostic");
+  }
+};
+
+/** Exported for tests; production code reaches it through {@link openRunDir}. */
+export const openEventsAppender = (
+  path: string,
+  options: EventsAppenderOptions = {},
+): EventsAppender => {
+  const limits = options.limits ?? DEFAULT_RUN_TRACE_LIMITS;
+  validateTraceLimits(limits);
+  const diagnosticReserveBytes = terminalDiagnosticReserveBytes(limits);
+  const stream: WriteStream = createWriteStream(path, { flags: "a", mode: 0o600 });
+  // Nothing awaits `pending` until flush(), so a rejected link in the chain
+  // would sit unhandled and crash the whole suite. Write and stream errors are
+  // recorded here instead and surfaced from flush() at the run boundary.
+  let firstError: Error | null = null;
+  const recordError = (err: Error): void => {
+    firstError ??= err;
+  };
+  stream.on("error", recordError);
+  let pending = Promise.resolve();
+  let closing: Promise<void> | null = null;
+  let eventCount = 0;
+  let bytes = 0;
+  let limitFailure: RunTraceLimitFailure | null = null;
+  const limitListeners = new Set<(failure: RunTraceLimitFailure) => void>();
+  const writeEvent = (event: RunEvent, line: string): void => {
+    eventCount++;
+    bytes += Buffer.byteLength(line);
+    options.onEvent?.(event);
+    pending = pending.then(
+      () =>
+        new Promise<void>((resolve) => {
+          stream.write(line, (err) => {
+            if (err) recordError(err);
+            resolve();
+          });
+        }),
+    );
+  };
+  const exceedLimit = (limit: RunTraceLimitFailure["limit"]): RunTraceLimitFailure => {
+    limitFailure = runTraceLimitFailure(limit, limits);
+    const diagnostic = runTraceLimitDiagnostic(limitFailure);
+    writeEvent(diagnostic, `${JSON.stringify(diagnostic)}\n`);
+    for (const listener of limitListeners) listener(limitFailure);
+    return limitFailure;
+  };
+  const append = (event: RunEvent): RunTraceLimitFailure | null => {
+    // A straggler (e.g. an abort firing after a failed setup already closed
+    // the run dir) must degrade to a no-op, not ERR_STREAM_WRITE_AFTER_END.
+    if (closing) return limitFailure;
+    if (limitFailure) return limitFailure;
+    const serialized = JSON.stringify(event);
+    const line = `${serialized}\n`;
+    if (eventCount + 1 >= limits.maxEvents) return exceedLimit("events");
+    if (bytes + Buffer.byteLength(line) + diagnosticReserveBytes > limits.maxBytes) {
+      return exceedLimit("bytes");
+    }
+    writeEvent(JSON.parse(serialized) as RunEvent, line);
+    return null;
+  };
+  const onLimitExceeded = (listener: (failure: RunTraceLimitFailure) => void): (() => void) => {
+    limitListeners.add(listener);
+    if (limitFailure) listener(limitFailure);
+    return () => limitListeners.delete(listener);
+  };
+  const drain = async (): Promise<void> => {
+    await pending;
+    if (firstError) throw firstError;
+  };
+  const flush = (): Promise<void> => {
+    closing ??= (async () => {
+      await drain();
+      await new Promise<void>((resolve) => {
+        stream.end((err: Error | null | undefined) => {
+          if (err) recordError(err);
+          resolve();
+        });
+      });
+    })();
+    return closing;
+  };
+  return { append, onLimitExceeded, drain, flush };
+};
+
+export type OpenRunDirOptions = {
+  runsRoot: string;
+  caseId: string;
+  driverName: string;
+  startedAt?: Date | undefined;
+  /** Tap on the event stream, called for every appended event. Must not throw. */
+  onEvent?: ((event: RunEvent) => void) | undefined;
+  /** Test-only override; production uses the reader's shared limits. */
+  traceLimits?: RunTraceLimits | undefined;
+};
+
+export const openRunDir = async (options: OpenRunDirOptions): Promise<OpenedRunDir> => {
+  const ts = isoTimestampSafe(options.startedAt ?? new Date());
+  const slug = slugifyCaseId(options.caseId);
+  const basePath = join(options.runsRoot, slug, slugifyCaseId(options.driverName), ts);
+  await mkdir(dirname(basePath), { recursive: true });
+  // Same case+driver+millisecond must not share a dir — their events.jsonl
+  // streams (opened with flags "a") would interleave silently. A bare mkdir
+  // is the reservation, so concurrent processes race on EEXIST instead of
+  // both passing an existsSync check.
+  let path = basePath;
+  for (let n = 2; ; n++) {
+    try {
+      await mkdir(path, { mode: 0o700 });
+      await chmod(path, 0o700);
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      path = `${basePath}-${n}`;
+    }
+  }
+  const artifactsDir = join(path, "artifacts");
+  await mkdir(artifactsDir, { recursive: true, mode: 0o700 });
+  await chmod(artifactsDir, 0o700);
+  const recorded: RunEvent[] = [];
+  const events = openEventsAppender(join(path, "events.jsonl"), {
+    ...(options.traceLimits ? { limits: options.traceLimits } : {}),
+    onEvent: (event) => {
+      recorded.push(event);
+      options.onEvent?.(structuredClone(event));
+    },
+  });
+  return {
+    path,
+    artifactsDir,
+    events,
+    recorded,
+    writeJson: (relPath, value) => writeRunBundleJson(join(path, relPath), value),
+    close: () => events.flush(),
+  };
+};
+
+export const writeFrozenCase = (
+  runDir: string,
+  evalCase: EvalCase,
+  casePath: string,
+): Promise<void> => writeRunBundleJson(join(runDir, "case.json"), { ...evalCase, casePath });