homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/logclient/settings.js

@@ -0,0 +1,64 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/settings.ts: Scalar constants for the Homebridge UI log client.
+ */
+/* Scalar constants only. This module is the single home for the log client's plain numbers and strings; it deliberately holds no parser data tables (the ANSI regex and
+ * the SGR-code-to-level map live in `parser.ts`, beside the code that owns them) and no derived policy. The reconnect-backoff curve the socket uses is deliberately the
+ * log client's OWN exponential shape - a 500 ms base climbing to a 5-second ceiling - rather than `defaultRetryBackoff`'s 1-second base and 30-second ceiling: a plugin
+ * developer restarts Homebridge frequently while iterating, so the tool should resume the tail snappily rather than lag up to half a minute behind. Both the base and
+ * the cap therefore live here, beside the jitter fraction, and the socket layers them into its own backoff policy (see `socket.ts`).
+ */
+// Default host to connect to when the caller supplies none. The web UI typically runs on the same machine as Homebridge, so loopback is the sensible default.
+export const DEFAULT_HOST = "localhost";
+// Default homebridge-config-ui-x listen port. The web UI ships with 8581 as its out-of-the-box port; callers override via configuration when a custom port is in use.
+export const DEFAULT_PORT = 8581;
+// The Socket.IO namespace the live-log stream is served on. The server registers a `log` namespace; clients join it with a `40/log,` connect frame and address it on
+// every subsequent message frame.
+export const LOG_NAMESPACE = "log";
+// The Engine.IO/Socket.IO HTTP path the WebSocket handshake is mounted at. This is the default mount point for homebridge-config-ui-x and is combined with the
+// `?EIO=4&transport=websocket&token=<rawjwt>` query string to form the connect URL.
+export const SOCKET_PATH = "/socket.io/";
+// The pseudo-terminal column width advertised to the server in the `tail-log` request. The server sizes its `tail`/`journalctl` output to this width; 80 columns is the
+// conventional terminal width and avoids the server wrapping lines at an unexpectedly narrow boundary.
+export const PTY_COLUMNS = 80;
+// The pseudo-terminal row count advertised to the server in the `tail-log` request. The server seeds roughly the last 500 lines regardless of this value, so the row
+// count is advisory; a conventional 24-row terminal height is advertised for realism.
+export const PTY_ROWS = 24;
+// The base reconnect delay, in milliseconds, that anchors the log client's jittered exponential backoff curve. Kept small so a healthy session that drops momentarily
+// reconnects briskly - a developer who just restarted Homebridge wants the tail back almost immediately, not after a one-second-and-climbing wait. The socket doubles
+// this on each successive failed connect attempt (500, 1000, 2000, ...) until the curve reaches the ceiling at `RECONNECT_CAP_MS`.
+export const RECONNECT_BASE_MS = 500;
+// The maximum reconnect delay, in milliseconds, that caps the log client's exponential backoff curve. This 5-second ceiling is deliberately far lower than
+// `defaultRetryBackoff`'s 30-second ceiling: a log-tailing dev tool wants to keep retrying briskly through a Homebridge restart rather than back off to a half-minute
+// lag, so the curve plateaus here. Paired with `RECONNECT_BASE_MS`, the socket's backoff climbs 500, 1000, 2000, 4000, then holds at 5000 for every later attempt.
+export const RECONNECT_CAP_MS = 5000;
+// The fraction of a computed backoff delay used as the maximum random jitter added on top of it. Jitter spreads reconnect attempts so a fleet of clients does not
+// stampede the server in lockstep after a shared outage; 0.5 means up to a 50% upward perturbation of each delay.
+export const JITTER_FRACTION = 0.5;
+// The additional headroom, in milliseconds, added on top of the server's advertised ping interval plus its ping timeout when sizing the liveness watchdog window. The
+// server pings on a fixed cadence; the watchdog must allow for one ping interval plus the server's ping timeout plus scheduling slack before concluding the connection
+// has gone silent, so this margin is added to that window to avoid a premature fire on a momentarily late ping.
+export const MARGIN_MS = 5000;
+// The idle gap, in milliseconds, after which a seed-served one-shot window is considered quiescent. When a `--since` (one-shot) window is served from the socket seed the
+// source is the never-ending live socket, so the channel needs an explicit terminator: a re-armable quiescence watchdog re-armed on every source line. Once this much
+// time elapses with no further source line (and the settle floor below has passed), the seed burst is judged complete and the one-shot ends. Kept small so a quiet log's
+// one-shot exits promptly after its seed has drained.
+export const SEED_QUIESCENCE_MS = 250;
+// The settle floor, in milliseconds, before a seed-served one-shot window may terminate, measured from the snapshot horizon captured at channel entry. The ~500-line seed
+// arrives as a fast burst, but a momentary intra-burst stall shorter than this floor must not be mistaken for the end of the burst and truncate the window. Holding the
+// quiescence terminator off until the floor has passed guarantees the whole seed burst is given time to arrive before the one-shot can end, so a quiet log terminates at
+// roughly this floor rather than at the much later hard cap.
+export const SEED_SETTLE_MS = 1000;
+// The hard cap, in milliseconds, on a seed-served one-shot window, measured from the snapshot horizon. A perpetually-chatty log keeps producing source lines, which keeps
+// re-arming the quiescence terminator indefinitely, so this cap guarantees the one-shot terminates regardless. Because the seed burst is fast (the recent tail, not the
+// multi-second whole-file download), the cap is comfortably longer than any legitimate seed burst and so never truncates one - it bounds only the busy-log case where
+// post-horizon live lines (filtered out of the window) would otherwise keep the channel open forever.
+export const SEED_WINDOW_MAX_MS = 5000;
+// The maximum number of leading, non-entry lines the seed gate will drop before it gives up and admits the stream unconditionally. The server seeds a live tail from a
+// BYTE offset in the log file, so the first line of content is a truncated fragment preceded by the server's `Loading logs...` / `File: ...` preamble; the gate drops
+// those until the first genuine `[timestamp]` entry (see `SeedGate` in `parser.ts`). This bound is the safety valve for the pathological case of a stream whose
+// timestamps are not the recognized en-US rendering (a non-default server locale): with no line ever recognized as an entry start, the gate would otherwise suppress the
+// stream forever, so after this many drops it concludes the format is unrecognized and opens. It is sized well above any plausible leading-noise run yet well below the
+// ~500-line seed, so it never fires for a normal log and bounds the worst-case loss to a fraction of the seed when it does.
+export const SEED_GATE_MAX_SKIP = 100;
+//# sourceMappingURL=settings.js.map

