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

package/src/client/deploy.ts

@@ -0,0 +1,402 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Deploy-adjacent helpers used by `RkClient.buildAndDeploy` /
+ * `launch` / `buildAndLaunchWithParams`. Pure-ish: workspace root
+ * discovery, manifest parsing, launch URL composition, tooling
+ * loader. The build/sideload/launch methods themselves stay on
+ * `RkClient` because they need the live ECP client, log session,
+ * and health singleton.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+
+import {
+    ECP_PORT,
+    loadToolingDeps as loadToolingDepsFromHelpers,
+    type RokuDeviceInstance as ToolingRokuDeviceInstance,
+    type ToolingDeps as ToolingDepsFromHelpers,
+    type ToolingDevice as ToolingDeviceFromHelpers,
+    ToolingError,
+    validateAndNormalizeKey
+} from "@roku-sdk/tooling/src/device-test-helpers";
+
+import { BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS, ENV_VAR } from "../constants";
+import { RkClientError } from "../errors";
+import { trimTrailingSlash } from "../jest/artifacts";
+
+export function normalizeKeyOrThrow(key: string): string {
+    const result = validateAndNormalizeKey(key);
+    if (!result.valid) {
+        throw new RkClientError(result.error ?? `Invalid Roku key: ${key}`, "ECP_INVALID_KEY");
+    }
+    return result.normalizedKey;
+}
+
+/**
+ * `POST /api/build` payload subset — only fields `buildAndDeploy`
+ * needs. Server-side `pkg`, `bumpMinor`, etc. are deliberately
+ * omitted; add explicitly here if a test path needs them.
+ */
+export interface ServerBuildRequest {
+    /** Absolute (or rk-server-cwd-relative) path to the app root. */
+    root: string;
+    /** Out directory relative to `root`. */
+    outDir: string;
+    /** Optional override for `roku-config.dropConsole`. */
+    dropConsole?: boolean;
+    /**
+     * Build with development artifacts — no minification, readable identifiers,
+     * source maps. Equivalent to `rk build --debug`. Useful for profiling sessions
+     * where readable function names in tracepoints matter.
+     */
+    dev?: boolean;
+    /**
+     * Enable SolidJS dev mode — imports the `solid-js/dev` build so signal
+     * and effect names remain readable in Perfetto tracepoints. Equivalent to
+     * `rk build --solid-dev-mode`.
+     */
+    solidDevMode?: boolean;
+    /**
+     * Build-time variable overrides merged on top of the app's `roku-config.ts`
+     * `buildVariables`. Pass `{ __SIGNAL__: true }` to enable SolidJS dev mode
+     * (readable signal/effect names in Perfetto tracepoints); other boolean
+     * entries are forwarded as-is.
+     */
+    buildVariables?: Record<string, boolean | string | number>;
+    /** Build type for the orchestrator session. Defaults to "build". */
+    buildType?: string;
+    /**
+     * Skip the whole-program TypeScript semantic check before
+     * bundling (maps to `rk build --no-typecheck`).
+     * Integration-test fixture builds set this so a pre-existing
+     * type error elsewhere in the workspace cannot block on-device
+     * verification of unrelated runtime APIs.
+     */
+    disableTypeChecking?: boolean;
+}
+
+/**
+ * Drive a `POST /api/build` SSE stream from the device-test-client
+ * to rk-server. Builds run in the sidecar container instead of the
+ * build container so esbuild service processes don't leak across
+ * Jest test-file module registries (each fresh `require` of
+ * `build-utils` would spawn a new `esbuild --service` child).
+ *
+ * Throws `RkClientError` on HTTP errors, SSE `error`/`complete`
+ * with `success:false`, or after the resolved idle timeout of
+ * inactivity — the caller wraps in `BuildFailedError`. The idle
+ * timeout caps sidecar wedges at a per-call failure so retries can
+ * recover instead of eating the whole CI job's wall-clock budget.
+ *
+ * The timeout is resolved from `RK_BUILD_SSE_IDLE_TIMEOUT_MS`
+ * (positive integer ms) at first call and cached for the process.
+ * A late env-var change does not retroactively reconfigure
+ * in-flight builds. Invalid values warn once and fall back to
+ * `BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS`.
+ */
+let resolvedSseIdleTimeoutMs: number | undefined;
+
+function resolveSseIdleTimeoutMs(): number {
+    if (resolvedSseIdleTimeoutMs !== undefined) return resolvedSseIdleTimeoutMs;
+    const raw = process.env[ENV_VAR.BUILD_SSE_IDLE_TIMEOUT_MS];
+    if (raw === undefined || raw === "") {
+        resolvedSseIdleTimeoutMs = BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS;
+        return resolvedSseIdleTimeoutMs;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+        // Warn once, then cache the fallback so we don't spam logs
+        // across every build call in a long suite.
+        console.warn(
+            `[device-test-client] ${ENV_VAR.BUILD_SSE_IDLE_TIMEOUT_MS}="${raw}" is not a positive integer; ` +
+                `falling back to default (${BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS}ms).`
+        );
+        resolvedSseIdleTimeoutMs = BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS;
+        return resolvedSseIdleTimeoutMs;
+    }
+    resolvedSseIdleTimeoutMs = parsed;
+    return resolvedSseIdleTimeoutMs;
+}
+
+/** Test-only: clear the cached idle-timeout so the next call re-reads env. */
+export function __resetBuildSseIdleTimeoutForTests(): void {
+    resolvedSseIdleTimeoutMs = undefined;
+}
+
+export async function requestServerBuild(serverUrl: string, payload: ServerBuildRequest): Promise<void> {
+    const endpoint = `${trimTrailingSlash(serverUrl)}/build`;
+
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "text/event-stream"
+        },
+        // Spread payload first; the explicit `buildType` override
+        // wins so the server sees a concrete value even if
+        // payload.buildType was blank.
+        body: JSON.stringify({
+            ...payload,
+            buildType: payload.buildType ?? "build"
+        })
+    });
+
+    if (!response.ok) {
+        // Body holds `{error, code}`; surface raw text and let the
+        // caller wrap in BuildFailedError with full path context.
+        const text = await response.text().catch(() => "<unreadable response body>");
+        throw new RkClientError(
+            `rk-server /api/build returned HTTP ${response.status}: ${text}`,
+            "RK_SERVER_BUILD_HTTP_ERROR"
+        );
+    }
+    if (!response.body) {
+        throw new RkClientError("rk-server /api/build returned no response body", "RK_SERVER_BUILD_EMPTY_BODY");
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let serverError: string | undefined;
+    let completed = false;
+    let success = false;
+
+    // SSE frames separated by `\n\n`. We only care about `error`
+    // and `complete` events; `stdout`/`stderr` build-log events
+    // are dropped (rk-server.log already captures them).
+    // Each `read()` races an idle timer; if no frame arrives for
+    // the resolved idle-timeout window we cancel the body and
+    // throw, converting sidecar wedges into recoverable per-call
+    // failures. Sized via env so cold-start CI runners can extend
+    // it without forcing a code change.
+    const idleTimeoutMs = resolveSseIdleTimeoutMs();
+    while (true) {
+        let result: ReadableStreamReadResult<Uint8Array>;
+        let idleTimer: ReturnType<typeof setTimeout> | undefined;
+        try {
+            result = await new Promise<ReadableStreamReadResult<Uint8Array>>((resolve, reject) => {
+                idleTimer = setTimeout(() => {
+                    reader.cancel(new Error(`SSE idle timeout after ${idleTimeoutMs}ms`)).catch(() => {
+                        // best-effort; we're rejecting either way
+                    });
+                    reject(
+                        new RkClientError(
+                            `rk-server /api/build SSE stream idle for ${idleTimeoutMs}ms ` +
+                                `(override via ${ENV_VAR.BUILD_SSE_IDLE_TIMEOUT_MS})`,
+                            "RK_SERVER_BUILD_IDLE_TIMEOUT"
+                        )
+                    );
+                }, idleTimeoutMs);
+                if (typeof (idleTimer as { unref?: () => unknown }).unref === "function") {
+                    (idleTimer as { unref: () => unknown }).unref();
+                }
+                reader.read().then(resolve, reject);
+            });
+        } finally {
+            if (idleTimer !== undefined) clearTimeout(idleTimer);
+        }
+        const { value, done } = result;
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+
+        let separatorIndex = buffer.indexOf("\n\n");
+        while (separatorIndex >= 0) {
+            const frame = buffer.slice(0, separatorIndex);
+            buffer = buffer.slice(separatorIndex + 2);
+            separatorIndex = buffer.indexOf("\n\n");
+
+            let eventType: string | undefined;
+            let dataPayload = "";
+            for (const line of frame.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed) continue;
+                if (trimmed.startsWith("event:")) {
+                    eventType = trimmed.slice(6).trim();
+                } else if (trimmed.startsWith("data:")) {
+                    const part = trimmed.slice(5).trim();
+                    dataPayload = dataPayload ? `${dataPayload}${part}` : part;
+                }
+            }
+            if (!eventType) continue;
+
+            let data: unknown;
+            if (dataPayload) {
+                try {
+                    data = JSON.parse(dataPayload);
+                } catch {
+                    data = dataPayload;
+                }
+            }
+
+            if (eventType === "error") {
+                const message =
+                    typeof data === "object" && data && "message" in data
+                        ? String((data as { message?: unknown }).message ?? "")
+                        : typeof data === "string"
+                          ? data
+                          : "rk-server build error (no message)";
+                serverError = message;
+            } else if (eventType === "complete") {
+                completed = true;
+                success =
+                    typeof data === "object" && data && "success" in data
+                        ? Boolean((data as { success?: boolean }).success)
+                        : true;
+            }
+        }
+    }
+
+    if (serverError) {
+        throw new RkClientError(`rk-server build error: ${serverError}`, "RK_SERVER_BUILD_FAILED");
+    }
+    if (!completed) {
+        throw new RkClientError(
+            "rk-server build stream closed before emitting `complete`",
+            "RK_SERVER_BUILD_STREAM_TRUNCATED"
+        );
+    }
+    if (!success) {
+        throw new RkClientError(
+            "rk-server build emitted `complete` with success=false",
+            "RK_SERVER_BUILD_UNSUCCESSFUL"
+        );
+    }
+}
+
+export function buildLaunchUrl(ip: string, channelId: string, deepLink?: Record<string, string>): string {
+    const base = `http://${ip}:${ECP_PORT}/launch/${encodeURIComponent(channelId)}`;
+    if (!deepLink || Object.keys(deepLink).length === 0) return base;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(deepLink)) params.append(k, v);
+    return `${base}?${params.toString()}`;
+}
+
+/**
+ * POST a no-body ECP request with the caller's timeout. Throws
+ * `ToolingError` with the standard tooling code taxonomy so retry
+ * predicates treat `/launch` and `/query` failures identically.
+ */
+export async function postNoBody(url: string, timeoutMs: number): Promise<void> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    if (typeof (timer as { unref?: () => unknown }).unref === "function") {
+        (timer as { unref: () => unknown }).unref();
+    }
+    let res: Response;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Length": "0" },
+            signal: controller.signal
+        });
+    } catch (err) {
+        clearTimeout(timer);
+        if ((err as Error).name === "AbortError") {
+            throw new ToolingError(`Request to ${url} timed out after ${timeoutMs}ms.`, "ECP_TIMEOUT");
+        }
+        throw new ToolingError(`ECP launch failed: ${(err as Error).message}`, "ECP_UNKNOWN_ERROR");
+    }
+    clearTimeout(timer);
+    if (!res.ok) {
+        // Mirrors EcpClient.handleHttpError so isTransientEcpError
+        // detects 5xx uniformly.
+        if (res.status === 401) {
+            throw new ToolingError(`Developer mode disabled on device (${url}).`, "ECP_DEVELOPER_MODE_DISABLED");
+        }
+        if (res.status === 404) {
+            throw new ToolingError(`ECP endpoint not found: ${url}.`, "ECP_ENDPOINT_NOT_FOUND");
+        }
+        throw new ToolingError(`ECP launch failed: ${res.status} ${res.statusText}`, "ECP_REQUEST_FAILED");
+    }
+}
+
+export function directoryExists(p: string): boolean {
+    try {
+        return statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Resolve `appPath`: absolute paths verbatim; relative paths
+ * tried against cwd, then the nearest `pnpm-workspace.yaml`
+ * ancestor. Falls back to the cwd-relative path so error
+ * messages name what the user most likely intended.
+ */
+export function resolveAppPath(appPath: string): string {
+    const cwdResolved = resolvePath(process.cwd(), appPath);
+    if (directoryExists(cwdResolved)) return cwdResolved;
+
+    const workspaceRoot = findWorkspaceRoot(process.cwd());
+    if (workspaceRoot) {
+        const workspaceResolved = resolvePath(workspaceRoot, appPath);
+        if (directoryExists(workspaceResolved)) return workspaceResolved;
+    }
+    return cwdResolved;
+}
+
+export function findWorkspaceRoot(startDir: string): string | null {
+    let dir = startDir;
+    while (true) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+        const parent = resolvePath(dir, "..");
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Read sideload app-type from a built pkg's `manifest`.
+ * Presence of `sg_component_libs_provided` → DCL library
+ * (`InstallLib_<name>`); otherwise a standard channel.
+ */
+export async function readAppTypeFromManifest(
+    pkgDir: string,
+    readManifestEntries: ToolingDeps["readManifestEntries"]
+): Promise<{ appType: "" | "channel" | "dcl"; libraryName?: string }> {
+    try {
+        const entries = await readManifestEntries(join(pkgDir, "manifest"));
+        const libsProvided = entries["sg_component_libs_provided"];
+        if (libsProvided) {
+            return { appType: "dcl", libraryName: libsProvided };
+        }
+    } catch {
+        // No manifest / unreadable — fall through to plain channel install.
+    }
+    return { appType: "" };
+}
+
+// ---------------------------------------------------------------------
+// Tooling dep surface — re-exported from `@roku-sdk/tooling`.
+//
+// The shapes and the lazy `require()` loader live on the tooling side
+// (see `@roku-sdk/tooling/device-test-helpers`) so the deep-require
+// paths are owned by the package whose internals they reference. We
+// re-export them under the original local names so the rest of this
+// package's source stays diff-free; consumers outside the package
+// continue to import from `@roku-sdk/device-test-client`.
+//
+// Why re-export instead of directly importing from the helper at
+// every callsite: `client.ts` already has `import type { ... } from
+// "./deploy"` for these names, and changing every callsite would
+// churn unrelated files for no readability win.
+// ---------------------------------------------------------------------
+
+export type ToolingDevice = ToolingDeviceFromHelpers;
+export type RokuDeviceInstance = ToolingRokuDeviceInstance;
+export type ToolingDeps = ToolingDepsFromHelpers;
+
+/**
+ * Load the heavy build-orchestration surface from `@roku-sdk/tooling`.
+ * Thin pass-through to `loadToolingDeps()` in
+ * `@roku-sdk/tooling/device-test-helpers`; kept as a local export so
+ * existing `import { loadToolingDeps } from "./deploy"` callsites
+ * (and the package's unit-test mocks targeting the underlying
+ * tooling modules via `jest.mock(...)`) keep their existing shape.
+ */
+export function loadToolingDeps(): ToolingDeps {
+    return loadToolingDepsFromHelpers();
+}

package/src/client/ecp-queue.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Serialized request queue with per-category minimum gap enforcement.
+ *
+ * Rationale: Roku's ECP server is single-threaded on the device side.
+ * Overlapping requests cause dropped calls and intermittent failures.
+ * All framework traffic therefore funnels through one queue with
+ * `concurrency = 1`. Additional throttles (200ms for `/query/app-ui`,
+ * 500ms for `/capture-screen`) layer on top per-category.
+ *
+ * The interval is measured between the **end** of the previous call in
+ * the same category and the **start** of the next — "gap-based", not
+ * "start-to-start". This matches the "minimum interval" semantics and
+ * is what the acceptance criteria test (`3x queryAppUi in >= 400ms` →
+ * 200ms gap × 2).
+ *
+ * Not exported from `src/index.ts`; it is an internal primitive used by
+ * `RkClient`. Exposed in tests via a dedicated relative import.
+ */
+
+type QueueTask<T = unknown> = {
+    category: string;
+    run: () => Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+};
+
+export class EcpRequestQueue {
+    private readonly minIntervalsByCategory: Record<string, number>;
+    private readonly lastFinishedAt: Record<string, number> = {};
+    private readonly pending: QueueTask[] = [];
+    private running = false;
+
+    /**
+     * @param minIntervalsByCategory - Minimum ms gap per category. Unknown
+     *     categories passed to `enqueue` are treated as `0` (serial but
+     *     unthrottled).
+     */
+    constructor(minIntervalsByCategory: Record<string, number>) {
+        this.minIntervalsByCategory = { ...minIntervalsByCategory };
+    }
+
+    /**
+     * Enqueue `fn` under `category`. The returned promise resolves with
+     * `fn`'s value (or rejects with its error) after:
+     *   1. all previously-enqueued tasks have settled (FIFO), and
+     *   2. the per-category minimum gap since the last successful call
+     *      in that category has elapsed.
+     *
+     * If `fn` throws, the next queued task runs immediately — a failure
+     * does NOT consume the rate-limit budget of its category. This keeps
+     * a broken endpoint from stalling the suite with phantom waits.
+     */
+    enqueue<T>(category: string, fn: () => Promise<T>): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            this.pending.push({
+                category,
+                run: fn as () => Promise<unknown>,
+                resolve: resolve as (v: unknown) => void,
+                reject
+            });
+            void this.drain();
+        });
+    }
+
+    private async drain(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+
+        try {
+            while (this.pending.length > 0) {
+                const task = this.pending.shift()!;
+                const minInterval = this.minIntervalsByCategory[task.category] ?? 0;
+                const lastEnd = this.lastFinishedAt[task.category] ?? 0;
+
+                if (minInterval > 0) {
+                    const wait = lastEnd + minInterval - Date.now();
+                    if (wait > 0) {
+                        await sleepUnref(wait);
+                    }
+                }
+
+                try {
+                    const result = await task.run();
+                    // Only successful calls count toward the rate limit;
+                    // failed endpoints must not stall the queue.
+                    this.lastFinishedAt[task.category] = Date.now();
+                    task.resolve(result);
+                } catch (err) {
+                    task.reject(err);
+                }
+            }
+        } finally {
+            this.running = false;
+        }
+    }
+}
+
+/**
+ * `setTimeout`-based sleep that `unref()`s the timer so Node can exit
+ * cleanly if the queue is drained while a timeout is still armed.
+ */
+function sleepUnref(ms: number): Promise<void> {
+    return new Promise<void>(resolve => {
+        const t = setTimeout(resolve, ms);
+        // `.unref()` is only defined in Node; guard for non-Node hosts.
+        if (typeof (t as { unref?: () => unknown }).unref === "function") {
+            (t as { unref: () => unknown }).unref();
+        }
+    });
+}

