hive-am 1.1.0 → 1.2.0

package/server/dist/objects/model.js

@@ -0,0 +1,250 @@
+/**
+ * Objects of a colony: things that are not agents but live next to them. A server is a command that hive-am keeps running; a Docker
+ * object is a container (or a compose project) that hive-am starts, stops and reads the logs of.
+ */
+import { parseProps } from './driver-props.js';
+import { DomainError } from '../errors.js';
+export class ObjectError extends DomainError {
+}
+export const DB_ENGINES = {
+    mysql: { label: 'MySQL / MariaDB', port: 3306 }, postgresql: { label: 'PostgreSQL', port: 5432 }, sqlite: { label: 'SQLite', port: 0 }, mssql: { label: 'SQL Server', port: 1433 },
+};
+export const NAME_MAX = 60;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PORT_SPEC = /^((\d{1,3}\.){3}\d{1,3}:)?\d{1,5}:\d{1,5}(\/(tcp|udp))?$/;
+const IMAGE = /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,199}$/;
+const CONTAINER = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const PROJECT = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+const str = (v, what, max = 2000) => {
+    if (typeof v !== 'string')
+        throw new ObjectError(`${what} must be text`);
+    if (v.includes('\0') || v.length > max)
+        throw new ObjectError(`${what} is not valid`);
+    return v.trim();
+};
+const optStr = (v, what, max) => (v === undefined || v === null || v === '' ? undefined : str(v, what, max));
+const port = (v, what) => {
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1 || n > 65535)
+        throw new ObjectError(`${what} must be a port between 1 and 65535`);
+    return n;
+};
+const env = (v) => {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'object' || Array.isArray(v))
+        throw new ObjectError('Environment variables must be NAME: value pairs');
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (!ENV_KEY.test(k))
+            throw new ObjectError(`"${k}" is not a valid variable name`);
+        out[k] = str(String(val ?? ''), `Value of ${k}`, 4000);
+    }
+    return Object.keys(out).length ? out : undefined;
+};
+const list = (v, what, each) => {
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v))
+        throw new ObjectError(`${what} must be a list`);
+    const out = v.map((x) => each(str(x, what))).filter(Boolean);
+    if (out.length > 50)
+        throw new ObjectError(`${what} has too many entries`);
+    return out.length ? out : undefined;
+};
+const oneOf = (v, list, what) => {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    if (!list.includes(v))
+        throw new ObjectError(`${what} is not valid`);
+    return v;
+};
+const num = (v, what, min, max) => {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < min || n > max)
+        throw new ObjectError(`${what} must be between ${min} and ${max}`);
+    return n;
+};
+export function parseHealth(h) {
+    if (!h || !h.target)
+        return undefined;
+    const kind = oneOf(h.kind, ['http', 'tcp', 'command'], 'The kind of health check');
+    if (!kind)
+        throw new ObjectError('Choose the kind of health check');
+    const target = str(h.target, 'The health check target', 1000);
+    if (kind === 'http' && !/^https?:\/\//i.test(target))
+        throw new ObjectError('The health check URL must start with http:// or https://');
+    if (kind === 'tcp' && !/^((\d{1,3}\.){3}\d{1,3}:|localhost:)?\d{1,5}$/.test(target))
+        throw new ObjectError('The health check port must be a number or host:port');
+    return { kind, target, intervalSec: num(h.intervalSec, 'The interval', 2, 3600), timeoutSec: num(h.timeoutSec, 'The timeout', 1, 120), retries: num(h.retries, 'The retries', 1, 20), restartWhenUnhealthy: h.restartWhenUnhealthy ? true : undefined };
+}
+export function parseServer(c) {
+    const start = str(c?.start, 'The start command');
+    if (!start)
+        throw new ObjectError('Write the command that starts it');
+    const cwd = str(c?.cwd, 'The folder');
+    if (!cwd.startsWith('/'))
+        throw new ObjectError('The folder must be an absolute path');
+    return {
+        cwd, start, stop: optStr(c?.stop, 'The stop command'), env: env(c?.env), port: c?.port === undefined || c?.port === null || c?.port === '' ? undefined : port(c.port, 'The port'),
+        restart: oneOf(c?.restart, ['no', 'on-failure', 'always'], 'The restart policy'), maxRestarts: num(c?.maxRestarts, 'The restart limit', 1, 100),
+        health: parseHealth(c?.health), stopTimeoutSec: num(c?.stopTimeoutSec, 'The stop timeout', 1, 300), logMaxMb: num(c?.logMaxMb, 'The log size', 0.05, 500),
+    };
+}
+export function parseDocker(c) {
+    const mode = c?.mode;
+    if (mode !== 'container' && mode !== 'compose' && mode !== 'existing')
+        throw new ObjectError('Choose how the container is managed: create it, compose, or an existing one');
+    if (mode === 'existing') {
+        const container = str(c?.container, 'The container');
+        if (!CONTAINER.test(container))
+            throw new ObjectError('The container name is not valid');
+        return { mode, container, stopTimeoutSec: num(c?.stopTimeoutSec, 'The stop timeout', 1, 300) };
+    }
+    if (mode === 'compose') {
+        const file = str(c?.file, 'The compose file');
+        if (!file.startsWith('/'))
+            throw new ObjectError('The compose file must be an absolute path');
+        const project = optStr(c?.project, 'The project name');
+        if (project && !PROJECT.test(project))
+            throw new ObjectError('The project name must be lowercase letters, digits, - or _');
+        return { mode, file, project, stopTimeoutSec: num(c?.stopTimeoutSec, 'The stop timeout', 1, 300), services: list(c?.services, 'Services', (s) => { if (!CONTAINER.test(s))
+                throw new ObjectError(`"${s}" is not a valid service name`); return s; }) };
+    }
+    const image = str(c?.image, 'The image');
+    if (!IMAGE.test(image))
+        throw new ObjectError('The image name is not valid');
+    const restart = optStr(c?.restart, 'The restart policy');
+    if (restart && !['no', 'always', 'unless-stopped', 'on-failure'].includes(restart))
+        throw new ObjectError('Unknown restart policy');
+    return {
+        mode, image, restart: restart, command: optStr(c?.command, 'The command'), env: env(c?.env),
+        memory: ((v) => { if (v && !/^\d+(\.\d+)?[bkmg]?$/i.test(v))
+            throw new ObjectError('The memory limit must look like 512m or 1g'); return v; })(optStr(c?.memory, 'The memory limit', 20)),
+        cpus: num(c?.cpus, 'The CPU limit', 0.01, 256), network: ((v) => { if (v && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(v))
+            throw new ObjectError('The network name is not valid'); return v; })(optStr(c?.network, 'The network', 64)),
+        stopTimeoutSec: num(c?.stopTimeoutSec, 'The stop timeout', 1, 300), logMaxMb: num(c?.logMaxMb, 'The log size', 0.05, 500),
+        ports: list(c?.ports, 'Ports', (s) => { if (!PORT_SPEC.test(s))
+            throw new ObjectError(`"${s}" is not a port mapping (use 8080:80)`); return s; }),
+        volumes: list(c?.volumes, 'Volumes', (s) => { if (s.startsWith('-') || !s.includes(':'))
+            throw new ObjectError(`"${s}" is not a volume (use /host/path:/in/container)`); return s; }),
+    };
+}
+const ENV_NAME = /^[\w.$-]{1,60}$/, VAR_NAME = /^[A-Za-z_][\w.-]{0,80}$/;
+export function parseHttp(c) {
+    const folder = str(c?.folder, 'The folder');
+    if (!folder.startsWith('/'))
+        throw new ObjectError('The folder must be an absolute path');
+    const envName = optStr(c?.env, 'The environment', 100);
+    let variables;
+    if (c?.variables && typeof c.variables === 'object') {
+        variables = {};
+        const envs = Object.entries(c.variables);
+        if (envs.length > 30)
+            throw new ObjectError('At most 30 environments');
+        for (const [name, vars] of envs) {
+            if (!ENV_NAME.test(name))
+                throw new ObjectError(`"${name}" is not a valid environment name`);
+            if (!vars || typeof vars !== 'object')
+                continue;
+            const out = {};
+            const entries = Object.entries(vars);
+            if (entries.length > 100)
+                throw new ObjectError(`At most 100 variables in ${name}`);
+            for (const [k, v] of entries) {
+                if (!VAR_NAME.test(k))
+                    throw new ObjectError(`"${k}" is not a valid variable name`);
+                out[k] = { value: typeof v?.value === 'string' ? str(v.value, `The value of ${k}`, 4000) : '', ...(v?.secret ? { secret: true } : {}) };
+            }
+            variables[name] = out;
+        }
+        if (!Object.keys(variables).length)
+            variables = undefined;
+    }
+    return { folder, env: envName, variables };
+}
+const HOST = /^[A-Za-z0-9._\-]{1,255}$|^\[[0-9A-Fa-f:.]{2,45}\]$/;
+export function parseDatabase(c) {
+    const engine = oneOf(c?.engine, ['mysql', 'postgresql', 'sqlite', 'mssql'], 'The engine');
+    if (!engine)
+        throw new ObjectError('Choose the engine: MySQL, PostgreSQL, SQLite or SQL Server');
+    const common = { readOnly: c?.readOnly === false ? false : true, timeoutSec: num(c?.timeoutSec, 'The query timeout', 1, 600), maxRows: num(c?.maxRows, 'The row limit', 1, 10000) };
+    if (engine === 'sqlite') {
+        const file = str(c?.file, 'The file');
+        if (!file.startsWith('/'))
+            throw new ObjectError('The file must be an absolute path');
+        return { engine, file, props: parseProps(engine, c?.props), ...common };
+    }
+    const host = optStr(c?.host, 'The host', 255) ?? '127.0.0.1';
+    if (!HOST.test(host))
+        throw new ObjectError('The host is not valid');
+    const database = optStr(c?.database, 'The database', 128);
+    if (database && /[\0\r\n;]/.test(database))
+        throw new ObjectError('The database name is not valid');
+    const props = parseProps(engine, c?.props);
+    if (props && !c?.ssl && Object.keys(props).some((k) => k.startsWith('ssl.')))
+        throw new ObjectError('The SSL properties need "Use SSL" on');
+    return {
+        engine, host, port: c?.port === undefined || c?.port === null || c?.port === '' ? undefined : port(c.port, 'The port'),
+        user: optStr(c?.user, 'The user', 200), password: typeof c?.password === 'string' && c.password !== '' ? str(c.password, 'The password', 1000) : undefined, database,
+        ssl: c?.ssl ? true : undefined, trustCert: c?.ssl && c?.trustCert ? true : undefined, props, ...common,
+    };
+}
+export function parseCluster(c) {
+    if (!Array.isArray(c?.members))
+        throw new ObjectError('Choose the resources it groups');
+    const members = [...new Set(c.members.map((x) => str(x, 'A member')))];
+    if (members.length > 30)
+        throw new ObjectError('A cluster groups at most 30 resources');
+    return { members };
+}
+export function parseConfig(kind, c) {
+    return kind === 'server' ? parseServer(c) : kind === 'docker' ? parseDocker(c) : kind === 'http' ? parseHttp(c) : kind === 'database' ? parseDatabase(c) : parseCluster(c);
+}
+export function parseName(v) {
+    const name = str(v, 'The name', NAME_MAX);
+    if (!name)
+        throw new ObjectError('Give it a name');
+    return name;
+}
+export const isKind = (k) => k === 'server' || k === 'docker' || k === 'http' || k === 'database' || k === 'cluster';
+/** `boss` was the first name of a cluster: the API still accepts it. */
+export const kindOf = (k) => (k === 'boss' ? 'cluster' : k);
+/** Splits a command line the way a shell would for quotes (no expansion): `sh -c "echo hi"` → ["sh", "-c", "echo hi"]. */
+export function splitArgs(line) {
+    const out = [];
+    let cur = '', q = null, any = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (q) {
+            if (ch === q)
+                q = null;
+            else if (ch === '\\' && q === '"' && i + 1 < line.length)
+                cur += line[++i];
+            else
+                cur += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            q = ch;
+            any = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (cur || any) {
+                out.push(cur);
+                cur = '';
+                any = false;
+            }
+        }
+        else if (ch === '\\' && i + 1 < line.length)
+            cur += line[++i];
+        else
+            cur += ch;
+    }
+    if (q)
+        throw new ObjectError('A quote is not closed in the command');
+    if (cur || any)
+        out.push(cur);
+    return out;
+}

