@andrian.yablonskyy/thub-common 1.0.26 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Shared job-spec schema, state enums and a thin API client used by the Agent and Client",
   "main": "src/index.js",
   "files": [

package/src/client-config.js

@@ -16,10 +16,12 @@
 'use strict';
 
 const Ajv = require('ajv'),
-  addFormats = require('ajv-formats'),
-  { DOCKER_IMAGE_PATTERN } = require('./job-spec.schema');
+  addFormats = require('ajv-formats');
 
-const MAX_DEVICES = 8,
+// The config file's key for an HW Client's devices. Older files call it
+// `hw`, still read (and rewritten as `hw-devices` on the next save).
+const HW_DEVICES = 'hw-devices',
+  MAX_DEVICES = 8,
   device = (extra = {}) => ({
     type: 'object',
     additionalProperties: false,
@@ -44,74 +46,152 @@ const MAX_DEVICES = 8,
     properties: {
       stlinks: list(device({ serial: { type: 'string', pattern: '^[A-Za-z0-9]{1,64}$' } })),
       uarts: list(device({ baudRate: { type: 'integer', minimum: 50, maximum: 4000000 } })),
-      usbs: list(device()),
-      relays: list({
-        type: 'object',
-        additionalProperties: false,
-        required: ['channel'],
-        properties: {
-          channel: { type: 'integer', minimum: 0, maximum: 7 },
-          baseUrl: { type: 'string', format: 'uri', pattern: '^https?://' }
-        }
-      }),
-      power: {
-        type: ['object', 'null'],
-        additionalProperties: false,
-        properties: {
-          method: { enum: ['uhubctl', 'relay'] },
-          hub: { type: 'string', pattern: '^[A-Za-z0-9.:-]{1,32}$' },
-          port: { type: 'integer', minimum: 1, maximum: 64 },
-          baseUrl: { type: 'string', format: 'uri', pattern: '^https?://' }
-        }
-      }
-    }
-  },
-  swSchema = {
-    type: 'object',
-    additionalProperties: false,
-    properties: {
-      image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
-      registry: { type: 'string', pattern: '^(https?://)?[A-Za-z0-9.-]+(:[0-9]+)?/?$', maxLength: 255 },
-      allowDockerHub: { type: 'boolean' },
-      allowJobImages: { type: 'boolean' },
-      cpus: { type: 'number', exclusiveMinimum: 0, maximum: 256 },
-      memory: { type: 'string', pattern: '^[0-9]+[kmgKMG]?$' },
-      cmd: { type: 'array', maxItems: 32, items: { type: 'string', maxLength: 1024 } }
+      usbs: list(device())
     }
   },
+  // An SW Client has no settings of its own: its editable section is empty.
+  swSchema = { type: 'object', additionalProperties: false, properties: {} },
   ajv = new Ajv({ allErrors: true, strict: false }),
   validators = { hw: null, sw: null };
 addFormats(ajv);
 validators.hw = ajv.compile(hwSchema);
 validators.sw = ajv.compile(swSchema);
 
-// Fields of a section that never leave the Client (secrets) — kept on the
-// Client when a dashboard edit is applied, never reported or accepted.
-const PRIVATE_FIELDS = { hw: [], sw: ['registryAuth'] };
+// The hw-devices section of a config file (or its older name, `hw`).
+function hwDevicesOf(file){
+  return file?.[HW_DEVICES] !== undefined ? file[HW_DEVICES] : file?.hw;
+}
+
+// An hw-devices section without the power control Clients no longer have
+// (relays, power — relay boards and uhubctl), so a config file that still
+// has them reports, saves and imports without them. Returns
+// { section, dropped } (dropped: the names left out).
+function withoutPowerControl(hw){
+  if (!hw || typeof hw !== 'object' || Array.isArray(hw)){
+    return { section: hw, dropped: [] };
+  }
+  const { relays, power, ...section } = hw;
+  return {
+    section,
+    dropped: [...(relays !== undefined ? [`${HW_DEVICES}.relays`] : []), ...(power !== undefined ? [`${HW_DEVICES}.power`] : [])]
+  };
+}
 
-// { valid, errors } for a Client's `type` ('hw' | 'sw') config section.
+// { valid, errors } for a Client's editable section: an HW Client's
+// hw-devices; an SW Client's is always empty ({}).
 function validateClientConfig(type, section){
   const validate = validators[type];
   if (!validate){
     return { valid: false, errors: [`unknown Client type "${type}"`] };
   }
   if (!section || typeof section !== 'object' || Array.isArray(section)){
-    return { valid: false, errors: [`the ${type} section must be an object`] };
+    return { valid: false, errors: [`the ${type === 'hw' ? HW_DEVICES : type} section must be an object`] };
   }
   const valid = validate(section);
   return {
     valid,
-    errors: valid ? [] : validate.errors.map((e) => `${type}${e.instancePath.replace(/\//g, '.')} ${e.message}`)
+    errors: valid
+      ? []
+      : validate.errors.map((e) => (type === 'sw'
+        ? 'an SW Client has no settings of its own (the sw section is gone)'
+        : `${HW_DEVICES}${e.instancePath.replace(/\//g, '.')} ${e.message}`))
   };
 }
 
-// The editable view of a section: without its private fields.
-function publicClientConfig(type, section){
-  const out = { ...(section || {}) };
-  for (const key of PRIVATE_FIELDS[type] || []){
+// ── The whole config file: dashboard Export / Import (README §10) ──────────
+
+// Never taken from an imported file: how this Client reaches and joins its
+// Coordinator, and its name (the dashboard renames it instead).
+const IMPORT_IGNORED_FIELDS = ['joinKey', 'coordinatorUrl', 'name'],
+  // Top-level fields a config file may carry, checked on import (anything
+  // else is passed through as is).
+  strings = { type: 'array', maxItems: 64, items: { type: 'string', minLength: 1, maxLength: 1024 } },
+  fileSchema = {
+    type: 'object',
+    properties: {
+      type: { enum: ['hw', 'sw'] },
+      labels: strings,
+      groups: strings,
+      heartbeatIntervalSec: { type: 'integer', minimum: 1, maximum: 3600 },
+      longPollWaitSec: { type: 'integer', minimum: 1, maximum: 3600 }
+    }
+  },
+  validateFile = ajv.compile(fileSchema),
+
+  // Also never imported: what ties a config to its host and instance — the
+  // Client's identity (clientId) and every file or directory path (tokenFile,
+  // socketPath, workDir, varDir, …): taken from another Client they'd share
+  // its token, socket or state.
+  isHostBound = (key) => key === 'clientId' || /(File|Path|Dir)$/.test(key),
+
+  // Sections older Clients had and current ones ignore — dropped from
+  // Export (`artifactory` held a token, `sw` a registry password) and
+  // listed as ignored on Import.
+  LEGACY_SECTIONS = ['artifactory', 'sources', 'sw'];
+
+// A config file as it's shared (Export, and what an Import may carry): the
+// legacy sections dropped, an older `hw` section under its new name.
+function shareableClientConfigFile(file){
+  const out = JSON.parse(JSON.stringify(file || {})),
+    hw = hwDevicesOf(out);
+  for (const key of [...LEGACY_SECTIONS, 'hw']){
     delete out[key];
   }
+  if (hw !== undefined){
+    out[HW_DEVICES] = hw;
+  }
   return out;
 }
 
-module.exports = { validateClientConfig, publicClientConfig, CLIENT_CONFIG_PRIVATE_FIELDS: PRIVATE_FIELDS };
+// Checks an imported config file for a `type` Client and splits it into
+// what gets applied: { valid, errors, section (an HW Client's hw-devices, or
+// null; an SW Client's is always {}), fields (the other top-level fields),
+// ignored (names left out) }.
+function importClientConfigFile(type, file){
+  const fail = (...errors) => ({ valid: false, errors, section: null, fields: {}, ignored: [] });
+  if (!file || typeof file !== 'object' || Array.isArray(file)){
+    return fail('the file must hold a JSON object — a Client config');
+  }
+  if (file.type !== undefined && file.type !== type){
+    return fail(`it's a ${String(file.type).toUpperCase()} Client config, but this is a ${type.toUpperCase()} Client`);
+  }
+  if (!validateFile(file)){
+    return fail(...validateFile.errors.map((e) => `${e.instancePath.replace(/^\//, '').replace(/\//g, '.') || 'config'} ${e.message}`));
+  }
+  const shared = shareableClientConfigFile(file),
+    ignored = [],
+    fields = {},
+    errors = [];
+  ignored.push(...LEGACY_SECTIONS.filter((key) => file[key] !== undefined));
+  let section = type === 'sw' ? {} : null;
+  if (shared[HW_DEVICES] !== undefined){
+    if (type === 'hw'){
+      const { section: hw, dropped } = withoutPowerControl(shared[HW_DEVICES]);
+      section = hw;
+      ignored.push(...dropped);
+      errors.push(...validateClientConfig('hw', section).errors);
+    }
+    else {
+      ignored.push(HW_DEVICES); // an SW Client has no devices
+    }
+  }
+  for (const [key, value]of Object.entries(shared)){
+    if (IMPORT_IGNORED_FIELDS.includes(key) || isHostBound(key)){
+      ignored.push(key);
+    }
+    else if (key !== 'type' && key !== HW_DEVICES){
+      fields[key] = value;
+    }
+  }
+  return { valid: errors.length === 0, errors, section, fields, ignored };
+}
+
+module.exports = {
+  validateClientConfig,
+  shareableClientConfigFile,
+  importClientConfigFile,
+  withoutPowerControl,
+  hwDevicesOf,
+  HW_DEVICES_SECTION: HW_DEVICES,
+  CLIENT_CONFIG_IMPORT_IGNORED: IMPORT_IGNORED_FIELDS
+};

package/src/env-list.js

@@ -0,0 +1,40 @@
+/**
+ * @file        packages/shared/src/env-list.js
+ * @description Parses the Agent's `--env NAME=value[,NAME=value]` values into a job's env
+ *
+ * @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';
+
+// ['A=1,B=2', 'C'] -> { A: '1', B: '2', C: <C from environ> }. A comma only
+// starts a new variable when NAME= follows it, so values may contain commas
+// (`P=a,b` is P="a,b"). A bare NAME — a whole --env of its own — takes its
+// value from `environ`: keeps secrets like DOCKER_PASSWORD off the command
+// line and out of shell history. Throws on a malformed item or a bare NAME
+// that isn't set.
+function parseEnvList(values = [], environ = process.env){
+  const env = {};
+  for (const value of values){
+    for (const item of String(value).split(/,(?=[A-Za-z_][A-Za-z0-9_]*=)/)){
+      const m = /^([A-Za-z_][A-Za-z0-9_]*)(?:=(.*))?$/s.exec(item);
+      if (!m){
+        throw new Error(`--env ${item}: expected NAME=value or NAME (NAME: letters, digits and _, not starting with a digit)`);
+      }
+      const [, name, val] = m;
+      if (val === undefined && environ[name] === undefined){
+        throw new Error(`--env ${name}: not set in this shell — give it as ${name}=value or export it first`);
+      }
+      env[name] = val === undefined ? environ[name] : val;
+    }
+  }
+  return env;
+}
+
+module.exports = { parseEnvList };

package/src/index.js

@@ -21,5 +21,6 @@ module.exports = {
   ...require('./cron'),
   ...require('./client-config'),
   ...require('./split-args'),
+  ...require('./env-list'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -23,6 +23,9 @@ const DOCKER_IMAGE_PATTERN =
   // no spaces or the characters git forbids, not ending in "/", ".lock", ".".
   GIT_REF_PATTERN = '^(?![-/])(?!.*\\.\\.)(?!.*//)(?!.*(/|\\.lock|\\.)$)[A-Za-z0-9._/+@-]+$',
 
+  // An environment variable name a job may set (`--env NAME=value`).
+  ENV_NAME_PATTERN = '^[A-Za-z_][A-Za-z0-9_]*$',
+
   // Matches the job spec shape documented in README.md §4.3. A task is:
   // optionally files to download and/or a git checkout, optionally (SW only)
   // a Docker image to run as the DUT, and — always — the shell command that
@@ -76,8 +79,8 @@ const DOCKER_IMAGE_PATTERN =
         },
         default: []
       },
-      // A Docker image an SW Client runs as the DUT instead of its own
-      // sw.image, if it allows that (sw.allowJobImages) — `--docker-image`.
+      // A Docker image an SW Client runs as the job's DUT container, next to
+      // its command — `--docker-image`.
       image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
       // A repository the Client clones before running the command — at `ref`
       // (branch, tag or commit; default: the default branch), `depth` commits
@@ -98,6 +101,18 @@ const DOCKER_IMAGE_PATTERN =
           options: { type: 'string', minLength: 1, maxLength: 1024 }
         }
       },
+      // Environment variables (`--env NAME=value`) the Client sets for every
+      // command it runs for the job — git, docker login, the job's command.
+      // DOCKER_REGISTRY + DOCKER_USERNAME + DOCKER_PASSWORD: the Client logs in
+      // to that registry first (README §8.1). Values are secrets as far as
+      // the Coordinator is concerned: masked in the Agent API and dropped
+      // from its database once the job ends.
+      env: {
+        type: 'object',
+        maxProperties: 64,
+        propertyNames: { pattern: ENV_NAME_PATTERN, maxLength: 128 },
+        additionalProperties: { type: 'string', maxLength: 8192 }
+      },
       timeoutSec: { type: 'integer', minimum: 1, default: 1800 },
       priority: { type: 'integer', minimum: 0, maximum: 100, default: 50 },
       // Set by the Coordinator from the agent token's kind; any value an
@@ -113,6 +128,9 @@ const DOCKER_IMAGE_PATTERN =
       // see README §7.1 "Dry-run the pipeline".
       dryRun: { type: 'boolean', default: false }
     }
-  };
+  },
+
+  // The job env variables the Client logs in to a Docker registry with.
+  DOCKER_LOGIN_ENV = ['DOCKER_REGISTRY', 'DOCKER_USERNAME', 'DOCKER_PASSWORD'];
 
-module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN };
+module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN, ENV_NAME_PATTERN, DOCKER_LOGIN_ENV };

package/src/states.js

@@ -72,6 +72,8 @@ const RESOURCE_STATES = Object.freeze({
     INFRA: 2, // ERROR, TIMEOUT, LOST
     CANCELED: 3,
     USAGE: 4,
+    // `thub status <id> --json` on a job still queued or running.
+    ACTIVE: 5,
     DETACHED: 130
   });
 

package/src/validate-job-spec.js

@@ -15,7 +15,7 @@
 
 const Ajv = require('ajv'),
   addFormats = require('ajv-formats'),
-  { jobSpecSchema } = require('./job-spec.schema'),
+  { jobSpecSchema, DOCKER_LOGIN_ENV } = require('./job-spec.schema'),
   { splitArgs } = require('./split-args');
 
 const ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
@@ -52,7 +52,11 @@ function legacyShapeError(spec){
 // Git transports a Client may fetch sources over. Never `ext::` (runs a
 // command), `file://` or a local path: the Client also sets
 // GIT_ALLOW_PROTOCOL to the same list (downloader.js).
-const GIT_URL = /^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s]+)$/;
+const GIT_URL = /^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s]+)$/,
+
+  // Job env names the Client sets itself for a job's commands (besides
+  // THUB_*): git's safety settings, and the job's own Docker config dir.
+  RESERVED_ENV = ['GIT_TERMINAL_PROMPT', 'GIT_ALLOW_PROTOCOL', 'DOCKER_CONFIG'];
 
 // Rules across fields, spelled out here rather than as schema if/then,
 // whose errors ("must match a schema in then") say little.
