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

package/README.md

@@ -66,6 +66,7 @@ export const transcoder = defineContainer({
     maxInstances: 5,
     sleepAfter: "5m",
     secrets: ["TRANSCODER_API_KEY"], // forwarded from Worker secrets / .dev.vars
+    labels: { team: "media" }, // metadata attached to every instance for metrics/observability
 });
 ```
 
@@ -89,10 +90,81 @@ 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.
+`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).
 
 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.
 
+### Multi-port containers
+
+Declare every port the container must be listening on with `requiredPorts` (start-up waits for all of them); `defaultPort` is the target when a request doesn't pick one. Route a single request to another port with `.port(n)` — it composes with `.get()`, `.any()`, and `.pool()`:
+
+```ts
+export const app = defineContainer({
+    image: "./containers/app",
+    defaultPort: 8080,
+    requiredPorts: [8080, 9090], // app + admin
+});
+
+// in an action:
+await ctx.containers.app.get(tenantId).fetch("/work"); // → 8080
+await ctx.containers.app.get(tenantId).port(9090).fetch("/admin"); // → 9090
+```
+
+### Build-time args
+
+`env` and `secrets` are runtime values; for build-time `docker build --build-arg` values (wrangler `image_vars`, exposed to the Dockerfile as `ARG`) use `buildArgs`. They apply only to an image Lunora builds and are ignored for a pre-built `{ registry }` image.
+
+```ts
+export const worker = defineContainer({
+    image: "./containers/worker",
+    buildArgs: { NODE_VERSION: "22", BUILD_TARGET: "production" },
+});
+```
+
+### 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.
+
+```ts
+export const fetcher = defineContainer({
+    image: "./containers/fetcher",
+    enableInternet: false,
+    allowedHosts: ["*.stripe.com", "api.github.com"],
+    deniedHosts: ["*.evil.com"],
+});
+
+// tighten or relax one running instance at runtime:
+await ctx.containers.fetcher.get(tenantId).egress.allow("hooks.slack.com");
+```
+
+For advanced egress rewriting in worker code, `@lunora/container/do` re-exports Cloudflare's custom outbound-handler types (`OutboundHandler`, `OutboundHandlers`, `outboundParams`) — wire them onto a hand-authored `LunoraContainer` subclass to inject auth, route, or mock a container's outbound calls.
+
+### Readiness gating
+
+The platform health check waits for an open port, not necessarily a _ready_ app. `readyOn` adds application-level probes that gate request proxying: a `ctx.containers.<name>` fetch holds until every probe responds with its expected status, so callers never hit a container still applying migrations or warming caches. Probes are declarative data (path + optional `port`/`status`), run in parallel at start, and probe the container's TCP port directly.
+
+```ts
+export const api = defineContainer({
+    image: "./containers/api",
+    defaultPort: 8080,
+    readyOn: [
+        { path: "/ready" }, // expect 200 on defaultPort
+        { path: "/live", port: 9090, status: 204 }, // own port + expected status
+    ],
+});
+```
+
+### Hard timeout
+
+`sleepAfter` caps _idle_ time; `hardTimeout` caps _total_ lifetime — a runaway-cost backstop measured from start, regardless of activity (same grammar as `sleepAfter`). When it elapses the generated class's `onHardTimeoutExpired` hook runs (default: `stop()`); the timer is run-generation-stamped so a stale timer from a slept/crashed run can't kill a fresh one.
+
+```ts
+export const job = defineContainer({
+    image: "./containers/job",
+    hardTimeout: "1h", // never run longer than an hour, busy or not
+});
+```
+
 ### Calling Lunora from inside a container
 
 Container code calls back into your app's functions with the bridge client (any JS runtime), over the Worker's HTTP RPC endpoint:

package/dist/do/index.d.mts

@@ -1,5 +1,6 @@
 import { Container, StopParams } from '@cloudflare/containers';
-import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.mjs";
+export { ContainerProxy, type OutboundHandler, type OutboundHandlerContext, type OutboundHandlerParams, type OutboundHandlerParamsOf, type OutboundHandlers, outboundParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-DAOLRiZQ.mjs";
 /**
 * Cloudflare Durable Object data-residency jurisdiction. Widening union —
 * Cloudflare adds values over time.
@@ -41,11 +42,44 @@ declare class LunoraContainer<Env = unknown> extends Container<Env> {
   private readonly lunoraJurisdiction?;
   /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
   private readonly lunoraName;
+  /** Default port the readiness probes target when a check omits its own `port`. */
+  private readonly lunoraDefaultPort?;
+  /** Hard-cap lifetime in whole seconds (from the `hardTimeout` config), or `undefined`. */
+  private readonly lunoraHardTimeoutSeconds?;
+  /** Declarative readiness probes that gate request proxying (from the `readyOn` config). */
+  private readonly lunoraReadyOn;
   constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
+  override onActivityExpired(): Promise<void>;
   override onError(error: unknown): unknown;
   override onStart(): Promise<void>;
+  /**
+  * Hook run when the container's `hardTimeout` elapses (dispatched by the base
+  * scheduler via the run-generation-stamped schedule armed in
+  * {@link onStart}). Default: stop the instance. Override to drain/checkpoint
+  * first. A stale schedule from a previous run, or an already-stopped
+  * instance, is ignored (upstream cloudflare/containers#85).
+  */
+  onHardTimeoutExpired(payload?: {
+    generation?: number;
+  }): Promise<void>;
   override onStop(parameters: StopParams): Promise<void>;
   /**
+  * Arm the hard-timeout kill via the base scheduler (so it integrates with
+  * the container's own alarm machinery instead of fighting it). Bumps the run
+  * generation and stamps the schedule with it, so {@link onHardTimeoutExpired}
+  * can tell a fresh schedule from a stale one. No-op without a `hardTimeout`.
+  */
+  private armHardTimeout;
+  /**
+  * Block until every `readyOn` probe responds with its expected status, or
+  * throw once the readiness budget is spent. Probes run in parallel and hit
+  * the container's TCP port directly (NOT `containerFetch`, which would
+  * recurse back into the start path). No-op without `readyOn`.
+  */
+  private awaitContainerReadiness;
+  /** Poll one readiness probe until it returns its expected status or the shared deadline passes. */
+  private awaitReadinessCheck;
+  /**
   * 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
@@ -60,4 +94,4 @@ declare class LunoraContainer<Env = unknown> extends Container<Env> {
   */
   private instanceId;
 }
-export { LunoraContainer as default };
+export { LunoraContainer };

package/dist/do/index.d.ts

@@ -1,5 +1,6 @@
 import { Container, StopParams } from '@cloudflare/containers';
-import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.js";
+export { ContainerProxy, type OutboundHandler, type OutboundHandlerContext, type OutboundHandlerParams, type OutboundHandlerParamsOf, type OutboundHandlers, outboundParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-DAOLRiZQ.js";
 /**
 * Cloudflare Durable Object data-residency jurisdiction. Widening union —
 * Cloudflare adds values over time.
@@ -41,11 +42,44 @@ declare class LunoraContainer<Env = unknown> extends Container<Env> {
   private readonly lunoraJurisdiction?;
   /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
   private readonly lunoraName;
+  /** Default port the readiness probes target when a check omits its own `port`. */
+  private readonly lunoraDefaultPort?;
+  /** Hard-cap lifetime in whole seconds (from the `hardTimeout` config), or `undefined`. */
+  private readonly lunoraHardTimeoutSeconds?;
+  /** Declarative readiness probes that gate request proxying (from the `readyOn` config). */
+  private readonly lunoraReadyOn;
   constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
+  override onActivityExpired(): Promise<void>;
   override onError(error: unknown): unknown;
   override onStart(): Promise<void>;
+  /**
+  * Hook run when the container's `hardTimeout` elapses (dispatched by the base
+  * scheduler via the run-generation-stamped schedule armed in
+  * {@link onStart}). Default: stop the instance. Override to drain/checkpoint
+  * first. A stale schedule from a previous run, or an already-stopped
+  * instance, is ignored (upstream cloudflare/containers#85).
+  */
+  onHardTimeoutExpired(payload?: {
+    generation?: number;
+  }): Promise<void>;
   override onStop(parameters: StopParams): Promise<void>;
   /**
+  * Arm the hard-timeout kill via the base scheduler (so it integrates with
+  * the container's own alarm machinery instead of fighting it). Bumps the run
+  * generation and stamps the schedule with it, so {@link onHardTimeoutExpired}
+  * can tell a fresh schedule from a stale one. No-op without a `hardTimeout`.
+  */
+  private armHardTimeout;
+  /**
+  * Block until every `readyOn` probe responds with its expected status, or
+  * throw once the readiness budget is spent. Probes run in parallel and hit
+  * the container's TCP port directly (NOT `containerFetch`, which would
+  * recurse back into the start path). No-op without `readyOn`.
+  */
+  private awaitContainerReadiness;
+  /** Poll one readiness probe until it returns its expected status or the shared deadline passes. */
+  private awaitReadinessCheck;
+  /**
   * 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
@@ -60,4 +94,4 @@ declare class LunoraContainer<Env = unknown> extends Container<Env> {
   */
   private instanceId;
 }
-export { LunoraContainer as default };
+export { LunoraContainer };

package/dist/do/index.mjs

@@ -1,5 +1,6 @@
 import { Container } from '@cloudflare/containers';
-import { resolveContainerEnvVars as resolveContainerEnvVariables } from '../packem_shared/containerBindingName-BGdSdFNA.mjs';
+export { ContainerProxy, outboundParams } from '@cloudflare/containers';
+import { resolveContainerEnvVars as resolveContainerEnvVariables, parseDurationSeconds } from '../packem_shared/containerBindingName-C7Lic2ET.mjs';
 
 const LUNORA_EVENT_SOURCE = "lunora";
 const buildContainerLifecycleEvent = (container, instance, event, message) => {
@@ -73,6 +74,9 @@ const reportContainerLifecycle = async (env, envelope, jurisdiction) => {
   }
 };
 
+const READINESS_POLL_INTERVAL_MS = 500;
+const READINESS_TIMEOUT_MS = 3e4;
+const HARD_TIMEOUT_GENERATION_KEY = "__lunoraHardTimeoutGeneration";
 class LunoraContainer extends Container {
   /**
    * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
@@ -82,17 +86,50 @@ class LunoraContainer extends Container {
   lunoraJurisdiction;
   /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
   lunoraName;
+  /** Default port the readiness probes target when a check omits its own `port`. */
+  lunoraDefaultPort;
+  /** Hard-cap lifetime in whole seconds (from the `hardTimeout` config), or `undefined`. */
+  lunoraHardTimeoutSeconds;
+  /** Declarative readiness probes that gate request proxying (from the `readyOn` config). */
+  lunoraReadyOn;
   constructor(context, env, definition, exportName, jurisdiction) {
     super(context, env, {
       defaultPort: definition.defaultPort,
+      entrypoint: definition.entrypoint ? [...definition.entrypoint] : void 0,
       envVars: resolveContainerEnvVariables(definition, env, exportName),
       sleepAfter: definition.sleepAfter
     });
     if (definition.enableInternet !== void 0) {
       this.enableInternet = definition.enableInternet;
     }
+    if (definition.requiredPorts !== void 0) {
+      this.requiredPorts = [...definition.requiredPorts];
+    }
+    if (definition.interceptHttps !== void 0) {
+      this.interceptHttps = definition.interceptHttps;
+    }
+    if (definition.allowedHosts !== void 0) {
+      this.allowedHosts = [...definition.allowedHosts];
+    }
+    if (definition.deniedHosts !== void 0) {
+      this.deniedHosts = [...definition.deniedHosts];
+    }
+    if (definition.pingEndpoint !== void 0) {
+      this.pingEndpoint = definition.pingEndpoint;
+    }
+    if (definition.labels !== void 0) {
+      this.labels = { ...definition.labels };
+    }
     this.lunoraName = exportName ?? "container";
     this.lunoraJurisdiction = jurisdiction;
+    this.lunoraDefaultPort = definition.defaultPort;
+    this.lunoraReadyOn = definition.readyOn ? [...definition.readyOn] : [];
+    this.lunoraHardTimeoutSeconds = definition.hardTimeout === void 0 ? void 0 : parseDurationSeconds(definition.hardTimeout);
+  }
+  async onActivityExpired() {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "sleep");
+    this.surfaceInStudioLogs(envelope);
+    await super.onActivityExpired();
   }
   onError(error) {
     const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "error", error instanceof Error ? error.message : String(error));
@@ -103,12 +140,93 @@ class LunoraContainer extends Container {
     const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "start");
     this.surfaceInStudioLogs(envelope);
     await super.onStart();
+    await this.armHardTimeout();
+    await this.awaitContainerReadiness();
+  }
+  /**
+   * Hook run when the container's `hardTimeout` elapses (dispatched by the base
+   * scheduler via the run-generation-stamped schedule armed in
+   * {@link onStart}). Default: stop the instance. Override to drain/checkpoint
+   * first. A stale schedule from a previous run, or an already-stopped
+   * instance, is ignored (upstream cloudflare/containers#85).
+   */
+  async onHardTimeoutExpired(payload) {
+    const current = await this.ctx.storage.get(HARD_TIMEOUT_GENERATION_KEY);
+    if (payload?.generation !== void 0 && payload.generation !== current) {
+      return;
+    }
+    if (this.ctx.container?.running !== true) {
+      return;
+    }
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "stop", "hard timeout reached");
+    this.surfaceInStudioLogs(envelope);
+    await this.stop();
   }
   async onStop(parameters) {
     const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "stop", `${parameters.reason} (exit ${String(parameters.exitCode)})`);
     this.surfaceInStudioLogs(envelope);
     await super.onStop(parameters);
   }
+  /**
+   * Arm the hard-timeout kill via the base scheduler (so it integrates with
+   * the container's own alarm machinery instead of fighting it). Bumps the run
+   * generation and stamps the schedule with it, so {@link onHardTimeoutExpired}
+   * can tell a fresh schedule from a stale one. No-op without a `hardTimeout`.
+   */
+  async armHardTimeout() {
+    if (this.lunoraHardTimeoutSeconds === void 0) {
+      return;
+    }
+    const generation = (await this.ctx.storage.get(HARD_TIMEOUT_GENERATION_KEY) ?? 0) + 1;
+    await this.ctx.storage.put(HARD_TIMEOUT_GENERATION_KEY, generation);
+    await this.schedule(this.lunoraHardTimeoutSeconds, "onHardTimeoutExpired", { generation });
+  }
+  /**
+   * Block until every `readyOn` probe responds with its expected status, or
+   * throw once the readiness budget is spent. Probes run in parallel and hit
+   * the container's TCP port directly (NOT `containerFetch`, which would
+   * recurse back into the start path). No-op without `readyOn`.
+   */
+  async awaitContainerReadiness() {
+    if (this.lunoraReadyOn.length === 0) {
+      return;
+    }
+    const { container } = this.ctx;
+    if (container === void 0) {
+      return;
+    }
+    const deadline = Date.now() + READINESS_TIMEOUT_MS;
+    await Promise.all(this.lunoraReadyOn.map(async (check) => this.awaitReadinessCheck(container, check, deadline)));
+  }
+  /** Poll one readiness probe until it returns its expected status or the shared deadline passes. */
+  async awaitReadinessCheck(container, check, deadline) {
+    const port = check.port ?? this.lunoraDefaultPort;
+    if (port === void 0) {
+      throw new Error(
+        `container "${this.lunoraName}": readyOn check "${check.path}" has no port — set the check's \`port\` or the container \`defaultPort\`.`
+      );
+    }
+    const expectedStatus = check.status ?? 200;
+    const path = check.path.startsWith("/") ? check.path : `/${check.path}`;
+    const tcpPort = container.getTcpPort(port);
+    for (; ; ) {
+      try {
+        const response = await tcpPort.fetch(`http://container${path}`);
+        if (response.status === expectedStatus) {
+          return;
+        }
+      } catch {
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `container "${this.lunoraName}": readiness check "${check.path}" (port ${String(port)}) did not return ${String(expectedStatus)} within ${String(READINESS_TIMEOUT_MS)}ms`
+        );
+      }
+      await new Promise((resolve) => {
+        setTimeout(resolve, READINESS_POLL_INTERVAL_MS);
+      });
+    }
+  }
   /**
    * 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
@@ -135,4 +253,4 @@ class LunoraContainer extends Container {
   }
 }
 
-export { LunoraContainer as default };
+export { LunoraContainer };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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";
+import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-DAOLRiZQ.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/types.d-DAOLRiZQ.mjs";
 /**
 * The `ctx.containers` action surface: typed handles over the `CONTAINER_*`
 * Durable Object namespace bindings the config layer reconciles.
@@ -23,13 +23,25 @@ interface ContainerStartOptions {
 /** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
 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>;
 }
@@ -57,6 +69,15 @@ interface ContainerHandle {
   * `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
@@ -68,13 +89,48 @@ interface ContainerHandle {
 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 request automatically, but WebSocket message activity does not yet
+  * renew it (cloudflare/containers#147) — call this on inbound WS traffic to
+  * keep a busy socket's container awake.
+  */
+  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>;
 }
