@theford/runly 0.0.0-stage → 0.20.0

package/dist/drivers/appliances.js

@@ -0,0 +1,174 @@
+/**
+ * Appliances: singular, machine-shared backing services (a Postgres server, a
+ * Redis, a MinIO) that environments point at but never own.
+ *
+ * The contract is ENSURE, NOT OWN (decision 0018). An appliance's identity is
+ * its probe address: whoever answers `host:port` IS the appliance, no matter
+ * who started it — a compose file yesterday, a teammate's shell, or runly a
+ * minute ago. runly never supervises the process (the `start:` command is
+ * expected to daemonize, e.g. `docker run -d`), never stops one automatically,
+ * and blames nobody's code when one is missing: every failure here is an
+ * infra-error by construction.
+ */
+import { runBounded, DEFAULT_CMD_TIMEOUT_S } from '../core/exec.js';
+import { connect } from 'node:net';
+import { mkdirSync, rmdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../core/paths.js';
+import { BrokerError, now, sha256 } from '../core/util.js';
+const PROBE_TIMEOUT_MS = 3000;
+const START_POLL_MS = 500;
+/** A start lock older than this is a crashed starter, not a live one. */
+/**
+ * A start lock is stale once nobody could still be legitimately holding it.
+ * A fixed 5 minutes was WRONG for an appliance declaring a longer timeout: a
+ * second caller stole the lock mid-start and raced the first one's container.
+ */
+const LOCK_STALE_MS = 5 * 60 * 1000;
+const lockStaleMs = (timeoutS) => Math.max(LOCK_STALE_MS, (timeoutS ?? 0) * 1000 + 60_000);
+export function probeTcp(target, timeoutMs = PROBE_TIMEOUT_MS) {
+    const [host, portStr] = target.split(':');
+    const port = Number(portStr);
+    return new Promise((resolve) => {
+        const sock = connect({ host: host || 'localhost', port, timeout: timeoutMs });
+        sock.once('connect', () => {
+            sock.end();
+            resolve(true);
+        });
+        const fail = () => {
+            sock.destroy();
+            resolve(false);
+        };
+        sock.once('error', fail);
+        sock.once('timeout', fail);
+    });
+}
+/**
+ * Appliance commands are the likeliest to hang: `start: docker run ...` without
+ * `-d` never returns, and an unbounded wait there wedges the bind AND leaves
+ * the environment permanently busy (so its lease never expires and teardown
+ * refuses it). Bounded, in its own process group.
+ */
+const sh = async (cmd, cwd) => {
+    const r = await runBounded(cmd, cwd);
+    return {
+        code: r.code,
+        output: r.timedOut ? `${r.output}\n[killed: exceeded ${DEFAULT_CMD_TIMEOUT_S}s]` : r.output,
+    };
+};
+/**
+ * One start attempt per probe target machine-wide, whatever stack asked.
+ * Two stacks declaring "the postgres on 5433" race to the same lock, and the
+ * loser adopts what the winner started.
+ */
+function lockDir(target) {
+    const dir = join(stateRoot(), 'appliances');
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `${target.replace(/[^A-Za-z0-9._-]/g, '_')}-${sha256(target).slice(0, 8)}.lock`);
+}
+function acquireLock(target, timeoutS) {
+    const lock = lockDir(target);
+    try {
+        mkdirSync(lock);
+        return true;
+    }
+    catch {
+        try {
+            if (now() - statSync(lock).mtimeMs > lockStaleMs(timeoutS)) {
+                rmdirSync(lock);
+                mkdirSync(lock);
+                return true;
+            }
+        }
+        catch {
+            /* raced — treat as not acquired */
+        }
+        return false;
+    }
+}
+function releaseLock(target) {
+    try {
+        rmdirSync(lockDir(target));
+    }
+    catch {
+        /* already gone */
+    }
+}
+async function awaitUp(name, spec, root, deadline) {
+    while (now() < deadline) {
+        if (await probeTcp(spec.probe)) {
+            if (!spec.ready)
+                return true;
+            const r = await sh(spec.ready, root);
+            if (r.code === 0)
+                return true;
+        }
+        await new Promise((r) => setTimeout(r, START_POLL_MS));
+    }
+    return false;
+}
+/**
+ * Probe; if down and a `start:` is declared, start it (once, machine-wide) and
+ * wait for the probe (and optional `ready:` gate) to accept. Throws infra-error
+ * when the appliance stays unreachable — with the start output when we tried.
+ */
+export async function ensureAppliance(name, spec, root, say) {
+    const timeoutMsEarly = (spec.timeout ?? 60) * 1000;
+    if (await probeTcp(spec.probe)) {
+        // An open TCP port is NOT readiness. Postgres accepts connections while
+        // still recovering; a container forwards the port before the server is
+        // listening. Returning 'up' here skipped the declared ready: gate entirely,
+        // so the bind proceeded against a half-started appliance and the failure
+        // surfaced later as an unrelated work-error.
+        if (!spec.ready)
+            return 'up';
+        const first = await sh(spec.ready, root);
+        if (first.code === 0)
+            return 'up';
+        say(`appliance '${name}' answers at ${spec.probe} but is not ready yet — waiting`);
+        if (await awaitUp(name, spec, root, now() + timeoutMsEarly))
+            return 'adopted';
+        throw new BrokerError('infra-error', `appliance '${name}' answers at ${spec.probe} but its ready: gate never passed within ${spec.timeout ?? 60}s`, 'appliance', first.output.slice(0, 800));
+    }
+    if (!spec.start) {
+        throw new BrokerError('infra-error', `appliance '${name}' unreachable at ${spec.probe} and declares no start: — bring it up yourself`, 'appliance');
+    }
+    const timeoutMs = (spec.timeout ?? 60) * 1000;
+    const deadline = now() + timeoutMs;
+    if (!acquireLock(spec.probe, spec.timeout)) {
+        // Someone else is starting it right now; wait for their result.
+        say(`appliance '${name}' is being started by another consumer — waiting`);
+        if (await awaitUp(name, spec, root, deadline))
+            return 'adopted';
+        throw new BrokerError('infra-error', `appliance '${name}' still unreachable at ${spec.probe} after waiting ${spec.timeout ?? 60}s for a concurrent start`, 'appliance');
+    }
+    try {
+        // Locked. Re-probe: it may have come up between our probe and the lock.
+        // Same rule as above — the ready: gate decides, not the open port.
+        if (await probeTcp(spec.probe) && (await awaitUp(name, spec, root, now() + 1000)))
+            return 'up';
+        say(`starting appliance '${name}'`);
+        const r = await sh(spec.start, root);
+        if (r.code !== 0) {
+            throw new BrokerError('infra-error', `appliance '${name}' start command failed`, 'appliance', r.output.slice(0, 800));
+        }
+        if (!(await awaitUp(name, spec, root, deadline))) {
+            throw new BrokerError('infra-error', `appliance '${name}' started but never answered at ${spec.probe} within ${spec.timeout ?? 60}s`, 'appliance', r.output.slice(0, 800));
+        }
+        return 'started';
+    }
+    finally {
+        releaseLock(spec.probe);
+    }
+}
+/** Explicit stop verb only — runly never stops an appliance on its own. */
+export async function stopAppliance(name, spec, root) {
+    if (!spec.stop) {
+        throw new BrokerError('work-error', `appliance '${name}' declares no stop: command`, 'appliance');
+    }
+    const r = await sh(spec.stop, root);
+    if (r.code !== 0) {
+        throw new BrokerError('infra-error', `appliance '${name}' stop command failed`, 'appliance', r.output.slice(0, 800));
+    }
+}
+//# sourceMappingURL=appliances.js.map

