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

package/dist/packem_shared/{containerBindingName-BGdSdFNA.mjs → containerBindingName-CWmEE_3Y.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("/");
@@ -49,6 +60,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)) {
@@ -61,6 +85,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`);
@@ -71,11 +96,83 @@ const assertValidEnvAndSecrets = (config) => {
       );
     }
   }
+  assertValidSecretsStore(config, envNames, secretNames);
+};
+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 +191,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 +212,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-BtzK5gJL.mjs

@@ -0,0 +1,225 @@
+const applyJurisdiction = (namespace, jurisdiction) => {
+  if (jurisdiction === void 0) {
+    return namespace;
+  }
+  if (typeof namespace.jurisdiction !== "function") {
+    throw new TypeError(
+      `@lunora/container: Durable Object namespace does not support jurisdiction("${jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
+    );
+  }
+  return namespace.jurisdiction(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);
+  if (port !== void 0) {
+    request.headers.set(TARGET_PORT_HEADER, String(port));
+  }
+  return request;
+};
+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) => {
+      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, 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") {
+    throw new TypeError(`ctx.containers: the "${binding}" container DO does not expose ${method}() — is @lunora/container/do up to date?`);
+  }
+  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, options) => {
+  const stub = () => namespace.get(namespace.idFromName(instanceName));
+  return {
+    ...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 (startOptions) => lifecycleCall(stub(), "start", spec.binding, startOptions),
+    stop: async (signal) => lifecycleCall(stub(), "stop", spec.binding, signal)
+  };
+};
+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 retryOnServerError = (response) => response.status >= 500;
+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;
+  const maxBackoff = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const shouldRetry = options.retryOn ?? retryOnServerError;
+  return {
+    fetch: async (input, init) => {
+      let lastError;
+      for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (attempt > 0) {
+          await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
+        }
+        const request = toRequest(input, init, port);
+        try {
+          const response = await namespace.get(namespace.idFromName(randomPoolName(size))).fetch(request);
+          if (attempt === attempts - 1 || !shouldRetry(response)) {
+            return response;
+          }
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      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) => {
+  return {
+    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(
+      `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.`
+    );
+  };
+  return { any: fail, get: fail, pool: fail };
+};
+const createContainerContext = (env, specs, jurisdiction) => {
+  const containers = {};
+  for (const spec of specs) {
+    const binding = env[spec.binding];
+    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec) : missingBindingAccessor(spec);
+  }
+  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 namespace = testNamespaceFor(handler);
+    const spec = { binding: `CONTAINER_${exportName.toUpperCase()}`};
+    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/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;
+};
+
+export { createContainerContext, createContainerTestContext };

package/dist/packem_shared/types.d-BlNwNY44.d.mts

@@ -0,0 +1,250 @@
+/**
+* Public configuration types for `@lunora/container`.
+*
+* Everything in this module is pure data — no Cloudflare runtime imports — so
+* it is safe to import from Node tooling (codegen, the config layer) as well
+* as from worker code.
+*/
+/** Named instance types Cloudflare Containers provides. */
+type NamedContainerInstanceType = "basic" | "lite" | "standard-1" | "standard-2" | "standard-3" | "standard-4";
+/**
+* A custom instance type. Cloudflare's bounds at the time of writing: up to
+* 4 vCPU, 12 GiB memory, 20 GB disk, ≥ 3 GiB memory per vCPU and ≤ 2 GB disk
+* per GiB memory. The config-layer validator enforces the documented ranges.
+*/
+interface CustomContainerInstanceType {
+  /** Disk in MB. Cloudflare's default is 2000 (2 GB). */
+  diskMb?: number;
+  /** Memory in MiB. Cloudflare's default is 256. */
+  memoryMib?: number;
+  /** vCPU count. Cloudflare's default is 0.0625 (1/16 vCPU). */
+  vcpu?: number;
+}
+type ContainerInstanceType = CustomContainerInstanceType | NamedContainerInstanceType;
+/** Rolling-deploy tuning for a container. */
+interface ContainerRollout {
+  /** Seconds an active instance runs before it's eligible for update (wrangler `rollout_active_grace_period`). */
+  gracePeriodSeconds?: number;
+  /** Percentage of instances updated per rollout step, 1–100 (wrangler `rollout_step_percentage`). */
+  stepPercentage?: number;
+}
+/**
+* A pre-built image pulled from a registry — the Cloudflare Registry, Docker
+* Hub, or Amazon ECR (the registries `wrangler deploy` supports). The
+* reference must be fully qualified, e.g. `docker.io/acme/transcoder:1.4`.
+*/
+interface RegistryImageSource {
+  registry: string;
+}
+/**
+* A Dockerfile-less build via [Railpack](https://railpack.com): point at a
+* source directory and `lunora deploy` builds an OCI image with Railpack
+* (needs a BuildKit instance) and pushes it to the Cloudflare Registry before
+* wrangler runs. Opt-in — the Dockerfile path is the zero-extra-deps default.
+*/
+interface BuildImageSource {
+  build: string;
+}
+/**
+* Where the container image comes from. A `string` is a **local path** —
+* either a directory containing a `Dockerfile` (normalized to
+* `<dir>/Dockerfile` with the directory as the build context) or a path to
+* 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*
+  * values use {@link ContainerConfig.env} / {@link ContainerConfig.secrets}.
+  * Ignored for a pre-built `{ registry }` image.
+  */
+  buildArgs?: Readonly<Record<string, string>>;
+  /**
+  * The port the container listens on. Worker → container requests target
+  * 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. 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;
+  /**
+  * Resource class for each instance: a named Cloudflare instance type or a
+  * custom `{ vcpu, memoryMib, diskMb }` object.
+  */
+  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()`.
+  */
+  maxInstances?: number;
+  /**
+  * Override for the wrangler `containers[].name` identifier. Defaults to
+  * wrangler's own default (worker name + class name + environment).
+  */
+  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
+  * update (wrangler `rollout_active_grace_period`).
+  */
+  rollout?: ContainerRollout;
+  /**
+  * Names of Worker secrets (from `wrangler secret` / `.dev.vars`) forwarded
+  * into the container's environment at instance start. Each declared name
+  * must exist on the Worker `env` — a missing one fails fast with a
+  * directed error instead of starting the container without it.
+  */
+  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"`.
+  */
+  sleepAfter?: number | string;
+}
+/**
+* The value `defineContainer` returns: the validated config plus a brand the
+* codegen discovery and the generated Container DO class key on.
+*/
+interface ContainerDefinition extends ContainerConfig {
+  /** Brand marking a value as a Lunora container definition. */
+  readonly isLunoraContainer: true;
+}
+/** A normalized image source, as written into `wrangler.jsonc`. */
+type NormalizedContainerImage = {
+  /** Build context directory (wrangler `image_build_context`). */
+  buildContext: string;
+  /** Path to the Dockerfile (wrangler `image`). */
+  dockerfilePath: string;
+  kind: "dockerfile";
+} | {
+  /** Railpack source directory built + pushed at deploy time. */
+  buildDir: string;
+  kind: "build";
+} | {
+  kind: "registry"; /** Fully-qualified image reference (wrangler `image`). */
+  reference: string;
+};
+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 };