@omnitron-dev/omnitron 0.1.3 → 0.3.0

package/dist/infrastructure/config-payload.js

@@ -0,0 +1,235 @@
+/**
+ * A container's configuration files, carried to the node that will run it.
+ *
+ * A stack's gateway is configured by files — an nginx template, an entrypoint,
+ * Lua modules, a maintenance page — and the resolver mounts them from the
+ * MASTER's filesystem: `${projectRoot}/infra/nginx/...`. That works while the
+ * container runs on the master.
+ *
+ * On a node it cannot. The node has no copy of the project: measured on the
+ * test server, `ls -d /root/daos /opt/daos` finds nothing, and
+ * `daos-test-gateway` came up with an empty `Mounts` array, a null entrypoint,
+ * zero `UPSTREAM_*` variables and the stock `default.conf` baked into the
+ * image. Its onion answered HTTP 200 with `Welcome to OpenResty!` — the
+ * gateway's own page, because the gateway had never been told what to proxy.
+ *
+ * So the files travel with the request that asks for the container. They are
+ * small — the daos gateway's six files are 65 KB — and they are text that
+ * already crosses the wire as part of a config; carrying them is cheaper than
+ * the alternatives (a git checkout on every node, a second image per stack, a
+ * shared filesystem) and has no state to drift.
+ *
+ * The node writes them under its own root and mounts its own copies, so a
+ * container's spec on a node names paths that exist on that node. Nothing
+ * here reaches back to the master at container start.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Directory names a config payload must never descend into, and file
+ * extensions it must never carry.
+ *
+ * Checked against EVERY segment, not the path as a whole. My first version
+ * anchored on `$`, so it caught `.git` and missed `.git/config` — which is the
+ * only spelling anyone would actually send, since a bare directory has no
+ * content to travel. A denylist that matches the shape nobody writes is a
+ * denylist that does nothing.
+ */
+const REFUSED_SEGMENTS = new Set(['.git', 'node_modules', '.svn', '.hg']);
+const REFUSED_FILE = /^(\.env(\..*)?|.*\.(key|pem|p12|pfx|crt|cer))$/i;
+/**
+ * Whether a relative path is safe to write under a root.
+ *
+ * A payload arrives over RPC from another daemon, and a path is the one field
+ * that can leave the directory it is supposed to stay in. Absolute paths,
+ * `..` segments and anything resolving above the root are refused rather than
+ * sanitised: a path that needed fixing was not the path the sender meant, and
+ * silently rewriting it turns a mistake into a different file.
+ */
+export function isSafeRelativePath(p) {
+    if (!p || p.length > 255)
+        return false;
+    if (p.startsWith('/') || p.startsWith('\\'))
+        return false;
+    if (/^[a-zA-Z]:/.test(p))
+        return false;
+    const segments = p.split('/');
+    if (segments.some((s) => s === '' || s === '.' || s === '..'))
+        return false;
+    if (segments.some((s) => s.includes('\0')))
+        return false;
+    if (segments.some((s) => REFUSED_SEGMENTS.has(s.toLowerCase())))
+        return false;
+    return !REFUSED_FILE.test(segments[segments.length - 1] ?? '');
+}
+/**
+ * Octal mode strings this accepts.
+ *
+ * Exactly four octal digits, and the first — the setuid/setgid/sticky digit —
+ * must be `0`. A config file has no business carrying setuid, and a payload
+ * that asks for it is either a mistake or an attempt.
+ *
+ * My first version of this read `!/^0[4267]/`, which tests the second digit —
+ * the OWNER permission — so it rejected every ordinary mode (`0644`, `0755`,
+ * `0600`) and accepted `0111`. It was wrong in both directions at once, and
+ * only running it on real values showed that: the regex looked right, and a
+ * predicate that looks right is the kind that ships.
+ */
+export function isSafeMode(mode) {
+    return /^0[0-7]{3}$/.test(mode);
+}
+/**
+ * A fingerprint of a service's files.
+ *
+ * Folded into the container's spec hash by the caller, so a changed template
+ * recreates the container. Without it a corrected nginx.conf reaches the node,
+ * is written to disk, and the container that has the old one mounted keeps
+ * running with it — the same shape as a corrected health check that never
+ * reaches anything already running.
+ */
+export function configFilesHash(files) {
+    const h = createHash('sha256');
+    for (const f of [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+        h.update(f.path).update('\0').update(f.mode).update('\0').update(f.content).update('\0');
+    }
+    return h.digest('hex').slice(0, 16);
+}
+/** Total bytes of a payload, for the bound the transport needs. */
+export function payloadBytes(payload) {
+    let total = 0;
+    for (const files of Object.values(payload)) {
+        for (const f of files)
+            total += Buffer.byteLength(f.content, 'utf-8') + f.path.length;
+    }
+    return total;
+}
+/**
+ * The most a payload may carry, in bytes.
+ *
+ * Config files are text and few. A directory that grew a build output, a log
+ * or a data file is not a config directory any more, and shipping it through
+ * an RPC call would turn one provisioning request into a transfer nobody
+ * budgeted for. The daos gateway, the largest real one, is 65 KB.
+ */
+export const MAX_PAYLOAD_BYTES = 2 * 1024 * 1024;
+/**
+ * Validate a payload received over RPC.
+ *
+ * Returns the reasons it is not acceptable — empty means it is. Every check is
+ * on the RECEIVING side, because that is the side that has to live with the
+ * answer: a sender that has been tampered with, or is simply older, is exactly
+ * the case where the sender's own validation is not evidence.
+ */
+export function validatePayload(payload) {
+    const problems = [];
+    if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) {
+        return ['config payload must be an object keyed by service name'];
+    }
+    let bytes = 0;
+    for (const [service, files] of Object.entries(payload)) {
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(service)) {
+            problems.push(`'${service}' is not a service name`);
+            continue;
+        }
+        if (!Array.isArray(files)) {
+            problems.push(`${service}: expected a list of files`);
+            continue;
+        }
+        for (const entry of files) {
+            const f = entry;
+            if (typeof f?.path !== 'string' || typeof f?.content !== 'string' || typeof f?.mode !== 'string') {
+                problems.push(`${service}: a file entry is missing path, content or mode`);
+                continue;
+            }
+            if (!isSafeRelativePath(f.path))
+                problems.push(`${service}: refusing path '${f.path}'`);
+            if (!isSafeMode(f.mode))
+                problems.push(`${service}: refusing mode '${f.mode}' for '${f.path}'`);
+            bytes += Buffer.byteLength(f.content, 'utf-8');
+        }
+    }
+    if (bytes > MAX_PAYLOAD_BYTES) {
+        problems.push(`config payload is ${Math.round(bytes / 1024)} KB, over the ${MAX_PAYLOAD_BYTES / 1024} KB limit`);
+    }
+    return problems;
+}
+/**
+ * Where a node keeps the config files a master sent it.
+ *
+ * Under the daemon's own home, partitioned by project and stack, because two
+ * stacks on one node have two gateways with two different templates and the
+ * only thing distinguishing them is which stack asked. Same reasoning as the
+ * container prefix: without it the second stack overwrites the first's
+ * configuration and reconciles a container towards a spec nobody declared.
+ */
+export function nodeConfigRoot(home, project, stack, service) {
+    const safe = (s) => (/^[a-z0-9][a-z0-9-]{0,63}$/i.test(s) ? s : 'unknown');
+    return `${home}/.omnitron/stack-config/${safe(project)}/${safe(stack)}/${safe(service)}`;
+}
+/**
+ * Write one service's files under a root, and report where they landed.
+ *
+ * Validated first, entirely, before anything is written: a payload with one
+ * bad path must not leave half a configuration on disk, because a gateway
+ * that starts with four of its six files is worse than one that does not
+ * start — it serves something, and what it serves is nobody's intention.
+ *
+ * Files this wrote before and are no longer in the payload are removed, so a
+ * Lua module deleted upstream stops being mounted here. A stale file in a
+ * config directory is read by the thing that globs the directory, which is how
+ * a removed rule keeps applying.
+ */
+export async function writeConfigFiles(root, files, host, remove, list) {
+    const problems = validatePayload({ service: files });
+    if (problems.length > 0)
+        throw new Error(problems.join('; '));
+    const written = [];
+    for (const f of files) {
+        await host.writeFile(`${root}/${f.path}`, f.content, { mode: f.mode });
+        written.push(f.path);
+    }
+    const keep = new Set(written);
+    for (const existing of await list(root)) {
+        if (!keep.has(existing))
+            await remove(`${root}/${existing}`);
+    }
+    return { root, written };
+}
+/**
+ * Read a service's config directory into a payload, on the master.
+ *
+ * Walks the directory the resolver would have mounted. Refused paths are
+ * skipped with a reason rather than aborting: a project that happens to have
+ * a `.git` inside its nginx directory should still get a working gateway, and
+ * the operator should be told what was left behind.
+ */
+export async function readConfigDirectory(dir, fs) {
+    const files = [];
+    const skipped = [];
+    async function walk(prefix) {
+        const entries = await fs.readdir(prefix ? `${dir}/${prefix}` : dir);
+        for (const entry of entries) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!isSafeRelativePath(rel)) {
+                    skipped.push(rel);
+                    continue;
+                }
+                await walk(rel);
+                continue;
+            }
+            if (!isSafeRelativePath(rel)) {
+                skipped.push(rel);
+                continue;
+            }
+            const full = `${dir}/${rel}`;
+            // The mode comes off the file: an entrypoint is executable because
+            // someone made it so, and a payload that flattened everything to 0644
+            // would ship a script the container cannot run.
+            const { mode } = await fs.stat(full);
+            files.push({ path: rel, content: await fs.readFile(full), mode: `0${(mode & 0o777).toString(8).padStart(3, '0')}` });
+        }
+    }
+    await walk('');
+    return { files, skipped };
+}
+//# sourceMappingURL=config-payload.js.map

