@lunora/container 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/do/index.d.mts

@@ -1,5 +1,19 @@
 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
@@ -19,9 +33,15 @@ type DurableObjectContext = ConstructorParameters<typeof Container>[0];
 * ```
 */
 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);
+  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>;

package/dist/do/index.d.ts

@@ -1,5 +1,19 @@
 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
@@ -19,9 +33,15 @@ type DurableObjectContext = ConstructorParameters<typeof Container>[0];
 * ```
 */
 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);
+  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>;

package/dist/do/index.mjs

@@ -27,6 +27,17 @@ const emitContainerLifecycle = (container, instance, event, message) => {
 
 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;
@@ -34,13 +45,14 @@ const isShardNamespace = (value) => {
   const candidate = value;
   return typeof candidate.get === "function" && typeof candidate.idFromName === "function";
 };
-const resolveRootShard = (namespace) => {
-  if (typeof namespace.getByName === "function") {
-    return namespace.getByName(ROOT_SHARD_NAME);
+const resolveRootShard = (namespace, jurisdiction) => {
+  const pinned = applyJurisdiction(namespace, jurisdiction);
+  if (typeof pinned.getByName === "function") {
+    return pinned.getByName(ROOT_SHARD_NAME);
   }
-  return namespace.get(namespace.idFromName(ROOT_SHARD_NAME));
+  return pinned.get(pinned.idFromName(ROOT_SHARD_NAME));
 };
-const reportContainerLifecycle = async (env, envelope) => {
+const reportContainerLifecycle = async (env, envelope, jurisdiction) => {
   try {
     const envRecord = env ?? {};
     const namespace = envRecord["SHARD"];
@@ -56,15 +68,21 @@ const reportContainerLifecycle = async (env, envelope) => {
       headers: { authorization: `Bearer ${adminBearer}`, "content-type": "application/json" },
       method: "POST"
     });
-    await resolveRootShard(namespace).fetch(request);
+    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) {
+  constructor(context, env, definition, exportName, jurisdiction) {
     super(context, env, {
       defaultPort: definition.defaultPort,
       envVars: resolveContainerEnvVariables(definition, env, exportName),
@@ -74,6 +92,7 @@ class LunoraContainer extends Container {
       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));
@@ -98,7 +117,7 @@ class LunoraContainer extends Container {
    * out of a lifecycle hook — the `console` path stays the source of truth.
    */
   surfaceInStudioLogs(envelope) {
-    reportContainerLifecycle(this.env, envelope).catch(() => {
+    reportContainerLifecycle(this.env, envelope, this.lunoraJurisdiction).catch(() => {
     });
   }
   /**

package/dist/index.d.mts

@@ -33,10 +33,21 @@ interface ContainerStubLike {
   start?: (options?: ContainerStartOptions) => Promise<void>;
   stop?: (signal?: number | string) => Promise<void>;
 }
+/**
+* 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";
 /** What the client needs from a Durable Object namespace binding. */
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
 /** A handle on one container instance (one Durable Object). */
 interface ContainerHandle {
@@ -126,7 +137,7 @@ interface ContainerBindingSpec {
 * handle is actually used — so one unprovisioned container never breaks
 * unrelated functions.
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>) => Record<string, ContainerAccessor>;
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
 /** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
@@ -186,4 +197,4 @@ declare const isContainerDefinition: (value: unknown) => value is ContainerDefin
 * credential it was promised yields far worse errors downstream.
 */
 declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
-export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/index.d.ts

@@ -33,10 +33,21 @@ interface ContainerStubLike {
   start?: (options?: ContainerStartOptions) => Promise<void>;
   stop?: (signal?: number | string) => Promise<void>;
 }
+/**
+* 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";
 /** What the client needs from a Durable Object namespace binding. */
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
 /** A handle on one container instance (one Durable Object). */
 interface ContainerHandle {
@@ -126,7 +137,7 @@ interface ContainerBindingSpec {
 * handle is actually used — so one unprovisioned container never breaks
 * unrelated functions.
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>) => Record<string, ContainerAccessor>;
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
 /** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
@@ -186,4 +197,4 @@ declare const isContainerDefinition: (value: unknown) => value is ContainerDefin
 * credential it was promised yields far worse errors downstream.
 */
 declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
-export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-ChDD53ys.mjs';
+export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-CTpyUQ4J.mjs';
 export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BGdSdFNA.mjs';

package/dist/packem_shared/{createContainerContext-ChDD53ys.mjs → createContainerContext-CTpyUQ4J.mjs}

@@ -1,3 +1,14 @@
+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 DEFAULT_POOL_SIZE = 3;
 const DEFAULT_MAX_BACKOFF_MS = 3e4;
 const toRequest = (input, init) => {
@@ -83,11 +94,11 @@ const missingBindingAccessor = (spec) => {
   };
   return { any: fail, get: fail, pool: fail };
 };
-const createContainerContext = (env, specs) => {
+const createContainerContext = (env, specs, jurisdiction) => {
   const containers = {};
   for (const spec of specs) {
-    const namespace = env[spec.binding];
-    containers[spec.exportName] = namespace && typeof namespace.idFromName === "function" && typeof namespace.get === "function" ? accessorFor(namespace, spec) : missingBindingAccessor(spec);
+    const binding = env[spec.binding];
+    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec) : missingBindingAccessor(spec);
   }
   return containers;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",