@wringer/stream 0.0.0-stage → 0.1.0

package/src/start-stream-recorder.ts

@@ -0,0 +1,354 @@
+import { join } from 'node:path';
+import { WringerError } from '@wringer/core';
+import type { Access, Host } from '@wringer/core';
+import { createActor } from 'xstate';
+import { z } from 'zod';
+import { buildFileStep } from './build-file-step.ts';
+import type { FileFollowState } from './build-file-step.ts';
+import { collectLines } from './collect-lines.ts';
+import { pickCommandStopDelay } from './pick-command-stop-delay.ts';
+import type { FileChunk, FilePosition } from './read-file-from.ts';
+import { recordWriterMachine } from './record-writer-machine.ts';
+import { sourcePhaseMachine } from './source-phase-machine.ts';
+import type { SourceDetails, SourcePhase } from './source-phase-machine.ts';
+
+const commandSourceSchema = z.strictObject({ command: z.array(z.string().min(1)).min(1) });
+const fileSourceSchema = z.strictObject({ file: z.string().min(1) });
+
+export const streamSourceSchema = z.union([commandSourceSchema, fileSourceSchema]);
+
+export type StreamSource = z.infer<typeof streamSourceSchema>;
+
+export interface RecorderRequest {
+  readonly sources: Readonly<Record<string, StreamSource>>;
+  readonly directory: string;
+  readonly host: Host;
+  readonly access: Access;
+  readonly now: () => Date;
+  readonly createDirectory: (path: string) => Promise<void>;
+  readonly appendText: (path: string, text: string) => Promise<void>;
+  readonly readFileFrom: (
+    path: string,
+    from: FilePosition,
+    limitBytes: number,
+  ) => Promise<FileChunk>;
+
+  // A file source polls through this; it settles early, without rejecting, once the signal aborts.
+  readonly wait: (delayMs: number, signal: AbortSignal) => Promise<void>;
+
+  // At most this many records wait behind the batch being written; a source that logs faster loses
+  // the excess, and the stream says how many lines it lost.
+  readonly pendingLimit: number;
+}
+
+export const sourceStatusSchema = z.strictObject({
+  name: z.string(),
+  state: z.enum(['running', 'exited', 'failed']),
+  detail: z.string().nullable(),
+});
+
+type SourceStatus = z.infer<typeof sourceStatusSchema>;
+
+export interface StreamRecorder {
+  readonly status: () => readonly SourceStatus[];
+  readonly stop: () => Promise<void>;
+}
+
+// Follows each source for the whole run and appends each line to `<name>.ndjson` as `{ at, line }`.
+// A `command` source runs on the target's host; a `file` source is read where the run lives.
+export async function startStreamRecorder(request: RecorderRequest): Promise<StreamRecorder> {
+  await request.createDirectory(request.directory);
+
+  const lifetime = new AbortController();
+
+  const followers = Object.entries(request.sources).map(([name, source]) =>
+    followSource({ ...request, name, source, signal: lifetime.signal }),
+  );
+
+  return {
+    status: () => followers.map((follower) => follower.status()),
+    stop: async () => {
+      lifetime.abort();
+
+      const readFailures = await Promise.all(followers.map((follower) => follower.done));
+      const settled = await Promise.allSettled(followers.map((follower) => follower.drain()));
+
+      const failures = [
+        ...readFailures.flatMap((failure) => (failure === null ? [] : [failure])),
+        ...settled.flatMap((result) =>
+          result.status === 'rejected' ? [String(result.reason)] : [],
+        ),
+      ];
+
+      if (failures.length > 0) {
+        throw new WringerError('environment', {
+          message: `The recorder lost records: ${failures.join('; ')}`,
+        });
+      }
+    },
+  };
+}
+
+interface FollowSourceRequest extends RecorderRequest {
+  readonly name: string;
+  readonly source: StreamSource;
+  readonly signal: AbortSignal;
+}
+
+interface Follower {
+  readonly status: () => SourceStatus;
+
+  // Settles once the source ends, with why reading it failed, or null when it ended without a fault.
+  readonly done: Promise<string | null>;
+  readonly drain: () => Promise<void>;
+}
+
+interface ReportedPhase {
+  readonly state: SourceStatus['state'];
+  readonly detail: keyof SourceDetails | null;
+}
+
+const reportedPhases: Readonly<Record<SourcePhase, ReportedPhase>> = {
+  running: { state: 'running', detail: null },
+  'running-unwritten': { state: 'failed', detail: 'write' },
+  exited: { state: 'exited', detail: 'reading' },
+  'exited-unwritten': { state: 'failed', detail: 'write' },
+  failed: { state: 'failed', detail: 'reading' },
+  'failed-unwritten': { state: 'failed', detail: 'write' },
+};
+
+export function buildSourceStatus(
+  name: string,
+  phase: SourcePhase,
+  details: SourceDetails,
+): SourceStatus {
+  const reported = reportedPhases[phase];
+
+  return {
+    name,
+    state: reported.state,
+    detail: reported.detail === null ? null : details[reported.detail],
+  };
+}
+
+function followSource(request: FollowSourceRequest): Follower {
+  const path = join(request.directory, `${request.name}.ndjson`);
+  const phase = createActor(sourcePhaseMachine);
+
+  phase.start();
+
+  const writer = makeRecordWriter({
+    path,
+    now: request.now,
+    appendText: request.appendText,
+    pendingLimit: request.pendingLimit,
+    onError: (error) => {
+      phase.send({
+        type: 'write-failed',
+        detail: `The recorder could not write: ${String(error)}`,
+      });
+    },
+    onRecovered: () => {
+      phase.send({ type: 'write-recovered', detail: null });
+    },
+  });
+
+  const onLine = (line: string): void => {
+    writer.add(JSON.stringify({ at: request.now().toISOString(), line: capLine(line) }));
+  };
+
+  const watch = async (): Promise<string | null> => {
+    try {
+      const exitCode = await runFollow(request, onLine);
+
+      phase.send({ type: 'exit', detail: `exit code ${exitCode}` });
+
+      return null;
+    } catch (error) {
+      phase.send({ type: 'fail', detail: String(error) });
+
+      return `${request.name} could not be read: ${String(error)}`;
+    }
+  };
+
+  return {
+    status: () => {
+      const snapshot = phase.getSnapshot();
+
+      return buildSourceStatus(request.name, snapshot.context.phase, snapshot.context.details);
+    },
+    done: watch(),
+    drain: writer.drain,
+  };
+}
+
+interface RecordWriterOptions {
+  readonly path: string;
+  readonly now: () => Date;
+  readonly appendText: (path: string, text: string) => Promise<void>;
+  readonly pendingLimit: number;
+  readonly onError: (error: unknown) => void;
+  readonly onRecovered: () => void;
+}
+
+interface RecordWriter {
+  readonly add: (record: string) => void;
+  readonly drain: () => Promise<void>;
+}
+
+function makeRecordWriter(options: RecordWriterOptions): RecordWriter {
+  const writer = createActor(recordWriterMachine, {
+    input: {
+      ...options,
+      write: (text: string) => options.appendText(options.path, text),
+    },
+  });
+
+  writer.start();
+
+  return {
+    add: (record) => {
+      writer.send({ type: 'add', record });
+    },
+    drain: async () => {
+      const settle = Promise.withResolvers<null>();
+
+      writer.send({ type: 'drain', settle });
+
+      await settle.promise;
+    },
+  };
+}
+
+// A record holds at most this many characters of its line, so every record fits well inside the
+// smallest slice a reader takes.
+const recordLineCap = 4 * 1024;
+
+function capLine(line: string): string {
+  return line.length > recordLineCap ? `${line.slice(0, recordLineCap)}...` : line;
+}
+
+function runFollow(request: FollowSourceRequest, onLine: (line: string) => void): Promise<number> {
+  if ('command' in request.source) {
+    return followCommand(request, request.source.command, onLine);
+  }
+
+  return followFile(request, request.source.file, onLine);
+}
+
+// A follow command, such as `tail -F`, prints each line as it reads it, so the recorder reads on
+// until the command's output goes quiet before it kills the command.
+async function followCommand(
+  request: FollowSourceRequest,
+  argv: readonly string[],
+  onLine: (line: string) => void,
+): Promise<number> {
+  const follow = new AbortController();
+
+  let lastLineMs: number | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const checkQuiet = (stopMs: number): void => {
+    const delayMs = pickCommandStopDelay({ nowMs: performance.now(), stopMs, lastLineMs });
+
+    if (delayMs === 0) {
+      follow.abort();
+    } else {
+      timer = setTimeout(checkQuiet, delayMs, stopMs);
+    }
+  };
+
+  const onStop = (): void => {
+    checkQuiet(performance.now());
+  };
+
+  request.signal.addEventListener('abort', onStop, { once: true });
+
+  if (request.signal.aborted) {
+    follow.abort();
+  }
+
+  try {
+    return await request.host.follow({
+      argv,
+      access: request.access,
+      signal: follow.signal,
+      onLine: (line) => {
+        lastLineMs = performance.now();
+
+        onLine(line);
+      },
+    });
+  } finally {
+    clearTimeout(timer);
+
+    request.signal.removeEventListener('abort', onStop);
+  }
+}
+
+const filePollMs = 100;
+
+// A file source can hold a large log before the run starts, so each read takes at most this much,
+// and the recorder reads again until it reaches the end.
+const fileReadLimitBytes = 64 * 1024;
+
+// A file that a writer keeps growing never reads to its end, so one pass, the final one at a stop
+// included, takes at most this many reads.
+const fileReadsPerPass = 256;
+
+// The recorder reads a file source itself, so its stop can read the file to its end once the app
+// has stopped writing; a killed `tail` would drop what it had yet to read. A file source ends with
+// exit code 0 at the recorder's stop.
+async function followFile(
+  request: FollowSourceRequest,
+  path: string,
+  onLine: (line: string) => void,
+): Promise<number> {
+  let decoder = new TextDecoder();
+
+  let state: FileFollowState = { position: { offset: 0, identity: null }, carry: '' };
+
+  const readNew = async (): Promise<void> => {
+    let more = true;
+
+    for (let reads = 0; more && reads < fileReadsPerPass; reads += 1) {
+      const chunk = await request.readFileFrom(path, state.position, fileReadLimitBytes);
+
+      const step = buildFileStep(state, {
+        start: chunk.start,
+        identity: chunk.identity,
+        byteCount: chunk.bytes.length,
+      });
+
+      // A fresh decoder drops the old file's unfinished character along with its line.
+      if (step.restarted) {
+        decoder = new TextDecoder();
+      }
+
+      const text = decoder.decode(chunk.bytes, { stream: true });
+      const split = collectLines(step.state.carry, text, recordLineCap);
+
+      state = { position: step.state.position, carry: split.carry };
+      more = step.more;
+
+      for (const line of split.lines) {
+        onLine(line);
+      }
+    }
+  };
+
+  while (!request.signal.aborted) {
+    await readNew();
+
+    // Bun.sleep takes no signal, and this wait has to end at the stop.
+    await request.wait(filePollMs, request.signal);
+  }
+
+  await readNew();
+
+  if (state.carry !== '') {
+    onLine(state.carry);
+  }
+
+  return 0;
+}

