Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion biome.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,8 @@
"child_process": {
"importNames": ["execSync", "spawnSync", "execFileSync"],
"message": "Sync subprocesses freeze the serving event loop (Electron main / host-service / pty-daemon) until the child exits — every request queues behind them. Prefer async spawn/execFile: the caller awaits the same result, but the loop keeps serving while the child runs. Git reads belong in the worker pools."
}
},
"@vercel/sandbox": "Most calls on a raw sandbox handle resume a stopped box. Use the functions in packages/trpc/src/lib/sandbox, where only a wake or a create may resume one."
}
}
}
Expand Down Expand Up @@ -92,6 +93,18 @@
}
}
},
{
// The one place that holds sandbox handles, and the release tooling that
// builds its own boxes. Neither runs on a desktop or host-service loop.
"includes": ["packages/trpc/src/lib/sandbox/**", "packages/sandbox/**"],
"linter": {
"rules": {
"style": {
"noRestrictedImports": "off"
}
}
}
},
{
// Legacy on-loop sync-subprocess call sites, frozen by the
// no-*-blocking ratchet tests — delete entries here as they're fixed.
Expand Down
17 changes: 11 additions & 6 deletions docs/cloud-sandbox-mismatches.md
Original file line number Diff line number Diff line change
Expand Up @@ -790,12 +790,17 @@ timeout a moment later is resumed by the next call on that object, and no
code chose to start it. Measured: 9 sessions in a week started 0.8–1.5 s after
a timeout stop. `wakeSandbox` passes `onResume` to `Sandbox.get` and runs
`beforeResume` (which authorizes the boot) for such a session; a refused one is
stopped at once. A top-up goes through the session, which never resumes.
Other callers on a box read `running` are covered only by the reconcile, which
adopts any session that has no boot row within one run: promote's
`source.snapshot()` (wrapped in `withResume`), and `applySandboxPolicy`, whose
`update` does not resume in SDK 4.0.0 but would if a later SDK wrapped it.
`provisionSandbox` on a box it already made is covered by its own boot.
stopped at once. **What we did:** only `wakeSandbox` and `provisionSandbox`
get a full handle (`getSandboxToWake` in `vercel.ts`). Every other caller gets
`getSandbox`, typed to the members that cannot resume (`stop`, `update`,
`delete`, `listSessions`, `currentSession()` and reads), and acts on a running
box through the session, whose calls answer 410 or 422 on a stopped one
instead. Top-up and the credential refresh treat that answer as "not
running"; promote builds a stopped source's golden from the snapshot its
stop took (measured: a create from that automatic snapshot has the stopped
box's files). An HTTP request to a stopped box's port does not resume it
either: measured, it answers `410 This sandbox was stopped` and no session
starts, so the archive hook and other host-service calls cannot wake a box.

**`stop()` returns before the stop's snapshot is current.** The sandbox is
still `stopping` when the call resolves, and a fork taken then boots from
Expand Down
1 change: 1 addition & 0 deletions packages/sandbox/src/real-sandbox.ts
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,7 @@ for (;;) {
}
}
const woken = await wakeSandbox({ providerSandboxId: name, claim });
if (!woken) throw new Error(`${name} did not wake`);
log(
`host-service answered at ${woken.hostTarget} (${Date.now() - started} ms since start)`,
);
Expand Down
220 changes: 190 additions & 30 deletions packages/trpc/src/lib/sandbox/vercel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,22 @@ import {
setSystemTime,
test,
} from "bun:test";
import { Drive, Sandbox } from "@vercel/sandbox";
import { APIError, Drive, Sandbox } from "@vercel/sandbox";
import { stub } from "../../../test/stub";
import {
agentToolsMounts,
applySandboxPolicy,
deleteSandbox,
describeSandbox,
findSandboxSession,
listActiveWorkspaceSandboxes,
listSandboxSessions,
promoteSandboxToEnvironment,
type SandboxClaim,
SandboxUnavailableError,
SESSION_TIMEOUT_MS,
sandboxExists,
stopSandbox,
topUpSandboxSession,
wakeSandbox,
} from "./vercel";
Expand Down Expand Up @@ -153,65 +159,198 @@ describe("listSandboxSessions", () => {
});
});

