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

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-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";
+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.
@@ -101,9 +101,12 @@ interface ContainerInstanceHandle extends ContainerHandle {
   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.
+  * 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. */
@@ -137,10 +140,25 @@ 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, 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.
   */
-  any: (count?: number) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+  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
@@ -177,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`. */
@@ -253,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 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 };
+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-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";
+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.
@@ -101,9 +101,12 @@ interface ContainerInstanceHandle extends ContainerHandle {
   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.
+  * 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. */
@@ -137,10 +140,25 @@ 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, 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.
   */
-  any: (count?: number) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+  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
@@ -177,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`. */
@@ -253,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 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 };
+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-DBp8oJOr.mjs';
-export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-C7Lic2ET.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';