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

package/src/logs/log-buffer.ts

@@ -0,0 +1,278 @@
+// 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, and includes the currently-open gap so a
+     * still-reconnecting stream is detectable mid-wait.
+     *
+     * `from == to` is an empty *line* range but not an empty
+     * question: a wait that received nothing while the stream was
+     * reconnecting is the case where "no lines" and "lines we never
+     * heard about" are indistinguishable, so an open gap still
+     * answers. Only an inverted range answers `null` outright.
+     */
+    hasGapWithin(from: LogPosition, to?: LogPosition): Gap | null {
+        const fromN = parsePos(from);
+        const toN = to !== undefined ? parsePos(to) : this.nextSeq;
+        if (toN < fromN) return null;
+        // Overlap is the wrong test for an empty range — nothing
+        // overlaps it — so ask instead whether a gap contains `fromN`
+        // itself, which is what `findGapContaining` means by tainted
+        // and what a gap closed at `[fromN, fromN + 1)` records. A gap
+        // lying entirely to either side stays excluded either way.
+        const empty = toN === fromN;
+        for (const g of this.gaps) {
+            const reachesWindow = empty ? fromN >= g.start && fromN < g.end : g.start < toN && g.end > fromN;
+            if (reachesWindow) 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);
+    }
+}