@cloudflare/sandbox 1.0.0-rc.2 → 1.0.1

package/README.md

@@ -62,17 +62,17 @@ The image needs the helper that `Files` runs, and the Worker needs `nodejs_compa
 
 ## What you can build
 
-| Goal                                   | Guide                                                                                                                              | Example                                                                                                  |
-| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Run a script and read its output       | [Execute commands](https://developers.cloudflare.com/containers/guides/execute-commands/)                                          | [`workspace`](examples/workspace)                                                                        |
-| Keep a server or build running         | [Run background processes](https://developers.cloudflare.com/sandbox/commands/run-background-processes/)                           | [`process-workspace`](examples/process-workspace)                                                        |
-| Open a shell in the browser            | [Open a terminal in the browser](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/)               | [`terminal-workspace`](examples/terminal-workspace)                                                      |
-| Process files from a bucket            | [Mount an R2 bucket](https://developers.cloudflare.com/sandbox/files/mount-an-r2-bucket/)                                          | [`artifact-workspace`](examples/artifact-workspace)                                                      |
-| Save a workspace and resume it later   | [Save and restore a sandbox](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/)                        | [`checkpoint-workspace`](examples/checkpoint-workspace), [`backup-workspace`](examples/backup-workspace) |
-| Preview a web app while you edit it    | [Preview a web application](https://developers.cloudflare.com/sandbox/previews/)                                                   | [`preview-workspace`](examples/preview-workspace)                                                        |
-| Share a port on its own URL            | [Serve previews on their own hostnames](https://developers.cloudflare.com/sandbox/previews/serve-previews-on-their-own-hostnames/) | [`share-workspace`](examples/share-workspace)                                                            |
-| Choose which hosts a sandbox can reach | [Control network access](https://developers.cloudflare.com/sandbox/network/)                                                       | [`outbound-workspace`](examples/outbound-workspace)                                                      |
-| Run a coding agent on a repository     | [Coding agents](https://developers.cloudflare.com/sandbox/coding-agents/)                                                          | [`coding-agents`](examples/coding-agents), [`devin`](devin), [`openai/agents-api`](openai/agents-api)    |
+| Goal                                   | Guide                                                                                                                              | Example                                                                                                                                       |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run a script and read its output       | [Execute commands](https://developers.cloudflare.com/containers/guides/execute-commands/)                                          | [`workspace`](examples/workspace)                                                                                                             |
+| Keep a server or build running         | [Run background processes](https://developers.cloudflare.com/sandbox/commands/run-background-processes/)                           | [`process-workspace`](examples/process-workspace)                                                                                             |
+| Open a shell in the browser            | [Open a terminal in the browser](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/)               | [`terminal-workspace`](examples/terminal-workspace)                                                                                           |
+| Process files from a bucket            | [Mount an R2 bucket](https://developers.cloudflare.com/sandbox/files/mount-an-r2-bucket/)                                          | [`artifact-workspace`](examples/artifact-workspace)                                                                                           |
+| Save a workspace and resume it later   | [Save and restore a sandbox](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/)                        | [`checkpoint-workspace`](examples/checkpoint-workspace), [`backup-workspace`](examples/backup-workspace)                                      |
+| Preview a web app while you edit it    | [Preview a web application](https://developers.cloudflare.com/sandbox/previews/)                                                   | [`preview-workspace`](examples/preview-workspace)                                                                                             |
+| Share a port on its own URL            | [Serve previews on their own hostnames](https://developers.cloudflare.com/sandbox/previews/serve-previews-on-their-own-hostnames/) | [`share-workspace`](examples/share-workspace)                                                                                                 |
+| Choose which hosts a sandbox can reach | [Control network access](https://developers.cloudflare.com/sandbox/network/)                                                       | [`outbound-workspace`](examples/outbound-workspace)                                                                                           |
+| Run a coding agent on a repository     | [Coding agents](https://developers.cloudflare.com/sandbox/coding-agents/)                                                          | [`coding-agents`](examples/coding-agents), [`templates/devin`](templates/devin), [`templates/openai-agents-api`](templates/openai-agents-api) |
 
 To run JavaScript or Python without a Linux environment, use [Dynamic Workers](https://developers.cloudflare.com/sandbox/concepts/) instead.
 

package/dist/index.d.mts

@@ -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 {
@@ -101,7 +101,7 @@ interface DirectoryBackupGatewayBinding {
  * 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.
  */
-declare class DirectoryBackupGateway extends WorkerEntrypoint<object, DirectoryBackupGatewayProps> {
+export declare class DirectoryBackupGateway extends WorkerEntrypoint<object, DirectoryBackupGatewayProps> {
   #private;
   fetch(request: Request): Promise<Response>;
   createUpload(name?: string): Promise<string>;
@@ -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 DirectoryBackup {
+export declare class DirectoryBackup {
   #private;
   constructor(container: DirectoryBackupContainer, gateway: DirectoryBackupGatewayBinding, storage: DirectoryBackupStorage);
   /**
@@ -145,9 +145,12 @@ declare class 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
@@ -211,7 +214,7 @@ type MkdirOptions = FileOperationOptions & {
  * Operations run against the current native container execution. Its image must provide the matching shim at
  * `/usr/local/bin/sandbox-shim`.
  */
-declare class Files {
+export declare class Files {
   #private;
   constructor(container: Pick<Container, "exec">);
   /**
@@ -449,7 +452,7 @@ interface S3GatewayBinding {
 }
 //#endregion
 //#region src/s3-mount/s3-gateway.d.ts
-declare class S3Gateway extends WorkerEntrypoint<object, S3GatewayProps> {
+export declare class S3Gateway extends WorkerEntrypoint<object, S3GatewayProps> {
   fetch(request: Request): Promise<Response>;
 }
 //#endregion
@@ -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 S3Mount {
+export declare class S3Mount {
   #private;
   constructor(container: S3MountContainer, gateway: S3GatewayBinding);
   /**
@@ -502,7 +505,7 @@ declare const FILE_OPERATIONS: readonly ["readFile", "writeFile", "stat", "lstat
 /** Filesystem operation that failed. */
 type SandboxFileOperation = (typeof FILE_OPERATIONS)[number];
 /** A native Linux filesystem failure reported by the sandbox container. */
-interface SandboxFileError extends Error {
+export interface SandboxFileError extends Error {
   readonly name: "SandboxFileError";
   readonly code: SandboxFileErrorCode;
   readonly operation: SandboxFileOperation;
@@ -510,38 +513,38 @@ interface SandboxFileError extends Error {
   readonly destination?: string;
   readonly detail: string;
 }
-declare const SandboxFileError: {
+export declare const SandboxFileError: {
   /** Recognizes local and JSRPC-crossed SandboxFileError values. */
   is(cause: unknown): cause is SandboxFileError;
 };
 /** An incompatible or malformed exchange with `sandbox-shim`. */
-interface SandboxProtocolError extends Error {
+export interface SandboxProtocolError extends Error {
   readonly name: "SandboxProtocolError";
   readonly code: "SANDBOX_PROTOCOL_ERROR";
   readonly detail: string;
 }
-declare const SandboxProtocolError: {
+export declare const SandboxProtocolError: {
   /** Recognizes local and JSRPC-crossed SandboxProtocolError values. */
   is(cause: unknown): cause is SandboxProtocolError;
 };
 type SandboxS3MountErrorCode = "S3_MOUNT_CONFLICT" | "S3_MOUNT_BUSY" | "S3_MOUNT_FAILED" | "S3_MOUNT_INCOMPATIBLE";
 type S3MountOperation = "mount" | "inspect" | "unmount";
 /** A classifiable failure while reconciling an S3-compatible filesystem mount. */
-interface SandboxS3MountError extends Error {
+export interface SandboxS3MountError extends Error {
   readonly name: "SandboxS3MountError";
   readonly code: SandboxS3MountErrorCode;
   readonly operation: S3MountOperation;
   readonly path: string;
   readonly detail: string;
 }
-declare const SandboxS3MountError: {
+export declare const SandboxS3MountError: {
   /** Recognizes local and JSRPC-crossed SandboxS3MountError values. */
   is(cause: unknown): cause is SandboxS3MountError;
 };
 type SandboxBackupErrorCode = "BACKUP_NOT_FOUND" | "BACKUP_INTEGRITY" | "BACKUP_TRANSFER";
 type DirectoryBackupOperation = "backup" | "restore" | "delete";
 /** A failure specific to a directory backup: a missing, altered, or unreachable object. */
-interface SandboxBackupError extends Error {
+export interface SandboxBackupError extends Error {
   readonly name: "SandboxBackupError";
   readonly code: SandboxBackupErrorCode;
   readonly operation: DirectoryBackupOperation;
@@ -549,9 +552,9 @@ interface SandboxBackupError extends Error {
   readonly path: string;
   readonly detail: string;
 }
-declare const SandboxBackupError: {
+export declare const SandboxBackupError: {
   /** Recognizes local and JSRPC-crossed SandboxBackupError values. */
   is(cause: unknown): cause is SandboxBackupError;
 };
 //#endregion
-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 };
+export type { DirectoryBackupDeleteOptions, DirectoryBackupGatewayBinding, DirectoryBackupOperation, DirectoryBackupOptions, DirectoryBackupRecord, DirectoryBackupStorage, DirectoryRestoreOptions, FileContent, FileOperationOptions, MkdirOptions, RemoveOptions, S3GatewayBinding, S3MountInspection, S3MountOperation, S3MountOperationOptions, S3MountRequest, SandboxBackupErrorCode, SandboxDirectoryEntry, SandboxFileStat, SandboxFileType, SandboxS3MountErrorCode };

package/dist/index.mjs

@@ -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;
@@ -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");
@@ -704,9 +719,12 @@ var DirectoryBackup = 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.1",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "aws4fetch": "1.0.20",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   }
 }