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

package/dist/do/index.mjs

@@ -1,138 +1 @@
-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 };
+import{Container as S}from"../packem_shared/ContainerProxy-BsQAwSNX.mjs";import{ContainerProxy as A,outboundParams as L}from"../packem_shared/ContainerProxy-BsQAwSNX.mjs";import{LunoraError as u}from"@lunora/errors";import{resolveContainerEnvVars as g,parseDurationSeconds as v}from"../packem_shared/containerBindingName-DP2NqQV-.mjs";import{e as y}from"../packem_shared/jurisdiction-BKRNOTip.mjs";const w="lunora",N=(i,t,n,e)=>({container:i,event:n,instance:t,level:n==="error"?"error":"info",message:e,source:w,ts:Date.now(),type:"container"}),a=(i,t,n,e)=>{const o=N(i,t,n,e),r=JSON.stringify(o);return n==="error"?console.error(r):console.log(r),o},$="__lunora_admin__:recordContainerEvent",h="__root__",E=i=>{if(i===null||typeof i!="object")return!1;const t=i;return typeof t.get=="function"&&typeof t.idFromName=="function"},I=(i,t)=>{const n=y(i,t);return typeof n.getByName=="function"?n.getByName(h):n.get(n.idFromName(h))},T=async(i,t,n)=>{try{const e=i??{},o=e.SHARD;if(!E(o))return;const r=typeof e.LUNORA_ADMIN_TOKEN=="string"?e.LUNORA_ADMIN_TOKEN:void 0;if(!r||r.length===0)return;const s=new Request("https://shard.internal/rpc",{body:JSON.stringify({args:{event:t},functionPath:$}),headers:{authorization:`Bearer ${r}`,"content-type":"application/json"},method:"POST"});await I(o,n).fetch(s)}catch{}},l=500,p=3e4,d="__lunoraHardTimeoutGeneration";class _ extends S{lunoraJurisdiction;lunoraName;lunoraDefaultPort;lunoraHardTimeoutSeconds;lunoraReadyOn;lunoraSecretsStore;lunoraSecretsStoreResolved;constructor(t,n,e,o,r){super(t,n,{defaultPort:e.defaultPort,entrypoint:e.entrypoint?[...e.entrypoint]:void 0,envVars:g(e,n,o),sleepAfter:e.sleepAfter}),e.enableInternet!==void 0&&(this.enableInternet=e.enableInternet),e.requiredPorts!==void 0&&(this.requiredPorts=[...e.requiredPorts]),e.interceptHttps!==void 0&&(this.interceptHttps=e.interceptHttps),e.allowedHosts!==void 0&&(this.allowedHosts=[...e.allowedHosts]),e.deniedHosts!==void 0&&(this.deniedHosts=[...e.deniedHosts]),e.pingEndpoint!==void 0&&(this.pingEndpoint=e.pingEndpoint),e.labels!==void 0&&(this.labels={...e.labels}),this.lunoraName=o??"container",this.lunoraJurisdiction=r,this.lunoraDefaultPort=e.defaultPort,this.lunoraReadyOn=e.readyOn?[...e.readyOn]:[],this.lunoraHardTimeoutSeconds=e.hardTimeout===void 0?void 0:v(e.hardTimeout),this.lunoraSecretsStore=e.secretsStore}async containerFetch(...t){return await this.resolveSecretsStoreEnv(),super.containerFetch(...t)}async start(...t){const[n]=t;return n?.envVars===void 0&&await this.resolveSecretsStoreEnv(),super.start(...t)}async onActivityExpired(){const t=a(this.lunoraName,this.instanceId(),"sleep");this.surfaceInStudioLogs(t),await super.onActivityExpired()}onError(t){const n=a(this.lunoraName,this.instanceId(),"error",t instanceof Error?t.message:String(t));return this.surfaceInStudioLogs(n),super.onError(t)}async onStart(){const t=a(this.lunoraName,this.instanceId(),"start");this.surfaceInStudioLogs(t),await super.onStart(),await this.armHardTimeout(),await this.awaitContainerReadiness()}async onHardTimeoutExpired(t){const n=await this.ctx.storage.get(d);if(t?.generation!==void 0&&t.generation!==n||this.ctx.container?.running!==!0)return;const e=a(this.lunoraName,this.instanceId(),"stop","hard timeout reached");this.surfaceInStudioLogs(e),await this.stop()}async onStop(t){const n=a(this.lunoraName,this.instanceId(),"stop",`${t.reason} (exit ${String(t.exitCode)})`);this.surfaceInStudioLogs(n),await super.onStop(t)}async armHardTimeout(){if(this.lunoraHardTimeoutSeconds===void 0)return;const t=(await this.ctx.storage.get(d)??0)+1;await this.ctx.storage.put(d,t),await this.schedule(this.lunoraHardTimeoutSeconds,"onHardTimeoutExpired",{generation:t})}async resolveSecretsStoreEnv(){const t=this.lunoraSecretsStore;t!==void 0&&(this.lunoraSecretsStoreResolved??=(async()=>{const n=this.env,e={};for(const[o,r]of Object.entries(t)){const s=n[r];if(s===void 0||typeof s.get!="function")throw new u("INTERNAL",`container "${this.lunoraName}": secretsStore env "${o}" points at binding "${r}", which is not a Secrets Store binding on the Worker env. Add a \`secrets_store_secrets\` entry binding "${r}".`);const c=await s.get();if(typeof c!="string")throw new TypeError(`container "${this.lunoraName}": Secrets Store binding "${r}" (env "${o}") did not resolve to a string value.`);e[o]=c}this.envVars={...this.envVars,...e}})().catch(n=>{throw this.lunoraSecretsStoreResolved=void 0,n}),await this.lunoraSecretsStoreResolved)}async awaitContainerReadiness(){if(this.lunoraReadyOn.length===0)return;const{container:t}=this.ctx;if(t===void 0)return;const n=Date.now()+p;await Promise.all(this.lunoraReadyOn.map(async e=>this.awaitReadinessCheck(t,e,n)))}async awaitReadinessCheck(t,n,e){const o=n.port??this.lunoraDefaultPort;if(o===void 0)throw new u("INTERNAL",`container "${this.lunoraName}": readyOn check "${n.path}" has no port — set the check's \`port\` or the container \`defaultPort\`.`);const r=n.status??200,s=n.path.startsWith("/")?n.path:`/${n.path}`,c=t.getTcpPort(o);for(;;){const f=Math.max(l,e-Date.now());try{if((await c.fetch(`http://container${s}`,{signal:AbortSignal.timeout(f)})).status===r)return}catch{}if(Date.now()>=e)throw new u("INTERNAL",`container "${this.lunoraName}": readiness check "${n.path}" (port ${String(o)}) did not return ${String(r)} within ${String(p)}ms`);await new Promise(m=>{setTimeout(m,l)})}}surfaceInStudioLogs(t){T(this.env,t,this.lunoraJurisdiction).catch(()=>{})}instanceId(){try{const{id:t}=this.ctx;return typeof t?.toString=="function"?t.toString():"unknown"}catch{return"unknown"}}}export{A as ContainerProxy,_ as LunoraContainer,L as outboundParams};

