velocious 1.0.430 → 1.0.432

package/src/background-jobs/cron-expression.js

@@ -0,0 +1,277 @@
+// @ts-check
+
+/**
+ * Minimal POSIX-style 5-field cron parser used by the background-job
+ * scheduler. Supports `*`, single values, ranges (`N-M`), steps
+ * (`*\/N` or `N-M/N`), comma-separated lists, and the common
+ * `@hourly`/`@daily`/`@weekly`/`@monthly`/`@yearly`/`@midnight`
+ * shortcuts. Month and day-of-week names (`jan`-`dec`, `sun`-`sat`,
+ * case-insensitive) are also accepted.
+ *
+ * For day-of-month + day-of-week interaction, follows POSIX/Vixie
+ * cron semantics: when both fields are restricted (neither `*`), the
+ * job fires when EITHER matches. When one is `*` it has no effect.
+ */
+
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
+const DAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"]
+
+const SHORTCUTS = {
+  "@hourly": "0 * * * *",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@weekly": "0 0 * * 0",
+  "@monthly": "0 0 1 * *",
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *"
+}
+
+const FIELDS = [
+  {name: "minute", min: 0, max: 59},
+  {name: "hour", min: 0, max: 23},
+  {name: "dayOfMonth", min: 1, max: 31},
+  {name: "month", min: 1, max: 12, names: MONTH_NAMES},
+  // Accept 0-7 so ranges like `5-7` (Fri-Sun) work; we normalize 7
+  // down to 0 after parsing in `normalizeDayOfWeek` below.
+  {name: "dayOfWeek", min: 0, max: 7, names: DAY_NAMES}
+]
+
+/**
+ * ParsedCron type.
+ * @typedef {object} ParsedCron
+ * @property {Set<number>} minute - Allowed minute values (0-59).
+ * @property {Set<number>} hour - Allowed hour values (0-23).
+ * @property {Set<number>} dayOfMonth - Allowed day-of-month values (1-31).
+ * @property {Set<number>} month - Allowed month values (1-12).
+ * @property {Set<number>} dayOfWeek - Allowed day-of-week values (0-6, 0=Sun).
+ * @property {boolean} dayOfMonthRestricted - True when the dayOfMonth field is not `?`.
+ * @property {boolean} dayOfWeekRestricted - True when the dayOfWeek field is not `?`.
+ * @property {string} expression - Original expression for diagnostics.
+ */
+
+/**
+ * Runs the parseCronExpression helper.
+ * @param {string} expression - Cron expression or shortcut.
+ * @returns {ParsedCron}
+ */
+export function parseCronExpression(expression) {
+  if (typeof expression !== "string" || !expression.trim()) {
+    throw new Error(`Invalid cron expression: ${expression}`)
+  }
+
+  const trimmed = expression.trim().toLowerCase()
+  const expanded = SHORTCUTS[/**
+                              * Narrows the runtime value to the documented type.
+                               @type {keyof typeof SHORTCUTS} */ (trimmed)] || trimmed
+  const fields = expanded.split(/\s+/)
+
+  if (fields.length !== 5) {
+    throw new Error(`Invalid cron expression "${expression}": expected 5 fields, got ${fields.length}`)
+  }
+
+  const [minuteField, hourField, dayOfMonthField, monthField, dayOfWeekField] = fields
+  const parsed = {
+    minute: parseField(minuteField, FIELDS[0], expression),
+    hour: parseField(hourField, FIELDS[1], expression),
+    dayOfMonth: parseField(dayOfMonthField, FIELDS[2], expression),
+    month: parseField(monthField, FIELDS[3], expression),
+    // Cron treats both 0 and 7 as Sunday. We accept 7 throughout the
+    // parse pass (so `5-7` for Fri-Sun works) and then normalize any
+    // 7s down to 0 so the matcher only deals with 0-6.
+    dayOfWeek: normalizeDayOfWeek(parseField(dayOfWeekField, FIELDS[4], expression)),
+    dayOfMonthRestricted: dayOfMonthField !== "*",
+    dayOfWeekRestricted: dayOfWeekField !== "*",
+    expression
+  }
+
+  return parsed
+}
+
+/**
+ * Runs normalize day of week.
+ * @param {Set<number>} dayOfWeek
+ * @returns {Set<number>}
+ */
+function normalizeDayOfWeek(dayOfWeek) {
+  if (dayOfWeek.has(7)) {
+    dayOfWeek.delete(7)
+    dayOfWeek.add(0)
+  }
+
+  return dayOfWeek
+}
+
+/**
+ * Runs parse field.
+ * @param {string} field - Field expression.
+ * @param {{name: string, min: number, max: number, names?: string[]}} fieldSpec - Field spec.
+ * @param {string} expression - Whole cron expression for error messages.
+ * @returns {Set<number>}
+ */
+function parseField(field, fieldSpec, expression) {
+  const result = new Set()
+
+  for (const part of field.split(",")) {
+    addPartValues(part, fieldSpec, expression, result)
+  }
+
+  return result
+}
+
+/**
+ * Runs add part values.
+ * @param {string} part - Single comma-separated chunk.
+ * @param {{name: string, min: number, max: number, names?: string[]}} fieldSpec - Field spec.
+ * @param {string} expression - Original expression for errors.
+ * @param {Set<number>} result - Accumulator.
+ * @returns {void}
+ */
+function addPartValues(part, fieldSpec, expression, result) {
+  if (!part) {
+    throw new Error(`Invalid ${fieldSpec.name} field in cron expression "${expression}"`)
+  }
+
+  const [rangePart, stepPart] = part.split("/")
+  const step = stepPart === undefined ? 1 : parseStep(stepPart, fieldSpec, expression)
+  const [start, end] = parseRange(rangePart, fieldSpec, expression, stepPart !== undefined)
+
+  for (let value = start; value <= end; value += step) {
+    if (value < fieldSpec.min || value > fieldSpec.max) {
+      throw new Error(`Value ${value} out of range for ${fieldSpec.name} in cron expression "${expression}"`)
+    }
+
+    result.add(value)
+  }
+}
+
+/**
+ * Runs parse step.
+ * @param {string} value - Step value.
+ * @param {{name: string, min: number, max: number}} fieldSpec - Field spec.
+ * @param {string} expression - Original expression for errors.
+ * @returns {number}
+ */
+function parseStep(value, fieldSpec, expression) {
+  const step = Number(value)
+
+  if (!Number.isInteger(step) || step <= 0) {
+    throw new Error(`Invalid step "${value}" for ${fieldSpec.name} in cron expression "${expression}"`)
+  }
+
+  return step
+}
+
+/**
+ * Runs parse range.
+ * @param {string} rangePart - Range portion (before ? `/`).
+ * @param {{name: string, min: number, max: number, names?: string[]}} fieldSpec - Field spec.
+ * @param {string} expression - Original expression for errors.
+ * @param {boolean} hasStep - Whether the part had a `/step` suffix.
+ * @returns {[number, number]}
+ */
+function parseRange(rangePart, fieldSpec, expression, hasStep) {
+  if (rangePart === "*") {
+    return [fieldSpec.min, fieldSpec.max]
+  }
+
+  const dashIndex = rangePart.indexOf("-")
+
+  if (dashIndex === -1) {
+    const value = parseValue(rangePart, fieldSpec, expression)
+
+    // `N/step` is shorthand for `N-max/step` (Vixie cron).
+    return [value, hasStep ? fieldSpec.max : value]
+  }
+
+  const start = parseValue(rangePart.slice(0, dashIndex), fieldSpec, expression)
+  const end = parseValue(rangePart.slice(dashIndex + 1), fieldSpec, expression)
+
+  if (start > end) {
+    throw new Error(`Range start ${start} > end ${end} for ${fieldSpec.name} in cron expression "${expression}"`)
+  }
+
+  return [start, end]
+}
+
+/**
+ * Runs parse value.
+ * @param {string} rawValue - Raw value (may be a name).
+ * @param {{name: string, min: number, max: number, names?: string[]}} fieldSpec - Field spec.
+ * @param {string} expression - Original expression for errors.
+ * @returns {number}
+ */
+function parseValue(rawValue, fieldSpec, expression) {
+  if (!rawValue) {
+    throw new Error(`Invalid ${fieldSpec.name} value in cron expression "${expression}"`)
+  }
+
+  const namedIndex = fieldSpec.names?.indexOf(rawValue)
+
+  if (typeof namedIndex === "number" && namedIndex !== -1) {
+    return namedIndex + fieldSpec.min
+  }
+
+  const value = Number(rawValue)
+
+  if (!Number.isInteger(value)) {
+    throw new Error(`Invalid ${fieldSpec.name} value "${rawValue}" in cron expression "${expression}"`)
+  }
+
+  return value
+}
+
+// 5 years of minutes — covers the worst-case legitimate gap, the
+// `0 0 29 2 *` (Feb 29) leap-year-only schedule, with a one-year
+// buffer so we never report a real cron pattern as "never matches".
+const MAX_NEXT_FIRE_ITERATIONS = 5 * 366 * 24 * 60
+
+/**
+ * Returns the next Date strictly after `from` that satisfies `parsed`.
+ * Operates at minute granularity. Bails out with an error after five
+ * years of search, which only happens if the expression matches no
+ * real time (e.g., `0 0 31 2 *` — Feb 31st).
+ * @param {ParsedCron} parsed - Parsed cron expression.
+ * @param {Date} from - Reference Date — the next match is strictly after this.
+ * @returns {Date}
+ */
+export function nextCronFireDate(parsed, from) {
+  const candidate = new Date(from.getTime())
+
+  candidate.setSeconds(0, 0)
+  candidate.setMinutes(candidate.getMinutes() + 1)
+
+  for (let iterations = 0; iterations < MAX_NEXT_FIRE_ITERATIONS; iterations += 1) {
+    if (candidateMatches(candidate, parsed)) return candidate
+
+    candidate.setMinutes(candidate.getMinutes() + 1)
+  }
+
+  throw new Error(`Cron expression "${parsed.expression}" never matches`)
+}
+
+/**
+ * Runs candidate matches.
+ * @param {Date} candidate - Candidate Date (in local time).
+ * @param {ParsedCron} parsed - Parsed expression.
+ * @returns {boolean}
+ */
+function candidateMatches(candidate, parsed) {
+  if (!parsed.minute.has(candidate.getMinutes())) return false
+  if (!parsed.hour.has(candidate.getHours())) return false
+  if (!parsed.month.has(candidate.getMonth() + 1)) return false
+
+  const dayOfMonthMatch = parsed.dayOfMonth.has(candidate.getDate())
+  const dayOfWeekMatch = parsed.dayOfWeek.has(candidate.getDay())
+
+  // POSIX/Vixie cron OR semantics: when both day fields are
+  // restricted, fire when EITHER matches. When only one is
+  // restricted, only that one applies.
+  if (parsed.dayOfMonthRestricted && parsed.dayOfWeekRestricted) {
+    return dayOfMonthMatch || dayOfWeekMatch
+  }
+
+  if (parsed.dayOfMonthRestricted) return dayOfMonthMatch
+  if (parsed.dayOfWeekRestricted) return dayOfWeekMatch
+
+  return true
+}