+/**
+* 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.
+*/
+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>`. */
 interface ContainerAccessor {
   /**
@@ -197,4 +253,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 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 NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-D2l2SYol.js";
-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.js";
+import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-DAOLRiZQ.js";
+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/types.d-DAOLRiZQ.js";
 /**
 * The `ctx.containers` action surface: typed handles over the `CONTAINER_*`
 * Durable Object namespace bindings the config layer reconciles.
@@ -23,13 +23,25 @@ interface ContainerStartOptions {
 /** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
 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>;
 }
@@ -57,6 +69,15 @@ interface ContainerHandle {
   * `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
@@ -68,13 +89,48 @@ interface ContainerHandle {
 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 request automatically, but WebSocket message activity does not yet
+  * renew it (cloudflare/containers#147) — call this on inbound WS traffic to
+  * keep a busy socket's container awake.
+  */
+  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>;
 }
+/**
+* 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.
+*/
+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>`. */
 interface ContainerAccessor {
   /**
@@ -197,4 +253,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 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 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-CTpyUQ4J.mjs';
-export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BGdSdFNA.mjs';
+export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-DBp8oJOr.mjs';
+export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-C7Lic2ET.mjs';

package/dist/packem_shared/{containerBindingName-BGdSdFNA.mjs → containerBindingName-C7Lic2ET.mjs}

@@ -1,6 +1,17 @@
 const NAMED_INSTANCE_TYPES = /* @__PURE__ */ new Set(["basic", "lite", "standard-1", "standard-2", "standard-3", "standard-4"]);
 const ENV_NAME_PATTERN = /^[A-Z_]\w*$/i;
 const SLEEP_AFTER_PATTERN = /^\d+[smh]$/;
+const DURATION_UNIT_SECONDS = { h: 3600, m: 60, s: 1 };
+const parseDurationSeconds = (duration) => {
+  if (typeof duration === "number") {
+    return Math.floor(duration);
+  }
+  const match = SLEEP_AFTER_PATTERN.exec(duration);
+  if (match === null) {
+    throw new TypeError(`Invalid duration "${duration}" — expected a number of seconds or "<n>[smh]"`);
+  }
+  return Number(duration.slice(0, -1)) * (DURATION_UNIT_SECONDS[duration.slice(-1)] ?? 1);
+};
 const basename = (path) => {
   const trimmed = path.endsWith("/") ? path.slice(0, -1) : path;
   const separatorIndex = trimmed.lastIndexOf("/");
@@ -72,10 +83,81 @@ const assertValidEnvAndSecrets = (config) => {
     }
   }
 };
+const assertValidPort = (port, field) => {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new TypeError(`defineContainer: \`${field}\` must be an integer in 1–65535 (got ${String(port)})`);
+  }
+};
+const assertValidReadyOnChecks = (config) => {
+  for (const check of config.readyOn ?? []) {
+    if (typeof check.path !== "string" || check.path.trim().length === 0) {
+      throw new TypeError("defineContainer: `readyOn[].path` must be a non-empty HTTP path string");
+    }
+    if (check.path !== check.path.trim()) {
+      throw new TypeError("defineContainer: `readyOn[].path` must not have leading or trailing whitespace");
+    }
+    if (check.port !== void 0) {
+      assertValidPort(check.port, "readyOn[].port");
+    }
+    if (check.status !== void 0 && (!Number.isInteger(check.status) || check.status < 100 || check.status > 599)) {
+      throw new TypeError(`defineContainer: \`readyOn[].status\` must be an HTTP status code in 100–599 (got ${String(check.status)})`);
+    }
+  }
+};
+const assertValidHardTimeout = (hardTimeout) => {
+  if (hardTimeout === void 0) {
+    return;
+  }
+  if (typeof hardTimeout === "string") {
+    if (!SLEEP_AFTER_PATTERN.test(hardTimeout)) {
+      throw new TypeError(
+        `defineContainer: \`hardTimeout\` string "${hardTimeout}" must be a number of seconds followed by a unit, e.g. "30s", "5m", or "1h"`
+      );
+    }
+  } else if (!Number.isInteger(hardTimeout) || hardTimeout < 1) {
+    throw new TypeError(
+      `defineContainer: \`hardTimeout\` must be a positive integer number of seconds or a duration string like "5m" (got ${String(hardTimeout)})`
+    );
+  }
+};
+const assertValidEgressFields = (config) => {
+  for (const field of ["allowedHosts", "deniedHosts"]) {
+    const hosts = config[field];
+    if (hosts?.some((host) => typeof host !== "string" || host.trim().length === 0)) {
+      throw new TypeError(`defineContainer: \`${field}\` must be an array of non-empty hostname patterns`);
+    }
+  }
+  if (config.interceptHttps !== void 0 && typeof config.interceptHttps !== "boolean") {
+    throw new TypeError("defineContainer: `interceptHttps` must be a boolean, or omitted");
+  }
+};
+const assertValidContainerRuntimeFields = (config) => {
+  if (config.requiredPorts !== void 0) {
+    if (config.requiredPorts.length === 0) {
+      throw new TypeError("defineContainer: `requiredPorts` must be a non-empty array of ports, or omitted");
+    }
+    for (const port of config.requiredPorts) {
+      assertValidPort(port, "requiredPorts[]");
+    }
+  }
+  if (config.entrypoint !== void 0 && (config.entrypoint.length === 0 || config.entrypoint.some((part) => typeof part !== "string" || part.trim().length === 0))) {
+    throw new TypeError("defineContainer: `entrypoint` must be a non-empty array of non-empty strings, or omitted");
+  }
+  assertValidEgressFields(config);
+  if (config.pingEndpoint !== void 0 && (typeof config.pingEndpoint !== "string" || config.pingEndpoint.trim().length === 0)) {
+    throw new TypeError("defineContainer: `pingEndpoint` must be a non-empty path string");
+  }
+  for (const [key, value] of Object.entries(config.labels ?? {})) {
+    if (key.trim().length === 0 || typeof value !== "string") {
+      throw new TypeError("defineContainer: `labels` must be a record of non-empty keys to string values");
+    }
+  }
+  assertValidReadyOnChecks(config);
+};
 const defineContainer = (config) => {
   assertValidImage(config.image);
-  if (config.defaultPort !== void 0 && (!Number.isInteger(config.defaultPort) || config.defaultPort < 1 || config.defaultPort > 65535)) {
-    throw new TypeError(`defineContainer: \`defaultPort\` must be an integer in 1–65535 (got ${String(config.defaultPort)})`);
+  if (config.defaultPort !== void 0) {
+    assertValidPort(config.defaultPort, "defaultPort");
   }
   const stepPercentage = config.rollout?.stepPercentage;
   if (stepPercentage !== void 0 && (!Number.isInteger(stepPercentage) || stepPercentage < 1 || stepPercentage > 100)) {
@@ -94,7 +176,9 @@ const defineContainer = (config) => {
       `defineContainer: \`sleepAfter\` string "${config.sleepAfter}" must be a number of seconds followed by a unit, e.g. "30s", "5m", or "1h"`
     );
   }
+  assertValidHardTimeout(config.hardTimeout);
   assertValidEnvAndSecrets(config);
+  assertValidContainerRuntimeFields(config);
   return { ...config, isLunoraContainer: true };
 };
 const isContainerDefinition = (value) => typeof value === "object" && value !== null && value.isLunoraContainer === true;
@@ -113,4 +197,4 @@ const resolveContainerEnvVariables = (definition, workerEnv, exportName) => {
   return resolved;
 };
 
-export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, parseDurationSeconds, resolveContainerEnvVariables as resolveContainerEnvVars };

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

