@lunora/container 0.0.0 → 1.0.0-alpha.10

package/dist/bridge.d.mts

@@ -0,0 +1,90 @@
+import { LunoraError } from '@lunora/errors';
+/** 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. 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.
+*/
+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 @@
+import { LunoraError } from '@lunora/errors';
+/** 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. 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.
+*/
+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,79 @@
+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 };