@andrian.yablonskyy/thub-common 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "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/datetime.js

@@ -50,4 +50,36 @@ function formatDateTime(value, { timeZone, fallback = '—' } = {}){
   return `${p.day}/${p.month}/${p.year} ${p.hour}:${p.minute}:${p.second}`;
 }
 
-module.exports = { formatDateTime };
+// Minutes `timeZone` is ahead of UTC at `date` (e.g. 180 for Kyiv in summer).
+function zoneOffsetMinutes(date, timeZone){
+  const p = Object.fromEntries(formatterFor(timeZone).formatToParts(date).map(({ type, value }) => [type, value])),
+    asUtc = Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour), Number(p.minute), Number(p.second));
+  return Math.round((asUtc - Math.floor(date.getTime() / 1000) * 1000) / 60000);
+}
+
+// The inverse of formatDateTime: "28/09/2026 14:05[:03]" read as wall-clock
+// time in `timeZone` (omitted = this process's local zone). Returns a Date,
+// or null if the text isn't a valid date/time in that format.
+function parseDateTime(text, { timeZone } = {}){
+  const m = /^\s*(\d{1,2})\/(\d{1,2})\/(\d{4})(?:[ T]+(\d{1,2}):(\d{2})(?::(\d{2}))?)?\s*$/.exec(String(text ?? ''));
+  if (!m){
+    return null;
+  }
+  const [day, month, year, hour = 0, minute = 0, second = 0] = [m[1], m[2], m[3], m[4], m[5], m[6]].map((v) => (v === undefined ? undefined : Number(v))),
+    wall = Date.UTC(year, month - 1, day, hour, minute, second),
+    check = new Date(wall);
+  // Reject 31/02, 25:00 and the like rather than letting Date roll them over.
+  if (check.getUTCDate() !== day || check.getUTCMonth() !== month - 1 || check.getUTCHours() !== hour || minute > 59 || second > 59){
+    return null;
+  }
+  if (!timeZone){
+    return new Date(year, month - 1, day, hour, minute, second);
+  }
+  // Wall time -> instant: subtract the zone's offset, then re-check it at
+  // the result (the offset can differ across a DST change).
+  let at = wall - zoneOffsetMinutes(new Date(wall), timeZone) * 60000;
+  at = wall - zoneOffsetMinutes(new Date(at), timeZone) * 60000;
+  return new Date(at);
+}
+
+module.exports = { formatDateTime, parseDateTime };

package/src/job-spec.schema.js

@@ -13,74 +13,107 @@
 
 'use strict';
 
-// Matches the job spec shape documented in README.md §4.3.
-// Deliberately has no field for shell commands: the Client only ever
-// runs the fixed entry point from the downloaded test package.
-const jobSpecSchema = {
-  $id: 'https://thub.example.com/schemas/job-spec.json',
-  type: 'object',
-  additionalProperties: false,
-  required: ['target', 'firmware', 'tests'],
-  properties: {
-    target: {
-      type: 'object',
-      additionalProperties: false,
-      required: ['type'],
-      properties: {
-        type: { enum: ['hw', 'sw'] },
-        labels: {
-          type: 'array',
-          items: { type: 'string', minLength: 1 },
-          default: []
-        },
-        // Constrains scheduling to resources that are members of this
-        // group (§13.1, `thub run --group <id>`) — a third targeting
-        // dimension alongside type/labels. Omitted: any matching resource
-        // in any (or no) group is eligible, same as before groups existed.
-        group: { type: 'string', minLength: 1 },
-        // Pins the job to one specific Client (`thub run --client <name|id>`):
-        // it's queued for that resource alone and waits for it even if other
-        // matching resources are idle. Accepts a resource name or id; the
-        // Coordinator resolves it to the resource id at submission time, so
-        // a later rename of the Client doesn't orphan the queued job.
-        client: { type: 'string', minLength: 1 }
-      }
-    },
-    firmware: {
-      type: 'object',
-      additionalProperties: false,
-      required: ['url'],
-      properties: {
-        url: { type: 'string', format: 'uri' },
-        sha256: { type: 'string', pattern: '^[a-f0-9]{64}$' },
-        flashAddress: { type: 'string' }
-      }
-    },
-    tests: {
-      type: 'object',
-      additionalProperties: false,
-      required: ['url'],
-      properties: {
-        url: { type: 'string', format: 'uri' },
-        suite: { type: 'string', default: 'default' },
-        args: { type: 'array', items: { type: 'string' }, default: [] }
-      }
-    },
-    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
-    // (older) Agent sends is accepted but overwritten.
-    source: { enum: ['ci', 'cli'] },
-    // Free-text job owner (`thub run --user <name>`, §7.1) — purely a
-    // label shown on the Client and dashboard to tell whose job is whose,
-    // not an identity: nothing authenticates or enforces it.
-    user: { type: 'string', minLength: 1 },
-    meta: { type: 'object' },
-    // Exercises the full pipeline (schedule, accept, state transitions,
-    // logs, artifact, result) without flashing/running anything for real —
-    // see README §7.1 "Dry-run the pipeline".
-    dryRun: { type: 'boolean', default: false }
-  }
-};
+// A Docker image reference: [host[:port]/]path[:tag][@sha256:digest], e.g.
+// `alpine`, `alpine:3.20`, `library/ubuntu:24.04`, `registry.lab:5000/emu:1`.
+const DOCKER_IMAGE_PATTERN =
+    '^[A-Za-z0-9][A-Za-z0-9.-]*(:[0-9]+)?(/[a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*)*(:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(@sha256:[a-f0-9]{64})?$',
 
