@lunora/container 0.0.0 → 1.0.0-alpha.2

package/dist/bridge.d.mts

@@ -0,0 +1,90 @@
+/** A `fetch` implementation — defaults to the runtime global. */
+type FetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+}) => Promise<{
+  json: () => Promise<unknown>;
+  ok: boolean;
+  status: number;
+  statusText?: string;
+}>;
+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.
+  */
+  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.
+  */
+  token?: string;
+}
+/** Thrown when a Lunora function returns an error envelope. Carries the wire `code`. */
+declare class ContainerBridgeError extends Error {
+  readonly code: string;
+  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.
+*/
+interface BridgeFunctionReference<Args = unknown, Result = unknown> {
+  readonly __lunoraPhantom?: {
+    args: Args;
+    returns: Result;
+  };
+  readonly __lunoraRef: string;
+}
+/** Infer the args type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ArgsOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    args: infer Args;
+  };
+} ? Args : never;
+/** Infer the result type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ResultOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    returns: infer Result;
+  };
+} ? Result : never;
+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>;
+  /** Call any Lunora function by `namespace:fn` path; the server resolves its kind. */
+  call: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `mutation` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  mutation: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** 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`.
+  */
+  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.
+*/
+declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
+export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.d.ts

@@ -0,0 +1,90 @@
+/** A `fetch` implementation — defaults to the runtime global. */
+type FetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+}) => Promise<{
+  json: () => Promise<unknown>;
+  ok: boolean;
+  status: number;
+  statusText?: string;
+}>;
+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.
+  */
+  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.
+  */
+  token?: string;
+}
+/** Thrown when a Lunora function returns an error envelope. Carries the wire `code`. */
+declare class ContainerBridgeError extends Error {
+  readonly code: string;
+  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.
+*/
+interface BridgeFunctionReference<Args = unknown, Result = unknown> {
+  readonly __lunoraPhantom?: {
+    args: Args;
+    returns: Result;
+  };
+  readonly __lunoraRef: string;
+}
+/** Infer the args type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ArgsOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    args: infer Args;
+  };
+} ? Args : never;
+/** Infer the result type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ResultOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    returns: infer Result;
+  };
+} ? Result : never;
+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>;
+  /** Call any Lunora function by `namespace:fn` path; the server resolves its kind. */
+  call: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `mutation` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  mutation: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** 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`.
+  */
+  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.
+*/
+declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
+export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.mjs

@@ -0,0 +1,76 @@
+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 };

package/dist/do/index.d.mts

