velocious 1.0.430 → 1.0.431

package/src/background-jobs/types.js

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * @typedef {"inline" | "forked" | "spawned"} BackgroundJobExecutionMode
+ */
+/**
+ * @typedef {object} BackgroundJobOptions
+ * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"forked"`.
+ * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`.
+ * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
+ */
+/**
+ * @typedef {object} BackgroundJobPayload
+ * @property {string} [id] - Job id.
+ * @property {string} jobName - Job class name.
+ * @property {Array<?>} [args] - Serialized job arguments.
+ * @property {string} [workerId] - Worker id handling the job.
+ * @property {number} [handedOffAtMs] - Time handed to a worker in ms.
+ * @property {BackgroundJobOptions} [options] - Runtime options.
+ */
+/**
+ * @typedef {object} BackgroundJobRow
+ * @property {string} id - Job id.
+ * @property {string} jobName - Job class name.
+ * @property {Array<?>} args - Serialized job arguments.
+ * @property {BackgroundJobExecutionMode} executionMode - How the job should run.
+ * @property {boolean} forked - Compatibility flag; true for non-inline execution.
+ * @property {string} status - Current job status.
+ * @property {number | null} attempts - Failure attempts count.
+ * @property {number | null} maxRetries - Max retry attempts.
+ * @property {number | null} scheduledAtMs - Next scheduled time in ms.
+ * @property {number | null} createdAtMs - Creation time in ms.
+ * @property {number | null} handedOffAtMs - Time handed to worker in ms.
+ * @property {number | null} completedAtMs - Completion time in ms.
+ * @property {number | null} failedAtMs - Failure time in ms.
+ * @property {number | null} orphanedAtMs - Orphaned time in ms.
+ * @property {string | null} workerId - Worker id handling the job.
+ * @property {string | null} lastError - Last failure message.
+ */
+/**
+ * @typedef {object} BackgroundJobFailureEvent
+ * @property {BackgroundJobRow} job - Updated job row after failure handling.
+ * @property {?} error - Failure error.
+ * @property {number | null} attempts - Updated failure attempts count.
+ * @property {boolean} terminal - Whether this failure ended the job.
+ * @property {boolean} willRetry - Whether the job was returned to the queue.
+ * @property {number | undefined} handedOffAtMs - Handoff timestamp from the worker report.
+ * @property {string | undefined} workerId - Worker id from the worker report.
+ */
+/**
+ * @typedef {"worker" | "client" | "reporter"} BackgroundJobSocketRole
+ */
+/**
+ * @typedef {{type: "hello", role: BackgroundJobSocketRole, workerId?: string}} BackgroundJobHelloMessage
+ * @typedef {{type: "ready", acceptsForked?: boolean, acceptsInline?: boolean, acceptsSpawned?: boolean}} BackgroundJobReadyMessage
+ * @typedef {{type: "draining"}} BackgroundJobDrainingMessage
+ * @typedef {{type: "enqueue", jobName: string, args?: Array<?>, options?: BackgroundJobOptions}} BackgroundJobEnqueueMessage
+ * @typedef {{type: "enqueued", jobId: string}} BackgroundJobEnqueuedMessage
+ * @typedef {{type: "enqueue-error", error?: string}} BackgroundJobEnqueueErrorMessage
+ * @typedef {{type: "job", payload: BackgroundJobPayload}} BackgroundJobJobMessage
+ * @typedef {{type: "job-complete", jobId: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobCompleteMessage
+ * @typedef {{type: "job-failed", jobId: string, error?: ?, workerId?: string, handedOffAtMs?: number}} BackgroundJobFailedMessage
+ * @typedef {{type: "job-updated", jobId: string}} BackgroundJobUpdatedMessage
+ * @typedef {{type: "job-update-error", jobId: string, error?: string}} BackgroundJobUpdateErrorMessage
+ */
+/**
+ * @typedef {BackgroundJobHelloMessage | BackgroundJobReadyMessage | BackgroundJobDrainingMessage | BackgroundJobEnqueueMessage | BackgroundJobEnqueuedMessage | BackgroundJobEnqueueErrorMessage | BackgroundJobJobMessage | BackgroundJobCompleteMessage | BackgroundJobFailedMessage | BackgroundJobUpdatedMessage | BackgroundJobUpdateErrorMessage} BackgroundJobSocketMessage
+ */
+
+export const nothing = {}