-module.exports = { jobSpecSchema };
+  // A git branch or tag name: no leading "-" or "/", no "..", no spaces or
+  // the characters git forbids (~^:?*[\), not ending in "/", ".lock" or ".".
+  GIT_REF_PATTERN = '^(?![-/])(?!.*\\.\\.)(?!.*//)(?!.*(/|\\.lock|\\.)$)[A-Za-z0-9._/+@-]+$',
+
+  // Matches the job spec shape documented in README.md §4.3.
+  // Deliberately has no field for shell commands: the Client only ever
+  // runs the fixed entry point from the downloaded test package — the
+  // one exception is firmware.image, which a Client must opt in to.
+  jobSpecSchema = {
+    $id: 'https://thub.example.com/schemas/job-spec.json',
+    type: 'object',
+    additionalProperties: false,
+    required: ['target', 'tests'],
+    properties: {
+      target: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['type'],
+        properties: {
+          type: { enum: ['hw', 'sw'] },
+          labels: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+            default: []
+          },
+          // Constrains scheduling to resources that are members of this
+          // group (§13.1, `thub run --group <id>`) — a third targeting
+          // dimension alongside type/labels. Omitted: any matching resource
+          // in any (or no) group is eligible, same as before groups existed.
+          group: { type: 'string', minLength: 1 },
+          // Pins the job to one specific Client (`thub run --client <name|id>`):
+          // it's queued for that resource alone and waits for it even if other
+          // matching resources are idle. Accepts a resource name or id; the
+          // Coordinator resolves it to the resource id at submission time, so
+          // a later rename of the Client doesn't orphan the queued job.
+          client: { type: 'string', minLength: 1 }
+        }
+      },
+      // Exactly one of `url` (a firmware file the Client downloads — HW and
+      // SW) or `image` (a Docker image an SW Client runs instead of its own
+      // sw.image, if it allows that: sw.allowJobImages). The combinations are
+      // checked in validate-job-spec.js, for readable errors.
+      firmware: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          url: { type: 'string', format: 'uri' },
+          image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
+          sha256: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+          flashAddress: { type: 'string' }
+        }
+      },
+      // Where the tests come from — exactly one of `url` (an archive: tar in
+      // any compression, or zip) or `git` (a repository at a branch, tag or
+      // commit; default: its default branch) — and how they start: `command`
+      // (a shell command run in the sources, if the Client allows it:
+      // allowJobCommands), else the package's own run-tests.sh. Combinations
+      // are checked in validate-job-spec.js.
+      tests: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          url: { type: 'string', format: 'uri' },
+          git: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['url'],
+            properties: {
+              url: { type: 'string', minLength: 1, maxLength: 2048 },
+              // Ref names as git allows them — never starting with "-",
+              // so none can be taken for a git option.
+              branch: { type: 'string', maxLength: 255, pattern: GIT_REF_PATTERN },
+              tag: { type: 'string', maxLength: 255, pattern: GIT_REF_PATTERN },
+              commit: { type: 'string', pattern: '^[0-9a-fA-F]{7,40}$' }
+            }
+          },
+          command: { type: 'string', minLength: 1, maxLength: 4096 },
+          suite: { type: 'string', default: 'default' },
+          args: { type: 'array', items: { type: 'string' }, default: [] }
+        }
+      },
+      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
+      // (older) Agent sends is accepted but overwritten.
+      source: { enum: ['ci', 'cli'] },
+      // Free-text job owner (`thub run --user <name>`, §7.1) — purely a
+      // label shown on the Client and dashboard to tell whose job is whose,
+      // not an identity: nothing authenticates or enforces it.
+      user: { type: 'string', minLength: 1 },
+      meta: { type: 'object' },
+      // Exercises the full pipeline (schedule, accept, state transitions,
+      // logs, artifact, result) without flashing/running anything for real —
+      // see README §7.1 "Dry-run the pipeline".
+      dryRun: { type: 'boolean', default: false }
+    }
+  };
+
+module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN };

package/src/validate-job-spec.js

@@ -27,12 +27,61 @@ const validateFn = ajv.compile(jobSpecSchema);
  */
 function validateJobSpec(spec){
   const clone = JSON.parse(JSON.stringify(spec ?? {})),
-    valid = validateFn(clone);
-  return {
-    valid,
-    spec: clone,
-    errors: valid ? [] : (validateFn.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`)
-  };
+    schemaValid = validateFn(clone),
+    errors = schemaValid ? [] : (validateFn.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`);
+  errors.push(...firmwareErrors(clone), ...testsErrors(clone));
+  return { valid: errors.length === 0, spec: clone, errors };
+}
+
+// Git transports a Client may fetch test 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]+)$/;
+
+// tests.url (archive) vs tests.git (repo + at most one of branch/tag/commit).
+function testsErrors(spec){
+  const tests = spec.tests;
+  if (!tests || typeof tests !== 'object'){
+    return [];
+  }
+  if (tests.url && tests.git){
+    return ['/tests give either url (an archive) or git (a repository), not both'];
+  }
+  if (!tests.url && !tests.git){
+    return ['/tests needs url (an archive: tar/tar.gz/zip) or git (a repository)'];
+  }
+  if (tests.git){
+    if (!GIT_URL.test(tests.git.url || '')){
+      return ['/tests/git/url must be an https://, http://, ssh:// or git:// URL, or user@host:path'];
+    }
+    const refs = ['branch', 'tag', 'commit'].filter((k) => tests.git[k]);
+    if (refs.length > 1){
+      return [`/tests/git give at most one of branch, tag or commit (got ${refs.join(', ')})`];
+    }
+  }
+  return [];
+}
+
+// firmware.url vs firmware.image — spelled out here rather than as schema
+// oneOf/if-then, whose errors ("must match exactly one schema") say little.
+function firmwareErrors(spec){
+  const fw = spec.firmware;
+  if (!fw || typeof fw !== 'object'){
+    return ['/firmware is required'];
+  }
+  if (fw.url && fw.image){
+    return ['/firmware give either url (a firmware file) or image (a Docker image), not both'];
+  }
+  if (!fw.url && !fw.image){
+    return ['/firmware needs url (a firmware file) or image (a Docker image, SW jobs only)'];
+  }
+  if (fw.image && spec.target?.type === 'hw'){
+    return ['/firmware/image a Docker image only works for SW jobs (target.type "sw") — an HW job flashes a firmware file: use firmware.url'];
+  }
+  if (fw.image && fw.sha256){
+    return ['/firmware/sha256 applies to a firmware file (url) only — pin a Docker image by digest instead (image@sha256:...)'];
+  }
+  return [];
 }
 
 module.exports = { validateJobSpec };