Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): wait for a concurrent build's Vercel template instead of failing (#4707)

roboeve[bot]63b1daabc4ce
diff --git a/.changeset/vercel-template-name-conflict.md b/.changeset/vercel-template-name-conflict.md
new file mode 100644
index 000000000..25bef5f26
--- /dev/null
+++ b/.changeset/vercel-template-name-conflict.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Concurrent builds that need the same new Vercel sandbox template no longer fail with a 400 "sandbox with the name already exists" error. Each build now prepares its template in a private, non-persistent sandbox and records the finished snapshot under the shared template name only after the snapshot exists, so a build that fails, is killed, or times out never leaves half-prepared work where another build would reuse it.
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts b/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts
index 906be19e6..a8d868192 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts
@@ -2,7 +2,10 @@ import {
getVercelSandboxFetch,
resolveVercelSandboxCredentials,
} from "#execution/sandbox/bindings/vercel-credentials.js";
-import { isVercelSandboxMissingError } from "#execution/sandbox/bindings/vercel-errors.js";
+import {
+ isVercelSandboxMissingError,
+ isVercelSnapshotUnavailableError,
+} from "#execution/sandbox/bindings/vercel-errors.js";
import { errorMessage } from "#execution/sandbox/bindings/vercel-options.js";
import type {
VercelCreateOptions,
@@ -32,6 +35,31 @@ export async function getNamedVercelSandbox(input: {
}
}
+/** Whether a snapshot exists and finished, so a sandbox can still start from it. */
+export async function isVercelSnapshotCreated(input: {
+ readonly createOptions: VercelCreateOptions;
+ readonly sandboxModule: VercelModule;
+ readonly snapshotId: string;
+}): Promise<boolean> {
+ try {
+ const snapshot = await input.sandboxModule.Snapshot.get({
+ ...(await resolveVercelSandboxCredentials(input.createOptions)),
+ fetch: getVercelSandboxFetch(input.createOptions),
+ signal: input.createOptions.signal,
+ snapshotId: input.snapshotId,
+ });
+ return snapshot.status === "created";
+ } catch (error) {
+ if (isVercelSandboxMissingError(error) || isVercelSnapshotUnavailableError(error)) {
+ return false;
+ }
+ throw new Error(
+ `Failed to look up Vercel snapshot "${input.snapshotId}": ${errorMessage(error)}`,
+ { cause: error },
+ );
+ }
+}
+
async function getVercelSandboxGetOptions(input: {
readonly createOptions: VercelCreateOptions;
readonly sandboxName: string;
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
index b24f568cc..368aaad38 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
@@ -1,6 +1,6 @@
import { Readable } from "node:stream";
-import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
import { VERCEL_EVE_SANDBOX_IMAGE } from "#execution/sandbox/bindings/eve-image.js";
@@ -47,12 +47,13 @@ function createMockDetachedCommand(
function createMockSandbox(input: {
name: string;
snapshotId?: string;
+ sourceSnapshotId?: string;
status?: string;
tags?: Record<string, string>;
}) {
const files = new Map<string, Buffer>();
let tags = input.tags;
- return {
+ const sandbox = {
currentSnapshotId: input.snapshotId ?? "",
delete: vi.fn().mockResolvedValue(undefined),
fs: {
@@ -60,6 +61,7 @@ function createMockSandbox(input: {
unlink: vi.fn().mockResolvedValue(undefined),
},
name: input.name,
+ sourceSnapshotId: input.sourceSnapshotId,
readFile: vi.fn(async (file: { path: string }): Promise<object | null> => {
const content = files.get(file.path);
return content === undefined ? null : Readable.from([content]);
@@ -74,7 +76,11 @@ function createMockSandbox(input: {
}
: createMockCommandResult(),
),
- snapshot: vi.fn().mockResolvedValue({ snapshotId: `${input.name}-snapshot` }),
+ // Like the SDK, a snapshot becomes the sandbox's `currentSnapshotId`.
+ snapshot: vi.fn(async () => {
+ sandbox.currentSnapshotId = `${input.name}-snapshot`;
+ return { snapshotId: sandbox.currentSnapshotId };
+ }),
status: input.status ?? "running",
stop: vi.fn().mockResolvedValue(undefined),
get tags() {
@@ -93,6 +99,106 @@ function createMockSandbox(input: {
},
),
};
+ return sandbox;
+}
+
+/**
+ * `Sandbox.create` returning `sandboxes` in order, except that a build's
+ * template pointer (named exactly by the template key) gets a fresh mock.
+ */
+function createSandboxesInOrder(...sandboxes: ReadonlyArray<ReturnType<typeof createMockSandbox>>) {
+ const queue = [...sandboxes];
+ return vi.fn(async (options: MockCreateOptions) =>
+ TEMPLATE_POINTER_NAME.test(options.name)
+ ? createMockSandbox({ ...mockFromCreateOptions(options), status: "stopped" })
+ : queue.shift(),
+ );
+}
+
+interface MockCreateOptions {
+ name: string;
+ source?: { snapshotId?: string; type: string };
+ tags?: Record<string, string>;
+}
+
+/** What a sandbox created with `options` reports, like the SDK: its name, tags and source snapshot. */
+function mockFromCreateOptions(options: MockCreateOptions) {
+ return {
+ name: options.name,
+ sourceSnapshotId: options.source?.type === "snapshot" ? options.source.snapshotId : undefined,
+ tags: options.tags,
+ };
+}
+
+const TEMPLATE_POINTER_NAME = /^eve-sbx-tpl-vercel-[0-9a-f]{32}$/u;
+
+/**
+ * A Sandbox API stand-in that keeps sandboxes by name and snapshots by ID the
+ * way the real one does: a taken name rejects `create` with 400, `delete`
+ * removes whatever holds the name, and a snapshot outlives its sandbox.
+ * `create` hands out `presets` in order before making fresh mocks.
+ */
+function createFakeVercelProvider(...presets: ReadonlyArray<ReturnType<typeof createMockSandbox>>) {
+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
+ const snapshots = new Set<string>();
+ const queue = [...presets];
+ const missing = () => Object.assign(new Error("Not found"), { response: { status: 404 } });
+ function add(sandbox: ReturnType<typeof createMockSandbox>) {
+ const name = sandbox.name;
+ sandboxes.set(name, sandbox);
+ sandbox.delete.mockImplementation(async () => {
+ if (!sandboxes.delete(name)) throw missing();
+ });
+ // Stopping a sandbox someone else deleted fails like the real API: 404.
+ sandbox.stop.mockImplementation(async () => {
+ if (sandboxes.get(name) !== sandbox) throw missing();
+ });
+ sandbox.snapshot.mockImplementation(async () => {
+ snapshots.add(`${name}-snapshot`);
+ return { snapshotId: `${name}-snapshot` };
+ });
+ return sandbox;
+ }
+ const sandboxModule = {
+ Sandbox: {
+ create: vi.fn(async (options: MockCreateOptions) => {
+ if (sandboxes.has(options.name)) {
+ throw Object.assign(
+ new Error(`A sandbox with the name '${options.name}' already exists for this project.`),
+ { response: { status: 400 } },
+ );
+ }
+ const preset = TEMPLATE_POINTER_NAME.test(options.name) ? undefined : queue.shift();
+ const sandbox = preset ?? createMockSandbox(mockFromCreateOptions(options));
+ sandbox.name = options.name;
+ return add(sandbox);
+ }),
+ get: vi.fn(async (options: { name: string }) => sandboxes.get(options.name) ?? null),
+ },
+ Snapshot: {
+ get: vi.fn(async (options: { snapshotId: string }) => {
+ if (!snapshots.has(options.snapshotId)) throw missing();
+ return { snapshotId: options.snapshotId, status: "created" };
+ }),
+ },
+ };
+ /** Puts a sandbox under the template key before any build runs. */
+ function seedTemplate(name: string, sandbox: ReturnType<typeof createMockSandbox>) {
+ sandbox.name = name;
+ add(sandbox);
+ }
+ const pointer = () =>
+ [...sandboxes.values()].find((sandbox) => TEMPLATE_POINTER_NAME.test(sandbox.name));
+ return { pointer, sandboxModule, sandboxes, seedTemplate, snapshots };
+}
+
+/** The template key a build of this provider configuration uses. */
+async function templateKeyOf(build: (module: object) => Promise<unknown>): Promise<string> {
+ const fake = createFakeVercelProvider();
+ await build(fake.sandboxModule);
+ const name = fake.pointer()?.name;
+ if (name === undefined) throw new Error("build published no template");
+ return name;
}
function createVercelSandbox(input: Parameters<typeof createVercelImplementation>[0] = {}) {
@@ -112,7 +218,7 @@ async function createTestVercelSession() {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi.fn().mockResolvedValueOnce(templateSandbox).mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -193,10 +299,10 @@ describe("createVercelSandbox", () => {
vi.stubEnv("VERCEL_TOKEN", "token_env");
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(createMockSandbox({ name: "template" }))
- .mockResolvedValueOnce(createMockSandbox({ name: "session" })),
+ create: createSandboxesInOrder(
+ createMockSandbox({ name: "template" }),
+ createMockSandbox({ name: "session" }),
+ ),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -214,6 +320,11 @@ describe("createVercelSandbox", () => {
const credentials = { projectId: "prj_env", teamId: "team_env", token: "token_env" };
expect(sandboxModule.Sandbox.create.mock.calls.map(([options]) => options)).toEqual([
expect.objectContaining({ ...credentials, image: VERCEL_EVE_SANDBOX_IMAGE }),
+ // The template pointer, then the session.
+ expect.objectContaining({
+ ...credentials,
+ source: expect.objectContaining({ type: "snapshot" }),
+ }),
expect.objectContaining({
...credentials,
source: expect.objectContaining({ type: "snapshot" }),
@@ -238,7 +349,8 @@ describe("createVercelSandbox", () => {
({ Sandbox: { create, get: vi.fn().mockResolvedValue(null) } }) as never,
});
await provider.prepare({ appRoot: "/tmp/test-app-root", ...input });
- return create.mock.calls[0]?.[0].name;
+ return create.mock.calls.find(([options]) => TEMPLATE_POINTER_NAME.test(options.name))?.[0]
+ .name;
}
const first = await prepareName({ sourceRevision: "revision-a" });
@@ -263,7 +375,7 @@ describe("createVercelSandbox", () => {
const templateSandbox = createMockSandbox({ name: "template-key" });
const sandboxModule = {
Sandbox: {
- create: vi.fn().mockResolvedValueOnce(templateSandbox),
+ create: createSandboxesInOrder(templateSandbox),
get: vi.fn().mockResolvedValueOnce(null),
},
};
@@ -287,7 +399,7 @@ describe("createVercelSandbox", () => {
const templateSandbox = createMockSandbox({ name: "template-key" });
const sandboxModule = {
Sandbox: {
- create: vi.fn().mockResolvedValueOnce(templateSandbox),
+ create: createSandboxesInOrder(templateSandbox),
get: vi.fn().mockResolvedValueOnce(null),
},
};
@@ -378,19 +490,7 @@ describe("createVercelSandbox", () => {
]) as never)
: createMockCommandResult(),
);
- const sandboxModule = {
- Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
- get: vi
- .fn()
- .mockResolvedValueOnce(null)
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(null),
- },
- };
+ const { sandboxModule } = createFakeVercelProvider(templateSandbox, sessionSandbox);
const provider = createTestVercelSandbox({
loadSandboxModule: async () => sandboxModule as never,
@@ -442,10 +542,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -477,10 +574,7 @@ describe("createVercelSandbox", () => {
it("applies a 30-minute default timeout to Sandbox.create", async () => {
const templateSandbox = createMockSandbox({ name: "template" });
const sessionSandbox = createMockSandbox({ name: "session" });
- const create = vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox);
+ const create = createSandboxesInOrder(templateSandbox, sessionSandbox);
const sandboxModule = {
Sandbox: {
create,
@@ -502,8 +596,9 @@ describe("createVercelSandbox", () => {
sandboxName: "session-key",
});
- expect(create).toHaveBeenCalledTimes(2);
- const [templateArgs, sessionArgs] = create.mock.calls;
+ // The template, its pointer, then the session.
+ expect(create).toHaveBeenCalledTimes(3);
+ const [templateArgs, , sessionArgs] = create.mock.calls;
expect(templateArgs?.[0]).toMatchObject({ timeout: 30 * 60 * 1_000 });
expect(sessionArgs?.[0]).toMatchObject({ timeout: 30 * 60 * 1_000 });
});
@@ -698,57 +793,251 @@ describe("createVercelSandbox", () => {
});
});
- it.fails("shares the template a concurrent build creates under the same name", async () => {
- vi.useFakeTimers();
- onTestFinished(() => {
- vi.useRealTimers();
+ describe("shared templates", () => {
+ const buildWith = (prepare?: () => Promise<void> | void) => async (sandboxModule: object) =>
+ await createTestVercelSandbox({
+ loadSandboxModule: async () => sandboxModule as never,
+ prepare,
+ }).prepare({ appRoot: "/tmp/test-app-root", seedFiles: [] });
+
+ /** The build-private sandboxes: everything a build created except the template pointer. */
+ const privateSandboxes = (fake: ReturnType<typeof createFakeVercelProvider>) =>
+ fake.sandboxModule.Sandbox.create.mock.results
+ .map((result) => result.value as Promise<ReturnType<typeof createMockSandbox>>)
+ .filter((_, index) => {
+ const name = fake.sandboxModule.Sandbox.create.mock.calls[index]?.[0].name ?? "";
+ return !TEMPLATE_POINTER_NAME.test(name);
+ });
+
+ it("lets two builds that look the template up at once both succeed", async () => {
+ const fake = createFakeVercelProvider();
+ let lookups = 0;
+ let releaseLookups!: () => void;
+ const bothLookedUp = new Promise<void>((resolve) => {
+ releaseLookups = resolve;
+ });
+ // Both builds look the template up before either one publishes it.
+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {
+ const found = fake.sandboxes.get(options.name) ?? null;
+ if (++lookups === 2) releaseLookups();
+ await bothLookedUp;
+ return found;
+ });
+ const build = buildWith();
+
+ const results = await Promise.allSettled([
+ build(fake.sandboxModule),
+ build(fake.sandboxModule),
+ ]);
+
+ expect(results.map((result) => result.status)).toEqual(["fulfilled", "fulfilled"]);
+ for (const result of results) {
+ if (result.status !== "fulfilled") continue;
+ expect(fake.snapshots.has(result.value.snapshotId ?? "")).toBe(true);
+ }
+ for (const sandbox of await Promise.all(privateSandboxes(fake))) {
+ expect(sandbox.snapshot).toHaveBeenCalledTimes(1);
+ }
+ // Only the pointer remains: each build deleted the sandbox it prepared in.
+ expect([...fake.sandboxes.keys()]).toEqual([fake.pointer()?.name]);
});
- const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
- let lookups = 0;
- let releaseLookups!: () => void;
- const bothLookedUp = new Promise<void>((resolve) => {
- releaseLookups = resolve;
+
+ it("never prepares one sandbox for two builds", async () => {
+ const fake = createFakeVercelProvider();
+ let finishFirst!: () => void;
+ const firstFinished = new Promise<void>((resolve) => {
+ finishFirst = resolve;
+ });
+ const prepare = vi
+ .fn<() => Promise<void>>()
+ .mockImplementationOnce(async () => await firstFinished)
+ .mockResolvedValue(undefined);
+ const build = buildWith(prepare);
+
+ const first = build(fake.sandboxModule);
+ await vi.waitFor(() => expect(prepare).toHaveBeenCalledTimes(1));
+ // The second build starts while the first is still preparing, and doesn't wait for it.
+ const second = await build(fake.sandboxModule);
+ finishFirst();
+ const firstResult = await first;
+
+ const [firstSandbox, secondSandbox] = await Promise.all(privateSandboxes(fake));
+ expect(firstResult).toEqual({ snapshotId: `${firstSandbox?.name}-snapshot` });
+ expect(second).toEqual({ snapshotId: `${secondSandbox?.name}-snapshot` });
+ expect(firstSandbox?.snapshot).toHaveBeenCalledTimes(1);
+ expect(secondSandbox?.snapshot).toHaveBeenCalledTimes(1);
+ // The first build to finish published the template; the other kept its own snapshot.
+ expect(fake.pointer()?.sourceSnapshotId).toBe(second.snapshotId);
+ });
+
+ it("reuses a published template without preparing again", async () => {
+ const fake = createFakeVercelProvider();
+ const prepare = vi.fn();
+ const build = buildWith(prepare);
+
+ const first = await build(fake.sandboxModule);
+ const creates = fake.sandboxModule.Sandbox.create.mock.calls.length;
+ const second = await build(fake.sandboxModule);
+
+ expect(second).toEqual(first);
+ expect(prepare).toHaveBeenCalledTimes(1);
+ expect(fake.sandboxModule.Sandbox.create).toHaveBeenCalledTimes(creates);
+ });
+
+ it("leaves no template behind when preparation fails, so the next build prepares", async () => {
+ const fake = createFakeVercelProvider();
+ const prepare = vi
+ .fn<() => Promise<void>>()
+ .mockRejectedValueOnce(new Error("prepare failed"))
+ .mockResolvedValue(undefined);
+ const build = buildWith(prepare);
+
+ await expect(build(fake.sandboxModule)).rejects.toThrow(/prepare failed/);
+ expect(fake.sandboxes.size).toBe(0);
+
+ const next = await build(fake.sandboxModule);
+ expect(prepare).toHaveBeenCalledTimes(2);
+ expect(fake.pointer()?.sourceSnapshotId).toBe(next.snapshotId);
+ });
+
+ it("ignores the automatic snapshot of a template whose build was abandoned", async () => {
+ const templateKey = await templateKeyOf(buildWith());
+ const fake = createFakeVercelProvider();
+ // A persistent template sandbox Vercel snapshotted when its timeout stopped it mid-preparation.
+ const abandoned = createMockSandbox({
+ name: templateKey,
+ snapshotId: "abandoned-auto-snapshot",
+ status: "stopped",
+ });
+ fake.seedTemplate(templateKey, abandoned);
+ fake.snapshots.add("abandoned-auto-snapshot");
+ const prepare = vi.fn();
+
+ const result = await buildWith(prepare)(fake.sandboxModule);
+
+ expect(result.snapshotId).not.toBe("abandoned-auto-snapshot");
+ expect(fake.snapshots.has(result.snapshotId ?? "")).toBe(true);
+ expect(prepare).toHaveBeenCalledTimes(1);
+ expect(abandoned.snapshot).not.toHaveBeenCalled();
+ expect(fake.pointer()?.sourceSnapshotId).toBe(result.snapshotId);
+ });
+
+ it("lets two builds replace the same stale template without deleting each other's work", async () => {
+ const templateKey = await templateKeyOf(buildWith());
+ const fake = createFakeVercelProvider();
+ // A pointer to a snapshot that has since expired.
+ fake.seedTemplate(
+ templateKey,
+ createMockSandbox({
+ name: templateKey,
+ sourceSnapshotId: "expired",
+ status: "stopped",
+ }),
+ );
+ let lookups = 0;
+ let releaseLookups!: () => void;
+ const bothLookedUp = new Promise<void>((resolve) => {
+ releaseLookups = resolve;
+ });
+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {
+ const found = fake.sandboxes.get(options.name) ?? null;
+ if (++lookups === 2) releaseLookups();
+ await bothLookedUp;
+ return found;
+ });
+ const build = buildWith();
+
+ const results = await Promise.all([build(fake.sandboxModule), build(fake.sandboxModule)]);
+
+ const snapshotIds = results.map((result) => result.snapshotId ?? "");
+ expect(new Set(snapshotIds).size).toBe(2);
+ for (const snapshotId of snapshotIds) expect(fake.snapshots.has(snapshotId)).toBe(true);
+ for (const sandbox of await Promise.all(privateSandboxes(fake))) {
+ expect(sandbox.snapshot).toHaveBeenCalledTimes(1);
+ expect(sandbox.delete).toHaveBeenCalledTimes(1);
+ }
+ expect(snapshotIds).toContain(fake.pointer()?.sourceSnapshotId);
});
- const sandboxModule = {
- Sandbox: {
- create: vi.fn(async (options: { name: string }) => {
- if (sandboxes.has(options.name)) {
- throw Object.assign(
- new Error(
- `A sandbox with the name '${options.name}' already exists for this project.`,
- ),
- { response: { status: 400 } },
- );
- }
- const template = createMockSandbox({ name: options.name });
- template.snapshot.mockImplementation(async () => {
- template.currentSnapshotId = `${options.name}-snapshot`;
- return { snapshotId: template.currentSnapshotId };
+
+ it("keeps a build's snapshot when another build deletes its new pointer mid-publish", async () => {
+ const templateKey = await templateKeyOf(buildWith());
+ const fake = createFakeVercelProvider();
+ const stale = createMockSandbox({
+ name: templateKey,
+ sourceSnapshotId: "expired",
+ status: "stopped",
+ });
+ fake.seedTemplate(templateKey, stale);
+ let lookups = 0;
+ let releaseLookups!: () => void;
+ const bothLookedUp = new Promise<void>((resolve) => {
+ releaseLookups = resolve;
+ });
+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {
+ const found = fake.sandboxes.get(options.name) ?? null;
+ if (++lookups === 2) releaseLookups();
+ await bothLookedUp;
+ return found;
+ });
+ /*
+ * A deletes the stale pointer and creates its own; before A stops it,
+ * B's delete of the stale pointer it saw removes A's new one by name.
+ */
+ let pointerCreated!: () => void;
+ const firstPointerCreated = new Promise<void>((resolve) => {
+ pointerCreated = resolve;
+ });
+ let staleDeletedTwice!: () => void;
+ const secondStaleDelete = new Promise<void>((resolve) => {
+ staleDeletedTwice = resolve;
+ });
+ const deleteByName = stale.delete.getMockImplementation();
+ stale.delete.mockImplementation(async () => {
+ if (stale.delete.mock.calls.length === 1) return await deleteByName?.();
+ await firstPointerCreated;
+ await deleteByName?.();
+ staleDeletedTwice();
+ });
+ const create = fake.sandboxModule.Sandbox.create.getMockImplementation();
+ let pointers = 0;
+ fake.sandboxModule.Sandbox.create.mockImplementation(async (options: MockCreateOptions) => {
+ const sandbox = await create!(options);
+ if (TEMPLATE_POINTER_NAME.test(options.name) && ++pointers === 1) {
+ const stop = sandbox.stop.getMockImplementation();
+ sandbox.stop.mockImplementation(async () => {
+ pointerCreated();
+ await secondStaleDelete;
+ await stop?.();
});
- sandboxes.set(options.name, template);
- return template;
- }),
- // Both builds look the template up before either one creates it.
- get: vi.fn(async (options: { name: string }) => {
- const found = sandboxes.get(options.name) ?? null;
- if (++lookups === 2) releaseLookups();
- await bothLookedUp;
- return found;
- }),
- },
- };
- const build = async () =>
+ }
+ return sandbox;
+ });
+ const build = buildWith();
+
+ const results = await Promise.allSettled([
+ build(fake.sandboxModule),
+ build(fake.sandboxModule),
+ ]);
+
+ expect(results.map((result) => result.status)).toEqual(["fulfilled", "fulfilled"]);
+ for (const result of results) {
+ if (result.status !== "fulfilled") continue;
+ expect(fake.snapshots.has(result.value.snapshotId ?? "")).toBe(true);
+ }
+ // The second build's pointer replaced the one it deleted.
+ expect(pointers).toBe(2);
+ });
+
+ it("keeps the author's tags on the published template", async () => {
+ const fake = createFakeVercelProvider();
+
await createTestVercelSandbox({
- loadSandboxModule: async () => sandboxModule as never,
+ createOptions: { tags: { team: "x" } },
+ loadSandboxModule: async () => fake.sandboxModule as never,
}).prepare({ appRoot: "/tmp/test-app-root", seedFiles: [] });
- const builds = Promise.allSettled([build(), build()]);
- await vi.runAllTimersAsync();
-
- const [template] = sandboxes.values();
- const shared = { status: "fulfilled", value: { snapshotId: `${template?.name}-snapshot` } };
- expect(await builds).toEqual([shared, shared]);
- expect(template?.snapshot).toHaveBeenCalledTimes(1);
+ expect(fake.pointer()?.tags).toEqual({ team: "x" });
+ });
});
it("forwards author source to template create as the base layer", async () => {
@@ -768,10 +1057,7 @@ describe("createVercelSandbox", () => {
snapshotId: "author-snap",
});
const sessionSandbox = createMockSandbox({ name: "session" });
- const create = vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox);
+ const create = createSandboxesInOrder(templateSandbox, sessionSandbox);
const sandboxModule = {
Sandbox: {
create,
@@ -794,8 +1080,9 @@ describe("createVercelSandbox", () => {
sandboxName: "session-key",
});
- expect(create).toHaveBeenCalledTimes(2);
- const [templateArgs, sessionArgs] = create.mock.calls;
+ // The template, its pointer, then the session.
+ expect(create).toHaveBeenCalledTimes(3);
+ const [templateArgs, , sessionArgs] = create.mock.calls;
expect(templateArgs?.[0]).toMatchObject({
source: { snapshotId: "author-snap", type: "snapshot" },
});
@@ -878,10 +1165,7 @@ describe("createVercelSandbox", () => {
});
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -919,10 +1203,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session", status: "stopped" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1003,10 +1284,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1050,10 +1328,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1139,10 +1414,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1183,10 +1455,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1228,10 +1497,7 @@ describe("createVercelSandbox", () => {
const sessionSandbox = createMockSandbox({ name: "session" });
const sandboxModule = {
Sandbox: {
- create: vi
- .fn()
- .mockResolvedValueOnce(templateSandbox)
- .mockResolvedValueOnce(sessionSandbox),
+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1289,7 +1555,7 @@ describe("createVercelSandbox", () => {
const sandboxModule = {
Sandbox: {
- create: vi.fn().mockResolvedValueOnce(templateSandbox),
+ create: createSandboxesInOrder(templateSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
@@ -1331,7 +1597,7 @@ describe("createVercelSandbox", () => {
const sandboxModule = {
Sandbox: {
- create: vi.fn().mockResolvedValueOnce(templateSandbox),
+ create: createSandboxesInOrder(templateSandbox),
get: vi.fn().mockResolvedValue(null),
},
};
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.ts b/packages/eve/src/execution/sandbox/bindings/vercel.ts
index 68d7b29fe..dc899f2b5 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.ts
@@ -1,3 +1,5 @@
+import { randomBytes } from "node:crypto";
+
import type { VercelSandboxSession } from "#public/sandbox/vercel.js";
import { VERCEL_EVE_SANDBOX_IMAGE } from "#execution/sandbox/bindings/eve-image.js";
import {
@@ -54,7 +56,10 @@ import {
import { withToolSessionRetention } from "#execution/sandbox/bindings/vercel-tool-sessions.js";
import { isToolSessionId } from "#execution/tool-session/id.js";
import { withToolSessionSandboxes } from "#execution/tool-session/sandbox.js";
-import { getNamedVercelSandbox } from "#execution/sandbox/bindings/vercel-lookup.js";
+import {
+ getNamedVercelSandbox,
+ isVercelSnapshotCreated,
+} from "#execution/sandbox/bindings/vercel-lookup.js";
import {
deleteUnusableVercelSandbox,
deleteVercelSandbox,
@@ -115,9 +120,9 @@ export function createVercelSandbox(
const loadDeleteSandboxModule =
input.loadDeleteSandboxModule ??
(async () => await import("#compiled/@vercel/sandbox/index.js"));
- const createOptions: VercelCreateOptions = {
- timeout: DEFAULT_SANDBOX_TIMEOUT_MS,
+ const createOptions: ResolvedVercelCreateOptions = {
...input.createOptions,
+ timeout: input.createOptions?.timeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,
};
const createSandbox = input.createSandbox ?? createVercelEveImageSandbox;
@@ -218,10 +223,10 @@ export function createVercelSandbox(
: undefined,
resources: sandboxProviderResourceIdentity(context.resources),
sourceRevision: context.sourceRevision,
- version: 2,
+ version: 3,
}).slice(0, 32)}`;
try {
- const outcome = await ensureTemplateWithUnavailableRetry({
+ const snapshotId = await ensureTemplate({
createOptions,
createSandbox,
loadSandboxModule,
@@ -230,7 +235,7 @@ export function createVercelSandbox(
seedFiles,
templateKey,
});
- return { snapshotId: outcome.template.snapshotId };
+ return { snapshotId };
} catch (error) {
throw new Error(`Failed to prepare Vercel sandbox snapshot: ${errorMessage(error)}`, {
cause: error,
@@ -266,12 +271,6 @@ export function createVercelSandbox(
return withToolSessionSandboxes(implementation);
}
-interface VercelSandboxTemplateRecord {
- readonly sandboxName: string;
- readonly snapshotId: string;
- readonly templateKey: string;
-}
-
function vercelSessionName(
sessionId: string,
options: Readonly<VercelSandboxRuntimeOptions> | undefined,
@@ -317,126 +316,158 @@ function requirePreparedVercelTemplate(
return artifact.snapshotId === undefined ? {} : { snapshotId: artifact.snapshotId };
}
-interface EnsureTemplateOutcome {
- readonly template: VercelSandboxTemplateRecord;
-}
-
type VercelSeedFile = { readonly content: string | Uint8Array; readonly path: string };
+/** Create options with the default sandbox timeout applied once. */
+type ResolvedVercelCreateOptions = VercelCreateOptions & { readonly timeout: number };
+
interface EnsureTemplateInput {
readonly prepareSandbox?: (sandbox: SandboxSession) => void | Promise<void>;
- readonly createOptions: VercelCreateOptions;
+ readonly createOptions: ResolvedVercelCreateOptions;
readonly createSandbox: CreateVercelSandbox;
readonly loadSandboxModule: () => Promise<VercelModule>;
readonly log?: (message: string) => void;
readonly seedFiles: ReadonlyArray<VercelSeedFile>;
- readonly tags?: Record<string, string>;
readonly templateKey: string;
}
-async function ensureTemplateWithUnavailableRetry(
- input: EnsureTemplateInput,
-): Promise<EnsureTemplateOutcome> {
- try {
- return await ensureTemplate(input);
- } catch (error) {
- if (!isVercelSnapshotUnavailableError(error) && !isVercelSandboxMissingError(error)) {
- throw error;
- }
- input.log?.("cached template disappeared; rebuilding sandbox template");
- return await ensureTemplate(input);
- }
-}
-
/**
- * Creates or refreshes one named Vercel sandbox template and returns the
- * resulting snapshot metadata along with whether an existing snapshot
- * was reused. This runs only from the provider's preparation phase.
+ * Returns the prepared snapshot for one template key. Builds of the same
+ * revision share it through a pointer: a stopped sandbox named by the key,
+ * created from a snapshot that finished preparing. Preparation itself runs
+ * in a private sandbox no other build can see, so nothing under the shared
+ * name ever holds unfinished work, and deleting a stale pointer can never
+ * remove another build's preparation.
*/
-async function ensureTemplate(input: EnsureTemplateInput): Promise<EnsureTemplateOutcome> {
+async function ensureTemplate(input: EnsureTemplateInput): Promise<string> {
const sandboxModule = await input.loadSandboxModule();
- let sandbox = await getNamedVercelSandbox({
+ const pointer = await getNamedVercelSandbox({
createOptions: input.createOptions,
sandboxModule,
sandboxName: input.templateKey,
});
- const tags = resolveVercelSandboxTags(input.createOptions.tags, input.tags);
- const authorSnapshotId = extractAuthorSnapshotId(input.createOptions);
-
- if (sandbox !== null && isUnprovisionedTerminalTemplateSandbox(sandbox, authorSnapshotId)) {
- await sandbox.delete();
- sandbox = null;
- }
-
- if (sandbox === null) {
- sandbox = await input.createSandbox({
+ const publishedSnapshotId = pointer?.sourceSnapshotId;
+ if (
+ publishedSnapshotId !== undefined &&
+ (await isVercelSnapshotCreated({
+ createOptions: input.createOptions,
sandboxModule,
- createOptions: withBaseSetupNetworkPolicy({
- ...input.createOptions,
- name: input.templateKey,
- persistent: true,
- tags: tags,
- }),
- });
- } else {
- await ensureVercelSandboxTags(sandbox, tags);
+ snapshotId: publishedSnapshotId,
+ }))
+ ) {
+ input.log?.("reusing prepared sandbox template");
+ return publishedSnapshotId;
}
+ const snapshotId = await prepareTemplateSnapshot(input, sandboxModule);
/*
- * A non-empty `currentSnapshotId` normally means "this template was
- * prewarmed in a previous run — reuse it." But with an author-supplied
- * `source: snapshot`, the SDK pre-populates `currentSnapshotId` with
- * the *author's* snapshotId both on a fresh create and on every
- * subsequent `getNamedSandbox` reuse until we run our own snapshot.
- * So we ignore that exact value: it's the author's base layer, not a
- * framework snapshot, and we still owe `ensureSandboxWorkingDirectory`,
- * preparation, seed file writes, and `sandbox.snapshot()` on top.
+ * The pointer only saves later builds a preparation; this build's snapshot
+ * is already valid. So publishing never fails the build, including when a
+ * build replacing the same stale pointer deletes this one mid-publish.
*/
- const frameworkSnapshotId =
- typeof sandbox.currentSnapshotId === "string" &&
- sandbox.currentSnapshotId.length > 0 &&
- sandbox.currentSnapshotId !== authorSnapshotId
- ? sandbox.currentSnapshotId
- : null;
-
- if (frameworkSnapshotId !== null) {
- return {
- template: {
- sandboxName: sandbox.name,
- snapshotId: frameworkSnapshotId,
- templateKey: input.templateKey,
- },
- };
- }
-
- input.log?.("preparing base runtime inside sandbox");
- await ensureVercelSandboxBaseRuntime(sandbox);
- await applyInitialVercelNetworkPolicy(sandbox, input.createOptions.networkPolicy);
-
- const templateSession = buildSandboxSession(
- createVercelInternalSandboxSession(sandbox, input.createOptions.env),
- createVercelNetworkPolicySetter(sandbox),
+ await publishTemplatePointer(input, sandboxModule, pointer, snapshotId).catch(
+ (error: unknown) => {
+ input.log?.(`could not publish sandbox template: ${errorMessage(error)}`);
+ },
);
+ return snapshotId;
+}
- await writeVercelSandboxSeedFiles({
- sandbox,
- seedFiles: input.seedFiles,
- session: templateSession,
+/** Prepares the template in a sandbox only this build knows, and returns its snapshot. */
+async function prepareTemplateSnapshot(
+ input: EnsureTemplateInput,
+ sandboxModule: VercelModule,
+): Promise<string> {
+ /*
+ * Not persistent: a sandbox this build abandons (killed, timed out) is
+ * discarded without an automatic snapshot, and its name is unique, so no
+ * other build ever finds it.
+ */
+ const sandbox = await input.createSandbox({
+ sandboxModule,
+ createOptions: withBaseSetupNetworkPolicy({
+ ...input.createOptions,
+ name: `${input.templateKey}-${randomBytes(4).toString("hex")}`,
+ persistent: false,
+ }),
});
+ try {
+ input.log?.("preparing base runtime inside sandbox");
+ await ensureVercelSandboxBaseRuntime(sandbox);
+ await applyInitialVercelNetworkPolicy(sandbox, input.createOptions.networkPolicy);
+
+ const templateSession = buildSandboxSession(
+ createVercelInternalSandboxSession(sandbox, input.createOptions.env),
+ createVercelNetworkPolicySetter(sandbox),
+ );
+
+ await writeVercelSandboxSeedFiles({
+ sandbox,
+ seedFiles: input.seedFiles,
+ session: templateSession,
+ });
- input.log?.("running sandbox preparation");
- await input.prepareSandbox?.(
- createLoggingSandboxSession({ log: input.log, session: templateSession }),
- );
+ input.log?.("running sandbox preparation");
+ await input.prepareSandbox?.(
+ createLoggingSandboxSession({ log: input.log, session: templateSession }),
+ );
+
+ // The returned snapshot, not the handle's cached `currentSnapshotId`, which the SDK may not refresh.
+ return (await sandbox.snapshot()).snapshotId;
+ } finally {
+ /*
+ * A snapshot outlives its source sandbox, so the private sandbox is never
+ * needed again. Failing to delete it doesn't change this build's result:
+ * it's not persistent, and no other build looks it up.
+ */
+ await sandbox.delete().catch((error: unknown) => {
+ input.log?.(`could not delete sandbox ${sandbox.name}: ${errorMessage(error)}`);
+ });
+ }
+}
- const snapshot = await sandbox.snapshot();
- return {
- template: {
- sandboxName: sandbox.name,
- snapshotId: snapshot.snapshotId,
- templateKey: input.templateKey,
- },
- };
+/**
+ * Records a finished snapshot under the template key, replacing a stale
+ * pointer. When another build published first, its snapshot is as valid as
+ * this one, and this build keeps its own: there is nothing to read back.
+ */
+async function publishTemplatePointer(
+ input: EnsureTemplateInput,
+ sandboxModule: VercelModule,
+ stalePointer: VercelSandbox | null,
+ snapshotId: string,
+): Promise<void> {
+ if (stalePointer !== null) {
+ try {
+ await stalePointer.delete();
+ } catch (error) {
+ // Another build that saw the same stale pointer deleted it first.
+ if (!isVercelSandboxMissingError(error)) throw error;
+ }
+ }
+ // A snapshot source excludes `image`, `runtime`, and any authored source.
+ const {
+ image: _image,
+ runtime: _runtime,
+ source: _source,
+ ...createOptions
+ } = input.createOptions;
+ let pointer: VercelSandbox;
+ try {
+ pointer = await input.createSandbox({
+ sandboxModule,
+ createOptions: {
+ ...createOptions,
+ name: input.templateKey,
+ persistent: false,
+ source: { snapshotId, type: "snapshot" },
+ },
+ });
+ } catch (error) {
+ if (isVercelSandboxNameConflictError(error)) return;
+ throw error;
+ }
+ await stopVercelSandbox(pointer);
}
interface EnsureSessionInput {
@@ -680,38 +711,6 @@ async function resolveVercelWritePath(
return resolved;
}
-function isUnprovisionedTerminalTemplateSandbox(
- sandbox: VercelSandbox,
- authorSnapshotId: string | undefined,
-): boolean {
- const currentSnapshotId = sandbox.currentSnapshotId;
- if (
- typeof currentSnapshotId === "string" &&
- currentSnapshotId.length > 0 &&
- currentSnapshotId !== authorSnapshotId
- ) {
- return false;
- }
-
- return (
- sandbox.status === "aborted" || sandbox.status === "failed" || sandbox.status === "stopped"
- );
-}
-
-/**
- * Pulls the snapshotId out of an author-supplied `source: { type:
- * "snapshot", ... }`. Returns undefined for git/tarball sources or when
- * no source was supplied — those don't seed `currentSnapshotId` with a
- * pre-existing value the way snapshot sources do.
- */
-function extractAuthorSnapshotId(createOptions: VercelCreateOptions): string | undefined {
- const source = createOptions.source;
- if (source?.type === "snapshot" && typeof source.snapshotId === "string") {
- return source.snapshotId;
- }
- return undefined;
-}
-
/**
* 30 minutes. The `@vercel/sandbox` SDK defaults to 5 minutes which is
* too short for multi-step workflows — the VM expires between steps.