@lsdsoftware/utils 2.2.0 → 2.3.0

package/README.md

@@ -30,32 +30,33 @@ Observable wrapper for net.connect (see connect-socket.test.ts for usage)
 
 
 ### CLI Worker Rotator
-Rotate child processes that communicate over stdin/stdout.
+Rotate child processes that communicate over stdin/stdout using a line-oriented request/response protocol, such as JSONL.
 
 ```typescript
 import { spawn } from "node:child_process"
 import { makeCLIWorkerRotator } from "@lsdsoftware/utils"
 
 const subscription = makeCLIWorkerRotator({
-  spawnWorkerProcess: signal => spawn("my-cli-worker", {
-    signal,
+  spawnWorkerProcess: () => spawn("my-jsonl-worker", {
     stdio: ["pipe", "pipe", "inherit"]
   }),
-  workerTTL: 60_000,
+  workerTtlMs: 60_000,
+  request$,
+  maxPendingRequests: 100,
   onEvent: event => console.debug('[cli-worker-rotator]', event)
-}).subscribe(worker => {
-  if (worker) {
-    worker.stdin.write("hello\n")
-  }
-})
+}).subscribe()
 ```
 
+Each request writes exactly one stdin line. Each stdout line is paired with the next pending request in order. Child processes should write logs to stderr.
+
 Contract:
 
-- The returned observable is cold. Each subscription owns its own child process lifecycle.
-- The observable emits the child process when a worker starts, emits `null` when that worker closes, then repeats with a new worker.
-- `spawnWorkerProcess` receives an `AbortSignal`; pass it to `spawn` so unsubscribing can cancel an in-flight spawn.
-- `workerTTL` rotates a worker after the given number of milliseconds. It must be greater than zero when provided.
-- `retryConfig` controls retries after spawn failures. `repeatConfig` controls rotation after normal close or TTL expiry; the default waits 1000 ms before spawning the next worker.
-- `onEvent` receives `spawn`, `fail-spawn`, and `close` events for logging, tracing, or diagnostics.
-- Request framing, response matching, backpressure, and protocol-specific timeouts belong in the caller that uses the emitted stdin/stdout streams.
+- The returned observable is cold and does not emit values. Each subscription creates its own rotator engine and subscribes to `request$`; share the returned observable if you want one engine with multiple observers.
+- `onEvent` receives optional lifecycle events for logging, tracing, or diagnostics.
+- Requests emitted before the first child process is ready, or between child processes, are buffered and handed to the next child process.
+- `maxPendingRequests` caps the no-worker buffer and errors the rotator when exceeded. The default is `Infinity`.
+- Pending requests are considered handed off once they are written to a worker process. Delivery retries, acknowledgements, and exactly-once guarantees belong in the worker or an upstream queue.
+- Completing `request$` means no more input, but it does not define the rotator lifecycle. The engine runs until the returned observable is unsubscribed or errors.
+- Worker stdin is ended during teardown. Child processes should exit cleanly when stdin closes.
+
+If a worker exits before producing a matching stdout line for a written request, that request's `output$` is not resolved by this adapter. Apply timeout or cancellation around each request if the caller needs bounded waits.

package/dist/cli-worker-rotator.d.ts

@@ -1,26 +1,29 @@
-import type { ChildProcess, ChildProcessByStdio } from "child_process";
+import type { ChildProcessByStdio } from "child_process";
 import * as rxjs from "rxjs";
 import type { Readable, Writable } from "stream";
+export type CLIWorker = ChildProcessByStdio<Writable, Readable, null>;
 export type CLIWorkerRotatorEvent = {
-    type: 'spawn';
-    worker: ChildProcess;
+    type: 'hired' | 'relieved';
+    worker: CLIWorker;
 } | {
-    type: 'fail-spawn';
-    reason: unknown;
-} | {
-    type: 'close';
-    worker: ChildProcess;
+    type: 'quit';
+    worker: CLIWorker;
     reason: unknown;
 };
+export interface CLIRequest {
+    input: string;
+    output$: rxjs.SubjectLike<string>;
+}
 export interface CLIWorkerRotatorOptions {
-    spawnWorkerProcess: (signal: AbortSignal) => ChildProcessByStdio<Writable, Readable, null>;
-    workerTTL?: number;
-    retryConfig?: rxjs.RetryConfig;
-    repeatConfig?: rxjs.RepeatConfig;
+    spawnWorkerProcess: () => CLIWorker;
+    workerTtlMs: number;
+    request$: rxjs.Observable<CLIRequest>;
+    maxPendingRequests?: number;
     onEvent?: (event: CLIWorkerRotatorEvent) => void;
 }
 /**
- * Rotates child processes that communicate over stdin/stdout.
- * See the README for the lifecycle contract.
+ * Rotates child processes that communicate over stdin/stdout using a
+ * line-oriented request/response protocol, such as JSONL.
+ * See the README for the protocol and lifecycle contract.
  */