package/src/background-jobs/web/authorization.js

@@ -0,0 +1,89 @@
+// @ts-check
+
+import crypto from "node:crypto"
+
+/**
+ * Constant-time comparison so token checks don't leak length/contents through
+ * timing. Returns false for differing lengths before the timing-safe compare.
+ * @param {string} a - First value.
+ * @param {string} b - Second value.
+ * @returns {boolean} - Whether the values are equal.
+ */
+function safeEqual(a, b) {
+  const bufferA = Buffer.from(String(a))
+  const bufferB = Buffer.from(String(b))
+
+  if (bufferA.length !== bufferB.length) return false
+
+  return crypto.timingSafeEqual(bufferA, bufferB)
+}
+
+/**
+ * Runs bearer token.
+ * @param {import("../../http-server/client/request.js").default} request - Request object.
+ * @returns {string | null} - Bearer token from the Authorization header, if any.
+ */
+function bearerToken(request) {
+  const header = request.header("authorization")
+
+  if (typeof header !== "string") return null
+
+  const match = header.match(/^Bearer\s+(.+)$/i)
+
+  return match ? match[1].trim() : null
+}
+
+/**
+ * Runs is loopback.
+ * @param {string | undefined} remoteAddress - Remote address.
+ * @returns {boolean} - Whether the address is loopback.
+ */
+function isLoopback(remoteAddress) {
+  if (!remoteAddress) return false
+
+  return (
+    remoteAddress === "127.0.0.1" ||
+    remoteAddress === "::1" ||
+    remoteAddress === "::ffff:127.0.0.1" ||
+    remoteAddress.startsWith("127.")
+  )
+}
+
+/**
+ * Decides whether a jobs-dashboard request is authorized. Order of precedence:
+ * a matching bearer token, then the host-supplied `authorize` callback. When
+ * neither tokens nor an authorize callback are configured, access falls back to
+ * loopback-only so a freshly mounted dashboard is reachable on the same host
+ * during development without being exposed to the network.
+ * @param {object} args - Options.
+ * @param {import("./registry.js").JobsMountOptions} args.options - Mount options.
+ * @param {import("../../http-server/client/request.js").default} args.request - Request object.
+ * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+ * @param {import("../../authorization/ability.js").default | undefined} args.ability - Current ability.
+ * @returns {Promise<boolean>} - Whether the request is authorized.
+ */
+export async function authorizeJobsRequest({ability, configuration, options, request}) {
+  const accessTokens = Array.isArray(options.accessTokens)
+    ? options.accessTokens.filter((token) => typeof token === "string" && token.length > 0)
+    : []
+  const authorize = typeof options.authorize === "function" ? options.authorize : null
+  const token = bearerToken(request)
+
+  if (accessTokens.length > 0 && token) {
+    for (const accessToken of accessTokens) {
+      if (safeEqual(token, accessToken)) return true
+    }
+  }
+
+  if (authorize) {
+    const result = await authorize({ability, configuration, request, token})
+
+    if (result === true) return true
+  }
+
+  if (accessTokens.length === 0 && !authorize) {
+    return isLoopback(request.remoteAddress())
+  }
+
+  return false
+}

package/src/background-jobs/web/controller.js

