hive-am 1.0.0 → 1.2.0

package/server/dist/objects/docker.js

@@ -0,0 +1,285 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { execCapture } from './exec.js';
+import { ObjectError, splitArgs } from './model.js';
+/**
+ * A Docker object drives the `docker` command (never a shell, every value is one argument): start, stop, restart, status and logs of a
+ * container hive-am created, of a compose project, or of a container that already existed. Anything hive-am did not create is only
+ * ever started, stopped or read, never removed.
+ */
+const TIMEOUT = 60_000;
+const DOCKER_ENV = { ...process.env, DOCKER_CLI_HINTS: 'false' };
+async function dk(args, o = {}) {
+    const r = await execCapture('docker', args, { cwd: o.cwd, timeout: o.timeout ?? TIMEOUT, maxBuffer: 16 * 1024 * 1024, env: DOCKER_ENV });
+    if (r.missing)
+        throw new ObjectError('Docker is not installed or not in the PATH');
+    if (r.timedOut)
+        throw new ObjectError(`docker ${args[0]} took too long`);
+    return r;
+}
+const fail = (r, what) => new ObjectError(`${what}: ${(r.err || r.out).trim().split('\n').slice(-3).join(' ').slice(0, 400) || `docker exited with ${r.code}`}`);
+/** What makes a container different from another one when hive-am creates it: if it changes, the container is created again on the next start. */
+const CFG_FIELDS = ['image', 'ports', 'volumes', 'env', 'restart', 'command', 'memory', 'cpus', 'network', 'logMaxMb'];
+export const cfgHash = (c) => createHash('sha1').update(JSON.stringify(CFG_FIELDS.map((k) => c[k] ?? null))).digest('hex').slice(0, 12);
+const stopArgs = (c) => (c.stopTimeoutSec ? ['-t', String(c.stopTimeoutSec)] : []);
+/** The hash a container was created with (empty when it does not exist). */
+async function createdWith(name) {
+    const r = await dk(['inspect', '-f', '{{index .Config.Labels "hive-am.cfg"}}', name]);
+    return r.code === 0 ? r.out.trim() : null;
+}
+/** The name hive-am gives to a container it creates. */
+export const containerName = (id) => `hive-am-${id.slice(0, 8)}`;
+const nameOf = (id, c) => (c.mode === 'existing' ? c.container : containerName(id));
+/** `docker compose -f file -p project` + what to do. The folder of the file is the working folder, as compose expects. */
+const composeArgs = (c, rest) => ['compose', '-f', c.file, ...(c.project ? ['-p', c.project] : []), ...rest];
+function checkCompose(c) { if (!existsSync(c.file))
+    throw new ObjectError(`The compose file ${c.file} does not exist`); }
+export async function dockerState(id, c) {
+    try {
+        if (c.mode === 'compose') {
+            if (!existsSync(c.file))
+                return { status: 'error', detail: 'the compose file is missing' };
+            const r = await dk(composeArgs(c, ['ps', '--all', '--format', 'json', ...(c.services ?? [])]), { cwd: dirname(c.file) });
+            if (r.code !== 0)
+                return { status: 'unknown', detail: r.err.trim().split('\n').pop()?.slice(0, 160) };
+            const items = parseJsonLines(r.out);
+            if (!items.length)
+                return { status: 'stopped' };
+            const states = items.map((x) => String(x.State ?? '').toLowerCase());
+            const running = states.filter((s) => s === 'running').length;
+            if (running === items.length)
+                return items.some((x) => /starting|unhealthy/i.test(String(x.Health ?? x.Status ?? ''))) ? { status: 'starting', detail: 'health check pending' } : { status: 'running', detail: `${running} service${running === 1 ? '' : 's'}` };
+            if (running > 0)
+                return { status: 'starting', detail: `${running} of ${items.length} running` };
+            return states.some((s) => s === 'exited') && items.some((x) => Number(x.ExitCode) > 0) ? { status: 'error', detail: 'a service exited with an error' } : { status: 'stopped' };
+        }
+        const r = await dk(['inspect', '-f', '{{.State.Status}}|{{if .State.Health}}{{.State.Health.Status}}{{end}}|{{.State.ExitCode}}|{{.State.StartedAt}}', nameOf(id, c)]);
+        if (r.code !== 0)
+            return c.mode === 'existing' ? { status: 'unknown', detail: 'container not found' } : { status: 'stopped' };
+        const [state, health, exit, started] = r.out.trim().split('|');
+        const since = Date.parse(started) || undefined;
+        if (state === 'running')
+            return health === 'unhealthy' ? { status: 'error', detail: 'unhealthy', since } : health === 'starting' ? { status: 'starting', detail: 'health check pending', since } : { status: 'running', since };
+        if (state === 'restarting')
+            return { status: 'starting', detail: 'restarting', since };
+        if (state === 'exited' && Number(exit) !== 0)
+            return { status: 'error', detail: `exited with code ${exit}` };
+        return { status: 'stopped' };
+    }
+    catch (e) {
+        return { status: 'unknown', detail: e instanceof Error ? e.message : 'docker failed' };
+    }
+}
+/** `docker compose ps --format json` prints one JSON per line (or, in older versions, one array). */
+function parseJsonLines(out) {
+    const t = out.trim();
+    if (!t)
+        return [];
+    if (t.startsWith('[')) {
+        try {
+            return JSON.parse(t);
+        }
+        catch {
+            return [];
+        }
+    }
+    return t.split('\n').flatMap((l) => { try {
+        return [JSON.parse(l)];
+    }
+    catch {
+        return [];
+    } });
+}
+export async function startDocker(id, c) {
+    if (c.mode === 'compose') {
+        checkCompose(c);
+        const r = await dk(composeArgs(c, ['up', '-d', ...(c.services ?? [])]), { cwd: dirname(c.file), timeout: 300_000 });
+        if (r.code !== 0)
+            throw fail(r, 'compose up failed');
+        return;
+    }
+    const name = nameOf(id, c);
+    let exists = (await dk(['inspect', '-f', '{{.Id}}', name])).code === 0;
+    // A container hive-am created with other settings than the ones now configured is created again (what is inside it is lost, as with any recreate).
+    if (exists && c.mode === 'container') {
+        const w = await createdWith(name);
+        if (w && w !== cfgHash(c)) {
+            await dk(['rm', '-f', name]);
+            exists = false;
+        }
+    }
+    if (exists) {
+        const r = await dk(['start', name]);
+        if (r.code !== 0)
+            throw fail(r, 'could not start it');
+        return;
+    }
+    if (c.mode === 'existing')
+        throw new ObjectError(`There is no container named ${name}`);
+    const args = ['run', '-d', '--name', name, '--label', `hive-am.object=${id}`, '--label', `hive-am.cfg=${cfgHash(c)}`];
+    if (c.memory)
+        args.push('--memory', c.memory);
+    if (c.cpus)
+        args.push('--cpus', String(c.cpus));
+    if (c.network)
+        args.push('--network', c.network);
+    // A container always gets a log limit (10 MB x 3 unless set): docker's default is no limit, and a chatty container fills the disk.
+    args.push('--log-opt', `max-size=${Math.max(1, Math.round((c.logMaxMb ?? 10) * 1024))}k`, '--log-opt', 'max-file=3');
+    if (c.stopTimeoutSec)
+        args.push('--stop-timeout', String(c.stopTimeoutSec));
+    if (c.restart && c.restart !== 'no')
+        args.push('--restart', c.restart);
+    for (const p of c.ports ?? [])
+        args.push('-p', p);
+    for (const v of c.volumes ?? [])
+        args.push('-v', v);
+    for (const [k, v] of Object.entries(c.env ?? {}))
+        args.push('-e', `${k}=${v}`);
+    args.push(c.image, ...(c.command ? splitArgs(c.command) : []));
+    const r = await dk(args, { timeout: 300_000 }); // a first run may pull the image
+    if (r.code !== 0)
+        throw fail(r, 'could not create it');
+}
+export async function stopDocker(id, c) {
+    if (c.mode === 'compose') {
+        checkCompose(c);
+        const r = await dk(composeArgs(c, ['stop', ...stopArgs(c), ...(c.services ?? [])]), { cwd: dirname(c.file), timeout: 300_000 });
+        if (r.code !== 0)
+            throw fail(r, 'compose stop failed');
+        return;
+    }
+    const r = await dk(['stop', ...stopArgs(c), nameOf(id, c)], { timeout: 300_000 });
+    if (r.code !== 0 && !/No such container/i.test(r.err))
+        throw fail(r, 'could not stop it');
+}
+export async function restartDocker(id, c) {
+    if (c.mode === 'compose') {
+        checkCompose(c);
+        const r = await dk(composeArgs(c, ['restart', ...stopArgs(c), ...(c.services ?? [])]), { cwd: dirname(c.file), timeout: 300_000 });
+        if (r.code !== 0)
+            throw fail(r, 'compose restart failed');
+        return;
+    }
+    const name = nameOf(id, c);
+    if ((await dk(['inspect', '-f', '{{.Id}}', name])).code !== 0)
+        return startDocker(id, c);
+    if (c.mode === 'container') {
+        const w = await createdWith(name);
+        if (w && w !== cfgHash(c)) {
+            await dk(['stop', ...stopArgs(c), name], { timeout: 300_000 });
+            return startDocker(id, c);
+        }
+    } // changed settings: created again
+    const r = await dk(['restart', ...stopArgs(c), name], { timeout: 300_000 });
+    if (r.code !== 0)
+        throw fail(r, 'could not restart it');
+}
+/** One service of a compose project, alone: start (creating it if needed), stop, restart, create it again, or build it again and create it. */
+export async function composeServiceAction(c, service, action) {
+    if (c.mode !== 'compose')
+        throw new ObjectError('Only a compose project has services');
+    if (!/^[\w][\w.-]{0,80}$/.test(service))
+        throw new ObjectError('That is not a service name');
+    checkCompose(c);
+    const rest = action === 'start' ? ['up', '-d', service]
+        : action === 'recreate' ? ['up', '-d', '--force-recreate', service]
+            : action === 'rebuild' ? ['up', '-d', '--build', service]
+                : [action, ...stopArgs(c), service];
+    const r = await dk(composeArgs(c, rest), { cwd: dirname(c.file), timeout: action === 'rebuild' ? 900_000 : 300_000 });
+    if (r.code !== 0)
+        throw fail(r, `compose ${action} failed`);
+}
+/** The whole object: create its container(s) again (a compose project with --force-recreate; a container hive-am made is removed and run again), or build them again first. */
+export async function recreateDocker(id, c, build = false) {
+    if (c.mode === 'compose') {
+        checkCompose(c);
+        const r = await dk(composeArgs(c, ['up', '-d', ...(build ? ['--build'] : ['--force-recreate']), ...(c.services ?? [])]), { cwd: dirname(c.file), timeout: build ? 900_000 : 300_000 });
+        if (r.code !== 0)
+            throw fail(r, `compose ${build ? 'rebuild' : 'recreate'} failed`);
+        return;
+    }
+    if (build)
+        throw new ObjectError('Only a compose project builds images');
+    if (c.mode === 'existing')
+        throw new ObjectError('A container that already existed is never removed: it cannot be created again from here');
+    await dk(['rm', '-f', nameOf(id, c)], { timeout: 120_000 });
+    await startDocker(id, c);
+}
+/** The id of the container behind an object (or behind one service of a compose project), or an error when there is none. */
+export async function containerOf(id, c, service) {
+    if (c.mode !== 'compose')
+        return nameOf(id, c);
+    if (!service || !/^[\w][\w.-]{0,80}$/.test(service))
+        throw new ObjectError('Say which service');
+    checkCompose(c);
+    const r = await dk(composeArgs(c, ['ps', '-a', '-q', service]), { cwd: dirname(c.file) });
+    const cid = r.out.trim().split('\n')[0];
+    if (r.code !== 0 || !cid)
+        throw new ObjectError(`The service ${service} has no container: start it first`);
+    return cid;
+}
+export async function inspectDocker(id, c, service) {
+    const ref = await containerOf(id, c, service);
+    const r = await dk(['inspect', ref]);
+    if (r.code !== 0)
+        throw new ObjectError(`There is no container ${ref}`);
+    const j = JSON.parse(r.out)[0];
+    const cfg = j.Config ?? {}, st = j.State ?? {}, net = j.NetworkSettings ?? {};
+    return {
+        id: String(j.Id ?? '').slice(0, 12), name: String(j.Name ?? '').replace(/^\//, ''), image: String(cfg.Image ?? ''), status: String(st.Status ?? ''), created: String(j.Created ?? ''), started: String(st.StartedAt ?? ''),
+        restartPolicy: String(j.HostConfig?.RestartPolicy?.Name || 'no'), restarts: Number(j.RestartCount ?? 0),
+        command: Array.isArray(cfg.Cmd) ? cfg.Cmd.join(' ') : '', entrypoint: Array.isArray(cfg.Entrypoint) ? cfg.Entrypoint.join(' ') : String(cfg.Entrypoint ?? ''), workdir: String(cfg.WorkingDir ?? ''), user: String(cfg.User ?? ''),
+        env: (cfg.Env ?? []).map((e) => { const i = e.indexOf('='); return i < 0 ? { name: e, value: '' } : { name: e.slice(0, i), value: e.slice(i + 1) }; }),
+        ports: Object.entries((net.Ports ?? {})).flatMap(([cp, hs]) => (hs && hs.length ? [...new Map(hs.map((h) => [h.HostPort, h])).values()].map((h) => ({ container: cp, host: h.HostPort })) : [{ container: cp, host: '' }])),
+        mounts: (j.Mounts ?? []).map((m) => ({ type: String(m.Type ?? ''), source: String(m.Source ?? m.Name ?? ''), destination: String(m.Destination ?? ''), rw: m.RW !== false })),
+        networks: Object.entries((net.Networks ?? {})).map(([name, n]) => ({ name, ip: String(n.IPAddress ?? ''), gateway: String(n.Gateway ?? ''), aliases: (n.Aliases ?? []) })),
+        health: st.Health ? { status: String(st.Health.Status ?? ''), log: (st.Health.Log ?? []).slice(-5).map((l) => ({ at: String(l.End ?? l.Start ?? ''), exit: Number(l.ExitCode ?? 0), output: String(l.Output ?? '').slice(0, 300) })) } : undefined,
+        labels: (cfg.Labels ?? {}),
+    };
+}
+/** A container hive-am created goes away with its object; a compose project is only stopped; an existing container is left alone. */
+export async function removeDocker(id, c) {
+    if (c.mode === 'container')
+        await dk(['rm', '-f', containerName(id)]).catch(() => undefined);
+    else if (c.mode === 'compose' && existsSync(c.file))
+        await dk(composeArgs(c, ['stop', ...(c.services ?? [])]), { cwd: dirname(c.file) }).catch(() => undefined);
+}
+const STAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z/;
+/**
+ * The latest output. `after` is the time (RFC 3339) of the last line already seen; without it the last `tail` lines come back.
+ * Lines carry docker's own timestamp, which is what makes "only what is new" possible; it is cut out of the text shown.
+ */
+/**
+ * `--since` alone makes docker read the whole log file on every call (4 s for a 200 MB log, measured), so it always goes with `--tail`, which
+ * lets it read from the end: a poll costs the same however big the log is. If more than SINCE_TAIL lines arrived between two polls the
+ * oldest of them are skipped; the log pane shows the latest anyway.
+ */
+const SINCE_TAIL = 2000;
+const tailArgs = (o) => o.after ? ['--since', o.after, '--tail', String(SINCE_TAIL)] : ['--tail', String(Math.max(1, Math.min(o.tail ?? 300, 5000)))];
+export async function dockerLogs(id, c, o) {
+    const base = c.mode === 'compose'
+        ? composeArgs(c, ['logs', '--no-color', '--timestamps', ...tailArgs(o), ...(c.services ?? [])])
+        : ['logs', '--timestamps', ...tailArgs(o), nameOf(id, c)];
+    if (c.mode === 'compose')
+        checkCompose(c);
+    const r = await dk(base, { cwd: c.mode === 'compose' ? dirname(c.file) : undefined, timeout: 20_000 });
+    if (r.code !== 0 && !r.out && !r.err)
+        return { text: '', cursor: o.after ?? '' };
+    if (r.code !== 0 && /No such container/i.test(r.err))
+        return { text: '', cursor: o.after ?? '' };
+    // docker keeps stdout and stderr apart: put them back in order by their timestamps.
+    const lines = `${r.out}${r.err && r.code === 0 ? `\n${r.err}` : ''}`.split('\n').filter(Boolean)
+        .map((l) => ({ l, t: STAMP.exec(l.slice(0, 120))?.[0] ?? '' }));
+    lines.sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0));
+    let last = o.after ?? '';
+    const shown = [];
+    for (const { l, t } of lines) {
+        if (o.after && t && t <= o.after)
+            continue; // `--since` includes the second it names
+        if (t && t > last)
+            last = t;
+        shown.push(t ? l.replace(`${t} `, '').replace(t, '') : l);
+    }
+    return { text: shown.join('\n'), cursor: last };
+}

