@andrian.yablonskyy/thub-coordinator 1.0.38 → 1.0.40

package/src/services/registry.js

@@ -696,6 +696,39 @@ function createRegistryService(db, { bus, events }){
     return { resource: get(resourceId), ignored };
   }
 
+  // Groups tab (resource card): the Client's group membership. It belongs to
+  // the Client's config file (`groups`, which every registration reports),
+  // so it goes out as the next config revision — like an Import's top-level
+  // fields — for the Client to write there and restart with. The Coordinator
+  // applies it at once too, so scheduling follows without waiting for that.
+  // Fields of an Import not applied yet are carried along, not lost.
+  function setClientGroups(resourceId, groupIds, { by, knownGroupIds } = {}){
+    const r = get(resourceId);
+    if (!r){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    const ids = [...new Set(groupIds)],
+      unknown = knownGroupIds ? ids.filter((id) => !knownGroupIds.includes(id) && !r.group_ids.includes(id)) : [];
+    if (unknown.length){
+      throw Object.assign(new Error(`Unknown group: ${unknown.join(', ')}`), { status: 400 });
+    }
+    // Writing top-level fields needs a Client that reports its config file
+    // (the same that Import needs); an older one would drop them.
+    const desired = r.config_desired || r.client_config;
+    if (!desired || !r.client_config_file){
+      throw Object.assign(new Error(`${r.name} is too old to take its groups from the dashboard — update its Client first`), { status: 409 });
+    }
+    const revision = r.config_revision + 1,
+      fields = { ...(pendingImport(r) || {}), groups: ids };
+    db.transaction(() => {
+      db.prepare(`UPDATE resources SET config_desired = ?, config_revision = ?, config_error = NULL, config_import = ?
+                  WHERE id = ?`).run(JSON.stringify(desired), revision, JSON.stringify({ revision, fields }), resourceId);
+      setGroups(resourceId, ids);
+    })();
+    events.record('resource', resourceId, 'resource.groups_set', { by, revision, groups: ids });
+    return get(resourceId);
+  }
+
   // Export (resource card): the Client's config file as it last reported it
   // (secrets excluded), with what's saved for it but not applied yet — so
   // exporting right after an edit or import gives what the Client will run.
@@ -796,6 +829,7 @@ function createRegistryService(db, { bus, events }){
     setRebootSchedule,
     pendingRebootSchedule,
     setClientConfig,
+    setClientGroups,
     pendingConfig,
     importClientConfig,
     exportClientConfig,

package/src/services/retention.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/coordinator/src/services/retention.js
- * @description Deletes finished jobs' logs/artifacts past their retention window (README §9)
+ * @description Nightly consistent database backup (VACUUM INTO, README §9)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -17,20 +17,11 @@ const path = require('node:path');
 
 const DAY_MS = 86400 * 1000;
 
-// §9: fold job_logs into a console.log artifact when a job finishes, purge
-// old logs/artifacts on the configured retention windows, and take a nightly
-// consistent backup via VACUUM INTO.
-function createRetentionService(db, { bus, logs, artifacts, config }){
-  bus.on('job.finished', ({ jobId }) => {
-    const text = logs.renderConsoleLog(jobId);
-    if (text){
-      artifacts.storeGenerated(jobId, 'console.log', Buffer.from(text, 'utf8'), 'text/plain');
-    }
-  });
-
+// §9: a nightly consistent backup via VACUUM INTO. (A job's log lines live
+// as long as the job itself — retention.jobRetention / Clean up database,
+// services/cleanup.js — and there are no artifacts to purge any more.)
+function createRetentionService(db, { config }){
   function runDaily(){
-    logs.purgeOlderThan(config.retention.logRetentionDays);
-    artifacts.purgeOlderThan(config.retention.artifactRetentionDays);
     const backupPath = path.join(config.dataDir, `backup-${new Date().toISOString().slice(0, 10)}.db`);
     db.exec(`VACUUM INTO '${backupPath.replace(/'/g, '\'\'')}'`);
   }

package/src/services/session-store.js

@@ -0,0 +1,127 @@
+/**
+ * @file        packages/coordinator/src/services/session-store.js
+ * @description Dashboard session store in the Coordinator's SQLite database: survives restarts, prunes expired sessions
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const session = require('express-session');
+
+// express-session's default MemoryStore loses every session on a restart,
+// never drops expired ones (memory only grows) and warns against itself in
+// production. This one keeps them in the `sessions` table (migration 022),
+// so signing in survives a Coordinator restart or self-update, and an
+// expired session is deleted when read and by a periodic sweep.
+const PRUNE_INTERVAL_MS = 15 * 60 * 1000,
+  // A session without a cookie expiry (never the case here: routes.js sets
+  // each user's idle timeout) is kept this long.
+  FALLBACK_TTL_MS = 24 * 60 * 60 * 1000;
+
+class SqliteSessionStore extends session.Store{
+  constructor(db, { pruneIntervalMs = PRUNE_INTERVAL_MS, now = Date.now } = {}){
+    super();
+    this.now = now;
+    this.stmts = {
+      get: db.prepare('SELECT sess, expires FROM sessions WHERE sid = ?'),
+      set: db.prepare(
+        `INSERT INTO sessions (sid, sess, expires) VALUES (?, ?, ?)
+         ON CONFLICT(sid) DO UPDATE SET sess = excluded.sess, expires = excluded.expires`
+      ),
+      touch: db.prepare('UPDATE sessions SET sess = ?, expires = ? WHERE sid = ?'),
+      destroy: db.prepare('DELETE FROM sessions WHERE sid = ?'),
+      prune: db.prepare('DELETE FROM sessions WHERE expires <= ?'),
+      length: db.prepare('SELECT COUNT(*) AS n FROM sessions WHERE expires > ?'),
+      clear: db.prepare('DELETE FROM sessions')
+    };
+    if (pruneIntervalMs > 0){
+      this.pruneTimer = setInterval(() => this.prune(), pruneIntervalMs);
+      this.pruneTimer.unref?.();
+    }
+  }
+
+  expiresOf(sess){
+    const at = sess?.cookie?.expires ? new Date(sess.cookie.expires).getTime() : NaN;
+    return Number.isFinite(at) ? at : this.now() + FALLBACK_TTL_MS;
+  }
+
+  // Each method answers through `cb`, as express-session expects; errors
+  // (a locked or broken database) go there too instead of throwing.
+  run(cb, fn){
+    let result;
+    try {
+      result = fn();
+    }
+    catch (err){
+      return cb?.(err);
+    }
+    cb?.(null, result);
+  }
+
+  get(sid, cb){
+    this.run(cb, () => {
+      const row = this.stmts.get.get(sid);
+      if (!row){
+        return null;
+      }
+      if (row.expires <= this.now()){
+        this.stmts.destroy.run(sid);
+        return null;
+      }
+      return JSON.parse(row.sess);
+    });
+  }
+
+  set(sid, sess, cb){
+    this.run(cb, () => {
+      this.stmts.set.run(sid, JSON.stringify(sess), this.expiresOf(sess));
+    });
+  }
+
+  // Called for a request that didn't change the session: moves its expiry
+  // (rolling idle timeout, §10.1). A passive live-update request leaves the
+  // cookie's expiry as it was (server.js), so this writes the same value.
+  touch(sid, sess, cb){
+    this.run(cb, () => {
+      this.stmts.touch.run(JSON.stringify(sess), this.expiresOf(sess), sid);
+    });
+  }
+
+  destroy(sid, cb){
+    this.run(cb, () => {
+      this.stmts.destroy.run(sid);
+    });
+  }
+
+  length(cb){
+    this.run(cb, () => this.stmts.length.get(this.now()).n);
+  }
+
+  clear(cb){
+    this.run(cb, () => {
+      this.stmts.clear.run();
+    });
+  }
+
+  prune(){
+    try {
+      return this.stmts.prune.run(this.now()).changes;
+    }
+    catch {
+      return 0; // the next sweep tries again
+    }
+  }
+
+  close(){
+    clearInterval(this.pruneTimer);
+  }
+}
+
+module.exports = { SqliteSessionStore };

package/src/services/settings.js

@@ -0,0 +1,345 @@
+/**
+ * @file        packages/coordinator/src/services/settings.js
+ * @description Coordinator settings editable from the dashboard (/admin/settings): stored in the database, layered over the config file
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const { JOB_RETENTION } = require('./cleanup');
+
+// README §13.2. Precedence, lowest first: built-in default < config file <
+// dashboard setting (the `settings` table) < environment variable. The
+// dashboard can't write the config file — the systemd unit only lets the
+// service write its data directory — so its changes live in the database.
+//
+// `applies`: "now" — the code reads it on every use, so saving takes effect
+// at once; "restart" — read once at startup (timers, middleware), so it
+// takes effect when the Coordinator restarts. Settings that could cut the
+// dashboard off from the inside (listen, dataDir, sessionSecret) stay in
+// the config file.
+const int = (min, max) => (raw) => {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min || n > max){
+      throw new Error(`must be a whole number from ${min} to ${max}`);
+    }
+    return n;
+  },
+  bool = (raw) => raw === true || raw === 'true' || raw === 'on' || raw === '1',
+  oneOf = (values) => (raw) => {
+    const v = values.find((x) => String(x) === String(raw));
+    if (v === undefined){
+      throw new Error(`must be one of: ${values.join(', ')}`);
+    }
+    return v;
+  },
+
+  SETTINGS = [
+    {
+      key: 'publicUrl', group: 'General', label: 'Public URL', applies: 'now', env: 'THUB_PUBLIC_URL', type: 'text',
+      help: 'The https:// address Agents, Clients and browsers use. Job links and the dashboard\'s same-origin check use it.',
+      parse: (raw) => {
+        const s = String(raw).trim().replace(/\/+$/, '');
+        let url;
+        try {
+          url = new URL(s);
+        }
+        catch {
+          throw new Error('must be a URL like https://thub.example.com');
+        }
+        if (!/^https?:$/.test(url.protocol) || url.pathname !== '/' || url.search || url.hash){
+          throw new Error('must be just http(s)://host[:port], without a path');
+        }
+        return s;
+      }
+    },
+    {
+      key: 'clientJoinKey', group: 'General', label: 'Client join key', applies: 'now', env: 'THUB_CLIENT_JOIN_KEY', type: 'secret',
+      help: 'The shared secret Clients self-register with (joinKey in their config). Empty turns self-registration off. ' +
+        'Running Clients keep working; one with an old key can\'t register again after its next restart.',
+      parse: (raw) => {
+        const s = String(raw ?? '').trim();
+        if (s && s.length < 16){
+          throw new Error('must be at least 16 characters (or empty to turn registration off)');
+        }
+        return s || null;
+      }
+    },
+    {
+      key: 'trustProxy', group: 'General', label: 'Trusted proxies', applies: 'restart', type: 'text',
+      help: 'Whose X-Forwarded-For/-Proto to believe: loopback (a proxy on this host), a CIDR such as 10.0.0.0/8, ' +
+        'a number of hops, or false. Wrong values break HTTPS detection and sign-in behind a proxy.',
+      parse: (raw) => {
+        const s = String(raw).trim();
+        if (s === 'false' || s === 'true'){
+          return s === 'true';
+        }
+        if (/^\d+$/.test(s)){
+          return Number(s);
+        }
+        if (!/^[\w.:/,\s-]+$/.test(s) || !s){
+          throw new Error('must be loopback, uniquelocal, linklocal, IP addresses/CIDRs (comma-separated), a hop count, true or false');
+        }
+        return s;
+      }
+    },
+    {
+      key: 'session.secureCookie', group: 'General', label: 'Secure session cookie', applies: 'restart', type: 'select',
+      options: ['auto', 'true', 'false'],
+      help: 'auto: HTTPS-only whenever the public URL is https://. true/false force it.',
+      parse: (raw) => ({ auto: 'auto', true: true, false: false })[String(raw)] ?? oneOf(['auto', 'true', 'false'])(raw)
+    },
+    {
+      key: 'heartbeat.intervalSec', group: 'Heartbeat', label: 'Heartbeat interval (s)', applies: 'now', type: 'number',
+      help: 'How often Clients report. They switch to a new value with their next heartbeat (lowering it, the old one is ' +
+        'still allowed for a while). Clients older than this setting keep their own heartbeatIntervalSec (10 by default): ' +
+        'don\'t go below that while any are connected.',
+      parse: int(2, 300)
+    },
+    {
+      key: 'heartbeat.missedLimit', group: 'Heartbeat', label: 'Missed heartbeats allowed', applies: 'now', type: 'number',
+      help: 'A Client that misses this many in a row goes OUT_OF_SERVICE, and its running job becomes LOST.',
+      parse: int(2, 20)
+    },
+    {
+      key: 'heartbeat.sweepIntervalSec', group: 'Heartbeat', label: 'Check every (s)', applies: 'restart', type: 'number',
+      help: 'How often missed heartbeats, unaccepted assignments and job timeouts are checked.',
+      parse: int(1, 60)
+    },
+    {
+      key: 'rateLimit.requestsPerMinute', group: 'Rate limits', label: 'Requests per minute', applies: 'now', type: 'number',
+      help: 'Per caller: an agent or resource token, a dashboard user, else the IP address. Short bursts are fine; ' +
+        'past that, requests get 429 with Retry-After. A Client streaming logs makes up to ~240 a minute. 0: no limit.',
+      parse: int(0, 1_000_000)
+    },
+    {
+      key: 'rateLimit.loginPerMinute', group: 'Rate limits', label: 'Sign-in attempts per minute', applies: 'now', type: 'number',
+      help: 'Per IP address, against password guessing. 0: no limit.',
+      parse: int(0, 10_000)
+    },
+    {
+      key: 'jobs.defaultTimeoutSec', group: 'Jobs', label: 'Default job timeout (s)', applies: 'now', type: 'number',
+      help: 'For a job submitted without --timeout.', parse: int(60, 7 * 86400)
+    },
+    {
+      key: 'jobs.maxTimeoutSec', group: 'Jobs', label: 'Maximum job timeout (s)', applies: 'now', type: 'number',
+      help: 'A longer --timeout is cut to this.', parse: int(60, 7 * 86400)
+    },
+    {
+      key: 'scheduler.assignAckTimeoutSec', group: 'Scheduler', label: 'Accept timeout (s)', applies: 'now', type: 'number',
+      help: 'How long an assigned job waits for its Client to accept it before going back to the queue.', parse: int(5, 600)
+    },
+    {
+      key: 'scheduler.requeueOnLost', group: 'Scheduler', label: 'Retry lost jobs', applies: 'now', type: 'checkbox',
+      help: 'Requeue a job once when its Client goes offline mid-job.', parse: bool
+    },
+    {
+      key: 'scheduler.maxQueuedPerAgent', group: 'Scheduler', label: 'Max queued jobs per agent', applies: 'now', type: 'number',
+      help: 'Further submissions from that agent are refused until some run.', parse: int(1, 10000)
+    },
+    {
+      key: 'scheduler.tickIntervalSec', group: 'Scheduler', label: 'Safety-net pass (s)', applies: 'restart', type: 'number',
+      help: 'The scheduler also runs on every queued job and free Client; this periodic pass only catches anything missed.',
+      parse: int(1, 3600)
+    },
+    {
+      key: 'retention.jobRetention', group: 'Retention', label: 'Keep finished jobs', applies: 'now', type: 'select',
+      options: Object.keys(JOB_RETENTION), labels: Object.fromEntries(Object.entries(JOB_RETENTION).map(([k, v]) => [k, v.label])),
+      help: 'Older finished jobs, with their logs, are deleted hourly. forever: only by Clean up database.',
+      parse: oneOf(Object.keys(JOB_RETENTION))
+    },
+    {
+      key: 'updates.checkIntervalMin', group: 'Updates', label: 'Version check every (min)', applies: 'restart', type: 'number',
+      help: 'How often to look for new Coordinator/Agent/Client releases. 0 turns the periodic check off.', parse: int(0, 1440)
+    },
+    {
+      key: 'updates.registry', group: 'Updates', label: 'npm registry', applies: 'restart', type: 'text',
+      help: 'Empty: the public npm registry (or npm_config_registry). Set it for a private mirror.',
+      parse: (raw) => {
+        const s = String(raw ?? '').trim();
+        if (s && !/^https?:\/\/\S+$/.test(s)){
+          throw new Error('must be an http(s):// URL, or empty');
+        }
+        return s || null;
+      }
+    }
+  ],
+  BY_KEY = new Map(SETTINGS.map((s) => [s.key, s])),
+
+  getPath = (obj, key) => key.split('.').reduce((o, k) => o?.[k], obj),
+  setPath = (obj, key, value) => {
+    const parts = key.split('.'),
+      last = parts.pop(),
+      parent = parts.reduce((o, k) => (o[k] ??= {}), obj);
+    parent[last] = value;
+  },
+  same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// `config` is the live object every service holds: "now" settings are
+// written into it, so they take effect on the next use.
+function createSettingsService(db, { config, env = process.env }){
+  const stmts = {
+      all: db.prepare('SELECT key, value, updated_at, updated_by FROM settings'),
+      upsert: db.prepare(
+        `INSERT INTO settings (key, value, updated_at, updated_by) VALUES (?, ?, ?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at, updated_by = excluded.updated_by`
+      ),
+      remove: db.prepare('DELETE FROM settings WHERE key = ?')
+    },
+    // What the config file (plus defaults) said, before any dashboard
+    // setting: what "Reset" goes back to.
+    fileValues = Object.fromEntries(SETTINGS.map((s) => [s.key, structuredClone(getPath(config, s.key))]));
+  let running = null; // the values this process started with (for "after restart")
+
+  function stored(){
+    const rows = {};
+    for (const r of stmts.all.all()){
+      if (BY_KEY.has(r.key)){
+        rows[r.key] = { value: JSON.parse(r.value), updatedAt: r.updated_at, updatedBy: r.updated_by };
+      }
+    }
+    return rows;
+  }
+
+  const envLocked = (s) => Boolean(s.env && env[s.env]);
+
+  // What each setting resolves to right now: env > dashboard > file.
+  function desired(rows = stored()){
+    return Object.fromEntries(SETTINGS.map((s) => [
+      s.key,
+      envLocked(s) ? getPath(config, s.key) : s.key in rows ? rows[s.key].value : fileValues[s.key]
+    ]));
+  }
+
+  // At startup: put the dashboard's settings into the config every service
+  // reads. Then remember what this process runs with.
+  function applyAtStartup(){
+    const rows = stored();
+    // A value saved by an older version that this one no longer accepts is
+    // skipped (with a warning), not allowed to stop the Coordinator.
+    for (const [key, { value }]of Object.entries(rows)){
+      try {
+        BY_KEY.get(key).parse(value === null ? '' : value);
+      }
+      catch (err){
+        console.warn(`Ignoring dashboard setting ${key}=${JSON.stringify(value)}: ${err.message}`);
+        delete rows[key];
+      }
+    }
+    const want = desired(rows);
+    for (const s of SETTINGS){
+      setPath(config, s.key, structuredClone(want[s.key]));
+    }
+    running = structuredClone(want);
+    return service;
+  }
+
+  // For the settings page.
+  function list(){
+    const rows = stored(),
+      want = desired(rows);
+    return SETTINGS.map((s) => ({
+      ...s,
+      value: want[s.key],
+      fileValue: fileValues[s.key],
+      source: envLocked(s) ? 'env' : s.key in rows ? 'dashboard' : 'file',
+      updatedAt: rows[s.key]?.updatedAt,
+      updatedBy: rows[s.key]?.updatedBy,
+      pendingRestart: s.applies === 'restart' && !same(want[s.key], running?.[s.key])
+    }));
+  }
+
+  // `changes`: { key: rawValue } for the settings to set, `reset`: keys to
+  // put back to the config file's value. Validates everything first, so a
+  // bad value saves nothing. Returns what changed.
+  function save({ changes = {}, reset = [] }, { by, guard } = {}){
+    const rows = stored(),
+      before = desired(rows),
+      parsed = {},
+      errors = [];
+    for (const [key, raw]of Object.entries(changes)){
+      const s = BY_KEY.get(key);
+      if (!s || envLocked(s) || reset.includes(key)){
+        continue;
+      }
+      try {
+        parsed[key] = s.parse(raw);
+      }
+      catch (err){
+        errors.push(`${s.label}: ${err.message}`);
+      }
+    }
+    const after = { ...before, ...parsed };
+    for (const key of reset){
+      if (BY_KEY.has(key) && !envLocked(BY_KEY.get(key))){
+        after[key] = fileValues[key];
+      }
+    }
+    if (after['jobs.defaultTimeoutSec'] > after['jobs.maxTimeoutSec']){
+      errors.push('Default job timeout: can\'t be longer than the maximum job timeout');
+    }
+    if (!errors.length && guard){
+      const problem = guard(after);
+      if (problem){
+        errors.push(problem);
+      }
+    }
+    if (errors.length){
+      throw Object.assign(new Error(errors.join('\n')), { status: 400 });
+    }
+
+    const now = new Date().toISOString(),
+      changed = [];
+    db.transaction(() => {
+      for (const s of SETTINGS){
+        if (envLocked(s)){
+          continue;
+        }
+        if (reset.includes(s.key) && s.key in rows){
+          stmts.remove.run(s.key);
+        }
+        else if (s.key in parsed && !same(parsed[s.key], before[s.key])){
+          stmts.upsert.run(s.key, JSON.stringify(parsed[s.key]), now, by || null);
+        }
+        else {
+          continue;
+        }
+        if (!same(after[s.key], before[s.key])){
+          changed.push(s);
+        }
+      }
+    })();
+    for (const s of changed){
+      if (s.applies === 'now'){
+        setPath(config, s.key, structuredClone(after[s.key]));
+      }
+    }
+    return {
+      changed: changed.map((s) => s.key),
+      now: changed.filter((s) => s.applies === 'now').map((s) => s.key),
+      restart: changed.filter((s) => s.applies === 'restart').map((s) => s.key)
+    };
+  }
+
+  // thub-admin settings reset — the way back if a setting locked you out:
+  // the named settings (all when none) go back to the config file's value
+  // at the next start.
+  function reset(keys = []){
+    if (!keys.length){
+      return db.prepare('DELETE FROM settings').run().changes;
+    }
+    return keys.reduce((n, k) => n + stmts.remove.run(k).changes, 0);
+  }
+
+  const service = { list, save, reset, applyAtStartup, SETTINGS };
+  return service;
+}
+
+module.exports = { createSettingsService, SETTINGS };