@omnitron-dev/omnitron 0.2.0 → 0.3.0

package/dist/services/maintenance-lock.js

@@ -0,0 +1,316 @@
+/**
+ * The deployer's maintenance lock on a stack's gateway.
+ *
+ * A deployment stops and starts every app, swaps the frontend and runs the
+ * migrations — and it did all of that under whoever was using the platform.
+ * Nothing told them: a request that landed mid-restart failed as an outage
+ * would, a form sent into it was lost, and a tester's report described the
+ * deployment rather than the product. The gateway is the one component that
+ * stays up through all of it, so it holds the platform (daos
+ * `infra/nginx/lua/maintenance_check.lua`) while a key it reads exists:
+ *
+ *   omnitron:maintenance:notice  the warning, `noticeSeconds` ahead: open
+ *                                pages say «an update in N s»
+ *   omnitron:maintenance:deploy  the lock: every page, call and socket gets
+ *                                503 «being updated», administrators included
+ *
+ * It must never outlive the deployment by more than minutes. So the key is
+ * written with an expiry and RENEWED while this process lives: a deployer that
+ * dies — a laptop closed, a crash — stops renewing, and the gateway lets the
+ * platform go within `ttlSeconds`. Past `capSeconds` it is lifted even while
+ * the deployment runs: a stuck deployment is not a reason to keep everyone
+ * out for hours.
+ *
+ * Before lifting, the platform is asked THROUGH the gateway — the path a
+ * person's request takes — with a probe token only the lock's own key holds,
+ * rotated on every renewal; the gateway lets that token past only from its own
+ * loopback, only for GET `/` and `/api/<service>/health`. A platform that does
+ * not answer there keeps the lock, which then expires by itself.
+ *
+ * Everything runs on the node by `docker exec` over the deployer's SSH: the
+ * stack's Redis and gateway containers, named `<prefix>-redis` and
+ * `<prefix>-gateway`. A node without them — a first deployment — has nobody
+ * to hold, and the deployment goes on without the lock.
+ */
+import crypto from 'node:crypto';
+import { shellEscape } from '../shared/shell-escape.js';
+export const DEPLOY_KEY = 'omnitron:maintenance:deploy';
+export const NOTICE_KEY = 'omnitron:maintenance:notice';
+export const DEFAULT_MAINTENANCE_TIMING = {
+    noticeSeconds: 60,
+    etaSeconds: 180,
+    ttlSeconds: 600,
+    renewSeconds: 60,
+    capSeconds: 1800,
+    seenWithinMs: 8_000,
+    probeWithinMs: 60_000,
+};
+const sleepFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const token = () => crypto.randomBytes(24).toString('hex');
+const epoch = (ms) => Math.floor(ms / 1000);
+/**
+ * redis-cli in the stack's Redis container, in the gateway's database. A
+ * password, when the container has one, is read INSIDE the container — never
+ * put on a command line that `ps` on the node, or a log here, would show.
+ */
+export function redisCommand(site, args) {
+    const inner = '[ -n "${REDIS_PASSWORD:-}" ] && export REDISCLI_AUTH="$REDIS_PASSWORD"; ' +
+        `exec redis-cli --no-auth-warning -n ${site.db} ${args.map(shellEscape).join(' ')}`;
+    return `docker exec ${shellEscape(`${site.prefix}-redis`)} sh -c ${shellEscape(inner)}`;
+}
+/**
+ * A GET through the gateway, from inside its own container — the gateway's
+ * loopback, which is not the onion's socket, so a probe token is honoured;
+ * busybox wget exits non-zero on anything but 2xx.
+ */
+export function gatewayCommand(site, path, probe) {
+    const header = probe ? ` --header ${shellEscape(`X-Maintenance-Probe: ${probe}`)}` : '';
+    return `docker exec ${shellEscape(`${site.prefix}-gateway`)} wget -q -T 10 -O -${header} ${shellEscape(`http://127.0.0.1${path}`)}`;
+}
+export class MaintenanceLock {
+    site;
+    timing;
+    logger;
+    sleep;
+    probeToken = token();
+    timer = null;
+    lifted = false;
+    heldSince;
+    constructor(site, timing, logger, sleep, now) {
+        this.site = site;
+        this.timing = timing;
+        this.logger = logger;
+        this.sleep = sleep;
+        this.heldSince = now;
+    }
+    /**
+     * Warn, then hold. `null` when the node has no running gateway and Redis —
+     * nothing to hold, and nobody to warn — or when the lock could not be
+     * written; either way the deployment goes on, and the reason is logged.
+     */
+    static async open(site, logger, timing = DEFAULT_MAINTENANCE_TIMING, sleep = sleepFor) {
+        // Asked inside `try`, not with a `.catch` on what `run` returns: a runner
+        // that throws before it returns a promise went past the `.catch` and
+        // failed the whole deployment — ten cases in three courts whose fake
+        // deployer hands back no runner said «site.run is not a function» from
+        // 2026-09-29 (14d60961) on. A node that could not be asked has not said
+        // it has no gateway, so it is said differently; either way the deployment
+        // goes on unheld, which is this function's word.
+        let running;
+        try {
+            running = await site.run(`docker inspect -f '{{.Name}} {{.State.Running}}' ${shellEscape(`${site.prefix}-gateway`)} ${shellEscape(`${site.prefix}-redis`)} 2>/dev/null || true`);
+        }
+        catch (err) {
+            logger.warn({ prefix: site.prefix, err: err instanceof Error ? err.message : String(err) }, 'Could not ask the node for its gateway — deploying without a maintenance lock');
+            return null;
+        }
+        if (!/-gateway true\b/.test(running) || !/-redis true\b/.test(running)) {
+            logger.info({ prefix: site.prefix }, 'No running gateway and Redis on this node — deploying without a maintenance lock');
+            return null;
+        }
+        try {
+            if (timing.noticeSeconds > 0) {
+                const startsAt = epoch(Date.now()) + timing.noticeSeconds;
+                await site.run(redisCommand(site, [
+                    'SET',
+                    NOTICE_KEY,
+                    JSON.stringify({ startsAt, release: site.release }),
+                    'EX',
+                    String(timing.noticeSeconds + 120),
+                ]));
+                logger.info({ release: site.release, inSeconds: timing.noticeSeconds }, 'Maintenance announced to the platform');
+                await sleep(timing.noticeSeconds * 1000);
+            }
+            const lock = new MaintenanceLock(site, timing, logger, sleep, Date.now());
+            await lock.write();
+            await site.run(redisCommand(site, ['DEL', NOTICE_KEY]));
+            if (!(await lock.seen(true))) {
+                // The deployment goes on: refusing it over the lock would be worse
+                // than deploying without one. But it is said, because this is exactly
+                // how the lock failed before — written where the gateway did not look.
+                logger.error({ prefix: site.prefix, db: site.db }, 'The gateway does not see the maintenance lock — is its REDIS_DB the one written? Deploying unheld');
+            }
+            else {
+                logger.info({ release: site.release, db: site.db }, 'Maintenance: the platform is held');
+            }
+            lock.timer = setInterval(() => void lock.renew(), timing.renewSeconds * 1000);
+            lock.timer.unref?.();
+            return lock;
+        }
+        catch (err) {
+            logger.error({ err: err.message }, 'Could not set the maintenance lock — deploying without it');
+            await site.run(redisCommand(site, ['DEL', NOTICE_KEY, DEPLOY_KEY])).catch(() => undefined);
+            return null;
+        }
+    }
+    value() {
+        return JSON.stringify({
+            reason: 'deploy',
+            release: this.site.release,
+            since: epoch(this.heldSince),
+            eta: epoch(this.heldSince) + this.timing.etaSeconds,
+            probe: this.probeToken,
+        });
+    }
+    async write() {
+        await this.site.run(redisCommand(this.site, ['SET', DEPLOY_KEY, this.value(), 'EX', String(this.timing.ttlSeconds)]));
+    }
+    /**
+     * Keep holding while the deployment lives — with a new probe token — up to
+     * the cap. For up to 2 s after a renewal the gateway still holds the old
+     * key in its cache, so a probe then carries a token it has not read yet and
+     * is refused; `liftWhenAnswering` asks again, which is why it asks in a loop.
+     */
+    async renew() {
+        if (this.lifted)
+            return;
+        if (Date.now() - this.heldSince >= this.timing.capSeconds * 1000) {
+            this.logger.error({ heldSeconds: Math.round((Date.now() - this.heldSince) / 1000) }, 'Maintenance held past its cap — lifting it while the deployment runs');
+            await this.lift('capped');
+            return;
+        }
+        this.probeToken = token();
+        try {
+            await this.write();
+        }
+        catch (err) {
+            this.logger.warn({ err: err.message }, 'Could not renew the maintenance lock — it expires by itself');
+        }
+    }
+    /** Does the gateway say what we expect? Polled, since it caches for 2 s. */
+    async seen(active) {
+        const deadline = Date.now() + this.timing.seenWithinMs;
+        for (;;) {
+            try {
+                const state = JSON.parse(await this.site.run(gatewayCommand(this.site, '/_/maintenance')));
+                if (state.active === active && (!active || state.reason === 'deploy'))
+                    return true;
+            }
+            catch {
+                // A gateway mid-recreation answers nothing for a moment.
+            }
+            if (Date.now() >= deadline)
+                return false;
+            await this.sleep(500);
+        }
+    }
+    /** Paths that did not answer 2xx through the gateway, asked with this lock's probe token. */
+    async probe(paths) {
+        const failed = [];
+        for (const path of paths) {
+            try {
+                await this.site.run(gatewayCommand(this.site, path, this.probeToken));
+            }
+            catch {
+                failed.push(path);
+            }
+        }
+        return failed;
+    }
+    /**
+     * Lift when the platform answers through the gateway. A platform that does
+     * not, within `probeWithinMs`, KEEPS the lock — it stops being renewed and
+     * expires by itself within `ttlSeconds`, and the caller is told why.
+     */
+    async liftWhenAnswering(paths) {
+        const deadline = Date.now() + this.timing.probeWithinMs;
+        let failed = await this.probe(paths);
+        while (failed.length > 0 && Date.now() < deadline) {
+            await this.sleep(3_000);
+            failed = await this.probe(paths);
+        }
+        if (failed.length === 0) {
+            const heldMs = await this.lift('deployed');
+            return { lifted: true, heldMs, failed };
+        }
+        this.stopRenewing();
+        this.logger.error({ failed, expiresWithinSeconds: this.timing.ttlSeconds }, 'The platform does not answer through the gateway — the maintenance lock stays and expires by itself');
+        return { lifted: false, heldMs: Date.now() - this.heldSince, failed };
+    }
+    stopRenewing() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Let the platform go. Idempotent; a failed DEL is left to the expiry. */
+    async lift(outcome) {
+        const heldMs = Date.now() - this.heldSince;
+        if (this.lifted)
+            return heldMs;
+        this.lifted = true;
+        this.stopRenewing();
+        try {
+            await this.site.run(redisCommand(this.site, ['DEL', DEPLOY_KEY, NOTICE_KEY]));
+        }
+        catch (err) {
+            this.logger.error({ err: err.message, expiresWithinSeconds: this.timing.ttlSeconds }, 'Could not lift the maintenance lock — it expires by itself');
+            return heldMs;
+        }
+        const seen = await this.seen(false);
+        this.logger.info({ outcome, heldSeconds: Math.round(heldMs / 1000), seenByGateway: seen }, 'Maintenance lifted');
+        return heldMs;
+    }
+}
+/** Ask the gateway itself: the lock as it is enforced, not as it was written. */
+export async function readMaintenanceState(site) {
+    const raw = JSON.parse(await site.run(gatewayCommand(site, '/_/maintenance')));
+    return {
+        active: raw.active === true,
+        reason: typeof raw.reason === 'string' ? raw.reason : null,
+        message: typeof raw.message === 'string' ? raw.message : null,
+        endsAt: typeof raw.endsAt === 'number' ? raw.endsAt : null,
+        retryAfter: typeof raw.retryAfter === 'number' ? raw.retryAfter : null,
+        notice: raw.notice && typeof raw.notice === 'object' ? raw.notice : null,
+    };
+}
+/** The longest an operator can hold the platform by hand in one go. */
+export const MANUAL_HOLD_MAX_MINUTES = 60;
+/**
+ * Hold by hand for `minutes`: the deployer's lock, written once with its
+ * expiry — no renewal and no process to die, so it ends by itself. Bounded,
+ * because «on» typed and forgotten must not keep everyone out for a day.
+ */
+export async function holdByHand(site, minutes) {
+    if (!Number.isInteger(minutes) || minutes < 1 || minutes > MANUAL_HOLD_MAX_MINUTES) {
+        throw new Error(`Hold for 1–${MANUAL_HOLD_MAX_MINUTES} minutes, not ${String(minutes)}`);
+    }
+    const now = epoch(Date.now());
+    const value = JSON.stringify({ reason: 'deploy', release: site.release, since: now, eta: now + minutes * 60, probe: token() });
+    await site.run(redisCommand(site, ['SET', DEPLOY_KEY, value, 'EX', String(minutes * 60)]));
+    await site.run(redisCommand(site, ['DEL', NOTICE_KEY]));
+}
+/**
+ * Let go by hand — a lock a deployment left as much as one set by hand. Only
+ * omnitron's keys: the administrators' mode is main's, switched in /admin.
+ */
+export async function releaseByHand(site) {
+    await site.run(redisCommand(site, ['DEL', DEPLOY_KEY, NOTICE_KEY]));
+}
+/**
+ * Where the RUNNING gateway reads its lock: the stack's `<prefix>-gateway`
+ * container and the REDIS_DB it was given — asked of the container, so a lock
+ * written by hand or around a fleet upgrade goes where this gateway looks, not
+ * where a rule says it should. Only the REDIS_DB line crosses the wire; the
+ * container's other variables (a Redis password among them) stay on the node.
+ * `null` when the node has no such gateway.
+ */
+export async function runningGatewaySite(run, prefix, release) {
+    const gateway = shellEscape(`${prefix}-gateway`);
+    const line = await run(`docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' ${gateway} 2>/dev/null | grep '^REDIS_DB=' || true`).catch(() => '');
+    const db = Number(/^REDIS_DB=(\d+)\s*$/m.exec(line)?.[1] ?? NaN);
+    return Number.isInteger(db) && db >= 0 ? { run, prefix, db, release } : null;
+}
+/** Every stack gateway on a node (omnitron labels them), each where it reads. */
+export async function runningGatewaySites(run, release) {
+    const names = await run(`docker ps --filter label=omnitron.service=gateway --format '{{.Names}}' 2>/dev/null || true`).catch(() => '');
+    const sites = [];
+    for (const name of names.split('\n').map((n) => n.trim())) {
+        if (!name.endsWith('-gateway'))
+            continue;
+        const site = await runningGatewaySite(run, name.slice(0, -'-gateway'.length), release);
+        if (site)
+            sites.push(site);
+    }
+    return sites;
+}
+//# sourceMappingURL=maintenance-lock.js.map

