@cloudflare/sandbox 0.13.0-next.776.1 → 1.0.0-rc.0

package/dist/index.d.mts

@@ -0,0 +1,548 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import "zod/mini";
+//#region src/directory-backups/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 {
+  /** UUID. The object key is `<prefix><id>.tar.zst`. */
+  readonly id: string;
+  /** The directory the backup came from, and the default restore target. */
+  readonly dir: string;
+  /** Stored bytes, as R2 reported when the upload completed. */
+  readonly size: number;
+  readonly name?: string;
+  /** SHA-256 of the stored object, checked on every restore. */
+  readonly sha256: string;
+  readonly format: typeof DIRECTORY_BACKUP_FORMAT;
+}
+/** Where backups are stored. */
+interface DirectoryBackupStorage {
+  /** Name of an R2 bucket binding in the Worker's `env`. The gateway reads it there. */
+  readonly binding: string;
+  /** Optional key prefix. A non-empty prefix ends in `/`. */
+  readonly prefix?: string;
+}
+interface DirectoryBackupOptions {
+  /** Absolute path of the directory to back up. Pause writers in it first. */
+  dir: string;
+  /** A label stored in the record and in the object's custom metadata. */
+  name?: string;
+  /** gitignore-syntax patterns, relative to `dir`. */
+  exclude?: readonly string[];
+  /** Also apply `.gitignore` files inside `dir` and `.git/info/exclude`. No `git` binary is needed. */
+  gitignore?: boolean;
+  /** Cancels the operation without imposing a timeout. */
+  signal?: AbortSignal;
+}
+interface DirectoryRestoreOptions {
+  /** Absolute path to restore into instead of the record's `dir`. */
+  dir?: string;
+  /** Cancels the operation without imposing a timeout. */
+  signal?: AbortSignal;
+}
+interface DirectoryBackupDeleteOptions {
+  signal?: AbortSignal;
+}
+interface DirectoryBackupPart {
+  readonly partNumber: number;
+  readonly etag: string;
+}
+/** Props for the Durable Object's control calls. The container never receives these. */
+interface ControlGatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "control";
+  readonly binding: string;
+  readonly key: string;
+}
+/** The one grant the container holds while its operation runs: write parts of one upload. */
+interface WriteGatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "write";
+  readonly binding: string;
+  readonly key: string;
+  readonly uploadId: string;
+}
+/** The one grant the container holds while its operation runs: read ranges of one object. */
+interface ReadGatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "read";
+  readonly binding: string;
+  readonly key: string;
+}
+/** Props that deny every container request once an operation ends. */
+interface DenyGatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "deny";
+}
+type DirectoryBackupGatewayProps = ControlGatewayProps | WriteGatewayProps | ReadGatewayProps | DenyGatewayProps;
+/** The control methods `DirectoryBackupGateway` exposes to the Durable Object over RPC. */
+interface DirectoryBackupGatewayControl {
+  createUpload(name?: string): Promise<string>;
+  completeUpload(uploadId: string, parts: readonly DirectoryBackupPart[]): Promise<number>;
+  abortUpload(uploadId: string): Promise<void>;
+  deleteObject(): Promise<void>;
+}
+/** The application's `ctx.exports.DirectoryBackupGateway`. */
+interface DirectoryBackupGatewayBinding {
+  (options: {
+    readonly props: DirectoryBackupGatewayProps;
+  }): Fetcher & DirectoryBackupGatewayControl;
+}
+//#endregion
+//#region src/directory-backups/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`.
+ *
+ * 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> {
+  #private;
+  fetch(request: Request): Promise<Response>;
+  createUpload(name?: string): Promise<string>;
+  completeUpload(uploadId: string, parts: readonly DirectoryBackupPart[]): Promise<number>;
+  abortUpload(uploadId: string): Promise<void>;
+  deleteObject(): Promise<void>;
+}
+//#endregion
+//#region src/directory-backups/directory-backups.d.ts
+type DirectoryBackupContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
+/**
+ * Saves one directory from the running Container to an R2 bucket, and restores it as
+ * ordinary files into a Container, which may run a different image.
+ *
+ * One backup or restore runs at a time per Container; others wait their turn, so
+ * `Promise.all()` over several directories works. Start the Container first: this class never
+ * starts, retries, or times out anything. The application stores the returned records and
+ * decides when to delete them.
+ */
+declare class DirectoryBackups {
+  #private;
+  constructor(container: DirectoryBackupContainer, gateway: DirectoryBackupGatewayBinding, storage: DirectoryBackupStorage);
+  /**
+   * Backs up `dir` and returns its record. Pause writers in `dir` first: files that change
+   * while it's read are captured as they are at that moment.
+   *
+   * @throws {SandboxFileError} `dir` is missing or not a directory, a file can't be read, or an
+   *   exclude pattern is invalid (`EINVAL`).
+   * @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>;
+  /**
+   * 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.
+   *
+   * @throws {SandboxFileError} The target's parent is missing (`ENOENT`), the target isn't a
+   *   directory (`ENOTDIR`) or is a mount point (`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>;
+  /**
+   * 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>;
+}
+//#endregion
+//#region src/files/content.d.ts
+type FileContent = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>;
+//#endregion
+//#region src/files/file-type.d.ts
+type SandboxFileType = "file" | "directory" | "symlink" | "blockDevice" | "characterDevice" | "fifo" | "socket";
+//#endregion
+//#region src/files/read-directory.d.ts
+interface SandboxDirectoryEntry {
+  name: string;
+  type: SandboxFileType;
+}
+//#endregion
+//#region src/files/stat-file.d.ts
+interface SandboxFileStat {
+  type: SandboxFileType;
+  size: bigint;
+  mode: number;
+  uid: number;
+  gid: number;
+  accessedAt: Date;
+  modifiedAt: Date;
+  changedAt: Date;
+}
+//#endregion
+//#region src/files/files.d.ts
+interface FileOperationOptions {
+  /** Absolute directory that a relative path is joined onto. An absolute path ignores it. */
+  cwd?: string;
+  /** Numeric user and group IDs that open the file, as `uid:gid`. */
+  user?: string;
+  /** Cancels the native container process without imposing a timeout. */
+  signal?: AbortSignal;
+}
+type RemoveOptions = FileOperationOptions & {
+  /** Permits removing a directory tree without following symlinks. */
+  recursive?: boolean;
+  /** Ignores a missing target. */
+  force?: boolean;
+};
+type MkdirOptions = FileOperationOptions & {
+  /** Creates missing parent directories and accepts an existing target directory. */
+  recursive?: boolean;
+};
+/**
+ * Structured file operations for a sandbox workspace.
+ *
+ * Operations run against the current native container execution. Its image must provide the matching shim at
+ * `/usr/local/bin/sandbox-shim`.
+ */
+declare class Files {
+  #private;
+  constructor(container: Pick<Container, "exec">);
+  /**
+   * Streams bytes from a path in the running container using native Linux file semantics.
+   *
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @param path - Absolute path, or a relative path when `options.cwd` is provided.
+   * @param options - Native execution options relevant to opening the file.
+   * @returns A binary response whose body applies backpressure to the container process. A
+   *   file-streaming or native transport failure can surface while the body is consumed.
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without `cwd`, or an
+   *   option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure before returning the
+   *   response. A late file-streaming failure errors the response body with the same error type.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  readFile(path: string, options?: FileOperationOptions): Promise<Response>;
+  /**
+   * Creates or truncates a file and streams content into it using native Linux semantics.
+   *
+   * The destination is opened before a caller-provided stream is consumed. Failures after that
+   * point can leave a created, truncated, or partially written file. Native container, transport,
+   * source-stream, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  writeFile(path: string, content: FileContent, options?: FileOperationOptions): Promise<void>;
+  /**
+   * Returns metadata for a path using native Linux filesystem semantics.
+   *
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  stat(path: string, options?: FileOperationOptions): Promise<SandboxFileStat>;
+  /**
+   * Returns metadata for a path without following its final symlink.
+   *
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  lstat(path: string, options?: FileOperationOptions): Promise<SandboxFileStat>;
+  /**
+   * Returns the immediate entries from a directory in native enumeration order.
+   *
+   * The directory path may resolve through a symlink, but entry types describe the entries
+   * themselves and do not follow symlinks. The operation does not recurse or retrieve metadata
+   * for each child.
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  readDirectory(path: string, options?: FileOperationOptions): Promise<SandboxDirectoryEntry[]>;
+  /**
+   * Creates a directory using native Linux filesystem semantics.
+   *
+   * By default only the final directory is created. With `recursive`, missing parents are
+   * created and an existing target directory is accepted. Partial parent creation can remain
+   * after failure or cancellation.
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Renames a file, directory, or symlink using native Linux filesystem semantics.
+   *
+   * Existing destinations are replaced when Linux permits it. Cross-filesystem renames fail
+   * with `EXDEV`; no copy-and-remove fallback is attempted.
+   * Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} A path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  rename(source: string, destination: string, options?: FileOperationOptions): Promise<void>;
+  /**
+   * Removes a file or symlink using native Linux filesystem semantics.
+   *
+   * Directories are rejected unless `recursive` is set. Recursive removal does not follow
+   * symlinks and can leave partial effects after failure or cancellation. `force` ignores only
+   * a missing target. Native container, transport, and abort failures propagate unchanged.
+   *
+   * @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+   *   or an option is unknown or invalid.
+   * @throws {SandboxFileError} The container reports a filesystem failure.
+   * @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+   */
+  remove(path: string, options?: RemoveOptions): Promise<void>;
+}
+//#endregion
+//#region src/s3-mounts/contracts.d.ts
+type S3MountAccess = "read-only" | "read-write";
+type S3MountCredentials = {
+  readonly type: "static";
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  readonly sessionToken?: string;
+} | {
+  readonly type: "provider";
+  readonly fetcher: Pick<Fetcher, "fetch">;
+};
+type S3MountSource = {
+  readonly type: "s3";
+  readonly endpoint: string;
+  readonly region: string;
+  readonly bucket: string;
+  readonly credentials: S3MountCredentials;
+};
+type S3fsOptionValue = string | number | boolean;
+interface S3MountRequest {
+  readonly mountPath: string;
+  readonly source: S3MountSource;
+  /** Optional object-key prefix. A non-empty value ends in `/`. */
+  readonly keyPrefix?: string;
+  readonly access: S3MountAccess;
+  readonly s3fsOptions?: Readonly<Record<string, S3fsOptionValue>>;
+}
+interface S3MountOperationOptions {
+  readonly signal?: AbortSignal;
+}
+interface S3MountObservedConfiguration {
+  readonly source: {
+    readonly type: "s3";
+    readonly endpoint: string;
+    readonly region: string;
+    readonly bucket: string;
+  };
+  /** Omitted for the bucket root; otherwise canonical and slash-terminated. */
+  readonly keyPrefix?: string;
+  readonly access: S3MountAccess;
+  readonly s3fsOptions: readonly {
+    readonly name: string;
+    readonly value?: string;
+  }[];
+}
+type S3MountFuseInspection = {
+  readonly status: "connected";
+} | {
+  readonly status: "disconnected";
+} | {
+  readonly status: "indeterminate";
+  readonly detail: string;
+};
+type S3MountGatewayInspection = {
+  readonly status: "unreachable";
+  readonly detail: string;
+} | {
+  readonly status: "error";
+  readonly reason: "credential-provider" | "protocol" | "internal";
+  readonly detail: string;
+} | {
+  readonly status: "reachable";
+  readonly upstream: {
+    readonly status: "usable";
+  } | {
+    readonly status: "unavailable";
+    readonly detail: string;
+  } | {
+    readonly status: "rejected";
+    readonly reason: "credentials" | "access" | "not-found" | "other";
+    readonly detail: string;
+  };
+};
+type S3MountInspection = {
+  readonly mountPath: string;
+  readonly attachment: {
+    readonly status: "absent";
+  };
+} | {
+  readonly mountPath: string;
+  readonly attachment: {
+    readonly status: "unmanaged";
+    readonly filesystemType: string;
+  };
+} | {
+  readonly mountPath: string;
+  readonly attachment: {
+    readonly status: "incompatible";
+  };
+} | {
+  readonly mountPath: string;
+  readonly attachment: {
+    readonly status: "stale";
+    readonly configuration: S3MountObservedConfiguration;
+  };
+  readonly gateway: S3MountGatewayInspection;
+} | {
+  readonly mountPath: string;
+  readonly attachment: {
+    readonly status: "managed";
+    readonly configuration: S3MountObservedConfiguration;
+  };
+  readonly fuse: S3MountFuseInspection;
+  readonly gateway: S3MountGatewayInspection;
+};
+/** Props passed only to an active route-scoped `S3Gateway` service instance. */
+interface ActiveS3GatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "active";
+  readonly routeId: string;
+  readonly source: S3MountSource;
+  readonly keyPrefix?: string;
+  readonly access: S3MountAccess;
+}
+/** Props that deny requests after the matching mount is removed. */
+interface DenyS3GatewayProps {
+  readonly protocolVersion: 1;
+  readonly mode: "deny";
+  readonly routeId: string;
+}
+type S3GatewayProps = ActiveS3GatewayProps | DenyS3GatewayProps;
+interface S3GatewayBinding {
+  (options: {
+    readonly props: S3GatewayProps;
+  }): Fetcher;
+}
+//#endregion
+//#region src/s3-mounts/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
+type S3MountContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
+/**
+ * Attaches an S3-compatible bucket or prefix to a running Container.
+ *
+ * Use this for a few long-lived mounts in one job or session. Calling `mount()`
+ * again with the same settings reuses the existing mount. `unmount()` stops
+ * access and unmounts the path. It does not fully clean up the Container's
+ * intercept. For a new job or tenant, use a new sandbox name.
+ *
+ * Start the Container before calling `mount()`. This class never starts,
+ * monitors, or replaces it. The mounted path is not a POSIX filesystem. Do not
+ * use it for locking or atomic rename.
+ */
+declare class S3Mounts {
+  #private;
+  constructor(container: S3MountContainer, gateway: S3GatewayBinding);
+  /**
+   * Creates the mount, reuses a matching mount, or repairs leftover state.
+   *
+   * Reuse does not consume another Container intercept. Use `inspect()` to read
+   * current state without changing it.
+   */
+  mount(request: S3MountRequest, options?: S3MountOperationOptions): Promise<void>;
+  /**
+   * Reports the current path without changing it.
+   *
+   * Waits for an in-flight `mount()` or `unmount()` on the same path first.
+   * Gateway evidence can be newer than the guest snapshot. Pass `signal` when
+   * the application needs a deadline.
+   */
+  inspect(mountPath: string, options?: S3MountOperationOptions): Promise<S3MountInspection>;
+  /**
+   * Stops new access, then unmounts the path.
+   *
+   * This does not remove the Container intercept. If denying access fails, the
+   * filesystem stays mounted. If the filesystem is busy, access stays denied
+   * and you can retry. This never force-unmounts.
+   */
+  unmount(mountPath: string, options?: S3MountOperationOptions): Promise<void>;
+}
+//#endregion
+//#region src/shared/errors.d.ts
+/** Symbolic Linux errno, or `UNKNOWN` when the runtime does not name it. */
+type SandboxFileErrorCode = `E${string}` | "UNKNOWN";
+declare const FILE_OPERATIONS: readonly ["readFile", "writeFile", "stat", "lstat", "readDirectory", "mkdir", "rename", "remove", "backup", "restore"];
+/** Filesystem operation that failed. */
+type SandboxFileOperation = (typeof FILE_OPERATIONS)[number];
+/** A native Linux filesystem failure reported by the sandbox container. */
+interface SandboxFileError extends Error {
+  readonly name: "SandboxFileError";
+  readonly code: SandboxFileErrorCode;
+  readonly operation: SandboxFileOperation;
+  readonly path: string;
+  readonly destination?: string;
+  readonly detail: string;
+}
+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 {
+  readonly name: "SandboxProtocolError";
+  readonly code: "SANDBOX_PROTOCOL_ERROR";
+  readonly detail: string;
+}
+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 {
+  readonly name: "SandboxS3MountError";
+  readonly code: SandboxS3MountErrorCode;
+  readonly operation: S3MountOperation;
+  readonly path: string;
+  readonly detail: string;
+}
+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 {
+  readonly name: "SandboxBackupError";
+  readonly code: SandboxBackupErrorCode;
+  readonly operation: DirectoryBackupOperation;
+  /** The directory being backed up or restored, or the record's directory for `delete`. */
+  readonly path: string;
+  readonly detail: string;
+}
+declare const SandboxBackupError: {
+  /** Recognizes local and JSRPC-crossed SandboxBackupError values. */
+  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 };