@lunora/container 1.0.0-alpha.63 → 1.0.0-alpha.65

package/dist/packem_shared/{jurisdiction.d-DPvNG2h5.d.ts → jurisdiction.d-t4mtuqYW.d.ts}

@@ -1,3 +1,92 @@
+/**
+ * The `handle.spawn()` contract: start a process in a named container
+ * instance and stream it, rather than buffer it the way `exec` does.
+ *
+ * Node-safe (no runtime imports): the Durable Object half lives in
+ * `do/spawn.ts`. This module owns the request shape both halves agree on and
+ * turns the RPC result into a {@link ContainerProcess}.
+ */
+/** Per-call options for `handle.spawn()`. */
+interface ContainerSpawnOptions {
+  /** Arguments passed to `command`, unshelled. */
+  args?: ReadonlyArray<string>;
+  /** Working directory for the process. */
+  cwd?: string;
+  /** Extra environment for this process, merged over the container's start env. */
+  env?: Readonly<Record<string, string>>;
+  /**
+   * Run the process on a pseudo-terminal of this size (defaults `80×24`).
+   * Under a PTY, stderr is merged into `stdout` and `resize()` works — what an
+   * interactive shell or a browser terminal needs.
+   */
+  pty?: {
+    cols?: number;
+    rows?: number;
+  };
+  /** Kill the process when this signal aborts. */
+  signal?: AbortSignal;
+  /**
+   * Give the process a stdin: `true` returns a writable `stdin` stream, a
+   * `ReadableStream` is piped in as the process's whole input. Omitted or
+   * `false` leaves stdin closed.
+   */
+  stdin?: ReadableStream<Uint8Array> | boolean;
+  /**
+   * Kill the process after this many ms. Unlike `exec`, a spawned process has
+   * no default deadline: it runs until it exits, is killed, or the container
+   * stops.
+   */
+  timeoutMs?: number;
+}
+/** The request `lunoraSpawn` takes over RPC. An `AbortSignal` cannot cross RPC, so it stays on the caller's side. */
+interface ContainerSpawnRequest extends Omit<ContainerSpawnOptions, "args" | "env" | "signal"> {
+  args?: string[];
+  command: string;
+  env?: Record<string, string>;
+}
+/** The control stub `lunoraSpawn` returns, as the caller sees it over RPC. */
+interface ContainerProcessControlStub {
+  exitCode: () => Promise<number>;
+  kill: (signal?: number) => Promise<void> | void;
+  resize: (cols: number, rows: number) => Promise<void> | void;
+}
+/** `lunoraSpawn`'s RPC result. */
+interface SpawnResult {
+  control: ContainerProcessControlStub;
+  isPty: boolean;
+  pid: number;
+  stderr: ReadableStream<Uint8Array> | null;
+  stdin: WritableStream<Uint8Array> | null;
+  stdout: ReadableStream<Uint8Array> | null;
+}
+/**
+ * A running process in a container instance, returned by `handle.spawn()`.
+ *
+ * The container finishes a process's output, and settles `exitCode`, only
+ * while its output is being drained. Lunora drains `stdout` and `stderr` into
+ * a 1 MiB buffer each, so they can be read in either order, or after awaiting
+ * `exitCode`, while the stream you are not reading stays under 1 MiB. Past
+ * that the process stalls until you read it: for a process that may write more
+ * to one stream, read both concurrently, or cancel the one you do not need.
+ */
+interface ContainerProcess {
+  /** Resolves with the exit code once the process ends. */
+  exitCode: Promise<number>;
+  /** Whether the process runs on a PTY (`spawn({ pty })`). */
+  isPty: boolean;
+  /** Send `signal` (default `SIGTERM`). Resolves once the signal is sent, not when the process exits. */
+  kill: (signal?: number) => Promise<void>;
+  /** The process id inside the container, or `-1` when the runtime does not report one. */
+  pid: number;
+  /** Resize the PTY. Rejects for a process spawned without `pty`. */
+  resize: (cols: number, rows: number) => Promise<void>;
+  /** The process's stderr, or `null` under `pty` (merged into `stdout`). */
+  stderr: ReadableStream<Uint8Array> | null;
+  /** The process's stdin when spawned with `stdin: true`, else `null`. */
+  stdin: WritableStream<Uint8Array> | null;
+  /** The process's stdout (and, under `pty`, its stderr too). */
+  stdout: ReadableStream<Uint8Array> | null;
+}
 /**
  * Public configuration types for `@lunora/container`.
  *
@@ -26,6 +115,22 @@ interface CustomContainerInstanceType {
  * `ContainerInstanceType` is part of the experimental `@lunora/container` API and may change without a major version bump.
  */
 type ContainerInstanceType = CustomContainerInstanceType | NamedContainerInstanceType;