package/dist/services/maintenance-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-lock.js","sourceRoot":"","sources":["../../src/services/maintenance-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAIjC,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,MAAM,CAAC,MAAM,UAAU,GAAG,6BAA6B,CAAC;AACxD,MAAM,CAAC,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAmBxD,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,GAAG;IACf,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,EAAE;IAChB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,KAAK;IACnB,aAAa,EAAE,MAAM;CACtB,CAAC;AAiBF,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzF,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAA4C,EAAE,IAAuB;IAChG,MAAM,KAAK,GACT,0EAA0E;QAC1E,uCAAuC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACtF,OAAO,eAAe,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,QAAQ,CAAC,UAAU,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAqC,EAAE,IAAY,EAAE,KAAc;IAChG,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,aAAa,WAAW,CAAC,wBAAwB,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,OAAO,eAAe,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,UAAU,CAAC,sBAAsB,MAAM,IAAI,WAAW,CAAC,mBAAmB,IAAI,EAAE,CAAC,EAAE,CAAC;AACtI,CAAC;AAED,MAAM,OAAO,eAAe;IAOP,IAAI;IACJ,MAAM;IACN,MAAM;IACN,KAAK;IAThB,UAAU,GAAG,KAAK,EAAE,CAAC;IACrB,KAAK,GAA0B,IAAI,CAAC;IACpC,MAAM,GAAG,KAAK,CAAC;IACN,SAAS,CAAS;IAEnC,YACmB,IAAqB,EACrB,MAAyB,EACzB,MAAe,EACf,KAAoC,EACrD,GAAW;oBAJM,IAAI;sBACJ,MAAM;sBACN,MAAM;qBACN,KAAK;QAGtB,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CACf,IAAqB,EACrB,MAAe,EACf,MAAM,GAAsB,0BAA0B,EACtD,KAAK,GAAkC,QAAQ;QAE/C,0EAA0E;QAC1E,qEAAqE;QACrE,qEAAqE;QACrE,uEAAuE;QACvE,wEAAwE;QACxE,0EAA0E;QAC1E,iDAAiD;QACjD,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CACtB,oDAAoD,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,UAAU,CAAC,IAAI,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,QAAQ,CAAC,sBAAsB,CACvJ,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC9E,+EAA+E,CAChF,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,kFAAkF,CAAC,CAAC;YACzH,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,IAAI,MAAM,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC;gBAC1D,MAAM,IAAI,CAAC,GAAG,CACZ,YAAY,CAAC,IAAI,EAAE;oBACjB,KAAK;oBACL,UAAU;oBACV,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;oBACnD,IAAI;oBACJ,MAAM,CAAC,MAAM,CAAC,aAAa,GAAG,GAAG,CAAC;iBACnC,CAAC,CACH,CAAC;gBACF,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE,EAAE,uCAAuC,CAAC,CAAC;gBACjH,MAAM,KAAK,CAAC,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;YAC3C,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC1E,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;YACxD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBAC7B,mEAAmE;gBACnE,sEAAsE;gBACtE,uEAAuE;gBACvE,MAAM,CAAC,KAAK,CACV,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EACpC,mGAAmG,CACpG,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,mCAAmC,CAAC,CAAC;YAC3F,CAAC;YACD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;YAC9E,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAG,GAAa,CAAC,OAAO,EAAE,EAAE,2DAA2D,CAAC,CAAC;YAC3G,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC3F,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAEO,KAAK;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;YAC1B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YAC5B,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU;YACnD,KAAK,EAAE,IAAI,CAAC,UAAU;SACvB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACxH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC;YACjE,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,EAAE,EACjE,sEAAsE,CACvE,CAAC;YACF,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAG,GAAa,CAAC,OAAO,EAAE,EAAE,6DAA6D,CAAC,CAAC;QACnH,CAAC;IACH,CAAC;IAED,4EAA4E;IACpE,KAAK,CAAC,IAAI,CAAC,MAAe;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;QACvD,SAAS,CAAC;YACR,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAGxF,CAAC;gBACF,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC;oBAAE,OAAO,IAAI,CAAC;YACrF,CAAC;YAAC,MAAM,CAAC;gBACP,yDAAyD;YAC3D,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;gBAAE,OAAO,KAAK,CAAC;YACzC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,6FAA6F;IAC7F,KAAK,CAAC,KAAK,CAAC,KAAwB;QAClC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YACxE,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,iBAAiB,CAAC,KAAwB;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QACxD,IAAI,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAClD,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACxB,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,MAAM,EAAE,oBAAoB,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EACxD,qGAAqG,CACtG,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IACxE,CAAC;IAEO,YAAY;QAClB,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAC3C,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,MAAM,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QAChF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,GAAG,EAAG,GAAa,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAC7E,4DAA4D,CAC7D,CAAC;YACF,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,EACxE,oBAAoB,CACrB,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAYD,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAA6C;IACtF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAA8B,CAAC;IAC5G,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,IAAI;QAC3B,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;QAC1D,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;QAC7D,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;QAC1D,UAAU,EAAE,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI;QACtE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,GAAG,CAAC,MAAqC,CAAC,CAAC,CAAC,IAAI;KACzG,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAqB,EAAE,OAAe;IACrE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,uBAAuB,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,cAAc,uBAAuB,iBAAiB,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/H,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAoD;IACtF,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAe,EAAE,MAAc,EAAE,OAAe;IACvF,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,MAAM,UAAU,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,MAAM,GAAG,CACpB,iEAAiE,OAAO,0CAA0C,CACnH,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAClB,MAAM,EAAE,GAAG,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IACjE,OAAO,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAe,EAAE,OAAe;IACxE,MAAM,KAAK,GAAG,MAAM,GAAG,CACrB,6FAA6F,CAC9F,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAClB,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,SAAS;QACzC,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACvF,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/services/master-address.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The address a slave should dial to reach this master.
+ *
+ * A slave's generated config carries `master: { host, port }`, and it is the
+ * only way it knows where to send its metrics, logs and events. Getting it
+ * wrong does not fail loudly: the slave starts, supervises its apps, buffers
+ * everything it collects, and retries a connection that cannot succeed. The
+ * console shows a node that simply never has anything to say — the same
+ * picture as a healthy node on a quiet host.
+ *
+ * Both call sites computed it like this:
+ *
+ *     const masterHost = dc.host === '0.0.0.0' ? 'auto' : dc.host;
+ *     ...
+ *     provisionSlaveNode(node, masterHost === 'auto' ? node.host : masterHost, ...)
+ *
+ * `node.host` is the SLAVE's address. So a master that binds all interfaces —
+ * which is every master that has remote slaves at all, because a master bound
+ * to loopback cannot serve them — told each slave that the master was itself.
+ * The comment beside it read "slave uses its own view of master", which is
+ * the right idea and the wrong value.
+ *
+ * The ways to know, in the order they are trusted:
+ *
+ *  1. `daemon.advertiseHost`, if the operator set it. Nothing else can be
+ *     right when the master is behind NAT or a load balancer: only a human
+ *     knows the address that reaches it from outside.
+ *  2. `daemon.host`, when it names one interface. A master bound to
+ *     192.0.2.10 is reachable at 192.0.2.10.
+ *  3. The local address of a route to the node. Opening a TCP connection to
+ *     the machine we are about to provision and asking the kernel which of
+ *     our addresses it used answers "which of my addresses can this node see"
+ *     — for a directly-routable master, exactly right.
+ *
+ * And when none of them answers, it raises. A deployment that stops with
+ * "set daemon.advertiseHost" costs an operator a minute; one that silently
+ * provisions a fleet of slaves pointed at themselves costs an afternoon, and
+ * gives no clue where to look.
+ */
+export interface MasterAddressSources {
+    /** `daemon.advertiseHost` — what the operator says reaches this master. */
+    advertiseHost?: string | undefined;
+    /** `daemon.host` — the bind address. */
+    bindHost?: string | undefined;
+}
+export declare function isWildcardHost(host: string | undefined): boolean;
+/**
+ * Ask the kernel which of our addresses reaches `host`.
+ *
+ * No data is sent: the connection is opened and destroyed. A firewall that
+ * refuses still tells us what we need, because `localAddress` is assigned at
+ * connect time — but a connection that never resolves tells us nothing, hence
+ * the deadline.
+ */
+export declare function localAddressToward(host: string, port: number, timeoutMs?: number): Promise<string | null>;
+/**
+ * Resolve the master address to write into a slave's config.
+ *
+ * @param sources  what the daemon's own configuration says
+ * @param node     the slave being provisioned: used only to discover which of
+ *                 our addresses can reach it, never as the answer itself
+ * @throws Error naming the setting to add, when nothing can answer
+ */
+/**
+ * Where a slave should dial, or why there is nowhere.
+ *
+ * `host: null` is an answer, not a failure. Replication is master-PULL: the
+ * master opens the connection to each node — over SSH when the node's daemon
+ * port is closed — drains its buffer and acknowledges. A slave dials nothing,
+ * and the address it is given is read by one log line at startup.
+ *
+ * This used to THROW for a master on loopback, from a time when the push
+ * path was assumed to be the one that would exist. It made a workable
+ * deployment impossible: a workstation behind NAT, which is where remote
+ * stacks are started from, cannot be dialled by anything and does not need
+ * to be. Measured while deploying a stack to the test server:
+ *
+ *     Refusing to provision 37.27.130.185: this daemon listens on 127.0.0.1
+ *
+ * — from a master that was, at that moment, connected to that very node and
+ * pulling its metrics.
+ *
+ * The refusals it used to make are still the right thing to SAY. A master
+ * that could be dialled but is about to hand out an address that does not
+ * reach it is a misconfiguration, and `reason` carries it so the caller can
+ * report it once rather than discovering it as an empty console days later.
+ */
+export interface MasterAddress {
+    host: string | null;
+    source: 'advertiseHost' | 'bindHost' | 'route' | 'unreachable';
+    /** Present when `host` is null: why no address would have worked. */
+    reason?: string;
+}
+export declare function resolveMasterHost(sources: MasterAddressSources, node: {
+    host: string;
+    sshPort?: number | undefined;
+}, probe?: (host: string, port: number) => Promise<string | null>): Promise<MasterAddress>;
+/**
+ * Whether an address is one that only works inside a network.
+ *
+ * Hostnames answer `false`: a name can resolve to anything, and refusing one
+ * on suspicion would block the ordinary case where an operator gave a real
+ * DNS name. This exists to catch the address we DISCOVERED, which is always
+ * numeric.
+ */
+export declare function isPrivateAddress(host: string): boolean;
+//# sourceMappingURL=master-address.d.ts.map

