Skip to content

Commit cbf2a2e

Browse files
committed
feat(engine): auto-disable streaming-encode on Windows software-GPU compound
Field signal ts=1784131903 (win32/x64, CLI 0.7.58, 156s UI-heavy): stable ONLY with four flags together — --workers 1 --no-browser-gpu --low-memory-mode + PRODUCER_ENABLE_STREAMING_ENCODE=false. Since --no-browser-gpu and --low-memory-mode already imply screenshot capture, three of the four flags are structurally coupled. Auto-detect the compound at resolveConfig time and disable streaming-encode on the caller's behalf; user explicit-set (PRODUCER_ENABLE_STREAMING_ENCODE or overrides.enableStreamingEncode) always wins. Composition duration is not known at the config layer, so the wire-up passes compositionDurationSec:undefined and the helper reduces to the three-condition compound (platform + softwareGpuForced + workers=1). The 4-arg helper stays exported for downstream callers that DO know duration (e.g., renderOrchestrator) and want the >120s guard. Trade-off documented in code + PR body: false positives possible for short (~<120s) Windows software-GPU single-worker renders. Mitigation is the explicit opt-in escape hatch. Emits a single [hyperframes] log line naming the trigger + how to opt back in, so operators can tell an auto-disable apart from an explicit opt-out. Adds streamingEncodeAutoDisabledOnWin32Compound internal provenance for downstream telemetry. Stack: PR #2 of 9 (base via/protocol-timeout-discoverability). Signed-off-by: Via
1 parent 6944a1c commit cbf2a2e

2 files changed

Lines changed: 322 additions & 0 deletions

File tree

‎packages/engine/src/config.test.ts‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
scaleProtocolTimeoutForComposition,
88
shouldClampToScreenshotForConcreteGpu,
99
applyConcreteGpuScreenshotClamp,
10+
shouldAutoDisableStreamingEncodeOnWin32Compound,
1011
} from "./config.js";
1112
import type { EngineConfig } from "./config.js";
1213
import { isLowMemorySystem } from "./services/systemMemory.js";
@@ -518,6 +519,216 @@ describe("resolveConfig", () => {
518519
});
519520
});
520521