-export declare function makeCLIWorkerRotator({ spawnWorkerProcess, workerTTL, retryConfig, repeatConfig, onEvent }: CLIWorkerRotatorOptions): rxjs.Observable<ChildProcessByStdio<Writable, Readable, null> | null>;
+export declare function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests, onEvent }: CLIWorkerRotatorOptions): rxjs.Observable<never>;

package/dist/cli-worker-rotator.js

@@ -1,28 +1,82 @@
 import * as rxjs from "rxjs";
+import { makeLineReader } from "./line-reader.js";
 /**
- * Rotates child processes that communicate over stdin/stdout.
- * See the README for the lifecycle contract.
+ * Rotates child processes that communicate over stdin/stdout using a
+ * line-oriented request/response protocol, such as JSONL.
+ * See the README for the protocol and lifecycle contract.
  */
-export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTTL, retryConfig, repeatConfig = { delay: 1000 }, onEvent }) {
-    if (workerTTL != undefined && workerTTL <= 0) {
-        throw new Error('Invalid workerTTL');
-    }
+export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests = Infinity, onEvent }) {
     return rxjs.defer(() => {
-        const abortCtl = new AbortController();
-        return rxjs.defer(() => {
-            const child = spawnWorkerProcess(abortCtl.signal);
-            return rxjs.race(rxjs.fromEvent(child, 'spawn').pipe(rxjs.take(1), rxjs.map(() => child)), rxjs.fromEvent(child, 'error').pipe(rxjs.map(err => { throw err; })));
-        }).pipe(rxjs.tap({
-            next: worker => onEvent?.({ type: 'spawn', worker }),
-            error: err => onEvent?.({ type: 'fail-spawn', reason: err })
-        }), retryConfig ? rxjs.retry(retryConfig) : rxjs.identity, rxjs.exhaustMap(worker => {
-            return rxjs.NEVER.pipe(rxjs.startWith(worker), rxjs.takeUntil(rxjs.race(rxjs.fromEvent(worker, 'close', (code, signal) => `Process exit (${signal || code})`), rxjs.fromEvent(worker.stdin, 'error'), workerTTL
-                ? rxjs.timer(workerTTL).pipe(rxjs.map(() => 'TTL expire'))
-                : rxjs.NEVER).pipe(rxjs.tap(reason => onEvent?.({ type: 'close', worker, reason })))), rxjs.endWith(null), rxjs.finalize(() => {
-                worker.stdin.end();
-            }));
-        }), repeatConfig ? rxjs.repeat(repeatConfig) : rxjs.identity, rxjs.finalize(() => {
-            abortCtl.abort();
-        }));
+        if (maxPendingRequests !== Infinity && (!Number.isInteger(maxPendingRequests) || maxPendingRequests < 0)) {
+            throw new RangeError('maxPendingRequests must be a non-negative integer or Infinity');
+        }
+        return rxjs.defer(() => makeWorker(spawnWorkerProcess)).pipe(rxjs.tap(worker => onEvent?.({ type: 'hired', worker: worker.child })), rxjs.exhaustMap(worker => rxjs.NEVER.pipe(rxjs.startWith(worker), rxjs.takeUntil(rxjs.race(worker.quit$, rxjs.timer(workerTtlMs).pipe(rxjs.map(() => 'Worker TTL expired'))).pipe(rxjs.tap(reason => onEvent?.({ type: 'quit', worker: worker.child, reason })))), rxjs.endWith(null), rxjs.finalize(() => {
+            worker.relieve();
+            onEvent?.({ type: 'relieved', worker: worker.child });
+        }))), rxjs.repeat(), rxjs.share(), worker$ => request$.pipe(rxjs.window(worker$), rxjs.zipWith(worker$.pipe(rxjs.startWith(null))), rxjs.mergeScan((pending, [window$, worker]) => rxjs.concat(pending, window$).pipe(worker
+            ? request$ => worker.process(request$).pipe(rxjs.startWith([]))
+            : request$ => request$.pipe(bufferRequests(maxPendingRequests))), []), rxjs.ignoreElements()));
     });
 }
