@cloudflare/sandbox 1.0.0-rc.1 → 1.0.0

package/README.md

@@ -10,8 +10,8 @@ Run untrusted or generated code in a Linux sandbox that belongs to one user, tas
 A sandbox is a Durable Object and the [Container](https://developers.cloudflare.com/containers/) it starts. The Durable Object starts the instance and runs commands with the Container API on `this.ctx.container`. `@cloudflare/sandbox` adds three things that API does not have:
 
 - [`Files`](https://developers.cloudflare.com/sandbox/reference/files/) streams files in and out of the running instance and reports Linux errors such as `ENOENT`.
-- [`S3Mounts`](https://developers.cloudflare.com/sandbox/reference/s3-mounts/) mounts an S3-compatible bucket at a path. Your Worker signs each storage request, so the credentials never enter the sandbox.
-- [`DirectoryBackups`](https://developers.cloudflare.com/sandbox/reference/directory-backups/) saves a directory to R2 and restores it into any Container, including one on a newer image. The Container reaches only the one object each operation needs.
+- [`S3Mount`](https://developers.cloudflare.com/sandbox/reference/s3-mounts/) mounts an S3-compatible bucket at a path. Your Worker signs each storage request, so the credentials never enter the sandbox.
+- [`DirectoryBackup`](https://developers.cloudflare.com/sandbox/reference/directory-backups/) saves a directory to R2 and restores it into any Container, including one on a newer image. The Container reaches only the one object each operation needs.
 
 **[Read the documentation](https://developers.cloudflare.com/sandbox/)**
 
@@ -82,14 +82,14 @@ Version 0.x provided a `Sandbox` class that owned the Container and ran commands
 
 ## Repository
 
-| Path                                           | Contents                                                                              |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
-| [`packages/sandbox`](packages/sandbox)         | The `@cloudflare/sandbox` package                                                     |
-| [`crates/sandbox-tools`](crates/sandbox-tools) | `sandbox-shim`, the Linux helper that `Files`, `S3Mounts`, and `DirectoryBackups` run |
-| [`images/sandbox-tools`](images/sandbox-tools) | The `cloudflare/sandbox` image that ships `sandbox-shim`                              |
-| [`examples`](examples)                         | Deployable Workers, one per goal                                                      |
+| Path                                           | Contents                                                                            |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [`packages/sandbox`](packages/sandbox)         | The `@cloudflare/sandbox` package                                                   |
+| [`crates/sandbox-tools`](crates/sandbox-tools) | `sandbox-shim`, the Linux helper that `Files`, `S3Mount`, and `DirectoryBackup` run |
+| [`images/sandbox-tools`](images/sandbox-tools) | The `cloudflare/sandbox` image that ships `sandbox-shim`                            |
+| [`examples`](examples)                         | Deployable Workers, one per goal                                                    |
 
-To learn how these parts fit together, read [Architecture](docs/architecture.md). The package and `sandbox-shim` exchange frames described in [Shim protocol](docs/shim-protocol.md). [S3 mounts design](docs/s3-mounts-design.md) explains `S3Mounts` and `S3Gateway`. To add an example, read [Examples](docs/examples.md).
+To learn how these parts fit together, read [Architecture](docs/architecture.md). The package and `sandbox-shim` exchange frames described in [Shim protocol](docs/shim-protocol.md). [S3 mounts design](docs/s3-mount-design.md) explains `S3Mount` and `S3Gateway`. To add an example, read [Examples](docs/examples.md).
 
 Build and test with Node.js and Docker:
 

package/dist/index.d.mts

@@ -1,13 +1,13 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 import "zod/mini";
-//#region src/directory-backups/contracts.d.ts
+//#region src/directory-backup/contracts.d.ts
 /** The only archive format this version writes and reads. */
 declare const DIRECTORY_BACKUP_FORMAT = "tar+zstd/1";
 /**
  * A saved directory. A plain, serializable object: store it wherever the application keeps
  * state. It only works with the same R2 binding and key prefix that created it.
  */
-interface DirectoryBackup {
+interface DirectoryBackupRecord {
   /** UUID. The object key is `<prefix><id>.tar.zst`. */
   readonly id: string;
   /** The directory the backup came from, and the default restore target. */
@@ -41,7 +41,7 @@ interface DirectoryBackupOptions {
 interface DirectoryRestoreOptions {
   /** Absolute path to restore into instead of the record's `dir`. */
   dir?: string;
-  /** Cancels the operation without imposing a timeout. */
+  /** Cancels the restore until the download is verified, without imposing a timeout. */
   signal?: AbortSignal;
 }
 interface DirectoryBackupDeleteOptions {
@@ -93,10 +93,10 @@ interface DirectoryBackupGatewayBinding {
   }): Fetcher & DirectoryBackupGatewayControl;
 }
 //#endregion
-//#region src/directory-backups/directory-backup-gateway.d.ts
+//#region src/directory-backup/directory-backup-gateway.d.ts
 /**
  * Moves directory backups between a container and an R2 bucket binding. Export it from the
- * Worker and pass `ctx.exports.DirectoryBackupGateway` to `DirectoryBackups`.
+ * Worker and pass `ctx.exports.DirectoryBackupGateway` to `DirectoryBackup`.
  *
  * The container reaches `fetch()` through the outbound intercept and can only use the grant
  * its current operation holds. The other methods are for the Durable Object alone.
@@ -110,7 +110,7 @@ declare class DirectoryBackupGateway extends WorkerEntrypoint<object, DirectoryB
   deleteObject(): Promise<void>;
 }
 //#endregion
-//#region src/directory-backups/directory-backups.d.ts
+//#region src/directory-backup/directory-backup.d.ts
 type DirectoryBackupContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
 /**
  * Saves one directory from the running Container to an R2 bucket, and restores it as
@@ -121,7 +121,7 @@ type DirectoryBackupContainer = Pick<Container, "exec" | "interceptOutboundHttp"
  * starts, retries, or times out anything. The application stores the returned records and
  * decides when to delete them.
  */
-declare class DirectoryBackups {
+declare class DirectoryBackup {
   #private;
   constructor(container: DirectoryBackupContainer, gateway: DirectoryBackupGatewayBinding, storage: DirectoryBackupStorage);
   /**
@@ -142,24 +142,27 @@ declare class DirectoryBackups {
    * @throws {SandboxBackupError} `BACKUP_TRANSFER` when a part upload fails, or
    *   `BACKUP_INTEGRITY` when R2 stored a different size than was uploaded.
    */
-  backup(options: DirectoryBackupOptions): Promise<DirectoryBackup>;
+  backup(options: DirectoryBackupOptions): Promise<DirectoryBackupRecord>;
   /**
    * Replaces `options.dir`, or the record's `dir`, with the backup's contents. The directory is
-   * extracted beside the target and swapped in only after the download is verified, so a failed
-   * or aborted restore leaves the target as it was. The target's parent must exist; the target
-   * need not.
+   * extracted beside the target and swapped in only after the download is verified. A
+   * `SandboxFileError` or `SandboxBackupError` means the target was not replaced, and so does
+   * an abort before the download is verified; after that, aborting no longer ends the call. If the
+   * connection to the Container is lost, as when the Durable Object restarts, the target may or
+   * may not have been replaced, and restoring again settles it. The target's parent must exist;
+   * the target need not.
    *
    * @throws {SandboxFileError} The target's parent is missing (`ENOENT`), the target isn't a
    *   directory (`ENOTDIR`), is a mount point or has one inside it (`EBUSY`), the swap fails (for
    *   example `EXDEV`), or the disk fills (`ENOSPC`).
    * @throws {SandboxBackupError} `BACKUP_NOT_FOUND`, `BACKUP_INTEGRITY`, or `BACKUP_TRANSFER`.
    */
-  restore(backup: DirectoryBackup, options?: DirectoryRestoreOptions): Promise<void>;
+  restore(backup: DirectoryBackupRecord, options?: DirectoryRestoreOptions): Promise<void>;
   /**
    * Deletes the backup's object. Needs no running Container. Deleting an object that is already
    * gone succeeds. A restore reading it at the same time fails, and nothing is swapped.
    */
-  delete(backup: DirectoryBackup, options?: DirectoryBackupDeleteOptions): Promise<void>;
+  delete(backup: DirectoryBackupRecord, options?: DirectoryBackupDeleteOptions): Promise<void>;
 }
 //#endregion
 //#region src/files/content.d.ts
@@ -321,7 +324,7 @@ declare class Files {
   remove(path: string, options?: RemoveOptions): Promise<void>;
 }
 //#endregion
-//#region src/s3-mounts/contracts.d.ts
+//#region src/s3-mount/contracts.d.ts
 type S3MountAccess = "read-only" | "read-write";
 type S3MountCredentials = {
   readonly type: "static";
@@ -448,12 +451,12 @@ interface S3GatewayBinding {
   }): Fetcher;
 }
 //#endregion
-//#region src/s3-mounts/s3-gateway.d.ts
+//#region src/s3-mount/s3-gateway.d.ts
 declare class S3Gateway extends WorkerEntrypoint<object, S3GatewayProps> {
   fetch(request: Request): Promise<Response>;
 }
 //#endregion
-//#region src/s3-mounts/s3-mounts.d.ts
+//#region src/s3-mount/s3-mount.d.ts
 type S3MountContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
 /**
  * Attaches an S3-compatible bucket or prefix to a running Container.
@@ -467,7 +470,7 @@ type S3MountContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
  * monitors, or replaces it. The mounted path is not a POSIX filesystem. Do not
  * use it for locking or atomic rename.
  */
-declare class S3Mounts {
+declare class S3Mount {
   #private;
   constructor(container: S3MountContainer, gateway: S3GatewayBinding);
   /**
@@ -554,4 +557,4 @@ declare const SandboxBackupError: {
   is(cause: unknown): cause is SandboxBackupError;
 };
 //#endregion
-export { type DirectoryBackup, type DirectoryBackupDeleteOptions, DirectoryBackupGateway, type DirectoryBackupGatewayBinding, type DirectoryBackupOperation, type DirectoryBackupOptions, type DirectoryBackupStorage, DirectoryBackups, type DirectoryRestoreOptions, type FileContent, type FileOperationOptions, Files, type MkdirOptions, type RemoveOptions, S3Gateway, type S3GatewayBinding, type S3MountInspection, type S3MountOperation, type S3MountOperationOptions, type S3MountRequest, S3Mounts, SandboxBackupError, type SandboxBackupErrorCode, type SandboxDirectoryEntry, SandboxFileError, type SandboxFileStat, type SandboxFileType, SandboxProtocolError, SandboxS3MountError, type SandboxS3MountErrorCode };
+export { DirectoryBackup, type DirectoryBackupDeleteOptions, DirectoryBackupGateway, type DirectoryBackupGatewayBinding, type DirectoryBackupOperation, type DirectoryBackupOptions, type DirectoryBackupRecord, type DirectoryBackupStorage, type DirectoryRestoreOptions, type FileContent, type FileOperationOptions, Files, type MkdirOptions, type RemoveOptions, S3Gateway, type S3GatewayBinding, S3Mount, type S3MountInspection, type S3MountOperation, type S3MountOperationOptions, type S3MountRequest, SandboxBackupError, type SandboxBackupErrorCode, type SandboxDirectoryEntry, SandboxFileError, type SandboxFileStat, type SandboxFileType, SandboxProtocolError, SandboxS3MountError, type SandboxS3MountErrorCode };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { WorkerEntrypoint } from "cloudflare:workers";
 import * as z from "zod/mini";
 import { constants } from "node:os";
 import { AwsClient } from "aws4fetch";
-//#region src/directory-backups/gateway.ts
+//#region src/directory-backup/gateway.ts
 const PART_PATH = /^\/parts\/([1-9][0-9]{0,8})$/;
 const RANGE = /^bytes=([0-9]{1,15})-([0-9]{1,15})$/;
 const MAX_DETAIL_LENGTH = 1024;
@@ -61,10 +61,10 @@ function text(status, detail) {
 	return new Response(detail.slice(0, MAX_DETAIL_LENGTH), { status });
 }
 //#endregion
-//#region src/directory-backups/directory-backup-gateway.ts
+//#region src/directory-backup/directory-backup-gateway.ts
 /**
 * Moves directory backups between a container and an R2 bucket binding. Export it from the
-* Worker and pass `ctx.exports.DirectoryBackupGateway` to `DirectoryBackups`.
+* Worker and pass `ctx.exports.DirectoryBackupGateway` to `DirectoryBackup`.
 *
 * The container reaches `fetch()` through the outbound intercept and can only use the grant
 * its current operation holds. The other methods are for the Durable Object alone.
@@ -268,7 +268,7 @@ function validateOptions(options, rules) {
 	}
 }
 //#endregion
-//#region src/directory-backups/contracts.ts
+//#region src/directory-backup/contracts.ts
 /** The only archive format this version writes and reads. */
 const DIRECTORY_BACKUP_FORMAT = "tar+zstd/1";
 //#endregion
@@ -367,6 +367,10 @@ var ShimSession = class ShimSession {
 	waitFor(operation) {
 		return this.#abort.waitFor(operation);
 	}
+	/** Stops following the caller's signal: later waits no longer reject when it aborts. */
+	stopFollowingSignal() {
+		this.#abort.dispose();
+	}
 	finish() {
 		if (this.#settled) return;
 		this.#settled = true;
@@ -479,7 +483,7 @@ function validateHeader(header) {
 	if (header[4] !== PROTOCOL_VERSION) throw protocolError(`sandbox-shim protocol ${header[4]} is not supported`);
 }
 //#endregion
-//#region src/directory-backups/protocol.ts
+//#region src/directory-backup/protocol.ts
 /** The one intercepted host every operation's grant is registered on. */
 const GATEWAY_HOST = "backups.sandbox.internal";
 const ACKNOWLEDGEMENT = new Uint8Array([1]);
@@ -490,6 +494,7 @@ const errorSchema = z.object({
 	detail: z.string()
 });
 const lockedSchema = z.strictObject({ kind: z.literal("locked") });
+const verifiedSchema = z.strictObject({ kind: z.literal("verified") });
 /**
 * Runs one `directory-backup` shim exchange: wait for the lock, register the grant, acknowledge,
 * wait for the result, then deny and close stdin, in that order on every path. The shim holds
@@ -497,7 +502,10 @@ const lockedSchema = z.strictObject({ kind: z.literal("locked") });
 * operation's deny.
 *
 * An abort closes stdin rather than killing the shim, which then removes whatever it had
-* partly written, and rejects at once with the signal's reason.
+* partly written, and rejects with the signal's reason without waiting for the shim. A restore
+* reports `verified` before it swaps and swaps only once acknowledged, so the exchange
+* acknowledges it only while the signal hasn't aborted, and from then on reports the swap's
+* outcome instead of the abort.
 */
 async function runShimExchange(container, exchange) {
 	const { signal } = exchange;
@@ -535,6 +543,13 @@ async function runShimExchange(container, exchange) {
 		granting = exchange.grant();
 		await session.waitFor(granting);
 		await session.waitFor(input.write(ACKNOWLEDGEMENT));
+		if (exchange.command === "restore") {
+			const verified = await readMessage(control, operation, exchange.path);
+			if (!verifiedSchema.safeParse(verified).success) throw protocolError("sandbox-shim did not report a verified restore");
+			signal?.throwIfAborted();
+			session.stopFollowingSignal();
+			await input.write(ACKNOWLEDGEMENT);
+		}
 		const result = await readMessage(control, operation, exchange.path);
 		const done = exchange.done.safeParse(result);
 		if (!done.success) throw protocolError("sandbox-shim returned an invalid backup result");
@@ -578,7 +593,7 @@ function closeStdin(input) {
 	input.close().catch(() => void 0);
 }
 //#endregion
-//#region src/directory-backups/directory-backups.ts
+//#region src/directory-backup/directory-backup.ts
 const absolutePath = z.string().check(z.startsWith("/"), z.refine((value) => !value.includes("\0")));
 const SIGNAL = {
 	schema: z.instanceof(AbortSignal),
@@ -637,7 +652,7 @@ const restoreDoneSchema = z.strictObject({ kind: z.literal("done") });
 * starts, retries, or times out anything. The application stores the returned records and
 * decides when to delete them.
 */
-var DirectoryBackups = class {
+var DirectoryBackup = class {
 	#container;
 	#gateway;
 	#binding;
@@ -704,9 +719,12 @@ var DirectoryBackups = class {
 	}
 	/**
 	* Replaces `options.dir`, or the record's `dir`, with the backup's contents. The directory is
-	* extracted beside the target and swapped in only after the download is verified, so a failed
-	* or aborted restore leaves the target as it was. The target's parent must exist; the target
-	* need not.
+	* extracted beside the target and swapped in only after the download is verified. A
+	* `SandboxFileError` or `SandboxBackupError` means the target was not replaced, and so does
+	* an abort before the download is verified; after that, aborting no longer ends the call. If the
+	* connection to the Container is lost, as when the Durable Object restarts, the target may or
+	* may not have been replaced, and restoring again settles it. The target's parent must exist;
+	* the target need not.
 	*
 	* @throws {SandboxFileError} The target's parent is missing (`ENOENT`), the target isn't a
 	*   directory (`ENOTDIR`), is a mount point or has one inside it (`EBUSY`), the swap fails (for
@@ -1446,7 +1464,7 @@ async function readBoundedBody(body, limit, cancelReason) {
 	};
 }
 //#endregion
-//#region src/s3-mounts/credentials.ts
+//#region src/s3-mount/credentials.ts
 const CREDENTIAL_PROVIDER_URL = "https://credentials.sandbox.internal/";
 const MAX_CREDENTIAL_RESPONSE_BYTES = 16384;
 const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -1498,12 +1516,12 @@ async function readCredentialResponse(body) {
 	}
 }
 //#endregion
-//#region src/s3-mounts/route.ts
+//#region src/s3-mount/route.ts
 function routeHost(routeId) {
 	return `s3-${routeId}.sandbox.internal`;
 }
 //#endregion
-//#region src/s3-mounts/gateway-policy.ts
+//#region src/s3-mount/gateway-policy.ts
 const LIST_V1_PARAMETERS = /* @__PURE__ */ new Set([
 	"delimiter",
 	"encoding-type",
@@ -1738,7 +1756,7 @@ function usesAwsChunkedPayload(headers) {
 	return (headers.get("content-encoding") ?? "").split(",").some((encoding) => encoding.trim().toLowerCase() === "aws-chunked");
 }
 //#endregion
-//#region src/s3-mounts/gateway.ts
+//#region src/s3-mount/gateway.ts
 const INSPECTION_VERSION_HEADER = "x-sandbox-s3-gateway-version";
 const INSPECTION_RESULT_HEADER = "x-sandbox-s3-inspection-result";
 const INSPECTION_DETAIL_HEADER = "x-sandbox-s3-inspection-detail";
@@ -1849,14 +1867,14 @@ function inspectionResponse(result, detail, status) {
 	});
 }
 //#endregion
-//#region src/s3-mounts/s3-gateway.ts
+//#region src/s3-mount/s3-gateway.ts
 var S3Gateway = class extends WorkerEntrypoint {
 	fetch(request) {
 		return handleS3GatewayRequest(request, this.ctx.props);
 	}
 };
 //#endregion
-//#region src/s3-mounts/request.ts
+//#region src/s3-mount/request.ts
 const objectSchema = z.object({});
 const stringSchema = z.string();
 const fetcherSchema = z.object({ fetch: z.function() });
@@ -2024,7 +2042,7 @@ function requiredString(value, name) {
 	return parsed.data;
 }
 //#endregion
-//#region src/s3-mounts/protocol.ts
+//#region src/s3-mount/protocol.ts
 const ROUTE_READY = new Uint8Array([1]);
 const routeIdSchema = z.string().check(z.regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,58}[A-Za-z0-9])?$/));
 const keyPrefixSchema = z.optional(z.string().check(z.refine((value) => value.endsWith("/"))));
@@ -2324,7 +2342,7 @@ function parseGatewayState(state) {
 	}
 }
 //#endregion
-//#region src/s3-mounts/reconcile.ts
+//#region src/s3-mount/reconcile.ts
 function assembleInspection(mountPath, evidence) {
 	const state = evidence.state;
 	switch (state.kind) {
@@ -2367,7 +2385,7 @@ function gatewayFor(evidence) {
 	throw protocolError("sandbox-shim omitted managed mount gateway evidence");
 }
 //#endregion
-//#region src/s3-mounts/s3-mounts.ts
+//#region src/s3-mount/s3-mount.ts
 /**
 * Attaches an S3-compatible bucket or prefix to a running Container.
 *
@@ -2380,7 +2398,7 @@ function gatewayFor(evidence) {
 * monitors, or replaces it. The mounted path is not a POSIX filesystem. Do not
 * use it for locking or atomic rename.
 */
-var S3Mounts = class {
+var S3Mount = class {
 	#container;
 	#gateway;
 	constructor(container, gateway) {
@@ -2460,4 +2478,4 @@ var S3Mounts = class {
 	}
 };
 //#endregion
-export { DirectoryBackupGateway, DirectoryBackups, Files, S3Gateway, S3Mounts, SandboxBackupError, SandboxFileError, SandboxProtocolError, SandboxS3MountError };
+export { DirectoryBackup, DirectoryBackupGateway, Files, S3Gateway, S3Mount, SandboxBackupError, SandboxFileError, SandboxProtocolError, SandboxS3MountError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {