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

package/README.md

@@ -10,6 +10,8 @@
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 <br />
 
 <div align="center">
@@ -125,7 +127,7 @@ export const worker = defineContainer({
 
 ### Secrets and Secrets Store
 
-`secrets` forwards plain Worker secrets into the container env; `secretsStore` maps a _container env-var name → Cloudflare [Secrets Store](https://developers.cloudflare.com/secrets-store/) binding name_ and resolves each with its async `.get()` at first start (memoised). A collision with `env`/`secrets` is rejected at authoring time; a missing binding fails the start — the same fail-closed stance as `secrets`. Like `env`/`secrets`, these injected values only apply to implicit starts or a bare `start()`; a per-instance `start({ envVars })` replaces the env set wholesale (and skips Secrets Store resolution entirely).
+`secrets` forwards plain Worker secrets into the container env; `secretsStore` maps a _container env-var name → Cloudflare [Secrets Store](https://developers.cloudflare.com/secrets-store/) binding name_ and resolves each with its async `.get()` at first start (memoised). A collision with `env`/`secrets` is rejected at authoring time; a missing binding fails the start — the same fail-closed stance as `secrets`. A per-instance `start({ envVars })` replaces the env set wholesale (and skips Secrets Store resolution entirely), and is persisted for that instance: later starts, including implicit restarts, reuse it until `destroy()`. The override cannot change while the container is running or still starting: a differing `start({ envVars })` is rejected with `CONFLICT` in either case, so `stop()` it (and let any start in flight finish) first.
 
 ```ts
 export const worker = defineContainer({
@@ -170,13 +172,30 @@ export const api = defineContainer({
 
 ### Hard timeout
 
-`sleepAfter` caps _idle_ time; `hardTimeout` caps _total_ lifetime — a runaway-cost backstop measured from start, regardless of activity (same grammar as `sleepAfter`). When it elapses the generated class's `onHardTimeoutExpired` hook runs (default: `stop()`); the timer is run-generation-stamped so a stale timer from a slept/crashed run can't kill a fresh one.
+`sleepAfter` caps _idle_ time; `hardTimeout` caps _total_ lifetime — a runaway-cost backstop measured from start, regardless of activity (same grammar as `sleepAfter`). When it elapses the generated class's `onHardTimeoutExpired` hook runs (default: `stop()`, i.e. SIGTERM with no escalation — a container that ignores SIGTERM outlives its cap unless you override the hook and follow up with `destroy()`); the timer is run-generation-stamped so a stale timer from a slept/crashed run can't kill a fresh one.
 
 ```ts
 export const job = defineContainer({
     image: "./containers/job",
-    hardTimeout: "1h", // never run longer than an hour, busy or not
+    hardTimeout: "1h", // stopped after an hour, busy or not
+});
+```
+
+### Per-instance images and snapshots
+
+`schedulingPolicy: "durable_object"` (Cloudflare public beta) lets each instance pick its image and size at start, and save and restore its filesystem:
+
+```ts
+export const agentComputer = defineContainer({
+    schedulingPolicy: "durable_object",
+    images: { base: "./containers/base" },
+    image: "base",
 });
+
+const computer = ctx.containers.agentComputer.get(taskId);
+await computer.start({ image: "base", instanceType: "standard-2" });
+const saved = await computer.snapshot();
+await ctx.containers.agentComputer.get(otherId).start({ snapshot: saved });
 ```
 
 ### Calling Lunora from inside a container
@@ -194,7 +213,7 @@ await lunora.mutation("jobs:markDone", { id: pending[0].id });
 
 The token is a bearer your Worker's `resolveIdentity` recognizes — pass it to the container as a `secret`. Non-JS containers can `POST /_lunora/rpc` with `{ functionPath, args }` directly.
 
-Secure the bridge in `resolveIdentity`: read `request.headers.get("authorization")`, strip the `Bearer ` prefix, and compare the token against a Worker secret (e.g. `env.LUNORA_CONTAINER_TOKEN`) you also forward to the container. Return a `{ userId }` identity only on a match and `null` otherwise — an unrecognised request then runs anonymously and is rejected by your functions' own authorization checks. See [Securing the bridge](https://lunora.sh/docs/addons/containers#securing-the-bridge) for the full example.
+Secure the bridge in `resolveIdentity`: read `request.headers.get("authorization")`, strip the `Bearer ` prefix, and compare the token against a Worker secret (e.g. `env.LUNORA_CONTAINER_TOKEN`) you also forward to the container. Return a `{ userId }` identity only on a match and `null` otherwise — an unrecognised request then runs anonymously and is rejected by your functions' own authorization checks. See [Securing the bridge](https://lunora.sh/docs/packages/container#securing-the-bridge) for the full example.
 
 ### Entry points
 
@@ -202,7 +221,7 @@ Secure the bridge in `resolveIdentity`: read `request.headers.get("authorization
 - `@lunora/container/do` — workerd-only: the `LunoraContainer` base class the generated DO classes extend (pulls in `@cloudflare/containers`).
 - `@lunora/container/bridge` — runtime-agnostic: `createContainerBridge` for calling Lunora functions from inside a container.
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/containers)**.
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/container)**.
 
 ### Known platform limitations
 

package/dist/bridge.d.mts

@@ -1,5 +1,7 @@
 import { LunoraError } from '@lunora/errors';
-/** A `fetch` implementation — defaults to the runtime global. */
+/**
+ * A `fetch` implementation — defaults to the runtime global.
+ */
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -10,33 +12,38 @@ type FetchLike = (input: string, init: {
   status: number;
   statusText?: string;
 }>;
+/**
+ * `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
 interface ContainerBridgeOptions {
   /**
-  * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
-  * `https://my-app.workers.dev`. In a Lunora container, surface it as an
-  * `env` value on the definition.
-  */
+   * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
+   * `https://my-app.workers.dev`. In a Lunora container, surface it as an
+   * `env` value on the definition.
+   */
   baseUrl: string;
   /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
   fetch?: FetchLike;
   /**
-  * Bearer token sent as `Authorization: Bearer &lt;token>`. Your Worker's
-  * `resolveIdentity` maps it to the identity the called functions run as.
-  * Pass it to the container as a `secret`, never bake it into the image.
-  */
+   * Bearer token sent as `Authorization: Bearer <token>`. Your Worker's
+   * `resolveIdentity` maps it to the identity the called functions run as.
+   * Pass it to the container as a `secret`, never bake it into the image.
+   */
   token?: string;
 }
-/** Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`. */
+/**
+ * Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`.
+ */
 declare class ContainerBridgeError extends LunoraError {
   constructor(code: string, message: string);
 }
 /**
-* Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
-* handle the generated `_generated/api` object carries. Declared locally (not
-* imported) so the bridge stays dependency-free and its `.d.ts` is
-* self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
-* reference is assignable and its arg/return types are inferable.
-*/
+ * Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
+ * handle the generated `_generated/api` object carries. Declared locally (not
+ * imported) so the bridge stays dependency-free and its `.d.ts` is
+ * self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
+ * reference is assignable and its arg/return types are inferable.
+ */
 interface BridgeFunctionReference<Args = unknown, Result = unknown> {
   readonly __lunoraPhantom?: {
     args: Args;
@@ -56,6 +63,9 @@ type ResultOfReference<Reference> = Reference extends {
     returns: infer Result;
   };
 } ? Result : never;
+/**
+ * `ContainerBridge` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
 interface ContainerBridge {
   /** Call an `action` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
   action: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
@@ -66,25 +76,25 @@ interface ContainerBridge {
   /** Call a `query` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
   query: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
   /**
-  * Fully-typed call via a generated function reference. Pass a reference from
-  * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
-  * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
-  * for JS/TS containers that can import the generated `api`.
-  */
+   * Fully-typed call via a generated function reference. Pass a reference from
+   * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
+   * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
+   * for JS/TS containers that can import the generated `api`.
+   */
   run: <Reference extends BridgeFunctionReference>(reference: Reference, args: ArgsOfReference<Reference>, shardKey?: string) => Promise<ResultOfReference<Reference>>;
 }
 /**
-* Build a container→Lunora bridge bound to a Worker URL + token.
-*
-* ```ts
-* const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
-* const messages = await lunora.query("messages:list", { limit: 20 });
-* await lunora.mutation("messages:markProcessed", { id });
-* ```
-*
-* `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
-* wire is identical and the server dispatches by the function's registered
-* kind, so a query path called via `.mutation(...)` still runs as a query.
-*/
+ * Build a container→Lunora bridge bound to a Worker URL + token.
+ *
+ * ```ts
+ * const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
+ * const messages = await lunora.query("messages:list", { limit: 20 });
+ * await lunora.mutation("messages:markProcessed", { id });
+ * ```
+ *
+ * `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
+ * wire is identical and the server dispatches by the function's registered
+ * kind, so a query path called via `.mutation(...)` still runs as a query.
+ */
 declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
 export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.d.ts

@@ -1,5 +1,7 @@
 import { LunoraError } from '@lunora/errors';
-/** A `fetch` implementation — defaults to the runtime global. */
+/**
+ * A `fetch` implementation — defaults to the runtime global.
+ */
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -10,33 +12,38 @@ type FetchLike = (input: string, init: {
   status: number;
   statusText?: string;
 }>;
+/**
+ * `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
 interface ContainerBridgeOptions {
   /**
-  * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
-  * `https://my-app.workers.dev`. In a Lunora container, surface it as an
-  * `env` value on the definition.
-  */
+   * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
+   * `https://my-app.workers.dev`. In a Lunora container, surface it as an
+   * `env` value on the definition.
+   */
   baseUrl: string;
   /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
   fetch?: FetchLike;
   /**
-  * Bearer token sent as `Authorization: Bearer &lt;token>`. Your Worker's
-  * `resolveIdentity` maps it to the identity the called functions run as.
-  * Pass it to the container as a `secret`, never bake it into the image.
-  */
+   * Bearer token sent as `Authorization: Bearer <token>`. Your Worker's
+   * `resolveIdentity` maps it to the identity the called functions run as.
+   * Pass it to the container as a `secret`, never bake it into the image.
+   */
   token?: string;
 }
-/** Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`. */
+/**
+ * Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`.
+ */
 declare class ContainerBridgeError extends LunoraError {
   constructor(code: string, message: string);
 }
 /**
-* Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
-* handle the generated `_generated/api` object carries. Declared locally (not
-* imported) so the bridge stays dependency-free and its `.d.ts` is
-* self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
-* reference is assignable and its arg/return types are inferable.
-*/
+ * Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
+ * handle the generated `_generated/api` object carries. Declared locally (not
+ * imported) so the bridge stays dependency-free and its `.d.ts` is
+ * self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
+ * reference is assignable and its arg/return types are inferable.
+ */
 interface BridgeFunctionReference<Args = unknown, Result = unknown> {
   readonly __lunoraPhantom?: {
     args: Args;
@@ -56,6 +63,9 @@ type ResultOfReference<Reference> = Reference extends {
     returns: infer Result;
   };
 } ? Result : never;
+/**
+ * `ContainerBridge` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
 interface ContainerBridge {
   /** Call an `action` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
   action: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
@@ -66,25 +76,25 @@ interface ContainerBridge {
   /** Call a `query` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
   query: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
   /**
-  * Fully-typed call via a generated function reference. Pass a reference from
-  * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
-  * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
-  * for JS/TS containers that can import the generated `api`.
-  */
+   * Fully-typed call via a generated function reference. Pass a reference from
+   * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
+   * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
+   * for JS/TS containers that can import the generated `api`.
+   */
   run: <Reference extends BridgeFunctionReference>(reference: Reference, args: ArgsOfReference<Reference>, shardKey?: string) => Promise<ResultOfReference<Reference>>;
 }
 /**
-* Build a container→Lunora bridge bound to a Worker URL + token.
-*
-* ```ts
-* const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
-* const messages = await lunora.query("messages:list", { limit: 20 });
-* await lunora.mutation("messages:markProcessed", { id });
-* ```
-*
-* `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
-* wire is identical and the server dispatches by the function's registered
-* kind, so a query path called via `.mutation(...)` still runs as a query.
-*/
+ * Build a container→Lunora bridge bound to a Worker URL + token.
+ *
+ * ```ts
+ * const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
+ * const messages = await lunora.query("messages:list", { limit: 20 });
+ * await lunora.mutation("messages:markProcessed", { id });
+ * ```
+ *
+ * `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
+ * wire is identical and the server dispatches by the function's registered
+ * kind, so a query path called via `.mutation(...)` still runs as a query.
+ */
 declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
 export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.mjs

@@ -1,79 +1 @@
-import { LunoraError } from '@lunora/errors';
-
-const RPC_PATH = "/_lunora/rpc";
-class ContainerBridgeError extends LunoraError {
-  constructor(code, message) {
-    super(code, message, { name: "ContainerBridgeError" });
-  }
-}
-const joinUrl = (baseUrl, path) => {
-  let base = baseUrl;
-  while (base.endsWith("/")) {
-    base = base.slice(0, -1);
-  }
-  return `${base}${path}`;
-};
-const statusError = (functionPath, response) => new Error(
-  `createContainerBridge: request to "${functionPath}" failed (status ${String(response.status)}${response.statusText ? ` ${response.statusText}` : ""})`
-);
-const parseResponseBody = async (response, functionPath) => {
-  try {
-    return await response.json();
-  } catch {
-    if (!response.ok) {
-      throw statusError(functionPath, response);
-    }
-    throw new LunoraError(
-      "INTERNAL",
-      `createContainerBridge: request to "${functionPath}" returned a non-JSON response (status ${String(response.status)})`
-    );
-  }
-};
-const createContainerBridge = (options) => {
-  if (typeof options.baseUrl !== "string" || options.baseUrl.length === 0) {
-    throw new TypeError("createContainerBridge: `baseUrl` must be a non-empty Worker URL (e.g. https://my-app.workers.dev) — is the URL env var set?");
-  }
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  const call = async (functionPath, args = {}, shardKey) => {
-    if (typeof fetchImpl !== "function") {
-      throw new TypeError("createContainerBridge: no `fetch` available — pass `fetch` in options for this runtime.");
-    }
-    const headers = { "content-type": "application/json" };
-    if (options.token !== void 0) {
-      headers.authorization = `Bearer ${options.token}`;
-    }
-    const response = await fetchImpl(joinUrl(options.baseUrl, RPC_PATH), {
-      body: JSON.stringify({ args, functionPath, shardKey }),
-      headers,
-      method: "POST"
-    });
-    const body = await parseResponseBody(response, functionPath);
-    if (typeof body === "object" && body !== null && "error" in body) {
-      const { error } = body;
-      if (typeof error === "object" && error !== null) {
-        const { code, message } = error;
-        if (typeof code === "string" && typeof message === "string") {
-          throw new ContainerBridgeError(code, message);
-        }
-      }
-      let detail;
-      try {
-        detail = JSON.stringify(error);
-      } catch {
-        detail = String(error);
-      }
-      throw new LunoraError(
-        "INTERNAL",
-        `createContainerBridge: request to "${functionPath}" returned a malformed error envelope (status ${String(response.status)}): ${detail}`
-      );
-    }
-    if (!response.ok) {
-      throw statusError(functionPath, response);
-    }
-    return body.result;
-  };
-  const run = async (reference, args, shardKey) => call(reference.__lunoraRef, args, shardKey);
-  return { action: call, call, mutation: call, query: call, run };
-};
-
-export { ContainerBridgeError, createContainerBridge };
+import{LunoraError as u}from"@lunora/errors";import{encodeWire as h,decodeWire as p}from"@lunora/wire";const w="/_lunora/rpc";class m extends u{constructor(r,t){super(r,t,{name:"ContainerBridgeError"})}}const b=(e,r)=>{let t=e;for(;t.endsWith("/");)t=t.slice(0,-1);return`${t}${r}`},y=(e,r)=>new Error(`createContainerBridge: request to "${e}" failed (status ${String(r.status)}${r.statusText?` ${r.statusText}`:""})`),$=async(e,r)=>{try{return await e.json()}catch{throw e.ok?new u("INTERNAL",`createContainerBridge: request to "${r}" returned a non-JSON response (status ${String(e.status)})`):y(r,e)}},T=e=>{if(typeof e.baseUrl!="string"||e.baseUrl.length===0)throw new TypeError("createContainerBridge: `baseUrl` must be a non-empty Worker URL (e.g. https://my-app.workers.dev) — is the URL env var set?");const r=e.fetch??globalThis.fetch,t=async(o,i={},c)=>{if(typeof r!="function")throw new TypeError("createContainerBridge: no `fetch` available — pass `fetch` in options for this runtime.");const d={"content-type":"application/json"};e.token!==void 0&&(d.authorization=`Bearer ${e.token}`);const s=await r(b(e.baseUrl,w),{body:JSON.stringify({args:h(i),functionPath:o,shardKey:c}),headers:d,method:"POST"}),n=await $(s,o);if(typeof n=="object"&&n!==null&&"error"in n){const{error:a}=n;if(typeof a=="object"&&a!==null){const{code:f,message:g}=a;if(typeof f=="string"&&typeof g=="string")throw new m(f,g)}let l;try{l=JSON.stringify(a)}catch{l=String(a)}throw new u("INTERNAL",`createContainerBridge: request to "${o}" returned a malformed error envelope (status ${String(s.status)}): ${l}`)}if(!s.ok)throw y(o,s);return p(n.result)};return{action:t,call:t,mutation:t,query:t,run:async(o,i,c)=>t(o.__lunoraRef,i,c)}};export{m as ContainerBridgeError,T as createContainerBridge};