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

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

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 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]$/;
@@ -60,6 +62,19 @@ const assertValidImage = (image) => {
     throw new TypeError("defineContainer: `image.registry` must be a non-empty fully-qualified image reference");
   }
 };
+const assertValidSecretsStore = (config, envNames, secretNames) => {
+  for (const [envName, binding] of Object.entries(config.secretsStore ?? {})) {
+    if (!ENV_NAME_PATTERN.test(envName)) {
+      throw new TypeError(`defineContainer: secretsStore env name "${envName}" is not a valid environment variable name`);
+    }
+    if (typeof binding !== "string" || binding.trim().length === 0) {
+      throw new TypeError(`defineContainer: \`secretsStore["${envName}"]\` must be a non-empty Secrets Store binding name`);
+    }
+    if (envNames.has(envName) || secretNames.has(envName)) {
+      throw new TypeError(`defineContainer: "${envName}" is declared in both \`secretsStore\` and \`env\`/\`secrets\` — pick one source for the value`);
+    }
+  }
+};
 const assertValidEnvAndSecrets = (config) => {
   for (const name of Object.keys(config.env ?? {})) {
     if (!ENV_NAME_PATTERN.test(name)) {
@@ -72,6 +87,7 @@ const assertValidEnvAndSecrets = (config) => {
     }
   }
   const envNames = new Set(Object.keys(config.env ?? {}));
+  const secretNames = new Set(config.secrets);
   for (const secret of config.secrets ?? []) {
     if (!ENV_NAME_PATTERN.test(secret)) {
       throw new TypeError(`defineContainer: secret name "${secret}" is not a valid environment variable name`);
@@ -82,6 +98,7 @@ const assertValidEnvAndSecrets = (config) => {
       );
     }
   }
+  assertValidSecretsStore(config, envNames, secretNames);
 };
 const assertValidPort = (port, field) => {
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -188,7 +205,8 @@ const resolveContainerEnvVariables = (definition, workerEnv, exportName) => {
     const value = workerEnv[secret];
     if (typeof value !== "string") {
       const label = exportName === void 0 ? "container" : `container "${exportName}"`;
-      throw new Error(
+      throw new LunoraError(
+        "INTERNAL",
         `${label}: declared secret "${secret}" is not set on the Worker environment. Add it to .dev.vars for local dev and run \`wrangler secret put ${secret}\` for production.`
       );
     }

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

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const applyJurisdiction = (namespace, jurisdiction) => {
   if (jurisdiction === void 0) {
     return namespace;
@@ -11,6 +13,8 @@ const applyJurisdiction = (namespace, jurisdiction) => {
 };
 const DEFAULT_POOL_SIZE = 3;
 const DEFAULT_MAX_BACKOFF_MS = 3e4;
+const DEFAULT_COLD_START_ATTEMPTS = 3;
+const DEFAULT_COLD_START_BACKOFF_MS = 500;
 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);
@@ -19,13 +23,85 @@ const toRequest = (input, init, port) => {
   }
   return request;
 };
-const sendingHandle = (send, port) => {
+const sleep = async (ms) => {
+  if (ms <= 0) {
+    return;
+  }
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+};
+const COLD_START_ERROR_PATTERN = /no container instance|not listening|try again later|rate.?limit|provision/i;
+const COLD_START_NO_INSTANCE_BODY = "no Container instance available";
+const COLD_START_START_FAILURE_BODY = "Failed to start container:";
+const COLD_START_SENTINEL_SCAN_BYTES = 1024;
+const readBodyPrefix = async (response) => {
+  const stream = response.clone().body;
+  if (stream === null) {
+    return "";
+  }
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  try {
+    while (text.length < COLD_START_SENTINEL_SCAN_BYTES) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    await reader.cancel();
+  }
+  return text;
+};
+const isColdStartError = (error) => error instanceof Error && COLD_START_ERROR_PATTERN.test(error.message);
+const isColdStartTransient = async (response) => {
+  if (response.status === 429) {
+    return true;
+  }
+  if (response.status !== 500 && response.status !== 503) {
+    return false;
+  }
+  try {
+    const body = await readBodyPrefix(response);
+    return body.includes(COLD_START_NO_INSTANCE_BODY) || body.startsWith(COLD_START_START_FAILURE_BODY);
+  } catch {
+    return false;
+  }
+};
+const coldStartRetryingHandle = (send, options = {}, port) => {
+  const attempts = Math.max(1, options.attempts ?? DEFAULT_COLD_START_ATTEMPTS);
+  const baseBackoff = options.backoffMs ?? DEFAULT_COLD_START_BACKOFF_MS;
+  const maxBackoff = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
   return {
-    fetch: async (input, init) => send(toRequest(input, init, port)),
-    port: (targetPort) => sendingHandle(send, targetPort)
+    fetch: async (input, init) => {
+      const totalAttempts = typeof input === "string" ? attempts : 1;
+      let lastError;
+      for (let attempt = 0; attempt < totalAttempts; attempt += 1) {
+        const isLastAttempt = attempt === totalAttempts - 1;
+        if (attempt > 0) {
+          await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
+        }
+        try {
+          const response = await send(toRequest(input, init, port));
+          if (isLastAttempt || !await isColdStartTransient(response)) {
+            return response;
+          }
+        } catch (error) {
+          lastError = error;
+          if (isLastAttempt || !isColdStartError(error)) {
+            throw error;
+          }
+        }
+      }
+      throw lastError instanceof Error ? lastError : new Error("ctx.containers: cold-start retry exhausted");
+    },
+    port: (targetPort) => coldStartRetryingHandle(send, options, targetPort)
   };
 };
-const handleFor = (namespace, instanceName) => sendingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request));
+const handleFor = (namespace, instanceName, options) => coldStartRetryingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request), options);
 const lifecycleCall = async (stub, method, binding, argument) => {
   const rpc = stub[method];
   if (typeof rpc !== "function") {
@@ -43,15 +119,15 @@ const egressControlsFor = (stub, binding) => {
     setDenied: async (hosts) => lifecycleCall(stub(), "setDeniedHosts", binding, [...hosts])
   };
 };
-const instanceHandleFor = (namespace, spec, instanceName) => {
+const instanceHandleFor = (namespace, spec, instanceName, options) => {
   const stub = () => namespace.get(namespace.idFromName(instanceName));
   return {
-    ...sendingHandle(async (request) => stub().fetch(request)),
+    ...coldStartRetryingHandle(async (request) => stub().fetch(request), options),
     destroy: async () => lifecycleCall(stub(), "destroy", spec.binding),
     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),
+    start: async (startOptions) => lifecycleCall(stub(), "start", spec.binding, startOptions),
     stop: async (signal) => lifecycleCall(stub(), "stop", spec.binding, signal)
   };
 };
@@ -59,14 +135,6 @@ const randomPoolName = (size) => (
   // eslint-disable-next-line sonarjs/pseudo-random -- load-balancing pick across interchangeable instances, not a security decision
   `pool-${String(Math.floor(Math.random() * size))}`
 );
-const sleep = async (ms) => {
-  if (ms <= 0) {
-    return;
-  }
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-};
 const retryOnServerError = (response) => response.status >= 500;
 const poolHandleFor = (namespace, spec, options = {}, port) => {
   const size = options.size ?? spec.maxInstances ?? DEFAULT_POOL_SIZE;
@@ -98,14 +166,15 @@ const poolHandleFor = (namespace, spec, options = {}, port) => {
 };
 const accessorFor = (namespace, spec) => {
   return {
-    any: (count) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE)),
-    get: (name) => instanceHandleFor(namespace, spec, name),
+    any: (count, options) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE), options),
+    get: (name, options) => instanceHandleFor(namespace, spec, name, options),
     pool: (options) => poolHandleFor(namespace, spec, options)
   };
 };
 const missingBindingAccessor = (spec) => {
   const fail = () => {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `ctx.containers.${spec.exportName}: no "${spec.binding}" Durable Object binding found. Run \`lunora dev\` (or \`lunora deploy\`) to reconcile wrangler.jsonc, and make sure the worker entry re-exports the generated container classes.`
     );
   };
