@cloudflare/sandbox 1.0.0-rc.2 → 1.0.0

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 {
@@ -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

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.0",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {