@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/infrastructure/host-inspection.d.ts

@@ -0,0 +1,223 @@
+/**
+ * What a host looks like, for the services a stack declares — read, never
+ * changed.
+ *
+ * `provisionStack` observes, plans and APPLIES a node's host services in one
+ * call; there was no way to ask for the first two alone. On the test node
+ * that left one way to learn what a deployment would do to a server holding
+ * a mainnet chain — which unit it would write, whether it would restart a
+ * node mid-sync, what it would refuse — and the way was to deploy. Nor any
+ * other way to read the host: it takes SSH by password only, and the
+ * password does not leave the vault.
+ *
+ * Nothing here writes, and nothing returns a file's content: a config holds
+ * an `rpcauth` line, a unit's command line can hold a login. What comes back
+ * is the shape — present or not, matching or differing, whose, how big — and
+ * the plan a deployment would carry out.
+ */
+import type { NetworkInterfaceInfo } from 'node:os';
+import { type Provisioning } from './service-binding.js';
+import { type HostRunner } from './bare-metal-runner.js';
+import type { IServiceOverride, IServiceRequirement } from './types.js';
+export interface HostInspectionRequest {
+    /** The services the stack declares — as a deployment would send them. */
+    services: Record<string, IServiceRequirement>;
+    /** The stack's overrides, their references resolved by the master. */
+    overrides?: Record<string, IServiceOverride> | undefined;
+    /** Units to read beyond the declared ones — one a person wrote, say. */
+    units?: string[] | undefined;
+    /** Paths to measure: exists, owner, size, the room on their filesystem. */
+    paths?: string[] | undefined;
+    /** Snap packages: installed, and which version. */
+    snaps?: string[] | undefined;
+    /** `key=value` files and the keys wanted from each; a key naming a credential is refused. */
+    configKeys?: Array<{
+        path: string;
+        keys: string[];
+    }> | undefined;
+}
+export type FileState = 'absent' | 'matches' | 'differs' | 'not-managed' | 'not-declared';
+export interface DiskReading {
+    mount: string;
+    sizeBytes: number;
+    availBytes: number;
+}
+export interface UnitReading {
+    unit: string;
+    known: boolean;
+    active: boolean;
+    enabled: boolean;
+    /**
+     * systemd's own words — `active (running)`, `activating (start)`,
+     * `failed (exit-code)` — where `active` above is one bit of them. The test
+     * node's bitcoind read «inactive» while its chain advanced, and a bit
+     * could not say which of five states it was in (2026-09-23).
+     */
+    state: string;
+    /** `Result`: `success`, or how it last ended — `exit-code`, `timeout`, `signal`… */
+    result: string;
+    mainPid: number | null;
+    restarts: number | null;
+    /** When it last entered `active`. */
+    since: string | null;
+    /** Its cgroup, which every process it runs is inside. */
+    cgroup: string | null;
+    fragmentPath: string | null;
+    /** The command line, with the value after any `password=`, `login=` or `auth=` struck out. */
+    execStart: string | null;
+    /** Jobs systemd has pending — this unit's, and those it waits on — as `systemctl list-jobs` prints them. */
+    jobs: string[];
+    /** Its last journal lines, with every credential struck out as a command line's is. */
+    journal: string[];
+    /** Processes running its program, and whether each is inside it. */
+    processes: Array<{
+        pid: number;
+        cgroup: string | null;
+        inUnit: boolean;
+    }>;
+}
+export interface ProbeReading {
+    method: string;
+    ok: boolean;
+    /** The answer's scalar fields: height, target height, synchronized, version. */
+    result?: Record<string, string | number | boolean>;
+    /** The fields its declaration reads the answer by (`healthCheck.jsonrpc.report`). */
+    report?: string[];
+    error?: string;
+}
+/**
+ * The fields of an answer worth a line: those its declaration names, in its
+ * order — or, naming none, the first dozen short ones — and how many more
+ * `--json` holds.
+ *
+ * The first `infra inspect` of the test node printed monerod's fields as
+ * they came, `adjusted_time` to `database_size`, and cut off the network,
+ * height and sync state the probe had been sent for (2026-09-23).
+ */
+export declare function probeFields(reading: ProbeReading): {
+    fields: Array<[string, string | number | boolean | undefined]>;
+    more: number;
+};
+export interface HostServiceReading {
+    name: string;
+    provisioning: Provisioning;
+    networkMode?: string | undefined;
+    /** An `external` service: its declared address, as this node sees it. */
+    external?: {
+        host: string;
+        port: number | null;
+        /** The address is one of this node's own, or loopback. */
+        local: boolean;
+        reachable: boolean;
+        probe?: ProbeReading | undefined;
+    };
+    /** A `bareMetal` service: what is there, and what a deployment would do. */
+    onHost?: {
+        installed: boolean;
+        userExists: boolean;
+        dataDir: {
+            path: string;
+            exists: boolean;
+            owner: string | null;
+            disk: DiskReading | null;
+        } | null;
+        /** `active` is the plan's bit — up, or on its way; `state` is systemd's words for it. */
+        unit: {
+            name: string;
+            known: boolean;
+            active: boolean;
+            enabled: boolean;
+            state: string;
+        } | null;
+        config: FileState;
+        unitFile: FileState;
+        actions: string[];
+        refusals: string[];
+        /** Its declared health check, asked on loopback — where its applications reach it. */
+        probe?: ProbeReading | undefined;
+    };
+}
+export interface HostInspection {
+    interfaces: Array<{
+        name: string;
+        address: string;
+        family: string;
+        internal: boolean;
+    }>;
+    /** The machine's memory as its kernel counts it; null where there is no `/proc/meminfo`. */
+    memory: MemoryReading | null;
+    services: HostServiceReading[];
+    units: UnitReading[];
+    paths: Array<{
+        path: string;
+        exists: boolean;
+        owner: string | null;
+        sizeBytes: number | null;
+        disk: DiskReading | null;
+    }>;
+    snaps: Array<{
+        name: string;
+        installed: boolean;
+        version: string | null;
+        revision: string | null;
+    }>;
+    configKeys: Array<{
+        path: string;
+        exists: boolean;
+        values: Record<string, string | null>;
+        refused: string[];
+    }>;
+}
+export interface MemoryReading {
+    totalBytes: number;
+    /** `MemAvailable`: what can be taken without swapping, reclaimable cache counted in — the kernel's estimate. */
+    availableBytes: number;
+    swapTotalBytes: number;
+    swapFreeBytes: number;
+}
+/** What the inspection needs of the machine, so a court can be one. */
+export interface InspectionDeps {
+    host: HostRunner;
+    interfaces: () => NodeJS.Dict<NetworkInterfaceInfo[]>;
+    reach: (host: string, port: number) => Promise<boolean>;
+    jsonRpc: (url: string, method: string, auth: RpcAuth | null) => Promise<ProbeReading>;
+}
+export interface RpcAuth {
+    type: 'basic' | 'digest';
+    user: string;
+    password: string;
+}
+export declare function inspectHost(request: HostInspectionRequest, deps: InspectionDeps): Promise<HostInspection>;
+/** How a file on the host stands against the one a deployment would write — never its content. */
+export declare function fileState(wanted: string | undefined, current: string | null): FileState;
+export declare function isLocal(host: string, own: ReadonlySet<string>): boolean;
+/**
+ * A command line with every credential struck out and every flag kept.
+ *
+ * Two forms: `-rpcpassword=x` and `--rpc-login user:password` — the value
+ * after a space. Only the first was struck out, and the test node's
+ * monero-walletd unit passes both of its logins the second way: the first
+ * `infra inspect` of it printed a mainnet RPC password in the clear
+ * (2026-09-23).
+ */
+export declare function redactArgv(argv: string): string;
+/** TCP, with a deadline: an address that answers nothing is not reachable. */
+export declare function reachTcp(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * One JSON-RPC 2.0 call, over HTTP basic or digest authentication.
+ *
+ * Digest because monerod speaks nothing else, and implemented here rather
+ * than by running `curl --digest -u user:password`: a password on a command
+ * line is in the node's process table for as long as the call takes.
+ *
+ * The answer goes on the connection the challenge came on: monerod keeps a
+ * nonce per connection, and `fetch` sent the two requests on two — the first
+ * `infra inspect` of the test node read HTTP 401 from its daemon and its
+ * wallet (2026-09-23). Measured against the dev stack's monerod and
+ * wallet-rpc, the same answer is 200 on the challenge's socket, 401 on
+ * another.
+ */
+export declare function jsonRpcCall(url: string, method: string, auth: RpcAuth | null, timeoutMs?: number): Promise<ProbeReading>;
+/** RFC 7616 with MD5 or MD5-sess and `qop=auth` — what monerod offers. */
+export declare function digestAuthorization(challenge: string, auth: RpcAuth, httpMethod: string, uri: string, cnonce?: string): string;
+//# sourceMappingURL=host-inspection.d.ts.map

package/dist/infrastructure/host-inspection.d.ts.map

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