@roku-sdk/device-test-client 0.0.0-stage → 2.19.0

package/src/logs/log-session.ts

@@ -0,0 +1,436 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Host-side coordinator between `RkClient`'s log-assertion API and
+ * the `rk server` daemon.
+ *
+ * - Lazy `POST /logs/start` on first use; 400 "already active" is
+ *   treated as attaching to the existing session.
+ * - Owns the SSE `LogStreamClient`, wiring `log` frames into the
+ *   buffer and `status` frames into gap tracking.
+ * - `dispose()` closes the SSE client only; never `/logs/stop`
+ *   (global teardown owns server-side lifecycle).
+ *
+ * `streamFactory` and `fetchImpl` are DI seams for tests.
+ */
+
+import { LogSessionStartError } from "../errors";
+import { LogBuffer } from "./log-buffer";
+import type { LogStreamCallbacks, LogStreamClientOptions } from "./log-stream-client";
+import { LogStreamClient } from "./log-stream-client";
+
+export interface LogSessionOptions {
+    /** Base URL of the `rk server` daemon. */
+    serverUrl: string;
+    /** Device selector (ip / id / name). Optional; server falls back to active device. */
+    device?: string;
+    /** Roku log port. Optional; server defaults to `ROKU_LOG_PORT`. */
+    port?: number;
+    /** Requested server-side buffer size; propagated verbatim to `/logs/start`. */
+    bufferSize?: number;
+    /**
+     * Optional pre-built buffer. Tests inject one to pre-seed
+     * entries before `ensureStarted()`. Production callers let the
+     * session construct its own.
+     */
+    buffer?: LogBuffer;
+    /**
+     * Stream factory — defaults to `new LogStreamClient(...)`. Tests
+     * supply a fake so the session can be driven without HTTP.
+     */
+    streamFactory?: (opts: LogStreamClientOptions, cbs: LogStreamCallbacks) => LogStreamClientLike;
+    /**
+     * fetch override. Defaults to `globalThis.fetch`. Tests inject a
+     * mock to simulate the `/logs/start` response shape without opening
+     * real sockets.
+     */
+    fetchImpl?: typeof fetch;
+}
+
+/** Structural shape of the stream client the session drives. */
+export interface LogStreamClientLike {
+    open(): void;
+    close(): void;
+}
+
+export class LogSession {
+    public readonly buffer: LogBuffer;
+    private readonly opts: LogSessionOptions;
+    private readonly streamFactory: NonNullable<LogSessionOptions["streamFactory"]>;
+    private readonly fetchImpl: typeof fetch;
+    private stream: LogStreamClientLike | null = null;
+    private startPromise: Promise<void> | null = null;
+    // Only close a gap on `active` preceded by `reconnecting`; the
+    // very first `active` on initial attach must not close a
+    // non-existent gap.
+    private lastStatus: string | null = null;
+    // Highest server-assigned seq observed. Dedups the replay batch
+    // the server emits on every attach (initial + re-attach). Init
+    // -1 so the first frame (seq 0) is accepted. Lines without
+    // serverSeq bypass the check.
+    private lastServerSeq = -1;
+    // Warn at most once per session for post-ready SSE errors so
+    // a server burst doesn't flood CI logs.
+    private postReadyErrorWarned = false;
+    // In-flight `resync()`, shared by concurrent callers.
+    private resyncPromise: Promise<void> | null = null;
+    // Bumped per `dispose()`, so a re-attach in flight can tell that
+    // the caller gave up on the subscription while it was opening.
+    private disposeCount = 0;
+    // Set by `dispose()`, cleared by an explicit `ensureStarted()`. While
+    // set there is no subscription to re-attach, so `resync()` is a no-op.
+    private disposed = false;
+
+    constructor(opts: LogSessionOptions) {
+        this.opts = opts;
+        this.buffer = opts.buffer ?? new LogBuffer();
+        this.streamFactory = opts.streamFactory ?? ((streamOpts, cbs) => new LogStreamClient(streamOpts, cbs));
+        // Friendly diagnostic instead of "fetch is not a function".
+        const defaultFetch = (globalThis as { fetch?: typeof fetch }).fetch;
+        if (!opts.fetchImpl && !defaultFetch) {
+            throw new Error("LogSession requires a fetch implementation. Upgrade to Node 18+ or pass opts.fetchImpl.");
+        }
+        this.fetchImpl = opts.fetchImpl ?? defaultFetch!;
+    }
+
+    /**
+     * Idempotent. Failures clear the cached promise so a stale
+     * daemon that comes back online isn't permanently rejected.
+     */
+    ensureStarted(): Promise<void> {
+        this.disposed = false;
+        if (this.startPromise) return this.startPromise;
+        this.startPromise = this.doStart().catch(err => {
+            this.startPromise = null;
+            throw err;
+        });
+        return this.startPromise;
+    }
+
+    private async doStart(): Promise<void> {
+        await this.postStart();
+        await this.openStream();
+    }
+
+    private async postStart(): Promise<void> {
+        const url = joinUrl(this.opts.serverUrl, "/logs/start");
+        const body: Record<string, unknown> = {};
+        if (this.opts.device !== undefined) body.device = this.opts.device;
+        if (this.opts.port !== undefined) body.port = this.opts.port;
+        if (this.opts.bufferSize !== undefined) body.bufferSize = this.opts.bufferSize;
+        const payload = JSON.stringify(body);
+
+        // 429 retry budget: most parallel-shard 429 storms drain inside
+        // a handful of seconds (the `express-rate-limit` window is
+        // 15 minutes by default but the server should be started with
+        // `--no-rate-limit` for sharded runs — see
+        // `scripts/run-shards-on-devices.sh::rk-server section`). The
+        // retry here is defence-in-depth for the case where a user
+        // points `device-test-client` at a hand-started server they
+        // didn't realise had rate limits on. Cap attempts so a
+        // mis-configured server fails loudly instead of hanging.
+        const MAX_429_ATTEMPTS = 3;
+        let attempt = 0;
+        let res: Response;
+        while (true) {
+            try {
+                res = await this.fetchImpl(url, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: payload
+                });
+            } catch (err) {
+                throw new LogSessionStartError(
+                    `POST ${url} failed: ${(err as Error).message}. Is \`rk server\` running?`,
+                    {
+                        serverUrl: this.opts.serverUrl,
+                        detail: (err as Error).message
+                    }
+                );
+            }
+
+            if (res.status !== 429 || attempt >= MAX_429_ATTEMPTS - 1) break;
+
+            // Honour `Retry-After` when the server provides it
+            // (`express-rate-limit` sets it via `standardHeaders: true`).
+            // Fall back to exponential backoff capped at 8s so a hung
+            // window can't strand the test for the full 15-min default.
+            const retryAfterMs = parseRetryAfterMs(res.headers.get("retry-after"));
+            const backoffMs = retryAfterMs ?? Math.min(8_000, 500 * 2 ** attempt);
+            attempt += 1;
+            await delay(backoffMs);
+        }
+
+        if (res.ok) return;
+
+        // 400 "already active" → another worker already started a
+        // session for the same (device, port). Attach via SSE.
+        if (res.status === 400) {
+            const detail = await safeReadText(res);
+            if (/already active/i.test(detail)) return;
+            throw new LogSessionStartError(`POST ${url} returned 400: ${detail || "<no body>"}`, {
+                serverUrl: this.opts.serverUrl,
+                statusCode: 400,
+                detail
+            });
+        }
+
+        const detail = await safeReadText(res);
+        // Augment the 429 message with operator guidance — the bare
+        // `RATE_LIMIT_EXCEEDED` body is unhelpful on the failing test
+        // line. The same hint lives in `scripts/run-shards-on-devices.sh`.
+        const hint =
+            res.status === 429
+                ? ` Restart with \`rk server stop && rk server start --no-rate-limit --daemon\` ` +
+                  `or set \`RK_DISABLE_RATE_LIMIT=1\` before \`rk server start\` for parallel test runs.`
+                : "";
+        throw new LogSessionStartError(`POST ${url} returned HTTP ${res.status}${detail ? `: ${detail}` : ""}${hint}`, {
+            serverUrl: this.opts.serverUrl,
+            statusCode: res.status,
+            detail
+        });
+    }
+
+    /**
+     * Open SSE and await readiness. First `onStatus`/`onLine` →
+     * resolve; pre-ready `onError` → reject (so `ensureStarted()`
+     * surfaces the failure rather than handing back a dead stream);
+     * `onClose` triggers re-attach via `handleRemoteClose`.
+     */
+    private async openStream(): Promise<void> {
+        if (this.stream) return;
+        let resolveReady!: () => void;
+        let rejectReady!: (err: Error) => void;
+        const ready = new Promise<void>((resolve, reject) => {
+            resolveReady = resolve;
+            rejectReady = reject;
+        });
+        let readyResolved = false;
+        const markReady = (): void => {
+            if (readyResolved) return;
+            readyResolved = true;
+            resolveReady();
+        };
+
+        const stream = this.streamFactory(
+            {
+                serverUrl: this.opts.serverUrl,
+                device: this.opts.device,
+                port: this.opts.port
+            },
+            {
+                onLine: (line, serverSeq) => {
+                    // Replay-on-attach counts as live — resolve
+                    // readiness before appending.
+                    markReady();
+                    // Drop replay duplicates so gap-tracking and
+                    // `entriesSince` accounting stay correct.
+                    if (serverSeq !== undefined) {
+                        if (serverSeq <= this.lastServerSeq) return;
+                        this.lastServerSeq = serverSeq;
+                    }
+                    this.buffer.append(line);
+                },
+                onStatus: status => {
+                    markReady();
+                    if (status === "reconnecting") {
+                        this.buffer.markGapStart();
+                    } else if (status === "active") {
+                        // Initial-attach `active` is spurious; only
+                        // close a gap when we were reconnecting.
+                        if (this.lastStatus === "reconnecting") {
+                            this.buffer.markGapEnd();
+                        }
+                    } else if (status === "stopped") {
+                        // Server-side stop. In-flight `waitForLog` /
+                        // `expectNoLog` callers complete against the
+                        // captured buffer or surface a timeout.
+                        this.stream?.close();
+                        this.stream = null;
+                    }
+                    this.lastStatus = status;
+                },
+                onError: msg => {
+                    if (!readyResolved) {
+                        readyResolved = true;
+                        rejectReady(
+                            new LogSessionStartError(`LogSession: SSE attach failed before ready: ${msg}`, {
+                                serverUrl: this.opts.serverUrl,
+                                detail: msg
+                            })
+                        );
+                        return;
+                    }
+                    // Post-ready errors are informational; warn once
+                    // per session to keep CI logs readable.
+                    if (!this.postReadyErrorWarned) {
+                        this.postReadyErrorWarned = true;
+
+                        console.warn(`[device-test-client] LogSession SSE error (post-ready): ${msg}`);
+                    }
+                },
+                onClose: () => this.handleRemoteClose()
+            }
+        );
+        this.stream = stream;
+        stream.open();
+
+        try {
+            await ready;
+        } catch (err) {
+            // Tear the half-opened stream down for a clean retry.
+            try {
+                stream.close();
+            } catch {
+                // best-effort
+            }
+            this.stream = null;
+            throw err;
+        }
+    }
+
+    /**
+     * Handle server-initiated stream termination. Clears memoized
+     * session state so the next `ensureLogSession()` re-runs
+     * `/logs/start` + reopens SSE. Conservatively closes any open
+     * gap at the high-water seq (we can't distinguish "no lines
+     * lost" from "lines lost we never heard about").
+     */
+    private handleRemoteClose(): void {
+        this.buffer.markGapEnd();
+        this.stream = null;
+        this.startPromise = null;
+        this.lastStatus = null;
+        this.postReadyErrorWarned = false;
+    }
+
+    /**
+     * Drop the current subscription and open a fresh one.
+     *
+     * `/logs/tail` replays the whole server-side buffer on attach and
+     * `lastServerSeq` drops the duplicates, so a line the previous
+     * subscription never delivered still reaches the buffer — and
+     * through it any in-flight waiter, since `append` notifies
+     * subscribers. A subscription that stops delivering while the
+     * server still considers it active reports nothing and closes
+     * nothing, so re-attaching is the only way to find out whether
+     * the lines exist.
+     *
+     * Records no gap: a replay fills the window rather than losing
+     * it, and an open gap would mark the replayed lines themselves
+     * suspect, which is the opposite of the intent. Loss on the
+     * device→server leg is the server's own `reconnecting` status,
+     * which already marks a gap through `onStatus`.
+     *
+     * Concurrent callers share one re-attach. After `dispose()` it opens
+     * nothing: a waiter whose deadline fires once its test was torn down
+     * must not reopen the subscription the teardown closed.
+     */
+    resync(): Promise<void> {
+        if (this.resyncPromise) return this.resyncPromise;
+        if (this.disposed) return Promise.resolve();
+        const attempt = (async () => {
+            const generation = this.disposeCount;
+            this.teardownStream();
+            await this.ensureStarted();
+            // A `dispose()` that landed while we were attaching wins:
+            // the caller asked for no subscription, not a newer one.
+            // Without this a worker teardown can be followed by a
+            // fresh SSE socket opening behind it.
+            if (this.disposeCount !== generation) this.teardownStream();
+        })();
+        this.resyncPromise = attempt.finally(() => {
+            this.resyncPromise = null;
+        });
+        return this.resyncPromise;
+    }
+
+    /**
+     * Close the SSE subscription. Does NOT `/logs/stop` — global
+     * teardown owns server-side lifecycle so cross-worker sessions
+     * aren't torn down mid-suite.
+     */
+    dispose(): void {
+        this.disposed = true;
+        this.disposeCount += 1;
+        this.teardownStream();
+    }
+
+    /**
+     * Close the stream and clear the memoized session state so the
+     * next `ensureStarted()` re-runs `/logs/start` and reopens SSE.
+     * The buffer is deliberately untouched: its entries and gap
+     * records outlive any one subscription.
+     */
+    private teardownStream(): void {
+        if (this.stream) {
+            try {
+                this.stream.close();
+            } catch {
+                // best-effort; close errors are not actionable here
+            }
+            this.stream = null;
+        }
+        this.startPromise = null;
+        this.lastStatus = null;
+        this.postReadyErrorWarned = false;
+    }
+}
+
+/** URL join that doesn't mangle paths when base has no trailing slash. */
+function joinUrl(base: string, path: string): string {
+    const trimmed = base.endsWith("/") ? base.slice(0, -1) : base;
+    return trimmed + path;
+}
+
+async function safeReadText(res: Response): Promise<string> {
+    try {
+        return await res.text();
+    } catch {
+        return "";
+    }
+}
+
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. The header
+ * RFC permits two forms:
+ *   - delta-seconds (a non-negative integer)
+ *   - HTTP-date (RFC 7231 §7.1.1.1)
+ * Returns `undefined` for anything malformed so the caller can fall
+ * back to its own backoff schedule rather than waiting forever on a
+ * NaN value. Clamps absurd values (>5 minutes) so a misconfigured
+ * server can't strand the test process.
+ */
+function parseRetryAfterMs(headerValue: string | null): number | undefined {
+    if (!headerValue) return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed === "") return undefined;
+    const asNumber = Number(trimmed);
+    if (Number.isFinite(asNumber) && asNumber >= 0) {
+        return clampRetryAfter(asNumber * 1000);
+    }
+    const asDate = Date.parse(trimmed);
+    if (Number.isFinite(asDate)) {
+        const delta = asDate - Date.now();
+        return delta > 0 ? clampRetryAfter(delta) : 0;
+    }
+    return undefined;
+}
+
+const RETRY_AFTER_CAP_MS = 5 * 60 * 1000;
+
+function clampRetryAfter(ms: number): number {
+    if (ms <= 0) return 0;
+    if (ms > RETRY_AFTER_CAP_MS) return RETRY_AFTER_CAP_MS;
+    return Math.floor(ms);
+}
+
+function delay(ms: number): Promise<void> {
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        // `.unref()` is a Node-only Timer method; other hosts or test
+        // doubles may omit it. Optional-chain so the
+        // package stays universal.
+        (timer as { unref?: () => void }).unref?.();
+    });
+}