package/dist/infrastructure/config-payload.js.map

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

package/dist/infrastructure/container-runtime.d.ts

@@ -8,18 +8,141 @@
  * All Omnitron-managed containers are labeled with `omnitron.managed=true`.
  */
 import type { ContainerState, ResolvedContainer } from './types.js';
+/** Label carrying the desired-spec fingerprint, used for config-drift detection. */
+export declare const SPEC_HASH_LABEL = "omnitron.spec-hash";
+/**
+ * Stable fingerprint of a container's *desired* spec. Covers the fields that a
+ * config edit can change and that require a recreate to apply (image, env,
+ * ports, volumes, command/entrypoint, extraHosts). Deliberately EXCLUDES
+ * labels — the spec-hash label is derived from this, and docker-compose adds
+ * label noise — so the hash is stable across recreations of an unchanged spec.
+ *
+ * Stamped as a label at create time and compared on reconcile so that an env
+ * change (e.g. the Tor hidden-service target) triggers a recreate instead of
+ * being silently ignored because the image is unchanged.
+ */
+export declare function containerSpecHash(config: ResolvedContainer): string;
+/**
+ * How many containers this host's Docker holds, by state — every container,
+ * not only omnitron's.
+ *
+ * One `docker ps`, the CLI the rest of this file speaks, with a timeout that
+ * ends it. The system snapshot asked Docker through systeminformation's
+ * socket client instead, which sends `GET /info HTTP/1.0` and waits for the
+ * connection to close; OrbStack answers `HTTP/1.1 200` and keeps it open, so
+ * every question hung until the library's own timeout — measured 2026-09-23:
+ * no answer in 20 s where `curl` on the same socket took 0.055 s — and left
+ * its socket open behind it.
+ */
+export declare function countContainersByState(timeoutMs?: number): Promise<{
+    running: number;
+    paused: number;
+    stopped: number;
+}>;
 /**
  * Check if Docker daemon is available.
  */
 export declare function isDockerAvailable(): Promise<boolean>;
 /**
  * List all Omnitron-managed containers.
+ *
+ * `[]` when Docker cannot be asked, which is right for a listing and wrong for
+ * a health check: «nothing is running» and «Docker did not answer» are
+ * different states. `orThrow` keeps them apart.
  */