package/src/background-jobs/forked-runner-child.js

@@ -0,0 +1,86 @@
+// @ts-check
+
+import runJobPayload from "./job-runner.js"
+
+let finishing = false
+
+/**
+ * Runs is job message.
+ * @param {?} message - IPC message.
+ * @returns {message is {type: "job", payload: import("./types.js").BackgroundJobPayload}} - Whether this is a job message.
+ */
+function isJobMessage(message) {
+  if (!message || typeof message !== "object") return false
+
+  const messageRecord = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {{type?: ?, payload?: ?}} */ (message)
+
+  return messageRecord.type === "job" && Object.hasOwn(messageRecord, "payload")
+}
+
+/**
+ * Runs finish.
+ * @param {number} exitCode - Process exit code.
+ * @returns {void}
+ */
+function finish(exitCode) {
+  finishing = true
+  process.exitCode = exitCode
+
+  if (process.connected && process.disconnect) {
+    process.disconnect()
+  }
+
+  setImmediate(() => process.exit(exitCode))
+}
+
+/**
+ * Runs report job finished.
+ * @returns {void}
+ */
+function reportJobFinished() {
+  if (process.send) process.send({type: "job-reported"})
+}
+
+/**
+ * Runs run job message.
+ * @param {?} message - IPC message.
+ * @returns {Promise<void>} - Resolves after the payload has run.
+ */
+async function runJobMessage(message) {
+  if (!isJobMessage(message)) {
+    throw new Error("Forked background job runner received invalid payload")
+  }
+
+  await runJobPayload(message.payload)
+}
+
+/**
+ * Runs handle job message.
+ * @param {?} message - IPC message.
+ * @returns {Promise<void>} - Resolves after completion is reported.
+ */
+async function handleJobMessage(message) {
+  try {
+    await runJobMessage(message)
+    reportJobFinished()
+    finish(0)
+  } catch (error) {
+    reportJobFinished()
+    console.error("Forked background job runner failed:", error)
+    finish(1)
+  }
+}
+
+for (const signal of ["SIGTERM", "SIGINT"]) {
+  process.once(signal, () => process.exit(1))
+}
+
+process.once("disconnect", () => {
+  if (!finishing) process.exit(0)
+})
+
+process.once("message", (message) => {
+  void handleJobMessage(message)
+})

