@cloudflare/sandbox 1.0.0-rc.1 → 1.0.0-rc.2

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. */
@@ -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,7 +142,7 @@ 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
@@ -154,12 +154,12 @@ declare class DirectoryBackups {
    *   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 +321,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 +448,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 +467,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 +554,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
@@ -479,7 +479,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]);
@@ -578,7 +578,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 +637,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;
@@ -1446,7 +1446,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 +1498,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 +1738,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 +1849,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 +2024,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 +2324,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 +2367,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 +2380,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 +2460,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-rc.2",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {