@lunora/container 1.0.0-alpha.4 → 1.0.0-alpha.41

package/LICENSE.md

@@ -103,3 +103,29 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+
+# Licenses of bundled dependencies
+The published @lunora/container artifact additionally contains code with the following licenses:
+MIT OR Apache-2.0
+
+# Bundled dependencies:
+## @cloudflare/containers
+License: MIT OR Apache-2.0
+Repository: git+https://github.com/cloudflare/containers.git
+
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+
+# Licenses of bundled types
+The published @lunora/container artifact additionally contains code with the following licenses:
+MIT OR Apache-2.0
+
+# Bundled types:
+## @cloudflare/containers
+License: MIT OR Apache-2.0
+Repository: git+https://github.com/cloudflare/containers.git
+
+<!-- /TYPE_DEPENDENCIES -->

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">
@@ -90,7 +92,9 @@ export const transcode = action.input({ videoId: v.id("videos") }).action(async
 });
 ```
 
-`ctx.containers` is action-only (container calls are external I/O, like `ctx.fetch`); `.get(name)` handles also expose `start`/`stop`/`destroy`/`getState` lifecycle control plus `renewActivityTimeout()` (keep a busy WebSocket's container awake) and `egress.*` (adjust the allow/deny lists at runtime).
+`.get()` and `.any()` retry the **same** instance through a cold start — when a request lands while Cloudflare is still provisioning (a `503` "no instance", `500` "Failed to start", `429`, or "not listening"), they back off and retry (default 3 attempts) so the provisioning race never reaches your handler. Genuine app `5xx`s pass straight through. Tune or disable per call with `.get(id, { attempts, backoffMs })` (a pre-built `Request` is sent once and not retried, since its body may not be replayable).
+
+`ctx.containers` is action-only (container calls are external I/O, like `ctx.fetch`); `.get(name)` handles also expose `start`/`stop`/`destroy`/`getState` lifecycle control plus `renewActivityTimeout()` and `egress.*` (adjust the allow/deny lists at runtime). HTTP requests and WebSocket frames already keep a busy container awake automatically; `renewActivityTimeout()` is the escape hatch for non-HTTP/non-WS activity.
 
 The config layer (`lunora dev` / `lunora deploy`) reconciles the wrangler `containers[]` entry, the `CONTAINER_*` Durable Object binding, and the SQLite-class migration automatically; `wrangler deploy` builds the Dockerfile with local Docker and pushes it to the Cloudflare Registry.
 
@@ -121,6 +125,18 @@ 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).
+
+```ts
+export const worker = defineContainer({
+    image: "./containers/worker",
+    secrets: ["TRANSCODER_API_KEY"], // plain Worker secret → same-named env var
+    secretsStore: { STRIPE_KEY: "STRIPE_SECRET" }, // env.STRIPE_SECRET.get() → STRIPE_KEY
+});
+```
+
 ### Egress firewall
 
 Pair `enableInternet: false` with an `allowedHosts` allow-list (or layer a `deniedHosts` deny-list that overrides everything) to constrain a container's outbound traffic; `interceptHttps: true` extends the lists to TLS connections (the image must trust the Cloudflare CA). Codegen re-exports the `ContainerProxy` worker entrypoint the interception path needs automatically.
@@ -180,7 +196,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
 
@@ -188,7 +204,17 @@ 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
+
+Some constraints live in Cloudflare Containers itself (open issues on [`cloudflare/containers`](https://github.com/cloudflare/containers/issues)). Lunora papers over what it can — cold-start retry and WebSocket keep-alive — and surfaces the rest:
+
+- **No autoscaling / location-aware routing** — pools are fixed-size and pick uniformly at random ([#226](https://github.com/cloudflare/containers/issues/226)).
+- **Ephemeral disk; no FUSE / tmpfs / some `node:net` modes** — persist to [`@lunora/storage`](https://www.npmjs.com/package/@lunora/storage) (R2) ([#112](https://github.com/cloudflare/containers/issues/112), [#160](https://github.com/cloudflare/containers/issues/160), [#67](https://github.com/cloudflare/containers/issues/67)).
+- **Egress interception is HTTP-first** — HTTPS needs `interceptHttps`; raw gRPC isn't interceptable yet ([#195](https://github.com/cloudflare/containers/issues/195)).
+- **Long jobs can be terminated on rollout** — use `hardTimeout` and make work resumable ([#138](https://github.com/cloudflare/containers/issues/138)).
+- **Local dev can't pull from the Cloudflare Registry** — build from a local Dockerfile ([#155](https://github.com/cloudflare/containers/issues/155)).
 
 ## Related
 

package/dist/bridge.d.mts

@@ -1,4 +1,7 @@
-/** A `fetch` implementation — defaults to the runtime global. */
+import { LunoraError } from '@lunora/errors';
+/**
+ * A `fetch` implementation — defaults to the runtime global.
+ */
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -9,34 +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. Carries the wire `code`. */
-declare class ContainerBridgeError extends Error {
-  readonly code: string;
+/**
+ * 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,4 +1,7 @@
-/** A `fetch` implementation — defaults to the runtime global. */
+import { LunoraError } from '@lunora/errors';
+/**
+ * A `fetch` implementation — defaults to the runtime global.
+ */
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -9,34 +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. Carries the wire `code`. */
-declare class ContainerBridgeError extends Error {
-  readonly code: string;
+/**
+ * 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,76 +1 @@
-const RPC_PATH = "/_lunora/rpc";
-class ContainerBridgeError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "ContainerBridgeError";
-    this.code = code;
-  }
-}
-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 Error(`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 Error(
-        `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";const h="/_lunora/rpc";class w extends u{constructor(r,e){super(r,e,{name:"ContainerBridgeError"})}}const p=(t,r)=>{let e=t;for(;e.endsWith("/");)e=e.slice(0,-1);return`${e}${r}`},g=(t,r)=>new Error(`createContainerBridge: request to "${t}" failed (status ${String(r.status)}${r.statusText?` ${r.statusText}`:""})`),m=async(t,r)=>{try{return await t.json()}catch{throw t.ok?new u("INTERNAL",`createContainerBridge: request to "${r}" returned a non-JSON response (status ${String(t.status)})`):g(r,t)}},B=t=>{if(typeof t.baseUrl!="string"||t.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=t.fetch??globalThis.fetch,e=async(n,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"};t.token!==void 0&&(d.authorization=`Bearer ${t.token}`);const s=await r(p(t.baseUrl,h),{body:JSON.stringify({args:i,functionPath:n,shardKey:c}),headers:d,method:"POST"}),o=await m(s,n);if(typeof o=="object"&&o!==null&&"error"in o){const{error:a}=o;if(typeof a=="object"&&a!==null){const{code:f,message:y}=a;if(typeof f=="string"&&typeof y=="string")throw new w(f,y)}let l;try{l=JSON.stringify(a)}catch{l=String(a)}throw new u("INTERNAL",`createContainerBridge: request to "${n}" returned a malformed error envelope (status ${String(s.status)}): ${l}`)}if(!s.ok)throw g(n,s);return o.result};return{action:e,call:e,mutation:e,query:e,run:async(n,i,c)=>e(n.__lunoraRef,i,c)}};export{w as ContainerBridgeError,B as createContainerBridge};