-export declare function listManagedContainers(): Promise<ContainerState[]>;
+export declare function listManagedContainers(options?: {
+    orThrow?: boolean;
+}): Promise<ContainerState[]>;
 /**
  * Get state of a specific container by name.
  */
 export declare function getContainerState(name: string): Promise<ContainerState | null>;
+/**
+ * One `-p` value.
+ *
+ * `9800:80` publishes on every INTERFACE — Docker's default, and Docker's
+ * iptables rules are inserted ahead of the host firewall's, so such a port is
+ * reachable from the network no matter what `ufw status` says.
+ *
+ * An omission therefore used to mean the widest possible answer. This is the
+ * single place a published port becomes a docker argument, and it now reads an
+ * absent `bindHost` as loopback: a container that must be reachable says so,
+ * with `bindHost: '0.0.0.0'`, in a line someone can see in a diff.
+ *
+ * `applyManagedDefaults` fills the same field in the resolver, and should —
+ * that is what puts the binding into `containerSpecHash`, so changing it
+ * recreates the container instead of leaving the old one published. But a
+ * default that every resolver must remember is a default that one of them
+ * will not: `resolveGateway` was the one return of four that did not call it,
+ * and the gateway is the container that faces outward. Measured on the dev
+ * stand: `daos-dev-gateway` published on 0.0.0.0:80 while the other ten
+ * managed containers were all on 127.0.0.1, and a browser on the LAN could
+ * sign in. Defence in depth, because the resolver-side default is the one
+ * that can be forgotten and this one cannot.
+ */
+export declare function portArg(p: {
+    host: number;
+    container: number;
+    bindHost?: string;
+}): string;
+/**
+ * Docker state left over from a container that is gone.
+ *
+ * An orphaned libnetwork endpoint, or a `Created` husk holding the name.
+ * Both are scrubbed and the run retried.
+ */
+export declare function isStaleContainerState(message: string): boolean;
+/**
+ * A port whose previous holder has not let go yet.
+ *
+ * `docker rm` returns before the kernel releases the bind its docker-proxy
+ * held, so removing a container and immediately recreating it races that
+ * release. Measured on a node recreating postgres, redis and minio at once:
+ * all three failed this way, each left in `Created`, and `docker start` by
+ * hand a second later worked — which is what makes it a race rather than a
+ * conflict, and a retry the right answer rather than a louder error.
+ *
+ * Narrow on purpose. A missing image, a bad flag, or a port genuinely held
+ * by something else is permanent, and retrying it turns one clear error into
+ * several identical ones separated by delays.
+ */
+export declare function isPortNotYetReleased(message: string): boolean;
+/**
+ * Which container holds a host port, if any.
+ *
+ * `port is already allocated` is true and useless: it names the port and
+ * withholds the only thing an operator can act on. Measured on a node where
+ * three services would not start —
+ *
+ *     Bind for 127.0.0.1:5432 failed: port is already allocated
+ *
+ * — and the holder was `omnitron-postgres`, a container from an earlier
+ * naming of the same stack that the reconciler had stopped recognising and
+ * therefore stopped managing. Nothing in the failure said that, and nothing
+ * else would: the reconciler converges the containers it can name, and a
+ * container it no longer names is invisible to it while remaining very
+ * visible to the kernel.
+ *
+ * Answers null when nothing holds it, which is its own information: the
+ * bind failed for another reason.
+ */
+export declare function containerHoldingPort(hostPort: number): Promise<string | null>;
+/**
+ * Explain a bind failure by naming what is holding the port.
+ *
+ * Kept separate from the retry because it answers a different question:
+ * the retry asks "will this resolve on its own", and this asks "if not,
+ * what do I tell the operator".
+ */
+export declare function describeBindFailure(config: {
+    name: string;
+    ports: Array<{
+        host: number;
+        bindHost?: string | undefined;
+    }>;
+}, original: string, 
+/** The lookup, as a parameter so this is answerable without a docker. */
+lookup?: (hostPort: number) => Promise<string | null>): Promise<string>;
 /**
  * Create and start a container from a resolved config.
  */