package/dist/logclient/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/logclient/settings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,8JAA8J;AAC9J,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,sKAAsK;AACtK,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC,qKAAqK;AACrK,kCAAkC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC;AAEnC,+JAA+J;AAC/J,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC,wKAAwK;AACxK,uGAAuG;AACvG,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAE9B,qKAAqK;AACrK,sFAAsF;AACtF,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAE3B,sKAAsK;AACtK,sKAAsK;AACtK,mIAAmI;AACnI,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,2JAA2J;AAC3J,sKAAsK;AACtK,mKAAmK;AACnK,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,kKAAkK;AAClK,kHAAkH;AAClH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAEnC,sKAAsK;AACtK,uKAAuK;AACvK,gHAAgH;AAChH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAE9B,0KAA0K;AAC1K,sKAAsK;AACtK,yKAAyK;AACzK,sDAAsD;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,0KAA0K;AAC1K,wKAAwK;AACxK,yKAAyK;AACzK,6DAA6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,0KAA0K;AAC1K,wKAAwK;AACxK,sKAAsK;AACtK,sGAAsG;AACtG,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,uKAAuK;AACvK,sKAAsK;AACtK,gKAAgK;AAChK,yKAAyK;AACzK,wKAAwK;AACxK,4HAA4H;AAC5H,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}

