@lunora/container 1.0.0-alpha.6 → 1.0.0-alpha.60

package/dist/do/index.d.ts

@@ -1,5 +1,5 @@
+import { C as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-DPvNG2h5.js";
 import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
-import { a as ContainerDefinition } from "../packem_shared/types.d-BlNwNY44.js";
 /**
  * ContainerStartOptions as they come from worker types
  */
@@ -119,7 +119,7 @@ type OutboundHandler<E = Cloudflare.Env, P = unknown> = {
 type OutboundHandlerParams = Record<string, unknown>;
 type OutboundHandlerParamsOf<THandler> = THandler extends ((req: Request, env: unknown, ctx: OutboundHandlerContext<infer Params>) => Promise<Response> | Response) ? Params : never;
 declare function outboundParams<THandler extends OutboundHandler<unknown, unknown>>(_handler: THandler, params: OutboundHandlerParamsOf<THandler>): OutboundHandlerParamsOf<THandler>;
-type OutboundHandlers<ParamsByMethod extends OutboundHandlerParams, E = Cloudflare.Env> = { [Method in keyof ParamsByMethod]?: OutboundHandler<E, ParamsByMethod[Method]> };
+type OutboundHandlers<ParamsByMethod extends OutboundHandlerParams, E = Cloudflare.Env> = { [Method in keyof ParamsByMethod]?: OutboundHandler<E, ParamsByMethod[Method]>; };
 type OutboundHandlerOverride<Params = unknown> = {
   method: string;
 } & ([Params] extends [undefined] ? {
@@ -483,44 +483,30 @@ declare class Container<Env = Cloudflare.Env> extends DurableObject<Env> {
   getSchedule<T = string>(id: string): Promise<Schedule<T> | undefined>;
   private isActivityExpired;
 }
-/**
-* Cloudflare Durable Object data-residency jurisdiction. Widening union —
-* Cloudflare adds values over time.
-* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
-*/
-type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-/**
-* Forward one lifecycle envelope to the root ShardDO's log buffer, best-effort.
-*
-* `env` is the Container DO's worker `env`: we read the `SHARD` namespace and
-* the `LUNORA_ADMIN_TOKEN` from it. Returns a promise that NEVER rejects — every
-* failure path (missing binding, missing token, fetch error) resolves to
-* `undefined` — so the caller can `void` it from a lifecycle hook safely.
-*/
 type DurableObjectContext = ConstructorParameters<typeof Container>[0];
 /**
-* Base class for the generated Container DO classes. Applies a
-* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
-* port, sleep timeout, internet access, and the container environment (static
-* `env` merged with the declared Worker secrets — a declared-but-unset secret
-* fails fast here rather than starting a container without its credential).
-*
-* Generated subclasses stay one line of behavior:
-*
-* ```ts
-* export class TranscoderContainer extends LunoraContainer {
-*     constructor(ctx: DurableObjectState, env: Env) {
-*         super(ctx, env, transcoder, "transcoder");
-*     }
-* }
-* ```
-*/
+ * Base class for the generated Container DO classes. Applies a
+ * `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+ * port, sleep timeout, internet access, and the container environment (static
+ * `env` merged with the declared Worker secrets — a declared-but-unset secret
+ * fails fast here rather than starting a container without its credential).
+ *
+ * Generated subclasses stay one line of behavior:
+ *
+ * ```ts
+ * export class TranscoderContainer extends LunoraContainer {
+ *     constructor(ctx: DurableObjectState, env: Env) {
+ *         super(ctx, env, transcoder, "transcoder");
+ *     }
+ * }
+ * ```
+ */
 declare class LunoraContainer<Env = unknown> extends Container<Env> {
   /**
-  * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
-  * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
-  * to the same region as the root shard. `undefined` ⇒ un-pinned.
-  */
+   * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
+   * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
+   * to the same region as the root shard. `undefined` ⇒ un-pinned.
+   */
   private readonly lunoraJurisdiction?;
   /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
   private readonly lunoraName;
@@ -528,84 +514,238 @@ declare class LunoraContainer<Env = unknown> extends Container<Env> {
   private readonly lunoraDefaultPort?;
   /** Hard-cap lifetime in whole seconds (from the `hardTimeout` config), or `undefined`. */
   private readonly lunoraHardTimeoutSeconds?;
+  /** In-flight `readyOn` gate for the current start; cleared when it fails. See `awaitReadinessGate`. */
+  private lunoraReadiness?;
   /** Declarative readiness probes that gate request proxying (from the `readyOn` config). */
   private readonly lunoraReadyOn;
   /** Map of container env-var name → Worker Secrets Store binding name (from the `secretsStore` config). */
   private readonly lunoraSecretsStore?;
-  /** Memoised Secrets Store resolution: run once, then merged into `envVars` before the first start. */
+  /** The definition's `env` + `secrets`, as resolved at construction — the env a start uses absent an override. */
+  private readonly lunoraDeclaredEnv;
+  /** The persisted `start({ envVars })` override, once loaded. See {@link ENV_OVERRIDE_KEY}. */
+  private lunoraEnvOverride?;
+  /** Whether the override field reflects storage (read once per DO instance, then kept in step). */
+  private lunoraEnvOverrideLoaded;
+  /** Memoised Secrets Store resolution: the resolved `name → value` map, fetched once. */
   private lunoraSecretsStoreResolved?;
+  /**
+   * Count of runs observed to have ENDED, bumped by the `onStop` hook. Read
+   * across a start: a bump means the run that start snapshotted is over,
+   * whatever the `running` flag said at snapshot time. See `beginStart`.
+   */
+  private lunoraStops;
   constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
   /**
-  * Proxy entry for every `ctx.containers.&lt;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.
-  */
+   * HTTP entry for every request to this Durable Object. Refuses the reserved
+   * `/__lunora/*` namespace unconditionally: `exec` reaches it only through
+   * the {@link lunoraExec} RPC, so no header, path spelling, or inbound request
+   * an app forwards as-is (`env.CONTAINER_X.get(id).fetch(request)`) opens it.
+   * The client-side path guard is the first line; this is the second.
+   */
+  override fetch(request: Request): Promise<Response>;
+  /**
+   * Proxy entry for every `ctx.containers.<name>` fetch — and a public RPC on
+   * the stub in its own right, so it applies the same `/__lunora/*` refusal
+   * as {@link fetch} rather than trusting that every caller came through it.
+   * The base starts the container for this request through
+   * {@link startAndWaitForPorts}, which is where the `secretsStore` resolution
+   * lives — a request that finds the container already healthy needs no
+   * resolution at all.
+   */
   override containerFetch(...args: Parameters<Container<Env>["containerFetch"]>): Promise<Response>;
   /**
-  * Explicit start (`ctx.containers.&lt;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.
-  */
+   * The exec entry: `handle.exec` delivers its `POST /__lunora/exec` here, as
+   * an RPC, never over {@link fetch}. An RPC can only be invoked by code that
+   * holds the Durable Object binding, which is what makes the exec route
+   * unreachable from request content. Accepts exactly the exec route and
+   * nothing else under the reserved namespace, and honours a `.port(n)`
+   * handle's target-port header the way the base `fetch` does.
+   */
+  lunoraExec(request: Request): Promise<Response>;
+  /**
+   * The start path `containerFetch` takes (and the one an app can call itself).
+   * Resolves the `secretsStore` bindings into `envVars` first — `doStartContainer`
+   * reads `this.envVars`, so a container started this way would otherwise boot
+   * without its Secrets Store values.
+   *
+   * The base's last act is `blockConcurrencyWhile(… onStart())`, so this
+   * override resumes on the far side of that gate — which is where
+   * {@link afterContainerStart} has to run. See its docblock.
+   */
+  override startAndWaitForPorts(...args: Parameters<Container<Env>["startAndWaitForPorts"]>): Promise<void>;
+  /**
+   * Explicit start (`ctx.containers.<name>.get(id).start()`).
+   *
+   * A per-instance `start({ envVars })` REPLACES the declared env (`env`,
+   * `secrets`, `secretsStore` — the Secrets Store is not even read) and is
+   * PERSISTED: every later start of this instance, explicit or implicit (a
+   * `fetch`/`exec` after the container slept, crashed or hit `hardTimeout`),
+   * boots with the same variables until `destroy()`. That is what makes
+   * `start({ envVars: {} })` a credential-free sandbox rather than one that
+   * gets its credentials back on the next restart.
+   *
+   * A start with `envVars` that differ from what the instance is running (or
+   * starting) with is REJECTED rather than silently joined: the base would
+   * return early on a live container, reporting a start whose env never took
+   * effect. `stop()` it first, or `destroy()` it to drop the override.
+   */
   override start(...args: Parameters<Container<Env>["start"]>): Promise<void>;
+  /**
+   * Stop the container and forget this instance's `start({ envVars })`
+   * override, so the next start uses the declared env again.
+   */
+  override destroy(): Promise<void>;
   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).
-  */
+   * 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).
+   *
+   * `stop()` sends SIGTERM and returns; nothing escalates to `destroy()`. The
+   * cap is therefore a signal, not a bound — a container that traps or ignores
+   * SIGTERM keeps running, and the schedule is ONE-SHOT (the base deletes the
+   * row once it fires), so nothing signals it a second time either: an ignored
+   * SIGTERM means the cap is spent, not retried. Override this hook and follow
+   * the stop with a `destroy()` after a grace period if your workload needs a
+   * real ceiling.
+   */
   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`.
-  */
+  /** A 403 for a path under the reserved namespace, else `undefined`. */
+  private refuseReserved;
+  /**
+   * Arm the hard timeout and block on the `readyOn` probes — the work that has
+   * to happen once per real start, **outside** the base's start gate.
+   *
+   * It cannot live in `onStart`, which is the obvious home for it: the base
+   * invokes that hook as `blockConcurrencyWhile(async () => { … onStart() })`
+   * (`@cloudflare/containers`, both `start()` and `startAndWaitForPorts()`),
+   * and workerd treats a *rejecting* `blockConcurrencyWhile` closure as
+   * unrecoverable — it aborts the Durable Object, discards its in-memory state
+   * and every hibernating socket on it, and flattens the error to a plain
+   * `Error`. A readiness timeout is an ordinary, diagnosable failure: it must
+   * surface as the `LunoraError` naming the check, the port and the budget,
+   * not cost the object its life and arrive as an opaque message. (The same
+   * reasoning, and the same settle-outside-the-gate remedy, is written up on
+   * `ShardHost.runSerialized` in `@lunora/platform-cloudflare`.) A 30-second
+   * wait also has no business inside a gate that blocks every other dispatch
+   * to the object.
+   *
+   * Both start entry points call this immediately after `super`, so it runs
+   * once per start. It does NOT gate proxying on its own: the base commits the
+   * healthy state inside the start gate, before this runs, so a concurrent
+   * request would sail past `containerFetch`'s status check. That is what
+   * `awaitReadinessGate` is for, and it is the seam the move cost us —
+   * the in-gate placement got this for free from `blockConcurrencyWhile`.
+   */
+  private afterContainerStart;
+  /**
+   * Decide — synchronously, before anything is started — whether this start
+   * begins a NEW container run, and drop the previous run's readiness gate when
+   * it does. Returns whether the container was already running.
+   *
+   * The gate has to be keyed on the run, and `onStop` alone cannot key it:
+   * `@cloudflare/containers` reaches `onStop` only through
+   * `syncPendingStoppedEvents`, which `start()` never calls (only
+   * `startAndWaitForPorts`, `stop()` and the alarm loop do), while the monitor
+   * callback that observes a container exit merely records the state. So a
+   * `start()` in the up-to-three-minute window before the next alarm found the
+   * finished run's settled gate and skipped BOTH `armHardTimeout` and the
+   * `readyOn` probes — run 2 ran uncapped and was proxied to before it reported
+   * ready. A `hardTimeout` firing its own SIGTERM lands in exactly that window.
+   *
+   * The mirror case is why the answer is not "always re-arm": a start that finds
+   * the container already up begins no run, and re-arming there moves the cap
+   * (see {@link afterContainerStart}).
+   *
+   * Read with no `await` between it and `super`, so two concurrent starts of a
+   * stopped container both observe `false` and the second joins the first's
+   * gate instead of arming a second schedule — and so the flag is as fresh as
+   * it can be. It is a snapshot either way, and the run can end after it: the
+   * base's own pre-start work (`getPortsToCheck`, `syncPendingStoppedEvents`)
+   * still runs on the far side of it, and a start that came in on a live
+   * container would then arm nothing for the run the base goes on to start.
+   * Hence the second half of the answer, in the callers: an `onStop` observed
+   * ACROSS the base call ({@link lunoraStops}) demotes the snapshot, because
+   * the run it described is over. What that does not cover is an exit inside
+   * `start()`'s own base call — that path never syncs pending stop events, so
+   * nothing reports the exit until the next alarm or `startAndWaitForPorts`,
+   * and the cap for such a run is armed only when one of those arrives.
+   */
+  private beginStart;
+  /**
+   * Block until the `readyOn` probes for the current start have passed.
+   *
+   * Necessary because the base marks the container healthy *inside* the start
+   * gate — `startAndWaitForPorts` runs `setHealthy()` immediately before
+   * `onStart()` — while our probes run after it returns. `containerFetch`
+   * skips the start path entirely once it observes
+   * `container.running && status === "healthy"`, so without this a request
+   * arriving mid-probe would proxy to a container that never reported ready,
+   * and a request arriving after a *failed* probe would do so permanently.
+   * Holding `setHealthy` and the probes together the way the base does would
+   * mean putting the probes back inside the gate, which is the defect this
+   * whole path exists to avoid.
+   */
+  private awaitReadinessGate;
+  /**
+   * 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;
   /**
-  * 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`.
-  */
+   * 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`.
+   */
   private resolveSecretsStoreEnv;
+  /** The persisted `start({ envVars })` override, read from storage once per instance lifetime. */
+  private readEnvOverride;
   /**
-  * 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`.
-  */
+   * Record a `start({ envVars })` override, refusing one that differs from
+   * the env a running (or starting) container already has — see {@link start}.
+   */
+  private persistEnvOverride;
+  /**
+   * Set `envVars` for the start about to happen: the persisted override when
+   * there is one (the Secrets Store is not read), else the declared env plus
+   * the resolved Secrets Store values.
+   */
+  private applyStartEnv;
+  /**
+   * 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
-  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
-  * out of a lifecycle hook — the `console` path stays the source of truth.
-  */
+   * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+   * also appears in the Studio Logs panel (the terminal already has it via
+   * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+   * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+   * out of a lifecycle hook — the `console` path stays the source of truth.
+   */
   private surfaceInStudioLogs;
   /**
-  * Per-instance correlation id: the Durable Object id, which Cloudflare also
-  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
-  * defensively — the id shape varies and isn't worth crashing a hook over.
-  */
+   * Per-instance correlation id: the Durable Object id, which Cloudflare also
+   * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+   * defensively — the id shape varies and isn't worth crashing a hook over.
+   */
   private instanceId;
 }
 export { ContainerProxy, LunoraContainer, type OutboundHandler, type OutboundHandlerContext, type OutboundHandlerParams, type OutboundHandlerParamsOf, type OutboundHandlers, outboundParams };