@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/ports.js

@@ -0,0 +1,94 @@
+import { createServer } from 'node:net';
+import { readFileSync } from 'node:fs';
+/**
+ * Is `port` genuinely free?
+ *
+ * Binding only 127.0.0.1 misses a foreign process listening on the WILDCARD
+ * address: on Linux that bind collides and reports busy, but on macOS it
+ * succeeds, so the "port occupied by a foreign process" guard never fired
+ * there and the service started into a port someone else already held.
+ * Probing the wildcard as well is what makes the two platforms agree.
+ */
+export function probeFree(port) {
+    const bind = (host) => new Promise((resolve) => {
+        const srv = createServer();
+        srv.once('error', () => resolve(false));
+        srv.listen(port, host, () => srv.close(() => resolve(true)));
+    });
+    return bind('127.0.0.1').then((loopback) => (loopback ? bind('0.0.0.0') : false));
+}
+export const DEFAULT_PUBLIC_BLOCK = { lo: 20000, hi: 29999 };
+export const DEFAULT_INTERNAL_BLOCK = { lo: 30000, hi: 31999 };
+export const DEFAULT_TUNNEL_BLOCK = { lo: 32000, hi: 32767 };
+function blockFromEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const m = /^\s*(\d+)\s*-\s*(\d+)\s*$/.exec(raw);
+    if (!m)
+        return fallback;
+    const lo = Number(m[1]);
+    const hi = Number(m[2]);
+    if (!(lo >= 1024 && hi <= 65535 && lo <= hi))
+        return fallback;
+    return { lo, hi };
+}
+export const publicBlock = () => blockFromEnv('BACKLOT_PORT_RANGE', DEFAULT_PUBLIC_BLOCK);
+export const internalBlock = () => blockFromEnv('BACKLOT_INTERNAL_PORT_RANGE', DEFAULT_INTERNAL_BLOCK);
+export const tunnelBlock = () => blockFromEnv('BACKLOT_TUNNEL_PORT_RANGE', DEFAULT_TUNNEL_BLOCK);
+export const inBlock = (port, block) => port >= block.lo && port <= block.hi;
+/**
+ * The OS ephemeral (outbound source-port) range. Linux publishes it; other
+ * platforms get the IANA range their kernels use by default.
+ */
+export function ephemeralRange() {
+    try {
+        const [lo, hi] = readFileSync('/proc/sys/net/ipv4/ip_local_port_range', 'utf8').trim().split(/\s+/).map(Number);
+        if (lo && hi && lo <= hi)
+            return { lo, hi };
+    }
+    catch {
+        /* not Linux */
+    }
+    return { lo: 49152, hi: 65535 };
+}
+/** Human-readable overlaps of the configured blocks with each other and the ephemeral range. */
+export function blockConflicts() {
+    const eph = ephemeralRange();
+    const blocks = [['public', publicBlock()], ['internal', internalBlock()], ['tunnel', tunnelBlock()]];
+    const overlap = (a, b) => a.lo <= b.hi && b.lo <= a.hi;
+    const out = [];
+    for (const [name, b] of blocks) {
+        if (overlap(b, eph))
+            out.push(`the ${name} port block ${b.lo}-${b.hi} overlaps the OS ephemeral range ${eph.lo}-${eph.hi}; ports in the overlap are skipped`);
+    }
+    for (let i = 0; i < blocks.length; i++) {
+        for (let j = i + 1; j < blocks.length; j++) {
+            const [an, a] = blocks[i];
+            const [bn, b] = blocks[j];
+            if (overlap(a, b))
+                out.push(`the ${an} port block ${a.lo}-${a.hi} overlaps the ${bn} block ${b.lo}-${b.hi}`);
+        }
+    }
+    return out;
+}
+/**
+ * The first port of `block` that is not in `taken`, not ephemeral, and probes
+ * free, scanning from a random offset so concurrent daemons (and a daemon
+ * restarted with an empty memory) do not all start at the bottom. Returns
+ * undefined when the block has nothing left — the caller names the block.
+ */
+export async function allocateInBlock(block, taken, probe = probeFree) {
+    const eph = ephemeralRange();
+    const span = block.hi - block.lo + 1;
+    const start = Math.floor(Math.random() * span);
+    for (let i = 0; i < span; i++) {
+        const port = block.lo + ((start + i) % span);
+        if (taken.has(port) || inBlock(port, eph))
+            continue;
+        if (await probe(port))
+            return port;
+    }
+    return undefined;
+}
+//# sourceMappingURL=ports.js.map