package/dist/services/master-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-address.d.ts","sourceRoot":"","sources":["../../src/services/master-address.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAOH,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,SAAQ,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBxB;AAED;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;IAC/D,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EACpD,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAsB,GACjF,OAAO,CAAC,aAAa,CAAC,CAsDxB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBtD"}

package/dist/services/master-address.js

@@ -0,0 +1,154 @@
+/**
+ * The address a slave should dial to reach this master.
+ *
+ * A slave's generated config carries `master: { host, port }`, and it is the
+ * only way it knows where to send its metrics, logs and events. Getting it
+ * wrong does not fail loudly: the slave starts, supervises its apps, buffers
+ * everything it collects, and retries a connection that cannot succeed. The
+ * console shows a node that simply never has anything to say — the same
+ * picture as a healthy node on a quiet host.
+ *
+ * Both call sites computed it like this:
+ *
+ *     const masterHost = dc.host === '0.0.0.0' ? 'auto' : dc.host;
+ *     ...
+ *     provisionSlaveNode(node, masterHost === 'auto' ? node.host : masterHost, ...)
+ *
+ * `node.host` is the SLAVE's address. So a master that binds all interfaces —
+ * which is every master that has remote slaves at all, because a master bound
+ * to loopback cannot serve them — told each slave that the master was itself.
+ * The comment beside it read "slave uses its own view of master", which is
+ * the right idea and the wrong value.
+ *
+ * The ways to know, in the order they are trusted:
+ *
+ *  1. `daemon.advertiseHost`, if the operator set it. Nothing else can be
+ *     right when the master is behind NAT or a load balancer: only a human
+ *     knows the address that reaches it from outside.
+ *  2. `daemon.host`, when it names one interface. A master bound to
+ *     192.0.2.10 is reachable at 192.0.2.10.
+ *  3. The local address of a route to the node. Opening a TCP connection to
+ *     the machine we are about to provision and asking the kernel which of
+ *     our addresses it used answers "which of my addresses can this node see"
+ *     — for a directly-routable master, exactly right.
+ *
+ * And when none of them answers, it raises. A deployment that stops with
+ * "set daemon.advertiseHost" costs an operator a minute; one that silently
+ * provisions a fleet of slaves pointed at themselves costs an afternoon, and
+ * gives no clue where to look.
+ */
+import net from 'node:net';
+/** Addresses that mean "every interface" rather than a reachable host. */
+const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]', '*', '']);
+export function isWildcardHost(host) {
+    return host == null || WILDCARD_HOSTS.has(host.trim());
+}
+/**
+ * Ask the kernel which of our addresses reaches `host`.
+ *
+ * No data is sent: the connection is opened and destroyed. A firewall that
+ * refuses still tells us what we need, because `localAddress` is assigned at
+ * connect time — but a connection that never resolves tells us nothing, hence
+ * the deadline.
+ */
+export async function localAddressToward(host, port, timeoutMs = 5_000) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const done = (value) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setTimeout(timeoutMs, () => done(null));
+        socket.once('connect', () => {
+            const local = socket.localAddress ?? null;
+            // An IPv6-mapped IPv4 address (`::ffff:192.0.2.10`) is the same address
+            // wearing a different notation, and a config file is easier to read
+            // without it.
+            done(local && local.startsWith('::ffff:') ? local.slice('::ffff:'.length) : local);
+        });
+        socket.once('error', () => done(null));
+    });
+}
+export async function resolveMasterHost(sources, node, probe = localAddressToward) {
+    const advertised = sources.advertiseHost?.trim();
+    if (advertised && !isWildcardHost(advertised)) {
+        return { host: advertised, source: 'advertiseHost' };
+    }
+    const bind = sources.bindHost?.trim();
+    if (bind && !isWildcardHost(bind) && bind !== '127.0.0.1' && bind !== 'localhost' && bind !== '::1') {
+        return { host: bind, source: 'bindHost' };
+    }
+    // A master bound to loopback cannot be reached by any slave, so discovering
+    // a route to the node would produce an address that is real and useless.
+    if (bind === '127.0.0.1' || bind === 'localhost' || bind === '::1') {
+        return {
+            host: null,
+            source: 'unreachable',
+            reason: `this daemon listens on ${bind}, so no node can dial it. The mesh connects the other way — ` +
+                'this master opens the connection and pulls. Set `daemon.host` and `daemon.advertiseHost` ' +
+                'only if something needs to dial in.',
+        };
+    }
+    const routed = await probe(node.host, node.sshPort ?? 22);
+    if (routed && !isWildcardHost(routed)) {
+        // A route tells us which of our addresses reaches the node. It does not
+        // tell us that the node can reach US at that address, and when ours is
+        // private and the node is not, it positively cannot.
+        //
+        // Measured 2026-09-14, provisioning the test host from this workstation:
+        // the route to 37.27.130.185 leaves from 10.8.1.1 — a VPN address behind
+        // NAT. Handing that to the slave produces a config that looks filled in,
+        // parses, starts, and dials an address that does not exist from where it
+        // stands. The failure would arrive as an empty console, days later.
+        if (isPrivateAddress(routed) && !isPrivateAddress(node.host)) {
+            return {
+                host: null,
+                source: 'unreachable',
+                reason: `the route to ${node.host} leaves this master at ${routed}, a private address a public host cannot reach. ` +
+                    'The mesh connects the other way, so nothing is blocked; set `daemon.advertiseHost` if something needs to dial in.',
+            };
+        }
+        return { host: routed, source: 'route' };
+    }
+    return {
+        host: null,
+        source: 'unreachable',
+        reason: `no route from this master to ${node.host} answered, so there is no address to hand it. ` +
+            'The mesh connects the other way, so this does not stop the deployment.',
+    };
+}
+/**
+ * Whether an address is one that only works inside a network.
+ *
+ * Hostnames answer `false`: a name can resolve to anything, and refusing one
+ * on suspicion would block the ordinary case where an operator gave a real
+ * DNS name. This exists to catch the address we DISCOVERED, which is always
+ * numeric.
+ */
+export function isPrivateAddress(host) {
+    const h = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h === '::1')
+        return true;
+    // IPv6 unique-local (fc00::/7) and link-local (fe80::/10).
+    if (/^f[cd][0-9a-f]{2}:/.test(h) || /^fe[89ab][0-9a-f]:/.test(h))
+        return true;
+    const octets = h.split('.');
+    if (octets.length !== 4)
+        return false;
+    const [a, b] = octets.map((o) => Number(o));
+    if (!Number.isInteger(a) || !Number.isInteger(b))
+        return false;
+    if (a === 10 || a === 127)
+        return true; // private, loopback
+    if (a === 192 && b === 168)
+        return true; // private
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // private
+    if (a === 169 && b === 254)
+        return true; // link-local
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // carrier-grade NAT
+    return false;
+}
+//# sourceMappingURL=master-address.js.map