@@ -146,10 +215,11 @@ const createContainerTestContext = (handlers) => {
     containers[exportName] = {
       // `.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")
+      // simulate the random-pick or retry/backoff the real pool/cold-start
+      // path does (`attempts: 1` keeps a handler's own 5xx from looping).
+      any: () => handleFor(namespace, "pool-0", { attempts: 1 }),
+      get: (name) => instanceHandleFor(namespace, spec, name, { attempts: 1 }),
+      pool: () => handleFor(namespace, "pool-0", { attempts: 1 })
     };
   }
   return containers;

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

@@ -203,6 +203,22 @@ interface ContainerConfig {
   */
   secrets?: ReadonlyArray<string>;
   /**
+  * Cloudflare **Secrets Store** secrets forwarded into the container's
+  * environment, as a map of *container env-var name → Worker Secrets Store
+  * binding name*. Each binding is resolved with its async `.get()` the first
+  * time the instance starts, then injected as that env var — e.g.
+  * `{ STRIPE_KEY: "STRIPE_SECRET" }` runs `env.STRIPE_SECRET.get()` and sets
+  * `STRIPE_KEY` inside the container. Unlike {@link ContainerConfig.secrets}
+  * (plain Worker text secrets), this pulls from a `secrets_store_secrets`
+  * binding. A name already used by `env`/`secrets` is rejected at authoring
+  * time; a missing binding or unreadable value fails the start. Applies
+  * to the default start (the `ctx.containers` proxy path and a bare
+  * `start()`); a per-instance `start({ envVars })` replaces the env set
+  * wholesale, as it does for `env`/`secrets`. (Upstream
+  * cloudflare/containers#96.)
+  */
+  secretsStore?: Readonly<Record<string, string>>;
+  /**
   * Idle timeout after which the instance is put to sleep, e.g. `"5m"`,
   * `"30s"`, or a number of seconds. Cloudflare's default is `"10m"`.
   */
@@ -231,4 +247,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, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };
+export { BuildImageSource as B, ContainerConfig as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerDefinition 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-DAOLRiZQ.d.ts → types.d-BlNwNY44.d.ts}

