@andrian.yablonskyy/thub-common 1.0.21 → 1.0.23

package/package.json

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

@@ -0,0 +1,171 @@
+/**
+ * @file        packages/shared/src/cron.js
+ * @description Minimal 5-field cron expressions (minute hour day-of-month month day-of-week) — parsing, matching
+ *              and next-occurrence — for scheduled Client host reboots
+ *
+ * @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';
+
+// Standard crontab(5) semantics: `*`, lists (1,15), ranges (1-5), steps
+// (*/15, 0-30/10), month and weekday names (jan, mon); weekday 0 and 7 are
+// both Sunday; if both day fields are restricted, a day matching either one
+// counts (like cron). No seconds, no @macros except the common ones below.
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12, names: ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'] },
+    { name: 'day of week', min: 0, max: 7, names: ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'] }
+  ],
+  MACROS = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *'
+  };
+
+function parseValue(text, field){
+  const lower = text.toLowerCase(),
+    named = field.names ? field.names.indexOf(lower) : -1;
+  if (named >= 0){
+    return named + (field.name === 'month' ? 1 : 0);
+  }
+  if (!/^\d+$/.test(text)){
+    throw new Error(`${field.name}: "${text}" isn't a number${field.names ? ' or a name' : ''}`);
+  }
+  const n = Number(text);
+  if (n < field.min || n > field.max){
+    throw new Error(`${field.name}: ${n} is out of range ${field.min}-${field.max}`);
+  }
+  return n;
+}
+
+function parseField(text, field){
+  const values = new Set();
+  for (const part of text.split(',')){
+    const [range, stepText] = part.split('/'),
+      step = stepText === undefined ? 1 : Number(stepText);
+    if (stepText !== undefined && (!/^\d+$/.test(stepText) || step < 1)){
+      throw new Error(`${field.name}: bad step "${stepText}"`);
+    }
+    let lo,
+      hi;
+    if (range === '*'){
+      [lo, hi] = [field.min, field.max];
+    }
+    else if (range.includes('-')){
+      const [a, b] = range.split('-');
+      [lo, hi] = [parseValue(a, field), parseValue(b, field)];
+      if (lo > hi){
+        throw new Error(`${field.name}: range ${range} goes backwards`);
+      }
+    }
+    else {
+      lo = parseValue(range, field);
+      hi = stepText === undefined ? lo : field.max; // "5/10" = from 5, every 10
+    }
+    for (let v = lo; v <= hi; v += step){
+      values.add(v);
+    }
+  }
+  return values;
+}
+
+// Parses "m h dom mon dow" (or @daily etc.). Throws with a readable reason.
+function parseCron(expression){
+  const text = String(expression ?? '').trim(),
+    expanded = MACROS[text.toLowerCase()] || text,
+    parts = expanded.split(/\s+/);
+  if (parts.length !== 5){
+    throw new Error(`expected 5 fields (minute hour day-of-month month day-of-week), got ${parts.length === 1 && !parts[0] ? 0 : parts.length}`);
+  }
+  const [minute, hour, dom, month, dow] = parts.map((p, i) => parseField(p, FIELDS[i]));
+  if (dow.has(7)){
+    dow.add(0);
+  }
+  return {
+    expression: text,
+    minute,
+    hour,
+    dom,
+    month,
+    dow,
+    domRestricted: parts[2] !== '*',
+    dowRestricted: parts[4] !== '*'
+  };
+}
+
+function isValidCron(expression){
+  try {
+    parseCron(expression);
+    return true;
+  }
+  catch {
+    return false;
+  }
+}
+
+// Wall-clock fields of `date` in `timeZone` (omitted: this process's zone).
+function wallClock(date, timeZone){
+  if (!timeZone){
+    return { minute: date.getMinutes(), hour: date.getHours(), dom: date.getDate(), month: date.getMonth() + 1, dow: date.getDay() };
+  }
+  const p = Object.fromEntries(new Intl.DateTimeFormat('en-US', {
+    timeZone, hourCycle: 'h23', minute: 'numeric', hour: 'numeric', day: 'numeric', month: 'numeric', weekday: 'short'
+  }).formatToParts(date).map(({ type, value }) => [type, value]));
+  return {
+    minute: Number(p.minute),
+    hour: Number(p.hour),
+    dom: Number(p.day),
+    month: Number(p.month),
+    dow: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(p.weekday)
+  };
+}
+
+function dayMatches(c, t){
+  const dayOk = c.domRestricted && c.dowRestricted ? c.dom.has(t.dom) || c.dow.has(t.dow) : c.dom.has(t.dom) && c.dow.has(t.dow);
+  return dayOk && c.month.has(t.month);
+}
+
+// Does the minute containing `date` match? `cron`: a parseCron result or text.
+function cronMatches(cron, date, { timeZone } = {}){
+  const c = typeof cron === 'string' ? parseCron(cron) : cron,
+    t = wallClock(date, timeZone);
+  return c.minute.has(t.minute) && c.hour.has(t.hour) && dayMatches(c, t);
+}
+
+// The next matching minute strictly after `from`, or null if none within
+// `withinDays` (an impossible date like 31 feb never matches). Skips a whole
+// hour whenever its day or hour can't match — hour steps rather than jumps to
+// midnight, so a 23- or 25-hour DST day can't make it skip past a match.
+function nextCronRun(cron, from = new Date(), { timeZone, withinDays = 366 } = {}){
+  const c = typeof cron === 'string' ? parseCron(cron) : cron,
+    end = from.getTime() + withinDays * 86400000;
+  let t = Math.floor(from.getTime() / 60000) * 60000 + 60000;
+  while (t < end){
+    const w = wallClock(new Date(t), timeZone);
+    if (!dayMatches(c, w) || !c.hour.has(w.hour)){
+      t += (60 - w.minute) * 60000; // to the next hour
+    }
+    else if (!c.minute.has(w.minute)){
+      t += 60000;
+    }
+    else {
+      return new Date(t);
+    }
+  }
+  return null;
+}
+
+module.exports = { parseCron, isValidCron, cronMatches, nextCronRun };

package/src/index.js

@@ -18,5 +18,6 @@ module.exports = {
   ...require('./validate-job-spec'),
   ...require('./updates'),
   ...require('./datetime'),
+  ...require('./cron'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -18,6 +18,10 @@
 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})?$',
 
+  // 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
@@ -66,12 +70,31 @@ const DOCKER_IMAGE_PATTERN =
           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,
-        required: ['url'],
         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: [] }
         }

package/src/validate-job-spec.js

@@ -29,10 +29,39 @@ function validateJobSpec(spec){
   const clone = JSON.parse(JSON.stringify(spec ?? {})),
     schemaValid = validateFn(clone),
     errors = schemaValid ? [] : (validateFn.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`);
-  errors.push(...firmwareErrors(clone));
+  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){