@lunora/container 1.0.0-alpha.8 → 1.0.0-alpha.80

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-BwpauCoI.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 };

package/dist/sandbox/index.d.ts

@@ -0,0 +1,66 @@
+import { SandboxFileStat, SandboxDirectoryEntry, DirectoryBackupRecord, S3MountInspection } from '@cloudflare/sandbox';
+export { DirectoryBackupGateway, S3Gateway } from '@cloudflare/sandbox';
+import { LunoraContainer } from "../do/index.js";
+import { C as ContainerFileOptions, a as ContainerFileContent, b as ContainerBackupOptions, c as ContainerMountRequest } from "../packem_shared/sandbox-types.d-DXlHnsEg.js";
+import { C as ContainerDefinition } from "../packem_shared/jurisdiction.d-BwpauCoI.js";
+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 };

package/dist/sandbox/index.mjs

@@ -0,0 +1 @@
+import{default as r}from"../packem_shared/LunoraSandboxContainer-DPnhJUu1.mjs";import{DirectoryBackupGateway as t,S3Gateway as n}from"@cloudflare/sandbox";export{t as DirectoryBackupGateway,r as LunoraSandboxContainer,n as S3Gateway};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.80",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",
@@ -46,13 +46,23 @@
       "types": "./dist/bridge.d.ts",
       "import": "./dist/bridge.mjs"
     },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "import": "./dist/otel.mjs"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox/index.d.ts",
+      "import": "./dist/sandbox/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.3"
+    "@cloudflare/sandbox": "1.0.0",
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/wire": "1.0.0-alpha.1"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"