@@ -203,6 +203,22 @@ interface ContainerConfig {
   */
   secrets?: ReadonlyArray<string>;
   /**
+  * Cloudflare **Secrets Store** secrets forwarded into the container's
+  * environment, as a map of *container env-var name → Worker Secrets Store
+  * binding name*. Each binding is resolved with its async `.get()` the first
+  * time the instance starts, then injected as that env var — e.g.
+  * `{ STRIPE_KEY: "STRIPE_SECRET" }` runs `env.STRIPE_SECRET.get()` and sets
+  * `STRIPE_KEY` inside the container. Unlike {@link ContainerConfig.secrets}
+  * (plain Worker text secrets), this pulls from a `secrets_store_secrets`
+  * binding. A name already used by `env`/`secrets` is rejected at authoring
+  * time; a missing binding or unreadable value fails the start. Applies
+  * to the default start (the `ctx.containers` proxy path and a bare
+  * `start()`); a per-instance `start({ envVars })` replaces the env set
+  * wholesale, as it does for `env`/`secrets`. (Upstream
+  * cloudflare/containers#96.)
+  */
+  secretsStore?: Readonly<Record<string, string>>;
+  /**
   * Idle timeout after which the instance is put to sleep, e.g. `"5m"`,
   * `"30s"`, or a number of seconds. Cloudflare's default is `"10m"`.
   */
@@ -231,4 +247,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, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };
+export { BuildImageSource as B, ContainerConfig as C, NormalizedContainerImage as N, RegistryImageSource as R, ContainerDefinition 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.4",
+  "version": "1.0.0-alpha.6",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cloudflare/containers": "^0.3.7"
+    "@lunora/errors": "1.0.0-alpha.1"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"