@wtfalch/foundry 0.32.0 → 0.34.0

package/dist/plan/mail-relay.d.ts

@@ -0,0 +1,120 @@
+import type { DeclaredPlatform } from '../platform.js';
+import type { DeployHealthRuntime } from './deploy-health.js';
+import type { DraftStep } from './diff.js';
+import type { CoolifyPort } from './executor.js';
+/**
+ * The shared mail relay: one Postfix container that owns host port 25 and
+ * hands each message to the mail server that serves its recipient's domain,
+ * on the Docker network. One server address has one inbound mail port, so a
+ * company's own mail server cannot bind it; this container does, for all.
+ *
+ * It is a platform step (`coolify:app` keyed {@link PLATFORM_MAIL_RELAY_KEY}),
+ * planned only when `platform.mail.relay` is true. It mints no secret.
+ * Everything it knows reaches the container as env the step writes.
+ */
+export declare const PLATFORM_MAIL_RELAY_KEY = "platform:mail-relay";
+/** Fingerprint of the sorted routes and platform domains the last successful apply put live. */
+export declare const PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY = "mail_relay_routes_applied";
+/** The base image tag the last successful apply built the relay from. */
+export declare const PLATFORM_MAIL_RELAY_BASE_SCOPE_KEY = "mail_relay_base_applied";
+/** The org-applied-state key the company mail step records its server's SMTP address under (`<internal name>:25`). */
+export declare const OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY = "mail_smtp_internal";
+export declare const MAIL_RELAY_APP_NAME = "platform-mail-relay";
+/** One recipient domain and the mail server that receives it: `target` is `<internal name>:25`. */
+export interface MailRoute {
+    domain: string;
+    target: string;
+}
+/** Lower-cases and checks a recipient domain; `null` for anything that is not a plain DNS name. */
+export declare function normalizeMailDomain(domain: string): string | null;
+/** Lower-cases and checks `<host>:25`; `null` for whitespace, metacharacters, another port or no host. */
+export declare function normalizeMailTarget(target: string): string | null;
+/**
+ * The routes, checked and sorted by domain. `null` when any entry is invalid or
+ * one domain has two targets (a message could not know where to go).
+ */
+export declare function normalizeMailRoutes(routes: readonly MailRoute[]): MailRoute[] | null;
+/** The platform's own mail domains, checked, de-duplicated, sorted; `null` when any is invalid. */
+export declare function normalizeMailDomains(domains: readonly string[]): string[] | null;
+/**
+ * What the relay was last built to do, as one value. Order of the inputs does
+ * not matter; a changed target, a new route or a new platform domain does.
+ * Never empty, so a platform with no company route still records one.
+ */
+export declare function mailRelayFingerprint(routes: readonly MailRoute[], platformDomains: readonly string[]): string;
+/**
+ * The relay's container start script. It renders Postfix's config from env
+ * only and refuses to start on a value that is not a plain domain or host, so
+ * nothing from env reaches a config line unchecked. The relay accepts mail for
+ * the listed domains and nothing else (`reject_unauth_destination`), so it
+ * cannot be used to send to a third party.
+ *
+ * Env: `MAIL_RELAY_HOSTNAME`, `MAIL_RELAY_DEFAULT_TARGET` (the platform
+ * Stalwart, `<name>:25`), `MAIL_RELAY_ROUTES` (`domain=host:25`, comma
+ * separated), `MAIL_RELAY_PLATFORM_DOMAINS` (comma separated, delivered to the
+ * default target). `MAIL_RELAY_RENDER_ONLY=1` writes the files and stops, and
+ * `MAIL_RELAY_CONF_DIR` moves them; both are for tests.
+ */
+export declare const MAIL_RELAY_ENTRYPOINT = "#!/bin/sh\nset -eu\nset -f\nconf=\"${MAIL_RELAY_CONF_DIR:-/etc/postfix}\"\nfail() { echo \"mail relay: $1\" >&2; exit 1; }\nok_name() {\n  case \"$1\" in\n    ''|*[!a-z0-9.-]*|.*|*.|*..*|-*|*.-*|*-.*) return 1 ;;\n  esac\n  return 0\n}\nok_domain() { ok_name \"$1\" && case \"$1\" in *.*) return 0 ;; esac; return 1; }\nok_target() {\n  case \"$1\" in *:25) ;; *) return 1 ;; esac\n  ok_name \"${1%:25}\"\n}\nok_target \"${MAIL_RELAY_DEFAULT_TARGET:-}\" || fail \"MAIL_RELAY_DEFAULT_TARGET is not <host>:25\"\nok_name \"${MAIL_RELAY_HOSTNAME:-}\" || fail \"MAIL_RELAY_HOSTNAME is not a host name\"\n: > \"$conf/relay_domains\"\n: > \"$conf/transport\"\nIFS=','\nfor entry in ${MAIL_RELAY_ROUTES:-}; do\n  d=\"${entry%%=*}\"\n  t=\"${entry#*=}\"\n  ok_domain \"$d\" || fail \"a route domain is not a plain domain\"\n  ok_target \"$t\" || fail \"a route target is not <host>:25\"\n  printf '%s OK\\n' \"$d\" >> \"$conf/relay_domains\"\n  printf '%s smtp:[%s]:25\\n' \"$d\" \"${t%:25}\" >> \"$conf/transport\"\ndone\nfor d in ${MAIL_RELAY_PLATFORM_DOMAINS:-}; do\n  ok_domain \"$d\" || fail \"a platform domain is not a plain domain\"\n  printf '%s OK\\n' \"$d\" >> \"$conf/relay_domains\"\n  printf '%s smtp:[%s]:25\\n' \"$d\" \"${MAIL_RELAY_DEFAULT_TARGET%:25}\" >> \"$conf/transport\"\ndone\nunset IFS\ncat > \"$conf/main.cf\" <<CONF\nmyhostname = $MAIL_RELAY_HOSTNAME\nmyorigin = \\$myhostname\ninet_interfaces = all\ninet_protocols = ipv4\nmydestination =\nmynetworks = 127.0.0.0/8\nlocal_recipient_maps =\nalias_maps =\nalias_database =\nrelay_domains = texthash:$conf/relay_domains\ntransport_maps = texthash:$conf/transport\nrelay_recipient_maps =\nsmtpd_relay_restrictions = reject_unauth_destination\nsmtpd_recipient_restrictions = reject_unauth_destination\ndisable_vrfy_command = yes\nmaillog_file = /dev/stdout\nCONF\n[ \"${MAIL_RELAY_RENDER_ONLY:-}\" = \"1\" ] && exit 0\nexec postfix start-fg\n";
+/** The inline Dockerfile Coolify builds. The start script travels base64-encoded so no quoting can alter it. */
+export declare function mailRelayDockerfile(): string;
+/** The env the step writes; the only input the container reads. */
+export declare function mailRelayEnv(input: {
+    hostname: string;
+    defaultTarget: string;
+    routes: readonly MailRoute[];
+    platformDomains: readonly string[];
+}): Array<{
+    key: string;
+    value: string;
+    literal: boolean;
+}>;
+export declare const MAIL_RELAY_BLOCKED: {
+    readonly mailNotEnabled: "the platform's mail relay is blocked, not planned: the platform's mail server is not enabled";
+    readonly mailNotReady: "the platform's mail relay is blocked, not planned: the platform's mail server is neither applied nor planned";
+    readonly executorMissing: "the platform's mail relay is blocked, not planned: the host built the platform executor without its mail dependencies";
+    readonly invalidRoutes: "the platform's mail relay is blocked, not planned: a mail route or platform mail domain is not valid (a domain must be a plain DNS name, a target must be <host>:25, one domain needs one target)";
+};
+/**
+ * Plans the relay: nothing unless `mail.relay` is true. Planned when it was
+ * never applied, when the fingerprint of its routes differs from the recorded
+ * one, or when the base image pin changed. Blocked (reported, not planned) while
+ * the platform mail server is not applied, the executor cannot run it, or an
+ * input is invalid.
+ */
+export declare function planMailRelay(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>, input: {
+    routes: readonly MailRoute[];
+    platformDomains: readonly string[];
+    executorBlocked: string | undefined;
+    mailReady: boolean;
+}): {
+    step: DraftStep | null;
+    blocked: string | null;
+};
+export interface MailRelayDeps {
+    coolify: Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'findOrCreateEnvironment' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deployAndWait' | 'raw'>;
+    runtime?: DeployHealthRuntime;
+}
+/**
+ * Makes the relay true: finds or creates the app, sets its internal name and
+ * host port 25, writes env, and deploys when it was just created, its env or
+ * base changed, or it is not running (decided from the live app). The old
+ * container is stopped first, because two containers cannot both bind port 25.
+ * The routes fingerprint is recorded last, so a run that fails halfway leaves
+ * the step planned and the next apply repairs it. No secret exists here.
+ */
+export declare function provisionMailRelay(action: {
+    desired: Record<string, unknown>;
+}, context: {
+    recordedIds(): Readonly<Record<string, string>>;
+    recordScopeId(key: string, id: string): void;
+    persist?(): Promise<void>;
+}, deps: MailRelayDeps, input: {
+    projectUuid: string;
+    serverUuid: string;
+    hostname: string;
+    defaultTarget: string;
+    appScopeKey: string;
+}): Promise<{
+    resourceId: string;
+}>;