package/dist/index.d.mts

@@ -1,15 +1,9 @@
-import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-D2l2SYol.mjs";
-export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerRollout, e as CustomContainerInstanceType, f as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/types.d-D2l2SYol.mjs";
-/**
-* The `ctx.containers` action surface: typed handles over the `CONTAINER_*`
-* Durable Object namespace bindings the config layer reconciles.
-*
-* Deliberately structural (no `@cloudflare/containers` import): a Durable
-* Object namespace stub is all that is needed to route a request to a
-* container-enabled DO, so this module stays Node-safe and the test double
-* below can satisfy the exact same shape without a workerd runtime.
-*/
-/** Options for explicitly starting an instance (mirrors `@cloudflare/containers`). */
+import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-8oUUvrew.mjs";
+export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-8oUUvrew.mjs";
+/**
+ * Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
+ * @experimental
+ */
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
   enableInternet?: boolean;
@@ -20,108 +14,215 @@ interface ContainerStartOptions {
   /** Metadata labels attached for metrics/observability. */
   labels?: Record<string, string>;
 }
-/** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
+/**
+ * A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
+ * @experimental
+ */
 interface ContainerInstanceState {
   [key: string]: unknown;
+  /** Process exit code, present once the instance has `stopped_with_code`. */
+  exitCode?: number;
+  /** Epoch-ms of the last state transition. */
   lastChange?: number;
+  /** Lifecycle status. Widening union — Cloudflare adds values over time. */
+  status?: "healthy" | "running" | "stopped" | "stopped_with_code" | "stopping";
 }