package/dist/services/master-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-address.js","sourceRoot":"","sources":["../../src/services/master-address.ts"],"names":[],"mappings":"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"}

package/dist/services/migration-output.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a migrator printed, as lines worth a log.
+ *
+ * A data migration reports what it did on stdout — daos 194 names every role it
+ * swept, 195 counts the measurement axes it found and made and names the
+ * hand-made ones — and the runner prints how many it applied. Both places that
+ * run an app's migrations discarded all of it: a local stack's
+ * (`ProjectService.runStackMigrations`) logged «Migrations applied», a node's
+ * (`RemoteDeployer.migrateNodeApps`) «Database migrations applied on the
+ * node», and neither anything it had been told (2026-09-25: 195 on dev and on
+ * daos/test). The one line cut short is the runner's enumeration of every
+ * migration it found, 202 names on one line: its count is kept, the names are
+ * not.
+ */
+export declare function migrationOutput(stdout: string): string[];
+//# sourceMappingURL=migration-output.d.ts.map

package/dist/services/migration-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-output.d.ts","sourceRoot":"","sources":["../../src/services/migration-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAMxD"}

package/dist/services/migration-output.js

@@ -0,0 +1,22 @@
+/**
+ * What a migrator printed, as lines worth a log.
+ *
+ * A data migration reports what it did on stdout — daos 194 names every role it
+ * swept, 195 counts the measurement axes it found and made and names the
+ * hand-made ones — and the runner prints how many it applied. Both places that
+ * run an app's migrations discarded all of it: a local stack's
+ * (`ProjectService.runStackMigrations`) logged «Migrations applied», a node's
+ * (`RemoteDeployer.migrateNodeApps`) «Database migrations applied on the
+ * node», and neither anything it had been told (2026-09-25: 195 on dev and on
+ * daos/test). The one line cut short is the runner's enumeration of every
+ * migration it found, 202 names on one line: its count is kept, the names are
+ * not.
+ */
+export function migrationOutput(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() !== '')
+        .map((line) => line.replace(/^(Discovered \d+ migration\(s\)):.*$/, '$1'));
+}
+//# sourceMappingURL=migration-output.js.map