@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/stack-deploy-config.mjs

@@ -0,0 +1,313 @@
+// stack-deploy-config.mjs - the ONE reader of `environments.<env>.deploy` in .starcistacks/application-stacks.yaml (R294).
+// `starci app stack ...` (packages/hfs/stack) normalises the block through it and `starci app check` (rules/stacks-deploy.mjs)
+// judges the same block through it, so the verbs and the rule can never disagree. Pure given the block and a probe of the app tree.
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
+import { list } from '../lib/list.mjs';
+import { normalizeIngress } from './stack-ingress-config.mjs';
+
+export const DEPLOY_CONFIG_CODE = 'STACKS_DEPLOY_CONFIG_INVALID';
+
+export const NAME = /^[a-z][a-z0-9-]*$/u;
+export const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const VOLUME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/u;
+const HOST_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const REMOTE_BASE = /^\/[A-Za-z0-9._/-]+$/u;
+const HTTP_URL = /^https?:\/\/[^\s]+$/u;
+const PINNED_HELPER_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
+const UPPER_ENV = KEY;
+
+const FIELDS = {
+  deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
+  remote: ['host', 'releasesBase', 'sealed'],
+  sealed: ['ops', 'sshKey', 'knownHosts'],
+  image: ['app', 'buildArgs'],
+  buildArgs: ['values', 'sealed'],
+  secrets: ['grants', 'settings'],
+  grant: ['service', 'filePointers', 'from'],
+  source: ['member', 'keys', 'required', 'fill'],
+  settings: ['member', 'keys'],
+  environment: ['files', 'values', 'settings'],
+  setting: ['key', 'default'],
+  config: ['name', 'file', 'env'],
+  verify: ['http', 'exec'],
+  http: ['name', 'url', 'method', 'body', 'status', 'json', 'contains', 'retry'],
+  exec: ['name', 'service', 'command', 'stdout'],
+  jobs: ['service', 'command'],
+  task: ['service', 'command'],
+  backup: ['image', 'keepDays', 'dir', 'volumes'],
+  backupVolume: ['name', 'volume'],
+  registry: ['host', 'visibility'],
+};
+
+const text = (value) => typeof value === 'string' && value.length > 0;
+
+const nameField = (c, at, value, pattern = NAME) => patternField(c, at, value, pattern);
+
+function stringList(c, at, value, itemPattern, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value) || (nonEmpty && value.length === 0)) { c.problem(at, 'must be a list'); return []; }
+  value.forEach((item, index) => { if (typeof item !== 'string' || !itemPattern.test(item)) c.problem(`${at}[${index}]`, `must match ${itemPattern}`); });
+  return value;
+}
+
+function remote(c, block) {
+  if (block === undefined) return { host: 'vps', releasesBase: null, sealed: null };
+  if (!closedFields(c, 'deploy.remote', block, FIELDS.remote)) return { host: 'vps', releasesBase: null, sealed: null };
+  if (block.host !== undefined) nameField(c, 'deploy.remote.host', block.host, HOST_ALIAS);
+  if (block.releasesBase !== undefined && (!REMOTE_BASE.test(String(block.releasesBase)) || String(block.releasesBase).includes('..')))
+    c.problem('deploy.remote.releasesBase', 'must be an absolute path without ..');
+  let sealed = null;
+  if (block.sealed !== undefined && closedFields(c, 'deploy.remote.sealed', block.sealed, FIELDS.sealed)) {
+    for (const key of FIELDS.sealed) nameField(c, `deploy.remote.sealed.${key}`, block.sealed[key]);
+    sealed = { ...block.sealed };
+  }
+  return { host: block.host ?? 'vps', releasesBase: block.releasesBase ?? null, sealed };
+}
+
+function imageBuildArgs(c, at, block, members) {
+  const out = { values: {}, sealed: null };
+  if (block === undefined) return out;
+  if (!closedFields(c, at, block, FIELDS.buildArgs)) return out;
+  for (const [key, value] of Object.entries(block.values ?? {})) {
+    if (!KEY.test(key) || typeof value !== 'string') c.problem(`${at}.values.${key}`, 'must be KEY: "string"');
+    else out.values[key] = value;
+  }
+  if (block.sealed !== undefined && closedFields(c, `${at}.sealed`, block.sealed, FIELDS.settings)) {
+    memberRef(c, `${at}.sealed.member`, block.sealed.member, members);
+    out.sealed = { member: block.sealed.member, keys: stringList(c, `${at}.sealed.keys`, block.sealed.keys, KEY, { nonEmpty: true }) };
+  }
+  return out;
+}
+
+function memberRef(c, at, member, members) {
+  if (!nameField(c, at, member)) return;
+  if (members.size > 0 && !members.has(member)) c.problem(at, `sealed member ${member} has no .starcistacks/<env>/secrets/${member}.enc`);
+}
+
+function images(c, block, services, members) {
+  const out = {};
+  if (block === undefined) return out;
+  if (!plain(block)) { c.problem('deploy.images', 'must be a mapping of service to image'); return out; }
+  for (const [service, entry] of Object.entries(block)) {
+    const at = `deploy.images.${service}`;
+    nameField(c, at, service);
+    if (services.size > 0 && !services.has(service)) c.problem(at, `${service} is not a service of the stack source`);
+    if (!closedFields(c, at, entry, FIELDS.image)) continue;
+    nameField(c, `${at}.app`, entry.app);
+    out[service] = { app: entry.app, buildArgs: imageBuildArgs(c, `${at}.buildArgs`, entry.buildArgs, members) };
+  }
+  return out;
+}
+
+function sourceEntry(c, at, entry, members) {
+  if (!closedFields(c, at, entry, FIELDS.source)) return null;
+  memberRef(c, `${at}.member`, entry.member, members);
+  const keys = entry.keys === undefined ? null : stringList(c, `${at}.keys`, entry.keys, KEY, { nonEmpty: true });
+  for (const flag of ['required', 'fill']) if (entry[flag] !== undefined && typeof entry[flag] !== 'boolean') c.problem(`${at}.${flag}`, 'must be true or false');
+  if (entry.required === true && keys === null) c.problem(`${at}.required`, 'needs an explicit keys list');
+  return { member: entry.member, keys, required: entry.required === true, fill: entry.fill === true };
+}
+
+function grants(c, block, services, members) {
+  const out = [];
+  list(block).forEach((grant, index) => {
+    const at = `deploy.secrets.grants[${index}]`;
+    if (!closedFields(c, at, grant, FIELDS.grant)) return;
+    nameField(c, `${at}.service`, grant.service);
+    if (services.size > 0 && !services.has(grant.service)) c.problem(`${at}.service`, `${grant.service} is not a service of the stack source`);
+    if (grant.filePointers !== undefined && typeof grant.filePointers !== 'boolean') c.problem(`${at}.filePointers`, 'must be true or false');
+    if (!Array.isArray(grant.from) || grant.from.length === 0) { c.problem(`${at}.from`, 'must list at least one sealed source'); return; }
+    const from = grant.from.map((entry, at2) => sourceEntry(c, `${at}.from[${at2}]`, entry, members)).filter(Boolean);
+    out.push({ service: grant.service, filePointers: grant.filePointers === true, from });
+  });
+  return out;
+}
+
+function secretSettings(c, block, members) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.secrets.settings', block, FIELDS.settings)) return null;
+  memberRef(c, 'deploy.secrets.settings.member', block.member, members);
+  return { member: block.member, keys: stringList(c, 'deploy.secrets.settings.keys', block.keys, KEY, { nonEmpty: true }) };
+}
+
+function secrets(c, block, services, members) {
+  if (block === undefined) return { grants: [], settings: null };
+  if (!closedFields(c, 'deploy.secrets', block, FIELDS.secrets)) return { grants: [], settings: null };
+  if (block.grants !== undefined && !Array.isArray(block.grants)) c.problem('deploy.secrets.grants', 'must be a list');
+  return { grants: grants(c, block.grants, services, members), settings: secretSettings(c, block.settings, members) };
+}
+
+function serviceEnvironment(c, at, entry, probe) {
+  const out = { files: [], values: {}, settings: {} };
+  if (!closedFields(c, at, entry, FIELDS.environment)) return out;
+  list(entry.files).forEach((file, index) => { treeFile(c, `${at}.files[${index}]`, file, probe); out.files.push(file); });
+  for (const [key, value] of Object.entries(entry.values ?? {})) {
+    if (!UPPER_ENV.test(key) || typeof value !== 'string') c.problem(`${at}.values.${key}`, 'must be KEY: "string"');
+    else out.values[key] = value;
+  }
+  for (const [key, setting] of Object.entries(entry.settings ?? {})) {
+    if (!UPPER_ENV.test(key)) { c.problem(`${at}.settings.${key}`, `the environment name must match ${UPPER_ENV}`); continue; }
+    if (!closedFields(c, `${at}.settings.${key}`, setting, FIELDS.setting) || !nameField(c, `${at}.settings.${key}.key`, setting.key, KEY)) continue;
+    out.settings[key] = { key: setting.key, default: setting.default === undefined ? null : String(setting.default) };
+  }
+  return out;
+}
+
+function environmentBlock(c, block, services, probe) {
+  const out = {};
+  if (block === undefined) return out;
+  if (!plain(block)) { c.problem('deploy.environment', 'must be a mapping of service to environment'); return out; }
+  for (const [service, entry] of Object.entries(block)) {
+    if (services.size > 0 && !services.has(service)) c.problem(`deploy.environment.${service}`, `${service} is not a service of the stack source`);
+    out[service] = serviceEnvironment(c, `deploy.environment.${service}`, entry, probe);
+  }
+  return out;
+}
+
+function configs(c, block, probe) {
+  const out = [];
+  list(block).forEach((entry, index) => {
+    const at = `deploy.configs[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.config)) return;
+    nameField(c, `${at}.name`, entry.name);
+    nameField(c, `${at}.env`, entry.env, KEY);
+    treeFile(c, `${at}.file`, entry.file, probe);
+    out.push({ name: entry.name, file: entry.file, env: entry.env });
+  });
+  const seen = new Set();
+  for (const entry of out) { if (seen.has(entry.name)) c.problem('deploy.configs', `config name ${entry.name} is declared twice`); seen.add(entry.name); }
+  return out;
+}
+
+function httpChecks(c, block) {
+  return list(block).flatMap((entry, index) => {
+    const at = `deploy.verify.http[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.http)) return [];
+    if (!text(entry.name)) c.problem(`${at}.name`, 'must be a non-empty string');
+    if (!HTTP_URL.test(String(entry.url))) c.problem(`${at}.url`, 'must be an http(s) URL');
+    if (entry.method !== undefined && !['GET', 'POST'].includes(entry.method)) c.problem(`${at}.method`, 'must be GET or POST');
+    if (entry.status !== undefined && !(Number.isInteger(entry.status) && entry.status >= 100 && entry.status <= 599)) c.problem(`${at}.status`, 'must be an HTTP status code');
+    if (entry.json !== undefined && !plain(entry.json)) c.problem(`${at}.json`, 'must be a mapping of expected fields');
+    return [{ name: entry.name, url: entry.url, method: entry.method ?? 'GET', body: entry.body ?? null, status: entry.status ?? 200, json: entry.json ?? null, contains: entry.contains ?? null, retry: entry.retry === true }];
+  });
+}
+
+function command(c, at, value) {
+  const items = stringList(c, at, value, ARGUMENT, { nonEmpty: true });
+  return items;
+}
+
+function execChecks(c, block, services) {
+  return list(block).flatMap((entry, index) => {
+    const at = `deploy.verify.exec[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.exec)) return [];
+    if (!text(entry.name)) c.problem(`${at}.name`, 'must be a non-empty string');
+    nameField(c, `${at}.service`, entry.service);
+    if (services.size > 0 && !services.has(entry.service)) c.problem(`${at}.service`, `${entry.service} is not a service of the stack source`);
+    if (entry.stdout !== undefined) try { new RegExp(entry.stdout, 'u'); } catch { c.problem(`${at}.stdout`, 'must be a valid regular expression'); }
+    return [{ name: entry.name, service: entry.service, command: command(c, `${at}.command`, entry.command), stdout: entry.stdout ?? null }];
+  });
+}
+
+function verify(c, block, services) {
+  if (block === undefined) return { http: [], exec: [] };
+  if (!closedFields(c, 'deploy.verify', block, FIELDS.verify)) return { http: [], exec: [] };
+  return { http: httpChecks(c, block.http), exec: execChecks(c, block.exec, services) };
+}
+
+function jobs(c, block, services) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.jobs', block, FIELDS.jobs)) return null;
+  nameField(c, 'deploy.jobs.service', block.service);
+  if (services.size > 0 && !services.has(block.service)) c.problem('deploy.jobs.service', `${block.service} is not a service of the stack source`);
+  return { service: block.service, command: command(c, 'deploy.jobs.command', block.command) };
+}
+
+const TASK_NAME = /^[a-z][a-z0-9-]{0,40}$/u;
+
+/** The one-off commands (`starci app stack task <name>`): name -> { service, command }, each run inside a running task of the service. */
+function tasks(c, block, services) {
+  if (block === undefined) return {};
+  if (!plain(block)) { c.problem('deploy.tasks', 'must be a mapping'); return {}; }
+  const out = {};
+  for (const [name, entry] of Object.entries(block)) {
+    const at = `deploy.tasks.${name}`;
+    if (!TASK_NAME.test(name)) c.problem(at, `the task name must match ${TASK_NAME}`);
+    if (!closedFields(c, at, entry, FIELDS.task)) continue;
+    nameField(c, `${at}.service`, entry.service);
+    if (services.size > 0 && !services.has(entry.service)) c.problem(`${at}.service`, `${entry.service} is not a service of the stack source`);
+    out[name] = { service: entry.service, command: command(c, `${at}.command`, entry.command) };
+  }
+  return out;
+}
+
+const REGISTRY_HOST = /^[a-z0-9][a-z0-9.-]*(?::[0-9]{1,5})?$/u;
+const VISIBILITY = ['public', 'private'];
+
+/** The image registry: host (default ghcr.io) and the visibility the app's packages are meant to have (default public, the canon scaffold writes it and the app owns it afterwards). */
+function registry(c, block) {
+  const fallback = { host: 'ghcr.io', visibility: 'public' };
+  if (block === undefined) return fallback;
+  if (!closedFields(c, 'deploy.registry', block, FIELDS.registry)) return fallback;
+  if (block.host !== undefined) patternField(c, 'deploy.registry.host', block.host, REGISTRY_HOST);
+  if (block.visibility !== undefined && !VISIBILITY.includes(block.visibility)) c.problem('deploy.registry.visibility', `must be one of ${VISIBILITY.join(', ')}`);
+  return { host: block.host ?? fallback.host, visibility: block.visibility ?? fallback.visibility };
+}
+
+function backup(c, block) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.backup', block, FIELDS.backup)) return null;
+  if (!PINNED_HELPER_IMAGE.test(String(block.image))) c.problem('deploy.backup.image', 'must be a digest-pinned image reference (no all-zero digest)');
+  if (block.keepDays !== undefined && !(Number.isInteger(block.keepDays) && block.keepDays >= 1 && block.keepDays <= 3650)) c.problem('deploy.backup.keepDays', 'must be a whole number of days from 1 to 3650');
+  if (block.dir !== undefined && (!REMOTE_BASE.test(String(block.dir)) || String(block.dir).includes('..'))) c.problem('deploy.backup.dir', 'must be an absolute path without ..');
+  const volumes = list(block.volumes).flatMap((entry, index) => {
+    const at = `deploy.backup.volumes[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.backupVolume)) return [];
+    nameField(c, `${at}.name`, entry.name);
+    nameField(c, `${at}.volume`, entry.volume, VOLUME);
+    return [{ name: entry.name, volume: entry.volume }];
+  });
+  if (volumes.length === 0) c.problem('deploy.backup.volumes', 'must list at least one volume');
+  return { image: block.image, keepDays: block.keepDays ?? 14, dir: block.dir ?? null, volumes };
+}
+
+function ingress(c, block, probe) {
+  if (block === undefined) return null;
+  const result = normalizeIngress(block, { probe });
+  for (const item of result.problems) c.problem(item.at, item.message);
+  return result.ingress;
+}
+
+/**
+ * Validates and normalises one `deploy` block.
+ *   probe.exists(rel)  does a file exist below .starcistacks/<env>/ ?
+ *   probe.services     the service names of the committed stack source (empty set = unknown, service references are not checked)
+ *   probe.members      the sealed member slugs of .starcistacks/<env>/secrets (empty set = unknown)
+ * Returns { config, problems } ; config is null when a problem was found.
+ */
+export function normalizeDeploy(block, { project, probe }) {
+  const c = collector();
+  if (!closedFields(c, 'deploy', block, FIELDS.deploy)) return { config: null, problems: c.problems };
+  const services = probe.services ?? new Set();
+  const members = probe.members ?? new Set();
+  if (block.stack !== undefined) nameField(c, 'deploy.stack', block.stack);
+  const config = {
+    stack: block.stack ?? project,
+    remote: remote(c, block.remote),
+    images: images(c, block.images, services, members),
+    volumes: block.volumes === undefined ? [] : stringList(c, 'deploy.volumes', block.volumes, VOLUME),
+    secrets: secrets(c, block.secrets, services, members),
+    environment: environmentBlock(c, block.environment, services, probe),
+    configs: configs(c, block.configs, probe),
+    passEnv: block.passEnv === undefined ? [] : stringList(c, 'deploy.passEnv', block.passEnv, KEY),
+    verify: verify(c, block.verify, services),
+    jobs: jobs(c, block.jobs, services),
+    tasks: tasks(c, block.tasks, services),
+    backup: backup(c, block.backup),
+    ingress: ingress(c, block.ingress, probe),
+    registry: registry(c, block.registry),
+  };
+  if (block.stack === undefined && !NAME.test(String(project))) c.problem('deploy.stack', `the stack name ${project} must match ${NAME}`);
+  return { config: c.problems.length === 0 ? config : null, problems: c.problems };
+}