-/** What a handle needs from a Durable Object stub — `fetch` plus the optional lifecycle RPCs the container DO exposes. */
+/** What a handle needs from a Durable Object stub — `fetch` plus the optional lifecycle/egress RPCs the container DO exposes. */
 interface ContainerStubLike {
+  allowHost?: (hostname: string) => Promise<void>;
+  denyHost?: (hostname: string) => Promise<void>;
   destroy?: () => Promise<void>;
   fetch: (input: Request) => Promise<Response>;
   getState?: () => Promise<ContainerInstanceState>;
+  removeAllowedHost?: (hostname: string) => Promise<void>;
+  removeDeniedHost?: (hostname: string) => Promise<void>;
+  renewActivityTimeout?: () => Promise<void>;
+  setAllowedHosts?: (hosts: string[]) => Promise<void>;
+  setDeniedHosts?: (hosts: string[]) => Promise<void>;
   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. */
+ * What the client needs from a Durable Object namespace binding.
+ * @experimental
+ */
 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.
-  */
+   * 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). */
+/**
+ * A handle on one container instance (one Durable Object).
+ * @experimental
+ */
 interface ContainerHandle {
   /**
-  * Send an HTTP (or WebSocket-upgrade) request to the container. A path
-  * string (`"/transcode"`) is resolved against a synthetic origin; a full
-  * `Request`/URL passes through unchanged.
-  */
+   * Send an HTTP (or WebSocket-upgrade) request to the container. A path
+   * string (`"/transcode"`) is resolved against a synthetic origin; a full
+   * `Request`/URL passes through unchanged.
+   */
   fetch: (input: Request | string, init?: RequestInit) => Promise<Response>;
+  /**
+   * Return a handle that routes every request to `targetPort` on the
+   * container instead of the definition's `defaultPort` — for multi-port
+   * containers (declare the ports in `requiredPorts`). Sets the
+   * `cf-container-target-port` header the way `@cloudflare/containers`'
+   * `switchPort` does, so it composes with `.get()`, `.any()`, and `.pool()`:
+   * `ctx.containers.app.get("u1").port(9090).fetch("/admin")`.
+   */
+  port: (targetPort: number) => ContainerHandle;
 }
 /**
-* A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
-* lifecycle control. The per-entity pattern (a sandbox per user, a room per
-* game, a job runner per id) often needs to tear down or inspect the instance
-* rather than wait for `sleepAfter`, so these wrap the container DO's
-* `start`/`stop`/`destroy`/`getState`.
-*/
+ * A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
+ * lifecycle control. The per-entity pattern (a sandbox per user, a room per
+ * game, a job runner per id) often needs to tear down or inspect the instance
+ * rather than wait for `sleepAfter`, so these wrap the container DO's
+ * `start`/`stop`/`destroy`/`getState`.
+ * @experimental
+ */
 interface ContainerInstanceHandle extends ContainerHandle {
   /** Stop and discard the instance (its ephemeral disk is lost). */
   destroy: () => Promise<void>;
+  /**
+   * Adjust this instance's egress allow/deny lists at runtime — the dynamic
+   * counterpart to the static `allowedHosts`/`deniedHosts` config. Useful for
+   * per-tenant egress policy. Requires the worker to export `ContainerProxy`
+   * (codegen re-exports it from the generated container file whenever any
+   * container is defined, so the runtime controls always work).
+   */
+  egress: ContainerEgressControls;
   /** Read the instance's current runtime state. */
   getState: () => Promise<ContainerInstanceState>;
+  /**
+   * Reset the instance's `sleepAfter` idle timer. The platform renews it on
+   * each proxied request, and because `@lunora/container` proxies WebSocket
+   * frames through the Durable Object, message traffic on an open socket
+   * renews it too (the WebSocket-keepalive gap of cloudflare/containers#147 is
+   * closed in the bundled base). This manual control is the escape hatch for
+   * keeping a container awake during activity that is neither an HTTP request
+   * nor a WS message — e.g. a long out-of-band job running inside it.
+   */
+  renewActivityTimeout: () => Promise<void>;
   /** Explicitly start the instance, optionally with per-instance env/entrypoint. */
   start: (options?: ContainerStartOptions) => Promise<void>;
   /** Stop the instance (optionally with a signal); it can start again on the next request. */
   stop: (signal?: number | string) => Promise<void>;
 }
