@wringer/stream 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoff Whatley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@wringer/stream</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@wringer/stream"><img src="https://img.shields.io/npm/v/@wringer/stream" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+</div>
+
+The stream driver for wringer: it records a target's logs for the whole run, and reads them back
+from a cursor.
+
+## Install
+
+```bash
+bun add @wringer/core @wringer/stream
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Usage
+
+```ts
+import { createWringer, ssh } from '@wringer/core';
+import { stream } from '@wringer/stream';
+
+export const registry = createWringer({ name: 'shop' })
+  .use(stream({}))
+  .target('staging', {
+    mode: 'attach',
+    access: 'read-only',
+    host: ssh({ destination: 'deploy@staging.shop.example' }),
+    drivers: {
+      stream: () => ({
+        sources: { jobs: { command: ['journalctl', '-f', '-u', 'shop-jobs', '-o', 'cat'] } },
+      }),
+    },
+  })
+  .build();
+```
+
+An action calls `ctx.drivers.stream.read({ name, from })`. The CLI adds `stream read <name>`, and
+the doctor check `stream.recording`, which fails when a source has stopped or its records fail to
+write.
+
+## Sources
+
+- `{ command: [...] }` runs the command on the target's host and records each line it prints. At the
+  stop, the recorder reads on until the command prints nothing for 200 ms, for at most 2 s, then
+  kills it.
+- `{ file: '<path>' }` follows a file on the machine where the run lives. The supervisor stops the
+  app first, then reads the file to its end, so the lines the app logs while it shuts down are
+  recorded.
+- On an `attach` target, the run owns no app, so the recorder stops without waiting for one. A line
+  the app writes after the recorder's final read stays out of the stream.
+- A target with no `sources` records `app`: the log of the app that the run launched.
+
+The run's supervisor writes each source to `streams/<name>.ndjson` in the run folder, one
+`{ at, line }` record per line. A record keeps at most 4096 characters of its line. When a source
+logs faster than the disk takes it, the supervisor holds at most 10,000 pending records per source,
+plus the batch it is writing. It drops the rest, and then writes a record that counts the dropped
+lines. A batch that fails to write stays queued for the next write, and the source reads as failed
+until a write succeeds. When the run stops with records still unwritten, or with a source it could
+not read, the run ends as crashed, and its crash reason names the stream and the error. The `down`
+or `detach` that stopped the run then fails with an `environment` error that names them too.
+
+## Cursors
+
+A cursor is a byte offset into a stream's file. `use` marks the end of each stream, and every
+envelope holds the current ends in `cursors`.
+
+- A read with no `from` starts at the cursor that `use` last marked, so it returns only what was
+  logged since.
+- A read returns the records up to the `maxBytes` option, 64 KiB by default, with the next `cursor`
+  and `more` when the stream holds more. A read may pass a smaller `maxBytes`, down to 32 KiB.
+- A cursor past the end of the file belongs to an older run, so the read starts over at 0.

package/dist/append-whole-text.d.ts

@@ -0,0 +1 @@
+export declare function appendWholeText(path: string, text: string): Promise<void>;

package/dist/build-file-step.d.ts

@@ -0,0 +1,16 @@
+import type { FilePosition } from './read-file-from.ts';
+export interface FileFollowState {
+    readonly position: FilePosition;
+    readonly carry: string;
+}
+export interface ChunkInfo {
+    readonly start: number;
+    readonly identity: string | null;
+    readonly byteCount: number;
+}
+export interface FileStep {
+    readonly restarted: boolean;
+    readonly state: FileFollowState;
+    readonly more: boolean;
+}
+export declare function buildFileStep(state: FileFollowState, chunk: ChunkInfo): FileStep;

package/dist/build-stream-slice.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const streamRecordSchema: z.ZodObject<{
+    at: z.ZodString;
+    line: z.ZodString;
+}, z.core.$strict>;
+export type StreamRecord = z.infer<typeof streamRecordSchema>;
+export interface StreamSlice {
+    readonly records: readonly StreamRecord[];
+    readonly cursor: number;
+    readonly more: boolean;
+}
+export declare function buildStreamSlice(bytes: Buffer, from: number, size: number): StreamSlice;

package/dist/collect-lines.d.ts

@@ -0,0 +1,5 @@
+export interface LineSplit {
+    readonly lines: readonly string[];
+    readonly carry: string;
+}
+export declare function collectLines(carry: string, text: string, capLength: number): LineSplit;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { stream, streamReadSchema, streamSliceSchema } from './stream.ts';
+export type { StreamClient, StreamRead, StreamSliceData } from './stream.ts';
+export { streamRecordSchema } from './build-stream-slice.ts';
+export type { StreamRecord } from './build-stream-slice.ts';
+export type { StreamSource } from './start-stream-recorder.ts';

package/dist/pick-command-stop-delay.d.ts

@@ -0,0 +1,6 @@
+export interface CommandStopFacts {
+    readonly nowMs: number;
+    readonly stopMs: number;
+    readonly lastLineMs: number | null;
+}
+export declare function pickCommandStopDelay(facts: CommandStopFacts): number;

package/dist/pick-file-read.d.ts

@@ -0,0 +1,10 @@
+import type { FilePosition } from './read-file-from.ts';
+export interface FileFacts {
+    readonly size: number;
+    readonly identity: string;
+}
+export interface FileRead {
+    readonly start: number;
+    readonly length: number;
+}
+export declare function pickFileRead(file: FileFacts, from: FilePosition, limitBytes: number): FileRead;

package/dist/read-file-from.d.ts

@@ -0,0 +1,11 @@
+import type { OpenFile } from './types.ts';
+export interface FilePosition {
+    readonly offset: number;
+    readonly identity: string | null;
+}
+export interface FileChunk {
+    readonly start: number;
+    readonly identity: string | null;
+    readonly bytes: Uint8Array;
+}
+export declare function readFileFrom(path: string, from: FilePosition, limitBytes: number, openFile: OpenFile): Promise<FileChunk>;

package/dist/read-stream-slice.d.ts

@@ -0,0 +1,8 @@
+import type { StreamSlice } from './build-stream-slice.ts';
+import type { OpenFile } from './types.ts';
+export interface StreamSliceRequest {
+    readonly path: string;
+    readonly from: number;
+    readonly maxBytes: number;
+}
+export declare function readStreamSlice(request: StreamSliceRequest, openFile: OpenFile): Promise<StreamSlice>;

package/dist/record-writer-machine.d.ts

@@ -0,0 +1,65 @@
+interface WriterInput {
+    readonly path: string;
+    readonly pendingLimit: number;
+    readonly now: () => Date;
+    readonly write: (text: string) => Promise<void>;
+    readonly onError: (error: unknown) => void;
+    readonly onRecovered: () => void;
+}
+interface WriterContext extends WriterInput {
+    readonly pending: readonly string[];
+    readonly batch: readonly string[];
+    readonly batchDropped: number;
+    readonly dropped: number;
+    readonly failure: string | null;
+    readonly drains: readonly PromiseWithResolvers<null>[];
+}
+type WriterEvent = {
+    readonly type: 'add';
+    readonly record: string;
+} | {
+    readonly type: 'drain';
+    readonly settle: PromiseWithResolvers<null>;
+};
+interface BatchInput {
+    readonly write: WriterInput['write'];
+    readonly lines: readonly string[];
+}
+export declare const recordWriterMachine: import("xstate").StateMachine<WriterContext, WriterEvent, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<null, BatchInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "writeBatch";
+    logic: import("xstate").PromiseActorLogic<null, BatchInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "enqueue";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepBatch";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "keepDrain";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rejectDrains";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "reportRecovery";
+    params: unknown;
+} | {
+    type: "resolveDrains";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "takeBatch";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "hasPending";
+    params: unknown;
+}, never, "idle" | "stalled" | "writing", string, WriterInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    states: {
+        readonly idle: {};
+        readonly writing: {};
+        readonly stalled: {};
+    };
+}, import("xstate").MetaObject>;
+export {};

package/dist/source-phase-machine.d.ts

@@ -0,0 +1,21 @@
+export type SourcePhase = 'running' | 'running-unwritten' | 'exited' | 'exited-unwritten' | 'failed' | 'failed-unwritten';
+export type SourceEventType = 'exit' | 'fail' | 'write-failed' | 'write-recovered';
+export interface SourceEvent {
+    readonly type: SourceEventType;
+    readonly detail: string | null;
+}
+export interface SourceDetails {
+    readonly reading: string | null;
+    readonly write: string | null;
+}
+interface SourceContext {
+    readonly phase: SourcePhase;
+    readonly details: SourceDetails;
+}
+export declare const sourcePhaseMachine: import("xstate").StateMachine<SourceContext, SourceEvent, {}, never, {
+    type: "move";
+    params: import("xstate").NonReducibleUnknown;
+}, never, never, {}, string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {}, import("xstate").MetaObject>;
+export declare function canMoveSource(from: SourcePhase, to: SourcePhase): boolean;
+export declare function pickSourcePhase(phase: SourcePhase, event: SourceEventType): SourcePhase;
+export {};

package/dist/start-stream-recorder.d.ts

@@ -0,0 +1,39 @@
+import type { Access, Host } from '@wringer/core';
+import { z } from 'zod';
+import type { FileChunk, FilePosition } from './read-file-from.ts';
+import type { SourceDetails, SourcePhase } from './source-phase-machine.ts';
+export declare const streamSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    command: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    file: z.ZodString;
+}, z.core.$strict>]>;
+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>;
+    readonly wait: (delayMs: number, signal: AbortSignal) => Promise<void>;
+    readonly pendingLimit: number;
+}
+export declare const sourceStatusSchema: z.ZodObject<{
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        exited: "exited";
+        failed: "failed";
+        running: "running";
+    }>;
+    detail: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+type SourceStatus = z.infer<typeof sourceStatusSchema>;
+export interface StreamRecorder {
+    readonly status: () => readonly SourceStatus[];
+    readonly stop: () => Promise<void>;
+}
+export declare function startStreamRecorder(request: RecorderRequest): Promise<StreamRecorder>;
+export declare function buildSourceStatus(name: string, phase: SourcePhase, details: SourceDetails): SourceStatus;
+export {};

package/dist/stream.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const streamReadSchema: z.ZodObject<{
+    name: z.ZodString;
+    from: z.ZodOptional<z.ZodNumber>;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const streamSliceSchema: z.ZodObject<{
+    name: z.ZodString;
+    records: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        line: z.ZodString;
+    }, z.core.$strict>>;
+    cursor: z.ZodNumber;
+    more: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const stream: import("@wringer/core").DriverFactory<"stream", {
+    maxBytes?: number | undefined;
+}, {
+    sources?: Record<string, {
+        command: string[];
+    } | {
+        file: string;
+    }> | undefined;
+}, StreamClient>;
+export type StreamRead = z.input<typeof streamReadSchema>;
+export type StreamSliceData = z.infer<typeof streamSliceSchema>;
+export interface StreamClient {
+    readonly read: (request: StreamRead) => Promise<StreamSliceData>;
+}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+import type { FileHandle } from 'node:fs/promises';
+export type OpenFile = (path: string) => Promise<FileHandle>;

package/dist/wait-or-abort.d.ts

@@ -0,0 +1 @@
+export declare function waitOrAbort(delayMs: number, signal: AbortSignal): Promise<void>;

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@wringer/stream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "The stream driver for wringer: records a target's logs during a run and reads them from a cursor",
+  "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/stream#readme",
+  "bugs": "https://github.com/zgeoff/wringer/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/wringer.git",
+    "directory": "packages/stream"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist",
+    "!src/test-utils"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "xstate": "5.33.3",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@wringer/core": "0.1.0",
+    "@zgeoff/std": "0.4.2",
+    "@zgeoff/testing": "0.2.1",
+    "tiny-invariant": "1.3.3"
+  },
+  "peerDependencies": {
+    "@wringer/core": "0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  }
+}

package/src/append-whole-text.ts

@@ -0,0 +1,30 @@
+import { appendFile, stat, truncate } from 'node:fs/promises';
+import { isErrorCode } from '@wringer/core';
+
+// An append that fails part-way, such as on a full disk, leaves the bytes it wrote; they are cut,
+// so a retry of the same text never doubles a record or splices a torn one into the file.
+export async function appendWholeText(path: string, text: string): Promise<void> {
+  const size = await readFileSize(path);
+
+  try {
+    await appendFile(path, text);
+  } catch (error) {
+    await truncate(path, size);
+
+    throw error;
+  }
+}
+
+async function readFileSize(path: string): Promise<number> {
+  try {
+    const info = await stat(path);
+
+    return info.size;
+  } catch (error) {
+    if (isErrorCode(error, 'ENOENT')) {
+      return 0;
+    }
+
+    throw error;
+  }
+}

package/src/build-file-step.ts

@@ -0,0 +1,39 @@
+import type { FilePosition } from './read-file-from.ts';
+
+export interface FileFollowState {
+  readonly position: FilePosition;
+
+  // The text after the last newline, which waits for the rest of its line.
+  readonly carry: string;
+}
+
+export interface ChunkInfo {
+  readonly start: number;
+  readonly identity: string | null;
+  readonly byteCount: number;
+}
+
+export interface FileStep {
+  // The file shrank or was replaced, so its reader starts over with a fresh decoder.
+  readonly restarted: boolean;
+  readonly state: FileFollowState;
+
+  // A read stops at its limit, and a read of a file that changed under it can stop short of that,
+  // so only a read that returns no bytes reached the end.
+  readonly more: boolean;
+}
+
+// A file that starts over drops the old file's unfinished line, so it never joins the new file's
+// text.
+export function buildFileStep(state: FileFollowState, chunk: ChunkInfo): FileStep {
+  const restarted = chunk.start < state.position.offset;
+
+  return {
+    restarted,
+    state: {
+      position: { offset: chunk.start + chunk.byteCount, identity: chunk.identity },
+      carry: restarted ? '' : state.carry,
+    },
+    more: chunk.byteCount > 0,
+  };
+}

package/src/build-stream-slice.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+export const streamRecordSchema = z.strictObject({ at: z.string(), line: z.string() });
+
+export type StreamRecord = z.infer<typeof streamRecordSchema>;
+
+export interface StreamSlice {
+  readonly records: readonly StreamRecord[];
+  readonly cursor: number;
+  readonly more: boolean;
+}
+
+const newline = 0x0a;
+
+// The bytes read from `from` end in a part record when the read stopped mid-line; the slice keeps
+// the whole records, and its cursor points at the first byte it left.
+export function buildStreamSlice(bytes: Buffer, from: number, size: number): StreamSlice {
+  const end = bytes.lastIndexOf(newline) + 1;
+
+  const records = bytes
+    .subarray(0, end)
+    .toString('utf8')
+    .split('\n')
+    .filter((line) => line !== '')
+    .map((line) => parseRecord(line));
+
+  return { records, cursor: from + end, more: from + end < size };
+}
+
+function parseRecord(line: string): StreamRecord {
+  const parsed: unknown = JSON.parse(line);
+
+  return streamRecordSchema.parse(parsed);
+}

package/src/collect-lines.ts

@@ -0,0 +1,13 @@
+export interface LineSplit {
+  readonly lines: readonly string[];
+  readonly carry: string;
+}
+
+// The text after the last newline waits for the rest of its line. It keeps one character past
+// `capLength`, enough for the record to show the cut, so a file that never ends its line stays
+// small.
+export function collectLines(carry: string, text: string, capLength: number): LineSplit {
+  const parts = `${carry}${text}`.split('\n');
+
+  return { lines: parts.slice(0, -1), carry: (parts.at(-1) ?? '').slice(0, capLength + 1) };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { stream, streamReadSchema, streamSliceSchema } from './stream.ts';
+export type { StreamClient, StreamRead, StreamSliceData } from './stream.ts';
+export { streamRecordSchema } from './build-stream-slice.ts';
+export type { StreamRecord } from './build-stream-slice.ts';
+export type { StreamSource } from './start-stream-recorder.ts';

package/src/pick-command-stop-delay.ts

@@ -0,0 +1,23 @@
+export interface CommandStopFacts {
+  readonly nowMs: number;
+
+  // When the recorder began to stop.
+  readonly stopMs: number;
+
+  // When the command last printed a line, or null before its first.
+  readonly lastLineMs: number | null;
+}
+
+// The command's output has to go this long without a line before the recorder kills it.
+const commandQuietMs = 200;
+
+// The longest a stop waits for a command that never goes quiet.
+const commandStopLimitMs = 2000;
+
+// How long the recorder still reads a command source once it began to stop, or 0 to kill it now.
+export function pickCommandStopDelay(facts: CommandStopFacts): number {
+  const quietAtMs = Math.max(facts.stopMs, facts.lastLineMs ?? facts.stopMs) + commandQuietMs;
+  const killAtMs = Math.min(quietAtMs, facts.stopMs + commandStopLimitMs);
+
+  return Math.max(0, killAtMs - facts.nowMs);
+}

package/src/pick-file-read.ts

@@ -0,0 +1,22 @@
+import type { FilePosition } from './read-file-from.ts';
+
+export interface FileFacts {
+  readonly size: number;
+
+  // The device and inode of the file at the path now.
+  readonly identity: string;
+}
+
+export interface FileRead {
+  readonly start: number;
+  readonly length: number;
+}
+
+// A file that shrank, such as a log rotated in place, or a new file at the path, such as a log
+// rotated by rename, reads from 0.
+export function pickFileRead(file: FileFacts, from: FilePosition, limitBytes: number): FileRead {
+  const replaced = from.identity !== null && from.identity !== file.identity;
+  const start = replaced || file.size < from.offset ? 0 : from.offset;
+
+  return { start, length: Math.min(file.size - start, limitBytes) };
+}

package/src/read-file-from.ts

@@ -0,0 +1,54 @@
+import { isErrorCode } from '@wringer/core';
+import { pickFileRead } from './pick-file-read.ts';
+import type { OpenFile } from './types.ts';
+
+// Where a reader left a file: the byte offset, and the device and inode of the file it read, or
+// null before it read one.
+export interface FilePosition {
+  readonly offset: number;
+  readonly identity: string | null;
+}
+
+export interface FileChunk {
+  // Where `bytes` starts: the offset, or 0 once the file shrank below it or was replaced.
+  readonly start: number;
+  readonly identity: string | null;
+  readonly bytes: Uint8Array;
+}
+
+// Up to `limitBytes` of a file from `from`. A file that does not exist yet reads as empty, as
+// `tail -F` treats it.
+export async function readFileFrom(
+  path: string,
+  from: FilePosition,
+  limitBytes: number,
+  openFile: OpenFile,
+): Promise<FileChunk> {
+  const handle = await openFile(path).catch((error: unknown) => {
+    if (isErrorCode(error, 'ENOENT')) {
+      return null;
+    }
+
+    throw error;
+  });
+
+  if (handle === null) {
+    return { start: from.offset, identity: from.identity, bytes: new Uint8Array() };
+  }
+
+  try {
+    const stats = await handle.stat();
+
+    const identity = `${stats.dev}:${stats.ino}`;
+    const plan = pickFileRead({ size: stats.size, identity }, from, limitBytes);
+
+    const bytes = new Uint8Array(plan.length);
+
+    // A file truncated after the stat yields fewer bytes than the buffer holds.
+    const read = await handle.read(bytes, 0, bytes.length, plan.start);
+
+    return { start: plan.start, identity, bytes: bytes.subarray(0, read.bytesRead) };
+  } finally {
+    await handle.close();
+  }
+}