package/runtime/scripts/hfs/stack-ingress-config.mjs

@@ -0,0 +1,237 @@
+// stack-ingress-config.mjs - the reader of `environments.<env>.deploy.ingress`: the SHARED host ingress (80/443) of the VPS. The ingress is
+// its own swarm stack (`name`) owning the attachable overlay and the host-mode ports; the app stack consumes it. External (non-swarm, plain
+// docker compose) tenants are reached over the overlay by a UNIQUE alias, or by a host address (`hostAddress`).
+// Pure given the block and a probe of the app tree. `normalizeDeploy` (stack-deploy-config.mjs) hooks it in as `config.ingress`;
+// `starci app stack ingress plan|attach|takeover` (packages/hfs/stack/ingress.mjs) consumes the normalised result.
+import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { NAME } from './stack-deploy-config.mjs';
+
+const DOCKER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/u;
+const REMOTE_PATH = /^\/[A-Za-z0-9._/-]+$/u;
+const DNS_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const DNS_HOST = new RegExp(String.raw`^${DNS_LABEL}(?:\.${DNS_LABEL})+$`, 'u');
+const PINNED_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const TRAEFIK_ARG = /^--[A-Za-z0-9][A-Za-z0-9.-]*(?:=[^\s]*)?$/u;
+const OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IPV4 = new RegExp(String.raw`^${OCTET}(?:\.${OCTET}){3}$`, 'u');
+const URL_PATH = /^\/[A-Za-z0-9._~%/-]*$/u;
+const REDIRECT_STATUS = [301, 302, 303, 307, 308];
+
+const FIELDS = {
+  ingress: ['name', 'image', 'args', 'network', 'acmeVolume', 'service', 'legacy', 'upstreams', 'routes', 'middlewares', 'verify', 'drop', 'redirects', 'backup', 'publish', 'takeover'],
+  legacy: ['dir', 'dynamicDir', 'container'],
+  upstream: ['name', 'hosts', 'container', 'hostAddress', 'port', 'aliases', 'middlewares'],
+  verify: ['host', 'path', 'status'],
+  redirect: ['host', 'to', 'status'],
+  backup: ['dir'],
+  publish: ['file', 'supersedes'],
+  takeover: ['gateSeconds', 'rehearsalPorts'],
+  ports: ['http', 'https'],
+};
+
+const closed = (c, at, value, allowed) => closedFields(c, at, value, allowed, 'ingress');
+const matching = patternField;
+
+function remotePath(c, at, value) {
+  if (typeof value !== 'string' || !REMOTE_PATH.test(value) || value.split('/').includes('..')) c.problem(at, 'must be an absolute path without ..');
+}
+
+function port(c, at, value) {
+  if (!(Number.isInteger(value) && value >= 1 && value <= 65535)) c.problem(at, 'must be a port from 1 to 65535');
+}
+
+function httpStatus(c, at, value) {
+  if (!(Number.isInteger(value) && value >= 100 && value <= 599)) c.problem(at, 'must be an HTTP status code');
+}
+
+function list(c, at, value, check) {
+  if (!Array.isArray(value) || value.length === 0) { c.problem(at, 'must be a non-empty list'); return []; }
+  value.forEach((item, index) => check(`${at}[${index}]`, item));
+  return value;
+}
+
+const names = (c, pattern) => (where, item) => { matching(c, where, item, pattern); };
+
+function legacy(c, block) {
+  if (!closed(c, 'deploy.ingress.legacy', block, FIELDS.legacy)) return null;
+  remotePath(c, 'deploy.ingress.legacy.dir', block.dir);
+  remotePath(c, 'deploy.ingress.legacy.dynamicDir', block.dynamicDir);
+  matching(c, 'deploy.ingress.legacy.container', block.container, DOCKER_NAME);
+  return { dir: block.dir, dynamicDir: block.dynamicDir, container: block.container };
+}
+
+/** An upstream is a container on the overlay (alias = the route target) or a host address (`hostAddress`), never both. */
+function target(c, at, entry) {
+  if ((entry.container === undefined) === (entry.hostAddress === undefined)) c.problem(at, 'declare exactly one of container and hostAddress');
+  if (entry.container !== undefined) matching(c, `${at}.container`, entry.container, DOCKER_NAME);
+  if (entry.hostAddress !== undefined) matching(c, `${at}.hostAddress`, entry.hostAddress, IPV4);
+  if (entry.hostAddress !== undefined && entry.aliases !== undefined) c.problem(`${at}.aliases`, 'a hostAddress upstream has no alias');
+  if (entry.container === undefined) return [];
+  return entry.aliases === undefined ? [entry.name] : list(c, `${at}.aliases`, entry.aliases, names(c, DOCKER_NAME));
+}
+
+function upstream(c, at, entry) {
+  if (!closed(c, at, entry, FIELDS.upstream)) return null;
+  matching(c, `${at}.name`, entry.name, NAME);
+  port(c, `${at}.port`, entry.port);
+  const aliases = target(c, at, entry);
+  // an attach-only upstream (a container the tenants' own route files reach, with no host of its own) declares no hosts
+  const hosts = entry.hosts === undefined ? [] : list(c, `${at}.hosts`, entry.hosts, names(c, DNS_HOST));
+  const middlewareNames = entry.middlewares === undefined ? [] : list(c, `${at}.middlewares`, entry.middlewares, names(c, NAME));
+  return {
+    name: entry.name, hosts, container: entry.container ?? null, hostAddress: entry.hostAddress ?? null, port: entry.port, aliases, middlewares: middlewareNames,
+  };
+}
+
+function duplicates(c, label, values, at) {
+  const seen = new Set();
+  for (const value of values) {
+    if (seen.has(value)) c.problem(at, `${label} ${value} is declared more than once`);
+    seen.add(value);
+  }
+}
+
+function upstreams(c, block) {
+  if (block === undefined) return [];
+  const out = list(c, 'deploy.ingress.upstreams', block, () => {}).map((entry, index) => upstream(c, `deploy.ingress.upstreams[${index}]`, entry)).filter(Boolean);
+  duplicates(c, 'upstream name', out.map((entry) => entry.name), 'deploy.ingress.upstreams');
+  duplicates(c, 'host', out.flatMap((entry) => entry.hosts), 'deploy.ingress.upstreams');
+  duplicates(c, 'alias (aliases must be unique on the shared overlay)', out.flatMap((entry) => entry.aliases), 'deploy.ingress.upstreams');
+  return out;
+}
+
+function middlewareMap(c, block) {
+  if (block === undefined) return {};
+  if (!plain(block)) { c.problem('deploy.ingress.middlewares', 'must be a mapping of name to middleware'); return {}; }
+  const out = {};
+  for (const [name, value] of Object.entries(block)) {
+    const at = `deploy.ingress.middlewares.${name}`;
+    if (!matching(c, at, name, NAME)) continue;
+    if (plain(value)) out[name] = value;
+    else c.problem(at, 'must be a mapping');
+  }
+  return out;
+}
+
+function referencedMiddlewares(c, ups, declared, routes) {
+  if (routes !== null) return;
+  ups.forEach((entry, index) => {
+    for (const name of entry.middlewares) {
+      if (!Object.hasOwn(declared, name)) c.problem(`deploy.ingress.upstreams[${index}].middlewares`, `middleware ${name} is not declared in deploy.ingress.middlewares`);
+    }
+  });
+}
+
+function verifyList(c, block) {
+  if (block === undefined) return [];
+  return list(c, 'deploy.ingress.verify', block, () => {}).flatMap((entry, index) => {
+    const at = `deploy.ingress.verify[${index}]`;
+    if (!closed(c, at, entry, FIELDS.verify)) return [];
+    matching(c, `${at}.host`, entry.host, DNS_HOST);
+    if (entry.path !== undefined) matching(c, `${at}.path`, entry.path, URL_PATH);
+    if (entry.status !== undefined) httpStatus(c, `${at}.status`, entry.status);
+    return [{ host: entry.host, path: entry.path ?? '/', status: entry.status ?? null }];
+  });
+}
+
+function dropList(c, block) {
+  return block === undefined ? [] : list(c, 'deploy.ingress.drop', block, names(c, DNS_HOST));
+}
+
+function redirects(c, block) {
+  if (block === undefined) return [];
+  return list(c, 'deploy.ingress.redirects', block, () => {}).flatMap((entry, index) => {
+    const at = `deploy.ingress.redirects[${index}]`;
+    if (!closed(c, at, entry, FIELDS.redirect)) return [];
+    matching(c, `${at}.host`, entry.host, DNS_HOST);
+    matching(c, `${at}.to`, entry.to, DNS_HOST);
+    if (entry.status !== undefined && !REDIRECT_STATUS.includes(entry.status)) c.problem(`${at}.status`, `must be one of ${REDIRECT_STATUS.join(', ')}`);
+    return [{ host: entry.host, to: entry.to, status: entry.status ?? 301 }];
+  });
+}
+
+function backup(c, block) {
+  if (block === undefined) return null;
+  if (!closed(c, 'deploy.ingress.backup', block, FIELDS.backup)) return null;
+  remotePath(c, 'deploy.ingress.backup.dir', block.dir);
+  return { dir: block.dir };
+}
+
+const ROUTE_FILE = /^[a-z][a-z0-9-]*.ya?ml$/u;
+
+/** Where the app's own routes file lands in the shared directory, and the generic old file names it replaces (both required when declared). */
+function publish(c, block) {
+  if (block === undefined) return null;
+  const at = 'deploy.ingress.publish';
+  if (!closed(c, at, block, FIELDS.publish)) return null;
+  matching(c, `${at}.file`, block.file, ROUTE_FILE);
+  const supersedes = list(c, `${at}.supersedes`, block.supersedes, (where, name) => {
+    if (matching(c, where, name, ROUTE_FILE) && name === block.file) c.problem(where, 'must differ from publish.file');
+  });
+  duplicates(c, 'superseded file', supersedes, `${at}.supersedes`);
+  return { file: block.file, supersedes };
+}
+
+const DEFAULT_REHEARSAL_PORTS = { http: 18080, https: 18443 };
+
+/** Alternate host ports of the rehearsal: valid ports, never the production 80 and 443, and different from each other. */
+function rehearsalPorts(c, block) {
+  const at = 'deploy.ingress.takeover.rehearsalPorts';
+  if (block === undefined) return { ...DEFAULT_REHEARSAL_PORTS };
+  if (!closed(c, at, block, FIELDS.ports)) return { ...DEFAULT_REHEARSAL_PORTS };
+  for (const key of FIELDS.ports) {
+    port(c, `${at}.${key}`, block[key]);
+    if ([80, 443].includes(block[key])) c.problem(`${at}.${key}`, 'must not be the production port 80 or 443');
+  }
+  if (block.http === block.https) c.problem(at, 'http and https must differ');
+  return { http: block.http, https: block.https };
+}
+
+function takeover(c, block) {
+  if (block === undefined) return { gateSeconds: 30, rehearsalPorts: { ...DEFAULT_REHEARSAL_PORTS } };
+  if (!closed(c, 'deploy.ingress.takeover', block, FIELDS.takeover)) return null;
+  const gate = block.gateSeconds ?? 30;
+  if (!(Number.isInteger(gate) && gate >= 1 && gate <= 300)) c.problem('deploy.ingress.takeover.gateSeconds', 'must be a whole number of seconds from 1 to 300');
+  return { gateSeconds: gate, rehearsalPorts: rehearsalPorts(c, block.rehearsalPorts) };
+}
+
+/**
+ * Validates and normalises one `deploy.ingress` block (undefined -> { ingress: null, problems: [] }).
+ *   probe.exists(rel)  does a file exist below .starcistacks/<env>/ ?
+ * Returns { ingress, problems }; ingress is null when a problem was found.
+ */
+export function normalizeIngress(block, { probe }) {
+  const c = collector();
+  if (block === undefined) return { ingress: null, problems: [] };
+  if (!closed(c, 'deploy.ingress', block, FIELDS.ingress)) return { ingress: null, problems: c.problems };
+  for (const key of ['name', 'service']) if (block[key] !== undefined) matching(c, `deploy.ingress.${key}`, block[key], NAME);
+  if (block.image !== undefined) matching(c, 'deploy.ingress.image', block.image, PINNED_IMAGE);
+  const args = block.args === undefined ? null : list(c, 'deploy.ingress.args', block.args, names(c, TRAEFIK_ARG));
+  matching(c, 'deploy.ingress.network', block.network, DOCKER_NAME);
+  matching(c, 'deploy.ingress.acmeVolume', block.acmeVolume, DOCKER_NAME);
+  if (block.routes !== undefined) treeFile(c, 'deploy.ingress.routes', block.routes, probe);
+  const ups = upstreams(c, block.upstreams);
+  const declared = middlewareMap(c, block.middlewares);
+  const routes = block.routes ?? null;
+  referencedMiddlewares(c, ups, declared, routes);
+  const ingress = {
+    name: block.name ?? 'ingress',
+    image: block.image ?? null,
+    args,
+    service: block.service ?? 'ingress',
+    network: block.network,
+    acmeVolume: block.acmeVolume,
+    legacy: legacy(c, block.legacy),
+    upstreams: ups,
+    routes,
+    middlewares: declared,
+    verify: verifyList(c, block.verify),
+    drop: dropList(c, block.drop),
+    redirects: redirects(c, block.redirects),
+    backup: backup(c, block.backup),
+    publish: publish(c, block.publish),
+    takeover: takeover(c, block.takeover),
+  };
+  return { ingress: c.problems.length === 0 ? ingress : null, problems: c.problems };
+}