@@ -0,0 +1,280 @@
+// @ts-check
+
+import Controller from "../../controller.js"
+import BackgroundJobsStore from "../store.js"
+import {authorizeJobsRequest} from "./authorization.js"
+import {getJobsMount} from "./registry.js"
+
+const DASHBOARD_STATUSES = ["queued", "handed_off", "completed", "failed", "orphaned"]
+const SORTABLE_KEYS = ["attempts", "completedAtMs", "createdAtMs", "failedAtMs", "handedOffAtMs", "scheduledAtMs"]
+const DEFAULT_PER_PAGE = 25
+const MAX_PER_PAGE = 100
+
+/**
+ * Read-only HTTP API backing the background-jobs dashboard. Mounted by
+ * {@link import("./index.js").default} as a route-resolver hook so it can ship
+ * inside the velocious package. Every action is gated by {@link authorizeJobsRequest}.
+ */
+export default class VelociousBackgroundJobsWebController extends Controller {
+  /**
+   * Runs mount options.
+   * @returns {import("./registry.js").JobsMountOptions} - Options for the mount that matched this request.
+   */
+  _mountOptions() {
+    const at = this.params().velociousJobsMountAt
+
+    return getJobsMount(this.getConfiguration(), at) || {}
+  }
+
+  /**
+   * Runs store.
+   * @returns {BackgroundJobsStore} - Jobs store scoped to the mount's database.
+   */
+  _store() {
+    if (!this._jobsStore) {
+      this._jobsStore = new BackgroundJobsStore({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: this._mountOptions().databaseIdentifier
+      })
+    }
+
+    return this._jobsStore
+  }
+
+  /**
+   * Adds CORS headers when the request origin is allowed, so the standalone
+   * browser dashboard can read the API cross-origin.
+   * @param {import("./registry.js").JobsMountOptions} options - Mount options.
+   * @returns {void} - No return value.
+   */
+  _applyCorsHeaders(options) {
+    const allowedOrigins = Array.isArray(options.allowedOrigins) ? options.allowedOrigins : []
+
+    if (allowedOrigins.length === 0) return
+
+    const origin = this.request().origin()
+    const allowAll = allowedOrigins.includes("*")
+
+    if (!origin) return
+    if (!allowAll && !allowedOrigins.includes(origin)) return
+
+    const response = this.response()
+
+    response.setHeader("Access-Control-Allow-Origin", allowAll ? "*" : origin)
+    response.setHeader("Vary", "Origin")
+    response.setHeader("Access-Control-Allow-Headers", "authorization, content-type")
+    response.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS")
+  }
+
+  /**
+   * Applies CORS headers, authorizes the request, and runs the action body only
+   * when authorized. Renders a 401 otherwise. The base controller has no
+   * before-action halting, so authorization is enforced here per action.
+   * @param {() => Promise<void>} actionFn - Action body.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async _respond(actionFn) {
+    const options = this._mountOptions()
+
+    this._applyCorsHeaders(options)
+
+    const authorized = await authorizeJobsRequest({
+      ability: this.currentAbility(),
+      configuration: this.getConfiguration(),
+      options,
+      request: this.request()
+    })
+
+    if (!authorized) {
+      await this.render({json: {error: "unauthorized"}, status: 401})
+      return
+    }
+
+    await actionFn()
+  }
+
+  /**
+   * Runs health.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async health() {
+    await this._respond(async () => {
+      await this.render({json: {ok: true, service: "velocious-background-jobs"}})
+    })
+  }
+
+  /**
+   * Runs stats.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async stats() {
+    await this._respond(async () => {
+      const counts = await this._store().countsByStatus()
+      /**
+       * By status.
+        @type {Record<string, number>} */
+      const byStatus = {}
+      let total = 0
+
+      for (const status of DASHBOARD_STATUSES) {
+        byStatus[status] = counts[status] || 0
+      }
+
+      for (const value of Object.values(counts)) {
+        total += value
+      }
+
+      await this.render({json: {counts: byStatus, generatedAtMs: Date.now(), total}})
+    })
+  }
+
+  /**
+   * Runs index.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async index() {
+    await this._respond(async () => {
+      const params = this.params()
+      const status = this._sanitizeStatus(params.status)
+      const jobName = typeof params.jobName === "string" && params.jobName.length > 0 ? params.jobName : undefined
+      const page = this._positiveInt(params.page, 1)
+      const perPage = Math.min(this._positiveInt(params.perPage, DEFAULT_PER_PAGE), MAX_PER_PAGE)
+      const {sortColumn, sortDirection} = this._sanitizeSort(params.sort)
+      const store = this._store()
+      const jobs = await store.listJobs({jobName, limit: perPage, offset: (page - 1) * perPage, sortColumn, sortDirection, status})
+      const total = await store.countJobs({jobName, status})
+
+      await this.render({json: {
+        jobs: jobs.map((job) => this._serializeJob(job)),
+        pagination: {page, perPage, total, totalPages: perPage > 0 ? Math.ceil(total / perPage) : 0}
+      }})
+    })
+  }
+
+  /**
+   * Runs show.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async show() {
+    await this._respond(async () => {
+      const job = await this._store().getJob(this.params().id)
+
+      if (!job) {
+        await this.render({json: {error: "not_found"}, status: 404})
+        return
+      }
+
+      await this.render({json: {job: this._serializeJob(job)}})
+    })
+  }
+
+  /**
+   * Runs schedule.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async schedule() {
+    await this._respond(async () => {
+      const scheduled = await this.getConfiguration().getScheduledBackgroundJobsConfig()
+
+      await this.render({json: {schedule: this._serializeSchedule(scheduled)}})
+    })
+  }
+
+  /**
+   * Runs serialize job.
+   * @param {import("../types.js").BackgroundJobRow} job - Job row.
+   * @returns {Record<string, ?>} - Serialized job for the API.
+   */
+  _serializeJob(job) {
+    const redactArgs = Boolean(this._mountOptions().redactArgs)
+
+    return {
+      args: redactArgs ? undefined : job.args,
+      argsRedacted: redactArgs,
+      attempts: job.attempts,
+      completedAtMs: job.completedAtMs,
+      createdAtMs: job.createdAtMs,
+      executionMode: job.executionMode,
+      failedAtMs: job.failedAtMs,
+      forked: job.forked,
+      handedOffAtMs: job.handedOffAtMs,
+      id: job.id,
+      jobName: job.jobName,
+      lastError: job.lastError,
+      maxRetries: job.maxRetries,
+      orphanedAtMs: job.orphanedAtMs,
+      scheduledAtMs: job.scheduledAtMs,
+      status: job.status,
+      workerId: job.workerId
+    }
+  }
+
+  /**
+   * Runs serialize schedule.
+   * @param {import("../../configuration-types.js").ScheduledBackgroundJobsConfiguration | undefined} scheduled - Scheduled jobs config.
+   * @returns {Array<Record<string, ?>>} - Serialized recurring jobs.
+   */
+  _serializeSchedule(scheduled) {
+    const jobs = scheduled?.jobs
+
+    if (!jobs || typeof jobs !== "object") return []
+
+    const redactArgs = Boolean(this._mountOptions().redactArgs)
+
+    return Object.keys(jobs).map((name) => {
+      const entry = jobs[name] || /**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {?} */ ({})
+
+      return {
+        args: redactArgs ? undefined : (entry.args || []),
+        cron: entry.cron,
+        enabled: entry.enabled !== false,
+        every: entry.every,
+        jobName: typeof entry.class === "function" ? entry.class.name : undefined,
+        name,
+        options: entry.options || {}
+      }
+    })
+  }
+
+  /**
+   * Runs sanitize status.
+   * @param {?} value - Raw status param.
+   * @returns {string | undefined} - Valid status or undefined.
+   */
+  _sanitizeStatus(value) {
+    return typeof value === "string" && DASHBOARD_STATUSES.includes(value) ? value : undefined
+  }
+
+  /**
+   * Runs sanitize sort.
+   * @param {?} value - Raw sort param (e.g. "createdAtMs" or "-failedAtMs").
+   * @returns {{sortColumn: string, sortDirection: "ASC" | "DESC"}} - Normalized sort.
+   */
+  _sanitizeSort(value) {
+    if (typeof value !== "string" || value.length === 0) {
+      return {sortColumn: "createdAtMs", sortDirection: "DESC"}
+    }
+
+    const descending = value.startsWith("-")
+    const key = descending ? value.slice(1) : value
+    const sortColumn = SORTABLE_KEYS.includes(key) ? key : "createdAtMs"
+
+    return {sortColumn, sortDirection: descending ? "DESC" : "ASC"}
+  }
+
+  /**
+   * Runs positive int.
+   * @param {?} value - Raw numeric param.
+   * @param {number} fallback - Fallback when invalid.
+   * @returns {number} - Positive integer.
+   */
+  _positiveInt(value, fallback) {
+    const numeric = Number(Array.isArray(value) ? value[0] : value)
+
+    if (!Number.isFinite(numeric) || numeric < 1) return fallback
+
+    return Math.floor(numeric)
+  }
+}