package/dist/plan/mail-relay.js

@@ -0,0 +1,323 @@
+import { createHash } from 'node:crypto';
+import { VERSIONS } from '../bootstrap/versions.js';
+import { waitForDeploymentFinished } from './deploy-health.js';
+import { commandHealthCheckSettings, tcpProbe } from './health-check-settings.js';
+/**
+ * The shared mail relay: one Postfix container that owns host port 25 and
+ * hands each message to the mail server that serves its recipient's domain,
+ * on the Docker network. One server address has one inbound mail port, so a
+ * company's own mail server cannot bind it; this container does, for all.
+ *
+ * It is a platform step (`coolify:app` keyed {@link PLATFORM_MAIL_RELAY_KEY}),
+ * planned only when `platform.mail.relay` is true. It mints no secret.
+ * Everything it knows reaches the container as env the step writes.
+ */
+export const PLATFORM_MAIL_RELAY_KEY = 'platform:mail-relay';
+/** Fingerprint of the sorted routes and platform domains the last successful apply put live. */
+export const PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY = 'mail_relay_routes_applied';
+/** The base image tag the last successful apply built the relay from. */
+export const PLATFORM_MAIL_RELAY_BASE_SCOPE_KEY = 'mail_relay_base_applied';
+/** The org-applied-state key the company mail step records its server's SMTP address under (`<internal name>:25`). */
+export const OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY = 'mail_smtp_internal';
+/** `executor.ts`'s `isRunningOrStarting`, restated: importing it would make this module and the planner import each other. */
+function isRunningOrStarting(status) {
+    if (!status)
+        return true;
+    return !status.startsWith('exited') && !status.startsWith('stopped');
+}
+export const MAIL_RELAY_APP_NAME = 'platform-mail-relay';
+const LABEL = '[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?';
+const DOMAIN_PATTERN = new RegExp(`^(${LABEL}\\.)+[a-z]{2,63}$`);
+const HOST_PATTERN = new RegExp(`^${LABEL}(\\.${LABEL})*$`);
+/** Lower-cases and checks a recipient domain; `null` for anything that is not a plain DNS name. */
+export function normalizeMailDomain(domain) {
+    const lower = domain.toLowerCase();
+    return lower.length <= 253 && DOMAIN_PATTERN.test(lower) ? lower : null;
+}
+/** Lower-cases and checks `<host>:25`; `null` for whitespace, metacharacters, another port or no host. */
+export function normalizeMailTarget(target) {
+    const lower = target.toLowerCase();
+    if (!lower.endsWith(':25'))
+        return null;
+    const host = lower.slice(0, -3);
+    return host.length <= 253 && HOST_PATTERN.test(host) ? lower : null;
+}
+/**
+ * The routes, checked and sorted by domain. `null` when any entry is invalid or
+ * one domain has two targets (a message could not know where to go).
+ */
+export function normalizeMailRoutes(routes) {
+    const byDomain = new Map();
+    for (const route of routes) {
+        const domain = normalizeMailDomain(route.domain);
+        const target = normalizeMailTarget(route.target);
+        if (!domain || !target)
+            return null;
+        const existing = byDomain.get(domain);
+        if (existing !== undefined && existing !== target)
+            return null;
+        byDomain.set(domain, target);
+    }
+    return [...byDomain.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([domain, target]) => ({ domain, target }));
+}
+/** The platform's own mail domains, checked, de-duplicated, sorted; `null` when any is invalid. */
+export function normalizeMailDomains(domains) {
+    const out = new Set();
+    for (const domain of domains) {
+        const checked = normalizeMailDomain(domain);
+        if (!checked)
+            return null;
+        out.add(checked);
+    }
+    return [...out].sort();
+}
+/**
+ * What the relay was last built to do, as one value. Order of the inputs does
+ * not matter; a changed target, a new route or a new platform domain does.
+ * Never empty, so a platform with no company route still records one.
+ */
+export function mailRelayFingerprint(routes, platformDomains) {
+    const sortedRoutes = normalizeMailRoutes(routes) ?? [];
+    const sortedDomains = normalizeMailDomains(platformDomains) ?? [];
+    return createHash('sha256')
+        .update(JSON.stringify([sortedRoutes.map((r) => [r.domain, r.target]), sortedDomains]))
+        .digest('hex');
+}
+/**
+ * The relay's container start script. It renders Postfix's config from env
+ * only and refuses to start on a value that is not a plain domain or host, so
+ * nothing from env reaches a config line unchecked. The relay accepts mail for
+ * the listed domains and nothing else (`reject_unauth_destination`), so it
+ * cannot be used to send to a third party.
+ *
+ * Env: `MAIL_RELAY_HOSTNAME`, `MAIL_RELAY_DEFAULT_TARGET` (the platform
+ * Stalwart, `<name>:25`), `MAIL_RELAY_ROUTES` (`domain=host:25`, comma
+ * separated), `MAIL_RELAY_PLATFORM_DOMAINS` (comma separated, delivered to the
+ * default target). `MAIL_RELAY_RENDER_ONLY=1` writes the files and stops, and
+ * `MAIL_RELAY_CONF_DIR` moves them; both are for tests.
+ */
+export const MAIL_RELAY_ENTRYPOINT = `#!/bin/sh
+set -eu
+set -f
+conf="\${MAIL_RELAY_CONF_DIR:-/etc/postfix}"
+fail() { echo "mail relay: $1" >&2; exit 1; }
+ok_name() {
+  case "$1" in
+    ''|*[!a-z0-9.-]*|.*|*.|*..*|-*|*.-*|*-.*) return 1 ;;
+  esac
+  return 0
+}
+ok_domain() { ok_name "$1" && case "$1" in *.*) return 0 ;; esac; return 1; }
+ok_target() {
+  case "$1" in *:25) ;; *) return 1 ;; esac
+  ok_name "\${1%:25}"
+}
+ok_target "\${MAIL_RELAY_DEFAULT_TARGET:-}" || fail "MAIL_RELAY_DEFAULT_TARGET is not <host>:25"
+ok_name "\${MAIL_RELAY_HOSTNAME:-}" || fail "MAIL_RELAY_HOSTNAME is not a host name"
+: > "$conf/relay_domains"
+: > "$conf/transport"
+IFS=','
+for entry in \${MAIL_RELAY_ROUTES:-}; do
+  d="\${entry%%=*}"
+  t="\${entry#*=}"
+  ok_domain "$d" || fail "a route domain is not a plain domain"
+  ok_target "$t" || fail "a route target is not <host>:25"
+  printf '%s OK\\n' "$d" >> "$conf/relay_domains"
+  printf '%s smtp:[%s]:25\\n' "$d" "\${t%:25}" >> "$conf/transport"
+done
+for d in \${MAIL_RELAY_PLATFORM_DOMAINS:-}; do
+  ok_domain "$d" || fail "a platform domain is not a plain domain"
+  printf '%s OK\\n' "$d" >> "$conf/relay_domains"
+  printf '%s smtp:[%s]:25\\n' "$d" "\${MAIL_RELAY_DEFAULT_TARGET%:25}" >> "$conf/transport"
+done
+unset IFS
+cat > "$conf/main.cf" <<CONF
+myhostname = $MAIL_RELAY_HOSTNAME
+myorigin = \\$myhostname
+inet_interfaces = all
+inet_protocols = ipv4
+mydestination =
+mynetworks = 127.0.0.0/8
+local_recipient_maps =
+alias_maps =
+alias_database =
+relay_domains = texthash:$conf/relay_domains
+transport_maps = texthash:$conf/transport
+relay_recipient_maps =
+smtpd_relay_restrictions = reject_unauth_destination
+smtpd_recipient_restrictions = reject_unauth_destination
+disable_vrfy_command = yes
+maillog_file = /dev/stdout
+CONF
+[ "\${MAIL_RELAY_RENDER_ONLY:-}" = "1" ] && exit 0
+exec postfix start-fg
+`;
+/** The inline Dockerfile Coolify builds. The start script travels base64-encoded so no quoting can alter it. */
+export function mailRelayDockerfile() {
+    const script = Buffer.from(MAIL_RELAY_ENTRYPOINT, 'utf8').toString('base64');
+    return [
+        `FROM alpine:${VERSIONS.alpine}`,
+        `RUN apk add --no-cache postfix && echo ${script} | base64 -d > /entrypoint.sh && chmod +x /entrypoint.sh`,
+        'EXPOSE 25',
+        'ENTRYPOINT ["/entrypoint.sh"]',
+        '',
+    ].join('\n');
+}
+/** The env the step writes; the only input the container reads. */
+export function mailRelayEnv(input) {
+    return [
+        { key: 'MAIL_RELAY_HOSTNAME', value: input.hostname },
+        { key: 'MAIL_RELAY_DEFAULT_TARGET', value: input.defaultTarget },
+        {
+            key: 'MAIL_RELAY_ROUTES',
+            value: input.routes.map((r) => `${r.domain}=${r.target}`).join(','),
+        },
+        { key: 'MAIL_RELAY_PLATFORM_DOMAINS', value: input.platformDomains.join(',') },
+    ].map((e) => ({ ...e, literal: true }));
+}
+export const MAIL_RELAY_BLOCKED = {
+    mailNotEnabled: "the platform's mail relay is blocked, not planned: the platform's mail server is not enabled",
+    mailNotReady: "the platform's mail relay is blocked, not planned: the platform's mail server is neither applied nor planned",
+    executorMissing: "the platform's mail relay is blocked, not planned: the host built the platform executor without its mail dependencies",
+    invalidRoutes: "the platform's mail relay is blocked, not planned: a mail route or platform mail domain is not valid (a domain must be a plain DNS name, a target must be <host>:25, one domain needs one target)",
+};
+/**
+ * Plans the relay: nothing unless `mail.relay` is true. Planned when it was
+ * never applied, when the fingerprint of its routes differs from the recorded
+ * one, or when the base image pin changed. Blocked (reported, not planned) while
+ * the platform mail server is not applied, the executor cannot run it, or an
+ * input is invalid.
+ */
+export function planMailRelay(platform, recordedIds, input) {
+    if (platform.mail.relay !== true)
+        return { step: null, blocked: null };
+    if (!platform.mail.enabled)
+        return { step: null, blocked: MAIL_RELAY_BLOCKED.mailNotEnabled };
+    if (input.executorBlocked)
+        return { step: null, blocked: input.executorBlocked };
+    if (!input.mailReady)
+        return { step: null, blocked: MAIL_RELAY_BLOCKED.mailNotReady };
+    const routes = normalizeMailRoutes(input.routes);
+    const platformDomains = normalizeMailDomains(input.platformDomains);
+    if (!routes || !platformDomains)
+        return { step: null, blocked: MAIL_RELAY_BLOCKED.invalidRoutes };
+    const fingerprint = mailRelayFingerprint(routes, platformDomains);
+    const applied = Boolean(recordedIds[`coolify:app:${PLATFORM_MAIL_RELAY_KEY}`]);
+    if (applied &&
+        recordedIds[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY] === fingerprint &&
+        recordedIds[PLATFORM_MAIL_RELAY_BASE_SCOPE_KEY] === VERSIONS.alpine) {
+        return { step: null, blocked: null };
+    }
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_MAIL_RELAY_KEY,
+                desired: { routes, platformDomains, fingerprint },
+            },
+            step: {
+                description: applied
+                    ? `redeploy the shared mail relay with ${routes.length} company route${routes.length === 1 ? '' : 's'}`
+                    : `provision the shared mail relay on port 25 with ${routes.length} company route${routes.length === 1 ? '' : 's'}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * Makes the relay true: finds or creates the app, sets its internal name and
+ * host port 25, writes env, and deploys when it was just created, its env or
+ * base changed, or it is not running (decided from the live app). The old
+ * container is stopped first, because two containers cannot both bind port 25.
+ * The routes fingerprint is recorded last, so a run that fails halfway leaves
+ * the step planned and the next apply repairs it. No secret exists here.
+ */
+export async function provisionMailRelay(action, context, deps, input) {
+    const routes = normalizeMailRoutes((action.desired.routes ?? []));
+    const platformDomains = normalizeMailDomains((action.desired.platformDomains ?? []));
+    const defaultTarget = normalizeMailTarget(input.defaultTarget);
+    if (!routes || !platformDomains || !defaultTarget) {
+        throw new Error('platform:mail-relay: a mail route, platform domain or default target is invalid');
+    }
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const recorded = context.recordedIds();
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    const { environment } = await deps.coolify.findOrCreateEnvironment(input.projectUuid, 'production');
+    const existing = await deps.coolify.findApplicationByName(MAIL_RELAY_APP_NAME, {
+        environmentIds: [environment.id],
+    });
+    let appId;
+    let running = false;
+    const justCreated = !existing;
+    if (existing) {
+        appId = existing.uuid;
+        running = isRunningOrStarting((await deps.coolify.getApplication(appId)).status);
+    }
+    else {
+        appId = (await deps.coolify.createDockerfileApplication({
+            project_uuid: input.projectUuid,
+            server_uuid: input.serverUuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: mailRelayDockerfile(),
+            name: MAIL_RELAY_APP_NAME,
+            description: 'Postfix relay that owns host port 25 and routes by recipient domain',
+            instant_deploy: false,
+        })).uuid;
+    }
+    await record(input.appScopeKey, appId);
+    const baseChanged = !justCreated && recorded[PLATFORM_MAIL_RELAY_BASE_SCOPE_KEY] !== VERSIONS.alpine;
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: MAIL_RELAY_APP_NAME,
+        ports_exposes: '25',
+        ports_mappings: '25:25',
+        // Postfix has no HTTP: a connect to port 25 on the loopback is the check.
+        ...commandHealthCheckSettings(tcpProbe('25')),
+        ...(baseChanged
+            ? { dockerfile: Buffer.from(mailRelayDockerfile(), 'utf8').toString('base64') }
+            : {}),
+    });
+    const envs = mailRelayEnv({
+        hostname: input.hostname,
+        defaultTarget,
+        routes,
+        platformDomains,
+    });
+    const live = new Map((await deps.coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    const envsChanged = envs.some((e) => live.get(e.key) !== e.value);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    if (justCreated || !running || envsChanged || baseChanged) {
+        if (!justCreated && running) {
+            await deps.coolify.raw('POST', `/applications/${appId}/stop`);
+            await waitForStopped(deps.coolify, appId, runtime, sleep);
+        }
+        await waitForDeploymentFinished(deps.coolify, appId, runtime, 'platform:mail-relay', 'the relay keeps its previous routes');
+    }
+    await record(PLATFORM_MAIL_RELAY_BASE_SCOPE_KEY, VERSIONS.alpine);
+    await record(PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, mailRelayFingerprint(routes, platformDomains));
+    return { resourceId: appId };
+}
+async function waitForStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (!status || !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:mail-relay: the relay app ${appId} did not stop within ${Math.round(timeout / 1000)}s; apply again`);
+        }
+        await sleep(interval);
+    }
+}

package/dist/plan/org-names.d.ts

@@ -0,0 +1,24 @@
+import { type DeclaredOrg } from '../org.js';
+/** Which side of an org a derived name belongs to: its own services or its hosting entries. */
+export type OrgNameSource = 'own' | 'hosting';
+/**
+ * Every container name, network alias, database, tunnel and bucket name that
+ * foundry derives for an org: its own-service names when it owns services,
+ * and its hosting-entry and database names.
+ */
+export declare function orgDerivedNames(org: Pick<DeclaredOrg, 'slug' | 'services' | 'hosting'>): {
+    name: string;
+    source: OrgNameSource;
+}[];
+/** Every name the platform's shared services take. */
+export declare function platformDerivedNames(): string[];
+export interface NameClash {
+    name: string;
+    /** The slug of the other org, or `platform`. */
+    other: string;
+    /** Which side of `org` holds the clashing name. */
+    source: OrgNameSource;
+}
+/** Every name `org` derives that another org or the platform also derives. */
+export declare function findNameClashes(org: Pick<DeclaredOrg, 'slug' | 'services' | 'hosting'>, others: readonly Pick<DeclaredOrg, 'slug' | 'services' | 'hosting'>[]): NameClash[];
+export declare function nameClashMessage(slug: string, clash: NameClash): string;

