@andrian.yablonskyy/thub-coordinator 1.0.0

package/src/services/agents.js

@@ -0,0 +1,56 @@
+/**
+ * @file        packages/coordinator/src/services/agents.js
+ * @description Agent (CI/CD and developer) identity management: create, list, tokens
+ *
+ * @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 { v4: uuid } = require('uuid'),
+  { generateToken, hashToken } = require('./tokens');
+
+function createAgentsService(db, { events }){
+  function get(id){
+    return db.prepare('SELECT * FROM agents WHERE id = ?').get(id);
+  }
+
+  function getByTokenHash(tokenHash){
+    return db
+      .prepare('SELECT * FROM agents WHERE token_hash = ? AND revoked_at IS NULL')
+      .get(tokenHash);
+  }
+
+  function list(){
+    return db.prepare('SELECT id, name, kind, created_at, last_used_at, revoked_at FROM agents ORDER BY created_at DESC').all();
+  }
+
+  function create({ name, kind }){
+    const id = `agt_${uuid()}`,
+      token = generateToken('agt');
+    db.prepare(
+      'INSERT INTO agents (id, name, kind, token_hash, created_at) VALUES (?, ?, ?, ?, ?)'
+    ).run(id, name, kind, hashToken(token), new Date().toISOString());
+    events.record('agent', id, 'agent.created', { name, kind });
+    return { agent: get(id), token };
+  }
+
+  function revoke(id){
+    db.prepare('UPDATE agents SET revoked_at = ? WHERE id = ?').run(new Date().toISOString(), id);
+    events.record('agent', id, 'agent.revoked', {});
+  }
+
+  function touchLastUsed(id){
+    db.prepare('UPDATE agents SET last_used_at = ? WHERE id = ?').run(new Date().toISOString(), id);
+  }
+
+  return { get, getByTokenHash, list, create, revoke, touchLastUsed };
+}
+
+module.exports = { createAgentsService };

package/src/services/artifacts.js

@@ -0,0 +1,149 @@
+/**
+ * @file        packages/coordinator/src/services/artifacts.js
+ * @description Job artifact storage: saves uploaded files and generates download links
+ *
+ * @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 fs = require('node:fs'),
+  path = require('node:path'),
+  crypto = require('node:crypto');
+
+// §3.1 / §12: stores uploaded result files under artifacts/<jobId>/ and
+// generates HMAC-signed, time-limited download links (no server-side
+// session needed for the Agent/CI to fetch them).
+function createArtifactsService(db, { config }){
+  const secret = config.sessionSecret;
+
+  function jobDir(jobId){
+    const dir = path.join(config.artifactsDir, jobId);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  function sha256File(filePath){
+    const hash = crypto.createHash('sha256');
+    hash.update(fs.readFileSync(filePath));
+    return hash.digest('hex');
+  }
+
+  // `files` are multer file objects already written to a temp path.
+  function storeUploaded(jobId, files){
+    const dir = jobDir(jobId),
+      stored = [];
+    for (const file of files){
+      const dest = path.join(dir, path.basename(file.originalname));
+      fs.renameSync(file.path, dest);
+      const sha256 = sha256File(dest),
+        size = fs.statSync(dest).size,
+        info = db
+          .prepare(
+            `INSERT INTO artifacts (job_id, name, path, size, sha256, content_type, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`
+          )
+          .run(jobId, file.originalname, dest, size, sha256, file.mimetype, new Date().toISOString());
+      stored.push(get(info.lastInsertRowid));
+    }
+    return stored;
+  }
+
+  function storeGenerated(jobId, name, buffer, contentType){
+    const dir = jobDir(jobId),
+      dest = path.join(dir, name);
+    fs.writeFileSync(dest, buffer);
+    const info = db
+      .prepare(
+        `INSERT INTO artifacts (job_id, name, path, size, sha256, content_type, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(jobId, name, dest, buffer.length, sha256File(dest), contentType, new Date().toISOString());
+    return get(info.lastInsertRowid);
+  }
+
+  function get(id){
+    return db.prepare('SELECT * FROM artifacts WHERE id = ?').get(id);
+  }
+
+  function listForJob(jobId){
+    return db.prepare('SELECT * FROM artifacts WHERE job_id = ? ORDER BY id ASC').all(jobId);
+  }
+
+  function sign(artifactId, ttlHours = config.artifacts.linkTtlHours){
+    const expiresAt = Date.now() + ttlHours * 3600 * 1000,
+      payload = `${artifactId}.${expiresAt}`,
+      mac = crypto.createHmac('sha256', secret).update(payload).digest('base64url');
+    return `${payload}.${mac}`;
+  }
+
+  function verify(token){
+    const [artifactId, expiresAt, mac] = String(token).split('.');
+    if (!artifactId || !expiresAt || !mac){
+      throw invalidLink();
+    }
+    const payload = `${artifactId}.${expiresAt}`,
+      expectedMac = crypto.createHmac('sha256', secret).update(payload).digest('base64url');
+    if (!crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expectedMac))){
+      throw invalidLink();
+    }
+    if (Date.now() > Number(expiresAt)){
+      throw invalidLink('Link expired');
+    }
+    const artifact = get(Number(artifactId));
+    if (!artifact){
+      throw invalidLink();
+    }
+    return artifact;
+  }
+
+  function invalidLink(message = 'Invalid or expired link'){
+    return Object.assign(new Error(message), { status: 403 });
+  }
+
+  function signedUrl(artifact){
+    return `${config.publicUrl}/artifacts/download/${sign(artifact.id)}`;
+  }
+
+  // Removes a job's artifact files from disk (not the DB rows — the
+  // caller, jobs.js's cleanHistory, deletes those as part of the same
+  // transaction that also deletes the job itself).
+  function deleteJobArtifacts(jobId){
+    fs.rmSync(path.join(config.artifactsDir, jobId), { recursive: true, force: true });
+  }
+
+  function purgeOlderThan(days){
+    const cutoff = new Date(Date.now() - days * 86400 * 1000).toISOString(),
+      stale = db
+        .prepare(
+          `SELECT a.* FROM artifacts a JOIN jobs j ON j.id = a.job_id
+         WHERE j.finished_at IS NOT NULL AND j.finished_at <= ?`
+        )
+        .all(cutoff);
+    for (const artifact of stale){
+      fs.rmSync(artifact.path, { force: true });
+      db.prepare('DELETE FROM artifacts WHERE id = ?').run(artifact.id);
+    }
+  }
+
+  return {
+    storeUploaded,
+    storeGenerated,
+    get,
+    listForJob,
+    sign,
+    verify,
+    signedUrl,
+    purgeOlderThan,
+    deleteJobArtifacts,
+    jobDir
+  };
+}
+
+module.exports = { createArtifactsService };

package/src/services/bus.js

@@ -0,0 +1,23 @@
+/**
+ * @file        packages/coordinator/src/services/bus.js
+ * @description In-process event bus used to fan out log/state changes to SSE subscribers (README §3.1)
+ *
+ * @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 { EventEmitter } = require('node:events');
+
+// §3.1: "An in-process EventEmitter. The Coordinator is a single process
+// by design; SQLite plus one process is enough for tens of runners and
+// hundreds of jobs per day."
+class Bus extends EventEmitter{}
+
+module.exports = { bus: new Bus() };

package/src/services/commands.js

@@ -0,0 +1,43 @@
+/**
+ * @file        packages/coordinator/src/services/commands.js
+ * @description In-memory per-resource command queue delivered via the heartbeat response (README §5.1)
+ *
+ * @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';
+
+// §5.1: "The commands[] field in the heartbeat response is how the
+// Coordinator talks to a Client without an inbound connection." Pending
+// commands are cheap and short-lived, so an in-memory queue per resource
+// is enough — consistent with the single-process design (§3.1).
+function createCommandsService({ bus }){
+  const pending = new Map(); // resourceId -> [{command, jobId?, ...}]
+
+  bus.on('command', ({ resourceId, ...command }) => {
+    if (!pending.has(resourceId)){
+      pending.set(resourceId, []);
+    }
+    pending.get(resourceId).push(command);
+  });
+
+  function drain(resourceId){
+    const commands = pending.get(resourceId) || [];
+    pending.delete(resourceId);
+    return commands;
+  }
+
+  function push(resourceId, command){
+    bus.emit('command', { resourceId, ...command });
+  }
+
+  return { drain, push };
+}
+
+module.exports = { createCommandsService };

package/src/services/events.js

@@ -0,0 +1,37 @@
+/**
+ * @file        packages/coordinator/src/services/events.js
+ * @description Audit log service: records every state change to the events table (README §12)
+ *
+ * @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';
+
+// §12 Audit: "All state changes are written to the events table and
+// visible on the dashboard."
+function createEventsService(db){
+  const insert = db.prepare(
+    'INSERT INTO events (ts, entity, entity_id, type, data) VALUES (?, ?, ?, ?, ?)'
+  );
+
+  function record(entity, entityId, type, data){
+    insert.run(new Date().toISOString(), entity, entityId, type, data ? JSON.stringify(data) : null);
+  }
+
+  function recent(limit = 50){
+    return db
+      .prepare('SELECT * FROM events ORDER BY id DESC LIMIT ?')
+      .all(limit)
+      .map((e) => ({ ...e, data: e.data ? JSON.parse(e.data) : null }));
+  }
+
+  return { record, recent };
+}
+
+module.exports = { createEventsService };

package/src/services/groups.js

@@ -0,0 +1,79 @@
+/**
+ * @file        packages/coordinator/src/services/groups.js
+ * @description Resource group management: create/list/update/remove groups and their membership (README §13.1)
+ *
+ * @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 { v4: uuid } = require('uuid');
+
+// Admin-managed resource groups (README §13.1) — a job can be constrained
+// to run only on resources that are members of a given group
+// (`thub run --group <id>`, job-spec.schema.js's `target.group`).
+// Membership itself lives on the resource (registry.js's `group_ids`,
+// declared by the Client's own config), not here — this service only
+// owns the groups' own identity (id/name/comment).
+function createGroupsService(db, { events, registry }){
+  function get(id){
+    return db.prepare('SELECT * FROM groups WHERE id = ?').get(id);
+  }
+
+  function list(){
+    return db.prepare('SELECT * FROM groups ORDER BY name ASC').all();
+  }
+
+  function create({ name, comment }){
+    const id = uuid();
+    db.prepare('INSERT INTO groups (id, name, comment, created_at) VALUES (?, ?, ?, ?)').run(
+      id,
+      name,
+      comment || null,
+      new Date().toISOString()
+    );
+    events.record('group', id, 'group.created', { name, comment });
+    return get(id);
+  }
+
+  function update(id, { name, comment }){
+    const group = get(id);
+    if (!group){
+      throw Object.assign(new Error('Unknown group'), { status: 404 });
+    }
+    db.prepare('UPDATE groups SET name = ?, comment = ? WHERE id = ?').run(
+      name ?? group.name,
+      comment !== undefined ? comment : group.comment,
+      id
+    );
+    events.record('group', id, 'group.updated', { name, comment });
+    return get(id);
+  }
+
+  // Deletes the group and strips it out of every resource's membership
+  // list — a resource whose config still lists this id just stops
+  // matching on it, rather than being left with a dangling reference.
+  function remove(id){
+    const group = get(id);
+    if (!group){
+      return;
+    }
+    for (const resource of registry.list()){
+      if (resource.group_ids.includes(id)){
+        registry.setGroups(resource.id, resource.group_ids.filter((g) => g !== id));
+      }
+    }
+    db.prepare('DELETE FROM groups WHERE id = ?').run(id);
+    events.record('group', id, 'group.deleted', { name: group.name });
+  }
+
+  return { get, list, create, update, remove };
+}
+
+module.exports = { createGroupsService };

package/src/services/heartbeat.js

@@ -0,0 +1,56 @@
+/**
+ * @file        packages/coordinator/src/services/heartbeat.js
+ * @description Heartbeat sweeper: marks silent resources OUT_OF_SERVICE and requeues their jobs
+ *
+ * @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 { RESOURCE_STATES, ACTIVE_JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+
+// §5.1 sweeper: runs every sweepIntervalSec, marks resources OUT_OF_SERVICE
+// after missedLimit missed heartbeats and moves any active job to LOST.
+function createHeartbeatMonitor(db, { bus, events, registry, jobs, config }){
+  function sweepOnce(){
+    const { intervalSec, missedLimit } = config.heartbeat,
+      cutoff = new Date(Date.now() - missedLimit * intervalSec * 1000).toISOString(),
+
+      stale = db
+        .prepare(
+          `SELECT * FROM resources
+         WHERE status NOT IN (?, ?)
+           AND last_heartbeat_at IS NOT NULL
+           AND last_heartbeat_at <= ?`
+        )
+        .all(RESOURCE_STATES.OUT_OF_SERVICE, RESOURCE_STATES.MAINTENANCE, cutoff);
+
+    for (const resource of stale){
+      registry.markOutOfService(resource.id);
+
+      const activeJob = db
+        .prepare(
+          `SELECT id, state FROM jobs WHERE resource_id = ? AND state IN (${[...ACTIVE_JOB_STATES]
+            .map(() => '?')
+            .join(',')})`
+        )
+        .get(resource.id, ...ACTIVE_JOB_STATES);
+      if (activeJob){
+        jobs.markLost(activeJob.id);
+      }
+    }
+  }
+
+  const timer = setInterval(sweepOnce, config.heartbeat.sweepIntervalSec * 1000);
+  timer.unref?.();
+
+  return { sweepOnce, stop: () => clearInterval(timer) };
+}
+
+module.exports = { createHeartbeatMonitor };