@lunora/container 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/containerBindingName-BiTrAF1J.mjs

@@ -0,0 +1,224 @@
+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]$/;
+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("/");
+  return separatorIndex === -1 ? trimmed : trimmed.slice(separatorIndex + 1);
+};
+const dirname = (path) => {
+  const separatorIndex = path.lastIndexOf("/");
+  return separatorIndex === -1 ? "." : path.slice(0, separatorIndex) || "/";
+};
+const normalizeContainerImage = (image) => {
+  if (typeof image !== "string") {
+    if ("build" in image) {
+      const buildDirectory = image.build.endsWith("/") ? image.build.slice(0, -1) : image.build;
+      return { buildDir: buildDirectory, kind: "build" };
+    }
+    return { kind: "registry", reference: image.registry };
+  }
+  if (basename(image).startsWith("Dockerfile")) {
+    return { buildContext: dirname(image), dockerfilePath: image, kind: "dockerfile" };
+  }
+  const context = image.endsWith("/") ? image.slice(0, -1) : image;
+  return { buildContext: context, dockerfilePath: `${context}/Dockerfile`, kind: "dockerfile" };
+};
+const containerClassName = (exportName) => `${exportName.charAt(0).toUpperCase()}${exportName.slice(1)}Container`;
+const containerBindingName = (exportName) => `CONTAINER_${exportName.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toUpperCase()}`;
+const containerBuildTag = (exportName) => `lunora-${exportName.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g, "-").toLowerCase()}:build`;
+const assertValidImage = (image) => {
+  if (typeof image === "string") {
+    if (image.length === 0) {
+      throw new TypeError("defineContainer: `image` must be a non-empty path or a { registry } reference");
+    }
+    if (image.includes(":")) {
+      throw new TypeError(
+        `defineContainer: \`image\` string "${image}" looks like a registry reference — pass it as { registry: "${image}" } instead. Plain strings are local Dockerfile paths.`
+      );
+    }
+    return;
+  }
+  if ("build" in image) {
+    if (typeof image.build !== "string" || image.build.length === 0) {
+      throw new TypeError("defineContainer: `image.build` must be a non-empty source directory for Railpack to build");
+    }
+    return;
+  }
+  if (typeof image.registry !== "string" || image.registry.length === 0) {
+    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)) {
+      throw new TypeError(`defineContainer: env variable name "${name}" is not a valid environment variable name`);
+    }
+  }
+  for (const name of Object.keys(config.buildArgs ?? {})) {
+    if (!ENV_NAME_PATTERN.test(name)) {
+      throw new TypeError(`defineContainer: buildArg name "${name}" is not a valid environment variable name`);
+    }
+  }
+  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`);
+    }
+    if (envNames.has(secret)) {
+      throw new TypeError(
+        `defineContainer: "${secret}" is declared in both \`env\` and \`secrets\` — a secret would silently overwrite the static env value; pick one`
+      );
+    }
+  }
+  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) {
+    assertValidPort(config.defaultPort, "defaultPort");
+  }
+  const stepPercentage = config.rollout?.stepPercentage;
+  if (stepPercentage !== void 0 && (!Number.isInteger(stepPercentage) || stepPercentage < 1 || stepPercentage > 100)) {
+    throw new TypeError(`defineContainer: \`rollout.stepPercentage\` must be an integer in 1–100 (got ${String(stepPercentage)})`);
+  }
+  if (config.maxInstances !== void 0 && (!Number.isInteger(config.maxInstances) || config.maxInstances < 1)) {
+    throw new TypeError(`defineContainer: \`maxInstances\` must be a positive integer (got ${String(config.maxInstances)})`);
+  }
+  if (typeof config.instanceType === "string" && !NAMED_INSTANCE_TYPES.has(config.instanceType)) {
+    throw new TypeError(
+      `defineContainer: unknown \`instanceType\` "${config.instanceType}" — use one of ${[...NAMED_INSTANCE_TYPES].join(", ")}, or a custom { vcpu, memoryMib, diskMb } object`
+    );
+  }
+  if (typeof config.sleepAfter === "string") {
+    if (!SLEEP_AFTER_PATTERN.test(config.sleepAfter)) {
+      throw new TypeError(
+        `defineContainer: \`sleepAfter\` string "${config.sleepAfter}" must be a number of seconds followed by a unit, e.g. "30s", "5m", or "1h"`
+      );
+    }
+  } else if (config.sleepAfter !== void 0 && (!Number.isInteger(config.sleepAfter) || config.sleepAfter < 1)) {
+    throw new TypeError(
+      `defineContainer: \`sleepAfter\` must be a positive integer number of seconds or a duration string like "5m" (got ${String(config.sleepAfter)})`
+    );
+  }
+  assertValidHardTimeout(config.hardTimeout);
+  assertValidEnvAndSecrets(config);
+  assertValidContainerRuntimeFields(config);
+  return { ...config, isLunoraContainer: true };
+};
+const isContainerDefinition = (value) => typeof value === "object" && value !== null && value.isLunoraContainer === true;
+const resolveContainerEnvVariables = (definition, workerEnv, exportName) => {
+  const resolved = { ...definition.env };
+  for (const secret of definition.secrets ?? []) {
+    const value = workerEnv[secret];
+    if (typeof value !== "string") {
+      const label = exportName === void 0 ? "container" : `container "${exportName}"`;
+      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.`
+      );
+    }
+    resolved[secret] = value;
+  }
+  return resolved;
+};
+
+export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, parseDurationSeconds, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/packem_shared/createContainerContext-CIVzsY5m.mjs

@@ -0,0 +1,220 @@
+import { LunoraError } from '@lunora/errors';
+import { containerBindingName } from './containerBindingName-BiTrAF1J.mjs';
+import { a as applyJurisdiction } from './jurisdiction-CuPNcLDt.mjs';
+
+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) => {
+      const totalAttempts = typeof input === "string" ? attempts : 1;
+      let lastError;
+      for (let attempt = 0; attempt < totalAttempts; 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 === totalAttempts - 1 || !shouldRetry(response)) {
+            return response;
+          }
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      throw lastError instanceof Error ? lastError : new Error(`ctx.containers.${spec.exportName}.pool(): all ${String(totalAttempts)} 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 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.`
+    );
+  };
+  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: containerBindingName(exportName)};
+    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/jurisdiction-CuPNcLDt.mjs

@@ -0,0 +1,13 @@
+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);
+};
+
+export { applyJurisdiction as a };