@@ -64,6 +68,16 @@ function crossFieldErrors(spec){
   if (spec.git && !GIT_URL.test(spec.git.url || '')){
     errors.push('/git/url must be an https://, http://, ssh:// or git:// URL, or user@host:path');
   }
+  const envNames = Object.keys(spec.env && typeof spec.env === 'object' ? spec.env : {}),
+    reserved = envNames.filter((n) => /^THUB_/.test(n) || RESERVED_ENV.includes(n)),
+    login = DOCKER_LOGIN_ENV.filter((n) => envNames.includes(n));
+  if (reserved.length){
+    errors.push(`/env ${reserved.join(', ')}: set by the Client itself (THUB_*, ${RESERVED_ENV.join(', ')}) — use other names`);
+  }
+  if (login.length && login.length < DOCKER_LOGIN_ENV.length){
+    errors.push(`/env a Docker registry login needs all of ${DOCKER_LOGIN_ENV.join(', ')} — missing ` +
+      DOCKER_LOGIN_ENV.filter((n) => !login.includes(n)).join(', '));
+  }
   if (spec.git?.options){
     try {
       splitArgs(spec.git.options);
@@ -75,4 +89,12 @@ function crossFieldErrors(spec){
   return errors;
 }
 
-module.exports = { validateJobSpec };
+// A job's `env` with its values hidden — for anything but the Client that
+// runs the job (Agent API, logs, dry-run output).
+function maskEnv(env){
+  return env && typeof env === 'object' ? Object.fromEntries(Object.keys(env).map((k) => [k, MASKED])) : env;
+}
+
+const MASKED = '***';
+
+module.exports = { validateJobSpec, maskEnv, DOCKER_LOGIN_ENV, JOB_ENV_MASK: MASKED };