@andrian.yablonskyy/thub-common 1.0.27 → 1.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "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/job-spec.schema.js

@@ -79,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
@@ -102,11 +102,10 @@ const DOCKER_IMAGE_PATTERN =
         }
       },
       // 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.
+      // command it runs for the job — git and the job's command. No name
+      // means anything special. 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,
@@ -128,9 +127,6 @@ 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, ENV_NAME_PATTERN, DOCKER_LOGIN_ENV };
+module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN, ENV_NAME_PATTERN };

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, DOCKER_LOGIN_ENV } = require('./job-spec.schema'),
+  { jobSpecSchema } = require('./job-spec.schema'),
   { splitArgs } = require('./split-args');
 
 const ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
@@ -55,8 +55,8 @@ function legacyShapeError(spec){
 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'];
+  // THUB_*): git's safety settings.
+  RESERVED_ENV = ['GIT_TERMINAL_PROMPT', 'GIT_ALLOW_PROTOCOL'];
 
 // Rules across fields, spelled out here rather than as schema if/then,
 // whose errors ("must match a schema in then") say little.
@@ -69,15 +69,10 @@ function crossFieldErrors(spec){
     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));
+    reserved = envNames.filter((n) => /^THUB_/.test(n) || RESERVED_ENV.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);
@@ -97,4 +92,4 @@ function maskEnv(env){
 
 const MASKED = '***';
 
-module.exports = { validateJobSpec, maskEnv, DOCKER_LOGIN_ENV, JOB_ENV_MASK: MASKED };
+module.exports = { validateJobSpec, maskEnv, JOB_ENV_MASK: MASKED };