package/server/dist/objects/runner.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync, closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, truncateSync, unlinkSync, writeFileSync, readSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { DATA_DIR } from '../db.js';
+import { isAlive, processStamp } from '../watch.js';
+import { ObjectError } from './model.js';
+/**
+ * A server object is a shell command that hive-am keeps running. It starts in its own process group with its output going straight to a
+ * log file, so it survives hive-am restarts: afterwards the process is found again by the pid and start time saved next to the log.
+ * Stopping signals the whole group (the shell, `npm`, `node`…): first politely, then for good.
+ */
+const DIR = join(DATA_DIR, 'objects');
+const LOG_MAX = 5 * 1024 * 1024; // a bigger log is set aside when the object starts (and while it runs: see rotateLog)
+const logMaxBytes = (cfg) => Math.round((cfg.logMaxMb ?? 5) * 1024 * 1024) || LOG_MAX;
+const STOP_GRACE_MS = Number(process.env.HIVE_AM_OBJECT_STOP_MS) || 8000;
+const STARTING_MS = 120_000; // with a port: how long "starting" is believed before it counts as stopped working
+const files = (id) => ({ log: join(DIR, `${id}.log`), state: join(DIR, `${id}.json`) });
+export const readSaved = (id) => read(id);
+const read = (id) => { try {
+    return JSON.parse(readFileSync(files(id).state, 'utf8'));
+}
+catch {
+    return null;
+} };
+const write = (id, s) => { mkdirSync(DIR, { recursive: true }); writeFileSync(files(id).state, JSON.stringify(s)); };
+/** A line in the object's log, marked as coming from hive-am (who asked for what, how it ended). */
+export const noteServer = (id, text) => note(id, text);
+const note = (id, text) => { try {
+    mkdirSync(DIR, { recursive: true });
+    appendFileSync(files(id).log, `\n[hive-am] ${text}\n`);
+}
+catch { /* the log is a convenience */ } };
+const listening = (port) => new Promise((resolve) => {
+    const s = connect({ port, host: '127.0.0.1' }, () => { s.destroy(); resolve(true); });
+    s.setTimeout(800, () => { s.destroy(); resolve(false); });
+    s.on('error', () => resolve(false));
+});
+/** The saved pid, only while it is still the same process we started. */
+function livePid(id) {
+    const saved = read(id);
+    if (!saved)
+        return null;
+    return { saved, alive: isAlive(saved.pid, saved.stamp) };
+}
+export async function serverState(id, cfg) {
+    const cur = livePid(id);
+    if (!cur)
+        return { status: 'stopped' };
+    if (cur.alive) {
+        const since = cur.saved.startedAt;
+        if (cfg.port && !(await listening(cfg.port)))
+            return Date.now() - since < STARTING_MS ? { status: 'starting', pid: cur.saved.pid, since, detail: `waiting for port ${cfg.port}` } : { status: 'error', pid: cur.saved.pid, since, detail: `running, but nothing listens on port ${cfg.port}` };
+        return { status: 'running', pid: cur.saved.pid, since };
+    }
+    const x = cur.saved.exit;
+    if (cur.saved.stopped || !x || x.code === 0)
+        return { status: 'stopped', since: x?.at };
+    return { status: 'error', since: x.at, detail: x.signal ? `ended by ${x.signal}` : `exited with code ${x.code}` };
+}
+export async function startServer(id, cfg) {
+    const cur = livePid(id);
+    if (cur?.alive)
+        throw new ObjectError('It is already running');
+    if (!existsSync(cfg.cwd))
+        throw new ObjectError(`The folder ${cfg.cwd} does not exist`);
+    mkdirSync(DIR, { recursive: true });
+    const { log } = files(id);
+    try {
+        if (statSync(log).size > logMaxBytes(cfg))
+            renameSync(log, `${log}.1`);
+    }
+    catch { /* no log yet */ }
+    note(id, `▶ ${cfg.start}   (${new Date().toLocaleString()})`);
+    const fd = openSync(log, 'a');
+    try {
+        const child = spawn('sh', ['-c', cfg.start], { cwd: cfg.cwd, env: { ...process.env, ...cfg.env }, detached: true, stdio: ['ignore', fd, fd] });
+        if (!child.pid)
+            throw new ObjectError('The command could not be started');
+        const pid = child.pid, startedAt = Date.now();
+        write(id, { pid, stamp: processStamp(pid), startedAt });
+        child.on('error', (e) => { note(id, `could not start: ${e.message}`); write(id, { pid, stamp: null, startedAt, exit: { code: 127, signal: null, at: Date.now() } }); });
+        child.on('exit', (code, signal) => {
+            const saved = read(id);
+            if (!saved || saved.pid !== pid)
+                return;
+            write(id, { ...saved, exit: { code, signal, at: Date.now() } });
+            note(id, signal ? `■ ended by ${signal}` : `■ exited with code ${code}`);
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const killGroup = (pid, sig) => { try {
+    process.kill(-pid, sig);
+}
+catch {
+    try {
+        process.kill(pid, sig);
+    }
+    catch { /* already gone */ }
+} };
+export async function stopServer(id, cfg) {
+    const cur = livePid(id);
+    if (!cur)
+        return;
+    write(id, { ...cur.saved, stopped: true });
+    if (cfg.stop) {
+        note(id, `■ ${cfg.stop}`);
+        const fd = openSync(files(id).log, 'a');
+        try {
+            await new Promise((resolve) => {
+                const c = spawn('sh', ['-c', cfg.stop], { cwd: cfg.cwd, env: { ...process.env, ...cfg.env }, stdio: ['ignore', fd, fd] });
+                const t = setTimeout(() => { try {
+                    c.kill('SIGKILL');
+                }
+                catch { /* done */ } resolve(); }, 30_000);
+                c.on('exit', () => { clearTimeout(t); resolve(); });
+                c.on('error', () => { clearTimeout(t); resolve(); });
+            });
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    if (!isAlive(cur.saved.pid, cur.saved.stamp))
+        return;
+    killGroup(cur.saved.pid, 'SIGTERM');
+    const grace = cfg.stopTimeoutSec ? cfg.stopTimeoutSec * 1000 : STOP_GRACE_MS;
+    for (let waited = 0; waited < grace && isAlive(cur.saved.pid, cur.saved.stamp); waited += 150)
+        await sleep(150);
+    if (isAlive(cur.saved.pid, cur.saved.stamp)) {
+        note(id, 'did not stop in time: killing it');
+        killGroup(cur.saved.pid, 'SIGKILL');
+        for (let i = 0; i < 20 && isAlive(cur.saved.pid, cur.saved.stamp); i++)
+            await sleep(100);
+    }
+}
+/** Lines the object printed. `after` is a byte offset from an earlier call; without it the last `tail` lines come back. */
+export function serverLogs(id, o) {
+    const { log } = files(id);
+    let size = 0;
+    try {
+        size = statSync(log).size;
+    }
+    catch {
+        return { text: '', cursor: '0' };
+    }
+    const MAX = 256 * 1024;
+    let from, reset = false;
+    if (o.after !== undefined && Number.isFinite(o.after)) {
+        if (o.after > size) {
+            from = Math.max(0, size - MAX);
+            reset = true;
+        } // the file was cut or replaced
+        else
+            from = Math.max(o.after, size - MAX);
+    }
+    else
+        from = Math.max(0, size - Math.max(1, Math.min(o.tail ?? 300, 5000)) * 200);
+    const len = size - from;
+    if (len <= 0)
+        return { text: '', cursor: String(size) };
+    const buf = Buffer.alloc(len);
+    const fd = openSync(log, 'r');
+    try {
+        readSync(fd, buf, 0, len, from);
+    }
+    finally {
+        closeSync(fd);
+    }
+    let text = buf.toString('utf8');
+    if (o.after === undefined) {
+        const lines = text.split('\n');
+        if (from > 0)
+            lines.shift(); // the first line may be cut in half
+        text = lines.slice(-Math.max(1, Math.min(o.tail ?? 300, 5000))).join('\n');
+    }
+    return { text, cursor: String(size), reset: reset || undefined };
+}
+/** Removes the log and the saved state of a deleted object. */
+export function forgetServer(id) {
+    const { log, state } = files(id);
+    for (const f of [log, `${log}.1`, state]) {
+        try {
+            unlinkSync(f);
+        }
+        catch { /* none */ }
+    }
+}
+/**
+ * Keeps the log from growing for ever while the server runs. The process writes with O_APPEND to its own file, so the old part is copied
+ * aside and the file is emptied in place (a few lines printed in between can be lost; it is a log, not a ledger).
+ */
+export function rotateLog(id, cfg) {
+    const { log } = files(id);
+    try {
+        if (statSync(log).size <= logMaxBytes(cfg))
+            return false;
+        copyFileSync(log, `${log}.1`);
+        truncateSync(log, 0);
+        note(id, `log rotated: the earlier part is in ${id}.log.1`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/server/dist/objects/stats.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { containerName } from './docker.js';
+import { execCapture } from './exec.js';
+import { ObjectError } from './model.js';
+import { readSaved } from './runner.js';
+const run = async (file, args, o = {}) => {
+    const r = await execCapture(file, args, { cwd: o.cwd, timeout: o.timeout });
+    return { out: r.out, code: r.code };
+};
+const UNITS = { b: 1, kb: 1e3, mb: 1e6, gb: 1e9, tb: 1e12, kib: 1024, mib: 1024 ** 2, gib: 1024 ** 3, tib: 1024 ** 4 };
+/** "12.5MiB" → bytes. */
+const bytes = (s) => { const m = /^([\d.]+)\s*([a-z]+)$/i.exec(s.trim()); return m && UNITS[m[2].toLowerCase()] ? Math.round(Number(m[1]) * UNITS[m[2].toLowerCase()]) : null; };
+/** The processes of a server: its whole process group (the shell, npm, node…). */
+async function serverStats(o) {
+    const saved = readSaved(o.id);
+    const empty = { cpu: null, memBytes: null, memLimitBytes: null, pids: null, info: {} };
+    if (!saved)
+        return empty;
+    const { out, code } = await run('ps', ['-axo', 'pgid=,pcpu=,rss=']);
+    if (code !== 0)
+        return empty;
+    let cpu = 0, rss = 0, n = 0;
+    for (const line of out.split('\n')) {
+        const [g, c, r] = line.trim().split(/\s+/);
+        if (Number(g) === saved.pid) {
+            cpu += Number(c) || 0;
+            rss += Number(r) || 0;
+            n++;
+        }
+    }
+    return n ? { cpu: Math.round(cpu * 10) / 10, memBytes: rss * 1024, memLimitBytes: null, pids: n, info: { pid: saved.pid, started: saved.startedAt } } : { ...empty, info: { pid: saved.pid, started: saved.startedAt } };
+}
+async function containerStats(name) {
+    const [st, ins] = await Promise.all([
+        run('docker', ['stats', '--no-stream', '--format', '{{json .}}', name]),
+        run('docker', ['inspect', '-f', '{{.Config.Image}}|{{.State.Status}}|{{.RestartCount}}|{{.Created}}|{{.State.StartedAt}}|{{.HostConfig.RestartPolicy.Name}}|{{.HostConfig.NetworkMode}}|{{.HostConfig.Memory}}|{{.HostConfig.NanoCpus}}', name]),
+    ]);
+    const info = {};
+    if (ins.code === 0) {
+        const [image, status, restarts, created, started, policy, network, mem, nano] = ins.out.trim().split('|');
+        Object.assign(info, { image, status, restarts: Number(restarts), created: Date.parse(created) || null, started: Date.parse(started) || null, restartPolicy: policy || 'no', network, memoryLimit: Number(mem) || 0, cpuLimit: Number(nano) ? Number(nano) / 1e9 : 0 });
+    }
+    const ports = await run('docker', ['port', name]);
+    if (ports.code === 0)
+        info.ports = ports.out.trim().split('\n').filter(Boolean).join(', ');
+    let j = null;
+    try {
+        j = JSON.parse(st.out.trim().split('\n')[0] ?? '');
+    }
+    catch { /* not running */ }
+    if (!j)
+        return { cpu: null, memBytes: null, memLimitBytes: null, pids: null, info };
+    const [used, limit] = String(j.MemUsage ?? '').split('/');
+    return { cpu: Number.parseFloat(j.CPUPerc) || 0, memBytes: bytes(used ?? ''), memLimitBytes: bytes(limit ?? ''), pids: Number(j.PIDs) || null, net: j.NetIO ?? null, block: j.BlockIO ?? null, info };
+}
+async function composeStats(c) {
+    if (!existsSync(c.file))
+        throw new ObjectError('The compose file is missing');
+    const args = ['compose', '-f', c.file, ...(c.project ? ['-p', c.project] : [])];
+    const ps = await run('docker', [...args, 'ps', '--all', '--format', 'json', ...(c.services ?? [])], { cwd: dirname(c.file) });
+    const t = ps.out.trim();
+    const items = t.startsWith('[') ? (() => { try {
+        return JSON.parse(t);
+    }
+    catch {
+        return [];
+    } })() : t.split('\n').flatMap((l) => { try {
+        return [JSON.parse(l)];
+    }
+    catch {
+        return [];
+    } });
+    // "16379->6379" once, even when Docker lists the same port for IPv4 and IPv6
+    const portsOf = (x) => [...new Set((x.Publishers ?? []).filter((p) => p.PublishedPort).map((p) => `${p.PublishedPort}->${p.TargetPort}`))].join(', ') || String(x.Ports ?? '');
+    const services = items.map((x) => ({ name: String(x.Service ?? x.Name ?? ''), container: String(x.Name ?? ''), image: String(x.Image ?? ''), state: String(x.State ?? ''), health: String(x.Health ?? ''), status: String(x.Status ?? ''), ports: portsOf(x), cpu: null, memBytes: null }));
+    const ids = items.filter((x) => x.State === 'running').map((x) => String(x.ID ?? x.Name));
+    let cpu = 0, mem = 0, pids = 0;
+    if (ids.length) {
+        const st = await run('docker', ['stats', '--no-stream', '--format', '{{json .}}', ...ids]);
+        for (const l of st.out.trim().split('\n')) {
+            try {
+                const j = JSON.parse(l);
+                const c1 = Number.parseFloat(j.CPUPerc) || 0, m1 = bytes(String(j.MemUsage).split('/')[0] ?? '') ?? 0;
+                cpu += c1;
+                mem += m1;
+                pids += Number(j.PIDs) || 0;
+                const sv = services.find((x) => x.container === j.Name || (j.ID && String(items.find((i) => i.Name === x.container)?.ID ?? '').startsWith(String(j.ID))));
+                if (sv) {
+                    sv.cpu = Math.round(c1 * 10) / 10;
+                    sv.memBytes = m1;
+                }
+            }
+            catch { /* a line that is not json */ }
+        }
+    }
+    return { cpu: ids.length ? Math.round(cpu * 10) / 10 : null, memBytes: ids.length ? mem : null, memLimitBytes: null, pids: ids.length ? pids : null, info: { services: services.length, running: ids.length }, services };
+}
+export async function objectStats(o) {
+    if (o.kind === 'server')
+        return serverStats(o);
+    if (o.kind !== 'docker')
+        throw new ObjectError('This kind of resource has no usage figures');
+    const c = o.config;
+    return c.mode === 'compose' ? composeStats(c) : containerStats(c.mode === 'existing' ? c.container : containerName(o.id));
+}