velocious 1.0.430 → 1.0.431

package/src/background-jobs/normalize-error.js

@@ -0,0 +1,26 @@
+// @ts-check
+
+/**
+ * Runs normalize background job error.
+ * @param {?} error - Error input.
+ * @returns {string} - Normalized error string.
+ */
+export default function normalizeBackgroundJobError(error) {
+  if (error instanceof Error) return error.stack || error.message
+  if (typeof error === "string") return error
+
+  return stringifyUnknownError(error)
+}
+
+/**
+ * Runs stringify unknown error.
+ * @param {?} error - Error input.
+ * @returns {string} - Stringified error.
+ */
+function stringifyUnknownError(error) {
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}

package/src/background-jobs/scheduler.js

@@ -0,0 +1,274 @@
+// @ts-check
+
+import Logger from "../logger.js"
+import {nextCronFireDate, parseCronExpression} from "./cron-expression.js"
+
+const DURATION_MULTIPLIERS = {
+  d: 24 * 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  days: 24 * 60 * 60 * 1000,
+  h: 60 * 60 * 1000,
+  hour: 60 * 60 * 1000,
+  hours: 60 * 60 * 1000,
+  m: 60 * 1000,
+  minute: 60 * 1000,
+  minutes: 60 * 1000,
+  ms: 1,
+  s: 1000,
+  second: 1000,
+  seconds: 1000,
+  w: 7 * 24 * 60 * 60 * 1000,
+  week: 7 * 24 * 60 * 60 * 1000,
+  weeks: 7 * 24 * 60 * 60 * 1000
+}
+/**
+ * DurationUnit type.
+  @typedef {keyof typeof DURATION_MULTIPLIERS} DurationUnit */
+
+/**
+ * Runs the parseScheduledDuration helper.
+ * @param {number | string} value - Duration value.
+ * @param {string} fieldName - Field name for errors.
+ * @returns {number} - Duration in milliseconds.
+ */
+export function parseScheduledDuration(value, fieldName) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 1) {
+      throw new Error(`Scheduled background job ${fieldName} must be a positive number of milliseconds.`)
+    }
+
+    return value
+  }
+
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Scheduled background job ${fieldName} must be a non-empty string or number.`)
+  }
+
+  const normalizedValue = value.trim().toLowerCase()
+  const match = normalizedValue.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w|second|seconds|minute|minutes|hour|hours|day|days|week|weeks)$/)
+
+  if (!match) {
+    throw new Error(`Invalid scheduled background job ${fieldName}: ${value}`)
+  }
+
+  const numericValue = Number(match[1])
+  const multiplier = DURATION_MULTIPLIERS[/**
+                                           * Narrows the runtime value to the documented type.
+                                            @type {DurationUnit} */ (match[2])]
+
+  if (!multiplier) {
+    throw new Error(`Invalid scheduled background job ${fieldName}: ${value}`)
+  }
+
+  return Math.round(numericValue * multiplier)
+}
+
+/** Runs configured recurring background job schedules. */
+export default class BackgroundJobsScheduler {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration.
+   * @param {function({args: Array<?>, jobClass: typeof import("./job.js").default, jobKey: string, options: import("./types.js").BackgroundJobOptions}) : Promise<void>} args.enqueueJob - Enqueue callback.
+   */
+  constructor({configuration, enqueueJob}) {
+    this.configuration = configuration
+    this.enqueueJob = enqueueJob
+    this.logger = new Logger(this)
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Array<ReturnType<typeof setInterval>>} */
+    this.intervalIds = []
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Array<ReturnType<typeof setTimeout>>} */
+    this.timeoutIds = []
+    /**
+     * Narrows the runtime value to the documented type.
+     * @type {boolean} - True between stop() and the next start(); cron self-rescheduler checks this so a stop() during an in-flight enqueue doesn't immediately re-arm.
+     */
+    this.stopped = false
+  }
+
+  /**
+   * Runs start.
+    @returns {Promise<void>} */
+  async start() {
+    this.stopped = false
+
+    const scheduledBackgroundJobsConfig = await this.configuration.getScheduledBackgroundJobsConfig()
+
+    if (!scheduledBackgroundJobsConfig?.jobs) {
+      return
+    }
+
+    for (const jobKey of Object.keys(scheduledBackgroundJobsConfig.jobs)) {
+      const jobConfiguration = scheduledBackgroundJobsConfig.jobs[jobKey]
+
+      if (!jobConfiguration || jobConfiguration.enabled === false) {
+        continue
+      }
+
+      this.scheduleJob({jobConfiguration, jobKey})
+    }
+  }
+
+  /**
+   * Runs stop.
+    @returns {void} */
+  stop() {
+    this.stopped = true
+
+    for (const intervalId of this.intervalIds) {
+      clearInterval(intervalId)
+    }
+
+    for (const timeoutId of this.timeoutIds) {
+      clearTimeout(timeoutId)
+    }
+
+    this.intervalIds = []
+    this.timeoutIds = []
+  }
+
+  /**
+   * Runs schedule job.
+   * @param {object} args - Options.
+   * @param {import("../configuration-types.js").ScheduledBackgroundJobConfiguration} args.jobConfiguration - Job configuration.
+   * @param {string} args.jobKey - Job key.
+   * @returns {void}
+   */
+  scheduleJob({jobConfiguration, jobKey}) {
+    if (!jobConfiguration.class || typeof jobConfiguration.class.performLaterWithOptions !== "function") {
+      throw new Error(`Scheduled background job ${jobKey} must define a job class.`)
+    }
+
+    if (jobConfiguration.cron !== undefined && jobConfiguration.every !== undefined) {
+      throw new Error(`Scheduled background job ${jobKey} must define either "every" or "cron", not both.`)
+    }
+
+    if (jobConfiguration.cron !== undefined) {
+      this.scheduleCronJob({jobConfiguration, jobKey})
+
+      return
+    }
+
+    if (jobConfiguration.every === undefined) {
+      throw new Error(`Scheduled background job ${jobKey} must define either "every" or "cron".`)
+    }
+
+    this.scheduleEveryJob({jobConfiguration, jobKey})
+  }
+
+  /**
+   * Runs schedule every job.
+   * @param {object} args - Options.
+   * @param {import("../configuration-types.js").ScheduledBackgroundJobConfiguration} args.jobConfiguration - Job configuration.
+   * @param {string} args.jobKey - Job key.
+   * @returns {void}
+   */
+  scheduleEveryJob({jobConfiguration, jobKey}) {
+    const everyConfig = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {NonNullable<typeof jobConfiguration.every>} */ (jobConfiguration.every)
+    const {everyValue, firstInValue} = this.normalizeEvery(everyConfig)
+    const intervalMs = parseScheduledDuration(everyValue, `${jobKey}.every`)
+    const firstInMs = firstInValue !== undefined ? parseScheduledDuration(firstInValue, `${jobKey}.first_in`) : intervalMs
+
+    if (intervalMs < 1) {
+      throw new Error(`Scheduled background job ${jobKey}.every must be at least 1 millisecond.`)
+    }
+
+    const timeoutId = setTimeout(() => {
+      void this.enqueueScheduledJob({jobConfiguration, jobKey})
+
+      const intervalId = setInterval(() => {
+        void this.enqueueScheduledJob({jobConfiguration, jobKey})
+      }, intervalMs)
+
+      this.intervalIds.push(intervalId)
+    }, firstInMs)
+
+    this.timeoutIds.push(timeoutId)
+  }
+
+  /**
+   * Crontab schedules don't have a constant interval (`0 9 * * 1-5`
+   * fires once per weekday at 9 AM, with gaps of varying length), so
+   * we self-reschedule with `setTimeout` after every fire instead of
+   * using `setInterval`.
+   * @param {object} args - Options.
+   * @param {import("../configuration-types.js").ScheduledBackgroundJobConfiguration} args.jobConfiguration - Job configuration.
+   * @param {string} args.jobKey - Job key.
+   * @returns {void}
+   */
+  scheduleCronJob({jobConfiguration, jobKey}) {
+    const cronExpression = jobConfiguration.cron
+
+    if (typeof cronExpression !== "string") {
+      throw new Error(`Scheduled background job ${jobKey}.cron must be a string.`)
+    }
+
+    const parsed = parseCronExpression(cronExpression)
+    const scheduleNext = () => {
+      if (this.stopped) return
+
+      const nextDate = nextCronFireDate(parsed, new Date())
+      const delayMs = Math.max(1, nextDate.getTime() - Date.now())
+      const timeoutId = setTimeout(async () => {
+        if (this.stopped) return
+
+        await this.enqueueScheduledJob({jobConfiguration, jobKey})
+
+        // The await above can yield to a stop() call. Re-check before
+        // re-arming so we don't keep firing after shutdown.
+        if (this.stopped) return
+
+        scheduleNext()
+      }, delayMs)
+
+      this.timeoutIds.push(timeoutId)
+    }
+
+    scheduleNext()
+  }
+
+  /**
+   * Runs enqueue scheduled job.
+   * @param {object} args - Options.
+   * @param {import("../configuration-types.js").ScheduledBackgroundJobConfiguration} args.jobConfiguration - Job configuration.
+   * @param {string} args.jobKey - Job key.
+   * @returns {Promise<void>}
+   */
+  async enqueueScheduledJob({jobConfiguration, jobKey}) {
+    try {
+      await this.enqueueJob({
+        args: Array.isArray(jobConfiguration.args) ? jobConfiguration.args : [],
+        jobClass: jobConfiguration.class,
+        jobKey,
+        options: jobConfiguration.options || {}
+      })
+    } catch (error) {
+      await this.logger.error(() => ["Failed to enqueue scheduled background job", {jobKey, jobName: jobConfiguration.class.jobName()}, error])
+    }
+  }
+
+  /**
+   * Runs normalize every.
+   * @param {NonNullable<import("../configuration-types.js").ScheduledBackgroundJobConfiguration["every"]>} every - Every config (caller must guarantee not undefined).
+   * @returns {{everyValue: number | string, firstInValue?: number | string}} - Normalized interval and first-run delay values.
+   */
+  normalizeEvery(every) {
+    if (Array.isArray(every)) {
+      const [everyValue, everyOptions] = every
+
+      if (!everyOptions || typeof everyOptions !== "object" || Array.isArray(everyOptions)) {
+        return {everyValue}
+      }
+
+      return {everyValue, firstInValue: everyOptions.firstIn ?? everyOptions.first_in}
+    }
+
+    return {everyValue: every}
+  }
+}

package/src/background-jobs/socket-request.js

@@ -0,0 +1,68 @@
+// @ts-check
+
+import net from "net"
+import JsonSocket from "./json-socket.js"
+
+export default class BackgroundJobsSocketRequest {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {string} args.host - Host.
+   * @param {number} args.port - Port.
+   * @param {"client" | "reporter"} args.role - Socket role.
+   */
+  constructor({host, port, role}) {
+    this.host = host
+    this.port = port
+    this.role = role
+  }
+
+  /**
+   * Runs run.
+   * @template T
+   * @param {object} args - Options.
+   * @param {(jsonSocket: JsonSocket) => void} args.onConnect - Called after the socket connects.
+   * @param {(args: {message: import("./types.js").BackgroundJobSocketMessage, resolve: (value: T) => void, reject: (error: Error) => void}) => void} args.onMessage - Message handler.
+   * @returns {Promise<T>} - Resolved request value.
+   */
+  async run({onConnect, onMessage}) {
+    const socket = net.createConnection({host: this.host, port: this.port})
+    const jsonSocket = new JsonSocket(socket)
+
+    return await new Promise((resolve, reject) => {
+      let finished = false
+      /**
+       * Finish.
+       * @param {() => void} callback - Finish callback.
+       */
+      const finish = (callback) => {
+        if (finished) return
+        finished = true
+        jsonSocket.removeAllListeners()
+        jsonSocket.close()
+        callback()
+      }
+
+      jsonSocket.on("error", (error) => {
+        finish(() => reject(error))
+      })
+
+      /**
+       * Handles the socket response message.
+       * @param {import("./types.js").BackgroundJobSocketMessage} message - Socket message.
+       */
+      jsonSocket.on("message", (message) => {
+        onMessage({
+          message,
+          resolve: (value) => finish(() => resolve(value)),
+          reject: (error) => finish(() => reject(error))
+        })
+      })
+
+      socket.on("connect", () => {
+        jsonSocket.send({type: "hello", role: this.role})
+        onConnect(jsonSocket)
+      })
+    })
+  }
+}

package/src/background-jobs/status-reporter.js

@@ -0,0 +1,101 @@
+// @ts-check
+
+import timeout from "awaitery/build/timeout.js"
+import wait from "awaitery/build/wait.js"
+import Logger from "../logger.js"
+import normalizeBackgroundJobError from "./normalize-error.js"
+import BackgroundJobsSocketRequest from "./socket-request.js"
+
+export default class BackgroundJobsStatusReporter {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration.
+   * @param {string} [args.host] - Host.
+   * @param {number} [args.port] - Port.
+   */
+  constructor({configuration, host, port}) {
+    this.configuration = configuration
+    this.host = host
+    this.port = port
+    this.logger = new Logger(this)
+  }
+
+  /**
+   * Runs report.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {"completed" | "failed"} args.status - Status.
+   * @param {?} [args.error] - Error.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {string} [args.workerId] - Worker id.
+   * @returns {Promise<void>} - Resolves when reported.
+   */
+  async report({jobId, status, error, handedOffAtMs, workerId}) {
+    const config = this.configuration.getBackgroundJobsConfig()
+    const host = this.host || config.host
+    const port = typeof this.port === "number" ? this.port : config.port
+
+    await timeout({timeout: 5000}, async () => {
+      const request = new BackgroundJobsSocketRequest({host, port, role: "reporter"})
+
+      await request.run({
+        onConnect: (jsonSocket) => {
+          jsonSocket.send({
+            type: status === "completed" ? "job-complete" : "job-failed",
+            jobId,
+            workerId,
+            handedOffAtMs,
+            error: error ? normalizeBackgroundJobError(error) : undefined
+          })
+        },
+        onMessage: ({message, resolve, reject}) => {
+          if (message?.type === "job-updated" && message.jobId === jobId) {
+            resolve(undefined)
+            return
+          }
+
+          if (message?.type === "job-update-error" && message.jobId === jobId) {
+            reject(new Error(message.error || "Job update failed"))
+          }
+        }
+      })
+    })
+  }
+
+  /**
+   * Runs report with retry.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {"completed" | "failed"} args.status - Status.
+   * @param {?} [args.error] - Error.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {string} [args.workerId] - Worker id.
+   * @param {number} [args.maxDurationMs] - Max duration for retries.
+   * @returns {Promise<void>} - Resolves when reported.
+   */
+  async reportWithRetry({jobId, status, error, handedOffAtMs, workerId, maxDurationMs}) {
+    let attempt = 0
+    const startTime = Date.now()
+
+    while (true) {
+      try {
+        await this.report({jobId, status, error, handedOffAtMs, workerId})
+        return
+      } catch (error) {
+        attempt += 1
+        const delaySeconds = Math.min(30, 0.5 * attempt)
+
+        this.logger.debug(() => ["Background job status report failed, retrying", error])
+
+        if (maxDurationMs && Date.now() - startTime >= maxDurationMs) {
+          this.logger.warn(() => ["Background job status report timed out, giving up", error])
+          return
+        }
+
+        await wait(delaySeconds)
+      }
+    }
+  }
+
+}