@@ -11,17 +11,21 @@ const applyJurisdiction = (namespace, jurisdiction) => {
 };
 const DEFAULT_POOL_SIZE = 3;
 const DEFAULT_MAX_BACKOFF_MS = 3e4;
-const toRequest = (input, init) => {
-  if (typeof input === "string" && input.startsWith("/")) {
-    return new Request(`http://container${input}`, init);
+const TARGET_PORT_HEADER = "cf-container-target-port";
+const toRequest = (input, init, port) => {
+  const request = typeof input === "string" && input.startsWith("/") ? new Request(`http://container${input}`, init) : new Request(input, init);
+  if (port !== void 0) {
+    request.headers.set(TARGET_PORT_HEADER, String(port));
   }
-  return new Request(input, init);
+  return request;
 };
-const handleFor = (namespace, instanceName) => {
+const sendingHandle = (send, port) => {
   return {
-    fetch: async (input, init) => namespace.get(namespace.idFromName(instanceName)).fetch(toRequest(input, init))
+    fetch: async (input, init) => send(toRequest(input, init, port)),
+    port: (targetPort) => sendingHandle(send, targetPort)
   };
 };
+const handleFor = (namespace, instanceName) => sendingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request));
 const lifecycleCall = async (stub, method, binding, argument) => {
   const rpc = stub[method];
   if (typeof rpc !== "function") {
@@ -29,12 +33,24 @@ const lifecycleCall = async (stub, method, binding, argument) => {
   }
   return rpc(argument);
 };
+const egressControlsFor = (stub, binding) => {
+  return {
+    allow: async (hostname) => lifecycleCall(stub(), "allowHost", binding, hostname),
+    deny: async (hostname) => lifecycleCall(stub(), "denyHost", binding, hostname),
+    removeAllowed: async (hostname) => lifecycleCall(stub(), "removeAllowedHost", binding, hostname),
+    removeDenied: async (hostname) => lifecycleCall(stub(), "removeDeniedHost", binding, hostname),
+    setAllowed: async (hosts) => lifecycleCall(stub(), "setAllowedHosts", binding, [...hosts]),
+    setDenied: async (hosts) => lifecycleCall(stub(), "setDeniedHosts", binding, [...hosts])
+  };
+};
 const instanceHandleFor = (namespace, spec, instanceName) => {
   const stub = () => namespace.get(namespace.idFromName(instanceName));
   return {
+    ...sendingHandle(async (request) => stub().fetch(request)),
     destroy: async () => lifecycleCall(stub(), "destroy", spec.binding),
-    fetch: async (input, init) => stub().fetch(toRequest(input, init)),
+    egress: egressControlsFor(stub, spec.binding),
     getState: async () => lifecycleCall(stub(), "getState", spec.binding),
+    renewActivityTimeout: async () => lifecycleCall(stub(), "renewActivityTimeout", spec.binding),
     start: async (options) => lifecycleCall(stub(), "start", spec.binding, options),
     stop: async (signal) => lifecycleCall(stub(), "stop", spec.binding, signal)
   };
@@ -52,7 +68,7 @@ const sleep = async (ms) => {
   });
 };
 const retryOnServerError = (response) => response.status >= 500;
-const poolHandleFor = (namespace, spec, options = {}) => {
+const poolHandleFor = (namespace, spec, options = {}, port) => {
   const size = options.size ?? spec.maxInstances ?? DEFAULT_POOL_SIZE;
   const attempts = Math.max(1, options.attempts ?? 3);
   const baseBackoff = options.backoffMs ?? 100;
@@ -65,7 +81,7 @@ const poolHandleFor = (namespace, spec, options = {}) => {
         if (attempt > 0) {
           await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
         }
-        const request = toRequest(input, init);
+        const request = toRequest(input, init, port);
         try {
           const response = await namespace.get(namespace.idFromName(randomPoolName(size))).fetch(request);
           if (attempt === attempts - 1 || !shouldRetry(response)) {
@@ -76,7 +92,8 @@ const poolHandleFor = (namespace, spec, options = {}) => {
         }
       }
       throw lastError instanceof Error ? lastError : new Error(`ctx.containers.${spec.exportName}.pool(): all ${String(attempts)} attempts failed`);
-    }
+    },
+    port: (targetPort) => poolHandleFor(namespace, spec, options, targetPort)
   };
 };
 const accessorFor = (namespace, spec) => {
@@ -102,29 +119,37 @@ const createContainerContext = (env, specs, jurisdiction) => {
   }
   return containers;
 };
+const testNamespaceFor = (handler) => {
+  const stubFor = (name) => {
+    return {
+      allowHost: () => Promise.resolve(),
+      denyHost: () => Promise.resolve(),
+      destroy: () => Promise.resolve(),
+      fetch: (request) => Promise.resolve(handler(request, { name })),
+      getState: () => Promise.resolve({ lastChange: 0 }),
+      removeAllowedHost: () => Promise.resolve(),
+      removeDeniedHost: () => Promise.resolve(),
+      renewActivityTimeout: () => Promise.resolve(),
+      setAllowedHosts: () => Promise.resolve(),
+      setDeniedHosts: () => Promise.resolve(),
+      start: () => Promise.resolve(),
+      stop: () => Promise.resolve()
+    };
+  };
+  return { get: (id) => stubFor(String(id)), idFromName: (name) => name };
+};
 const createContainerTestContext = (handlers) => {
   const containers = {};
   for (const [exportName, handler] of Object.entries(handlers)) {
-    const testHandleFor = (instanceName) => {
-      return {
-        fetch: async (input, init) => handler(toRequest(input, init), { name: instanceName })
-      };
-    };
-    const testInstanceHandleFor = (instanceName) => {
-      return {
-        ...testHandleFor(instanceName),
-        destroy: () => Promise.resolve(),
-        getState: () => Promise.resolve({ lastChange: 0 }),
-        start: () => Promise.resolve(),
-        stop: () => Promise.resolve()
-      };
-    };
+    const namespace = testNamespaceFor(handler);
+    const spec = { binding: `CONTAINER_${exportName.toUpperCase()}`};
     containers[exportName] = {
-      any: () => testHandleFor("pool-0"),
-      get: (name) => testInstanceHandleFor(name),
-      // The double doesn't simulate failure/retry — pool() just routes to
-      // the handler like any other call, so tests stay deterministic.
-      pool: () => testHandleFor("pool-0")
+      // `.any()`/`.pool()` route to a fixed `pool-0` so the handler's
+      // `instance.name` is deterministic under test; the double doesn't
+      // simulate the random-pick or retry/backoff the real pool does.
+      any: () => handleFor(namespace, "pool-0"),
+      get: (name) => instanceHandleFor(namespace, spec, name),
+      pool: () => handleFor(namespace, "pool-0")
     };
   }
   return containers;

package/dist/packem_shared/{types.d-D2l2SYol.d.mts → types.d-DAOLRiZQ.d.mts}

@@ -52,7 +52,37 @@ interface BuildImageSource {
 * the Dockerfile itself — while `{ registry }` is a pre-built image reference.
 */
 type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
+/**
+* An application-level readiness probe that gates request proxying. Layered on
+* top of the platform's own port/`pingEndpoint` health wait, it lets you hold
+* traffic back until the app inside the container is *functionally* ready —
+* migrations applied, caches warmed — which an open-port check can't see.
+*
+* Declarative on purpose: a `defineContainer` value stays pure data (no handler
+* functions), so codegen and the config layer can read it without evaluating
+* code. (Upstream cloudflare/containers#188 expresses the same idea as handler
+* functions; the Lunora config is data-only, so it's modelled as descriptors.)
+*/
+interface ContainerReadinessCheck {
+  /** HTTP path probed on the container, e.g. `"/ready"` (a leading slash is optional). */
+  path: string;
+  /** Port to probe. Defaults to {@link ContainerConfig.defaultPort}. */
+  port?: number;
+  /** HTTP status that means "ready". Defaults to `200`. */
+  status?: number;
+}
 interface ContainerConfig {
+  /**
+  * Hostnames the container may reach **even when {@link ContainerConfig.enableInternet}
+  * is `false`** — an egress allow-list (Cloudflare's `allowedHosts`). Glob
+  * patterns like `*.stripe.com` are supported. Pair with `enableInternet:
+  * false` to deny all egress except these hosts (the firewall pattern
+  * upstream issue cloudflare/containers#30 asked for). The interception path
+  * needs the `ContainerProxy` worker entrypoint, which codegen re-exports
+  * from the generated container file automatically; the named-instance
+  * handle's `egress` controls adjust the lists at runtime.
+  */
+  allowedHosts?: ReadonlyArray<string>;
   /**
   * Build-time variables for a Dockerfile/Railpack image — wrangler's
   * `image_vars` (equivalent to `docker build --build-arg`). For *runtime*
@@ -62,21 +92,46 @@ interface ContainerConfig {
   buildArgs?: Readonly<Record<string, string>>;
   /**
   * The port the container listens on. Worker → container requests target
-  * this port. Locally the Dockerfile must also `EXPOSE` it.
+  * this port. Locally the Dockerfile must also `EXPOSE` it. For a
+  * multi-port container also declare {@link ContainerConfig.requiredPorts}
+  * and route per request with the handle's `.port(n)`.
   */
   defaultPort?: number;
   /**
+  * Hostnames the container may **never** reach — an egress deny-list
+  * (Cloudflare's `deniedHosts`). Overrides everything else, including
+  * `enableInternet: true` and {@link ContainerConfig.allowedHosts}. Glob
+  * patterns like `*.evil.com` are supported.
+  */
+  deniedHosts?: ReadonlyArray<string>;
+  /**
   * Whether the container may open outbound internet connections. Defaults
   * to `true` — the platform default. Note that container egress is billed
-  * per GB by Cloudflare.
+  * per GB by Cloudflare. Combine with {@link ContainerConfig.allowedHosts} /
+  * {@link ContainerConfig.deniedHosts} for a precise egress firewall.
   */
   enableInternet?: boolean;
   /**
+  * Default command to run inside the container, overriding the image's
+  * `ENTRYPOINT`/`CMD` (Cloudflare's `entrypoint`). A per-start override is
+  * still available via the named-instance handle's `start({ entrypoint })`.
+  */
+  entrypoint?: ReadonlyArray<string>;
+  /**
   * Static environment variables passed to the container on every start.
   * For secret values use {@link ContainerConfig.secrets} instead so they
   * flow through Worker Secrets rather than source code.
   */
   env?: Readonly<Record<string, string>>;
+  /**
+  * Hard cap on how long an instance may run, measured from start regardless
+  * of activity — a runaway-cost backstop on top of the idle
+  * {@link ContainerConfig.sleepAfter}. Same grammar as `sleepAfter`
+  * (`"30s"`, `"5m"`, `"1h"`, or a plain number of seconds). When it elapses,
+  * the `LunoraContainer.onHardTimeoutExpired` hook runs (default: `stop()`).
+  * (Upstream cloudflare/containers#85.)
+  */
+  hardTimeout?: number | string;
   /** Image source — a local Dockerfile path/directory or a registry reference. */
   image: ContainerImageSource;
   /**
@@ -85,6 +140,21 @@ interface ContainerConfig {
   */
   instanceType?: ContainerInstanceType;
   /**
+  * Intercept the container's outbound **HTTPS** traffic so the egress
+  * allow/deny lists apply to TLS connections too (Cloudflare's
+  * `interceptHttps`). Requires the image to trust the Cloudflare CA at
+  * `/etc/cloudflare/certs/cloudflare-containers-ca.crt`. Defaults to `false`
+  * (HTTP egress is gated regardless).
+  */
+  interceptHttps?: boolean;
+  /**
+  * Key-value metadata attached to every instance for metrics/observability
+  * (Cloudflare's container `labels`), e.g. `{ tenant: "acme", env: "prod" }`.
+  * A per-start override is available via the named-instance handle's
+  * `start({ labels })`.
+  */
+  labels?: Readonly<Record<string, string>>;
+  /**
   * Maximum number of concurrently *running* instances. Stopped (slept)
   * containers don't count. Also the default pool size for `.any()`.
   */
@@ -95,6 +165,30 @@ interface ContainerConfig {
   */
   name?: string;
   /**
+  * HTTP path Cloudflare polls to decide an instance is healthy
+  * (Cloudflare's `pingEndpoint`). Defaults to upstream's slash-less `"ping"`;
+  * either `"ping"` or `"/healthz"`-style paths are accepted. Set this when
+  * the container exposes its readiness check under a different route.
+  */
+  pingEndpoint?: string;
+  /**
+  * Application-level readiness probes that gate request proxying: a
+  * `ctx.containers.&lt;name>` fetch waits until every probe responds with its
+  * expected status before the request reaches the container — on top of the
+  * platform's port/`pingEndpoint` health wait. All probes run in parallel.
+  * Use these for readiness an open-port check can't see (migrations applied,
+  * caches warm). (Upstream cloudflare/containers#188.)
+  */
+  readyOn?: ReadonlyArray<ContainerReadinessCheck>;
+  /**
+  * Ports the container must be listening on before it's considered ready
+  * (Cloudflare's `requiredPorts`) — for multi-port containers. Start-up
+  * waits for every listed port, and the handle's `.port(n)` routes a request
+  * to any of them; {@link ContainerConfig.defaultPort} is the target when a
+  * request doesn't pick one.
+  */
+  requiredPorts?: ReadonlyArray<number>;
+  /**
   * Rolling-deploy tuning. `stepPercentage` is the share of instances updated
   * per rollout step (wrangler `rollout_step_percentage`); `gracePeriodSeconds`
   * is how long an active instance is left running before it's eligible for
@@ -137,4 +231,4 @@ type NormalizedContainerImage = {
   kind: "registry"; /** Fully-qualified image reference (wrangler `image`). */
   reference: string;
 };
-export { BuildImageSource as B, ContainerDefinition as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerRollout as d, CustomContainerInstanceType as e, NamedContainerInstanceType as f };
+export { BuildImageSource as B, ContainerDefinition as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };

package/dist/packem_shared/{types.d-D2l2SYol.d.ts → types.d-DAOLRiZQ.d.ts}

@@ -52,7 +52,37 @@ interface BuildImageSource {
 * the Dockerfile itself — while `{ registry }` is a pre-built image reference.
 */
 type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
+/**
+* An application-level readiness probe that gates request proxying. Layered on
+* top of the platform's own port/`pingEndpoint` health wait, it lets you hold
+* traffic back until the app inside the container is *functionally* ready —
+* migrations applied, caches warmed — which an open-port check can't see.
+*
+* Declarative on purpose: a `defineContainer` value stays pure data (no handler
+* functions), so codegen and the config layer can read it without evaluating
+* code. (Upstream cloudflare/containers#188 expresses the same idea as handler
+* functions; the Lunora config is data-only, so it's modelled as descriptors.)
+*/
+interface ContainerReadinessCheck {
+  /** HTTP path probed on the container, e.g. `"/ready"` (a leading slash is optional). */
+  path: string;
+  /** Port to probe. Defaults to {@link ContainerConfig.defaultPort}. */
+  port?: number;
+  /** HTTP status that means "ready". Defaults to `200`. */
+  status?: number;
+}
 interface ContainerConfig {
+  /**
+  * Hostnames the container may reach **even when {@link ContainerConfig.enableInternet}
+  * is `false`** — an egress allow-list (Cloudflare's `allowedHosts`). Glob
+  * patterns like `*.stripe.com` are supported. Pair with `enableInternet:
+  * false` to deny all egress except these hosts (the firewall pattern
+  * upstream issue cloudflare/containers#30 asked for). The interception path
+  * needs the `ContainerProxy` worker entrypoint, which codegen re-exports
+  * from the generated container file automatically; the named-instance
+  * handle's `egress` controls adjust the lists at runtime.
+  */
+  allowedHosts?: ReadonlyArray<string>;
   /**
   * Build-time variables for a Dockerfile/Railpack image — wrangler's
   * `image_vars` (equivalent to `docker build --build-arg`). For *runtime*
@@ -62,21 +92,46 @@ interface ContainerConfig {
   buildArgs?: Readonly<Record<string, string>>;
   /**
   * The port the container listens on. Worker → container requests target
-  * this port. Locally the Dockerfile must also `EXPOSE` it.
+  * this port. Locally the Dockerfile must also `EXPOSE` it. For a
+  * multi-port container also declare {@link ContainerConfig.requiredPorts}
+  * and route per request with the handle's `.port(n)`.
   */
   defaultPort?: number;
   /**
+  * Hostnames the container may **never** reach — an egress deny-list
+  * (Cloudflare's `deniedHosts`). Overrides everything else, including
+  * `enableInternet: true` and {@link ContainerConfig.allowedHosts}. Glob
+  * patterns like `*.evil.com` are supported.
+  */
+  deniedHosts?: ReadonlyArray<string>;
+  /**
   * Whether the container may open outbound internet connections. Defaults
   * to `true` — the platform default. Note that container egress is billed
-  * per GB by Cloudflare.
+  * per GB by Cloudflare. Combine with {@link ContainerConfig.allowedHosts} /
+  * {@link ContainerConfig.deniedHosts} for a precise egress firewall.
   */
   enableInternet?: boolean;
   /**
+  * Default command to run inside the container, overriding the image's
+  * `ENTRYPOINT`/`CMD` (Cloudflare's `entrypoint`). A per-start override is
+  * still available via the named-instance handle's `start({ entrypoint })`.
+  */
+  entrypoint?: ReadonlyArray<string>;
+  /**
   * Static environment variables passed to the container on every start.
   * For secret values use {@link ContainerConfig.secrets} instead so they
   * flow through Worker Secrets rather than source code.
   */
   env?: Readonly<Record<string, string>>;
+  /**
+  * Hard cap on how long an instance may run, measured from start regardless
+  * of activity — a runaway-cost backstop on top of the idle
+  * {@link ContainerConfig.sleepAfter}. Same grammar as `sleepAfter`
+  * (`"30s"`, `"5m"`, `"1h"`, or a plain number of seconds). When it elapses,
+  * the `LunoraContainer.onHardTimeoutExpired` hook runs (default: `stop()`).
+  * (Upstream cloudflare/containers#85.)
+  */
+  hardTimeout?: number | string;
   /** Image source — a local Dockerfile path/directory or a registry reference. */
   image: ContainerImageSource;
   /**
@@ -85,6 +140,21 @@ interface ContainerConfig {
   */
   instanceType?: ContainerInstanceType;
   /**
+  * Intercept the container's outbound **HTTPS** traffic so the egress
+  * allow/deny lists apply to TLS connections too (Cloudflare's
+  * `interceptHttps`). Requires the image to trust the Cloudflare CA at
+  * `/etc/cloudflare/certs/cloudflare-containers-ca.crt`. Defaults to `false`
+  * (HTTP egress is gated regardless).
+  */
+  interceptHttps?: boolean;
+  /**
+  * Key-value metadata attached to every instance for metrics/observability
+  * (Cloudflare's container `labels`), e.g. `{ tenant: "acme", env: "prod" }`.
+  * A per-start override is available via the named-instance handle's
+  * `start({ labels })`.
+  */
+  labels?: Readonly<Record<string, string>>;
+  /**
   * Maximum number of concurrently *running* instances. Stopped (slept)
   * containers don't count. Also the default pool size for `.any()`.
   */
@@ -95,6 +165,30 @@ interface ContainerConfig {
   */
   name?: string;
   /**
+  * HTTP path Cloudflare polls to decide an instance is healthy
+  * (Cloudflare's `pingEndpoint`). Defaults to upstream's slash-less `"ping"`;
+  * either `"ping"` or `"/healthz"`-style paths are accepted. Set this when
+  * the container exposes its readiness check under a different route.
+  */
+  pingEndpoint?: string;
+  /**
+  * Application-level readiness probes that gate request proxying: a
+  * `ctx.containers.&lt;name>` fetch waits until every probe responds with its
+  * expected status before the request reaches the container — on top of the
+  * platform's port/`pingEndpoint` health wait. All probes run in parallel.
+  * Use these for readiness an open-port check can't see (migrations applied,
+  * caches warm). (Upstream cloudflare/containers#188.)
+  */
+  readyOn?: ReadonlyArray<ContainerReadinessCheck>;
+  /**
+  * Ports the container must be listening on before it's considered ready
+  * (Cloudflare's `requiredPorts`) — for multi-port containers. Start-up
+  * waits for every listed port, and the handle's `.port(n)` routes a request
+  * to any of them; {@link ContainerConfig.defaultPort} is the target when a
+  * request doesn't pick one.
+  */
+  requiredPorts?: ReadonlyArray<number>;
+  /**
   * Rolling-deploy tuning. `stepPercentage` is the share of instances updated
   * per rollout step (wrangler `rollout_step_percentage`); `gracePeriodSeconds`
   * is how long an active instance is left running before it's eligible for
@@ -137,4 +231,4 @@ type NormalizedContainerImage = {
   kind: "registry"; /** Fully-qualified image reference (wrangler `image`). */
   reference: string;
 };
-export { BuildImageSource as B, ContainerDefinition as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerRollout as d, CustomContainerInstanceType as e, NamedContainerInstanceType as f };
+export { BuildImageSource as B, ContainerDefinition as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };

package/package.json

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