package/src/background-jobs/web/index.js

@@ -0,0 +1,57 @@
+// @ts-check
+
+import VelociousBackgroundJobsWebController from "./controller.js"
+import {matchJobsApiPath, normalizeMountPrefix} from "./path-matcher.js"
+import {registerJobsMount} from "./registry.js"
+
+/**
+ * Mountable read-only background-jobs dashboard API. Include it in a routes file
+ * the way Sidekiq::Web is mounted in Rails:
+ *
+ * ```js
+ * routes.draw((route) => {
+ *   route.mount(VelociousBackgroundJobsApi, {
+ *     at: "/velocious/jobs",
+ *     authorize: async ({request, ability}) => { ... },
+ *     accessTokens: [process.env.VELOCIOUS_JOBS_TOKEN]
+ *   })
+ * })
+ * ```
+ */
+export default class VelociousBackgroundJobsApi {
+  /**
+   * Registers the jobs API under `at`. Implemented as a route-resolver hook so
+   * the controller can live inside the velocious package rather than the host
+   * app's `src/routes` directory. Invoked by the routing layer for each
+   * `route.mount(...)` registration.
+   * @param {object} args - Options.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} args.at - Mount path prefix (e.g. "/velocious/jobs").
+   * @param {import("./registry.js").JobsMountOptions["authorize"]} [args.authorize] - Authorization callback.
+   * @param {string[]} [args.accessTokens] - Accepted bearer tokens for cross-origin/native access.
+   * @param {string[]} [args.allowedOrigins] - Allowed CORS origins for browser access.
+   * @param {boolean} [args.redactArgs] - When true, job arguments are omitted from responses.
+   * @param {string} [args.databaseIdentifier] - Database identifier the jobs store reads from.
+   * @returns {void} - No return value.
+   */
+  static mountInto({accessTokens, allowedOrigins, at, authorize, configuration, databaseIdentifier, redactArgs}) {
+    if (!configuration) throw new Error("No configuration given")
+
+    const prefix = normalizeMountPrefix(at)
+
+    registerJobsMount(configuration, prefix, {accessTokens, allowedOrigins, authorize, databaseIdentifier, redactArgs})
+
+    configuration.addRouteResolverHook(({currentPath, request}) => {
+      const match = matchJobsApiPath({method: request.httpMethod(), path: currentPath, prefix})
+
+      if (!match) return null
+
+      return {
+        action: match.action,
+        controller: "velociousBackgroundJobsWeb",
+        controllerClass: VelociousBackgroundJobsWebController,
+        params: {...match.params, velociousJobsMountAt: prefix}
+      }
+    })
+  }
+}