+async function makeWorker(spawn) {
+    const child = spawn();
+    await new Promise((f, r) => child.once('spawn', f).once('error', r));
+    return {
+        child,
+        process(request$) {
+            return request$.pipe(rxjs.mergeMap(request => writeLn(child.stdin, request.input).pipe(rxjs.map(() => request), rxjs.catchError(err => {
+                request.output$.error(err);
+                return rxjs.EMPTY;
+            }))), rxjs.zipWith(readLines(child.stdout)), rxjs.tap(([request, line]) => request.output$.next(line)), rxjs.ignoreElements());
+        },
+        relieve() {
+            child.stdin.end();
+        },
+        quit$: rxjs.race(rxjs.fromEvent(child, 'close', (code, signal) => `Worker exit ${signal || code}`), rxjs.fromEvent(child.stdin, 'error', err => new Error('Worker stdin error', { cause: err })))
+    };
+}
+function readLines(stream) {
+    return new rxjs.Observable(subscriber => {
+        const lineReader = makeLineReader(line => subscriber.next(line));
+        const onError = (err) => subscriber.error(err);
+        const onFinish = () => subscriber.complete();
+        lineReader.once('error', onError);
+        lineReader.once('finish', onFinish);
+        stream.once('error', onError);
+        stream.pipe(lineReader);
+        return () => {
+            lineReader.off('error', onError);
+            lineReader.off('finish', onFinish);
+            stream.off('error', onError);
+            stream.unpipe(lineReader);
+            lineReader.destroy();
+        };
+    });
+}
+function writeLn(stream, line) {
+    return new rxjs.Observable(subscriber => {
+        try {
+            stream.write(line + "\n", err => {
+                if (err) {
+                    subscriber.error(err);
+                }
+                else {
+                    subscriber.next();
+                    subscriber.complete();
+                }
+            });
+        }
+        catch (err) {
+            subscriber.error(err);
+        }
+    });
+}
+function bufferRequests(maxPendingRequests) {
+    return request$ => request$.pipe(rxjs.reduce((pending, request) => {
+        if (pending.length >= maxPendingRequests) {
+            throw new Error(`Worker rotator exceeded max pending requests (${maxPendingRequests})`);
+        }
+        pending.push(request);
+        return pending;
+    }, []));
+}

package/dist/cli-worker-rotator.test.js

@@ -2,52 +2,166 @@ import { describe } from "@service-broker/test-utils";
 import assert from "assert";
 import { EventEmitter } from "events";
 import * as rxjs from "rxjs";
