@hyperframes/engine 0.6.119 → 0.6.120

package/src/services/systemMemory.test.ts

@@ -1,324 +0,0 @@
-import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
-import {
-  _resetCgroupLimitCacheForTests,
-  isLowMemorySystem,
-  LOW_MEMORY_TOTAL_MB_THRESHOLD,
-  parseCgroupLimitMb,
-} from "./systemMemory.js";
-
-const BYTES_PER_MIB = 1024 * 1024;
-const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
-const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
-
-type SystemMemoryModule = typeof import("./systemMemory.js");
-
-type MockSystemMemoryOptions = {
-  files?: Record<string, string>;
-  hostTotalMb?: number;
-  platform?: NodeJS.Platform;
-  readErrors?: Record<string, NodeJS.ErrnoException>;
-  onRead?: (path: string) => void;
-  throwOnFileRead?: boolean;
-};
-
-function stubPlatform(platform: NodeJS.Platform): () => void {
-  const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
-  Object.defineProperty(process, "platform", { value: platform });
-
-  return () => {
-    if (descriptor) {
-      Object.defineProperty(process, "platform", descriptor);
-    }
-  };
-}
-
-async function withSystemMemoryMocks(
-  options: MockSystemMemoryOptions,
-  run: (systemMemory: SystemMemoryModule) => void | Promise<void>,
-): Promise<void> {
-  const {
-    files = {},
-    hostTotalMb = 32768,
-    platform = "linux",
-    readErrors = {},
-    onRead,
-    throwOnFileRead = false,
-  } = options;
-  const restorePlatform = stubPlatform(platform);
-
-  vi.resetModules();
-  vi.doMock("os", () => ({
-    totalmem: () => hostTotalMb * BYTES_PER_MIB,
-  }));
-  vi.doMock("fs", () => ({
-    readFileSync: (path: string) => {
-      onRead?.(path);
-
-      if (throwOnFileRead) {
-        throw new Error(`/sys read should not happen: ${path}`);
-      }
-
-      if (path in readErrors) {
-        throw readErrors[path];
-      }
-
-      if (path in files) {
-        return files[path];
-      }
-
-      throw Object.assign(new Error("missing cgroup file"), { code: "ENOENT" });
-    },
-  }));
-
-  try {
-    const systemMemory = await import("./systemMemory.js");
-    systemMemory._resetCgroupLimitCacheForTests();
-    await run(systemMemory);
-  } finally {
-    vi.doUnmock("fs");
-    vi.doUnmock("os");
-    vi.resetModules();
-    restorePlatform();
-  }
-}
-
-beforeEach(() => {
-  _resetCgroupLimitCacheForTests();
-});
-
-afterEach(() => {
-  _resetCgroupLimitCacheForTests();
-  vi.restoreAllMocks();
-});
-
-describe("isLowMemorySystem", () => {
-  it("treats sub-threshold RAM as low-memory", () => {
-    expect(isLowMemorySystem(4096)).toBe(true);
-    expect(isLowMemorySystem(6000)).toBe(true);
-    expect(isLowMemorySystem(7600)).toBe(true);
-  });
-
-  it("includes machines reporting exactly the threshold (8 GB boundary)", () => {
-    // Real "8 GB" hosts report at/just under 8192 MiB after firmware/iGPU
-    // reservations — the inclusive bound is the whole point (issue #1219).
-    expect(isLowMemorySystem(LOW_MEMORY_TOTAL_MB_THRESHOLD)).toBe(true);
-    expect(isLowMemorySystem(8192)).toBe(true);
-  });
-
-  it("treats above-threshold RAM as normal", () => {
-    expect(isLowMemorySystem(8193)).toBe(false);
-    expect(isLowMemorySystem(16384)).toBe(false);
-    expect(isLowMemorySystem(65536)).toBe(false);
-  });
-
-  it("treats a 4 GiB cgroup v2 limit on a 32 GiB host as low-memory", async () => {
-    await withSystemMemoryMocks(
-      {
-        files: {
-          [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(4096);
-        expect(isLowMemorySystem()).toBe(true);
-      },
-    );
-  });
-});
-
-describe("parseCgroupLimitMb", () => {
-  it("parses cgroup v2 numeric limits", () => {
-    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, null)).toBe(4096);
-  });
-
-  it('ignores cgroup v2 "max" limits', () => {
-    expect(parseCgroupLimitMb("max", null)).toBeNull();
-  });
-
-  it("parses cgroup v1 numeric limits and ignores no-limit sentinels", () => {
-    expect(parseCgroupLimitMb(null, `${6144 * BYTES_PER_MIB}`)).toBe(6144);
-    expect(parseCgroupLimitMb(null, "9223372036854771712")).toBeNull();
-  });
-
-  it("ignores absent and malformed limits", () => {
-    expect(parseCgroupLimitMb(null, null)).toBeNull();
-
-    for (const content of ["", "garbage", "-1", "0"]) {
-      expect(parseCgroupLimitMb(content, null)).toBeNull();
-      expect(parseCgroupLimitMb(null, content)).toBeNull();
-    }
-  });
-
-  it("uses cgroup v2 when both v2 and v1 contents are present", () => {
-    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, `${2048 * BYTES_PER_MIB}`)).toBe(4096);
-  });
-});
-
-describe("getSystemTotalMb", () => {
-  it("caches cgroup probes until the test reset hook clears the cache", async () => {
-    const readCalls: string[] = [];
-    const files = {
-      [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
-    };
-
-    await withSystemMemoryMocks(
-      {
-        files,
-        onRead: (path) => readCalls.push(path),
-      },
-      ({ _resetCgroupLimitCacheForTests, getSystemTotalMb }) => {
-        expect(getSystemTotalMb()).toBe(4096);
-        expect(getSystemTotalMb()).toBe(4096);
-        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH]);
-
-        files[CGROUP_V2_MEMORY_MAX_PATH] = `${2048 * BYTES_PER_MIB}`;
-        _resetCgroupLimitCacheForTests();
-
-        expect(getSystemTotalMb()).toBe(2048);
-        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH, CGROUP_V2_MEMORY_MAX_PATH]);
-      },
-    );
-  });
-
-  it('uses the host total when cgroup v2 reports "max"', async () => {
-    await withSystemMemoryMocks(
-      {
-        files: {
-          [CGROUP_V2_MEMORY_MAX_PATH]: "max",
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(isLowMemorySystem()).toBe(false);
-      },
-    );
-  });
-
-  it("honors cgroup v1 numeric limits when cgroup v2 is absent", async () => {
-    await withSystemMemoryMocks(
-      {
-        files: {
-          [CGROUP_V1_MEMORY_LIMIT_PATH]: `${6144 * BYTES_PER_MIB}`,
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(6144);
-        expect(isLowMemorySystem()).toBe(true);
-      },
-    );
-  });
-
-  it("uses the host total when cgroup v1 reports a no-limit sentinel", async () => {
-    await withSystemMemoryMocks(
-      {
-        files: {
-          [CGROUP_V1_MEMORY_LIMIT_PATH]: "9223372036854771712",
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(isLowMemorySystem()).toBe(false);
-      },
-    );
-  });
-
-  it("uses the host total when cgroup files are absent", async () => {
-    await withSystemMemoryMocks({}, ({ getSystemTotalMb, isLowMemorySystem }) => {
-      expect(getSystemTotalMb()).toBe(32768);
-      expect(isLowMemorySystem()).toBe(false);
-    });
-  });
-
-  it("warns once and uses the host total when a cgroup file is unreadable", async () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    await withSystemMemoryMocks(
-      {
-        readErrors: {
-          [CGROUP_V2_MEMORY_MAX_PATH]: Object.assign(new Error("permission denied"), {
-            code: "EACCES",
-          }),
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(isLowMemorySystem()).toBe(false);
-        expect(warn).toHaveBeenCalledTimes(1);
-        expect(warn.mock.calls[0]?.[0]).toContain(
-          "[SystemMemory] Unable to read cgroup memory limit",
-        );
-        expect(warn.mock.calls[0]?.[0]).toContain("EACCES");
-      },
-    );
-  });
-
-  it("stays silent when cgroup files are absent", async () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    await withSystemMemoryMocks({}, ({ getSystemTotalMb }) => {
-      expect(getSystemTotalMb()).toBe(32768);
-      expect(getSystemTotalMb()).toBe(32768);
-      expect(warn).not.toHaveBeenCalled();
-    });
-  });
-
-  it.each(["", "garbage", "-1", "0"])(
-    "uses the host total for malformed cgroup v2 content %j",
-    async (content) => {
-      await withSystemMemoryMocks(
-        {
-          files: {
-            [CGROUP_V2_MEMORY_MAX_PATH]: content,
-          },
-        },
-        ({ getSystemTotalMb, isLowMemorySystem }) => {
-          expect(getSystemTotalMb()).toBe(32768);
-          expect(isLowMemorySystem()).toBe(false);
-        },
-      );
-    },
-  );
-
-  it.each(["", "garbage", "-1", "0"])(
-    "uses the host total for malformed cgroup v1 content %j",
-    async (content) => {
-      await withSystemMemoryMocks(
-        {
-          files: {
-            [CGROUP_V1_MEMORY_LIMIT_PATH]: content,
-          },
-        },
-        ({ getSystemTotalMb, isLowMemorySystem }) => {
-          expect(getSystemTotalMb()).toBe(32768);
-          expect(isLowMemorySystem()).toBe(false);
-        },
-      );
-    },
-  );
-
-  it("uses the host total when a cgroup limit is larger than host RAM", async () => {
-    await withSystemMemoryMocks(
-      {
-        files: {
-          [CGROUP_V2_MEMORY_MAX_PATH]: `${65536 * BYTES_PER_MIB}`,
-        },
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(isLowMemorySystem()).toBe(false);
-      },
-    );
-  });
-
-  it("does not read cgroup files on non-Linux platforms", async () => {
-    await withSystemMemoryMocks(
-      {
-        platform: "darwin",
-        throwOnFileRead: true,
-      },
-      ({ getSystemTotalMb, isLowMemorySystem }) => {
-        expect(getSystemTotalMb()).toBe(32768);
-        expect(isLowMemorySystem()).toBe(false);
-      },
-    );
-  });
-});