package/dist/core/ports.js.map

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

package/dist/core/presets.d.ts

@@ -0,0 +1,25 @@
+import { type DatastoreSpec, type Manifest } from './manifest.js';
+/** The presets a datastore offers. A manifest without a catalog keeps its historical default choices. */
+export declare function presetCatalog(spec: DatastoreSpec): string[];
+/** A datastore's default preset, validated against its catalog. */
+export declare function defaultPresetFor(name: string, spec: DatastoreSpec): string;
+/**
+ * Validate an explicit `--preset` request (decision 0034) and every declared
+ * default, before anything is claimed or changed. Returns ONLY the datastores
+ * the caller named: an explicit preset reloads that datastore from its
+ * template, and a datastore nobody named keeps whatever it holds.
+ */
+export declare function validatePresetRequest(manifest: Manifest, requested?: unknown, file?: string): Record<string, string>;
+/**
+ * The preset a datastore is (re)created with when the caller named none: the
+ * one it holds, while the catalog still offers it, else the default. A store
+ * that is merely KEPT is never touched — this only decides what a restore that
+ * happens anyway (a reset, a first creation) restores.
+ */
+export declare function presetToRestore(name: string, spec: DatastoreSpec, held: string | undefined): string;
+/**
+ * CLI shorthand is only unambiguous for a single datastore — of the ones an
+ * environment has: a `copies_only` datastore (decision 0039) is never reloaded
+ * by `up`/`reset-data`, so it does not make `--preset NAME` ambiguous.
+ */
+export declare function parsePresetArgs(manifest: Manifest, values: string[]): Record<string, string> | undefined;

package/dist/core/presets.js

@@ -0,0 +1,86 @@
+import { declaredDefaultPreset, defaultPreset, envDatastoreNames } from './manifest.js';
+import { BrokerError } from './util.js';
+/** The presets a datastore offers. A manifest without a catalog keeps its historical default choices. */
+export function presetCatalog(spec) {
+    const declared = declaredDefaultPreset(spec);
+    return spec.presets?.length ? spec.presets : [...new Set(['default', ...(declared === undefined ? [] : [declared])])];
+}
+/** A datastore's default preset, validated against its catalog. */
+export function defaultPresetFor(name, spec) {
+    const catalog = presetCatalog(spec);
+    const declared = declaredDefaultPreset(spec);
+    if (declared !== undefined && !catalog.includes(declared))
+        throw new BrokerError('work-error', `default preset '${declared}' for '${name}' is not declared in presets`, 'manifest');
+    const value = defaultPreset(spec);
+    if (!catalog.includes(value)) {
+        throw new BrokerError('work-error', `no preset '${value}' for datastore '${name}' (have: ${catalog.join(', ') || 'none'})`, 'manifest');
+    }
+    return value;
+}
+/**
+ * Validate an explicit `--preset` request (decision 0034) and every declared
+ * default, before anything is claimed or changed. Returns ONLY the datastores
+ * the caller named: an explicit preset reloads that datastore from its
+ * template, and a datastore nobody named keeps whatever it holds.
+ */
+export function validatePresetRequest(manifest, requested, file = 'runly.yml') {
+    const stores = manifest.datastores ?? {};
+    if (requested !== undefined && (requested === null || typeof requested !== 'object' || Array.isArray(requested))) {
+        throw new BrokerError('work-error', 'presets must map datastore names to preset names', 'manifest');
+    }
+    const choices = (requested ?? {});
+    for (const [name, value] of Object.entries(choices)) {
+        if (!Object.hasOwn(stores, name))
+            throw new BrokerError('work-error', `no datastore '${name}' in ${file}`, 'manifest');
+        if (typeof value !== 'string' || !value)
+            throw new BrokerError('work-error', `preset for '${name}' must be a nonempty name`, 'manifest');
+    }
+    const out = {};
+    for (const [name, spec] of Object.entries(stores)) {
+        defaultPresetFor(name, spec);
+        if (!Object.hasOwn(choices, name))
+            continue;
+        const value = choices[name];
+        const catalog = presetCatalog(spec);
+        if (!catalog.includes(value)) {
+            throw new BrokerError('work-error', `no preset '${value}' for datastore '${name}' (have: ${catalog.join(', ') || 'none'})`, 'manifest');
+        }
+        out[name] = value;
+    }
+    return out;
+}
+/**
+ * The preset a datastore is (re)created with when the caller named none: the
+ * one it holds, while the catalog still offers it, else the default. A store
+ * that is merely KEPT is never touched — this only decides what a restore that
+ * happens anyway (a reset, a first creation) restores.
+ */
+export function presetToRestore(name, spec, held) {
+    if (held !== undefined && presetCatalog(spec).includes(held))
+        return held;
+    return defaultPresetFor(name, spec);
+}
+/**
+ * CLI shorthand is only unambiguous for a single datastore — of the ones an
+ * environment has: a `copies_only` datastore (decision 0039) is never reloaded
+ * by `up`/`reset-data`, so it does not make `--preset NAME` ambiguous.
+ */
+export function parsePresetArgs(manifest, values) {
+    if (values.length === 0)
+        return undefined;
+    const stores = envDatastoreNames(manifest);
+    const choices = Object.create(null);
+    for (const value of values) {
+        const at = value.indexOf('=');
+        if (at < 0 && stores.length !== 1) {
+            throw new BrokerError('work-error', `--preset NAME requires exactly one datastore an environment has (here: ${stores.join(', ') || 'none'}); use --preset DATASTORE=NAME`, 'manifest');
+        }
+        const name = at < 0 ? stores[0] : value.slice(0, at);
+        const preset = at < 0 ? value : value.slice(at + 1);
+        if (Object.hasOwn(choices, name))
+            throw new BrokerError('work-error', `preset for '${name}' was selected more than once`, 'manifest');
+        choices[name] = preset;
+    }
+    return choices;
+}
+//# sourceMappingURL=presets.js.map