package/dist/logclient/socket-double.d.ts

@@ -0,0 +1,201 @@
+import type { LogSocketFactory, LogSocketInit, LogSocketLike, WebSocketFactory, WebSocketLike } from "./socket.ts";
+/**
+ * A controllable {@link WebSocketLike} test double. It captures every frame the socket under test sends and every close code it issues, and it exposes explicit emit
+ * methods so a test can drive the connection through its handshake, ping/pong, streaming, and teardown by hand - no real network, fully deterministic.
+ *
+ * Fidelity to the seam contract: `readyState` starts OPEN and flips to CLOSED on the first `close()` (or an inbound {@link TestWebSocket.emitClose}), so the socket's
+ * teardown gate (send the namespace DISCONNECT only while OPEN) behaves exactly as it would against a real connection; `send` records the frame regardless of state so a
+ * test can assert the exact wire sequence including any post-close send attempt.
+ *
+ * @category Testing
+ */
+export declare class TestWebSocket implements WebSocketLike {
+    #private;
+    readonly sent: string[];
+    readonly closeCodes: number[];
+    readonly url: string;
+    /**
+     * Construct a controllable WebSocket double.
+     *
+     * @param url - The connect URL the factory was asked to build. Defaults to an empty string for tests that do not assert on the URL.
+     */
+    constructor(url?: string);
+    /**
+     * Register a listener. Mirrors the DOM `addEventListener` overloads the {@link WebSocketLike} seam declares; the matching `emit*` method dispatches to every
+     * registered listener of that type.
+     *
+     * @param type     - The event type to listen for.
+     * @param listener - The listener to register.
+     */
+    addEventListener(type: "close", listener: (event: {
+        readonly code: number;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+    addEventListener(type: "message", listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    addEventListener(type: "open", listener: () => void): void;
+    /**
+     * Close the socket. Records the close code and flips `readyState` to CLOSED. Idempotent in the sense the seam needs: a second close simply records a second code.
+     *
+     * @param code - The close code. Defaults to 1000 (normal closure), matching the platform default.
+     */
+    close(code?: number): void;
+    /**
+     * The current readyState: {@link WEBSOCKET_OPEN} until the first close, `WEBSOCKET_CLOSED` after.
+     */
+    get readyState(): number;
+    /**
+     * Record an outbound frame. The frame is captured regardless of `readyState` so a test can assert the full wire sequence, including any send attempted after close.
+     *
+     * @param data - The frame text.
+     */
+    send(data: string): void;
+    /**
+     * Dispatch a `close` event to every registered close listener and flip `readyState` to CLOSED, simulating the peer closing the connection.
+     *
+     * @param code - The close code to deliver. Defaults to 1000.
+     */
+    emitClose(code?: number): void;
+    /**
+     * Dispatch an `error` event to every registered error listener, simulating a transport-level error.
+     *
+     * @param event - The error event payload. Defaults to an object carrying an `error` field, the shape the socket's error describer reads.
+     */
+    emitError(event?: unknown): void;
+    /**
+     * Dispatch a `message` event carrying `data` to every registered message listener, simulating an inbound frame.
+     *
+     * @param data - The frame text (or any value, to exercise the socket's non-string guard).
+     */
+    emitMessage(data: unknown): void;
+    /**
+     * Dispatch an `open` event to every registered open listener, simulating the transport-layer connection opening.
+     */
+    emitOpen(): void;
+}
+/**
+ * A {@link WebSocketFactory} double that records every `create` call (the connect URL) and returns a {@link TestWebSocket}. By default it returns a fresh socket per
+ * call, which is exactly what the reconnect path needs - each connect attempt gets a distinct controllable socket - and the recorded sockets are retained in order so a
+ * test can drive the second attempt's socket after failing the first.
+ *
+ * @category Testing
+ */
+export declare class TestWebSocketFactory {
+    #private;
+    readonly sockets: TestWebSocket[];
+    readonly urls: string[];
+    /**
+     * Construct a WebSocket-factory double.
+     *
+     * @param socket - Optional fixed {@link TestWebSocket} to return from every `create`. When omitted, each `create` returns a fresh socket built with the call's URL.
+     */
+    constructor(socket?: TestWebSocket);
+    /**
+     * The {@link WebSocketFactory} function this double exposes. Bound as an arrow property so it can be passed directly as the `webSocketFactory` seam without losing
+     * `this`.
+     *
+     * @param url - The connect URL.
+     *
+     * @returns The recorded {@link TestWebSocket}.
+     */
+    readonly create: WebSocketFactory;
+    /**
+     * Resolve when the socket at `index` (0-based, in creation order) has been constructed, returning it - immediately when it already exists. Lets a reconnect test
+     * await the next connect attempt's socket deterministically instead of racing the reconnect loop's backoff against a fixed wall-clock delay.
+     *
+     * @param index - The 0-based creation-order index to await.
+     * @returns A promise resolving to the {@link TestWebSocket} at that index.
+     */
+    socketCreated(index: number): Promise<TestWebSocket>;
+}
+/**
+ * Construction-time configuration for a {@link TestLogSocket}. Every field defaults, so a bare `new TestLogSocket()` is usable.
+ *
+ * @property droppedLines - The value the `droppedLines` getter reports. Defaults to `0`.
+ * @property lines        - The raw log lines `stdout()` yields, in order, before it parks awaiting abort. Defaults to an empty array.
+ *
+ * @category Testing
+ */
+export interface TestLogSocketInit {
+    droppedLines?: number;
+    lines?: readonly string[];
+}
+/**
+ * A {@link LogSocketLike} test double. It yields caller-supplied lines from `stdout()` and then parks until aborted, mirroring how the real socket keeps a live stream
+ * open after the seed; `abort()` aborts a genuine {@link AbortSignal} with a real {@link HbpuAbortError} reason so a consumer's abort-reason derivations stay meaningful.
+ * A consumer can drive a client end to end against this double without a WebSocket.
+ *
+ * @category Testing
+ */
+export declare class TestLogSocket implements LogSocketLike {
+    #private;
+    readonly abortCalls: unknown[];
+    /**
+     * Construct a log-socket double.
+     *
+     * @param init - Optional configuration. See {@link TestLogSocketInit}. Every field defaults, so a bare `new TestLogSocket()` is valid.
+     */
+    constructor(init?: TestLogSocketInit);
+    /**
+     * Abort the socket. Aborts the internal signal with the supplied reason, defaulting to a real `HbpuAbortError("shutdown")`, and records the (defaulted) reason. Safe to
+     * call more than once: the underlying signal aborts only once.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}.
+     */
+    abort(reason?: unknown): void;
+    /**
+     * `AsyncDisposable` implementation. Aborts the socket (defaulting to `"shutdown"`).
+     *
+     * @returns A resolved promise once the abort has been issued.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * `true` once the socket's signal has aborted.
+     */
+    get aborted(): boolean;
+    /**
+     * The configured dropped-line count.
+     */
+    get droppedLines(): number;
+    /**
+     * The composed abort signal representing this socket's lifetime. Aborts exactly once, when `abort()` is called.
+     */
+    get signal(): AbortSignal;
+    /**
+     * Yield the configured lines in order, then park until the socket aborts (mirroring a live stream that stays open after its seed). Terminates (returns) when the
+     * signal aborts, so a consumer iterating this generator unwinds cleanly on `abort()` or disposal.
+     *
+     * @returns An async generator yielding the configured raw log lines, then parking until abort.
+     */
+    stdout(): AsyncGenerator<string>;
+}
+/**
+ * A {@link LogSocketFactory} double that records every `create` call (the init it was passed) and returns a {@link TestLogSocket}, mirroring the create-call-recording
+ * discipline `TestRecordingProcessFactory` uses. By default it returns a fresh, default-configured socket per call; supply a socket to the constructor to return a single
+ * pre-configured instance from every `create`.
+ *
+ * @category Testing
+ */
+export declare class TestLogSocketFactory implements LogSocketFactory {
+    #private;
+    readonly createCalls: {
+        init: LogSocketInit;
+        socket: TestLogSocket;
+    }[];
+    /**
+     * Construct a log-socket-factory double.
+     *
+     * @param socket - Optional pre-configured {@link TestLogSocket} to return from every `create`. When omitted, each `create` returns a fresh, default-configured socket.
+     */
+    constructor(socket?: TestLogSocket);
+    /**
+     * Record the create call and return a {@link TestLogSocket} - the constructor-supplied instance when one was given, otherwise a fresh default-configured one.
+     *
+     * @param init - The {@link LogSocketInit} the consumer passed.
+     *
+     * @returns The log-socket double.
+     */
+    create(init: LogSocketInit): LogSocketLike;
+}
+//# sourceMappingURL=socket-double.d.ts.map

package/dist/logclient/socket-double.js

@@ -0,0 +1,384 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/socket-double.ts: Reusable test doubles for the WebSocket and LogSocket dependency-inversion seams.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+ * Reusable test doubles for the log client's two socket seams.
+ *
+ * Two seams drive the live-log transport: the low-level {@link WebSocketFactory} ({@link logclient/socket!LogSocket | LogSocket} builds a {@link WebSocketLike} from
+ * it) and the high-level {@link LogSocketFactory} (a client builds a {@link LogSocketLike} from it). This module ships the fakes that cash both in, mirroring the
+ * shape of `recording-process-double.ts`:
+ *
+ * - {@link TestWebSocket} - a controllable {@link WebSocketLike} that captures every frame sent and every close code, and exposes `emitOpen` / `emitMessage` /
+ *   `emitError` / `emitClose` so a test drives the socket state machine frame by frame without a real network. {@link TestWebSocketFactory} records every `create` call
+ *   (the connect URL) and returns the socket.
+ * - {@link TestLogSocket} - a {@link LogSocketLike} that yields caller-supplied lines from `stdout()` and aborts a genuine {@link AbortSignal} on `abort()`.
+ *   {@link TestLogSocketFactory} records every `create` call (the init it was passed) and returns the socket, so a client can be exercised without a WebSocket at all.
+ *
+ * @module
+ */
+import { HbpuAbortError, onAbort } from "../util.js";
+import { WEBSOCKET_OPEN } from "./socket.js";
+// The DOM `WebSocket.CLOSED` readyState value. Named locally so the double can report a post-close readyState without depending on the platform constant, matching the
+// way `socket.ts` names {@link WEBSOCKET_OPEN}.
+const WEBSOCKET_CLOSED = 3;
+/**
+ * A controllable {@link WebSocketLike} test double. It captures every frame the socket under test sends and every close code it issues, and it exposes explicit emit
+ * methods so a test can drive the connection through its handshake, ping/pong, streaming, and teardown by hand - no real network, fully deterministic.
+ *
+ * Fidelity to the seam contract: `readyState` starts OPEN and flips to CLOSED on the first `close()` (or an inbound {@link TestWebSocket.emitClose}), so the socket's
+ * teardown gate (send the namespace DISCONNECT only while OPEN) behaves exactly as it would against a real connection; `send` records the frame regardless of state so a
+ * test can assert the exact wire sequence including any post-close send attempt.
+ *
+ * @category Testing
+ */
+export class TestWebSocket {
+    // Every frame passed to `send`, in order, so a test can assert the exact wire sequence the socket produced (the namespace connect, the `tail-log` event, each pong, the
+    // namespace DISCONNECT).
+    sent = [];
+    // Every close code passed to `close`, in order. A test asserts `close(1000)` is always issued on teardown.
+    closeCodes = [];
+    // The connect URL this socket was constructed with, retained for assertions on the query string (EIO version, transport, token).
+    url;
+    // The registered listeners, keyed by event type. Each emit method dispatches to every listener registered for its type, mirroring the DOM `addEventListener` fan-out.
+    #closeListeners = [];
+    #errorListeners = [];
+    #messageListeners = [];
+    #openListeners = [];
+    // The current readyState. Starts OPEN (the double models a connection that is already established by the time a test drives it) and flips to CLOSED on the first close.
+    #readyState = WEBSOCKET_OPEN;
+    /**
+     * Construct a controllable WebSocket double.
+     *
+     * @param url - The connect URL the factory was asked to build. Defaults to an empty string for tests that do not assert on the URL.
+     */
+    constructor(url = "") {
+        this.url = url;
+    }
+    addEventListener(type, listener) {
+        switch (type) {
+            case "close": {
+                this.#closeListeners.push(listener);
+                return;
+            }
+            case "error": {
+                this.#errorListeners.push(listener);
+                return;
+            }
+            case "message": {
+                this.#messageListeners.push(listener);
+                return;
+            }
+            case "open": {
+                this.#openListeners.push(listener);
+                return;
+            }
+            default: {
+                return;
+            }
+        }
+    }
+    /**
+     * Close the socket. Records the close code and flips `readyState` to CLOSED. Idempotent in the sense the seam needs: a second close simply records a second code.
+     *
+     * @param code - The close code. Defaults to 1000 (normal closure), matching the platform default.
+     */
+    close(code = 1000) {
+        this.closeCodes.push(code);
+        this.#readyState = WEBSOCKET_CLOSED;
+    }
+    /**
+     * The current readyState: {@link WEBSOCKET_OPEN} until the first close, `WEBSOCKET_CLOSED` after.
+     */
+    get readyState() {
+        return this.#readyState;
+    }
+    /**
+     * Record an outbound frame. The frame is captured regardless of `readyState` so a test can assert the full wire sequence, including any send attempted after close.
+     *
+     * @param data - The frame text.
+     */
+    send(data) {
+        this.sent.push(data);
+    }
+    /**
+     * Dispatch a `close` event to every registered close listener and flip `readyState` to CLOSED, simulating the peer closing the connection.
+     *
+     * @param code - The close code to deliver. Defaults to 1000.
+     */
+    emitClose(code = 1000) {
+        this.#readyState = WEBSOCKET_CLOSED;
+        for (const listener of [...this.#closeListeners]) {
+            listener({ code });
+        }
+    }
+    /**
+     * Dispatch an `error` event to every registered error listener, simulating a transport-level error.
+     *
+     * @param event - The error event payload. Defaults to an object carrying an `error` field, the shape the socket's error describer reads.
+     */
+    emitError(event = { error: new Error("Test WebSocket error.") }) {
+        for (const listener of [...this.#errorListeners]) {
+            listener(event);
+        }
+    }
+    /**
+     * Dispatch a `message` event carrying `data` to every registered message listener, simulating an inbound frame.
+     *
+     * @param data - The frame text (or any value, to exercise the socket's non-string guard).
+     */
+    emitMessage(data) {
+        for (const listener of [...this.#messageListeners]) {
+            listener({ data });
+        }
+    }
+    /**
+     * Dispatch an `open` event to every registered open listener, simulating the transport-layer connection opening.
+     */
+    emitOpen() {
+        for (const listener of [...this.#openListeners]) {
+            listener();
+        }
+    }
+}
+/**
+ * A {@link WebSocketFactory} double that records every `create` call (the connect URL) and returns a {@link TestWebSocket}. By default it returns a fresh socket per
+ * call, which is exactly what the reconnect path needs - each connect attempt gets a distinct controllable socket - and the recorded sockets are retained in order so a
+ * test can drive the second attempt's socket after failing the first.
+ *
+ * @category Testing
+ */
+export class TestWebSocketFactory {
+    // Every socket handed out, in creation order, so a test can drive a specific connect attempt's socket (e.g., fail attempt 0's socket, then drive attempt 1's).
+    sockets = [];
+    // The URLs every `create` was called with, in order, for assertions on the connect URL across reconnects.
+    urls = [];
+    // An optional fixed socket to return from every `create`; when omitted, each `create` mints a fresh one.
+    #socket;
+    // Pending `socketCreated(index)` waiters, keyed by the 0-based creation-order index they await. Resolved synchronously inside `create` the moment that index is
+    // minted, so a reconnect test can await the ACTUAL construction of the next attempt's socket rather than racing a fixed wall-clock delay against the loop's backoff.
+    #createWaiters = new Map();
+    /**
+     * Construct a WebSocket-factory double.
+     *
+     * @param socket - Optional fixed {@link TestWebSocket} to return from every `create`. When omitted, each `create` returns a fresh socket built with the call's URL.
+     */
+    constructor(socket) {
+        this.#socket = socket;
+    }
+    /**
+     * The {@link WebSocketFactory} function this double exposes. Bound as an arrow property so it can be passed directly as the `webSocketFactory` seam without losing
+     * `this`.
+     *
+     * @param url - The connect URL.
+     *
+     * @returns The recorded {@link TestWebSocket}.
+     */
+    create = (url) => {
+        const socket = this.#socket ?? new TestWebSocket(url);
+        this.urls.push(url);
+        this.sockets.push(socket);
+        // Settle any waiter parked on the index just filled (the new length minus one), so a pending `socketCreated()` resolves the moment its socket is constructed.
+        const waiter = this.#createWaiters.get(this.sockets.length - 1);
+        if (waiter) {
+            this.#createWaiters.delete(this.sockets.length - 1);
+            waiter.resolve(socket);
+        }
+        return socket;
+    };
+    /**
+     * Resolve when the socket at `index` (0-based, in creation order) has been constructed, returning it - immediately when it already exists. Lets a reconnect test
+     * await the next connect attempt's socket deterministically instead of racing the reconnect loop's backoff against a fixed wall-clock delay.
+     *
+     * @param index - The 0-based creation-order index to await.
+     * @returns A promise resolving to the {@link TestWebSocket} at that index.
+     */
+    socketCreated(index) {
+        const existing = this.sockets[index];
+        if (existing) {
+            return Promise.resolve(existing);
+        }
+        const waiter = this.#createWaiters.get(index) ?? Promise.withResolvers();
+        this.#createWaiters.set(index, waiter);
+        return waiter.promise;
+    }
+}
+/**
+ * A {@link LogSocketLike} test double. It yields caller-supplied lines from `stdout()` and then parks until aborted, mirroring how the real socket keeps a live stream
+ * open after the seed; `abort()` aborts a genuine {@link AbortSignal} with a real {@link HbpuAbortError} reason so a consumer's abort-reason derivations stay meaningful.
+ * A consumer can drive a client end to end against this double without a WebSocket.
+ *
+ * @category Testing
+ */
+export class TestLogSocket {
+    // The reasons every `abort(reason?)` call was invoked with, in order, for assertions. A no-argument call records the defaulted `HbpuAbortError("shutdown")`.
+    abortCalls = [];
+    // The internal controller whose signal is exposed as the socket lifetime. Owned privately so the only abort verb is `abort()`, which records the call.
+    #controller = new AbortController();
+    #droppedLines;
+    #lines;
+    /**
+     * Construct a log-socket double.
+     *
+     * @param init - Optional configuration. See {@link TestLogSocketInit}. Every field defaults, so a bare `new TestLogSocket()` is valid.
+     */
+    constructor(init = {}) {
+        this.#droppedLines = init.droppedLines ?? 0;
+        this.#lines = init.lines ?? [];
+    }
+    /**
+     * Abort the socket. Aborts the internal signal with the supplied reason, defaulting to a real `HbpuAbortError("shutdown")`, and records the (defaulted) reason. Safe to
+     * call more than once: the underlying signal aborts only once.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}.
+     */
+    abort(reason) {
+        const resolvedReason = reason ?? new HbpuAbortError("shutdown");
+        this.abortCalls.push(resolvedReason);
+        this.#controller.abort(resolvedReason);
+    }
+    /**
+     * `AsyncDisposable` implementation. Aborts the socket (defaulting to `"shutdown"`).
+     *
+     * @returns A resolved promise once the abort has been issued.
+     */
+    async [Symbol.asyncDispose]() {
+        this.abort();
+    }
+    /**
+     * `true` once the socket's signal has aborted.
+     */
+    get aborted() {
+        return this.#controller.signal.aborted;
+    }
+    /**
+     * The configured dropped-line count.
+     */
+    get droppedLines() {
+        return this.#droppedLines;
+    }
+    /**
+     * The composed abort signal representing this socket's lifetime. Aborts exactly once, when `abort()` is called.
+     */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /**
+     * Yield the configured lines in order, then park until the socket aborts (mirroring a live stream that stays open after its seed). Terminates (returns) when the
+     * signal aborts, so a consumer iterating this generator unwinds cleanly on `abort()` or disposal.
+     *
+     * @returns An async generator yielding the configured raw log lines, then parking until abort.
+     */
+    async *stdout() {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            for (const line of this.#lines) {
+                if (this.#controller.signal.aborted) {
+                    return;
+                }
+                yield line;
+            }
+            // Park until aborted. A single resolver settled by `onAbort` lets the generator suspend without a busy loop; the explicit aborted guard below returns immediately
+            // for an already-aborted socket, while `onAbort` settles the parked waiter when an abort arrives after parking has begun.
+            if (this.#controller.signal.aborted) {
+                return;
+            }
+            const { promise, resolve } = Promise.withResolvers();
+            const _registration = __addDisposableResource(env_1, onAbort(this.#controller.signal, () => resolve()), false);
+            await promise;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+}
+/**
+ * A {@link LogSocketFactory} double that records every `create` call (the init it was passed) and returns a {@link TestLogSocket}, mirroring the create-call-recording
+ * discipline `TestRecordingProcessFactory` uses. By default it returns a fresh, default-configured socket per call; supply a socket to the constructor to return a single
+ * pre-configured instance from every `create`.
+ *
+ * @category Testing
+ */
+export class TestLogSocketFactory {
+    // Every create call's init and the socket returned, in order, so a test can assert the seam was exercised with the expected init and can drive the returned socket.
+    createCalls = [];
+    // The pre-configured socket to return from every create, when supplied; otherwise each create returns a fresh default-configured socket.
+    #socket;
+    /**
+     * Construct a log-socket-factory double.
+     *
+     * @param socket - Optional pre-configured {@link TestLogSocket} to return from every `create`. When omitted, each `create` returns a fresh, default-configured socket.
+     */
+    constructor(socket) {
+        this.#socket = socket;
+    }
+    /**
+     * Record the create call and return a {@link TestLogSocket} - the constructor-supplied instance when one was given, otherwise a fresh default-configured one.
+     *
+     * @param init - The {@link LogSocketInit} the consumer passed.
+     *
+     * @returns The log-socket double.
+     */
+    create(init) {
+        const socket = this.#socket ?? new TestLogSocket();
+        this.createCalls.push({ init, socket });
+        return socket;
+    }
+}
+//# sourceMappingURL=socket-double.js.map

package/dist/logclient/socket-double.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-double.js","sourceRoot":"","sources":["../../src/logclient/socket-double.ts"],"names":[],"mappings":"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"}