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

package/dist/do/index.mjs

@@ -1,5 +1,6 @@
-import { Container } from '@cloudflare/containers';
-import { resolveContainerEnvVars as resolveContainerEnvVariables } from '../packem_shared/containerBindingName-BGdSdFNA.mjs';
+import { Container } from '../packem_shared/ContainerProxy-DWqUX_re.mjs';
+export { ContainerProxy, outboundParams } from '../packem_shared/ContainerProxy-DWqUX_re.mjs';
+import { resolveContainerEnvVars as resolveContainerEnvVariables, parseDurationSeconds } from '../packem_shared/containerBindingName-CWmEE_3Y.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,82 @@ 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;
+  /** Map of container env-var name → Worker Secrets Store binding name (from the `secretsStore` config). */
+  lunoraSecretsStore;
+  /** Memoised Secrets Store resolution: run once, then merged into `envVars` before the first start. */
+  lunoraSecretsStoreResolved;
   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);
+    this.lunoraSecretsStore = definition.secretsStore;
+  }
+  /**
+   * Proxy entry for every `ctx.containers.<name>` fetch. Resolves the
+   * `secretsStore` bindings into `envVars` before delegating, so the values
+   * are present when the base implicitly starts the container for this
+   * request — a no-op when `secretsStore` is unset.
+   */
+  async containerFetch(...args) {
+    await this.resolveSecretsStoreEnv();
+    return super.containerFetch(...args);
+  }
+  /**
+   * Explicit start (`ctx.containers.<name>.get(id).start()`). Resolves the
+   * `secretsStore` bindings into `envVars` first, mirroring
+   * {@link containerFetch}. A per-instance `start({ envVars })` replaces the
+   * env set wholesale (base behavior), so the injected values only apply to a
+   * bare `start()` — same as the static `env`/`secrets`. When the caller
+   * supplies its own `envVars` we skip resolution entirely: those values would
+   * be discarded anyway, so a missing/unreadable binding shouldn't fail a start
+   * that never uses them.
+   */
+  async start(...args) {
+    const [options] = args;
+    if (options?.envVars === void 0) {
+      await this.resolveSecretsStoreEnv();
+    }
+    return super.start(...args);
+  }
+  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 +172,129 @@ 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 });
+  }
+  /**
+   * Resolve the `secretsStore` bindings (async `.get()`) once and merge the
+   * values into `envVars`, so they're present when the base starts the
+   * container. Memoised on the first call — every later start reuses the
+   * resolved promise. A missing binding or a non-string value fails fast (the
+   * start surfaces the error), the same fail-closed stance the static
+   * `secrets` resolution takes for a missing Worker secret. No-op without
+   * `secretsStore`.
+   */
+  async resolveSecretsStoreEnv() {
+    const secretsStore = this.lunoraSecretsStore;
+    if (secretsStore === void 0) {
+      return;
+    }
+    this.lunoraSecretsStoreResolved ??= (async () => {
+      const workerEnv = this.env;
+      const resolved = {};
+      for (const [envName, binding] of Object.entries(secretsStore)) {
+        const store = workerEnv[binding];
+        if (store === void 0 || typeof store.get !== "function") {
+          throw new Error(
+            `container "${this.lunoraName}": secretsStore env "${envName}" points at binding "${binding}", which is not a Secrets Store binding on the Worker env. Add a \`secrets_store_secrets\` entry binding "${binding}".`
+          );
+        }
+        const value = await store.get();
+        if (typeof value !== "string") {
+          throw new TypeError(
+            `container "${this.lunoraName}": Secrets Store binding "${binding}" (env "${envName}") did not resolve to a string value.`
+          );
+        }
+        resolved[envName] = value;
+      }
+      this.envVars = { ...this.envVars, ...resolved };
+    })();
+    await this.lunoraSecretsStoreResolved;
+  }
+  /**
+   * 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 +321,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 { C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-BlNwNY44.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-BlNwNY44.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,23 +89,76 @@ 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 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>;
 }
+/**
+* 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 {
   /**
   * 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) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+  any: (count?: number, options?: InstanceRetryOptions) => ContainerHandle;
+  /**
+  * 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
@@ -121,6 +195,24 @@ interface PoolOptions {
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
   size?: number;
 }
+/**
+* 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.
+*/
+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. */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
@@ -197,4 +289,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 InstanceRetryOptions, 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 { C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-BlNwNY44.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-BlNwNY44.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,23 +89,76 @@ 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 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>;
 }
+/**
+* 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 {
   /**
   * 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) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+  any: (count?: number, options?: InstanceRetryOptions) => ContainerHandle;
+  /**
+  * 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
@@ -121,6 +195,24 @@ interface PoolOptions {
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
   size?: number;
 }
+/**
+* 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.
+*/
+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. */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
@@ -197,4 +289,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 InstanceRetryOptions, 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-BtzK5gJL.mjs';
+export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-CWmEE_3Y.mjs';