package/dist/core/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/core/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,iBAAiB,EAAqC,MAAM,eAAe,CAAC;AAC3H,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,yGAAyG;AACzG,MAAM,UAAU,aAAa,CAAC,IAAmB;IAC/C,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxH,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAmB;IAChE,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,mBAAmB,QAAQ,UAAU,IAAI,8BAA8B,EAAE,UAAU,CAAC,CAAC;IACpL,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,cAAc,KAAK,oBAAoB,IAAI,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,EAAE,UAAU,CAAC,CAAC;IAC1I,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAkB,EAAE,SAAmB,EAAE,IAAI,GAAG,WAAW;IAC/F,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC;IACzC,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QACjH,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,kDAAkD,EAAE,UAAU,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,SAAS,IAAI,EAAE,CAA4B,CAAC;IAC7D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,iBAAiB,IAAI,QAAQ,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC;QACvH,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,eAAe,IAAI,2BAA2B,EAAE,UAAU,CAAC,CAAC;IAC3I,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,SAAS;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAW,CAAC;QACtC,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,cAAc,KAAK,oBAAoB,IAAI,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,EAAE,UAAU,CAAC,CAAC;QAC1I,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAmB,EAAE,IAAwB;IACzF,IAAI,IAAI,KAAK,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAkB,EAAE,MAAgB;IAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,OAAO,GAA2B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,0EAA0E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,gCAAgC,EAAE,UAAU,CAAC,CAAC;QACzL,CAAC;QACD,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,eAAe,IAAI,+BAA+B,EAAE,UAAU,CAAC,CAAC;QACtI,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/procscan.d.ts

