From 0bce3315e645e513e10be271ad5bf415939a4147 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Fri, 13 Nov 2026 16:10:01 +0000 Subject: [PATCH] fix(studio): a file held open or read-only answers 423 or 403 with a reason, not 404 or 500 (#7649) * fix(studio): a file held open or read-only answers 423 or 403 with a reason, not 404 or 500 * fix(studio): valid workflow name for the Windows held-file test * test(studio): release the held file before the held-file test removes its folder * fix(studio): the code editor's save toast names a held or read-only file --- .../workflows/studio-server-windows-files.yml | 29 +++++ packages/core/src/renameWithRetry.ts | 15 +++ .../src/routes/files.heldFile.test.ts | 105 ++++++++++++++++++ packages/studio-server/src/routes/files.ts | 20 +++- .../studio/src/hooks/timelineTimingSync.ts | 5 +- .../studio/src/hooks/useEditorSave.test.tsx | 23 +++- packages/studio/src/hooks/useEditorSave.ts | 4 +- .../studio/src/hooks/useProjectFileWriter.ts | 10 +- .../studio/src/utils/studioFileHistory.ts | 2 +- .../src/utils/studioSaveDiagnostics.test.ts | 34 ++++++ .../studio/src/utils/studioSaveDiagnostics.ts | 41 ++++++- .../src/utils/timelineCompositionInsert.ts | 4 +- 12 files changed, 275 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/studio-server-windows-files.yml create mode 100644 packages/studio-server/src/routes/files.heldFile.test.ts diff --git a/.github/workflows/studio-server-windows-files.yml b/.github/workflows/studio-server-windows-files.yml new file mode 100644 index 0000000000..a1784fa0d8 --- /dev/null +++ b/.github/workflows/studio-server-windows-files.yml @@ -0,0 +1,29 @@ +name: Studio server files on Windows + +# A file another program holds open, or a read-only one, must not read as missing or as a server error. +on: + pull_request: + paths: + - packages/studio-server/src/routes/files.ts + - packages/studio-server/src/routes/files.heldFile.test.ts + - packages/core/src/renameWithRetry.ts + - .github/workflows/studio-server-windows-files.yml + +permissions: + contents: read + +jobs: + held-file: + runs-on: windows-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: 22 + - run: bun install --frozen-lockfile --ignore-scripts --linker=hoisted + - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build + - run: bun run --cwd packages/core build + - run: npx vitest run src/routes/files.heldFile.test.ts + working-directory: packages/studio-server diff --git a/packages/core/src/renameWithRetry.ts b/packages/core/src/renameWithRetry.ts index a5ae09da4b..b6bbf1310f 100644 --- a/packages/core/src/renameWithRetry.ts +++ b/packages/core/src/renameWithRetry.ts @@ -96,3 +96,18 @@ export async function renameWithRetryAsync( } } } + +export async function retryWindowsHold( + operation: () => T, + options: { platform?: NodeJS.Platform } = {}, +): Promise { + const platform = options.platform ?? process.platform; + for (let attempt = 0; ; attempt++) { + try { + return operation(); + } catch (error) { + if (!isWindowsHold(error, platform) || attempt >= BACKOFF_MS.length) throw error; + await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt])); + } + } +} diff --git a/packages/studio-server/src/routes/files.heldFile.test.ts b/packages/studio-server/src/routes/files.heldFile.test.ts new file mode 100644 index 0000000000..80e8a773b6 --- /dev/null +++ b/packages/studio-server/src/routes/files.heldFile.test.ts @@ -0,0 +1,105 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { Hono } from "hono"; +import { type ChildProcess, spawn, spawnSync } from "node:child_process"; +import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { registerFileRoutes } from "./files"; +import type { StudioApiAdapter } from "../types"; + +const cleanups: Array<() => void | Promise> = []; +afterEach(async () => { + for (const cleanup of cleanups.splice(0).reverse()) await cleanup(); +}); + +function fixture(name: string) { + const project = mkdtempSync(join(tmpdir(), "hf-held-file-")); + mkdirSync(join(project, "sub")); + const file = join(project, name); + writeFileSync(file, "
"); + cleanups.push(() => rmSync(project, { recursive: true, force: true })); + const adapter: StudioApiAdapter = { + listProjects: () => [], + resolveProject: async (id) => ({ id, dir: project }), + bundle: async () => null, + lint: async () => ({ findings: [] }), + runtimeUrl: "/api/runtime.js", + rendersDir: () => join(project, "renders"), + startRender: () => ({ id: "job", status: "rendering", progress: 0, outputPath: "out.mp4" }), + }; + const app = new Hono(); + registerFileRoutes(app, adapter); + const get = (query = "") => app.request(`http://localhost/projects/demo/files/${name}${query}`); + const put = () => + app.request(`http://localhost/projects/demo/files/${name}`, { + method: "PUT", + headers: { "If-Match": '"any"' }, + body: "
edited
", + }); + return { file, get, put }; +} + +const answered = async (response: Response) => ({ + status: response.status, + why: ((await response.json()) as { why?: string }).why, +}); + +describe.skipIf(process.platform === "win32" || process.getuid?.() === 0)( + "a file the process may not open", + () => { + // fails without the fix: the read answered 404 "not found" and the save threw a 500, whatever the cause. + it("answers a read 403 permission, not 404, and a save 403 permission, not 500", async () => { + const { file, get, put } = fixture("locked.html"); + chmodSync(file, 0o000); + expect(await answered(await get())).toEqual({ status: 403, why: "permission" }); + expect(await answered(await put())).toEqual({ status: 403, why: "permission" }); + }); + + it("does not answer an optional read of it as a blank file", async () => { + const { file, get } = fixture("locked.html"); + chmodSync(file, 0o000); + expect(await answered(await get("?optional=1"))).toEqual({ status: 403, why: "permission" }); + }); + }, +); + +/** Holds `file` open with no sharing, as an antivirus scan or a sync client does, until the cleanup runs. */ +async function holdOpen(file: string) { + const holder: ChildProcess = spawn("powershell", [ + "-NoProfile", + "-Command", + `$f=[IO.File]::Open('${file}','Open','ReadWrite','None'); 'held'; Start-Sleep 120`, + ]); + cleanups.push( + () => + new Promise((resolve) => { + holder.once("exit", () => resolve()); + holder.kill(); + }), + ); + await new Promise((resolve) => holder.stdout?.once("data", resolve)); +} + +describe.runIf(process.platform === "win32")("a file another program holds open on Windows", () => { + // fails without the fix: both answers were 404 "not found" (read) and 500 (save) for a file that exists. + it("answers a read and a save 423 busy after waiting it out", async () => { + const { file, get, put } = fixture("held.html"); + await holdOpen(file); + expect(await answered(await get())).toEqual({ status: 423, why: "busy" }); + expect(await answered(await put())).toEqual({ status: 423, why: "busy" }); + }, 30_000); + + it("does not answer an optional read of it as a blank file", async () => { + const { file, get } = fixture("held.html"); + await holdOpen(file); + expect(await answered(await get("?optional=1"))).toEqual({ status: 423, why: "busy" }); + }, 30_000); + + it("answers a save of a read-only file 403 permission and still reads it", async () => { + const { file, get, put } = fixture("readonly.html"); + spawnSync("attrib", ["+R", file]); + cleanups.push(() => spawnSync("attrib", ["-R", file])); + expect((await get()).status).toBe(200); + expect(await answered(await put())).toEqual({ status: 403, why: "permission" }); + }); +}); diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts index 8e0becca4c..ff0e6298aa 100644 --- a/packages/studio-server/src/routes/files.ts +++ b/packages/studio-server/src/routes/files.ts @@ -31,6 +31,7 @@ import type { StudioApiAdapter } from "../types.js"; import { isAudioFile } from "../helpers/mime.js"; import { lengthIsTimeline } from "../helpers/compositionInputs.js"; import { createFileAtomically, replaceFileAtomically } from "@hyperframes/core/atomic-file"; +import { retryWindowsHold } from "@hyperframes/core/rename-retry"; import { generateWaveformCache } from "../helpers/waveform.js"; import { validateUploadedMediaBuffer } from "../helpers/mediaValidation.js"; import { @@ -2796,6 +2797,15 @@ async function processUploadedFiles( const MAX_TEXT_READ_BYTES = 32 * 1024 * 1024; const GIT_BINARY_SNIFF_BYTES = 8000; +function heldFileAnswer(c: RouteContext, error: unknown) { + const code = (error as NodeJS.ErrnoException | null)?.code; + if (code === "EBUSY") return c.json({ error: "file in use", why: "busy" }, 423); + if (code === "EPERM" || code === "EACCES") { + return c.json({ error: "permission denied", why: "permission" }, 403); + } + return null; +} + export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void { // ── Read ── @@ -2808,8 +2818,10 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void { // and the read can't land a stale answer — both act on the identical inode. let fd: number; try { - fd = openSync(res.absPath, "r"); - } catch { + fd = await retryWindowsHold(() => openSync(res.absPath, "r")); + } catch (error) { + const held = heldFileAnswer(c, error); + if (held) return held; if (c.req.query("optional") === "1") { // `missing: true` separates the absent-file shim from a genuinely // 0-byte file — both answer `content: ""`, and the caller could not @@ -2912,8 +2924,10 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void { } else { let fd: number | null; try { - fd = openSync(res.absPath, "r+"); + fd = await retryWindowsHold(() => openSync(res.absPath, "r+")); } catch (error) { + const held = heldFileAnswer(c, error); + if (held) return held; if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") { throw error; } diff --git a/packages/studio/src/hooks/timelineTimingSync.ts b/packages/studio/src/hooks/timelineTimingSync.ts index 2a32f4714d..7b067f56c2 100644 --- a/packages/studio/src/hooks/timelineTimingSync.ts +++ b/packages/studio/src/hooks/timelineTimingSync.ts @@ -30,6 +30,7 @@ import { type StudioProjectFileWriter, } from "../utils/studioFileMutationCoordinator"; import { studioApiFetch } from "../utils/studioApiFetch"; +import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics"; import { moveLiveTweens } from "../utils/gsapLiveRetime"; export async function readFileContent(projectId: string, targetPath: string): Promise { @@ -40,7 +41,9 @@ export async function readFileContent(projectId: string, targetPath: string): Pr `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(targetPath)}`, ); if (!response.ok) { - throw new Error(`Failed to read ${targetPath}`); + throw await createStudioSaveHttpError(response, `Failed to read ${targetPath}`, { + path: targetPath, + }); } const data = (await response.json()) as { content?: string }; if (typeof data.content !== "string") { diff --git a/packages/studio/src/hooks/useEditorSave.test.tsx b/packages/studio/src/hooks/useEditorSave.test.tsx index f9a59c528d..4b32e5012b 100644 --- a/packages/studio/src/hooks/useEditorSave.test.tsx +++ b/packages/studio/src/hooks/useEditorSave.test.tsx @@ -9,7 +9,7 @@ vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({ trackStudioSaveFailure, })); -import { StudioFileConflictError } from "../utils/studioSaveDiagnostics"; +import { StudioFileConflictError, createStudioSaveHttpError } from "../utils/studioSaveDiagnostics"; import { useEditorSave, type EditorSaveHandle } from "./useEditorSave"; (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true; @@ -150,6 +150,27 @@ describe("useEditorSave pending work", () => { await mounted.unmount(); }); + // fails without the fix: the toast told the person to check the preview server for a file another program holds open. + it("toasts a held file in its own words, not the generic preview-server advice", async () => { + const held = await createStudioSaveHttpError( + new Response(JSON.stringify({ why: "busy" }), { status: 423 }), + "Failed to save index.html", + { path: "index.html" }, + ); + const mounted = await mountEditorSave(async () => { + throw held; + }); + + act(() => mounted.handle.handleContentChange("edit")); + await mounted.handle.flushPendingSave(); + + expect(mounted.showToast).toHaveBeenCalledWith( + "index.html is open in another program. Close it there, then try again.", + "error", + ); + await mounted.unmount(); + }); + it("emits a changed failure immediately and repeats after the burst window", async () => { const now = vi.spyOn(Date, "now").mockReturnValue(1_000); const writeProjectFile = vi diff --git a/packages/studio/src/hooks/useEditorSave.ts b/packages/studio/src/hooks/useEditorSave.ts index 6ab30e2e51..a41d1fdcc8 100644 --- a/packages/studio/src/hooks/useEditorSave.ts +++ b/packages/studio/src/hooks/useEditorSave.ts @@ -3,6 +3,7 @@ import { saveProjectFilesWithHistory } from "../utils/studioFileHistory"; import { StudioFileConflictError, buildStudioSaveFailureProperties, + heldFileWords, trackStudioSaveFailure, type StudioSaveDrainResult, } from "../utils/studioSaveDiagnostics"; @@ -93,7 +94,8 @@ export function useEditorSave({ ) { lastFailureToastAtRef.current = now; showToast( - `Couldn't save ${path}. Your latest edits are NOT persisted. Check the preview server; editing again retries the save.`, + heldFileWords(error) ?? + `Couldn't save ${path}. Your latest edits are NOT persisted. Check the preview server; editing again retries the save.`, "error", ); } diff --git a/packages/studio/src/hooks/useProjectFileWriter.ts b/packages/studio/src/hooks/useProjectFileWriter.ts index 50499aa4de..81514c2887 100644 --- a/packages/studio/src/hooks/useProjectFileWriter.ts +++ b/packages/studio/src/hooks/useProjectFileWriter.ts @@ -17,7 +17,8 @@ async function fetchProjectFile(projectId: string | null, path: string, query: s const response = await studioApiFetch( `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}${query}`, ); - if (!response.ok) throw new Error(`Failed to read ${path}`); + if (!response.ok) + throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path }); const data = (await response.json()) as { content?: string; version?: string }; return { content: data.content, version: data.version ?? response.headers.get("etag") }; } @@ -78,7 +79,9 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions) } else if (preflight.status === 404) { expectedVersion = null; } else { - throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`); + throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`, { + path, + }); } } // fallow-ignore-next-line complexity @@ -121,7 +124,8 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions) attemptedContent: content, }); } - if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`); + if (!response.ok) + throw await createStudioSaveHttpError(response, `Failed to save ${path}`, { path }); const result = (await response.json()) as { version?: string }; const version = result.version ?? response.headers.get("etag"); if (!version) diff --git a/packages/studio/src/utils/studioFileHistory.ts b/packages/studio/src/utils/studioFileHistory.ts index d79bf9461c..733d396640 100644 --- a/packages/studio/src/utils/studioFileHistory.ts +++ b/packages/studio/src/utils/studioFileHistory.ts @@ -75,7 +75,7 @@ export async function readProjectFileContent(pid: string, path: string): Promise buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`), ); if (!response.ok) { - throw await createStudioSaveHttpError(response, `Failed to read ${path}`); + throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path }); } const data = (await response.json()) as { content?: string }; if (typeof data.content !== "string") { diff --git a/packages/studio/src/utils/studioSaveDiagnostics.test.ts b/packages/studio/src/utils/studioSaveDiagnostics.test.ts index 84a5486c07..8c239d9900 100644 --- a/packages/studio/src/utils/studioSaveDiagnostics.test.ts +++ b/packages/studio/src/utils/studioSaveDiagnostics.test.ts @@ -7,12 +7,46 @@ import { StudioFileConflictError, StudioSaveHttpError, StudioSaveNetworkError, + createStudioSaveHttpError, buildStudioSaveFailureProperties, getStudioSaveStatusCode, retryStudioSave, trackStudioEditBlocked, } from "./studioSaveDiagnostics"; +describe("a file the server says is held or protected", () => { + // fails without the fix: the person read 'Failed to read ... (423): {"error":"file in use",...}' or no status at all. + it.each([ + [423, "busy", "index.html is open in another program. Close it there, then try again."], + [ + 403, + "permission", + "index.html can't be changed: it is read-only or protected. Check its permissions, then try again.", + ], + ])("tells a %i %s in words naming the file, not the folder", async (status, why, words) => { + const response = new Response(JSON.stringify({ error: "x", why }), { status }); + const error = await createStudioSaveHttpError(response, "Failed to save a/b/index.html", { + path: "a/b/index.html", + }); + expect(error.message).toBe(words); + expect(error.statusCode).toBe(status); + }); + + it("keeps the status and body for any other answer, and without a path", async () => { + const other = await createStudioSaveHttpError( + new Response("boom", { status: 500 }), + "Failed to save index.html", + { path: "index.html" }, + ); + expect(other.message).toBe("Failed to save index.html (500): boom"); + const noPath = await createStudioSaveHttpError( + new Response(JSON.stringify({ why: "busy" }), { status: 423 }), + "Failed to save index.html", + ); + expect(noPath.message).toMatch(/^Failed to save index.html \(423\)/); + }); +}); + describe("studio save diagnostics", () => { it("preserves conflict versions and both sides for explicit recovery UI", () => { const error = new StudioFileConflictError({ diff --git a/packages/studio/src/utils/studioSaveDiagnostics.ts b/packages/studio/src/utils/studioSaveDiagnostics.ts index f4a8c3ebf0..2bbd6092ce 100644 --- a/packages/studio/src/utils/studioSaveDiagnostics.ts +++ b/packages/studio/src/utils/studioSaveDiagnostics.ts @@ -19,12 +19,18 @@ export interface StudioSaveFailureInput { export class StudioSaveHttpError extends Error { readonly statusCode: number; readonly alreadyToasted: boolean; + readonly heldFile: boolean; - constructor(message: string, statusCode: number, options: { alreadyToasted?: boolean } = {}) { + constructor( + message: string, + statusCode: number, + options: { alreadyToasted?: boolean; heldFile?: boolean } = {}, + ) { super(message); this.name = "StudioSaveHttpError"; this.statusCode = statusCode; this.alreadyToasted = options.alreadyToasted ?? false; + this.heldFile = options.heldFile ?? false; } } @@ -188,10 +194,27 @@ export function trackStudioEditBlocked(input: StudioSaveFailureInput): void { trackStudioEvent("edit_blocked", buildStudioSaveFailureProperties(input)); } +const HELD_FILE_WORDS = { + busy: (file: string) => `${file} is open in another program. Close it there, then try again.`, + permission: (file: string) => + `${file} can't be changed: it is read-only or protected. Check its permissions, then try again.`, +} as const; + +function heldFileMessage(body: string, path: string | undefined): string | null { + if (!path) return null; + try { + const why: unknown = (JSON.parse(body) as { why?: unknown }).why; + if (why !== "busy" && why !== "permission") return null; + return HELD_FILE_WORDS[why](path.split(/[\\/]/).pop() ?? path); + } catch { + return null; + } +} + export async function createStudioSaveHttpError( response: Response, fallbackMessage: string, - options: { alreadyToasted?: boolean } = {}, + options: { alreadyToasted?: boolean; path?: string } = {}, ): Promise { let body = ""; try { @@ -200,12 +223,18 @@ export async function createStudioSaveHttpError( body = ""; } const detail = body.trim().slice(0, 300); - const message = detail - ? `${fallbackMessage} (${response.status}): ${detail}` - : `${fallbackMessage} (${response.status})`; - return new StudioSaveHttpError(message, response.status, options); + const held = heldFileMessage(body, options.path); + const message = + held ?? + (detail + ? `${fallbackMessage} (${response.status}): ${detail}` + : `${fallbackMessage} (${response.status})`); + return new StudioSaveHttpError(message, response.status, { ...options, heldFile: held !== null }); } +export const heldFileWords = (error: unknown): string | null => + error instanceof StudioSaveHttpError && error.heldFile ? error.message : null; + export async function retryStudioSave( operation: (attempt: number) => Promise, options: { diff --git a/packages/studio/src/utils/timelineCompositionInsert.ts b/packages/studio/src/utils/timelineCompositionInsert.ts index b29e26c82a..1b5f6a1f78 100644 --- a/packages/studio/src/utils/timelineCompositionInsert.ts +++ b/packages/studio/src/utils/timelineCompositionInsert.ts @@ -25,7 +25,9 @@ async function insertTimelineComposition(input: { buildProjectApiPath(input.projectId, `/files/${encodeURIComponent(input.targetPath)}`), ); if (!current.ok) { - throw await createStudioSaveHttpError(current, `Failed to read ${input.targetPath}`); + throw await createStudioSaveHttpError(current, `Failed to read ${input.targetPath}`, { + path: input.targetPath, + }); } const snapshot = (await current.json()) as { version?: string }; if (typeof snapshot.version !== "string") throw new Error("Missing composition file version");