+/**
+ * An instance size a Durable Object can pick at start under the
+ * `durable_object` scheduling policy. The runtime does not accept `basic` (or
+ * the legacy `dev`/`standard` aliases), and a custom size must set all three
+ * fields — it is passed to `ctx.container.start({ instance })` as-is.
+ */
+type ContainerRuntimeInstanceType = Exclude<NamedContainerInstanceType, "basic"> | Required<CustomContainerInstanceType>;
+/**
+ * One named image under the `durable_object` scheduling policy. A `string` is
+ * a local Dockerfile path or directory, built and uploaded by `wrangler deploy`
+ * (wrangler `dockerfile` + `build_context`); `{ registry }` must be a
+ * digest-pinned (`@sha256:…`) reference under `registry.cloudflare.com/`,
+ * the Cloudflare managed registry — Cloudflare does not accept Docker Hub, ECR
+ * or Artifact Registry references here.
+ */
+type ContainerNamedImageSource = RegistryImageSource | string;
 /**
  * Rolling-deploy tuning for a container.
  */
@@ -73,17 +178,27 @@ type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
 interface ContainerReadinessCheck {
   /** HTTP path probed on the container, e.g. `"/ready"` (a leading slash is optional). */
   path: string;
-  /** Port to probe. Defaults to {@link ContainerConfig.defaultPort}. */
+  /** Port to probe. Defaults to {@link ContainerConfigBase.defaultPort}. */
   port?: number;
   /** HTTP status that means "ready". Defaults to `200`. */
   status?: number;
 }
 /**
- * `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ * The fields every container accepts, whichever scheduling policy it uses.
+ */
+/**
+ * Where `handle.backup()` stores directory backups for a `sandbox: true`
+ * container: an R2 bucket binding and an optional key prefix.
  */
