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

package/src/logs/log-buffer.ts

@@ -0,0 +1,265 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Append-only in-memory log buffer with seq-numbered entries, gap
+ * tracking, and bounded memory. Pure (no I/O) so unit tests can
+ * drive it directly.
+ *
+ * Memory cap: when `max` is hit we drop the oldest `dropHalf` entries
+ * and advance `minAvailableSeq`. Client-side eviction is NOT recorded
+ * as a gap (no device-side loss occurred). `linesSince(pos)` with
+ * `pos < minAvailableSeq` throws `LogBufferOverflowError` so tests
+ * fail loudly instead of silently dropping lines.
+ */
+
+import { LOG_BUFFER_DROP_HALF, LOG_BUFFER_MAX_LINES } from "../constants";
+import { LogBufferOverflowError } from "../errors";
+import type { LogLine, LogPosition } from "../types";
+
+export interface LogEntry {
+    /** Monotonically-increasing sequence number, starting at 0. */
+    seq: number;
+    /** Raw log line (no trailing newline guaranteed). */
+    line: LogLine;
+    /** Host-side wall-clock at the time of append (ms since epoch). */
+    ts: number;
+}
+
+/** Half-open range `[start, end)` of lost lines. */
+export interface Gap {
+    start: number;
+    end: number;
+}
+
+export interface LogBufferOptions {
+    /** Hard cap on retained entries. Defaults to `LOG_BUFFER_MAX_LINES`. */
+    max?: number;
+    /** Count of oldest entries to drop when cap is hit. Defaults to `LOG_BUFFER_DROP_HALF`. */
+    dropHalf?: number;
+}
+
+/**
+ * Lifetime stream-health stats. Counters are monotonic; consumers
+ * wanting deltas snapshot before/after the window of interest.
+ */
+export interface LogBufferStats {
+    /** Number of closed gaps recorded since construction. */
+    gapCount: number;
+    /** Sum of `(end - start)` across every closed gap. */
+    totalGapSeqSpan: number;
+    /** Wall-clock ms (`Date.now()`) of the most recent `markGapEnd()`, or `null` if none. */
+    lastGapAt: number | null;
+    /** Whether a gap is currently open (`reconnecting` not yet resolved by `active`). */
+    openGap: boolean;
+}
+
+/**
+ * Parse an opaque position token back to its seq number.
+ * Package-internal: deep import allowed but NOT under SemVer.
+ * Exists so in-package callers share a single strict validator.
+ */
+export function parsePos(pos: LogPosition): number {
+    const n = Number.parseInt(pos, 10);
+    if (!Number.isFinite(n) || n < 0 || String(n) !== pos) {
+        throw new Error(
+            `Invalid LogPosition "${pos}": expected a non-negative decimal string produced by logPosition().`
+        );
+    }
+    return n;
+}
+
+export class LogBuffer {
+    private readonly entries: LogEntry[] = [];
+    private nextSeq = 0;
+    // Smallest seq still retained; grows on eviction so
+    // `linesSince(pos < minAvailableSeq)` can fail fast.
+    private minAvailableSeq = 0;
+    private readonly gaps: Gap[] = [];
+    private openGapStart: number | null = null;
+    private readonly listeners = new Set<(e: LogEntry) => void>();
+
+    private readonly max: number;
+    private readonly dropHalf: number;
+
+    // Lifetime counters; not reset on eviction (observability
+    // surface, not buffer content).
+    private gapCount = 0;
+    private totalGapSeqSpan = 0;
+    private lastGapAt: number | null = null;
+
+    constructor(opts: LogBufferOptions = {}) {
+        this.max = Math.max(2, opts.max ?? LOG_BUFFER_MAX_LINES);
+        // dropHalf < max so eviction makes progress; floor at 1.
+        const requestedDrop = opts.dropHalf ?? LOG_BUFFER_DROP_HALF;
+        this.dropHalf = Math.min(this.max - 1, Math.max(1, requestedDrop));
+    }
+
+    /** Append a new line, assigning the next seq. Returns the created entry. */
+    append(line: LogLine): LogEntry {
+        const entry: LogEntry = { seq: this.nextSeq, line, ts: Date.now() };
+        this.nextSeq += 1;
+        this.entries.push(entry);
+        if (this.entries.length > this.max) {
+            this.evict();
+        }
+        // Fire after eviction so listeners observing
+        // `currentPosition()` see consistent state.
+        for (const cb of Array.from(this.listeners)) {
+            try {
+                cb(entry);
+            } catch {
+                // Listener errors must not leak into the append path.
+            }
+        }
+        return entry;
+    }
+
+    /**
+     * Open a disconnect window. No-op if already open.
+     * `markGapEnd()` will close it as `[start, end)`.
+     */
+    markGapStart(): void {
+        if (this.openGapStart !== null) return;
+        this.openGapStart = this.nextSeq;
+    }
+
+    /**
+     * Close the open gap at the current high-water seq. No-op if no
+     * gap is open. A zero-width close still records a
+     * `[start, start+1)` gap: a reconnect cycle taints the
+     * transition point even if no lines were demonstrably lost.
+     */
+    markGapEnd(): void {
+        if (this.openGapStart === null) return;
+        const start = this.openGapStart;
+        this.openGapStart = null;
+        const end = Math.max(this.nextSeq, start + 1);
+        this.gaps.push({ start, end });
+        this.gapCount += 1;
+        this.totalGapSeqSpan += end - start;
+        this.lastGapAt = Date.now();
+    }
+
+    /** Snapshot of lifetime gap stats. */
+    getStats(): LogBufferStats {
+        return {
+            gapCount: this.gapCount,
+            totalGapSeqSpan: this.totalGapSeqSpan,
+            lastGapAt: this.lastGapAt,
+            openGap: this.openGapStart !== null
+        };
+    }
+
+    /** Current high-water position as an opaque decimal string. */
+    currentPosition(): LogPosition {
+        return String(this.nextSeq);
+    }
+
+    /**
+     * Return lines with `seq >= parseInt(pos)`. Throws
+     * `LogBufferOverflowError` when `pos` references evicted lines.
+     */
+    linesSince(pos: LogPosition): LogLine[] {
+        const from = parsePos(pos);
+        if (from < this.minAvailableSeq) {
+            throw new LogBufferOverflowError(
+                `Requested log position "${pos}" is below the buffer's minimum available position "${String(this.minAvailableSeq)}". ` +
+                    `The buffer dropped older entries to stay under its memory cap — raise the cap, shorten the wait window, ` +
+                    `or take a fresh logPosition() after each assertion.`,
+                {
+                    requested: pos,
+                    minAvailable: String(this.minAvailableSeq)
+                }
+            );
+        }
+        if (from >= this.nextSeq) return [];
+        const out: LogLine[] = [];
+        for (const e of this.entries) {
+            if (e.seq >= from) out.push(e.line);
+        }
+        return out;
+    }
+
+    /**
+     * Same as `linesSince` but returns full entries; needed by
+     * wait/expect paths for gap-overlap checks.
+     */
+    entriesSince(pos: LogPosition): LogEntry[] {
+        const from = parsePos(pos);
+        if (from < this.minAvailableSeq) {
+            throw new LogBufferOverflowError(
+                `Requested log position "${pos}" is below the buffer's minimum available position "${String(this.minAvailableSeq)}".`,
+                { requested: pos, minAvailable: String(this.minAvailableSeq) }
+            );
+        }
+        if (from >= this.nextSeq) return [];
+        const out: LogEntry[] = [];
+        for (const e of this.entries) {
+            if (e.seq >= from) out.push(e);
+        }
+        return out;
+    }
+
+    /**
+     * First gap overlapping `[from, to ?? currentPosition)`.
+     * Half-open: `from == to` is empty. Includes the currently-open
+     * gap so a still-reconnecting stream is detectable mid-wait.
+     */
+    hasGapWithin(from: LogPosition, to?: LogPosition): Gap | null {
+        const fromN = parsePos(from);
+        const toN = to !== undefined ? parsePos(to) : this.nextSeq;
+        if (toN <= fromN) return null;
+        for (const g of this.gaps) {
+            if (g.start < toN && g.end > fromN) return { ...g };
+        }
+        if (this.openGapStart !== null) {
+            // Open gap extends forward indefinitely; any un-arrived
+            // line is "maybe-lost". `start === end` is valid and
+            // means "reconnecting now, no lines missing yet".
+            if (this.openGapStart <= toN) {
+                return { start: this.openGapStart, end: this.nextSeq };
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Gap containing `seq`, half-open. Strictly narrower than
+     * `hasGapWithin`: gaps fully before `seq` don't invalidate a
+     * clean match because `since` is captured pre-action.
+     */
+    findGapContaining(seq: number): Gap | null {
+        for (const g of this.gaps) {
+            if (seq >= g.start && seq < g.end) return { ...g };
+        }
+        if (this.openGapStart !== null && seq >= this.openGapStart) {
+            return { start: this.openGapStart, end: this.nextSeq };
+        }
+        return null;
+    }
+
+    /** Subscribe to new appends. Returns an unsubscribe thunk. */
+    subscribe(cb: (e: LogEntry) => void): () => void {
+        this.listeners.add(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
+    }
+
+    /** Drop the oldest `dropHalf` entries without recording a gap. */
+    private evict(): void {
+        const toDrop = Math.min(this.dropHalf, this.entries.length);
+        this.entries.splice(0, toDrop);
+        this.minAvailableSeq = this.entries[0]?.seq ?? this.nextSeq;
+        // Prune gaps that lie entirely below the new minimum. Without
+        // this, long suites with frequent reconnects accumulate stale
+        // gap records indefinitely — `hasGapWithin`/`findGapContaining`
+        // cannot reach them via valid (non-throwing) queries because
+        // the seqs they cover are below `minAvailableSeq`. `gaps` is
+        // append-only in seq order, so a leading-prefix splice is safe.
+        const min = this.minAvailableSeq;
+        let i = 0;
+        while (i < this.gaps.length && this.gaps[i]!.end <= min) i++;
+        if (i > 0) this.gaps.splice(0, i);
+    }
+}

package/src/logs/log-session.ts

@@ -0,0 +1,374 @@
+// 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;
+
+    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> {
+        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;
+    }
+
+    /**
+     * 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 {
+        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?.();
+    });
+}