-/** The per-definition accessor exposed as `ctx.containers.&lt;exportName>`. */
+/**
+ * Runtime egress-firewall controls for a named instance (`handle.egress.*`).
+ * Each maps to the corresponding `@cloudflare/containers` `Container` RPC, so
+ * an app can tighten or relax a single instance's allowed/denied hosts after
+ * start without redeploying.
+ * @experimental
+ */
+interface ContainerEgressControls {
+  /** Add one hostname (or glob) to the allow-list. */
+  allow: (hostname: string) => Promise<void>;
+  /** Add one hostname (or glob) to the deny-list. */
+  deny: (hostname: string) => Promise<void>;
+  /** Remove one hostname from the allow-list. */
+  removeAllowed: (hostname: string) => Promise<void>;
+  /** Remove one hostname from the deny-list. */
+  removeDenied: (hostname: string) => Promise<void>;
+  /** Replace the entire allow-list. */
+  setAllowed: (hosts: ReadonlyArray<string>) => Promise<void>;
+  /** Replace the entire deny-list. */
+  setDenied: (hosts: ReadonlyArray<string>) => Promise<void>;
+}
+/**
+ * The per-definition accessor exposed as `ctx.containers.&lt;exportName>`.
+ * @experimental
+ */
 interface ContainerAccessor {
   /**
-  * A random instance from a fixed pool of `count` (defaults to the
-  * definition's `maxInstances`, else 3 — mirroring `getRandom` from
-  * `@cloudflare/containers`). For stateless, interchangeable workloads.
-  */
-  any: (count?: number) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+   * A random instance from a fixed pool of `count` (defaults to the
+   * definition's `maxInstances`, else 3 — mirroring `getRandom` from
+   * `@cloudflare/containers`). For stateless, interchangeable workloads.
+   *
+   * Like `.get()`, a path/URL-string fetch transparently retries the
+   * cold-start "instance is provisioning" transients (cloudflare/containers#45,
+   * #139); pass {@link InstanceRetryOptions} to tune or disable it.
+   */
+  any: (count?: number, options?: InstanceRetryOptions) => ContainerHandle;
   /**
-  * A resilient handle over the pool: each `fetch` picks a random instance and,
-  * on a thrown error or a retryable response (5xx by default), retries on a
-  * freshly-picked instance with exponential backoff. Until Cloudflare ships
-  * native autoscaling + health-aware routing this is the recommended way to
-  * call a stateless container pool — it rides over a single cold/unhealthy
-  * instance instead of failing the whole request.
-  *
-  * Because a retry re-issues the request, pass a **replayable** body — a path
-  * string plus an `init.body` string/`ArrayBuffer` (re-created each attempt).
-  * A pre-built `Request` carrying a stream body can only be sent once, so it
-  * is not retry-safe here; use `.get()`/`.any()` for those.
-  */
+   * The instance for `name` — one container per entity (user, room, job…),
+   * with lifecycle control.
+   *
+   * A path/URL-string fetch transparently retries the platform's cold-start
+   * transients — "there is no Container instance available" / "container is
+   * not listening" while an instance is still provisioning
+   * (cloudflare/containers#45, #139) — on the *same* instance with backoff,
+   * since the request never reached the app. Pass {@link InstanceRetryOptions}
+   * to tune attempts/backoff or disable it (`{ attempts: 1 }`). A pre-built
+   * `Request` (possibly a one-shot stream body) is sent once, never retried.
+   */
+  get: (name: string, options?: InstanceRetryOptions) => ContainerInstanceHandle;
+  /**
+   * A resilient handle over the pool: each `fetch` picks a random instance and,
+   * on a thrown error or a retryable response (5xx by default), retries on a
+   * freshly-picked instance with exponential backoff. Until Cloudflare ships
+   * native autoscaling + health-aware routing this is the recommended way to
+   * call a stateless container pool — it rides over a single cold/unhealthy
+   * instance instead of failing the whole request.
+   *
+   * Because a retry re-issues the request, pass a **replayable** body — a path
+   * string plus an `init.body` string/`ArrayBuffer` (re-created each attempt).
+   * A pre-built `Request` carrying a stream body can only be sent once, so it
+   * is not retry-safe here; use `.get()`/`.any()` for those.
+   */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
-/** Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}. */
+/**
+ * Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}.
+ * @experimental
+ */
 interface PoolOptions {
   /** Total attempts before giving up (each on a freshly-picked instance). Default 3. */
   attempts?: number;
   /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default 100. */
   backoffMs?: number;
   /**
-  * Upper bound on a single backoff sleep, in ms. The doubling delay is clamped
-  * to this ceiling so a large `attempts` count can't produce an unboundedly
-  * long wait. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s).
-  */
+   * Upper bound on a single backoff sleep, in ms. The doubling delay is clamped
+   * to this ceiling so a large `attempts` count can't produce an unboundedly
+   * long wait. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s).
+   */
   maxBackoffMs?: number;
   /**
-  * Whether a *returned* response should be retried on another instance.
-  * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
-  * always retried regardless of this predicate.
-  */
+   * Whether a *returned* response should be retried on another instance.
+   * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
+   * always retried regardless of this predicate.
+   */
   retryOn?: (response: Response) => boolean;
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
   size?: number;
 }
-/** Wiring info for one definition, emitted by codegen into the generated DO. */
+/**
+ * Tuning for the cold-start retry on a `.get()`/`.any()` handle. The retry fires
+ * only on the platform's provisioning transients (no-instance / not-listening /
+ * rate-limited — see {@link isColdStartTransient}), which is why it's safe by
+ * default: those responses mean the request never reached the container.
+ * @experimental
+ */
+interface InstanceRetryOptions {
+  /**
+   * Total attempts on a cold-start transient before the last outcome is
+   * surfaced as-is. `1` disables the retry. Default
+   * {@link DEFAULT_COLD_START_ATTEMPTS}.
+   */
+  attempts?: number;
+  /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default {@link DEFAULT_COLD_START_BACKOFF_MS}. */
+  backoffMs?: number;
+  /** Upper bound on a single backoff sleep, in ms. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s). */
+  maxBackoffMs?: number;
+}
+/**
+ * Wiring info for one definition, emitted by codegen into the generated DO.
+ * @experimental
+ */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
   binding: string;
@@ -131,70 +232,90 @@ interface ContainerBindingSpec {
   maxInstances?: number;
 }
 /**
-* Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
-*/
-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. */
+ * Build the `ctx.containers` record from the Worker `env`. Called by the
+ * generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+ * A missing binding doesn't throw here — only when the handle is actually used —
+ * so one unprovisioned container never breaks unrelated functions.
+ *
+ * `traceparent` (the inbound RPC's W3C trace context, forwarded by the runtime
+ * and read off the request by the DO) is stamped onto every outbound container
+ * `fetch`, so the container's own spans stitch under the Worker's trace.
+ * @experimental
+ */
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string) => Record<string, ContainerAccessor>;
+/**
+ * A test handler: receives the request plus the targeted instance name.
+ * @experimental
+ */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
 }) => Promise<Response> | Response;
 /**
-* Docker-free test double for `ctx.containers`: each export name maps to a
-* fetch handler that plays the container. Mirrors the real shape exactly, so
-* action handlers under test can't tell the difference.
-*
-* ```ts
-* const containers = createContainerTestContext({
-*     transcoder: (request) => new Response("ok"),
-* });
-* ```
-*/
+ * Docker-free test double for `ctx.containers`: each export name maps to a
+ * fetch handler that plays the container. Mirrors the real shape exactly, so
+ * action handlers under test can't tell the difference.
+ *
+ * ```ts
+ * const containers = createContainerTestContext({
+ *     transcoder: (request) => new Response("ok"),
+ * });
+ * ```
+ * @experimental
+ */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
 /**
-* Normalize a `ContainerImageSource` into the shape wrangler wants: a
-* Dockerfile path + build context for local builds, or a fully-qualified
-* reference for pre-built images.
-*
-* A local-path string whose basename starts with `Dockerfile` (so
-* `Dockerfile.dev` also counts) is used as-is with its directory as the build
-* context; any other path is treated as the build-context directory and the
-* Dockerfile is expected at `&lt;dir>/Dockerfile`.
-*/
+ * Normalize a `ContainerImageSource` into the shape wrangler wants: a
+ * Dockerfile path + build context for local builds, or a fully-qualified
+ * reference for pre-built images.
+ *
+ * A local-path string whose basename starts with `Dockerfile` (so
+ * `Dockerfile.dev` also counts) is used as-is with its directory as the build
+ * context; any other path is treated as the build-context directory and the
+ * Dockerfile is expected at `&lt;dir>/Dockerfile`.
+ * @experimental
+ */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
-* The generated Container DO class name for a `lunora/containers.ts` export:
-* `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
-* and the Durable Object binding's `class_name` both reference it, so codegen
-* and the config layer MUST derive it identically — always via this helper.
-*/
+ * The generated Container DO class name for a `lunora/containers.ts` export:
+ * `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
+ * and the Durable Object binding's `class_name` both reference it, so codegen
+ * and the config layer MUST derive it identically — always via this helper.
+ * @experimental
+ */
 declare const containerClassName: (exportName: string) => string;
 /**
-* The Durable Object binding name for a container export: `transcoder` →
-* `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
-* `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
-* so a container export can never collide with the built-in bindings.
-*/
+ * The Durable Object binding name for a container export: `transcoder` →
+ * `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
+ * `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
+ * so a container export can never collide with the built-in bindings.
+ * @experimental
+ */
 declare const containerBindingName: (exportName: string) => string;
 /**
-* The local image tag a Railpack `{ build }` container is built and pushed
-* under: `transcoder` → `lunora-transcoder:build`. The config reconciler writes
-* it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
-* with Railpack and `wrangler containers push`es it before deploying — so all
-* three derive the tag from this one helper and can never disagree.
-*/
+ * The local image tag a Railpack `{ build }` container is built and pushed
+ * under: `transcoder` → `lunora-transcoder:build`. The config reconciler writes
+ * it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
+ * with Railpack and `wrangler containers push`es it before deploying — so all
+ * three derive the tag from this one helper and can never disagree.
+ * @experimental
+ */
 declare const containerBuildTag: (exportName: string) => string;
+/**
+ * `defineContainer` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ * @experimental
+ */
 declare const defineContainer: (config: ContainerConfig) => ContainerDefinition;
-/** True when a value is a `defineContainer` result (the runtime brand check). */
+/**
+ * True when a value is a `defineContainer` result (the runtime brand check).
+ * @experimental
+ */
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
-* The container's full environment at instance start: the static `env` block
-* plus every declared secret resolved from the Worker `env`. A declared secret
-* missing from the Worker env fails fast — starting the container without a
-* credential it was promised yields far worse errors downstream.
-*/
+ * The container's full environment at instance start: the static `env` block
+ * plus every declared secret resolved from the Worker `env`. A declared secret
+ * missing from the Worker env fails fast — starting the container without a
+ * credential it was promised yields far worse errors downstream.
+ * @experimental
+ */
 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 DurableObjectJurisdiction, 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 ContainerEgressControls, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type InstanceRetryOptions, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };