@andrian.yablonskyy/thub-coordinator 1.0.9 → 1.0.11

package/README.md

@@ -43,7 +43,8 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
   "scheduler": { "assignAckTimeoutSec": 15, "requeueOnLost": true, "maxQueuedPerAgent": 20, "tickIntervalSec": 10 },
   "jobs": { "defaultTimeoutSec": 1800, "maxTimeoutSec": 14400 },
   "retention": { "logRetentionDays": 14, "artifactRetentionDays": 30 },
-  "artifacts": { "maxUploadMb": 512, "linkTtlHours": 168 }
+  "artifacts": { "maxUploadMb": 512, "linkTtlHours": 168 },
+  "updates": { "checkIntervalHours": 6, "registry": null }
 }
 ```
 
@@ -100,6 +101,10 @@ thub-admin jobs clean --yes
 thub-admin group add ci-nightly --comment "shared CI pool"
 thub-admin group list
 thub-admin group remove <groupId>
+
+# The Coordinator is only ever updated by hand (never from the dashboard).
+thub-admin check-update                  # installed vs latest published version
+thub-admin self-update [--to <x.y.z>]    # sudo npm i -g; the postinstall restarts the service
 ```
 
 Both `jobs reset` and `jobs clean` refuse to run without `--yes` — there's no undo for either, especially `clean`.
@@ -120,13 +125,14 @@ All endpoints are under `/api/v1`, JSON, and require `Authorization: Bearer <tok
 | `GET` | `/jobs/:id/logs/stream` | Server-Sent Events: `log`, `state`, `end`. Honors `Last-Event-ID` for resume. |
 | `GET` | `/jobs/:id/artifacts` | Artifact list with signed download URLs. |
 | `GET` | `/resources` | Resources with status (read-only). |
+| `GET` | `/agents/me/update` | `{updateTo, latest}` — a self-update requested for the calling agent. |
 
 **Resource (Client) endpoints** (used by [thub-client](https://github.com/andrianyablonskyy/thub-client)):
 
 | Method | Path | Description |
 |---|---|---|
 | `POST` | `/resources/register` | Self-register (every start/restart) using the shared `clientJoinKey`; upserts by `clientId`. `hostInfo.addresses` (`[{iface, address, family}]`) lists the host's non-loopback interface addresses; the request's source address is stored as the external one. |
-| `POST` | `/resources/:id/heartbeat` | Heartbeat and self-reported state, plus the current `addresses`; refreshes the external address; response may carry `commands[]`. |
+| `POST` | `/resources/:id/heartbeat` | Heartbeat and self-reported state, plus the current `addresses`; refreshes the external address; response may carry `commands[]` (`cancel-job`, `self-update`). |
 | `POST` | `/resources/:id/status` | Explicit status change, e.g. a local lock. |
 | `GET` | `/resources/:id/jobs/next?wait=30` | Long-poll for an assigned job; `204` when nothing arrived within `wait` seconds. |
 | `POST` | `/jobs/:id/accept` | Acknowledge assignment. |
@@ -151,10 +157,17 @@ Server-rendered Pug templates styled with Bootstrap 5.3, with a little vanilla J
 | `/admin/agents` | Register/revoke CI and developer agents; token shown once. Shows each agent's last reported version. |
 | `/profile` | Every logged-in user's own account settings: display name, avatar, timezone (renders every dashboard timestamp), theme, idle session timeout, password change. |
 
-**Resource card.** Clicking a resource on `/` or `/resources` opens a card with its name, type, status, Client version, IP addresses, labels, groups, busy source/reason, last heartbeat and (admins only) the maintenance/rotate-token actions. IP addresses are the Client host's interface addresses except loopback (reported at registration and on every heartbeat) plus the external address — the one the Coordinator last saw the Client connect from, taken from `X-Forwarded-For` when the request came through a proxy `trustProxy` trusts.
+**Resource card.** Clicking a resource on `/` or `/resources` opens a card with its name, type, status, Client version, IP addresses, capabilities (reported at registration: HW udev devices with a **missing** flag for any whose device node doesn't exist, relay channels and power control; SW image, source and limits), labels, groups, busy source/reason, last heartbeat and (admins only) the maintenance/rotate-token actions. IP addresses are the Client host's interface addresses except loopback (reported at registration and on every heartbeat) plus the external address — the one the Coordinator last saw the Client connect from, taken from `X-Forwarded-For` when the request came through a proxy `trustProxy` trusts.
 
 The Coordinator's own version (`ver. X.Y.Z`) is shown under the TestHub logo, top left of every page.
 
+**Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalHours` (default 6, `0` disables; `updates.registry` for a private mirror) and on **Check for updates**. A newer Coordinator shows as a badge under the logo; Agents and Resources show each one's version with an **update available** or pending **→ vX.Y.Z** badge. Admins request self-updates per agent/resource (**Update**, which becomes **Cancel update**) or with **Update all agents** / **Update all clients**, always to the latest version:
+- Clients get a `self-update` command on their next heartbeat and install it through their root `thub-client-update` helper, once none of the host's instances is busy.
+- Agents install it at the start of their next run (`GET /api/v1/agents/me/update`), then re-run the command on the new version.
+- The Coordinator itself is updated by hand only: `thub-admin self-update`.
+
+A request is cleared when the Agent/Client reports the new version.
+
 ## Data storage
 
 SQLite via `better-sqlite3`, WAL mode. Schema migrations are plain numbered SQL files in `src/db/migrations/`, applied automatically at startup. `job_logs` rows are compacted into `artifacts/<jobId>/console.log` when a job finishes and deleted after `logRetentionDays`; artifacts are deleted after `artifactRetentionDays`. See the [main repo's ER diagram](https://github.com/andrianyablonskyy/thub#9-data-storage-sqlite) for the full schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {

package/src/api/resource.js

@@ -65,6 +65,7 @@ function createResourceRouter({ services, config }){
         labels: labels || capabilities?.labels || [],
         groups: groups || [],
         hostInfo,
+        capabilities,
         remoteAddr: req.ip,
         clientVersion: appVersion(req, 'client')
       });