@@ -48,10 +171,34 @@ export declare function execInContainer(nameOrId: string, command: string[]): Pr
  * Wait for container health check to pass.
  */
 export declare function waitForHealthy(name: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Create a Docker bridge network if it doesn't exist.
+ *
+ * Idempotent — `docker network create` exits non-zero with a recognisable
+ * "already exists" message when the network is present; we swallow that
+ * specific case and propagate everything else. Done via execFile rather
+ * than the adapter because the adapter doesn't expose network APIs and
+ * the call is rare (once per daemon startup per network).
+ */
+export declare function ensureNetwork(name: string): Promise<void>;
 /**
  * Create a Docker volume if it doesn't exist.
  */
 export declare function createVolume(name: string): Promise<void>;
+/**
+ * Does a Docker volume exist?
+ *
+ * The question behind this one is "does this service already hold state
+ * initialised with some other password" — a Postgres data directory keeps
+ * the password it was created with and ignores `POSTGRES_PASSWORD`
+ * thereafter, so a volume is the difference between a first provision and
+ * one that would lock an application out of its own database.
+ *
+ * `docker volume inspect` rather than listing and filtering: the answer is
+ * about one name, and a list is a different question that happens to
+ * contain it.
+ */
+export declare function volumeExists(name: string): Promise<boolean>;
 /**
  * Get container logs.
  */
@@ -60,4 +207,35 @@ export declare function getContainerLogs(nameOrId: string, tail?: number): Promi
  * Dispose the adapter (cleanup).
  */
 export declare function disposeEngine(): Promise<void>;
+/**
+ * Why a container is not running, in the words Docker already has.
+ *
+ * `ContainerState.error` has been part of the type all along and nothing ever
+ * filled it, while `docker inspect` carries both the exit code and a
+ * human-readable reason. So `omnitron doctor` could say "Container
+ * omnitron-nginx is created" and no more, when the answer was sitting one
+ * field away: "Bind for 0.0.0.0:9800 failed: port is already allocated".
+ *
+ * A container that is running, or that exited cleanly because it was asked
+ * to, has nothing to report — returning something there would turn a normal
+ * stop into a finding.
+ */
+declare function describeContainerFailure(state?: {
+    Status?: string;
+    ExitCode?: number;
+    Error?: string;
+    OOMKilled?: boolean;
+}): string | undefined;
+/**
+ * Exported for tests only.
+ *
+ * `describeContainerFailure` is a pure function over an inspect payload, and
+ * the payloads worth testing are the ones a live Docker will not produce on
+ * demand — a refused port bind, an OOM kill.
+ */
+export declare const __test__: {
+    describeContainerFailure: typeof describeContainerFailure;
+    portArg: typeof portArg;
+};
+export {};
 //# sourceMappingURL=container-runtime.d.ts.map

package/dist/infrastructure/container-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container-runtime.d.ts","sourceRoot":"","sources":["../../src/infrastructure/container-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAmB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmBrF;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO1D;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CA6BvE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAiBpF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwFhF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9D;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1F;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9D;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAKnD"}
+{"version":3,"file":"container-runtime.d.ts","sourceRoot":"","sources":["../../src/infrastructure/container-runtime.ts"],"names":[],"mappings":"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"}