package/src/background-jobs/web/path-matcher.js

@@ -0,0 +1,74 @@
+// @ts-check
+
+/**
+ * @typedef {object} JobsApiMatch
+ * @property {string} action - Controller action to run.
+ * @property {Record<string, string>} params - Extra params extracted from the path.
+ */
+
+/**
+ * Normalizes a mount prefix: ensures a leading slash and strips any trailing
+ * slash so `/velocious/jobs/` and `/velocious/jobs` behave identically.
+ * @param {string} at - Raw mount prefix.
+ * @returns {string} - Normalized prefix.
+ */
+export function normalizeMountPrefix(at) {
+  if (typeof at !== "string" || !at.startsWith("/")) {
+    throw new Error(`mount requires an 'at' path starting with '/', got: ${String(at)}`)
+  }
+
+  if (at.length > 1 && at.endsWith("/")) {
+    return at.slice(0, -1)
+  }
+
+  return at
+}
+
+/**
+ * Matches an incoming request against the read-only jobs API routes that live
+ * under the mount prefix. Returns the controller action plus any extracted
+ * params, or null when the path/method isn't part of the jobs API.
+ * @param {object} args - Options.
+ * @param {string} args.prefix - Normalized mount prefix.
+ * @param {string} args.path - Request path without query string.
+ * @param {string} args.method - HTTP method.
+ * @returns {JobsApiMatch | null} - Matched action or null.
+ */
+export function matchJobsApiPath({prefix, path, method}) {
+  /** @type {string} */
+  let subPath
+
+  if (prefix === "/") {
+    // Root mount: the whole path is the sub-path (avoid building a "//" guard).
+    subPath = path
+  } else if (path === prefix) {
+    subPath = "/"
+  } else if (path.startsWith(`${prefix}/`)) {
+    subPath = path.slice(prefix.length)
+  } else {
+    return null
+  }
+
+  if (method === "GET" && subPath === "/api/health") return {action: "health", params: {}}
+  if (method === "GET" && subPath === "/api/stats") return {action: "stats", params: {}}
+  if (method === "GET" && subPath === "/api/schedule") return {action: "schedule", params: {}}
+  if (method === "GET" && subPath === "/api/jobs") return {action: "index", params: {}}
+
+  if (method === "GET") {
+    const jobMatch = subPath.match(/^\/api\/jobs\/([^/]+)$/)
+
+    if (jobMatch) {
+      let id
+
+      try {
+        id = decodeURIComponent(jobMatch[1])
+      } catch {
+        return null
+      }
+
+      return {action: "show", params: {id}}
+    }
+  }
+
+  return null
+}

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