package/src/db/migrations/011_add_capabilities.sql

@@ -0,0 +1,5 @@
+-- What the Client reported it can drive at registration (README §5.1,
+-- §10): its udev devices (with whether each is present), relays and power
+-- control for HW, or emulator image and limits for SW. JSON, NULL for
+-- Clients too old to report it.
+ALTER TABLE resources ADD COLUMN capabilities TEXT;

package/src/services/registry.js

@@ -25,7 +25,8 @@ function rowToResource(row){
     ...row,
     labels: JSON.parse(row.labels || '[]'),
     group_ids: JSON.parse(row.group_ids || '[]'),
-    host_info: row.host_info ? JSON.parse(row.host_info) : null
+    host_info: row.host_info ? JSON.parse(row.host_info) : null,
+    capabilities: row.capabilities ? JSON.parse(row.capabilities) : null
   };
 }
 
@@ -51,6 +52,52 @@ function normalizeRemoteAddr(addr){
   return typeof addr === 'string' && addr ? addr.replace(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/, '$1') : null;
 }
 
+// `capabilities` comes straight from the Client and is rendered on the
+// dashboard, so keep only the known shape, as plain strings/numbers/bools.
+const MAX_DEVICES = 8,
+  str = (v, max = 256) => (typeof v === 'string' && v ? v.slice(0, max) : null),
+  num = (v) => (Number.isFinite(v) ? v : null),
+  capList = (v) => (Array.isArray(v) ? v.slice(0, MAX_DEVICES) : []),
+  device = (d) => ({
+    path: str(d?.path),
+    index: num(d?.index),
+    serial: str(d?.serial, 64),
+    baudRate: num(d?.baudRate),
+    present: typeof d?.present === 'boolean' ? d.present : null
+  });
+
+function sanitizeCapabilities(caps){
+  if (!caps || typeof caps !== 'object'){
+    return null;
+  }
+  if (caps.sw && typeof caps.sw === 'object'){
+    const sw = caps.sw;
+    return {
+      sw: {
+        image: str(sw.image),
+        registry: str(sw.registry),
+        allowDockerHub: sw.allowDockerHub === true,
+        cpus: num(sw.cpus),
+        memory: str(sw.memory, 16)
+      }
+    };
+  }
+  if (caps.hw && typeof caps.hw === 'object'){
+    const hw = caps.hw,
+      power = hw.power && typeof hw.power === 'object' ? hw.power : null;
+    return {
+      hw: {
+        stlinks: capList(hw.stlinks).map(device),
+        uarts: capList(hw.uarts).map(device),
+        usbs: capList(hw.usbs).map(device),
+        relays: capList(hw.relays).map((r) => ({ channel: num(r?.channel), baseUrl: str(r?.baseUrl) })),
+        power: power ? { method: str(power.method, 32), hub: str(power.hub, 64), port: num(power.port) } : null
+      }
+    };
+  }
+  return null;
+}
+
 function createRegistryService(db, { bus, events }){
   function get(id){
     return rowToResource(db.prepare('SELECT * FROM resources WHERE id = ?').get(id));
@@ -106,10 +153,12 @@ function createRegistryService(db, { bus, events }){
   // this registration is allowed to reclaim it. Anything else (IDLE, BUSY,
   // MAINTENANCE, REGISTERED-but-just-created) means a process might still
   // be actively using that identity, so it stays a hard conflict.
-  function registerAuto({ clientId, name, type, labels = [], groups = [], hostInfo, remoteAddr, clientVersion = null }){
+  function registerAuto({ clientId, name, type, labels = [], groups = [], hostInfo, capabilities, remoteAddr, clientVersion = null }){
     const resourceToken = generateToken('res'),
       remote = normalizeRemoteAddr(remoteAddr);
     hostInfo = { ...(hostInfo || {}), addresses: sanitizeAddresses(hostInfo?.addresses) || [] };
+    const caps = sanitizeCapabilities(capabilities),
+      capsJson = caps ? JSON.stringify(caps) : null;
     let existing = getByClientId(clientId);
 
     if (!existing){
@@ -157,7 +206,7 @@ function createRegistryService(db, { bus, events }){
       db.prepare(
         `UPDATE resources
          SET token_hash = ?, client_id = ?, name = ?, type = ?, labels = ?, group_ids = ?, host_info = ?,
-             remote_addr = ?, client_version = ?, status = ?, busy_source = NULL, busy_reason = NULL
+             remote_addr = ?, client_version = ?, capabilities = ?, status = ?, busy_source = NULL, busy_reason = NULL
          WHERE id = ?`
       ).run(
         hashToken(resourceToken),
@@ -169,6 +218,7 @@ function createRegistryService(db, { bus, events }){
         JSON.stringify(hostInfo),
         remote,
         clientVersion,
+        capsJson,
         nextStatus,
         existing.id
       );
@@ -187,8 +237,9 @@ function createRegistryService(db, { bus, events }){
 
     const id = `res_${uuid()}`;
     db.prepare(
-      `INSERT INTO resources (id, name, type, status, labels, group_ids, host_info, remote_addr, client_version, token_hash, client_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      `INSERT INTO resources (id, name, type, status, labels, group_ids, host_info, remote_addr, client_version, capabilities,
+                              token_hash, client_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       id,
       name,
@@ -199,6 +250,7 @@ function createRegistryService(db, { bus, events }){
       JSON.stringify(hostInfo),
       remote,
       clientVersion,
+      capsJson,
       hashToken(resourceToken),
       clientId,
       new Date().toISOString()

package/views/mixins/resource.pug

@@ -33,6 +33,62 @@ mixin resourceActions(r, returnTo)
       i.bi.bi-arrow-repeat
   +updateButton(`/resources/${r.id}/update`, r.update_to, returnTo)
 
+//- One udev device line: path (or udev index / ST-Link serial), extra
+//- detail, and whether the node was present when the Client registered.
+mixin capDevice(d, detail)
+  li
+    code= d.path || (d.serial ? `serial ${d.serial}` : `index ${d.index}`)
+    if detail
+      span.text-body-secondary.small.ms-2= detail
+    if d.present === false
+      span.badge.text-bg-danger.ms-2(
+        data-bs-toggle="tooltip"
+        data-bs-title="The device node didn't exist when the Client registered — check the adapter and udev rules"
+      ) missing
+
+//- What the Client reported it can drive at registration (HW: udev
+//- devices, relays, power; SW: emulator image and limits).
+mixin capabilitiesList(caps)
+  if !caps
+    span.text-body-secondary —
+  else if caps.sw
+    ul.list-unstyled.mb-0
+      li
+        span.text-body-secondary.small.me-2 Image
+        code= caps.sw.image || '—'
+      li
+        span.text-body-secondary.small.me-2 Source
+        = caps.sw.registry ? caps.sw.registry : 'no local registry'
+        = caps.sw.allowDockerHub ? ', then Docker Hub' : ' (Docker Hub off)'
+      li
+        span.text-body-secondary.small.me-2 Limits
+        = `${caps.sw.cpus || '—'} CPU, ${caps.sw.memory || '—'}`
+  else if caps.hw
+    - const kinds = [['stlinks', 'ST-Link'], ['uarts', 'UART'], ['usbs', 'USB']]
+    - const empty = kinds.every(([k]) => !caps.hw[k].length) && !caps.hw.relays.length && !caps.hw.power
+    if empty
+      span.text-body-secondary no devices configured
+    each pair in kinds
+      if caps.hw[pair[0]].length
+        .small.text-body-secondary.mt-1= pair[1]
+        ul.list-unstyled.mb-0.ms-2
+          each d in caps.hw[pair[0]]
+            +capDevice(d, pair[0] === 'uarts' && d.baudRate ? `${d.baudRate} baud` : null)
+    if caps.hw.relays.length
+      .small.text-body-secondary.mt-1 Relays
+      ul.list-unstyled.mb-0.ms-2
+        each rl in caps.hw.relays
+          li
+            = `channel ${rl.channel}`
+            if rl.baseUrl
+              code.ms-2= rl.baseUrl
+    if caps.hw.power
+      .small.text-body-secondary.mt-1 Power
+      .ms-2
+        = caps.hw.power.method
+        if caps.hw.power.method === 'uhubctl' && caps.hw.power.hub
+          span.text-body-secondary.small.ms-2= `hub ${caps.hw.power.hub} port ${caps.hw.power.port}`
+
 mixin resourceCard(r, groupsById, returnTo)
   - const isLoopback = (a) => /^127\./.test(a) || a === '::1' || a === 'localhost'
   - const local = ((r.host_info && r.host_info.addresses) || []).filter((a) => !isLoopback(a.address))
@@ -69,6 +125,9 @@ mixin resourceCard(r, groupsById, returnTo)
                       data-bs-toggle="tooltip"
                       data-bs-title="The address the Coordinator last saw this Client connect from"
                     ) external
+            dt.col-sm-4 Capabilities
+            dd.col-sm-8
+              +capabilitiesList(r.capabilities)
             dt.col-sm-4 Labels
             dd.col-sm-8
               if r.labels.length