522+
describe("shouldAutoDisableStreamingEncodeOnWin32Compound (helper)", () => {
523+
// Baseline: field-signal compound — win32 + software-GPU forced + workers=1,
524+
// duration unknown, user hasn't touched the env / overrides.
525+
const compound = {
526+
platform: "win32" as NodeJS.Platform,
527+
softwareGpuForced: true,
528+
workers: 1,
529+
compositionDurationSec: undefined as number | undefined,
530+
userExplicitlySet: false,
531+
};
532+
533+
it("triggers on the field-signal compound (win32 + software-GPU + workers=1)", () => {
534+
expect(shouldAutoDisableStreamingEncodeOnWin32Compound(compound)).toBe(true);
535+
});
536+
537+
it("does NOT trigger on linux or darwin (platform gate)", () => {
538+
expect(
539+
shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, platform: "linux" }),
540+
).toBe(false);
541+
expect(
542+
shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, platform: "darwin" }),
543+
).toBe(false);
544+
});
545+
546+
it("does NOT trigger without software-GPU forced (bypass on hardware paths)", () => {
547+
expect(
548+
shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, softwareGpuForced: false }),
549+
).toBe(false);
550+
});
551+
552+
it("does NOT trigger with parallel workers (workers > 1 has a different failure surface)", () => {
553+
expect(shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, workers: 2 })).toBe(
554+
false,
555+
);
556+
expect(shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, workers: 4 })).toBe(
557+
false,
558+
);
559+
});
560+
561+
it("does NOT trigger when the user explicitly set enableStreamingEncode (escape hatch)", () => {
562+
expect(
563+
shouldAutoDisableStreamingEncodeOnWin32Compound({ ...compound, userExplicitlySet: true }),
564+
).toBe(false);
565+
});
566+
567+
it("does NOT trigger for short (<=120s) compositions when duration is known", () => {
568+
// 120s boundary is off (edge)
569+
expect(
570+
shouldAutoDisableStreamingEncodeOnWin32Compound({
571+
...compound,
572+
compositionDurationSec: 120,
573+
}),
574+
).toBe(false);
575+
// 60s — clearly short, off
576+
expect(
577+
shouldAutoDisableStreamingEncodeOnWin32Compound({
578+
...compound,
579+
compositionDurationSec: 60,
580+
}),
581+
).toBe(false);
582+
});
583+
584+
it("triggers when duration is known and exceeds 120s (heavy Windows composition)", () => {
585+
// 121s — just past the boundary, on
586+
expect(
587+
shouldAutoDisableStreamingEncodeOnWin32Compound({
588+
...compound,
589+
compositionDurationSec: 121,
590+
}),
591+
).toBe(true);
592+
// 156s — matches the field signal, on
593+
expect(
594+
shouldAutoDisableStreamingEncodeOnWin32Compound({
595+
...compound,
596+
compositionDurationSec: 156,
597+
}),
598+
).toBe(true);
599+
});
600+
601+
it("triggers when duration is undefined (config-layer wire-up reduces to 3-cond)", () => {
602+
// resolveConfig can't see composition duration at config time; the
603+
// three-condition compound is conservative on its own.
604+
expect(
605+
shouldAutoDisableStreamingEncodeOnWin32Compound({
606+
...compound,
607+
compositionDurationSec: undefined,
608+
}),
609+
).toBe(true);
610+
});
611+
});
612+
613+
describe("enableStreamingEncode (Windows compound auto-disable wire-up)", () => {
614+
const originalPlatform = process.platform;
615+
616+
function setPlatform(platform: NodeJS.Platform) {
617+
Object.defineProperty(process, "platform", { value: platform, configurable: true });
618+
}
619+
620+
afterEach(() => {
621+
Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
622+
});
623+
624+
it("auto-disables on win32 + software-GPU + workers=1 + no user opt-in", () => {
625+
setPlatform("win32");
626+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
627+
setEnv("PRODUCER_MAX_WORKERS", "1");
628+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
629+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
630+
631+
const config = resolveConfig();
632+
expect(config.enableStreamingEncode).toBe(false);
633+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true);
634+
});
635+
636+
it("leaves streaming-encode on when platform is linux", () => {
637+
setPlatform("linux");
638+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
639+
setEnv("PRODUCER_MAX_WORKERS", "1");
640+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
641+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
642+
643+
const config = resolveConfig();
644+
expect(config.enableStreamingEncode).toBe(true);
645+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined();
646+
});
647+
648+
it("leaves streaming-encode on when workers > 1", () => {
649+
setPlatform("win32");
650+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
651+
setEnv("PRODUCER_MAX_WORKERS", "4");
652+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
653+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
654+
655+
const config = resolveConfig();
656+
expect(config.enableStreamingEncode).toBe(true);
657+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined();
658+
});
659+
660+
it("respects explicit env opt-in (PRODUCER_ENABLE_STREAMING_ENCODE=true) on the compound", () => {
661+
setPlatform("win32");
662+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
663+
setEnv("PRODUCER_MAX_WORKERS", "1");
664+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
665+
setEnv("PRODUCER_ENABLE_STREAMING_ENCODE", "true");
666+
667+
const config = resolveConfig();
668+
expect(config.enableStreamingEncode).toBe(true);
669+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined();
670+
});
671+
672+
it("respects programmatic override enableStreamingEncode=true on the compound", () => {
673+
setPlatform("win32");
674+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
675+
setEnv("PRODUCER_MAX_WORKERS", "1");
676+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
677+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
678+
679+
const config = resolveConfig({ enableStreamingEncode: true });
680+
expect(config.enableStreamingEncode).toBe(true);
681+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined();
682+
});
683+
684+
it("triggers via disableGpu on win32 + workers=1 (browserGpuMode may still be 'auto')", () => {
685+
// --disable-gpu path: browserGpuMode may not be literal "software" but
686+
// Chrome is still routed to CPU raster. Field-signal compound applies.
687+
setPlatform("win32");
688+
unsetEnv("PRODUCER_BROWSER_GPU_MODE");
689+
setEnv("PRODUCER_DISABLE_GPU", "true");
690+
setEnv("PRODUCER_MAX_WORKERS", "1");
691+
unsetEnv("PRODUCER_LOW_MEMORY_MODE");
692+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
693+
694+
const config = resolveConfig();
695+
expect(config.enableStreamingEncode).toBe(false);
696+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true);
697+
});
698+
699+
it("triggers via lowMemoryMode alone on win32 + workers=1 (screenshot capture implied)", () => {
700+
// --low-memory-mode implies screenshot capture. Compound applies even
701+
// if browserGpuMode is not literal "software" (defense-in-depth: matches
702+
// the OR semantics in `softwareGpuForced`).
703+
setPlatform("win32");
704+
unsetEnv("PRODUCER_BROWSER_GPU_MODE");
705+
unsetEnv("PRODUCER_DISABLE_GPU");
706+
setEnv("PRODUCER_MAX_WORKERS", "1");
707+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
708+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
709+
710+
const config = resolveConfig();
711+
expect(config.enableStreamingEncode).toBe(false);
712+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true);
713+
});
714+
715+
it("does not trigger when concurrency is 'auto' (workers not explicitly pinned)", () => {
716+
// Config-layer sees `concurrency === "auto"`, not a number — the
717+
// helper's numeric workers check treats NaN as "unknown, don't trigger".
718+
// Downstream workers may still resolve to 1 via lowMemoryMode, but the
719+
// config-time clamp is deliberately conservative.
720+
setPlatform("win32");
721+
setEnv("PRODUCER_BROWSER_GPU_MODE", "software");
722+
unsetEnv("PRODUCER_MAX_WORKERS");
723+
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
724+
unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE");
725+
726+
const config = resolveConfig();
727+
expect(config.enableStreamingEncode).toBe(true);
728+
expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined();
729+
});
730+
});
731+
521732
describe("lowMemoryMode", () => {
522733
it("forces on for truthy PRODUCER_LOW_MEMORY_MODE values", () => {
523734
setEnv("PRODUCER_LOW_MEMORY_MODE", "true");

‎packages/engine/src/config.ts‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,15 @@ export interface EngineConfig {
150150
enableChunkedEncode: boolean;
151151
chunkSizeFrames: number;
152152
enableStreamingEncode: boolean;
153+
/**
154+
* INTERNAL. Set by `resolveConfig` when the Windows software-GPU compound
155+
* heuristic (`shouldAutoDisableStreamingEncodeOnWin32Compound`) turned
156+
* `enableStreamingEncode` off on the caller's behalf. Not intended to be
157+
* set by callers; surfaces the auto-decision for downstream observability
158+
* (log lines, telemetry) so operators can tell an auto-disable apart from
159+
* an explicit user opt-out.
160+
*/
161+
streamingEncodeAutoDisabledOnWin32Compound?: boolean;
153162
/**
154163
* Max composition duration eligible for streaming encode (seconds).
155164
* Mirrors GSAP rendering's 4-minute streaming guard: production has seen
@@ -355,6 +364,62 @@ export function scaleProtocolTimeoutForComposition(
355364
return Math.min(ceiling, Math.max(baseTimeoutMs, scaled));
356365
}
357366

367+
/**
368+
* Auto-disable `enableStreamingEncode` on Windows software-GPU compound.
369+
*
370+
* Field signal (`ts=1784131903`, win32/x64, CLI 0.7.58, 156s UI-heavy
371+
* composition): the render was stable ONLY with FOUR flags together —
372+
* `--workers 1 --no-browser-gpu --low-memory-mode` + explicit
373+
* `PRODUCER_ENABLE_STREAMING_ENCODE=false`. Every recent Windows-related
374+
* fix (#2359, #2245, #2298, #2331) already shipped in 0.7.58; the residual
375+
* failure is screenshot streaming-encode via CDP `Page.captureScreenshot`
376+
* on Windows even after software fallback. Since `--low-memory-mode` and
377+
* `--no-browser-gpu` already imply screenshot capture, three of the four
378+
* flags are structurally coupled — auto-detect the compound and disable
379+
* streaming-encode automatically so callers don't have to memorize the
380+
* four-flag combination.
381+
*
382+
* Conservative gates (all must hold):
383+
* 1. `platform === "win32"` — the failure is Windows-specific to CDP's
384+
* screenshot streaming path.
385+
* 2. `softwareGpuForced` — the render is already on the SwiftShader /
386+
* forced-screenshot path (from `--no-browser-gpu`, `disableGpu`, or
387+
* `--low-memory-mode` implying screenshot capture).
388+
* 3. `workers === 1` — the field signal reproduces on single-worker
389+
* captures; parallel workers have a different failure surface
390+
* (missing media frames) already handled by the worker-count route.
391+
* 4. Composition duration >120s WHEN KNOWN. When unknown at the config
392+
* layer (composition duration is parsed downstream), the guard
393+
* reduces to the three-condition compound. Trade-off documented in
394+
* the PR body: false positives possible for short (~<120s) Windows
395+
* software-GPU single-worker renders. Mitigation: the explicit
396+
* opt-in escape hatch (`PRODUCER_ENABLE_STREAMING_ENCODE=true` or
397+
* `overrides.enableStreamingEncode !== undefined`) always wins.
398+
*
399+
* Pure function; exported for tests.
400+
*/
401+
export function shouldAutoDisableStreamingEncodeOnWin32Compound(opts: {
402+
platform: NodeJS.Platform;
403+
softwareGpuForced: boolean;
404+
workers: number;
405+
compositionDurationSec: number | undefined;
406+
userExplicitlySet: boolean;
407+
}): boolean {
408+
if (opts.userExplicitlySet) return false;
409+
if (opts.platform !== "win32") return false;
410+
if (!opts.softwareGpuForced) return false;
411+
// Strict equality: NaN (concurrency: "auto") and fractional / zero worker
412+
// counts do NOT match. The field-signal compound is `--workers 1`.
413+
if (opts.workers !== 1) return false;
414+
// Duration boundary: when known, only auto-disable if >120s (avoid
415+
// over-triggering on short renders). When unknown, skip this check —
416+
// the three conditions above are already conservative on their own.
417+
if (opts.compositionDurationSec !== undefined && opts.compositionDurationSec <= 120) {
418+
return false;
419+
}
420+
return true;
421+
}
422+
358423
function memoryAdaptiveCacheLimit(): number {
359424
const total = getSystemTotalMb();
360425
if (total < 4096) return 32;
@@ -608,6 +673,52 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
608673
merged.forceScreenshot = true;
609674
}
610675

676+
// Windows software-GPU compound auto-disable for streaming-encode.
677+
//
678+
// Field signal ts=1784131903 (win32/x64, CLI 0.7.58, 156s UI-heavy):
679+
// stable ONLY with FOUR flags — `--workers 1 --no-browser-gpu
680+
// --low-memory-mode` + `PRODUCER_ENABLE_STREAMING_ENCODE=false`. Since
681+
// `--no-browser-gpu` and `--low-memory-mode` already imply screenshot
682+
// capture, three of the four flags are structurally coupled: auto-detect
683+
// the compound and disable streaming-encode on the caller's behalf.
684+
//
685+
// Explicit user intent wins: if `PRODUCER_ENABLE_STREAMING_ENCODE` env
686+
// is set to any value OR the caller passed `overrides.enableStreamingEncode`,
687+
// this clamp is a no-op (the user's explicit choice — including
688+
// `PRODUCER_ENABLE_STREAMING_ENCODE=true` — is preserved).
689+
//
690+
// Composition duration is not known at the config-resolution layer
691+
// (the composition is parsed downstream of `resolveConfig`), so this
692+
// wire-up passes `compositionDurationSec: undefined` and the helper
693+
// reduces to the three-condition compound. Trade-off documented in the
694+
// helper's JSDoc and the PR body: false positives possible for short
695+
// Windows software-GPU single-worker renders; the explicit opt-in
696+
// escape hatch is the mitigation.
697+
const streamingEncodeUserExplicitlySet =
698+
env("PRODUCER_ENABLE_STREAMING_ENCODE") !== undefined ||
699+
overrides?.enableStreamingEncode !== undefined;
700+
const softwareGpuForced =
701+
merged.browserGpuMode === "software" || merged.disableGpu || merged.lowMemoryMode;
702+
const resolvedWorkers = typeof merged.concurrency === "number" ? merged.concurrency : NaN;
703+
if (
704+
merged.enableStreamingEncode &&
705+
shouldAutoDisableStreamingEncodeOnWin32Compound({
706+
platform: process.platform,
707+
softwareGpuForced,
708+
workers: resolvedWorkers,
709+
compositionDurationSec: undefined,
710+
userExplicitlySet: streamingEncodeUserExplicitlySet,
711+
})
712+
) {
713+
merged.enableStreamingEncode = false;
714+
merged.streamingEncodeAutoDisabledOnWin32Compound = true;
715+
console.error(
716+
"[hyperframes] Windows compound-workaround auto-detected — disabling streaming-encode " +
717+
"(platform=win32, software-GPU forced, workers=1). Field signal ts=1784131903. " +
718+
"Override: PRODUCER_ENABLE_STREAMING_ENCODE=true.",
719+
);
720+
}
721+
611722
// drawElement capture and page-side shader compositing are mutually
612723
// incompatible capture strategies (drawElement reads paint records directly
613724
// and bypasses the page-side prepare→composite→resolve protocol). When

0 commit comments

Comments
 (0)