-interface ContainerConfig {
+interface ContainerBackupStorage {
+  /** Name of an R2 bucket binding on the Worker env (`r2_buckets[].binding`). */
+  bucket: string;
+  /** Key prefix for the backup objects. A non-empty prefix ends in `/`. */
+  prefix?: string;
+}
+interface ContainerConfigBase {
   /**
-   * Hostnames the container may reach **even when {@link ContainerConfig.enableInternet}
+   * Hostnames the container may reach **even when {@link ContainerConfigBase.enableInternet}
    * is `false`** — an egress allow-list (Cloudflare's `allowedHosts`). Glob
    * patterns like `*.stripe.com` are supported. Pair with `enableInternet:
    * false` to deny all egress except these hosts (the firewall pattern
@@ -93,32 +208,39 @@ interface ContainerConfig {
    * handle's `egress` controls adjust the lists at runtime.
    */
   allowedHosts?: ReadonlyArray<string>;
+  /**
+   * Where `handle.backup()` saves directory backups (requires `sandbox: true`).
+   * The backup and restore traffic goes through the `DirectoryBackupGateway`
+   * Worker entrypoint, which hands the container a grant for one object per
+   * operation, so the container never holds bucket credentials.
+   */
+  backups?: ContainerBackupStorage;
   /**
    * Build-time variables for a Dockerfile/Railpack image — wrangler's
    * `image_vars` (equivalent to `docker build --build-arg`). For *runtime*
-   * values use {@link ContainerConfig.env} / {@link ContainerConfig.secrets}.
+   * values use {@link ContainerConfigBase.env} / {@link ContainerConfigBase.secrets}.
    * Ignored for a pre-built `{ registry }` image.
    */
   buildArgs?: Readonly<Record<string, string>>;
   /**
    * The port the container listens on. Worker → container requests target
    * this port. Locally the Dockerfile must also `EXPOSE` it. For a
-   * multi-port container also declare {@link ContainerConfig.requiredPorts}
+   * multi-port container also declare {@link ContainerConfigBase.requiredPorts}
    * and route per request with the handle's `.port(n)`.
    */
   defaultPort?: number;
   /**
    * Hostnames the container may **never** reach — an egress deny-list
    * (Cloudflare's `deniedHosts`). Overrides everything else, including
-   * `enableInternet: true` and {@link ContainerConfig.allowedHosts}. Glob
+   * `enableInternet: true` and {@link ContainerConfigBase.allowedHosts}. Glob
    * patterns like `*.evil.com` are supported.
    */
   deniedHosts?: ReadonlyArray<string>;
   /**
    * Whether the container may open outbound internet connections. Defaults
    * to `true` — the platform default. Note that container egress is billed
-   * per GB by Cloudflare. Combine with {@link ContainerConfig.allowedHosts} /
-   * {@link ContainerConfig.deniedHosts} for a precise egress firewall.
+   * per GB by Cloudflare. Combine with {@link ContainerConfigBase.allowedHosts} /
+   * {@link ContainerConfigBase.deniedHosts} for a precise egress firewall.
    */
   enableInternet?: boolean;
   /**
@@ -129,14 +251,14 @@ interface ContainerConfig {
   entrypoint?: ReadonlyArray<string>;
   /**
    * Static environment variables passed to the container on every start.
-   * For secret values use {@link ContainerConfig.secrets} instead so they
+   * For secret values use {@link ContainerConfigBase.secrets} instead so they
    * flow through Worker Secrets rather than source code.
    */
   env?: Readonly<Record<string, string>>;
   /**
    * Hard cap on how long an instance may run, measured from start regardless
    * of activity — a runaway-cost backstop on top of the idle
-   * {@link ContainerConfig.sleepAfter}. Same grammar as `sleepAfter`
+   * {@link ContainerConfigBase.sleepAfter}. Same grammar as `sleepAfter`
    * (`"30s"`, `"5m"`, `"1h"`, or a plain number of seconds). When it elapses,
    * the `LunoraContainer.onHardTimeoutExpired` hook runs (default: `stop()`,
    * which sends SIGTERM and does not escalate — a container that ignores the
@@ -144,13 +266,6 @@ interface ContainerConfig {
    * `destroy()`). (Upstream cloudflare/containers#85.)
    */
   hardTimeout?: number | string;
-  /** Image source — a local Dockerfile path/directory or a registry reference. */
-  image: ContainerImageSource;
-  /**
-   * Resource class for each instance: a named Cloudflare instance type or a
-   * custom `{ vcpu, memoryMib, diskMb }` object.
-   */
-  instanceType?: ContainerInstanceType;
   /**
    * Intercept the container's outbound **HTTPS** traffic so the egress
    * allow/deny lists apply to TLS connections too (Cloudflare's
@@ -166,11 +281,6 @@ interface ContainerConfig {
    * `start({ labels })`.
    */
   labels?: Readonly<Record<string, string>>;
-  /**
-   * Maximum number of concurrently *running* instances. Stopped (slept)
-   * containers don't count. Also the default pool size for `.any()`.
-   */
-  maxInstances?: number;
   /**
    * Override for the wrangler `containers[].name` identifier. Defaults to
    * wrangler's own default (worker name + class name + environment).
@@ -196,17 +306,21 @@ interface ContainerConfig {
    * Ports the container must be listening on before it's considered ready
    * (Cloudflare's `requiredPorts`) — for multi-port containers. Start-up
    * waits for every listed port, and the handle's `.port(n)` routes a request
-   * to any of them; {@link ContainerConfig.defaultPort} is the target when a
+   * to any of them; {@link ContainerConfigBase.defaultPort} is the target when a
    * request doesn't pick one.
    */
   requiredPorts?: ReadonlyArray<number>;
   /**
-   * Rolling-deploy tuning. `stepPercentage` is the share of instances updated
-   * per rollout step (wrangler `rollout_step_percentage`); `gracePeriodSeconds`
-   * is how long an active instance is left running before it's eligible for
-   * update (wrangler `rollout_active_grace_period`).
+   * Opt in to the Sandbox SDK helpers (`@cloudflare/sandbox`): structured
+   * file operations, directory backups to R2 and S3-compatible bucket mounts
+   * on a named instance. The image must ship the `sandbox-shim` helper at
+   * `/usr/local/bin/sandbox-shim`, copied from Cloudflare's shim-only
+   * `cloudflare/sandbox` image (`COPY --from=…`). Turning it on also makes codegen export the `S3Gateway` and
+   * `DirectoryBackupGateway` entrypoints from the worker, which the helpers
+   * route the container's storage traffic through. Must be a `true`/`false`
+   * literal, because codegen reads it. Defaults to `false`.
    */
-  rollout?: ContainerRollout;
+  sandbox?: boolean;
   /**
    * Names of Worker secrets (from `wrangler secret` / `.dev.vars`) forwarded
    * into the container's environment at instance start. Each declared name
@@ -220,7 +334,7 @@ interface ContainerConfig {
    * binding name*. Each binding is resolved with its async `.get()` the first
    * time the instance starts, then injected as that env var — e.g.
    * `{ STRIPE_KEY: "STRIPE_SECRET" }` runs `env.STRIPE_SECRET.get()` and sets
-   * `STRIPE_KEY` inside the container. Unlike {@link ContainerConfig.secrets}
+   * `STRIPE_KEY` inside the container. Unlike {@link ContainerConfigBase.secrets}
    * (plain Worker text secrets), this pulls from a `secrets_store_secrets`
    * binding. A name already used by `env`/`secrets` is rejected at authoring
    * time; a missing binding or unreadable value fails the start. Applies
@@ -236,13 +350,95 @@ interface ContainerConfig {
    */
   sleepAfter?: number | string;
 }
+/**
+ * A container under the `default` scheduling policy: one application-wide
+ * image and instance size, set in wrangler and rolled out by Cloudflare on
+ * deploy.
+ */
+interface DefaultScheduledContainerConfig extends ContainerConfigBase {
+  /** Image source — a local Dockerfile path/directory or a registry reference. */
+  image: ContainerImageSource;
+  /**
+   * Resource class for each instance: a named Cloudflare instance type or a
+   * custom `{ vcpu, memoryMib, diskMb }` object.
+   */
+  instanceType?: ContainerInstanceType;
+  /**
+   * Maximum number of concurrently *running* instances. Stopped (slept)
+   * containers don't count. Also the default pool size for `.any()`.
+   */
+  maxInstances?: number;
+  /**
+   * Rolling-deploy tuning. `stepPercentage` is the share of instances updated
+   * per rollout step (wrangler `rollout_step_percentage`); `gracePeriodSeconds`
+   * is how long an active instance is left running before it's eligible for
+   * update (wrangler `rollout_active_grace_period`).
+   */
+  rollout?: ContainerRollout;
+  /**
+   * Where the image and instance size are configured. `"default"` (the
+   * default) sets them once in wrangler; `"durable_object"` is the
+   * per-instance policy.
+   * Immutable once deployed: switching policies means a new container
+   * application, which replaces every running instance.
+   */
+  schedulingPolicy?: "default";
+}
+/**
+ * A container under the `durable_object` scheduling policy (Cloudflare public
+ * beta): each instance picks its image and size when it starts, via
+ * `ctx.containers.<name>.get(id).start({ image, instanceType })`, and can save
+ * and restore its filesystem with `snapshot()` / `start({ snapshot })`.
+ * Instances keep the image they started with across deploys — there is no
+ * application-wide rollout, and no `maxInstances` cap (running instances count
+ * against the account limit).
+ */
+interface DurableObjectScheduledContainerConfig extends ContainerConfigBase {
+  /**
+   * The image a start uses when it names none — including the implicit start a
+   * `fetch`/`exec` triggers. Either a key of `images`
+   * or a Cloudflare-managed image such as `"cloudflare/debian-trixie"`.
+   * Without it, an instance must be started explicitly with an `image` (or a
+   * `snapshot`) before it can serve requests.
+   */
+  image?: string;
+  /**
+   * Named images an instance can start from, keyed by the name `start({ image })`
+   * takes (wrangler `containers[].images`). Up to 100, each name 1–128
+   * characters. Updating the map does not restart running instances.
+   */
+  images?: Readonly<Record<string, ContainerNamedImageSource>>;
+  /**
+   * The instance size a start uses when it names none. Cloudflare's runtime
+   * default is `"lite"`.
+   */
+  instanceType?: ContainerRuntimeInstanceType;
+  /** Selects the per-instance policy. Immutable once deployed. */
+  schedulingPolicy: "durable_object";
+}
+/**
+ * `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
+type ContainerConfig = DefaultScheduledContainerConfig | DurableObjectScheduledContainerConfig;
 /**
  * The value `defineContainer` returns: the validated config plus a brand the
  * codegen discovery and the generated Container DO class key on.
  */
-interface ContainerDefinition extends ContainerConfig {
+type ContainerDefinition = ContainerConfig & {
   /** Brand marking a value as a Lunora container definition. */
   readonly isLunoraContainer: true;
+};
+/**
+ * A saved container filesystem, as `snapshot()` returns it. Plain data: store
+ * it anywhere and pass it back to `start({ snapshot })`, from the same or
+ * another instance of the same container. Tied to the image it was taken
+ * from; Cloudflare keeps it 30 days, refreshed on each restore.
+ */
+interface ContainerSnapshot {
+  id: string;
+  name?: string;
+  /** Size in bytes. */
+  size: number;
 }
 /**
  * A normalized image source, as written into `wrangler.jsonc`.
@@ -268,4 +464,4 @@ type NormalizedContainerImage = {
  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
  */
 type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-export { BuildImageSource as B, ContainerDefinition as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };
+export { BuildImageSource as B, ContainerDefinition as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, SpawnResult as S, ContainerSpawnOptions as a, ContainerSnapshot as b, ContainerProcess as c, ContainerRuntimeInstanceType as d, ContainerSpawnRequest as e, DefaultScheduledContainerConfig as f, DurableObjectScheduledContainerConfig as g, ContainerImageSource as h, ContainerBackupStorage as i, ContainerConfig as j, ContainerConfigBase as k, ContainerInstanceType as l, ContainerNamedImageSource as m, ContainerReadinessCheck as n, ContainerRollout as o, CustomContainerInstanceType as p, NamedContainerInstanceType as q };

package/dist/packem_shared/sandbox-types.d-DXlHnsEg.d.mts

@@ -0,0 +1,110 @@
+import { SandboxDirectoryEntry, SandboxFileStat, DirectoryBackupRecord, S3MountInspection } from '@cloudflare/sandbox';
+/** Options every file operation accepts. */
+interface ContainerFileOptions {
+  /** Absolute directory a relative path is joined onto. */
+  cwd?: string;
+  /** Numeric `uid:gid` that opens the file. */
+  user?: string;
+}
+/** What `handle.files.writeFile` accepts. A stream is written as it arrives. */
+type ContainerFileContent = ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | string;
+/**
+ * Structured file operations on the instance's own disk (`handle.files`),
+ * through `@cloudflare/sandbox`'s `Files`. A filesystem failure rejects with a
+ * `LunoraError` whose `data.errno` is the Linux code (`ENOENT`, `EACCES`, …).
+ */
+interface ContainerFiles {
+  /** Create a directory; `recursive` creates parents and accepts an existing one. */
+  mkdir: (path: string, options?: ContainerFileOptions & {
+    recursive?: boolean;
+  }) => Promise<void>;
+  /** List a directory's immediate entries, without following symlinked entries. */
+  readDirectory: (path: string, options?: ContainerFileOptions) => Promise<SandboxDirectoryEntry[]>;
+  /**
+   * Stream a file out of the container. The body applies backpressure to the
+   * read. Read the body to the end or cancel it: the container is counted in
+   * flight until then, so an abandoned body keeps it from sleeping.
+   */
+  readFile: (path: string, options?: ContainerFileOptions) => Promise<Response>;
+  /** Remove a file or symlink; `recursive` removes a directory tree, `force` ignores a missing target. */
+  remove: (path: string, options?: ContainerFileOptions & {
+    force?: boolean;
+    recursive?: boolean;
+  }) => Promise<void>;
+  /** Rename within one filesystem (`EXDEV` across filesystems; there is no copy fallback). */
+  rename: (source: string, destination: string, options?: ContainerFileOptions) => Promise<void>;
+  /** Metadata for a path, following a final symlink. */
+  stat: (path: string, options?: ContainerFileOptions) => Promise<SandboxFileStat>;
+  /** Create or truncate a file and write `content` into it. */
+  writeFile: (path: string, content: ContainerFileContent, options?: ContainerFileOptions) => Promise<void>;
+}
+/** Options for `handle.backup()`. */
+interface ContainerBackupOptions {
+  /** gitignore-syntax patterns, relative to the directory, to leave out. */
+  exclude?: ReadonlyArray<string>;
+  /** Also apply `.gitignore` files inside the directory and `.git/info/exclude`. */
+  gitignore?: boolean;
+  /** A label stored with the backup. */
+  name?: string;
+}
+/**
+ * Credentials for an S3-compatible bucket mount, by **name**: each value is the
+ * name of a Worker secret (`wrangler secret put`) the container Durable Object
+ * reads at mount time. The keys themselves never appear in source, and the
+ * Worker signs every storage request, so they never enter the container either.
+ */
+interface ContainerMountCredentials {
+  /** Worker secret holding the access key id. */
+  accessKeyIdSecret: string;
+  /** Worker secret holding the secret access key. */
+  secretAccessKeySecret: string;
+  /** Worker secret holding a session token, for temporary credentials. */
+  sessionTokenSecret?: string;
+}
+/**
+ * An S3-compatible bucket (R2, S3, GCS) to mount at `path` with
+ * `handle.mount()`. For R2 the endpoint is
+ * `https://<account-id>.r2.cloudflarestorage.com` with region `"auto"`, and the
+ * credentials are an R2 API token's S3 keys — an R2 bucket binding is not used.
+ */
+interface ContainerMountRequest {
+  access: "read-only" | "read-write";
+  bucket: string;
+  credentials: ContainerMountCredentials;
+  endpoint: string;
+  /** Mount only this key prefix. A non-empty prefix ends in `/`. */
+  keyPrefix?: string;
+  /** Absolute path inside the container to mount at. */
+  path: string;
+  region: string;
+  /** Extra s3fs options, passed through as-is. */
+  s3fsOptions?: Readonly<Record<string, boolean | number | string>>;
+}
+/** The sandbox operations on a named instance of a `defineContainer({ sandbox: true })` container. */
+interface ContainerSandboxControls {
+  /**
+   * Save `directory` to the R2 bucket in the definition's `backups` and return its
+   * record — plain data to store and pass to `restore` later, here or on
+   * another instance, even one on a newer image. Pause writers in it first.
+   */
+  backup: (directory: string, options?: ContainerBackupOptions) => Promise<DirectoryBackupRecord>;
+  /** Delete a backup's object. Deleting one that is already gone succeeds. */
+  deleteBackup: (backup: DirectoryBackupRecord) => Promise<void>;
+  /** Structured file operations on the instance's disk. */
+  files: ContainerFiles;
+  /** Report a mount path's state without changing it. */
+  inspectMount: (path: string) => Promise<S3MountInspection>;
+  /** Mount an S3-compatible bucket at `request.path`. Mounting the same settings again reuses the mount. */
+  mount: (request: ContainerMountRequest) => Promise<void>;
+  /**
+   * Replace `options.directory` (default: the directory it was taken from) with the
+   * backup's contents. The target is swapped in only after the download is
+   * verified; a rejection means it was not replaced.
+   */
+  restore: (backup: DirectoryBackupRecord, options?: {
+    directory?: string;
+  }) => Promise<void>;
+  /** Stop access to a mount and unmount it. Never force-unmounts a busy path. */
+  unmount: (path: string) => Promise<void>;
+}
+export { ContainerFileOptions as C, ContainerFileContent as a, ContainerBackupOptions as b, ContainerMountRequest as c, ContainerSandboxControls as d, ContainerFiles as e, ContainerMountCredentials as f };

package/dist/packem_shared/sandbox-types.d-DXlHnsEg.d.ts

@@ -0,0 +1,110 @@
+import { SandboxDirectoryEntry, SandboxFileStat, DirectoryBackupRecord, S3MountInspection } from '@cloudflare/sandbox';
+/** Options every file operation accepts. */
+interface ContainerFileOptions {
+  /** Absolute directory a relative path is joined onto. */
+  cwd?: string;
+  /** Numeric `uid:gid` that opens the file. */
+  user?: string;
+}
+/** What `handle.files.writeFile` accepts. A stream is written as it arrives. */
+type ContainerFileContent = ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | string;
+/**
+ * Structured file operations on the instance's own disk (`handle.files`),
+ * through `@cloudflare/sandbox`'s `Files`. A filesystem failure rejects with a
+ * `LunoraError` whose `data.errno` is the Linux code (`ENOENT`, `EACCES`, …).
+ */
+interface ContainerFiles {
+  /** Create a directory; `recursive` creates parents and accepts an existing one. */
+  mkdir: (path: string, options?: ContainerFileOptions & {
+    recursive?: boolean;
+  }) => Promise<void>;
+  /** List a directory's immediate entries, without following symlinked entries. */
+  readDirectory: (path: string, options?: ContainerFileOptions) => Promise<SandboxDirectoryEntry[]>;
+  /**
+   * Stream a file out of the container. The body applies backpressure to the
+   * read. Read the body to the end or cancel it: the container is counted in
+   * flight until then, so an abandoned body keeps it from sleeping.
+   */
+  readFile: (path: string, options?: ContainerFileOptions) => Promise<Response>;
+  /** Remove a file or symlink; `recursive` removes a directory tree, `force` ignores a missing target. */
+  remove: (path: string, options?: ContainerFileOptions & {
+    force?: boolean;
+    recursive?: boolean;
+  }) => Promise<void>;
+  /** Rename within one filesystem (`EXDEV` across filesystems; there is no copy fallback). */
+  rename: (source: string, destination: string, options?: ContainerFileOptions) => Promise<void>;
+  /** Metadata for a path, following a final symlink. */
+  stat: (path: string, options?: ContainerFileOptions) => Promise<SandboxFileStat>;
+  /** Create or truncate a file and write `content` into it. */
+  writeFile: (path: string, content: ContainerFileContent, options?: ContainerFileOptions) => Promise<void>;
+}
+/** Options for `handle.backup()`. */
+interface ContainerBackupOptions {
+  /** gitignore-syntax patterns, relative to the directory, to leave out. */
+  exclude?: ReadonlyArray<string>;
+  /** Also apply `.gitignore` files inside the directory and `.git/info/exclude`. */
+  gitignore?: boolean;
+  /** A label stored with the backup. */
+  name?: string;
+}
+/**
+ * Credentials for an S3-compatible bucket mount, by **name**: each value is the
+ * name of a Worker secret (`wrangler secret put`) the container Durable Object
+ * reads at mount time. The keys themselves never appear in source, and the
+ * Worker signs every storage request, so they never enter the container either.
+ */
+interface ContainerMountCredentials {
+  /** Worker secret holding the access key id. */
+  accessKeyIdSecret: string;
+  /** Worker secret holding the secret access key. */
+  secretAccessKeySecret: string;
+  /** Worker secret holding a session token, for temporary credentials. */
+  sessionTokenSecret?: string;
+}
+/**
+ * An S3-compatible bucket (R2, S3, GCS) to mount at `path` with
+ * `handle.mount()`. For R2 the endpoint is
+ * `https://<account-id>.r2.cloudflarestorage.com` with region `"auto"`, and the
+ * credentials are an R2 API token's S3 keys — an R2 bucket binding is not used.
+ */
+interface ContainerMountRequest {
+  access: "read-only" | "read-write";
+  bucket: string;
+  credentials: ContainerMountCredentials;
+  endpoint: string;
+  /** Mount only this key prefix. A non-empty prefix ends in `/`. */
+  keyPrefix?: string;
+  /** Absolute path inside the container to mount at. */
+  path: string;
+  region: string;
+  /** Extra s3fs options, passed through as-is. */
+  s3fsOptions?: Readonly<Record<string, boolean | number | string>>;
+}
+/** The sandbox operations on a named instance of a `defineContainer({ sandbox: true })` container. */
+interface ContainerSandboxControls {
+  /**
+   * Save `directory` to the R2 bucket in the definition's `backups` and return its
+   * record — plain data to store and pass to `restore` later, here or on
+   * another instance, even one on a newer image. Pause writers in it first.
+   */
+  backup: (directory: string, options?: ContainerBackupOptions) => Promise<DirectoryBackupRecord>;
+  /** Delete a backup's object. Deleting one that is already gone succeeds. */
+  deleteBackup: (backup: DirectoryBackupRecord) => Promise<void>;
+  /** Structured file operations on the instance's disk. */
+  files: ContainerFiles;
+  /** Report a mount path's state without changing it. */
+  inspectMount: (path: string) => Promise<S3MountInspection>;
+  /** Mount an S3-compatible bucket at `request.path`. Mounting the same settings again reuses the mount. */
+  mount: (request: ContainerMountRequest) => Promise<void>;
+  /**
+   * Replace `options.directory` (default: the directory it was taken from) with the
+   * backup's contents. The target is swapped in only after the download is
+   * verified; a rejection means it was not replaced.
+   */
+  restore: (backup: DirectoryBackupRecord, options?: {
+    directory?: string;
+  }) => Promise<void>;
+  /** Stop access to a mount and unmount it. Never force-unmounts a busy path. */
+  unmount: (path: string) => Promise<void>;
+}
+export { ContainerFileOptions as C, ContainerFileContent as a, ContainerBackupOptions as b, ContainerMountRequest as c, ContainerSandboxControls as d, ContainerFiles as e, ContainerMountCredentials as f };

package/dist/sandbox/index.d.mts

@@ -0,0 +1,66 @@
+import { SandboxFileStat, SandboxDirectoryEntry, DirectoryBackupRecord, S3MountInspection } from '@cloudflare/sandbox';
+export { DirectoryBackupGateway, S3Gateway } from '@cloudflare/sandbox';
+import { LunoraContainer } from "../do/index.mjs";
+import { C as ContainerFileOptions, a as ContainerFileContent, b as ContainerBackupOptions, c as ContainerMountRequest } from "../packem_shared/sandbox-types.d-DXlHnsEg.mjs";
+import { C as ContainerDefinition } from "../packem_shared/jurisdiction.d-t4mtuqYW.mjs";
+import 'cloudflare:workers';
+type DurableObjectContext = ConstructorParameters<typeof LunoraContainer>[0];
+declare class LunoraSandboxContainer<Env = unknown> extends LunoraContainer<Env> {
+  #private;
+  constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: ConstructorParameters<typeof LunoraContainer>[4]);
+  lunoraReadFile(path: string, options?: ContainerFileOptions): Promise<Response>;
+  lunoraWriteFile(path: string, content: ContainerFileContent, options?: ContainerFileOptions): Promise<void>;
+  lunoraStat(path: string, options?: ContainerFileOptions): Promise<SandboxFileStat>;
+  lunoraReadDirectory(path: string, options?: ContainerFileOptions): Promise<SandboxDirectoryEntry[]>;
+  lunoraMkdir(path: string, options?: ContainerFileOptions & {
+    recursive?: boolean;
+  }): Promise<void>;
+  lunoraRename(source: string, destination: string, options?: ContainerFileOptions): Promise<void>;
+  lunoraRemove(path: string, options?: ContainerFileOptions & {
+    force?: boolean;
+    recursive?: boolean;
+  }): Promise<void>;
+  lunoraBackup(directory: string, options?: ContainerBackupOptions): Promise<DirectoryBackupRecord>;
+  lunoraRestore(backup: DirectoryBackupRecord, options?: {
+    directory?: string;
+  }): Promise<void>;
+  /** Needs no running container — it only deletes the object. */
+  lunoraDeleteBackup(backup: DirectoryBackupRecord): Promise<void>;
+  lunoraMount(request: ContainerMountRequest): Promise<void>;
+  lunoraInspectMount(path: string): Promise<S3MountInspection>;
+  lunoraUnmount(path: string): Promise<void>;
+  /**
+   * Route backup traffic to its gateway before the base installs the egress
+   * policy's catch-all, which takes every hostname registered after it.
+   * Without an egress policy there is no catch-all, and each backup or
+   * restore registers its own route when it runs.
+   */
+  protected override beforeContainerStart(): Promise<void>;
+  /** Run one helper operation on the running container, translating sandbox errors. */
+  private withContainer;
+  private files;
+  /** One `DirectoryBackup` per instance: it runs one operation at a time per container, which only holds if every call shares it. */
+  private backups;
+  private mounts;
+  /** A Worker entrypoint from `ctx.exports`, with the fix when the worker does not export it. */
+  private workerExport;
+  /** Resolve a mount's credentials from the Worker secrets they name. */
+  private mountCredentials;
+  private label;
+}
+export {
+/**
+ * `@lunora/container/sandbox` — the workerd-only half of the Sandbox SDK
+ * helpers (`@cloudflare/sandbox`) a `defineContainer({ sandbox: true })`
+ * container uses. A separate subpath from `/do`, so an app that never opts in
+ * never loads `@cloudflare/sandbox` (or the `zod` it depends on).
+ *
+ * `LunoraSandboxContainer` is the base class codegen extends for a `sandbox:
+ * true` container: `LunoraContainer` plus the file, backup and bucket-mount
+ * RPCs the named-instance handle calls. `DirectoryBackupGateway` and
+ * `S3Gateway` are the `WorkerEntrypoint`s the backup and mount helpers route
+ * the container's storage traffic through (reached as `ctx.exports.<Name>`),
+ * so the deployed worker must export both; the generated
+ * `_generated/containers.ts` re-exports them from here.
+ */
+LunoraSandboxContainer };