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

package/src/client/build-cache.ts

@@ -0,0 +1,292 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * In-process build memoization for `RkClient.buildAndDeploy`.
+ *
+ * **Why this exists.** Each device-test file
+ * registers its own `beforeAll` deploy via `installDeployGuard`,
+ * which calls `RkClient.buildAndDeploy(appPath, opts)`. A single
+ * Jest `--runInBand` shard often deploys the same fixture from
+
+ * many test files — e.g. the `internal-runtime` shard re-builds `apps/internal-runtime`
+
+ * eight times for the eight `runtime/*.test.ts` siblings. Source
+ * files do not change between those `beforeAll` blocks, so the
+ * second through eighth `requestServerBuild()` calls are pure
+ * waste: rk-server happily re-bundles, re-instruments, re-packages
+ * an identical input on every call. Even a 20s build amortises to
+ * ~2–3 min of redundant wall-clock per shard.
+ *
+ * This module caches the BUILD step only. Sideload + launch still
+ * run on every `buildAndDeploy` invocation — the device's state
+ * between two test files is unknown and a fresh sideload is the
+ * cheapest way to guarantee a clean slate.
+ *
+ * ## Cache key
+ *
+ * The key is the tuple `(absRoot, outDir, buildType, dropConsole)`.
+ * These are exactly the inputs of `requestServerBuild`'s payload
+ * that affect the produced `pkg-dir`. `deviceSelector`, `channelId`,
+ * `deepLink`, `readyNode`, `readinessTimeout` are not part of the
+ * key because they are deploy/launch concerns; mutating any of them
+ * across calls MUST NOT skip the rebuild (and does not, because
+ * none of them is in the key).
+ *
+ * `dropConsole === undefined` is canonicalised to `null` so the
+ * three states (`true`, `false`, omitted) hash to three distinct
+ * keys. This matches `requestServerBuild`'s server-side merge
+ * semantics: an omitted value lets `roku-config.ts` win, while an
+ * explicit value overrides — those are different inputs and must
+ * be different cache buckets.
+ *
+ * ## Failure semantics
+ *
+ * Cache entries store the in-flight `Promise<void>`, not the
+ * resolved value. On rejection the entry is removed from the map
+ * BEFORE the rejection propagates, so a transient build failure
+ * does not poison subsequent retries. The deploy-guard's retry
+ * loop relies on this: a failing first attempt must be retryable
+ * without first wiping the cache by hand.
+ *
+ * Storing the Promise also gives us free deduplication for
+ * concurrent callers: if two `beforeAll` hooks race the same key
+ * (rare under `--runInBand`, but cheap to support and forward-
+ * compatible with future `maxWorkers > 1` modes), both await the
+ * same in-flight `requestServerBuild`.
+ *
+ * ## Invalidation
+ *
+ * Two explicit paths exist:
+ *
+ *   - `invalidateBuildCacheForApp(absRoot)` — removes every entry
+ *     whose `absRoot` matches. Called by
+ *     `device-tests/testUtils/deploy-guard.ts`'s
+ *     `wipeIntegrationBuildOutput` right after it `rm -rf`s
+ *     `<absRoot>/dist-integration-test/`. Pairing the two means a
+ *     "the previous attempt's bundle is dirty" recovery path also
+ *     invalidates the memoized "we already built this" assertion.
+ *   - `__resetBuildCacheForTests()` — clears everything. Wired
+ *     into unit-test `beforeEach` so cache state never leaks
+ *     across test cases in the same Jest worker.
+ *
+ * IMPORTANT: different keys can still write the same physical output
+ * directory. Example: `buildType=never-ready` and `buildType=build`
+ * both write `<absRoot>/dist-integration-test/pkg-dir`. Therefore a
+ * cache miss that is about to build one key must evict any sibling
+ * entries with the same `(absRoot, outDir)` before the build writes
+ * to disk. Otherwise a later hit for the old key would skip rebuild
+ * and sideload bytes produced by the newer sibling build.
+ *
+ * Exported via `./support/deploy` (not the public barrel) because
+ * it is a harness helper, not something test bodies call. Treat any
+ * change here as a change to that entry point and the deploy-guard
+ * contract together.
+ */
+
+/**
+ * Cache-key components surfaced to the call site. `dropConsole`
+ * accepts the explicit-`undefined` arm so callers can pass
+ * `opts?.dropConsole` directly without pre-normalising.
+ */
+export interface BuildCacheKeyInput {
+    /** Absolute path to the app root that rk-server will build. */
+    absRoot: string;
+    /** `outDir` relative to `absRoot` (currently always
+     * `dist-integration-test`, but keyed explicitly so a future
+     * out-dir change cannot silently reuse a stale entry). */
+    outDir: string;
+    /** Value forwarded as `buildType` in the server payload —
+     * derived from `process.env.ROKU_BUILD_TYPE` with `"build"`
+     * fallback. */
+    buildType: string;
+    /** Tri-state: `true` / `false` / `undefined` (omitted). */
+    dropConsole: boolean | undefined;
+    /**
+     * Whether the build was requested with development artifacts
+     * (no minification, source maps). A dev build and a prod build
+     * of the same app must not share a cache entry.
+     */
+    dev?: boolean;
+    /** Whether SolidJS dev mode was requested (`--solid-dev`). */
+    solidDevMode?: boolean;
+    /**
+     * Build-time variable overrides. Different overrides produce
+     * different bundles (e.g. `__SIGNAL__: true` switches to the
+     * SolidJS dev build) so they must be part of the cache key.
+     */
+    buildVariables?: Record<string, boolean | string | number>;
+}
+
+/**
+ * Compute the deterministic string key for a build-cache lookup.
+ * Exported (named, no underscore) so the unit tests can derive the
+ * same key directly and assert the canonicalisation rules — and so
+ * a future caller that wants to peek at the cache outside
+ * `getOrCreateBuildPromise` does not have to re-implement the
+ * shape contract.
+ *
+ * **Key shape (stable contract):** newline-separated `field=value`
+ * pairs in a fixed order. The line-based layout — chosen over
+ * `JSON.stringify` — sidesteps any future key-order change in V8's
+ * object-literal serialisation and stays grep-friendly in debug
+ * logs. The fixed field order is the public contract: appending a
+ * new field is a minor (older keys still match), reordering
+ * existing fields is a breaking cache flush.
+ */
+export function computeBuildCacheKey(input: BuildCacheKeyInput): string {
+    // Canonicalise `dropConsole`: the `undefined` arm collapses to
+    // the literal string `"omitted"` so a forgotten `?? null` at a
+    // call site cannot create a key collision with `dropConsole: null`
+    // (which would otherwise stringify the same as our sentinel).
+    const dropConsoleKey = input.dropConsole === undefined ? "omitted" : input.dropConsole ? "true" : "false";
+    // Canonicalise buildVariables: sort keys so `{ a, b }` and `{ b, a }` hash the same.
+    const buildVarsKey = input.buildVariables
+        ? Object.keys(input.buildVariables)
+              .sort()
+              .map(k => `${k}=${input.buildVariables![k]}`)
+              .join(",")
+        : "omitted";
+    return [
+        `root=${input.absRoot}`,
+        `outDir=${input.outDir}`,
+        `buildType=${input.buildType}`,
+        `dropConsole=${dropConsoleKey}`,
+        `dev=${input.dev ? "true" : "false"}`,
+        `solidDevMode=${input.solidDevMode ? "true" : "false"}`,
+        `buildVariables=${buildVarsKey}`
+    ].join("\n");
+}
+
+interface BuildCacheEntry {
+    /** Absolute app root the entry was created for. Carried on the
+     * entry so `invalidateBuildCacheForApp(absRoot)` can match
+     * without re-parsing the composite key. */
+    readonly absRoot: string;
+    /** Out directory relative to `absRoot`. Entries with the same
+     * `(absRoot, outDir)` point at the same on-disk pkg-dir even when
+     * their logical build inputs differ (e.g. `buildType`). */
+    readonly outDir: string;
+    /** In-flight or already-resolved promise from `requestServerBuild`.
+     * Rejected promises are removed from the cache BEFORE the
+     * rejection settles to the original caller (see the catch
+     * handler installed in `getOrCreateBuildPromise`). */
+    readonly promise: Promise<void>;
+}
+
+const buildCache = new Map<string, BuildCacheEntry>();
+
+function invalidateSiblingOutputEntries(keyToKeep: string, keyInput: BuildCacheKeyInput): void {
+    for (const [key, entry] of buildCache) {
+        if (key !== keyToKeep && entry.absRoot === keyInput.absRoot && entry.outDir === keyInput.outDir) {
+            buildCache.delete(key);
+        }
+    }
+}
+
+/**
+ * Run `factory()` exactly once per `(absRoot, outDir, buildType,
+ * dropConsole)` combination within this process. Subsequent calls
+ * with the same key await the cached promise without re-invoking
+ * `factory`.
+ *
+ * The factory is responsible for performing the actual build work
+ * (`requestServerBuild`). Resolution / rejection propagate verbatim
+ * to every caller awaiting the same key; on rejection the entry
+ * is dropped so the very next call re-enters the factory rather
+ * than re-throwing forever.
+ *
+ * On cache hit a single `[device-test-client] build cache hit: …`
+ * line is emitted to stdout — meaningful triage signal for
+ * "why did the runtime shard finish 3 min faster on this run"
+ * without flooding the log (each shard fires this O(#test-files)
+ * times at most, ~5–10 total).
+ */
+export function getOrCreateBuildPromise(keyInput: BuildCacheKeyInput, factory: () => Promise<void>): Promise<void> {
+    const key = computeBuildCacheKey(keyInput);
+    const existing = buildCache.get(key);
+    if (existing) {
+        console.log(`[device-test-client] build cache hit: ${keyInput.absRoot}`);
+        return existing.promise;
+    }
+    // A cache miss is about to write `<absRoot>/<outDir>/pkg-dir`.
+    // Remove any older logical variants pointing at that same output
+    // directory first. Without this, `buildType=build` can overwrite
+    // the pkg-dir produced by `buildType=never-ready` while the
+    // never-ready cache entry remains "valid" and later sideloads the
+    // wrong bytes.
+    invalidateSiblingOutputEntries(key, keyInput);
+    // Wrap the factory invocation in a try/catch so a synchronous
+    // throw (e.g. a programming error in the factory closure) is
+    // converted to a rejected promise — without this, the cache
+    // would never have stored the failure and any caller racing the
+    // same key would re-enter the failing factory.
+    let promise: Promise<void>;
+    try {
+        promise = factory();
+    } catch (err) {
+        promise = Promise.reject(err);
+    }
+    const entry: BuildCacheEntry = {
+        absRoot: keyInput.absRoot,
+        outDir: keyInput.outDir,
+        promise: promise.catch(err => {
+            // Remove the failed entry FIRST so a retry that races
+            // the rejection settling still goes through to a fresh
+            // factory invocation. `Map.delete` is keyed by the
+            // composite string we computed above, so we close over
+            // `key` rather than relying on entry identity.
+            buildCache.delete(key);
+            throw err;
+        })
+    };
+    buildCache.set(key, entry);
+    // Return the wrapped promise (not the raw `promise`) so the
+    // failure-cleanup `.catch` always runs even when the original
+    // caller awaits and immediately exits on error. Awaiters of
+    // both the original and the cached entry observe the same
+    // rejection.
+    return entry.promise;
+}
+
+/**
+ * Remove every cache entry whose `absRoot` matches the argument.
+ *
+ * Called by `device-tests/testUtils/deploy-guard.ts` immediately
+ * after wiping `<absRoot>/dist-integration-test/`. The wipe runs
+ * between deploy retries to defend against a half-written manifest
+ * left by a crashed rk-server build; if we kept the memoized
+ * promise around, a retry inside the same Jest run would "succeed"
+ * by skipping the build entirely — and then sideload from an
+ * empty pkg-dir.
+ *
+ * Per-`absRoot` granularity (rather than `clearAll`) is deliberate:
+ * a recovery loop for one fixture should not flush the entries for
+ * unrelated fixtures already cached in the same Jest run.
+ */
+export function invalidateBuildCacheForApp(absRoot: string): void {
+    for (const [key, entry] of buildCache) {
+        if (entry.absRoot === absRoot) {
+            buildCache.delete(key);
+        }
+    }
+}
+
+/**
+ * Test-only escape hatch — clear every cache entry. Unit tests
+ * call this in `beforeEach` so cache state never leaks across
+ * cases in the same Jest worker. Production code MUST NOT call
+ * this; use `invalidateBuildCacheForApp` for per-`absRoot`
+ * eviction instead.
+ */
+export function __resetBuildCacheForTests(): void {
+    buildCache.clear();
+}
+
+/**
+ * Test-only — number of live entries currently in the cache.
+ * Exposed for assertions like "the second call did NOT add a new
+ * entry" without inspecting the private map directly.
+ */
+export function __buildCacheSizeForTests(): number {
+    return buildCache.size;
+}