@@ -0,0 +1,49 @@
+// @ts-check
+
+/**
+ * JobsMountOptions type.
+ * @typedef {object} JobsMountOptions
+ * @property {(args: {request: import("../../http-server/client/request.js").default, ability: (import("../../authorization/ability.js").default | undefined), token: (string | null), configuration: import("../../configuration.js").default}) => (boolean | void | Promise<boolean | void>)} [authorize] - Authorization callback. Return true to allow the request.
+ * @property {string[]} [accessTokens] - Bearer tokens accepted for cross-origin/native access.
+ * @property {string[]} [allowedOrigins] - Origins allowed for cross-origin browser access.
+ * @property {boolean} [redactArgs] - When true, job arguments are omitted from API responses.
+ * @property {string} [databaseIdentifier] - Database identifier the jobs store reads from.
+ */
+
+/**
+ * Mount options are keyed by configuration so multiple configurations (e.g.
+ * across tests) never share state, and by mount path so a single configuration
+ * can mount the dashboard at more than one prefix. Functions in the options
+ * (the `authorize` callback) can't travel through route params, so the
+ * controller looks them up here using the plain `at` string it receives.
+ * @type {WeakMap<import("../../configuration.js").default, Map<string, JobsMountOptions>>}
+ */
+const registry = new WeakMap()
+
+/**
+ * Runs the registerJobsMount helper.
+ * @param {import("../../configuration.js").default} configuration - Configuration instance.
+ * @param {string} at - Normalized mount path.
+ * @param {JobsMountOptions} options - Mount options.
+ * @returns {void} - No return value.
+ */
+export function registerJobsMount(configuration, at, options) {
+  let byPath = registry.get(configuration)
+
+  if (!byPath) {
+    byPath = new Map()
+    registry.set(configuration, byPath)
+  }
+
+  byPath.set(at, options)
+}
+
+/**
+ * Runs the getJobsMount helper.
+ * @param {import("../../configuration.js").default} configuration - Configuration instance.
+ * @param {string} at - Normalized mount path.
+ * @returns {JobsMountOptions | undefined} - Mount options if registered.
+ */
+export function getJobsMount(configuration, at) {
+  return registry.get(configuration)?.get(at)
+}