package/server/dist/objects/driver-props.js

@@ -0,0 +1,196 @@
+import { readFileSync, statSync } from 'node:fs';
+import { ObjectError } from './model.js';
+/** Spanish descriptions, by property name (the same name has the same meaning in every engine that has it). */
+const ES = {
+    'ssl.ca': 'Archivo con el certificado de la autoridad que firmó el del servidor (.pem). Hace falta para verificar una autoridad privada.',
+    'ssl.cert': 'Certificado del cliente (.pem), para servidores que piden que el cliente se identifique.',
+    'ssl.key': 'Llave privada del certificado del cliente (.pem, sin frase de contraseña).',
+    'ssl.minVersion': 'Versión de TLS más antigua que acepta.',
+    'ssl.ciphers': 'Suites de cifrado permitidas, en formato OpenSSL.',
+    'ssl.servername': 'Nombre contra el que se comprueba el certificado del servidor, si no es el del host.',
+    charset: 'Juego de caracteres o collation de la conexión.',
+    timezone: 'Zona horaria con la que lee las fechas: local, Z o un desfase.',
+    decimalNumbers: 'Devuelve las columnas DECIMAL como número y no como texto (puede perder precisión).',
+    connectTimeout: 'Milisegundos que espera a que se abra la conexión (por defecto 10000).',
+    enableKeepAlive: 'Mantiene viva la conexión con paquetes TCP keep-alive.',
+    keepAliveInitialDelay: 'Milisegundos de silencio antes del primer paquete keep-alive.',
+    compress: 'Comprime el tráfico con el servidor (ayuda en enlaces lentos).',
+    insecureAuth: 'Permite servidores que aún usan el cifrado antiguo e inseguro de contraseñas.',
+    enableCleartextPlugin: 'Permite el plugin de autenticación en texto claro (PAM y LDAP). Solo con SSL.',
+    application_name: 'Nombre con el que aparece la sesión en pg_stat_activity.',
+    search_path: 'Esquemas en los que busca, en orden (se envía como -c search_path=…).',
+    client_encoding: 'Juego de caracteres de la conexión.',
+    options: 'Otros ajustes de la sesión, como opciones de línea de comandos.',
+    lock_timeout: 'Milisegundos que una sentencia espera un bloqueo antes de fallar (0 = sin límite).',
+    idle_in_transaction_session_timeout: 'Milisegundos que una transacción abierta puede estar inactiva antes de que el servidor cierre la sesión (0 = sin límite).',
+    connectionTimeoutMillis: 'Milisegundos que espera a que se abra la conexión (por defecto 10000).',
+    keepAlive: 'Mantiene viva la conexión con paquetes TCP keep-alive.',
+    keepAliveInitialDelayMillis: 'Milisegundos de silencio antes del primer paquete keep-alive.',
+    enableChannelBinding: 'Exige channel binding de SCRAM (un intercambio de contraseña más fuerte, requiere SSL).',
+    sslnegotiation: 'Cómo empieza TLS. "direct" se salta la petición en claro previa (PostgreSQL 17 o posterior).',
+    appName: 'Nombre con el que aparece la sesión en sys.dm_exec_sessions.',
+    language: 'Idioma de los mensajes del servidor.',
+    dateFormat: 'Orden de día, mes y año al leer fechas.',
+    datefirst: 'Primer día de la semana: 1 es lunes, 7 es domingo.',
+    enableArithAbort: 'Detiene la sentencia ante un error aritmético (SET ARITHABORT).',
+    useUTC: 'Lee y envía las fechas en UTC y no en hora local.',
+    instanceName: 'Instancia con nombre (host\\NOMBRE). Con ella no se usa el puerto: se busca por el servicio SQL Browser.',
+    connectionTimeout: 'Milisegundos que espera a que se abra la conexión (por defecto 10000).',
+    packetSize: 'Bytes por paquete de red (de 512 a 32767).',
+    readOnlyIntent: 'Pide la réplica de lectura de un grupo de disponibilidad.',
+    multiSubnetFailover: 'Prueba a la vez todas las direcciones del listener de un grupo de disponibilidad.',
+    workstationId: 'Nombre de equipo que la sesión informa al servidor.',
+    serverName: 'Nombre que se envía al servidor al conectar por TLS (SNI), si no es el del host.',
+    timeout: 'Milisegundos que espera cuando otro proceso tiene bloqueado el archivo (por defecto 5000).',
+    foreign_keys: 'Hace cumplir las llaves foráneas.',
+    case_sensitive_like: 'Hace que LIKE distinga mayúsculas de minúsculas.',
+    cache_size: 'Páginas que mantiene en memoria; un número negativo son kilobytes.',
+    temp_store: 'Dónde viven las tablas e índices temporales.',
+};
+const p = (name, type, group, desc, extra = {}) => ({ name, type, group, desc, es: ES[name] ?? desc, ...extra });
+const TLS = ['TLSv1.2', 'TLSv1.3'];
+/** TLS files and settings: the same names for the three server engines (SQL Server takes them inside `cryptoCredentialsDetails`). */
+const sslProps = (servername) => [
+    p('ssl.ca', 'file', 'ssl', 'File with the certificate of the authority that signed the server certificate (.pem). Needed to verify a private authority.', { placeholder: '/etc/ssl/certs/my-ca.pem' }),
+    p('ssl.cert', 'file', 'ssl', 'Client certificate (.pem), for servers that ask the client to identify itself.', { placeholder: '/home/you/client-cert.pem' }),
+    p('ssl.key', 'file', 'ssl', 'Private key of the client certificate (.pem, not protected by a passphrase).', { placeholder: '/home/you/client-key.pem' }),
+    p('ssl.minVersion', 'choice', 'ssl', 'Oldest TLS version it will accept.', { choices: TLS }),
+    p('ssl.ciphers', 'string', 'ssl', 'Allowed cipher suites, in OpenSSL format.', { placeholder: 'ECDHE-RSA-AES256-GCM-SHA384' }),
+    ...(servername ? [p('ssl.servername', 'string', 'ssl', 'Name the server certificate is checked against, when it differs from the host.', { placeholder: 'db.example.com' })] : []),
+];
+export const DRIVER_PROPS = {
+    mysql: [
+        p('charset', 'string', 'session', 'Character set or collation of the connection.', { placeholder: 'utf8mb4' }),
+        p('timezone', 'string', 'session', 'Time zone used to read dates: local, Z or an offset.', { placeholder: 'Z' }),
+        p('decimalNumbers', 'boolean', 'session', 'Return DECIMAL columns as numbers instead of text (can lose precision).'),
+        p('connectTimeout', 'number', 'network', 'Milliseconds to wait for the connection to open (default 10000).', { min: 1000, max: 120000, placeholder: '10000' }),
+        p('enableKeepAlive', 'boolean', 'network', 'Keep the connection alive with TCP keep-alive packets.'),
+        p('keepAliveInitialDelay', 'number', 'network', 'Milliseconds of silence before the first keep-alive packet.', { min: 0, max: 600000, placeholder: '0' }),
+        p('compress', 'boolean', 'network', 'Compress the traffic with the server (helps on slow links).'),
+        p('insecureAuth', 'boolean', 'advanced', 'Allow servers that still use the old, insecure password hashing.'),
+        p('enableCleartextPlugin', 'boolean', 'advanced', 'Allow the cleartext authentication plugin (PAM and LDAP setups). Only over SSL.'),
+        ...sslProps(true),
+    ],
+    postgresql: [
+        p('application_name', 'string', 'session', 'Name the session shows in pg_stat_activity.', { placeholder: 'hive-am' }),
+        p('search_path', 'string', 'session', 'Schemas it looks in, in order (it is sent as -c search_path=…).', { placeholder: 'app,public' }),
+        p('client_encoding', 'string', 'session', 'Character set of the connection.', { placeholder: 'UTF8' }),
+        p('options', 'string', 'session', 'Other session settings, as command line options.', { placeholder: '-c timezone=UTC' }),
+        p('lock_timeout', 'number', 'session', 'Milliseconds a statement waits for a lock before it fails (0 = no limit).', { min: 0, max: 3600000, placeholder: '0' }),
+        p('idle_in_transaction_session_timeout', 'number', 'session', 'Milliseconds an open transaction may sit idle before the server ends the session (0 = no limit).', { min: 0, max: 3600000, placeholder: '0' }),
+        p('connectionTimeoutMillis', 'number', 'network', 'Milliseconds to wait for the connection to open (default 10000).', { min: 1000, max: 120000, placeholder: '10000' }),
+        p('keepAlive', 'boolean', 'network', 'Keep the connection alive with TCP keep-alive packets.'),
+        p('keepAliveInitialDelayMillis', 'number', 'network', 'Milliseconds of silence before the first keep-alive packet.', { min: 0, max: 600000, placeholder: '0' }),
+        p('enableChannelBinding', 'boolean', 'advanced', 'Require SCRAM channel binding (a stronger password exchange, needs SSL).'),
+        p('sslnegotiation', 'choice', 'advanced', 'How TLS starts. "direct" skips the plain request first (PostgreSQL 17 and later).', { choices: ['postgres', 'direct'] }),
+        ...sslProps(true),
+    ],
+    mssql: [
+        p('appName', 'string', 'session', 'Name the session shows in sys.dm_exec_sessions.', { placeholder: 'hive-am' }),
+        p('language', 'string', 'session', 'Language of the server messages.', { placeholder: 'us_english' }),
+        p('dateFormat', 'choice', 'session', 'Order of day, month and year when reading dates.', { choices: ['mdy', 'dmy', 'ymd', 'ydm', 'myd', 'dym'] }),
+        p('datefirst', 'number', 'session', 'First day of the week: 1 is Monday, 7 is Sunday.', { min: 1, max: 7, placeholder: '7' }),
+        p('enableArithAbort', 'boolean', 'session', 'Stop a statement on an arithmetic error (SET ARITHABORT).'),
+        p('useUTC', 'boolean', 'session', 'Read and send dates as UTC instead of local time.'),
+        p('instanceName', 'string', 'network', 'Named instance (host\\NAME). With it the port is not used: the instance is found through the SQL Browser service.', { placeholder: 'SQLEXPRESS' }),
+        p('connectionTimeout', 'number', 'network', 'Milliseconds to wait for the connection to open (default 10000).', { min: 1000, max: 120000, placeholder: '10000' }),
+        p('packetSize', 'number', 'network', 'Bytes per network packet (512 to 32767).', { min: 512, max: 32767, placeholder: '4096' }),
+        p('readOnlyIntent', 'boolean', 'network', 'Ask for the read replica of an availability group.'),
+        p('multiSubnetFailover', 'boolean', 'network', 'Try every address of an availability group listener at once.'),
+        p('workstationId', 'string', 'advanced', 'Host name the session reports to the server.', { placeholder: 'hive-am' }),
+        p('serverName', 'string', 'advanced', 'Name sent to the server when it connects over TLS (SNI), when it differs from the host.', { placeholder: 'db.example.com' }),
+        ...sslProps(false),
+    ],
+    sqlite: [
+        p('timeout', 'number', 'session', 'Milliseconds to wait when the file is locked by another process (default 5000).', { min: 0, max: 600000, placeholder: '5000' }),
+        p('foreign_keys', 'boolean', 'session', 'Enforce foreign keys.'),
+        p('case_sensitive_like', 'boolean', 'session', 'Make LIKE case sensitive.'),
+        p('cache_size', 'number', 'session', 'Pages kept in memory; a negative number is kilobytes.', { min: -1000000, max: 1000000, placeholder: '-2000' }),
+        p('temp_store', 'choice', 'session', 'Where temporary tables and indexes live.', { choices: ['default', 'file', 'memory'] }),
+    ],
+};
+export const MAX_PROPS = 40;
+const CTRL = /[\0\r\n]/;
+/** Checks the properties the interface sent: only known names, each with a value of its kind. Empty values are dropped. */
+export function parseProps(engine, raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new ObjectError('The driver properties must be a list of name and value');
+    const known = new Map(DRIVER_PROPS[engine].map((x) => [x.name, x]));
+    const out = {};
+    for (const [name, v] of Object.entries(raw)) {
+        if (v === undefined || v === null || (typeof v === 'string' && v.trim() === ''))
+            continue;
+        const def = known.get(name);
+        if (!def)
+            throw new ObjectError(`"${name}" is not a property this driver takes: choose it from the list`);
+        const s = String(v).trim();
+        if (s.length > 1000 || CTRL.test(s))
+            throw new ObjectError(`The value of "${name}" is not valid`);
+        if (def.type === 'number') {
+            const n = Number(s);
+            if (!Number.isInteger(n) || (def.min !== undefined && n < def.min) || (def.max !== undefined && n > def.max))
+                throw new ObjectError(`"${name}" must be a whole number${def.min !== undefined ? ` from ${def.min} to ${def.max}` : ''}`);
+        }
+        else if (def.type === 'boolean') {
+            if (s !== 'true' && s !== 'false')
+                throw new ObjectError(`"${name}" must be true or false`);
+        }
+        else if (def.type === 'choice') {
+            if (!def.choices.includes(s))
+                throw new ObjectError(`"${name}" must be one of: ${def.choices.join(', ')}`);
+        }
+        else if (def.type === 'file') {
+            if (!s.startsWith('/'))
+                throw new ObjectError(`"${name}" must be the absolute path of a file`);
+        }
+        else if (name === 'search_path' && !/^[A-Za-z0-9_$," .-]+$/.test(s))
+            throw new ObjectError('The search_path has characters that are not allowed');
+        else if (name === 'options' && !/^[A-Za-z0-9_$=\-.,:/ ]+$/.test(s))
+            throw new ObjectError('"options" has characters that are not allowed');
+        else if (name === 'instanceName' && !/^[A-Za-z0-9_$#@-]{1,128}$/.test(s))
+            throw new ObjectError('The instance name is not valid');
+        out[name] = s;
+    }
+    if (Object.keys(out).length > MAX_PROPS)
+        throw new ObjectError(`At most ${MAX_PROPS} driver properties`);
+    return Object.keys(out).length ? out : undefined;
+}
+/** The properties as the driver wants them: numbers and booleans typed, files read (a missing file says which property it was). */
+export function propValues(engine, props) {
+    const out = {};
+    for (const def of DRIVER_PROPS[engine]) {
+        const v = props?.[def.name];
+        if (v === undefined)
+            continue;
+        if (def.type === 'number')
+            out[def.name] = Number(v);
+        else if (def.type === 'boolean')
+            out[def.name] = v === 'true';
+        else if (def.type === 'file') {
+            try {
+                if (!statSync(v).isFile())
+                    throw new Error('not a file');
+                out[def.name] = readFileSync(v, 'utf8');
+            }
+            catch {
+                throw new ObjectError(`"${def.name}": the file ${v} cannot be read`);
+            }
+        }
+        else
+            out[def.name] = v;
+    }
+    return out;
+}
+/** The `ssl.*` properties as the options of a TLS socket (Node's `tls.connect`). */
+export function tlsOptions(v, verify) {
+    const o = { rejectUnauthorized: verify };
+    const pick = [['ssl.ca', 'ca'], ['ssl.cert', 'cert'], ['ssl.key', 'key'], ['ssl.minVersion', 'minVersion'], ['ssl.ciphers', 'ciphers'], ['ssl.servername', 'servername']];
+    for (const [from, to] of pick)
+        if (v[from] !== undefined)
+            o[to] = v[from];
+    return o;
+}
+/** The properties that are not `ssl.*`, ready to spread in the options of a driver. */
+export const plain = (v) => Object.fromEntries(Object.entries(v).filter(([k]) => !k.startsWith('ssl.')));

package/server/dist/objects/exec.js

@@ -0,0 +1,16 @@
+import { execFile } from 'node:child_process';
+/**
+ * Runs a program without a shell (every value is one argument) and always resolves: output, exit code and whether it was missing or
+ * timed out. Callers decide what each case means for them. A death by signal or an overflowed buffer counts as a failure (code 1).
+ */
+export function execCapture(file, args, o = {}) {
+    return new Promise((resolve) => {
+        execFile(file, args, { cwd: o.cwd, timeout: o.timeout ?? 15_000, maxBuffer: o.maxBuffer ?? 8 * 1024 * 1024, env: o.env, encoding: 'utf8' }, (e, stdout, stderr) => {
+            resolve({
+                out: String(stdout ?? ''), err: String(stderr ?? ''),
+                code: e ? (typeof e.code === 'number' ? e.code : 1) : 0,
+                missing: e?.code === 'ENOENT', timedOut: !!e?.killed && e?.code !== 'ENOENT',
+            });
+        });
+    });
+}

package/server/dist/objects/http-history.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from '../db.js';
+const HISTORY_MAX = 100, BODY_MAX = 100_000;
+const DIR = join(DATA_DIR, 'http-history');
+const fileOf = (id) => join(DIR, `${id.replace(/[^\w-]/g, '')}.json`);
+const cache = new Map();
+function load(id) {
+    let list = cache.get(id);
+    if (!list) {
+        try {
+            list = existsSync(fileOf(id)) ? JSON.parse(readFileSync(fileOf(id), 'utf8')) : [];
+        }
+        catch {
+            list = [];
+        }
+        cache.set(id, list);
+    }
+    return list;
+}
+function save(id, list) {
+    try {
+        mkdirSync(DIR, { recursive: true });
+        const tmp = `${fileOf(id)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(list));
+        renameSync(tmp, fileOf(id));
+    }
+    catch { /* the history is a convenience: never break a run for it */ }
+}
+export function recordRun(id, e) {
+    const list = load(id);
+    const run = e.run ? { ...e.run, body: e.run.body.length > BODY_MAX ? e.run.body.slice(0, BODY_MAX) : e.run.body, truncated: e.run.truncated || e.run.body.length > BODY_MAX } : undefined;
+    const entry = { ...e, run, n: (list[0]?.n ?? 0) + 1, at: Date.now() };
+    list.unshift(entry);
+    if (list.length > HISTORY_MAX)
+        list.length = HISTORY_MAX;
+    save(id, list);
+    return entry;
+}
+export const listHistory = (id) => load(id);
+export function clearHistory(id) { cache.delete(id); try {
+    rmSync(fileOf(id), { force: true });
+}
+catch { /* nothing to remove */ } }