package/src/background-jobs/job-record.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+import DatabaseRecord from "../database/record/index.js"
+
+export default class BackgroundJobRecord extends DatabaseRecord {
+  static tableName() {
+    return "background_jobs"
+  }
+
+  static primaryKey() {
+    return "id"
+  }
+}

package/src/background-jobs/job-registry.js

@@ -0,0 +1,92 @@
+// @ts-check
+
+import fs from "fs/promises"
+import path from "path"
+import toImportSpecifier from "../utils/to-import-specifier.js"
+import VelociousJob from "./job.js"
+
+export default class BackgroundJobRegistry {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration.
+   */
+  constructor({configuration}) {
+    this.configuration = configuration
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Map<string, typeof VelociousJob>} */
+    this.jobsByName = new Map()
+  }
+
+  /**
+   * Runs load.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async load() {
+    const directory = this.configuration.getDirectory()
+    const jobsDir = path.join(directory, "src", "jobs")
+    await this._loadJobsFromDirectory(jobsDir, {skipDuplicates: false})
+
+    const velociousPath = await this.configuration.getEnvironmentHandler().getVelociousPath()
+    const velociousJobsDir = path.join(velociousPath, "src", "jobs")
+    const normalizedJobsDir = path.resolve(jobsDir)
+    const normalizedVelociousJobsDir = path.resolve(velociousJobsDir)
+
+    if (normalizedJobsDir !== normalizedVelociousJobsDir) {
+      await this._loadJobsFromDirectory(velociousJobsDir, {skipDuplicates: true})
+    }
+  }
+
+  /**
+   * Runs get job by name.
+   * @param {string} jobName - Job name.
+   * @returns {typeof VelociousJob} - Job class.
+   */
+  getJobByName(jobName) {
+    const jobClass = this.jobsByName.get(jobName)
+
+    if (!jobClass) {
+      throw new Error(`Unknown job "${jobName}". Check src/jobs`)
+    }
+
+    return jobClass
+  }
+
+  /**
+   * Runs load jobs from directory.
+   * @param {string} jobsDir - Directory with job files.
+   * @param {object} args - Options.
+   * @param {boolean} args.skipDuplicates - Whether to skip duplicate job names.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async _loadJobsFromDirectory(jobsDir, {skipDuplicates}) {
+    try {
+      await fs.access(jobsDir)
+    } catch {
+      return
+    }
+
+    const jobFiles = fs.glob(`${jobsDir}/**/*.js`)
+
+    for await (const jobFile of jobFiles) {
+      const jobImport = await import(toImportSpecifier(jobFile))
+      const JobClass = jobImport.default
+
+      if (!JobClass) throw new Error(`Job file must export a default class: ${jobFile}`)
+      if (!(JobClass.prototype instanceof VelociousJob)) {
+        throw new Error(`Job class must extend VelociousJob: ${jobFile}`)
+      }
+
+      const jobName = JobClass.jobName()
+
+      if (this.jobsByName.has(jobName)) {
+        if (skipDuplicates) continue
+
+        throw new Error(`Duplicate job name "${jobName}" from ${jobFile}`)
+      }
+
+      this.jobsByName.set(jobName, JobClass)
+    }
+  }
+}

package/src/background-jobs/job-runner.js

@@ -0,0 +1,107 @@
+// @ts-check
+
+import configurationResolver from "../configuration-resolver.js"
+import BackgroundJobRegistry from "./job-registry.js"
+import BackgroundJobsStatusReporter from "./status-reporter.js"
+
+const BEACON_READY_TIMEOUT_MS = 5000
+
+/**
+ * Runs report beacon ready error.
+ * @param {import("../configuration.js").default} configuration - Configuration.
+ * @param {?} error - Beacon readiness error.
+ * @returns {void}
+ */
+function reportBeaconReadyError(configuration, error) {
+  const errorEvents = configuration.getErrorEvents()
+  const normalizedError = error instanceof Error ? error : new Error(String(error))
+  const payload = {
+    context: {peerType: "background-jobs-runner", stage: "beacon-ready"},
+    error: normalizedError
+  }
+  const hasListener = errorEvents.listenerCount("framework-error") > 0
+    || errorEvents.listenerCount("all-error") > 0
+
+  errorEvents.emit("framework-error", payload)
+  errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+
+  if (!hasListener) {
+    console.error(`[velocious framework-error stage=beacon-ready] ${normalizedError.message}`)
+  }
+}
+
+/**
+ * Runs connect beacon.
+ * @param {import("../configuration.js").default} configuration - Configuration.
+ * @returns {Promise<void>}
+ */
+async function connectBeacon(configuration) {
+  const beaconClient = await configuration.connectBeacon({peerType: "background-jobs-runner"})
+
+  if (!beaconClient) return
+
+  try {
+    await beaconClient.waitForReady({timeoutMs: BEACON_READY_TIMEOUT_MS})
+  } catch (error) {
+    reportBeaconReadyError(configuration, error)
+  }
+}
+
+/**
+ * Runs run job payload.
+ * @param {import("./types.js").BackgroundJobPayload} payload - Payload.
+ * @returns {Promise<void>} - Resolves when complete.
+ */
+export default async function runJobPayload(payload) {
+  const configuration = await configurationResolver()
+  configuration.setCurrent()
+  await configuration.initialize({type: "background-jobs-runner"})
+  await connectBeacon(configuration)
+  const reporter = new BackgroundJobsStatusReporter({configuration})
+
+  const registry = new BackgroundJobRegistry({configuration})
+  await registry.load()
+  const JobClass = registry.getJobByName(payload.jobName)
+  const jobInstance = new JobClass()
+  /**
+   * Perform.
+    @type {(...args: Array<?>) => Promise<void>} */
+  const perform = jobInstance.perform
+
+  try {
+    try {
+      await configuration.withConnections({name: `Background job runner: ${payload.jobName}`}, async () => {
+        await perform.apply(jobInstance, payload.args || [])
+      })
+
+      if (payload.id) {
+        await reporter.reportWithRetry({
+          jobId: payload.id,
+          status: "completed",
+          workerId: payload.workerId,
+          handedOffAtMs: payload.handedOffAtMs,
+          maxDurationMs: 30000
+        })
+      }
+    } catch (error) {
+      if (payload.id) {
+        await reporter.reportWithRetry({
+          jobId: payload.id,
+          status: "failed",
+          error,
+          workerId: payload.workerId,
+          handedOffAtMs: payload.handedOffAtMs,
+          maxDurationMs: 30000
+        })
+      }
+
+      throw error
+    }
+  } finally {
+    try {
+      await configuration.disconnectBeacon()
+    } finally {
+      await configuration.closeDatabaseConnections()
+    }
+  }
+}

package/src/background-jobs/job.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+import BackgroundJobsClient from "./client.js"
+
+export default class VelociousJob {
+  /**
+   * Runs job name.
+   * @returns {string} - Job name.
+   */
+  static jobName() {
+    return this.name
+  }
+
+  /**
+   * Runs perform later.
+   * @param {...?} args - Job args.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLater(...args) {
+    const {jobArgs, jobOptions} = this._splitArgsAndOptions(args)
+    const client = new BackgroundJobsClient()
+
+    return await client.enqueue({
+      jobName: this.jobName(),
+      args: jobArgs,
+      options: jobOptions
+    })
+  }
+
+  /**
+   * Runs perform later with options.
+   * @param {object} args - Options.
+   * @param {Array<?>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLaterWithOptions({args, options}) {
+    const client = new BackgroundJobsClient()
+
+    return await client.enqueue({
+      jobName: this.jobName(),
+      args,
+      options
+    })
+  }
+
+  /**
+   * Runs split args and options.
+   * @param {Array<?>} args - Job args.
+   * @returns {{jobArgs: Array<?>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
+   */
+  static _splitArgsAndOptions(args) {
+    if (args.length === 0) {
+      return {jobArgs: [], jobOptions: {}}
+    }
+
+    const lastArg = args[args.length - 1]
+    const isOptionsArg = lastArg && typeof lastArg === "object" && !Array.isArray(lastArg) && "jobOptions" in lastArg
+
+    if (isOptionsArg) {
+      const {jobOptions} = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {{jobOptions: import("./types.js").BackgroundJobOptions}} */ (lastArg)
+      return {jobArgs: args.slice(0, -1), jobOptions: jobOptions || {}}
+    }
+
+    return {jobArgs: args, jobOptions: {}}
+  }
+
+  /**
+   * Override in subclasses.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async perform() {
+    throw new Error("perform not implemented")
+  }
+}