-import { PassThrough } from "stream";
+import { PassThrough, Writable } from "stream";
 import { makeCLIWorkerRotator } from "./cli-worker-rotator.js";
 describe('cli-worker-rotator', ({ test }) => {
-    test('emits each spawned worker and null when it closes', async () => {
-        const children = [makeChild(), makeChild()];
-        const spawned = [...children];
-        const emissions = await rxjs.firstValueFrom(makeCLIWorkerRotator({
+    test('pairs stdout lines with requests in order', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild({ autoSpawn: true });
+        const firstOutput$ = new rxjs.Subject;
+        const secondOutput$ = new rxjs.Subject;
+        const subscription = makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$
+        }).subscribe();
+        try {
+            request$.next({ input: 'one', output$: firstOutput$ });
+            request$.next({ input: 'two', output$: secondOutput$ });
+            const outputs = await Promise.all([
+                rxjs.firstValueFrom(firstOutput$),
+                rxjs.firstValueFrom(secondOutput$)
+            ]);
+            assert.deepStrictEqual(outputs, ['ONE', 'TWO']);
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
+    test('buffers requests before the first worker is ready', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild();
+        const firstOutput$ = new rxjs.Subject;
+        const secondOutput$ = new rxjs.Subject;
+        const subscription = makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$
+        }).subscribe();
+        try {
+            request$.next({ input: 'one', output$: firstOutput$ });
+            request$.next({ input: 'two', output$: secondOutput$ });
+            child.spawn();
+            const outputs = await Promise.all([
+                rxjs.firstValueFrom(firstOutput$),
+                rxjs.firstValueFrom(secondOutput$)
+            ]);
+            assert.deepStrictEqual(outputs, ['ONE', 'TWO']);
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
+    test('buffers requests between workers', async () => {
+        const request$ = new rxjs.Subject;
+        const firstChild = makeEchoChild({ autoSpawn: true });
+        const secondChild = makeEchoChild();
+        const children = [firstChild, secondChild];
+        const firstOutput$ = new rxjs.Subject;
+        const secondOutput$ = new rxjs.Subject;
+        const subscription = makeCLIWorkerRotator({
             spawnWorkerProcess: () => children.shift(),
-            onEvent: event => {
-                if (event.type === 'spawn') {
-                    setTimeout(() => event.worker.emit('close', 0, null), 0);
-                }
-            },
-            repeatConfig: { count: 2, delay: 0 }
-        }).pipe(rxjs.take(4), rxjs.toArray()));
-        assert.strictEqual(emissions.length, 4);
-        assert.strictEqual(emissions[0], spawned[0]);
-        assert.strictEqual(emissions[1], null);
-        assert.strictEqual(emissions[2], spawned[1]);
-        assert.strictEqual(emissions[3], null);
-    });
-    test('aborts an in-flight spawn when unsubscribed before the worker starts', async () => {
-        let aborted = false;
+            workerTtlMs: 1000,
+            request$
+        }).subscribe();
+        try {
+            request$.next({ input: 'one', output$: firstOutput$ });
+            assert.equal(await rxjs.firstValueFrom(firstOutput$), 'ONE');
+            firstChild.emit('close', 0, null);
+            request$.next({ input: 'two', output$: secondOutput$ });
+            secondChild.spawn();
+            assert.equal(await rxjs.firstValueFrom(secondOutput$), 'TWO');
+            assert(firstChild.stdinEnded);
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
+    test('errors when pending request cap is exceeded', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild();
+        const error = defer();
+        makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$,
+            maxPendingRequests: 1
+        }).subscribe({
+            error: err => error.resolve(err)
+        });
+        request$.next({ input: 'one', output$: new rxjs.Subject });
+        request$.next({ input: 'two', output$: new rxjs.Subject });
+        const err = await error.promise;
+        assert(err instanceof Error);
+        assert.equal(err.message, 'Worker rotator exceeded max pending requests (1)');
+    });
+    test('reports lifecycle events', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild({ autoSpawn: true });
+        const events = [];
         const subscription = makeCLIWorkerRotator({
-            spawnWorkerProcess: signal => {
-                signal.addEventListener('abort', () => {
-                    aborted = true;
-                });
-                return makeChild({ autoSpawn: false });
-            }
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$,
+            onEvent: event => events.push(event)
         }).subscribe();
-        subscription.unsubscribe();
-        assert.strictEqual(aborted, true);
+        try {
+            await waitFor(() => events.length >= 1);
+            child.emit('close', 0, null);
+            await waitFor(() => events.length >= 3);
+            assert.deepStrictEqual(events.slice(0, 3).map(event => event.type), ['hired', 'quit', 'relieved']);
+            assert.equal(events[1].type == 'quit' && events[1].reason, 'Worker exit 0');
+        }
+        finally {
+            subscription.unsubscribe();
+        }
     });
 });
-function makeChild({ autoSpawn = true } = {}) {
+function makeEchoChild({ autoSpawn = false } = {}) {
     const child = new EventEmitter();
-    const stdin = new PassThrough();
-    child.stdin = stdin;
-    child.stdout = new PassThrough();
+    const stdout = new PassThrough();
+    let remainder = '';
+    let stdinEnded = false;
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) {
+            remainder += chunk.toString();
+            const lines = remainder.split(/\r?\n/);
+            remainder = lines.pop();
+            for (const line of lines) {
+                stdout.write(line.toUpperCase() + '\n');
+            }
+            callback();
+        },
+        final(callback) {
+            stdinEnded = true;
+            callback();
+        }
+    });
+    child.stdout = stdout;
     child.stderr = null;
-    stdin.on('close', () => {
-        child.emit('close', 0, null);
+    child.spawn = () => child.emit('spawn');
+    Object.defineProperty(child, 'stdinEnded', {
+        get: () => stdinEnded
     });
     if (autoSpawn) {
-        setTimeout(() => child.emit('spawn'), 0);
+        setTimeout(() => child.spawn(), 0);
     }
     return child;
 }
+function defer() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+async function waitFor(condition) {
+    for (let i = 0; i < 100; i++) {
+        if (condition())
+            return;
+        await new Promise(resolve => setTimeout(resolve, 1));
+    }
+    assert(condition());
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lsdsoftware/utils",
   "type": "module",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Useful JavaScript utilities",
   "main": "dist/index.js",
   "files": [