@@ -0,0 +1,111 @@
+export declare const ENV_TAG = "BACKLOT_ENV_ID";
+export declare const SERVICE_TAG = "BACKLOT_SERVICE";
+/** Scopes a tag to one state root so parallel installs never reap each other. */
+export declare const ROOT_TAG = "BACKLOT_STATE_ROOT";
+export interface TaggedProc {
+    pid: number;
+    envId: string;
+    service: string;
+    startTime: number;
+}
+/** The environment every supervised service is spawned with. */
+/** The service name `runly exec`'s command is tagged with; never reaped (see scanTagged). */
+export declare const EXEC_SERVICE = "exec";
+export declare function serviceTag(envId: string, service: string, stateRoot: string): Record<string, string>;
+export declare const procScanSupported: () => boolean;
+/**
+ * Field 22 of /proc/<pid>/stat: the process start time in clock ticks since
+ * boot. Unique per pid *life*, so (pid, startTime) survives pid reuse.
+ *
+ * comm (field 2) is an arbitrary string wrapped in parens and may itself
+ * contain spaces or parens, so parse after the LAST ')' rather than splitting
+ * the whole line.
+ */
+export declare function startTime(pid: number): number | undefined;
+/**
+ * Field 5 of /proc/<pid>/stat: the process group id.
+ *
+ * `sh -c <cmd>` does NOT reliably exec: dash forks for anything non-trivial,
+ * so the pid runly records is often only the wrapper, and the real server is
+ * a sibling in the same group. Killing "the leader" and then checking the
+ * leader's liveness therefore reports success while the server keeps running —
+ * group membership is the only honest liveness question.
+ */
+export declare function processGroup(pid: number): number | undefined;
+/**
+ * Is ANY process still in this group?
+ *
+ * Without /proc, `kill(-pgid, 0)` is still a genuine GROUP query — ESRCH means
+ * the group is empty. Checking the leader instead would report "gone" the
+ * moment an `sh -c` wrapper exited, while the real server kept running, which
+ * is the whole failure this function exists to detect.
+ */
+export declare function groupAlive(pgid: number): boolean;
+/** Is this pid alive at all? Says nothing about whose it is. */
+export declare function isAlive(pid: number): boolean;
+/**
+ * Is pid N still the same process that was recorded with `recordedStart`?
+ *
+ * With no recorded start time (a journal written by an older runly, or a
+ * non-Linux host) this can only fall back to liveness, which is exactly the
+ * pid-reuse hazard this exists to close — so callers should treat an
+ * un-verifiable pid as un-signallable where a mistake would be costly.
+ */
+export declare function sameProcess(pid: number, recordedStart?: number): boolean;
+/**
+ * Every live process tagged as belonging to this state root.
+ *
+ * Note this finds *descendants* too — an `ng serve` inherits the tag from the
+ * `sh -c` wrapper runly spawned, which is the whole point: after the wrapper
+ * dies the child is still identifiable.
+ */
+export declare function scanTagged(stateRoot: string): TaggedProc[];
+/** Carried by `runly db with`'s command and its descendants: the copy it runs against (decision 0039). */
+export declare const DB_COPY_TAG = "BACKLOT_DB_COPY";
+/** The environment `runly db with` runs its command with, so the daemon can find it again. */
+export declare function dbCopyTag(copy: string, stateRoot: string): Record<string, string>;
+/**
+ * Every live process of this state root running against database copy
+ * `copy` — `runly db with`'s command and whatever it started (the tag is
+ * inherited). Linux only, like `scanTagged`; elsewhere the recorded pid is
+ * all there is.
+ */
+export declare function scanDbCopy(copy: string, stateRoot: string): Array<{
+    pid: number;
+    startTime: number;
+}>;
+/**
+ * Every live process whose working directory sits inside `prefix` AND which has
+ * no controlling terminal.
+ *
+ * The tag scan above misses a descendant that scrubbed its environment (a
+ * process launched through `env -i`, a re-exec that rebuilds environ, some
+ * language runtimes' worker pools). Those still have to live SOMEWHERE. Under
+ * the old projection that somewhere was the environment's own tree; since
+ * decision 0032 services run in the caller's worktree, where cwd proves
+ * nothing, so the engine only ever points this at an environment's PRIVATE
+ * directory (see Engine.reapEnvTree).
+ *
+ * Linux keeps the cwd link readable after the directory is unlinked, appending
+ * " (deleted)" to the target — which is precisely the shape of the leak this
+ * exists to catch: hundreds of service children still running out of an
+ * environment tree that was removed a day earlier. The suffix is stripped so a
+ * deleted tree still matches its prefix.
+ *
+ * The tty exclusion is not a nicety. cwd is NOT proof of ownership — a developer
+ * who runs `cd <env-tree>` to look around matches this scan exactly, and callers
+ * signal a matched process's whole GROUP, so without the exclusion a teardown
+ * would kill that person's shell and every job in it. That is the one outcome
+ * this module exists to prevent (see the header): skipping a sweep is safe,
+ * signalling a stranger's process is not. A runly service can never be
+ * excluded by it, because it never has a terminal to begin with.
+ *
+ * Even so, deliberately NOT used on the quiesce path, and never on a worktree:
+ * only teardown, which is about to delete the environment's private directory
+ * anyway, may reap by cwd — and only inside that directory.
+ */
+export declare function scanByCwd(prefix: string): Array<{
+    pid: number;
+    startTime: number;
+    cwd: string;
+}>;