package/dist/plan/org-names.js

@@ -0,0 +1,52 @@
+import { ownsServices } from '../org.js';
+import { orgTarget, platformTarget } from './own-services.js';
+import { appNameFor } from './platform-diff.js';
+/**
+ * Every container name, network alias, database, tunnel and bucket name that
+ * foundry derives for an org: its own-service names when it owns services,
+ * and its hosting-entry and database names.
+ */
+export function orgDerivedNames(org) {
+    const names = [];
+    if (ownsServices(org)) {
+        const target = orgTarget(org);
+        for (const name of [...Object.values(target.names), ...Object.values(target.internal)]) {
+            names.push({ name, source: 'own' });
+        }
+    }
+    for (const entry of org.hosting.entries) {
+        names.push({ name: appNameFor(org, entry), source: 'hosting' });
+    }
+    if (org.hosting.entries.some((entry) => entry.database)) {
+        names.push({ name: `${org.slug}-db`, source: 'hosting' });
+    }
+    return names;
+}
+/** Every name the platform's shared services take. */
+export function platformDerivedNames() {
+    const target = platformTarget();
+    return [...Object.values(target.names), ...Object.values(target.internal)];
+}
+/** Every name `org` derives that another org or the platform also derives. */
+export function findNameClashes(org, others) {
+    const mine = orgDerivedNames(org);
+    const platform = new Set(platformDerivedNames());
+    const clashes = [];
+    for (const { name, source } of mine) {
+        if (platform.has(name))
+            clashes.push({ name, other: 'platform', source });
+    }
+    for (const other of others) {
+        if (other.slug === org.slug)
+            continue;
+        const theirs = new Set(orgDerivedNames(other).map((n) => n.name));
+        for (const { name, source } of mine) {
+            if (theirs.has(name))
+                clashes.push({ name, other: other.slug, source });
+        }
+    }
+    return clashes;
+}
+export function nameClashMessage(slug, clash) {
+    return `name '${clash.name}' is taken by both '${slug}' and '${clash.other}'`;
+}