jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Fix fresh browser screenshot prep race

Browse Source
This commit is contained in:
Mohamed Boudra
2026-07-03 07:18:45 +02:00
parent f22865df62
commit cda1ba43cc
9 changed files with 497 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/desktop/src/features/browser-automation/ipc.test.ts
+115 -4
View File
@@ -299,6 +299,101 @@ describe("browser automation IPC adapter", () => {
expect(ipc.listenerCount("paseo:browser:capture-prepared")).toBe(0);
});
test("prepareForPixelCapture waits for the guest host renderer before asking for prep", async () => {
vi.useFakeTimers();
try {
const host = new FakeHostWebContents(10);
const contents = new FakeWebContents(20, null);
const ipc = new FakeIpcBridge();
const tab = adaptWebContents(contents, "browser-a", {
ipc,
createRequestId: () => "prepare-1",
timeoutMs: 250,
});
const preparation = tab.prepareForPixelCapture();
await vi.advanceTimersByTimeAsync(49);
expect(host.sentMessages).toEqual([]);
contents.hostWebContents = host;
await vi.advanceTimersByTimeAsync(1);
expect(host.sentMessages).toEqual([
{
channel: "paseo:browser:capture-prepare",
payload: { requestId: "prepare-1", browserId: "browser-a" },
},
]);
ipc.emit("paseo:browser:capture-prepared", {
requestId: "prepare-1",
ok: true,
token: "token-a",
});
await expect(preparation).resolves.toEqual({ token: "token-a" });
} finally {
vi.useRealTimers();
}
});
test("prepareForPixelCapture retries when the renderer prep handler is not registered yet", async () => {
vi.useFakeTimers();
try {
const host = new FakeHostWebContents(10);
const contents = new FakeWebContents(20, host);
const ipc = new FakeIpcBridge();
const requestIds = ["prepare-1", "prepare-2"];
const tab = adaptWebContents(contents, "browser-a", {
ipc,
createRequestId: () => {
const requestId = requestIds.shift();
if (!requestId) {
throw new Error("Missing request id");
}
return requestId;
},
timeoutMs: 250,
});
const preparation = tab.prepareForPixelCapture();
expect(host.sentMessages).toEqual([
{
channel: "paseo:browser:capture-prepare",
payload: { requestId: "prepare-1", browserId: "browser-a" },
},
]);
ipc.emit("paseo:browser:capture-prepared", {
requestId: "prepare-1",
ok: false,
message: "Browser pixel capture preparation is unavailable.",
});
await vi.advanceTimersByTimeAsync(50);
expect(host.sentMessages).toEqual([
{
channel: "paseo:browser:capture-prepare",
payload: { requestId: "prepare-1", browserId: "browser-a" },
},
{
channel: "paseo:browser:capture-prepare",
payload: { requestId: "prepare-2", browserId: "browser-a" },
},
]);
ipc.emit("paseo:browser:capture-prepared", {
requestId: "prepare-2",
ok: true,
token: "token-a",
});
await expect(preparation).resolves.toEqual({ token: "token-a" });
} finally {
vi.useRealTimers();
}
});
test("prepareForPixelCapture ignores matching responses from the wrong sender", async () => {
const host = new FakeHostWebContents(10);
const contents = new FakeWebContents(20, host);
@@ -364,12 +459,28 @@ describe("browser automation IPC adapter", () => {
}
});
test("prepareForPixelCapture reports prep_unavailable when the guest host renderer never appears", async () => {
vi.useFakeTimers();
try {
const contents = new FakeWebContents(20, null);
const tab = adaptWebContents(contents, "browser-a", { timeoutMs: 25 });
const preparation = tab.prepareForPixelCapture();
const rejection = expect(preparation).rejects.toThrow(
"Browser screenshot prep_unavailable: Browser host renderer is not available.",
);
await vi.advanceTimersByTimeAsync(25);
await rejection;
} finally {
vi.useRealTimers();
}
});
test("prepareForPixelCapture rejects when the guest has no embedder renderer", async () => {
const contents = new FakeWebContents(20, null);
const tab = adaptWebContents(contents, "browser-a");
const tab = adaptWebContents(contents, "browser-a", { timeoutMs: 1 });
await expect(tab.prepareForPixelCapture()).rejects.toThrow(
"Browser host renderer is not available.",
);
await expect(tab.prepareForPixelCapture()).rejects.toThrow("prep_unavailable");
});
});
packages/desktop/src/features/browser-automation/ipc.ts
+75 -5
View File
@@ -14,6 +14,8 @@ import {
const MAX_CONSOLE_MESSAGES_PER_TAB = 200;
const PIXEL_CAPTURE_BRIDGE_TIMEOUT_MS = 5_000;
const PIXEL_CAPTURE_PREP_RETRY_INTERVAL_MS = 50;
const PIXEL_CAPTURE_PREP_UNAVAILABLE_PREFIX = "Browser screenshot prep_unavailable:";
const consoleMessagesByContentsId = new Map<number, BrowserAutomationConsoleLogEntry[]>();
const observedContentsIds = new Set<number>();
let nextPixelCaptureBridgeRequest = 0;
@@ -121,12 +123,11 @@ export function adaptWebContents(
reload: () => contents.reload(),
capturePage: (captureOptions) => contents.capturePage(undefined, captureOptions),
prepareForPixelCapture: async () => {
const host = getPixelCaptureHost(contents);
const result = await requestPixelCaptureBridge({ host, browserId, kind: "prepare", options });
const result = await preparePixelCaptureBridgeWithRetry({ contents, browserId, options });
if (!result.token) {
throw new Error("Browser pixel capture preparation did not return a token.");
}
preparedPixelCapturesByToken.set(result.token, { browserId, host });
preparedPixelCapturesByToken.set(result.token, { browserId, host: result.host });
return { token: result.token };
},
restorePixelCapture: async (preparation) => {
@@ -159,14 +160,83 @@ export function adaptWebContents(
};
}
function getPixelCaptureHost(contents: BrowserAutomationWebContents): HostWebContents {
function getPixelCaptureHost(contents: BrowserAutomationWebContents): HostWebContents | null {
const host = contents.hostWebContents;
if (!host || host.isDestroyed()) {
throw new Error("Browser host renderer is not available.");
return null;
}
return host;
}
async function preparePixelCaptureBridgeWithRetry(input: {
contents: BrowserAutomationWebContents;
browserId: string;
options: PixelCaptureBridgeOptions | undefined;
}): Promise<PixelCaptureBridgeSuccess & { host: HostWebContents }> {
const timeoutMs = input.options?.timeoutMs ?? PIXEL_CAPTURE_BRIDGE_TIMEOUT_MS;
const deadline = Date.now() + timeoutMs;
let lastUnavailableReason = "Browser host renderer is not available.";
while (Date.now() < deadline) {
const host = getPixelCaptureHost(input.contents);
if (!host) {
await delayUntilRetry(deadline);
continue;
}
try {
const result = await requestPixelCaptureBridge({
host,
browserId: input.browserId,
kind: "prepare",
options: withBridgeTimeout(input.options, Math.max(1, deadline - Date.now())),
});
return { ...result, host };
} catch (error) {
if (!isRetryablePrepareUnavailableError(error)) {
throw error;
}
lastUnavailableReason = errorMessage(error);
await delayUntilRetry(deadline);
}
}
throw new Error(`${PIXEL_CAPTURE_PREP_UNAVAILABLE_PREFIX} ${lastUnavailableReason}`);
}
function withBridgeTimeout(
options: PixelCaptureBridgeOptions | undefined,
timeoutMs: number,
): PixelCaptureBridgeOptions {
return {
...options,
timeoutMs,
};
}
function isRetryablePrepareUnavailableError(error: unknown): boolean {
const message = errorMessage(error);
return (
message.includes("Browser pixel capture preparation is unavailable.") ||
message.includes("Browser host renderer is not available.") ||
message.includes("is not mounted.")
);
}
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
async function delayUntilRetry(deadline: number): Promise<void> {
const remainingMs = deadline - Date.now();
if (remainingMs <= 0) {
return;
}
await new Promise((resolve) => {
setTimeout(resolve, Math.min(PIXEL_CAPTURE_PREP_RETRY_INTERVAL_MS, remainingMs));
});
}
function requestPixelCaptureBridge(input: {
host: HostWebContents;
browserId: string;
packages/desktop/src/features/browser-automation/service.test.ts
+135 -4
View File
@@ -53,9 +53,12 @@ class FakeTab implements TabContents {
public consoleMessages: BrowserAutomationConsoleLogEntry[] = [];
public captureNeverPaints = false;
public captureThrows = false;
public captureErrorMessage = "capture failed";
public deferCaptures = false;
public prepareNeverAcks = false;
public prepareErrorMessage: string | null = null;
public fullPageScreenshotThrows = false;
public fullPageScreenshotErrorMessage = "UnknownVizError";
public layoutMetrics = {
cssLayoutViewport: { clientWidth: 390, clientHeight: 844 },
cssContentSize: { width: 390, height: 1200 },
@@ -131,7 +134,7 @@ class FakeTab implements TabContents {
this.actions.push("capture");
this.resolveCaptureStartWaiters();
if (this.captureThrows) {
throw new Error("capture failed");
throw new Error(this.captureErrorMessage);
}
if (this.captureNeverPaints) {
return new Promise<never>(() => {});
@@ -146,6 +149,9 @@ class FakeTab implements TabContents {
public async prepareForPixelCapture(): Promise<TabPixelCapturePreparation> {
this.actions.push("prepare");
if (this.prepareErrorMessage) {
throw new Error(this.prepareErrorMessage);
}
if (this.prepareNeverAcks) {
return new Promise<never>(() => {});
}
@@ -186,7 +192,7 @@ class FakeTab implements TabContents {
}
if (command === "Page.captureScreenshot") {
if (this.fullPageScreenshotThrows) {
throw new Error("UnknownVizError");
throw new Error(this.fullPageScreenshotErrorMessage);
}
return { data: this.fullPageScreenshotData };
}
@@ -963,10 +969,32 @@ describe("executeAutomationCommand", () => {
}
});
test("screenshot returns no-frame and restores capture preparation when viewport capture throws", async () => {
test("screenshot restores capture preparation when viewport capture fails with an ordinary error", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.captureThrows = true;
await expect(
browser.execute({
command: "screenshot",
args: { browserId: BROWSER_A },
}),
).rejects.toThrow("capture failed");
expect(browser.tab.actions).toEqual([
"prepare",
"background:false",
"invalidate",
"capture",
"restore:capture-1",
"background:true",
]);
});
test("screenshot returns no-frame and restores capture preparation when viewport capture throws UnknownVizError", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.captureThrows = true;
browser.tab.captureErrorMessage = "UnknownVizError";
await expect(
browser.execute({
command: "screenshot",
@@ -1010,7 +1038,7 @@ describe("executeAutomationCommand", () => {
error: {
code: "screenshot_no_frame",
message:
"The browser tab has no painted frame. Focus the tab in the app, then try again.",
"Browser screenshot prep_unavailable: the app renderer did not acknowledge capture preparation before the timeout.",
retryable: false,
},
});
@@ -1020,6 +1048,28 @@ describe("executeAutomationCommand", () => {
}
});
test("screenshot returns prep_unavailable and does not capture when preparation cannot be honored", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.prepareErrorMessage =
"Browser screenshot prep_unavailable: Browser host renderer is not available.";
const result = await browser.execute({
command: "screenshot",
args: { browserId: BROWSER_A },
});
expect(result).toEqual({
requestId: "req-screenshot",
ok: false,
error: {
code: "screenshot_no_frame",
message: "Browser screenshot prep_unavailable: Browser host renderer is not available.",
retryable: false,
},
});
expect(browser.tab.actions).toEqual(["prepare", "background:true"]);
});
test("overlapping screenshots serialize capture preparation and restore", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.deferCaptures = true;
@@ -1076,6 +1126,65 @@ describe("executeAutomationCommand", () => {
]);
});
test("overlapping screenshots across browser tabs serialize capture preparation and restore", async () => {
const registry = new FakeRegistry();
const firstTab = new FakeTab(1, "https://a.test", "A");
const secondTab = new FakeTab(2, "https://b.test", "B");
firstTab.deferCaptures = true;
secondTab.deferCaptures = true;
registry.register(BROWSER_A, WORKSPACE_A, firstTab);
registry.register(BROWSER_B, WORKSPACE_A, secondTab);
const first = executeAutomationCommand(
automationRequest({
command: "screenshot",
args: { browserId: BROWSER_A },
}),
registry,
);
await firstTab.waitForCaptureStart(1);
const second = executeAutomationCommand(
automationRequest(
{
command: "screenshot",
args: { browserId: BROWSER_B },
},
{ requestId: "req-screenshot-2" },
),
registry,
);
await Promise.resolve();
expect(firstTab.actions).toEqual(["prepare", "background:false", "invalidate", "capture"]);
expect(secondTab.actions).toEqual([]);
firstTab.finishNextCapture();
await secondTab.waitForCaptureStart(1);
expect(firstTab.actions).toEqual([
"prepare",
"background:false",
"invalidate",
"capture",
"restore:capture-1",
"background:true",
]);
expect(secondTab.actions).toEqual(["prepare", "background:false", "invalidate", "capture"]);
secondTab.finishNextCapture();
await expect(first).resolves.toMatchObject({ requestId: "req-screenshot", ok: true });
await expect(second).resolves.toMatchObject({ requestId: "req-screenshot-2", ok: true });
expect(secondTab.actions).toEqual([
"prepare",
"background:false",
"invalidate",
"capture",
"restore:capture-1",
"background:true",
]);
});
test("screenshot with fullPage captures the page content area through CDP", async () => {
const browser = new BrowserAutomationHarness();
@@ -1176,6 +1285,28 @@ describe("executeAutomationCommand", () => {
]);
});
test("screenshot with fullPage restores capture preparation when CDP capture fails with an ordinary error", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.fullPageScreenshotThrows = true;
browser.tab.fullPageScreenshotErrorMessage = "Debugger detached";
await expect(
browser.execute({
command: "screenshot",
args: { browserId: BROWSER_A, fullPage: true },
}),
).rejects.toThrow("Debugger detached");
expect(browser.tab.actions).toEqual([
"prepare",
"background:false",
"invalidate",
"debug:Page.getLayoutMetrics",
"debug:Page.captureScreenshot",
"restore:capture-1",
"background:true",
]);
});
test("upload resolves workspace files before setting them on the file input", async () => {
const browser = new BrowserAutomationHarness();
browser.tab.snapshotElements = [
packages/desktop/src/features/browser-automation/service.ts
+52 -19
View File
@@ -63,8 +63,9 @@ const WAIT_POLL_INTERVAL_MS = 25;
const PIXEL_CAPTURE_TIMEOUT_MS = 5_000;
const SCREENSHOT_NO_FRAME_MESSAGE =
"The browser tab has no painted frame. Focus the tab in the app, then try again.";
const SCREENSHOT_PREP_UNAVAILABLE_PREFIX = "Browser screenshot prep_unavailable:";
const ALLOWED_PAGE_URL_PROTOCOLS = new Set(["http:", "https:"]);
const pixelCaptureQueuesByContentsId = new Map<number, Promise<void>>();
let pixelCaptureQueue: Promise<void> = Promise.resolve();
function fail(
requestId: string,
@@ -76,8 +77,8 @@ function fail(
}
class ScreenshotNoFrameError extends Error {
public constructor() {
super(SCREENSHOT_NO_FRAME_MESSAGE);
public constructor(message = SCREENSHOT_NO_FRAME_MESSAGE) {
super(message);
this.name = "ScreenshotNoFrameError";
}
}
@@ -86,8 +87,11 @@ function isScreenshotNoFrameError(error: unknown): error is ScreenshotNoFrameErr
return error instanceof ScreenshotNoFrameError;
}
function screenshotNoFrameFailure(requestId: string): FailurePayload {
return fail(requestId, "screenshot_no_frame", SCREENSHOT_NO_FRAME_MESSAGE);
function screenshotNoFrameFailure(
requestId: string,
error: ScreenshotNoFrameError,
): FailurePayload {
return fail(requestId, "screenshot_no_frame", error.message);
}
async function withPixelCaptureTimeout<T>(capture: Promise<T>): Promise<T> {
@@ -107,25 +111,22 @@ async function withPixelCaptureTimeout<T>(capture: Promise<T>): Promise<T> {
}
}
async function runSerializedPixelCapture<T>(
contents: TabContents,
capture: () => Promise<T>,
): Promise<T> {
const previous = pixelCaptureQueuesByContentsId.get(contents.id) ?? Promise.resolve();
async function runSerializedPixelCapture<T>(capture: () => Promise<T>): Promise<T> {
const previous = pixelCaptureQueue;
let releaseCurrent = () => {};
const current = new Promise<void>((resolve) => {
releaseCurrent = resolve;
});
const tail = previous.catch(() => {}).then(() => current);
pixelCaptureQueuesByContentsId.set(contents.id, tail);
pixelCaptureQueue = tail;
await previous.catch(() => {});
try {
return await capture();
} finally {
releaseCurrent();
if (pixelCaptureQueuesByContentsId.get(contents.id) === tail) {
pixelCaptureQueuesByContentsId.delete(contents.id);
if (pixelCaptureQueue === tail) {
pixelCaptureQueue = Promise.resolve();
}
}
}
@@ -133,8 +134,8 @@ async function runSerializedPixelCapture<T>(
async function prepareForPixelCapture(contents: TabContents): Promise<TabPixelCapturePreparation> {
try {
return await withPixelCaptureTimeout(contents.prepareForPixelCapture());
} catch {
throw new ScreenshotNoFrameError();
} catch (error) {
throw screenshotPreparationError(error);
}
}
@@ -156,15 +157,47 @@ async function capturePreparedPixelFrame<T>(capture: () => Promise<T>): Promise<
if (isScreenshotNoFrameError(error)) {
throw error;
}
throw new ScreenshotNoFrameError();
if (isKnownNoFrameCaptureError(error)) {
throw new ScreenshotNoFrameError();
}
throw error;
}
}
function screenshotPreparationError(error: unknown): ScreenshotNoFrameError {
const message = error instanceof Error ? error.message : String(error);
if (isScreenshotNoFrameError(error)) {
return new ScreenshotNoFrameError(
`${SCREENSHOT_PREP_UNAVAILABLE_PREFIX} the app renderer did not acknowledge capture preparation before the timeout.`,
);
}
if (message.includes(SCREENSHOT_PREP_UNAVAILABLE_PREFIX)) {
return new ScreenshotNoFrameError(message);
}
if (
message.includes("Browser pixel capture preparation is unavailable.") ||
message.includes("Browser host renderer is not available.") ||
message.includes("is not mounted.")
) {
return new ScreenshotNoFrameError(`${SCREENSHOT_PREP_UNAVAILABLE_PREFIX} ${message}`);
}
return new ScreenshotNoFrameError(`${SCREENSHOT_PREP_UNAVAILABLE_PREFIX} ${message}`);
}
function isKnownNoFrameCaptureError(error: unknown): boolean {
const message = error instanceof Error ? error.message : String(error);
return (
message.includes("UnknownVizError") ||
message.includes("No frame") ||
message.includes("no painted frame")
);
}
async function runPreparedPixelCapture<T>(
contents: TabContents,
capture: () => Promise<T>,
): Promise<T> {
return runSerializedPixelCapture(contents, async () => {
return runSerializedPixelCapture(async () => {
const previousBackgroundThrottling = contents.isBackgroundThrottlingAllowed();
let preparation: TabPixelCapturePreparation | null = null;
try {
@@ -839,7 +872,7 @@ async function executeScreenshot(
image = await capturePaintedViewport(target.contents);
} catch (error) {
if (isScreenshotNoFrameError(error)) {
return screenshotNoFrameFailure(requestId);
return screenshotNoFrameFailure(requestId, error);
}
throw error;
}
@@ -931,7 +964,7 @@ async function executeFullPageScreenshot(
});
} catch (error) {
if (isScreenshotNoFrameError(error)) {
return screenshotNoFrameFailure(requestId);
return screenshotNoFrameFailure(requestId, error);
}
throw error;
}