Skip to content

Commit b9aae16

Browse files
jrusso1020Anton Sidorov aka anticodeguy
andauthored
fix(producer): try Windows junctions before copying cached frames (#3740)
Follow up Anton Sidorov’s junction staging contribution in #2314 on current main. Co-authored-by: Anton Sidorov aka anticodeguy <[email protected]>
1 parent 30d6f43 commit b9aae16

6 files changed

Lines changed: 223 additions & 42 deletions

File tree

‎.github/workflows/windows-render.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -484,6 +484,11 @@ jobs:
484484
shell: pwsh
485485
run: bunx vitest run packages/producer/src/services/hyperframeLint.file-race.test.ts --maxWorkers=2
486486

487+
- name: Verify Windows frame staging
488+
if: matrix.lane == 'studio-engine-cli'
489+
shell: pwsh
490+
run: bunx vitest run packages/producer/src/services/windowsFrameStaging.test.ts --maxWorkers=2
491+
487492
- name: Verify catalog source reads on Windows
488493
if: matrix.lane == 'studio-engine-cli'
489494
shell: pwsh

‎packages/producer/src/services/render/shared.ts‎

Lines changed: 35 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -306,7 +306,7 @@ type MaterializePathModule = {
306306
type MaterializeFileSystem = {
307307
existsSync: (path: string) => boolean;
308308
mkdirSync: (path: string, options: { recursive: true }) => unknown;
309-
symlinkSync: (target: string, path: string) => unknown;
309+
symlinkSync: (target: string, path: string, type?: "dir" | "junction") => unknown;
310310
cpSync: (src: string, dest: string, options: { recursive: true }) => unknown;
311311
// Optional: only the stale-entry (EEXIST) recovery path calls it, and the
312312
// default fileSystem always supplies it. Test doubles that never trigger
@@ -412,31 +412,55 @@ export function createMemorySampler(intervalMs: number = 250): MemorySampler {
412412
* external callers should use `executeRenderJob` instead.
413413
*/
414414
// Stage one video's extracted-frame dir into the compiled dir. Default is a
415-
// single symlink (cheap; the in-process renderer); `materializeSymlinks` copies
416-
// instead (distributed plan() needs a self-contained dir). On Windows without
417-
// Developer Mode/Administrator symlink creation is rejected with EPERM/EACCES,
418-
// which failed high/standard renders — degrade to a copy there rather than
419-
// throwing. Non-permission errors still propagate so real failures aren't hidden.
415+
// directory link (cheap; the in-process renderer); `materializeSymlinks` copies
416+
// instead (distributed plan() needs a self-contained dir). On Windows, try a
417+
// junction if symlink privileges are unavailable before falling back to a copy.
420418
// One-time guard for the symlink→copy fallback notice below.
421419
let warnedSymlinkFallback = false;
422420

421+
// Junctions avoid Windows symlink privileges. POSIX keeps its copy fallback.
422+
function tryWindowsFrameJunction(
423+
fileSystem: MaterializeFileSystem,
424+
src: string,
425+
dest: string,
426+
): boolean {
427+
if (process.platform !== "win32") return false;
428+
try {
429+
fileSystem.symlinkSync(src, dest, "junction");
430+
return true;
431+
} catch (error) {
432+
const code =
433+
error instanceof Error && "code" in error && typeof error.code === "string"
434+
? error.code
435+
: undefined;
436+
if (
437+
["EPERM", "EACCES", "UNKNOWN", "EINVAL", "ENOSYS", "EOPNOTSUPP", "ENOTSUP"].includes(
438+
code ?? "",
439+
)
440+
) {
441+
return false;
442+
}
443+
throw error;
444+
}
445+
}
446+
423447
// Create the symlink, degrading to a copy on Windows' no-symlink-privilege
424-
// errors (EPERM/EACCES, plus UNKNOWN — some Windows builds surface a symlink
425-
// privilege denial as an UNKNOWN-coded error rather than EPERM). Non-permission
426-
// errors propagate.
448+
// errors (EPERM/EACCES, plus UNKNOWN), trying a Windows junction first.
449+
// Other symlink errors and non-capability junction errors propagate.
427450
function linkOrCopyFrameDir(fileSystem: MaterializeFileSystem, src: string, dest: string): void {
428451
try {
429-
fileSystem.symlinkSync(src, dest);
452+
fileSystem.symlinkSync(src, dest, "dir");
430453
} catch (err) {
431454
const code = (err as NodeJS.ErrnoException | undefined)?.code;
432455
if (code !== "EPERM" && code !== "EACCES" && code !== "UNKNOWN") throw err;
456+
if (tryWindowsFrameJunction(fileSystem, src, dest)) return;
433457
// Copying is measurably slower than symlinking, so surface the degrade once
434458
// — it explains a render that suddenly got heavier and saves a support
435459
// round-trip diagnosing slow frame staging on Windows.
436460
if (!warnedSymlinkFallback) {
437461
warnedSymlinkFallback = true;
438462
defaultLogger.info(
439-
`[Render] Symlinking extracted frames was rejected (${code}); copying them into the compiled dir instead. Expected on Windows without Developer Mode/Administrator.`,
463+
`[Render] Linking extracted frames was rejected (${code}); copying them into the compiled dir instead.`,
440464
);
441465
}
442466
fileSystem.cpSync(src, dest, { recursive: true });

‎packages/producer/src/services/render/stages/extractVideosStage.test.ts‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ import {
1515
buildHdrProbeStageError,
1616
resolveVideoExtractionPolicy,
1717
safeVideoExtractionSourceLogMetadata,
18-
shouldCopyExtractedFrames,
1918
VideoExtractionStageError,
2019
} from "./extractVideosStage.js";
2120
import { EncoderInterruptedError } from "../encoderInterruption.js";
@@ -210,17 +209,6 @@ describe("HDR probe src resolution (PRINFRA-349)", () => {
210209
});
211210
});
212211

213-
describe("shouldCopyExtractedFrames", () => {
214-
it("copies frames on Windows (symlinkSync throws EPERM without Developer Mode)", () => {
215-
expect(shouldCopyExtractedFrames("win32")).toBe(true);
216-
});
217-
218-
it("symlinks on macOS and Linux (cheaper, symlinks allowed)", () => {
219-
expect(shouldCopyExtractedFrames("darwin")).toBe(false);
220-
expect(shouldCopyExtractedFrames("linux")).toBe(false);
221-
});
222-
});
223-
224212
describe("resolveVideoExtractionPolicy", () => {
225213
it("enforces extraction failures by default (#3372)", () => {
226214
expect(resolveVideoExtractionPolicy({})).toEqual({

‎packages/producer/src/services/render/stages/extractVideosStage.ts‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -112,18 +112,6 @@ export interface ExtractVideosStageResult {
112112
failureToEnforce: VideoExtractionStageError | null;
113113
}
114114

115-
/**
116-
* Whether the extract stage should COPY frames into the compiled dir instead of
117-
* symlinking them. Windows without Developer Mode / Administrator can't create
118-
* symlinks (`symlinkSync` throws EPERM), which failed local video renders; copy
119-
* there instead. Elsewhere symlinking is cheaper, so keep it. (The distributed
120-
* `plan()` path already forces copying for a different reason — a self-contained
121-
* planDir — by passing `materializeSymlinks: true` explicitly.)
122-
*/
123-
export function shouldCopyExtractedFrames(platform: NodeJS.Platform): boolean {
124-
return platform === "win32";
125-
}
126-
127115
export type VideoExtractionStageErrorCode = "VIDEO_SOURCE_UNRENDERABLE" | "VIDEO_EXTRACTION_FAILED";
128116

129117
export interface VideoExtractionStageFailureSummary {

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -161,10 +161,7 @@ import {
161161
import { runCompileStage } from "./render/stages/compileStage.js";
162162
import { runProbeStage } from "./render/stages/probeStage.js";
163163
import { validateRenderDuration } from "./render/planValidation.js";
164-
import {
165-
runExtractVideosStage,
166-
shouldCopyExtractedFrames,
167-
} from "./render/stages/extractVideosStage.js";
164+
import { runExtractVideosStage } from "./render/stages/extractVideosStage.js";
168165
import { runAudioStage } from "./render/stages/audioStage.js";
169166
import { runCaptureStage } from "./render/stages/captureStage.js";
170167
import {
@@ -2482,9 +2479,8 @@ async function executeRenderPipeline(input: {
24822479
composition,
24832480
abortSignal: executionSignal,
24842481
assertNotAborted,
2485-
// Copy (don't symlink) extracted frames on Windows — symlinkSync throws
2486-
// EPERM there without Developer Mode/admin, which failed local renders.
2487-
materializeSymlinks: shouldCopyExtractedFrames(process.platform),
2482+
// Local staging can use links; distributed plan() alone requires real copies.
2483+
materializeSymlinks: false,
24882484
}),
24892485
);
24902486
const {
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2+
import {
3+
cpSync,
4+
existsSync,
5+
lstatSync,
6+
mkdirSync,
7+
mkdtempSync,
8+
readFileSync,
9+
rmSync,
10+
symlinkSync,
11+
writeFileSync,
12+
} from "node:fs";
13+
import { tmpdir } from "node:os";
14+
import { join } from "node:path";
15+
import { createRenderJob, executeRenderJob } from "./renderOrchestrator.js";
16+
import { materializeExtractedFramesForCompiledDir } from "./render/shared.js";
17+
18+
const staging = vi.hoisted((): { requestedCopy?: boolean } => ({}));
19+
vi.mock("@hyperframes/engine", async (importOriginal) => ({
20+
...(await importOriginal<typeof import("@hyperframes/engine")>()),
21+
assertConfiguredFfmpegBinariesExist: () => {},
22+
}));
23+
vi.mock("./render/stages/compileStage.js", () => ({
24+
runCompileStage: async () => ({
25+
compiled: { html: "<div></div>" },
26+
composition: { width: 320, height: 180, duration: 1, videos: [], images: [], audios: [] },
27+
deviceScaleFactor: 1,
28+
outputWidth: 320,
29+
outputHeight: 180,
30+
compileOnlyMs: 0,
31+
forceScreenshot: true,
32+
}),
33+
}));
34+
vi.mock("./render/stages/probeStage.js", () => ({
35+
runProbeStage: async ({ compiled }: { compiled: object }) => ({
36+
compiled,
37+
fileServer: null,
38+
probeSession: null,
39+
lastBrowserConsole: [],
40+
duration: 1,
41+
totalFrames: 30,
42+
browserProbeMs: 0,
43+
}),
44+
}));
45+
vi.mock("./render/stages/extractVideosStage.js", async (importOriginal) => ({
46+
...(await importOriginal<typeof import("./render/stages/extractVideosStage.js")>()),
47+
runExtractVideosStage: async ({ materializeSymlinks }: { materializeSymlinks?: boolean }) => {
48+
staging.requestedCopy = materializeSymlinks;
49+
throw new Error("staging reached");
50+
},
51+
}));
52+
53+
const dirs: string[] = [];
54+
function fixture() {
55+
const root = mkdtempSync(join(tmpdir(), "hf-windows-staging-"));
56+
dirs.push(root);
57+
const source = join(root, "cache");
58+
mkdirSync(source);
59+
const frame = join(source, "frame_000001.jpg");
60+
writeFileSync(frame, "frame bytes");
61+
return {
62+
root,
63+
source,
64+
compiled: join(root, "compiled"),
65+
extracted: { videoId: "clip", outputDir: source, framePaths: new Map([[0, frame]]) },
66+
};
67+
}
68+
afterEach(() => {
69+
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
70+
});
71+
72+
it("the actual local Windows renderer does not request eager frame copies", async () => {
73+
const { root } = fixture();
74+
writeFileSync(join(root, "index.html"), "<div></div>");
75+
const job = createRenderJob({
76+
fps: 30,
77+
quality: "standard",
78+
hdrMode: "force-sdr",
79+
logger: { info() {}, warn() {}, error() {}, debug() {} },
80+
});
81+
const platform = Object.getOwnPropertyDescriptor(process, "platform")!;
82+
try {
83+
Object.defineProperty(process, "platform", { value: "win32" });
84+
await expect(executeRenderJob(job, root, join(root, "output.mp4"))).rejects.toThrow(
85+
"staging reached",
86+
);
87+
expect(staging.requestedCopy).not.toBe(true);
88+
} finally {
89+
Object.defineProperty(process, "platform", platform);
90+
}
91+
});
92+
93+
describe.skipIf(process.platform !== "win32")("real Windows frame staging", () => {
94+
it("uses a real junction after a symlink privilege denial without copying frames", () => {
95+
const { source, compiled, extracted } = fixture();
96+
const attempts: Array<string | undefined> = [];
97+
materializeExtractedFramesForCompiledDir([extracted], compiled, {
98+
fileSystem: {
99+
existsSync,
100+
mkdirSync,
101+
rmSync,
102+
symlinkSync: (target, path, type) => {
103+
attempts.push(type);
104+
if (attempts.length === 1)
105+
throw Object.assign(new Error("symlink denied"), { code: "EPERM" });
106+
symlinkSync(target, path, type);
107+
},
108+
cpSync: () => {
109+
throw new Error("junction-capable local staging must not copy");
110+
},
111+
},
112+
});
113+
expect(attempts).toEqual(["dir", "junction"]);
114+
expect(lstatSync(extracted.outputDir).isSymbolicLink()).toBe(true);
115+
writeFileSync(join(source, "frame_000001.jpg"), "updated cache bytes");
116+
expect(readFileSync(extracted.framePaths.get(0)!, "utf8")).toBe("updated cache bytes");
117+
rmSync(extracted.outputDir, { recursive: true });
118+
expect(readFileSync(join(source, "frame_000001.jpg"), "utf8")).toBe("updated cache bytes");
119+
});
120+
});
121+
122+
it("distributed materialization stays physically self-contained after cache removal", () => {
123+
const { source, compiled, extracted } = fixture();
124+
materializeExtractedFramesForCompiledDir([extracted], compiled, { materializeSymlinks: true });
125+
expect(lstatSync(extracted.outputDir).isSymbolicLink()).toBe(false);
126+
rmSync(source, { recursive: true });
127+
expect(readFileSync(extracted.framePaths.get(0)!, "utf8")).toBe("frame bytes");
128+
});
129+
130+
describe("Windows link fallbacks", () => {
131+
const platform = Object.getOwnPropertyDescriptor(process, "platform")!;
132+
beforeEach(() => Object.defineProperty(process, "platform", { value: "win32" }));
133+
afterEach(() => Object.defineProperty(process, "platform", platform));
134+
135+
it.each(["EPERM", "EACCES", "UNKNOWN", "EINVAL", "ENOSYS", "EOPNOTSUPP", "ENOTSUP"])(
136+
"copies only after the junction is rejected with %s",
137+
(code) => {
138+
const { compiled, extracted } = fixture();
139+
const attempts: Array<string | undefined> = [];
140+
materializeExtractedFramesForCompiledDir([extracted], compiled, {
141+
fileSystem: {
142+
existsSync,
143+
mkdirSync,
144+
cpSync,
145+
rmSync,
146+
symlinkSync: (_target, _path, type) => {
147+
attempts.push(type);
148+
throw Object.assign(new Error("link unavailable"), {
149+
code: type === "junction" ? code : "EPERM",
150+
});
151+
},
152+
},
153+
});
154+
expect(attempts).toEqual(["dir", "junction"]);
155+
expect(lstatSync(extracted.outputDir).isSymbolicLink()).toBe(false);
156+
expect(readFileSync(extracted.framePaths.get(0)!, "utf8")).toBe("frame bytes");
157+
},
158+
);
159+
160+
it("does not hide a disk failure from the junction attempt", () => {
161+
const { compiled, extracted } = fixture();
162+
const copy = vi.fn();
163+
expect(() =>
164+
materializeExtractedFramesForCompiledDir([extracted], compiled, {
165+
fileSystem: {
166+
existsSync,
167+
mkdirSync,
168+
rmSync,
169+
cpSync: copy,
170+
symlinkSync: (_target, _path, type) => {
171+
throw Object.assign(new Error(type === "junction" ? "disk full" : "denied"), {
172+
code: type === "junction" ? "ENOSPC" : "EPERM",
173+
});
174+
},
175+
},
176+
}),
177+
).toThrow("disk full");
178+
expect(copy).not.toHaveBeenCalled();
179+
});
180+
});

0 commit comments

Comments
 (0)