package/dist/drivers/appliances.js.map

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

package/dist/drivers/datastores.d.ts

@@ -0,0 +1,144 @@
+import { type DatastoreSpec } from '../core/manifest.js';
+export interface DsHandle {
+    envId: string;
+    /**
+     * Where the datastore's repo commands (create/drop/template_restore) run:
+     * the caller's worktree, which is where the environment runs (decision
+     * 0032). Teardown falls back to the environment's own directory when the
+     * worktree is already gone.
+     */
+    cwd: string;
+    dataDir: string;
+}
+export interface DsDriver {
+    readonly name: string;
+    /** The ns for an environment: sqlite = file path; server = SQL-safe db name. */
+    ns(h: DsHandle): string;
+    /** The connection string services/checks receive. */
+    url(h: DsHandle): string;
+    /** infra-error (never code blame) when the external server is unreachable. */
+    probe(): Promise<void>;
+    /** Create/restore the namespace at the preset. force = recreate even if present. */
+    ensure(h: DsHandle, preset: string, force: boolean, exists: boolean): Promise<void>;
+    /** Best-effort removal (recycle). */
+    drop(h: DsHandle): Promise<void>;
+    /**
+     * The drop as data, for a row that must be reapable without the manifest
+     * (a `runly db` copy, decision 0034): the already-templated command for a
+     * server datastore, or null when the namespace is a file under the state
+     * root (sqlite) — removing that is the engine's to do.
+     */
+    dropCommand(h: DsHandle): string | null;
+    /** True when the namespace is a local file (sqlite), false for a server database. */
+    readonly fileBased: boolean;
+    /**
+     * How to drop this namespace later without the manifest (decision 0037):
+     * the templated command and where to run it, or the file to delete.
+     */
+    dropRecipe(h: DsHandle): {
+        cmd?: string;
+        cwd?: string;
+        path?: string;
+        ns?: string;
+    };
+    /**
+     * The template a restore at `preset` uses, as `<stack>/<marker file>` under
+     * the templates root, or null when this datastore bakes none. Retention
+     * keeps a template while a row references it (decision 0037).
+     */
+    templateRef(preset: string): string | null;
+    /**
+     * Drop this datastore's CURRENT templates (every preset, the current
+     * template key) and their server-side databases, so the next restore bakes
+     * afresh. Only `--pristine` asks for this (decision 0039): a template whose
+     * key matches was baked from the same create command and trigger content,
+     * so an `@rebake-template` rule that fires only says which template is
+     * current — it never rebakes one that already exists.
+     */
+    rebake(cwd?: string): void | Promise<void>;
+    /** Is the template a restore at `preset` would use already baked? Always false without templates. */
+    templateBaked(preset: string): boolean;
+}
+/** Exclusive: bake, rebake, prune or drop the stack's templates. */
+export declare function withBakeLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/** Shared: restore from one of the stack's templates; no writer runs meanwhile. */
+export declare function withTemplateRead<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * One datastore's templates: the stack lock shared, then this datastore's lock
+ * — exclusive (`write`) to bake or drop one, shared to restore from one. The
+ * order is always stack, then datastore, and nothing waits for the stack lock
+ * while holding a datastore lock, so the two levels cannot deadlock.
+ */
+export declare function withDatastoreLock<T>(stackId: string, ds: string, write: boolean, fn: () => Promise<T>): Promise<T>;
+/**
+ * Baked-template markers are self-describing (vetbill-1i49): they carry the
+ * server-side template ns AND the already-templated drop command, so
+ * retention/rebake can DROP the actual database when the marker is pruned —
+ * previously only the marker file was deleted and `backlot_tpl_*` databases
+ * leaked on the appliance forever. Legacy markers (bare ns string) still
+ * parse; they just can't be dropped server-side.
+ */
+export interface BakedMarker {
+    v: 1;
+    ns: string;
+    drop: string | null;
+    /** The datastore it was baked for (0.18+), so a rebake drops only that datastore's. */
+    ds?: string;
+    /**
+     * When, and by which bake (0.19): two bakes of one key write different
+     * markers, so a restore that failed can tell a sibling's rebake from the
+     * template it failed on — the content alone is deterministic.
+     */
+    bakedAt?: number;
+    nonce?: string;
+    /** In `<name>@shared/` (0.20, decision 0044). */
+    shared?: boolean;
+    /** A `--pristine` bake private to one worktree of a shared datastore (0.20). */
+    private?: boolean;
+    /** The stack dir a shared marker was adopted from, naming its database (0.20). */
+    adoptedFrom?: string;
+}
+export declare function parseBakedMarker(content: string): BakedMarker;
+export declare function hasOtherTemplateOwner(full: string, ns: string): boolean;
+/**
+ * Shared templates (decision 0044). A template whose key folds in the content
+ * of its `@rebake-template` trigger files is a function of (manifest name,
+ * datastore, preset, create command, trigger content) — never of the worktree
+ * path — so every worktree of one manifest name on this daemon can restore
+ * from the same one. They live in `<name>@shared/` next to the per-stack dirs
+ * (`<name>-<8 chars>`); a manifest name cannot contain `@`, so the two never
+ * collide.
+ */
+export declare const SHARED_TEMPLATE_SUFFIX = "@shared";
+export declare const sharedTemplateDir: (project: string) => string;
+export declare const isSharedTemplateDir: (dir: string) => boolean;
+/** The manifest name a templates dir belongs to: `<name>@shared`, or a stack id `<name>-<8-char hash>`. */
+export declare function templateProject(dir: string): string;
+/**
+ * A template baked by `--pristine` for one worktree of a shared datastore
+ * (decision 0044): `<ds>-<preset>@<key>.own.<ext>` in the stack's own dir. It
+ * outranks the shared one for that worktree while it exists, and retention
+ * keeps it only while a row references it.
+ */
+export declare const PRIVATE_TEMPLATE_TAG = ".own";
+export declare const isPrivateTemplateFile: (file: string) => boolean;
+/** How a datastore's templates are scoped. */
+export interface TemplateScope {
+    /** Content bake key: the `@rebake-template` trigger content (vetbill-1i49). */
+    bakeKey?: string;
+    /**
+     * The manifest name. With a bake key and without `share_templates: false`,
+     * the templates are shared by every worktree of this name (decision 0044).
+     * Omitted: per stack, as before 0.20.
+     */
+    project?: string;
+    /** `--pristine` on a shared datastore: bake a template private to this worktree instead of dropping the shared one. */
+    privateBake?: boolean;
+}
+/** Whether a datastore's templates are shared across worktrees (decision 0044). */
+export declare function sharesTemplates(spec: DatastoreSpec, scope: TemplateScope): boolean;
+/**
+ * `scope` is the template scope; a bare string is the bake key alone (per
+ * stack, as before 0.20 — unit tests and callers that only read the url).
+ */
+export declare function makeDatastore(name: string, spec: DatastoreSpec, stackId: string, scope?: string | TemplateScope): DsDriver;