package/src/services/systemMemory.ts

@@ -1,180 +0,0 @@
-/**
- * System-memory probing for memory-adaptive render behaviour.
- *
- * The render pipeline tunes itself to the host's RAM in several places —
- * frame-cache sizes (`config.ts`), Chrome heap + GPU budget flags
- * (`browserManager.ts`), and worker count (`parallelCoordinator.ts`).
- * They all need the same "how much memory does this box have" reading, so
- * it lives here once instead of being re-derived inline.
- */
-
-import { readFileSync } from "fs";
-import { totalmem } from "os";
-
-const BYTES_PER_MIB = 1024 * 1024;
-const BYTES_PER_MIB_BIGINT = BigInt(BYTES_PER_MIB);
-// These are the paths as seen from INSIDE a container, where the runtime
-// mounts the container's own cgroup at the namespace root — the case this
-// probe exists for. They are deliberately not resolved via /proc/self/cgroup:
-// on a bare host under systemd the process's real limit may live in a nested
-// slice (e.g. /sys/fs/cgroup/user.slice/.../memory.max) that these root paths
-// don't see, and that's acceptable — bare hosts are covered by total-RAM
-// detection, and chasing nested slices adds fragility for no container gain.
-const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
-const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
-// Kernel no-limit sentinel is page-rounded 2^63-1 (~9223372036854771712); >= 2^60 is implausible as a real limit.
-const CGROUP_V1_NO_LIMIT_CUTOFF_BYTES = 2n ** 60n;
-
-let _cachedCgroupLimitMb: number | null | undefined;
-let _warnedCgroupReadFailure = false;
-
-/** Parse cgroup v2/v1 memory limits from sysfs file contents into MiB. */
-export function parseCgroupLimitMb(
-  v2Content: string | null,
-  v1Content: string | null,
-): number | null {
-  if (v2Content !== null) {
-    return parseCgroupV2LimitMb(v2Content);
-  }
-
-  return parseCgroupV1LimitMb(v1Content);
-}
-
-function parseCgroupV2LimitMb(content: string): number | null {
-  const trimmed = content.trim();
-  if (trimmed === "max") {
-    return null;
-  }
-
-  return parsePositiveByteLimitMb(trimmed);
-}
-
-function parseCgroupV1LimitMb(content: string | null): number | null {
-  if (content === null) {
-    return null;
-  }
-
-  return parsePositiveByteLimitMb(content.trim(), CGROUP_V1_NO_LIMIT_CUTOFF_BYTES);
-}
-
-function parsePositiveByteLimitMb(content: string, noLimitCutoffBytes?: bigint): number | null {
-  if (!/^\d+$/.test(content)) {
-    return null;
-  }
-
-  const bytes = BigInt(content);
-  if (bytes <= 0n) {
-    return null;
-  }
-
-  if (noLimitCutoffBytes !== undefined && bytes >= noLimitCutoffBytes) {
-    return null;
-  }
-
-  return Number(bytes / BYTES_PER_MIB_BIGINT);
-}
-
-/** Test-only: reset the cached cgroup memory probe. */
-export function _resetCgroupLimitCacheForTests(): void {
-  _cachedCgroupLimitMb = undefined;
-  _warnedCgroupReadFailure = false;
-}
-
-function getCgroupLimitMb(): number | null {
-  if (_cachedCgroupLimitMb !== undefined) return _cachedCgroupLimitMb;
-
-  if (process.platform !== "linux") {
-    _cachedCgroupLimitMb = null;
-    return null;
-  }
-
-  const v2Content = readCgroupFile(CGROUP_V2_MEMORY_MAX_PATH);
-  const v1Content = v2Content === null ? readCgroupFile(CGROUP_V1_MEMORY_LIMIT_PATH) : null;
-
-  _cachedCgroupLimitMb = parseCgroupLimitMb(v2Content, v1Content);
-  if (_cachedCgroupLimitMb !== null) {
-    console.info(
-      `[SystemMemory] cgroup memory limit detected: ${_cachedCgroupLimitMb} MiB — ` +
-        `it governs memory-adaptive render behaviour instead of host RAM.`,
-    );
-  }
-  return _cachedCgroupLimitMb;
-}
-
-function readCgroupFile(path: string): string | null {
-  try {
-    return readFileSync(path, "utf8");
-  } catch (error) {
-    const code = getErrorCode(error);
-    if (code !== "ENOENT" && code !== "ENOTDIR") {
-      warnCgroupReadFailure(path, error);
-    }
-    return null;
-  }
-}
-
-function getErrorCode(error: unknown): string | undefined {
-  if (typeof error !== "object" || error === null || !("code" in error)) {
-    return undefined;
-  }
-
-  return typeof error.code === "string" ? error.code : undefined;
-}
-
-function formatCgroupReadError(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
-  const code = getErrorCode(error);
-  return code ? `${code}: ${message}` : message;
-}
-
-function warnCgroupReadFailure(path: string, error: unknown): void {
-  if (_warnedCgroupReadFailure) return;
-  _warnedCgroupReadFailure = true;
-  console.warn(
-    `[SystemMemory] Unable to read cgroup memory limit at ${path} ` +
-      `(${formatCgroupReadError(error)}); falling back to host RAM.`,
-  );
-}
-
-/** Total physical RAM in MiB. */
-export function getSystemTotalMb(): number {
-  const hostTotalMb = Math.floor(totalmem() / BYTES_PER_MIB);
-  const cgroupLimitMb = getCgroupLimitMb();
-
-  return cgroupLimitMb === null ? hostTotalMb : Math.min(hostTotalMb, cgroupLimitMb);
-}
-
-/**
- * Total-RAM ceiling (MiB) at or below which the host is treated as
- * memory-constrained. Tuned to the 8 GB laptops in
- * heygen-com/hyperframes#1218 / #1219: on those boxes the default render
- * shape (probe Chrome + a throwaway calibration Chrome + N capture
- * workers) thrashes, so the pipeline collapses to its cheapest form.
- *
- * `<=` deliberately includes machines that report exactly 8192 MiB —
- * real "8 GB" hardware reports anywhere from ~7600 to 8192 MiB once
- * firmware/integrated-GPU reservations are subtracted, and a strict `<`
- * would skip the optimisation on the very hardware that needs it.
- */
-export const LOW_MEMORY_TOTAL_MB_THRESHOLD = 8192;
-
-/**
- * True when the host should run the low-memory render profile.
- *
- * Keyed on total physical RAM, not free memory: free memory swings
- * moment to moment and is underreported on macOS, whereas total RAM is a
- * stable proxy for "how many concurrent Chrome instances can this box
- * survive". Accepts an explicit `totalMb` so callers (and tests) can pass
- * a known value instead of re-probing.
- *
- * Caveat: Linux cgroup v1/v2 memory limits are consulted when readable, so
- * Docker and serverless runtimes, including Lambda tiers with readable cgroup
- * ceilings, inherit the tighter container limit instead of the host's physical
- * RAM. Environments that hide cgroup files should set
- * `PRODUCER_LOW_MEMORY_MODE` explicitly rather than relying on auto-detection.
- * Hosts whose *effective* total RAM is genuinely <= the threshold (laptops,
- * small VMs, small Lambda tiers, small containers) are detected correctly.
- */
-export function isLowMemorySystem(totalMb: number = getSystemTotalMb()): boolean {
-  return totalMb <= LOW_MEMORY_TOTAL_MB_THRESHOLD;
-}