describe("promoteSandboxToEnvironment", () => {
const sourceCalls: string[] = [];
const source = {
status: "running",
region: "iad1",
/**
* A box the way the SDK presents it: the handle keeps the status it was read
* with, a session call on a stopped session fails, and a handle call resumes
* it first, which `resumes` records.
*/
function fakeBox(read: "running" | "stopped") {
const box = {
live: read,
snapshotId: "snap_stop_0",
resumes: [] as string[],
};
const stoppedError = () => new APIError(new Response(null, { status: 410 }));
const session = {
sessionId: "sess_A",
vcpus: 4,
currentSession: () => ({ sessionId: "sess_A" }),
snapshot: async () => {
sourceCalls.push("snapshot");
return { snapshotId: "snap_1" };
update: async () => {
if (box.live !== "running") throw stoppedError();
},
writeFiles: async () => {
sourceCalls.push("writeFiles");
extendTimeout: async () => {
if (box.live !== "running") throw stoppedError();
},
runCommand: async () => {
sourceCalls.push("runCommand");
snapshot: async () => {
if (box.live !== "running") throw stoppedError();
box.live = "stopped";
return { snapshotId: "snap_now" };
},
};
const resumingCall = (method: string) => async () => {
if (box.live !== "running") {
box.resumes.push(method);
box.live = "running";
}
return method === "snapshot" ? session.snapshot() : undefined;
};
const handle = () => ({
name: "ws-box",
status: box.live,
region: "iad1",
vcpus: 4,
currentSnapshotId: box.snapshotId,
expiresAt: new Date(NOW + HOUR / 2),
domain: () => "https://box.test",
currentSession: () => session,
update: async (params: { networkPolicy?: unknown }) => {
if (params.networkPolicy && handleStatus === "running") {
await session.update();
}
},
mkDir: async () => {
sourceCalls.push("mkDir");
delete: async () => {},
listSessions: async () => (async function* () {})(),
snapshot: resumingCall("snapshot"),
runCommand: resumingCall("runCommand"),
writeFiles: resumingCall("writeFiles"),
extendTimeout: resumingCall("extendTimeout"),
});
let handleStatus: string = read;
const stopNow = () => {
box.live = "stopped";
box.snapshotId = "snap_stop_1";
};
return {
box,
stopNow,
get: async () => {
const read = handle();
handleStatus = read.status;
return read;
},
};
}

/** The idle timeout ends the session after the first read, before any call. */
function stopsAfterRead(fake: ReturnType<typeof fakeBox>) {
const read = fake.get;
let reads = 0;
fake.get = async () => {
const handle = await read();
if (++reads === 1) fake.stopNow();
return handle;
};
return fake;
}

describe("a caller that is not a wake leaves a stopped box stopped", () => {
let fake = fakeBox("stopped");
stub(Sandbox, { get: async () => fake.get() });

test("reads, stops, deletes, session lists, policy and top-up", async () => {
fake = fakeBox("stopped");
await describeSandbox("ws-box");
await sandboxExists("ws-box");
await stopSandbox("ws-box");
await listSandboxSessions("ws-box", NOW - HOUR);
await findSandboxSession("ws-box", null);
expect(
await applySandboxPolicy({
providerSandboxId: "ws-box",
networkPolicy: {},
}),
).toBe("not-running");
expect(await topUpSandboxSession("ws-box")).toBeNull();
await deleteSandbox("ws-box");
expect(fake.box).toMatchObject({ live: "stopped", resumes: [] });
});

test("policy and top-up find the box stopped since they read it running", async () => {
fake = stopsAfterRead(fakeBox("running"));
expect(
await applySandboxPolicy({
providerSandboxId: "ws-box",
networkPolicy: {},
}),
).toBe("not-running");
expect(fake.box).toMatchObject({ live: "stopped", resumes: [] });

fake = stopsAfterRead(fakeBox("running"));
expect(await topUpSandboxSession("ws-box")).toBeNull();
expect(fake.box).toMatchObject({ live: "stopped", resumes: [] });
});
});

describe("promoteSandboxToEnvironment", () => {
let fake = fakeBox("running");
let sourceSnapshot: string | undefined;
let createTags: unknown;
const golden = {
currentSnapshotId: "snap_golden_0",
runCommand: async () => {},
stop: async () => {},
};
let createTags: unknown;
stub(Sandbox, {
get: async ({ name }: { name: string }) =>
name === "ws-box"
? source
? fake.get()
: { status: "stopped", currentSnapshotId: "snap_golden_1" },
create: async (params: { tags: unknown }) => {
create: async (params: {
tags: unknown;
source: { snapshotId: string };
}) => {
createTags = params.tags;
sourceSnapshot = params.source.snapshotId;
return golden;
},
});
const promote = () =>
promoteSandboxToEnvironment({
sourceSandbox: "ws-box",
goldenName: "env-1",
organizationId: "org_1",
});

test("ends the source's session for the snapshot and leaves its restart to the caller", async () => {
expect(
await promoteSandboxToEnvironment({
sourceSandbox: "ws-box",
goldenName: "env-1",
organizationId: "org_1",
}),
).toEqual({
test("snapshots a running source through its session and leaves its restart to the caller", async () => {
fake = fakeBox("running");
expect(await promote()).toEqual({
goldenName: "env-1",
region: "iad1",
stopped: { sessionId: "sess_A" },
});
expect(sourceCalls).toEqual(["snapshot"]);
expect(sourceSnapshot).toBe("snap_now");
expect(createTags).toEqual({ kind: "environment", org: "org_1" });
expect(fake.box.resumes).toEqual([]);
});

test("builds from a stopped source's last stop without resuming it", async () => {
fake = fakeBox("stopped");
expect((await promote()).stopped).toBeNull();
expect(sourceSnapshot).toBe("snap_stop_0");
expect(fake.box).toMatchObject({ live: "stopped", resumes: [] });
});

test("a stopped source with no snapshot to build from fails at once", async () => {
fake = fakeBox("stopped");
fake.box.snapshotId = undefined;
sourceSnapshot = undefined;
await expect(promote()).rejects.toBeInstanceOf(SandboxUnavailableError);
expect(sourceSnapshot).toBeUndefined();
expect(fake.box.resumes).toEqual([]);
});

test("a source that stops before its snapshot is built from that stop's snapshot", async () => {
fake = stopsAfterRead(fakeBox("running"));
await promote();
expect(sourceSnapshot).toBe("snap_stop_1");
expect(fake.box).toMatchObject({ live: "stopped", resumes: [] });
});
});

describe("wakeSandbox", () => {
type Box = { memoryMb: number; vcpus: number };
let running: boolean;
let onResume: (sandbox: unknown) => Promise<void>;
const calls: string[] = [];
const box = {
get status() {
return running ? "running" : "stopped";
Expand All @@ -220,13 +359,19 @@ describe("wakeSandbox", () => {
vcpus: 4,
domain: () => "https://box.test",
currentSession: () => ({ vcpus: 8, sessionId: "sess_new" }),
update: async () => {},
writeFiles: async () => {},
update: async () => {
calls.push("update");
},
writeFiles: async () => {
calls.push("writeFiles");
},
// The SDK's withResume: a call on a stopped session resumes it, then retries.
extendTimeout: async () => {
calls.push("extendTimeout");
await onResume(box);
},
runCommand: async () => {
calls.push("runCommand");
await onResume(box);
throw new Error("stop before settle");
},
Expand Down Expand Up @@ -278,6 +423,21 @@ describe("wakeSandbox", () => {
running = false;
expect(await wake()).toEqual([{ memoryMb: 8192, vcpus: 4 }]);
});

test("a wake only for a running box leaves a box that stopped since the caller looked", async () => {
running = false;
calls.length = 0;
const woken = await wakeSandbox({
providerSandboxId: "ws-box",
claim: { vcpus: 4, identity, networkPolicy: {} } as never,
onlyIfRunning: true,
beforeResume: async () => {
calls.push("beforeResume");
},
});
expect(woken).toBeNull();
expect(calls).toEqual([]);
});
});

describe("listActiveWorkspaceSandboxes", () => {
Expand Down
Loading
Loading