Skip to content

Write HTML. Render video. Built for agents.

fix(studio-server): send Studio's history edits to the process that owns the project's history (#5826)

Miguel Ángelcadd7af2b552
diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts
index 7a22a78f0f..9112f15b83 100644
--- a/packages/cli/src/commands/preview.ts
+++ b/packages/cli/src/commands/preview.ts
@@ -1578,6 +1578,7 @@ export async function runEmbeddedMode(
// Compute everything that may throw before acquiring the fs.watch handle.
// Once createStudioServer returns, every subsequent exit path must close it.
const serverBuildSignature = await loadPreviewServerBuildSignature();
+ let listening: string | undefined;
const {
app,
watcher,
@@ -1587,6 +1588,7 @@ export async function runEmbeddedMode(
projectName: pName,
autoProxy: options?.autoProxy,
browserGpuMode: options?.browserGpuMode,
+ origin: () => listening,
});
let result: FindPortResult;
try {
@@ -1643,6 +1645,7 @@ export async function runEmbeddedMode(
}
const url = `http://localhost:${result.port}`;
+ listening = `http://127.0.0.1:${result.port}`;
if (options?.json) {
writeLifecycleJson(foregroundPreviewReadyPayload(pName, url, dir, process.pid));
} else {
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index ca404a0ec1..64a9dd2842 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -363,6 +363,7 @@ export interface StudioServerOptions {
browserGpuMode?: BrowserGpuMode;
/** Where project histories are kept; defaults to ~/.cache/hyperframes/history. */
historyRoot?: string;
+ origin?: () => string | undefined;
}
export interface StudioServer {
@@ -453,11 +454,16 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
// Opened on first use, so a server that never serves Studio's history never writes one. A failed open stays off
// for this run; one another process was holding is tried again on the next request, which no write waits for.
let ownerWaitMs: number | undefined;
+ const historyUrl = () => {
+ const origin = options.origin?.();
+ return origin && `${origin}/api/projects/${encodeURIComponent(projectId)}/history`;
+ };
const histories = historyCache(() =>
openProjectHistory({
projectDir,
historyRoot: options.historyRoot ?? DEFAULT_HISTORY_ROOT,
ownerWaitMs,
+ ownerUrl: historyUrl(),
})
.then((history) => {
ownerWaitMs = undefined;
diff --git a/packages/studio-server/src/history/ownerLock.ts b/packages/studio-server/src/history/ownerLock.ts
index 4cf97986bc..8511ad831e 100644
--- a/packages/studio-server/src/history/ownerLock.ts
+++ b/packages/studio-server/src/history/ownerLock.ts
@@ -1,9 +1,12 @@
import { randomUUID } from "node:crypto";
-import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
export class HistoryBusyError extends Error {
- constructor(readonly pid: number) {
+ constructor(
+ readonly pid: number,
+ readonly url?: string,
+ ) {
super(`This project's history is open in another process (pid ${pid}).`);
this.name = "HistoryBusyError";
}
@@ -70,18 +73,44 @@ function evictDeadOwner(file: string): boolean {
}
}
+/** The owner's url sits beside owner.pid, so readers of owner.pid from older versions see no change. */
+function advertise(urlFile: string, url: string | undefined): void {
+ if (!url) return rmSync(urlFile, { force: true });
+ const draft = `${urlFile}-${process.pid}-${randomUUID()}.tmp`;
+ writeFileSync(draft, JSON.stringify({ pid: process.pid, url }));
+ renameSync(draft, urlFile);
+}
+
+/** The url `pid` advertised, only while `pid` is alive and still holds `file`. */
+function servedBy(file: string, urlFile: string, pid: number): string | undefined {
+ try {
+ const said = JSON.parse(readFileSync(urlFile, "utf-8")) as { pid?: unknown; url?: unknown };
+ const live = said.pid === pid && alive(pid) && ownerOf(file) === pid;
+ return live && typeof said.url === "string" ? said.url : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
/**
* One process at a time keeps a project's history open (a second opener would fork the log). Waits up to `waitMs`
- * for the owner to close, takes over a dead owner's lock.
+ * for the owner to close, takes over a dead owner's lock. `url` is where this process serves the history's routes.
*/
-export async function takeHistoryOwnership(home: string, waitMs: number): Promise<() => void> {
+export async function takeHistoryOwnership(
+ home: string,
+ waitMs: number,
+ url?: string,
+): Promise<() => void> {
const file = join(home, "owner.pid");
+ const urlFile = join(home, "owner-url.json");
const deadline = Date.now() + waitMs;
mkdirSync(home, { recursive: true });
for (;;) {
if (claim(file)) {
+ advertise(urlFile, url);
let held = true;
return () => {
+ if (held && servedBy(file, urlFile, process.pid)) rmSync(urlFile, { force: true });
if (held) releaseOwn(file);
held = false;
};
@@ -89,7 +118,7 @@ export async function takeHistoryOwnership(home: string, waitMs: number): Promis
const pid = ownerOf(file);
if (pid === null) continue;
if (!alive(pid) && evictDeadOwner(file)) continue;
- if (Date.now() >= deadline) throw new HistoryBusyError(pid);
+ if (Date.now() >= deadline) throw new HistoryBusyError(pid, servedBy(file, urlFile, pid));
await new Promise((settle) => setTimeout(settle, 50));
}
}
diff --git a/packages/studio-server/src/history/projectHistory.ts b/packages/studio-server/src/history/projectHistory.ts
index f496829696..1c90a6b8c8 100644
--- a/packages/studio-server/src/history/projectHistory.ts
+++ b/packages/studio-server/src/history/projectHistory.ts
@@ -82,6 +82,7 @@ export interface ProjectHistoryOptions {
onError?: (error: unknown) => void;
/** How long an open waits for another process to close the same history (default 5 s). */
ownerWaitMs?: number;
+ ownerUrl?: string;
/** A CLI turn's window from an earlier open: writes since, within its idle limit, become the entry with its id. */
closedWindow?: ClosedWindow;
closedWindowAfterOwnership?: () => ClosedWindow | undefined;
@@ -1360,6 +1361,7 @@ export async function openProjectHistory(options: ProjectHistoryOptions): Promis
const release = await takeHistoryOwnership(
join(options.historyRoot, projectId),
options.ownerWaitMs ?? 5000,
+ options.ownerUrl,
);
try {
const blobs = await openBlobStore(join(options.historyRoot, projectId, "blobs"));
diff --git a/packages/studio-server/src/routes/history.test.ts b/packages/studio-server/src/routes/history.test.ts
index 92dd0cc467..390e62f142 100644
--- a/packages/studio-server/src/routes/history.test.ts
+++ b/packages/studio-server/src/routes/history.test.ts
@@ -1,6 +1,8 @@
// @vitest-environment node
// fallow-ignore-file code-duplication
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -545,8 +547,87 @@ describe("history routes", () => {
const blob = await api.request(`/projects/demo/history/blob/${"0".repeat(64)}`);
expect([blob.status, await blob.json()]).toEqual([409, busy]);
});
+
+ it("send Studio's edit to the process that owns the history, so it is the person's entry there", async () => {
+ const { projectDir, owner, desktop } = await ownedElsewhere();
+ writeFileSync(join(projectDir, "index.html"), "B");
+
+ const claim = await desktop("/claim", { label: "Color", paths: ["index.html"] });
+ expect(claim.status).toBe(200);
+ expect(owner.list().at(-1)).toMatchObject({ label: "Color", who: { name: "You" } });
+ expect(await (await desktop("/step", { direction: "back" })).json()).toMatchObject({
+ ok: true,
+ });
+ expect(readFileSync(join(projectDir, "index.html"), "utf-8")).toBe("A");
+ });
+
+ it("trust the owner's address only when it is loopback and names the live owner", async () => {
+ for (const said of [{ url: "http://example.com/history" }, { pid: process.pid + 1 }]) {
+ const { historyRoot, ownerUrl, desktop } = await ownedElsewhere();
+ const home = readdirSync(historyRoot).find((id) =>
+ existsSync(join(historyRoot, id, "owner.pid")),
+ )!;
+ writeFileSync(
+ join(historyRoot, home, "owner-url.json"),
+ JSON.stringify({ pid: process.pid, url: ownerUrl, ...said }),
+ );
+ expect((await desktop("/claim", { label: "Color", paths: ["index.html"] })).status).toBe(409);
+ }
+ });
+
+ it("answer the 409 with the reason when the owner takes the request and never replies", async () => {
+ const silent = createServer(() => {});
+ await new Promise<void>((listening) => silent.listen(0, "127.0.0.1", listening));
+ cleanup.push(() => {
+ silent.closeAllConnections();
+ return new Promise((closed) => silent.close(closed));
+ });
+ const port = (silent.address() as AddressInfo).port;
+ const { desktop } = await ownedElsewhere(`http://127.0.0.1:${port}/projects/demo/history`);
+ const started = Date.now();
+
+ const claim = await desktop("/claim", { label: "Color", paths: ["index.html"] });
+ expect(claim.status).toBe(409);
+ expect(Date.now() - started).toBeLessThan(9_000);
+ }, 15_000);
});
+/** A project whose history a served Studio API owns, and a second host (as Desktop) that finds it busy. */
+async function ownedElsewhere(advertised?: string) {
+ const projectDir = tempDir("hf-history-owned-");
+ writeFileSync(join(projectDir, "index.html"), "A");
+ const historyRoot = tempDir("hf-history-owned-root-");
+ let owner: ProjectHistory | null = null;
+ const resolveProject = (id: string) => (id === "demo" ? { id, dir: projectDir } : null);
+ const served = createStudioApi({
+ listProjects: () => [],
+ resolveProject,
+ history: () => owner,
+ } as unknown as StudioApiAdapter);
+ const server = createServer(async (req, res) => {
+ const chunks: Buffer[] = [];
+ for await (const chunk of req) chunks.push(chunk as Buffer);
+ const body = chunks.length ? Buffer.concat(chunks) : undefined;
+ const headers = req.headers as Record<string, string>;
+ const reply = await served.request(req.url ?? "/", { method: req.method, headers, body });
+ res.writeHead(reply.status, Object.fromEntries(reply.headers));
+ res.end(Buffer.from(await reply.arrayBuffer()));
+ });
+ await new Promise<void>((listening) => server.listen(0, "127.0.0.1", listening));
+ cleanup.push(() => new Promise((closed) => server.close(closed)));
+ const ownerUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}/projects/demo/history`;
+ owner = await openProjectHistory({ projectDir, historyRoot, ownerUrl: advertised ?? ownerUrl });
+ cleanup.push(() => owner?.close());
+ const api = createStudioApi({
+ listProjects: () => [],
+ resolveProject,
+ history: () => openProjectHistory({ projectDir, historyRoot, ownerWaitMs: 0 }),
+ } as unknown as StudioApiAdapter);
+ const desktop = (path: string, body: object) =>
+ api.request(`/projects/demo/history${path}`, { method: "POST", body: JSON.stringify(body) });
+ return { projectDir, historyRoot, ownerUrl, owner, desktop };
+}
+
it("checkpoints pending writes without closing an agent window", async () => {
const { projectDir, history, call } = await demoProject();
const who = { kind: "agent", name: "test-agent" } as const;
diff --git a/packages/studio-server/src/routes/history.ts b/packages/studio-server/src/routes/history.ts
index e2d6240f48..c056f89261 100644
--- a/packages/studio-server/src/routes/history.ts
+++ b/packages/studio-server/src/routes/history.ts
@@ -8,6 +8,7 @@ import {
type ProjectHistory,
} from "../history/projectHistory.js";
import type { HistoryWho, HistoryTarget } from "../history/historyLog.js";
+import { HistoryBusyError } from "../history/ownerLock.js";
const YOU: HistoryWho = { kind: "person", name: "You" };
@@ -91,7 +92,40 @@ function nextStep(history: ProjectHistory, direction: "back" | "forward") {
return { id: target.id, label: target.label, endedAt: target.endedAt, paths };
}
-/** Runs `task` on the project's history; no history is a 404, a refusal to open or to act ("no longer kept") a 409. */
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const FORWARD_DEADLINE_MS = 5_000;
+
+function ownerRoute(c: Context, error: unknown): string | null {
+ if (!(error instanceof HistoryBusyError) || !error.url || !URL.canParse(error.url)) return null;
+ const owner = new URL(error.url);
+ if (owner.protocol !== "http:" || !LOOPBACK.has(owner.hostname)) return null;
+ const rest = c.req.path.replace(/^.*?\/projects\/[^/]+\/history/, "");
+ return `${owner.href.replace(/\/$/, "")}${rest}${new URL(c.req.url).search}`;
+}
+
+async function forward(c: Context, target: string): Promise<Response> {
+ const token = c.req.header("X-Hyperframes-Write-Token");
+ const reads = c.req.method === "GET" || c.req.method === "HEAD";
+ const reply = await fetch(target, {
+ method: c.req.method,
+ headers: {
+ "content-type": c.req.header("content-type") ?? "application/json",
+ ...(token && { "X-Hyperframes-Write-Token": token }),
+ },
+ ...(!reads && { body: await c.req.arrayBuffer() }),
+ signal: AbortSignal.timeout(FORWARD_DEADLINE_MS),
+ });
+ const type = reply.headers.get("content-type") ?? "application/json";
+ return new Response(await reply.arrayBuffer(), {
+ status: reply.status,
+ headers: { "content-type": type },
+ });
+}
+
+/**
+ * Runs `task` on the project's history; no history is a 404, a refusal to open or to act ("no longer kept") a 409.
+ * A history another live process owns is that owner's: the request goes to it, so one log keeps every edit.
+ */
async function withHistory(
adapter: StudioApiAdapter,
c: Context,
@@ -103,7 +137,11 @@ async function withHistory(
const result = await task(history, await bodyOf(c));
return result instanceof Response ? result : c.json(result ?? null);
} catch (error) {
- return c.json({ error: error instanceof Error ? error.message : String(error) }, 409);
+ const target = ownerRoute(c, error);
+ const forwarded = target && (await forward(c, target).catch(() => null));
+ return (
+ forwarded || c.json({ error: error instanceof Error ? error.message : String(error) }, 409)
+ );
}
}