@@ -0,0 +1,63 @@
+import { Container, StopParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.mjs";
+/**
+* Cloudflare Durable Object data-residency jurisdiction. Widening union —
+* Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
+* Forward one lifecycle envelope to the root ShardDO's log buffer, best-effort.
+*
+* `env` is the Container DO's worker `env`: we read the `SHARD` namespace and
+* the `LUNORA_ADMIN_TOKEN` from it. Returns a promise that NEVER rejects — every
+* failure path (missing binding, missing token, fetch error) resolves to
+* `undefined` — so the caller can `void` it from a lifecycle hook safely.
+*/
+type DurableObjectContext = ConstructorParameters<typeof Container>[0];
+/**
+* Base class for the generated Container DO classes. Applies a
+* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+* port, sleep timeout, internet access, and the container environment (static
+* `env` merged with the declared Worker secrets — a declared-but-unset secret
+* fails fast here rather than starting a container without its credential).
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class TranscoderContainer extends LunoraContainer {
+*     constructor(ctx: DurableObjectState, env: Env) {
+*         super(ctx, env, transcoder, "transcoder");
+*     }
+* }
+* ```
+*/
+declare class LunoraContainer<Env = unknown> extends Container<Env> {
+  /**
+  * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
+  * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
+  * to the same region as the root shard. `undefined` ⇒ un-pinned.
+  */
+  private readonly lunoraJurisdiction?;
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  private readonly lunoraName;
+  constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
+  override onError(error: unknown): unknown;
+  override onStart(): Promise<void>;
+  override onStop(parameters: StopParams): Promise<void>;
+  /**
+  * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+  * also appears in the Studio Logs panel (the terminal already has it via
+  * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+  * out of a lifecycle hook — the `console` path stays the source of truth.
+  */
+  private surfaceInStudioLogs;
+  /**
+  * Per-instance correlation id: the Durable Object id, which Cloudflare also
+  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+  * defensively — the id shape varies and isn't worth crashing a hook over.
+  */
+  private instanceId;
+}
+export { LunoraContainer as default };

package/dist/do/index.d.ts

@@ -0,0 +1,63 @@
+import { Container, StopParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.js";
+/**
+* Cloudflare Durable Object data-residency jurisdiction. Widening union —
+* Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
+* Forward one lifecycle envelope to the root ShardDO's log buffer, best-effort.
+*
+* `env` is the Container DO's worker `env`: we read the `SHARD` namespace and
+* the `LUNORA_ADMIN_TOKEN` from it. Returns a promise that NEVER rejects — every
+* failure path (missing binding, missing token, fetch error) resolves to
+* `undefined` — so the caller can `void` it from a lifecycle hook safely.
+*/
+type DurableObjectContext = ConstructorParameters<typeof Container>[0];
+/**
+* Base class for the generated Container DO classes. Applies a
+* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+* port, sleep timeout, internet access, and the container environment (static
+* `env` merged with the declared Worker secrets — a declared-but-unset secret
+* fails fast here rather than starting a container without its credential).
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class TranscoderContainer extends LunoraContainer {
+*     constructor(ctx: DurableObjectState, env: Env) {
+*         super(ctx, env, transcoder, "transcoder");
+*     }
+* }
+* ```
+*/
+declare class LunoraContainer<Env = unknown> extends Container<Env> {
+  /**
+  * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
+  * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
+  * to the same region as the root shard. `undefined` ⇒ un-pinned.
+  */
+  private readonly lunoraJurisdiction?;
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  private readonly lunoraName;
+  constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
+  override onError(error: unknown): unknown;
+  override onStart(): Promise<void>;
+  override onStop(parameters: StopParams): Promise<void>;
+  /**
+  * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+  * also appears in the Studio Logs panel (the terminal already has it via
+  * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+  * out of a lifecycle hook — the `console` path stays the source of truth.
+  */
+  private surfaceInStudioLogs;
+  /**
+  * Per-instance correlation id: the Durable Object id, which Cloudflare also
+  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+  * defensively — the id shape varies and isn't worth crashing a hook over.
+  */
+  private instanceId;
+}
+export { LunoraContainer as default };

package/dist/do/index.mjs

@@ -0,0 +1,138 @@
+import { Container } from '@cloudflare/containers';
+import { resolveContainerEnvVars as resolveContainerEnvVariables } from '../packem_shared/containerBindingName-BGdSdFNA.mjs';
+
+const LUNORA_EVENT_SOURCE = "lunora";
+const buildContainerLifecycleEvent = (container, instance, event, message) => {
+  return {
+    container,
+    event,
+    instance,
+    level: event === "error" ? "error" : "info",
+    message,
+    source: LUNORA_EVENT_SOURCE,
+    ts: Date.now(),
+    type: "container"
+  };
+};
+const emitContainerLifecycle = (container, instance, event, message) => {
+  const envelope = buildContainerLifecycleEvent(container, instance, event, message);
+  const line = JSON.stringify(envelope);
+  if (event === "error") {
+    console.error(line);
+  } else {
+    console.log(line);
+  }
+  return envelope;
+};
+
+const RECORD_CONTAINER_EVENT_OP = "__lunora_admin__:recordContainerEvent";
+const ROOT_SHARD_NAME = "__root__";
+const applyJurisdiction = (namespace, jurisdiction) => {
+  if (jurisdiction === void 0) {
+    return namespace;
+  }
+  if (typeof namespace.jurisdiction !== "function") {
+    throw new TypeError(
+      `@lunora/container: Durable Object namespace does not support jurisdiction("${jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
+    );
+  }
+  return namespace.jurisdiction(jurisdiction);
+};
+const isShardNamespace = (value) => {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.get === "function" && typeof candidate.idFromName === "function";
+};
+const resolveRootShard = (namespace, jurisdiction) => {
+  const pinned = applyJurisdiction(namespace, jurisdiction);
+  if (typeof pinned.getByName === "function") {
+    return pinned.getByName(ROOT_SHARD_NAME);
+  }
+  return pinned.get(pinned.idFromName(ROOT_SHARD_NAME));
+};
+const reportContainerLifecycle = async (env, envelope, jurisdiction) => {
+  try {
+    const envRecord = env ?? {};
+    const namespace = envRecord["SHARD"];
+    if (!isShardNamespace(namespace)) {
+      return;
+    }
+    const adminBearer = typeof envRecord["LUNORA_ADMIN_TOKEN"] === "string" ? envRecord["LUNORA_ADMIN_TOKEN"] : void 0;
+    if (!adminBearer || adminBearer.length === 0) {
+      return;
+    }
+    const request = new Request("https://shard.internal/rpc", {
+      body: JSON.stringify({ args: { event: envelope }, functionPath: RECORD_CONTAINER_EVENT_OP }),
+      headers: { authorization: `Bearer ${adminBearer}`, "content-type": "application/json" },
+      method: "POST"
+    });
+    await resolveRootShard(namespace, jurisdiction).fetch(request);
+  } catch {
+  }
+};
+
+class LunoraContainer extends Container {
+  /**
+   * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
+   * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
+   * to the same region as the root shard. `undefined` ⇒ un-pinned.
+   */
+  lunoraJurisdiction;
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  lunoraName;
+  constructor(context, env, definition, exportName, jurisdiction) {
+    super(context, env, {
+      defaultPort: definition.defaultPort,
+      envVars: resolveContainerEnvVariables(definition, env, exportName),
+      sleepAfter: definition.sleepAfter
+    });
+    if (definition.enableInternet !== void 0) {
+      this.enableInternet = definition.enableInternet;
+    }
+    this.lunoraName = exportName ?? "container";
+    this.lunoraJurisdiction = jurisdiction;
+  }
+  onError(error) {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "error", error instanceof Error ? error.message : String(error));
+    this.surfaceInStudioLogs(envelope);
+    return super.onError(error);
+  }
+  async onStart() {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "start");
+    this.surfaceInStudioLogs(envelope);
+    await super.onStart();
+  }
+  async onStop(parameters) {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "stop", `${parameters.reason} (exit ${String(parameters.exitCode)})`);
+    this.surfaceInStudioLogs(envelope);
+    await super.onStop(parameters);
+  }
+  /**
+   * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+   * also appears in the Studio Logs panel (the terminal already has it via
+   * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+   * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+   * out of a lifecycle hook — the `console` path stays the source of truth.
+   */
+  surfaceInStudioLogs(envelope) {
+    reportContainerLifecycle(this.env, envelope, this.lunoraJurisdiction).catch(() => {
+    });
+  }
+  /**
+   * Per-instance correlation id: the Durable Object id, which Cloudflare also
+   * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+   * defensively — the id shape varies and isn't worth crashing a hook over.
+   */
+  instanceId() {
+    try {
+      const { id } = this.ctx;
+      return typeof id?.toString === "function" ? id.toString() : "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+}
+
+export { LunoraContainer as default };