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
This commit is contained in:
Miguel Ángel
2026-11-13 16:10:01 +00:00
committed by GitHub
parent 9f0a4edb43
commit 0bce3315e6
12 changed files with 275 additions and 17 deletions
@@ -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
+15
View File
@@ -96,3 +96,18 @@ export async function renameWithRetryAsync(
}
}
}
export async function retryWindowsHold<T>(
operation: () => T,
options: { platform?: NodeJS.Platform } = {},
): Promise<T> {
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]));
}
}
}
@@ -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<void>> = [];
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, "<div></div>");
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: "<div>edited</div>",
});
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<void>((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" });
});
});
+17 -3
View File
@@ -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;
}
@@ -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<string> {
@@ -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") {
@@ -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
+3 -1
View File
@@ -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",
);
}
@@ -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)
@@ -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") {
@@ -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({
@@ -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<StudioSaveHttpError> {
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<T>(
operation: (attempt: number) => Promise<T>,
options: {
@@ -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");