package/src/stream.ts

@@ -0,0 +1,175 @@
+import { open } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import { join } from 'node:path';
+import { WringerError, createDirectory, defineDriver, findOwnValue } from '@wringer/core';
+import type { DriverSession, Fence, RunHandle } from '@wringer/core';
+import { z } from 'zod';
+import { appendWholeText } from './append-whole-text.ts';
+import { streamRecordSchema } from './build-stream-slice.ts';
+import type { StreamSlice } from './build-stream-slice.ts';
+import { readFileFrom } from './read-file-from.ts';
+import { readStreamSlice } from './read-stream-slice.ts';
+import type { StreamSliceRequest } from './read-stream-slice.ts';
+import {
+  sourceStatusSchema,
+  startStreamRecorder,
+  streamSourceSchema,
+} from './start-stream-recorder.ts';
+import type { StreamSource } from './start-stream-recorder.ts';
+import { waitOrAbort } from './wait-or-abort.ts';
+
+const streamNameSchema = z.string().regex(/^[a-z0-9][a-z0-9-]*$/u);
+
+// The recorder caps a record's line at 4096 characters, which JSON escaping can grow to about
+// 24 KiB, so a smaller slice could hold no whole record and never advance its cursor.
+const minimumSliceBytes = 32 * 1024;
+
+export const streamReadSchema = z.strictObject({
+  name: streamNameSchema,
+  from: z.number().int().nonnegative().optional(),
+  maxBytes: z.number().int().min(minimumSliceBytes).optional(),
+});
+
+export const streamSliceSchema = z.strictObject({
+  name: z.string(),
+  records: z.array(streamRecordSchema),
+  cursor: z.number().int().nonnegative(),
+  more: z.boolean(),
+});
+
+const optionsSchema = z.strictObject({
+  maxBytes: z
+    .number()
+    .int()
+    .min(64 * 1024)
+    .default(64 * 1024),
+});
+
+const targetConfigSchema = z.strictObject({
+  sources: z.record(streamNameSchema, streamSourceSchema).optional(),
+});
+
+const statusListSchema = z.array(sourceStatusSchema);
+
+// Records a target's logs for the whole run, in the run's supervisor, and reads them back from a
+// cursor. A read with no `from` starts at the cursor that `use` last marked, so an agent reads only
+// what its own steps logged.
+export const stream = defineDriver({
+  name: 'stream',
+  options: optionsSchema,
+  targetConfig: targetConfigSchema,
+  services: {
+    recorder: {
+      start: async (ctx) => {
+        const recorder = await startStreamRecorder({
+          sources: pickSources(ctx.config.sources, ctx.run),
+          directory: ctx.run.paths.streams,
+          host: ctx.host,
+          access: ctx.access,
+          now: () => new Date(),
+          createDirectory,
+          appendText: appendWholeText,
+          readFileFrom: (path, from, limitBytes) =>
+            readFileFrom(path, from, limitBytes, openForRead),
+          wait: waitOrAbort,
+          pendingLimit: 10_000,
+        });
+
+        return {
+          methods: { status: () => Promise.resolve(recorder.status()) },
+          stop: recorder.stop,
+        };
+      },
+    },
+  },
+  client: (session, fence) =>
+    createStreamClient(session, fence, (request) => readStreamSlice(request, openForRead)),
+  commands: (command) => [
+    command({
+      path: ['stream', 'read'],
+      summary: 'Read a stream from the cursor that `use` marked, or from --from',
+      args: streamReadSchema,
+      positionals: ['name'],
+      data: streamSliceSchema,
+      effect: 'read',
+      run: (args, ctx) => ctx.client.read(args),
+    }),
+  ],
+  checks: [
+    {
+      name: 'recording',
+      timeoutMs: 5000,
+      run: async (ctx) => {
+        const answer = await ctx.session.service('recorder').call('status', null);
+
+        const statuses = statusListSchema.parse(answer);
+        const stopped = statuses.filter((status) => status.state !== 'running');
+
+        if (stopped.length > 0) {
+          throw new WringerError('check-failed', {
+            message: `These streams stopped recording: ${stopped.map((status) => `${status.name} (${status.detail ?? status.state})`).join(', ')}.`,
+          });
+        }
+      },
+    },
+  ],
+});
+
+// With no sources, the driver records the app the run launched.
+function pickSources(
+  sources: Readonly<Record<string, StreamSource>> | undefined,
+  run: RunHandle,
+): Readonly<Record<string, StreamSource>> {
+  return sources ?? { app: { file: run.childLog('app').path } };
+}
+
+function openForRead(path: string): Promise<FileHandle> {
+  return open(path, 'r');
+}
+
+type StreamSession = DriverSession<
+  z.infer<typeof optionsSchema>,
+  z.infer<typeof targetConfigSchema>
+>;
+
+type ReadSlice = (request: StreamSliceRequest) => Promise<StreamSlice>;
+
+export type StreamRead = z.input<typeof streamReadSchema>;
+
+export type StreamSliceData = z.infer<typeof streamSliceSchema>;
+
+export interface StreamClient {
+  readonly read: (request: StreamRead) => Promise<StreamSliceData>;
+}
+
+function createStreamClient(
+  session: StreamSession,
+  fence: Fence,
+  readSlice: ReadSlice,
+): StreamClient {
+  return {
+    read: fence({
+      effect: () => 'read',
+      describe: (request: StreamRead) => `stream read ${request.name}`,
+      run: async (request) => {
+        const parsed = streamReadSchema.parse(request);
+        const sources = pickSources(session.config.sources, session.run);
+
+        if (!Object.hasOwn(sources, parsed.name)) {
+          throw new WringerError('usage', {
+            message: `Target ${session.target} records no stream named ${parsed.name}.`,
+            hint: `Read one of: ${Object.keys(sources).join(', ')}.`,
+          });
+        }
+
+        const slice = await readSlice({
+          path: join(session.run.paths.streams, `${parsed.name}.ndjson`),
+          from: parsed.from ?? findOwnValue(session.cursors, parsed.name) ?? 0,
+          maxBytes: Math.min(parsed.maxBytes ?? session.options.maxBytes, session.options.maxBytes),
+        });
+
+        return { name: parsed.name, ...slice, records: [...slice.records] };
+      },
+    }),
+  };
+}

package/src/types.ts

@@ -0,0 +1,4 @@
+import type { FileHandle } from 'node:fs/promises';
+
+// Opens a file for reading. The driver passes `open(path, 'r')` from `node:fs/promises`.
+export type OpenFile = (path: string) => Promise<FileHandle>;

package/src/wait-or-abort.ts

@@ -0,0 +1,7 @@
+import { setTimeout } from 'node:timers/promises';
+
+// Settles after the delay, or as soon as the signal aborts, and never rejects: a poll loop checks
+// the signal itself after each wait.
+export async function waitOrAbort(delayMs: number, signal: AbortSignal): Promise<void> {
+  await setTimeout(delayMs, undefined, { signal }).catch(() => null);
+}