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

package/src/logs/log-stream-client.ts

@@ -0,0 +1,296 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Tiny SSE consumer for `POST /logs/tail`. Avoids a dependency for
+ * ~30 lines of framing logic (auditable in failure postmortems).
+ *
+ * Wire format: `event: <type>\ndata: <payload>\n\n` where payload is
+ * raw for `log` events and JSON for `status`/`error`.
+ *
+ * Handles CRLF normalisation, chunk-split frames (pending buffer
+ * dispatched on `\n\n`), and multi-line `data:` continuations.
+ */
+
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+
+import { SSE_PENDING_MAX_BYTES } from "../constants";
+
+export interface LogStreamCallbacks {
+    /**
+     * `event: log` frame. `serverSeq` is the parsed `id:` field, used
+     * by `LogSession` to dedup replay batches; `undefined` when the
+     * server omits it (older builds).
+     */
+    onLine(line: string, serverSeq?: number): void;
+    /** `event: status` frame. `lines` is best-effort. */
+    onStatus(status: string, lines?: number): void;
+    /** `event: error` frames and fatal transport errors. */
+    onError(message: string): void;
+    /**
+     * Server-initiated transport termination (response `end` w/o
+     * `status: stopped`, or post-connect socket error). NOT invoked
+     * for local `close()` — teardown stays silent.
+     */
+    onClose?(): void;
+}
+
+export interface LogStreamClientOptions {
+    /** Base URL of the `rk server` daemon (e.g. `http://localhost:3737`). */
+    serverUrl: string;
+    /** Device selector (ip/id/name); omit → server's active device. */
+    device?: string;
+    /** Roku log port override (default server-side: 8085). */
+    port?: number;
+    /** Test-only body override. */
+    body?: string;
+}
+
+type ParsedEvent = { event: string; data: string; id?: string };
+
+export class LogStreamClient {
+    private readonly opts: LogStreamClientOptions;
+    private readonly cbs: LogStreamCallbacks;
+    private controller: AbortController | null = null;
+    private req: http.ClientRequest | null = null;
+    private closed = false;
+    // True iff close() was invoked locally; suppresses onClose so
+    // user-initiated teardown stays silent.
+    private userClosed = false;
+    // Guards onClose from firing more than once across end + error.
+    private onCloseFired = false;
+    private pending = "";
+
+    constructor(opts: LogStreamClientOptions, cbs: LogStreamCallbacks) {
+        this.opts = opts;
+        this.cbs = cbs;
+    }
+
+    /**
+     * Open POST + SSE subscription. Synchronous; HTTP dial happens
+     * in the background, errors surface via `cbs.onError`. Callers
+     * gate on the first `onStatus("active", ...)` for "connected".
+     */
+    open(): void {
+        if (this.controller) return; // already open
+        this.controller = new AbortController();
+        const body =
+            this.opts.body ??
+            JSON.stringify({
+                ...(this.opts.device ? { device: this.opts.device } : {}),
+                ...(this.opts.port !== undefined ? { port: this.opts.port } : {})
+            });
+
+        // Don't use `new URL("/logs/tail", base)` — WHATWG URL
+        // resolution drops the base's path on a leading `/`. Our
+        // base is `http://host:port/api`; concatenate to preserve.
+        let url: URL;
+        try {
+            const base = this.opts.serverUrl.endsWith("/") ? this.opts.serverUrl.slice(0, -1) : this.opts.serverUrl;
+            url = new URL(`${base}/logs/tail`);
+        } catch (err) {
+            this.cbs.onError(`LogStreamClient: invalid serverUrl "${this.opts.serverUrl}": ${(err as Error).message}`);
+            return;
+        }
+
+        const lib = url.protocol === "https:" ? https : http;
+        const req = lib.request(
+            {
+                protocol: url.protocol,
+                hostname: url.hostname,
+                port: url.port || (url.protocol === "https:" ? 443 : 80),
+                path: url.pathname + url.search,
+                method: "POST",
+                headers: {
+                    Accept: "text/event-stream",
+                    "Content-Type": "application/json",
+                    "Content-Length": Buffer.byteLength(body, "utf8"),
+                    "Cache-Control": "no-cache"
+                },
+                signal: this.controller.signal
+            },
+            res => {
+                // Non-2xx → surface to session manager for retry
+                // decision. Guard against late arrival post-close.
+                if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                    if (this.closed) return;
+                    this.cbs.onError(`LogStreamClient: /logs/tail returned HTTP ${res.statusCode ?? "?"}.`);
+                    return;
+                }
+                res.setEncoding("utf8");
+                res.on("data", chunk => this.ingest(chunk));
+                res.on("end", () => {
+                    this.flushPending();
+                    const wasUserClosed = this.userClosed;
+                    this.closed = true;
+                    if (!wasUserClosed) this.fireOnClose();
+                });
+                res.on("error", err => {
+                    if (this.closed) return;
+                    this.cbs.onError(`LogStreamClient: response stream error: ${err.message}`);
+                    // Post-connect socket error is a remote close.
+                    this.closed = true;
+                    if (!this.userClosed) this.fireOnClose();
+                });
+            }
+        );
+
+        req.on("error", err => {
+            if (this.closed) return;
+            // AbortError from close() is expected; suppress noise.
+            if ((err as NodeJS.ErrnoException).name === "AbortError") return;
+            this.cbs.onError(`LogStreamClient: request error: ${err.message}`);
+        });
+
+        req.write(body);
+        req.end();
+        this.req = req;
+    }
+
+    /** Abort the HTTP request. Idempotent. */
+    close(): void {
+        if (this.closed) return;
+        // Flag BEFORE aborting so abort/end handlers see the
+        // user-initiated flavour and suppress onClose.
+        this.userClosed = true;
+        this.closed = true;
+        try {
+            this.controller?.abort();
+        } catch {
+            // swallow — abort is best-effort
+        }
+        try {
+            this.req?.destroy();
+        } catch {
+            // swallow
+        }
+        this.controller = null;
+        this.req = null;
+    }
+
+    /** Fire `onClose` at most once; swallow handler errors. */
+    private fireOnClose(): void {
+        if (this.onCloseFired) return;
+        this.onCloseFired = true;
+        try {
+            this.cbs.onClose?.();
+        } catch {
+            // callback errors are not actionable here
+        }
+    }
+
+    /** Ingest a chunk of SSE text and dispatch completed events. */
+    private ingest(chunk: string): void {
+        if (this.closed) return;
+        this.pending += chunk.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        let idx: number;
+        while ((idx = this.pending.indexOf("\n\n")) !== -1) {
+            const raw = this.pending.slice(0, idx);
+            this.pending = this.pending.slice(idx + 2);
+            const parsed = this.parseFrame(raw);
+            if (parsed) this.dispatch(parsed);
+        }
+        // Fail loud if the server streams without frame terminators
+        // so the worker doesn't OOM. Treat as user-close so onClose
+        // is silent — re-attaching would just repeat the pathology.
+        if (this.pending.length > SSE_PENDING_MAX_BYTES) {
+            if (this.closed) return;
+            const size = this.pending.length;
+            this.pending = "";
+            this.cbs.onError(
+                `LogStreamClient: SSE frame exceeded ${SSE_PENDING_MAX_BYTES} bytes without terminator (pending=${size}).`
+            );
+            this.close();
+        }
+    }
+
+    /** Flush trailing bytes at stream end (rarely has a complete frame). */
+    private flushPending(): void {
+        if (!this.pending) return;
+        const raw = this.pending;
+        this.pending = "";
+        const parsed = this.parseFrame(raw);
+        if (parsed) this.dispatch(parsed);
+    }
+
+    /**
+     * Minimal SSE frame parser. Ignores `:` comments and `retry:`.
+     * `data:` lines join with `\n`; `id:` last-wins per spec.
+     */
+    private parseFrame(raw: string): ParsedEvent | null {
+        let event = "message";
+        let id: string | undefined;
+        const dataParts: string[] = [];
+        for (const line of raw.split("\n")) {
+            if (!line || line.startsWith(":")) continue;
+            const colon = line.indexOf(":");
+            const field = colon === -1 ? line : line.slice(0, colon);
+            // SSE spec: if a space follows the colon, skip it.
+            let value = colon === -1 ? "" : line.slice(colon + 1);
+            if (value.startsWith(" ")) value = value.slice(1);
+            if (field === "event") event = value;
+            else if (field === "data") dataParts.push(value);
+            else if (field === "id") id = value;
+            // ignore retry / other
+        }
+        if (dataParts.length === 0) return null;
+        return { event, data: dataParts.join("\n"), id };
+    }
+
+    private dispatch(evt: ParsedEvent): void {
+        if (this.closed) return;
+        try {
+            if (evt.event === "log") {
+                // Server emits `{"line":"..."}`; fall back to raw
+                // payload on parse failure so we make progress on
+                // malformed events.
+                const line = extractLine(evt.data);
+                const serverSeq = parseSeq(evt.id);
+                this.cbs.onLine(line, serverSeq);
+            } else if (evt.event === "status") {
+                const parsed = tryParseJson(evt.data);
+                const status = typeof parsed?.status === "string" ? parsed.status : "";
+                const lines = typeof parsed?.lines === "number" ? parsed.lines : undefined;
+                if (status) this.cbs.onStatus(status, lines);
+            } else if (evt.event === "error") {
+                const parsed = tryParseJson(evt.data);
+                const msg = (typeof parsed?.message === "string" && parsed.message) || evt.data || "unknown SSE error";
+                this.cbs.onError(msg);
+            }
+            // other event types: ignored
+        } catch (err) {
+            this.cbs.onError(`LogStreamClient: dispatch error: ${(err as Error).message}`);
+        }
+    }
+}
+
+/**
+ * Extract `line` field from a log event. Falls back to raw `data`
+ * so the parser doesn't wedge on malformed payloads.
+ */
+function extractLine(data: string): string {
+    const parsed = tryParseJson(data);
+    if (parsed && typeof parsed.line === "string") return parsed.line;
+    return data;
+}
+
+function tryParseJson(data: string): Record<string, unknown> | null {
+    try {
+        const v = JSON.parse(data);
+        return typeof v === "object" && v !== null ? (v as Record<string, unknown>) : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Parse SSE `id:` as a non-negative integer; `undefined` for
+ * missing/invalid (callers fall back to first-seen-wins).
+ */
+function parseSeq(id: string | undefined): number | undefined {
+    if (id === undefined || id === "") return undefined;
+    const n = Number(id);
+    if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) return undefined;
+    return n;
+}

package/src/paths.ts

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Internal path helpers. Not re-exported from `src/index.ts` — these
+ * are implementation details for call sites that compose a default
+ * path to the consumer's `test-results/` directory.
+ *
+ * Why this module exists:
+ *   Before this file, three call sites (`device-env-sync.ts`,
+ *   `client.ts`, `device-test-environment.ts`) each embedded the
+ *   string `"test-results"` inline. A rename (e.g. to `"artifacts/"`)
+ *   would have silently split call sites. Centralising here keeps
+ *   future renames to a one-file change.
+ *
+ * Kept out of the public barrel on purpose: the consumer's own
+ * `jest.config.ts` / `setup.ts` pass an explicit `testResultsDir` to
+ * `createGlobalSetup` / `installDeviceTestHooks`, so the default is
+ * a library-internal fallback, not a documented API surface.
+ */
+
+/**
+ * Directory name (relative to the consumer's repo root / `process.cwd()`)
+ * where Jest artifacts, baselines metadata, and the device-env snapshot
+ * are written. Every call site that composes a default path to the
+ * consumer's test-results directory MUST go through this constant so
+ * that a future rename is a one-file change.
+ */
+export const TEST_RESULTS_DIR_NAME = "test-results";
+
+import { isAbsolute } from "node:path";
+
+/**
+ * Absolute per-run artifact root used by the multi-device shard runner.
+ * When set, it MUST override the historical `<cwd>/test-results` default
+ * everywhere worker-side code reads globalSetup artifacts (`.device-ip`,
+ * `device-env.json`, junit helpers). Keeping this env name in the package
+ * rather than only in `device-tests/testUtils/test-results-dir.ts` prevents
+ * the split-brain failure where globalSetup writes to one directory while
+ * `createDefaultClient()` reads from another.
+ */
+export const TEST_RESULTS_DIR_ENV_VAR = "RK_TEST_RESULTS_DIR";
+
+/**
+ * Compose an absolute path to the consumer's test-results directory.
+ *
+ * Precedence:
+ *   1. `RK_TEST_RESULTS_DIR` absolute path (multi-device runner).
+ *   2. Historical default: `<rootDir>/test-results`.
+ *
+ * Returned string uses POSIX forward-slashes for the fallback to match
+ * the pre-existing behaviour of `client.ts`' IP-handoff path composition.
+ */
+export function defaultTestResultsDir(rootDir: string = process.cwd()): string {
+    const fromEnv = process.env[TEST_RESULTS_DIR_ENV_VAR];
+    if (fromEnv && fromEnv.length > 0) {
+        if (!isAbsolute(fromEnv)) {
+            throw new Error(
+                `[device-test-client] ${TEST_RESULTS_DIR_ENV_VAR} must be an absolute path; got "${fromEnv}". ` +
+                    `Relative paths would split globalSetup artifacts from worker-side readers.`
+            );
+        }
+        return fromEnv;
+    }
+    return `${rootDir}/${TEST_RESULTS_DIR_NAME}`;
+}