package/src/client/ecp-retry.ts

@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Single-shot retry wrapper for transient ECP failures.
+ *
+ * Per Jira AC: "On 5xx or timeout, retry once after 500ms backoff,
+ * transparent to callers." Not exponential, not configurable count —
+ * exactly one retry. If the retry fails, we surface the second error,
+ * so the caller gets the most recent diagnostic.
+ */
+
+import { ToolingError } from "@roku-sdk/tooling/src/device-test-helpers";
+
+export interface RetryOptions {
+    /** Delay between the first failure and the retry (ms). */
+    backoffMs: number;
+    /** Predicate — return true to retry, false to rethrow immediately. */
+    isTransient: (err: unknown) => boolean;
+}
+
+/**
+ * Run `op`. On failure, if `isTransient(err)` is true, wait `backoffMs`
+ * and run once more. Propagates the second error (not the first) on
+ * double-failure so the most recent device signal reaches the caller.
+ */
+export async function retryOnTransient<T>(op: () => Promise<T>, opts: RetryOptions): Promise<T> {
+    try {
+        return await op();
+    } catch (err) {
+        if (!opts.isTransient(err)) throw err;
+        await sleepUnref(opts.backoffMs);
+        return await op();
+    }
+}
+
+/**
+ * ECP-specific transience predicate. Treats these as retryable:
+ *   - `ECP_TIMEOUT` — fetch aborted by our `AbortController`.
+ *   - `ECP_REQUEST_FAILED` with status 5xx parsed out of the message.
+ *   - `ECP_UNKNOWN_ERROR` when the underlying fetch surfaced a generic
+ *     transport failure (`fetch failed`), which we observe on the room
+ *     Roku as a transient blip even while the device remains healthy.
+ *
+ * Non-transient (intentionally):
+ *   - 401 `ECP_DEVELOPER_MODE_DISABLED` — config issue, retrying can't help.
+ *   - 404 `ECP_ENDPOINT_NOT_FOUND` — wrong endpoint / unsupported device.
+ *   - Invalid-IP / connection-refused — physical issue, retry is noise.
+ *
+ * The 5xx branch delegates to `isEcpServerError`, which parses the
+ * status out of the message; on parse failure it reports false, so we
+ * default to NOT retrying — false negatives are safer than retrying
+ * 4xx forever.
+ */
+export function isTransientEcpError(err: unknown): boolean {
+    if (!(err instanceof ToolingError)) return false;
+
+    if (err.code === "ECP_TIMEOUT") return true;
+
+    if (err.code === "ECP_REQUEST_FAILED") return isEcpServerError(err);
+
+    if (err.code === "ECP_UNKNOWN_ERROR") {
+        return err.message.includes("fetch failed");
+    }
+
+    return false;
+}
+
+/**
+ * True when `err` is an `ECP_REQUEST_FAILED` carrying a 5xx status —
+ * the device answered, but its own subsystem refused the request
+ * (e.g. `503` from a launcher that is busy foregrounding a channel).
+ * Callers that can verify the outcome another way use this to tell a
+ * device-side hiccup apart from a client-side mistake (4xx).
+ *
+ * `ToolingError` bakes the status into the message as
+ * `ECP ${context} failed: ${status} ${statusText}`, which is what the
+ * status is parsed from.
+ */
+export function isEcpServerError(err: unknown): boolean {
+    if (!(err instanceof ToolingError) || err.code !== "ECP_REQUEST_FAILED") return false;
+    const match = /failed:\s*(\d{3})\b/.exec(err.message);
+    if (!match) return false;
+    const status = Number(match[1]);
+    return status >= 500 && status < 600;
+}
+
+function sleepUnref(ms: number): Promise<void> {
+    return new Promise<void>(resolve => {
+        const t = setTimeout(resolve, ms);
+        if (typeof (t as { unref?: () => unknown }).unref === "function") {
+            (t as { unref: () => unknown }).unref();
+        }
+    });
+}