velocious 1.0.627 → 1.0.628

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

@@ -93,6 +93,14 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   await registry.load()
   const JobClass = registry.getJobByName(payload.jobName)
   const jobInstance = new JobClass()
+  const jobArgs = payload.args || []
+  jobInstance._setBackgroundJobContext({
+    args: jobArgs,
+    jobClass: JobClass,
+    jobName: payload.jobName,
+    options: payload.options || {},
+    payload
+  })
   /**
    * Perform.
    * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
@@ -107,7 +115,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   try {
     try {
       await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
-        await perform.apply(jobInstance, payload.args || [])
+        await perform.apply(jobInstance, jobArgs)
       })
     } catch (error) {
       if (error instanceof BackgroundJobRescheduleSignal) {

package/src/background-jobs/local-dispatcher.js

@@ -184,7 +184,29 @@ export default class LocalBackgroundJobsDispatcher {
         configuration: this.configuration,
         JobClass,
         jobArgs: job.args,
-        name: `Local background job: ${job.jobName}`
+        jobOptions: {
+          concurrencyKey: job.concurrencyKey || undefined,
+          executionMode: job.executionMode,
+          maxConcurrency: job.maxConcurrency ?? undefined,
+          maxRetries: job.maxRetries ?? undefined,
+          queue: job.queue,
+          scheduledAtMs: job.scheduledAtMs ?? undefined,
+          timeoutMs: job.timeoutMs ?? undefined
+        },
+        name: `Local background job: ${job.jobName}`,
+        payload: {
+          args: job.args,
+          handedOffAtMs: handoff.handedOffAtMs,
+          handoffId: handoff.handoffId,
+          id: job.id,
+          jobName: job.jobName,
+          options: {
+            concurrencyKey: job.concurrencyKey || undefined,
+            executionMode: job.executionMode,
+            maxConcurrency: job.maxConcurrency ?? undefined,
+            queue: job.queue
+          }
+        }
       })
     } catch (error) {
       if (error instanceof BackgroundJobRescheduleSignal) {

package/src/background-jobs/main.js

@@ -223,10 +223,7 @@ export default class BackgroundJobsMain {
           await this.store.enqueue({
             jobName: jobClass.jobName(),
             args,
-            // Fold in the job class's static `queue` (as performLater* do) so a
-            // scheduled job with `static queue = "..."` lands on its queue and
-            // honors the configured cap without every schedule repeating it.
-            options: jobClass._withQueue(options)
+            options: jobClass._withJobContext({jobArgs: args, jobOptions: options})
           })
           this._notifyEnqueued()
           // Persistence is the scheduler enqueue boundary. Dispatch remains
@@ -1400,7 +1397,12 @@ export default class BackgroundJobsMain {
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
+              concurrencyKey: job.concurrencyKey || undefined,
               executionMode: job.executionMode,
+              maxConcurrency: job.maxConcurrency ?? undefined,
+              maxRetries: job.maxRetries ?? undefined,
+              queue: job.queue,
+              scheduledAtMs: job.scheduledAtMs ?? undefined,
               ...(job.timeoutMs === null ? {} : {timeoutMs: job.timeoutMs})
             }
           }

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

@@ -6,11 +6,20 @@
  * @param {import("../configuration.js").default} args.configuration - Active configuration.
  * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
  * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions} [args.jobOptions] - Resolved runtime options.
  * @param {string} args.name - Connection-scope label.
+ * @param {import("./types.js").BackgroundJobPayload} [args.payload] - Persisted runner payload.
  * @returns {Promise<void>} - Resolves after performance.
  */
-export default async function performBackgroundJob({configuration, JobClass, jobArgs, name}) {
+export default async function performBackgroundJob({configuration, JobClass, jobArgs, jobOptions = {}, name, payload}) {
   const jobInstance = new JobClass()
+  jobInstance._setBackgroundJobContext({
+    args: jobArgs,
+    jobClass: JobClass,
+    jobName: JobClass.jobName(),
+    options: jobOptions,
+    ...(payload ? {payload} : {})
+  })
   /**
    * Narrows the generic subclass's runtime method to serialized job arguments.
    * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>}

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

@@ -14,6 +14,11 @@ import {cancelScheduledBackgroundJob, enqueueBackgroundJob, replaceScheduledBack
  * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
  */
 export default class VelociousJob {
+  constructor() {
+    /** @type {import("./types.js").BackgroundJobContext | undefined} */
+    this._backgroundJobContext = undefined
+  }
+
   /**
    * Database identifiers checked out while this job performs. Set an explicit
    * list to avoid holding unrelated configured database connections, or `[]`
@@ -82,6 +87,63 @@ export default class VelociousJob {
     return merged
   }
 
+  /**
+   * Resolves class-derived enqueue options on a hydrated job instance. Explicit
+   * per-enqueue options take precedence over the instance concurrency key.
+   * @param {object} args - Job context.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+   * @returns {import("./types.js").BackgroundJobOptions} - Resolved job options.
+   */
+  static _withJobContext({jobArgs, jobOptions}) {
+    const options = this._withQueue(jobOptions)
+
+    if (options.concurrencyKey !== undefined) return options
+
+    const jobInstance = new this()
+    jobInstance._setBackgroundJobContext({
+      args: jobArgs,
+      jobClass: this,
+      jobName: this.jobName(),
+      options
+    })
+    const concurrencyKey = jobInstance.concurrencyKey()
+
+    if (concurrencyKey !== undefined) options.concurrencyKey = concurrencyKey
+
+    return options
+  }
+
+  /**
+   * Sets the complete context available to this hydrated job instance.
+   * Framework enqueue/runner boundaries own this method.
+   * @param {import("./types.js").BackgroundJobContext} context - Job context.
+   * @returns {void}
+   */
+  _setBackgroundJobContext(context) {
+    this._backgroundJobContext = context
+  }
+
+  /**
+   * Returns this hydrated job's complete enqueue or runner context.
+   * @returns {import("./types.js").BackgroundJobContext} - Job context.
+   */
+  backgroundJobContext() {
+    if (!this._backgroundJobContext) throw new Error("Background job context is not hydrated")
+
+    return this._backgroundJobContext
+  }
+
+  /**
+   * Override to derive a durable concurrency key from `backgroundJobContext()`.
+   * Pair the derived key with `maxConcurrency` in enqueue options. An explicit
+   * per-enqueue `concurrencyKey` takes precedence and skips this method.
+   * @returns {string | undefined} - Derived concurrency key, or undefined for none.
+   */
+  concurrencyKey() {
+    return undefined
+  }
+
   /**
    * Runs perform later.
    * @param {...ReturnType<typeof JSON.parse>} args - Job args.

package/src/background-jobs/runtime.js

@@ -52,9 +52,10 @@ export async function enqueueBackgroundJob({JobClass, jobArgs, jobOptions}) {
  * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
  */
 export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions}) {
+  const resolvedJobOptions = JobClass._withJobContext({jobArgs, jobOptions})
 
   if (configuration.getBackgroundJobsConfig().mode === "inline") {
-    validateInlineOptions(jobOptions)
+    validateInlineOptions(resolvedJobOptions)
     configuration.setCurrent()
     await configuration.initialize({type: "background-jobs-inline"})
 
@@ -63,6 +64,7 @@ export async function enqueueBackgroundJobForConfiguration({configuration, JobCl
         configuration,
         JobClass,
         jobArgs,
+        jobOptions: resolvedJobOptions,
         name: `Background job inline mode: ${JobClass.jobName()}`
       })
     } catch (error) {
@@ -81,7 +83,7 @@ export async function enqueueBackgroundJobForConfiguration({configuration, JobCl
   return await client.enqueue({
     jobName: JobClass.jobName(),
     args: jobArgs,
-    options: JobClass._withQueue(jobOptions)
+    options: resolvedJobOptions
   })
 }
 
@@ -117,12 +119,13 @@ export async function replaceScheduledBackgroundJobForConfiguration({configurati
   }
 
   const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+  const resolvedJobOptions = JobClass._withJobContext({jobArgs, jobOptions})
 
   return await client.replaceScheduled({
     scheduleKey,
     jobName: JobClass.jobName(),
     args: jobArgs,
-    options: JobClass._withQueue(jobOptions)
+    options: resolvedJobOptions
   })
 }
 

package/src/background-jobs/types.js

@@ -71,6 +71,14 @@
  * @property {number} [handedOffAtMs] - Time handed to a worker in ms.
  * @property {BackgroundJobOptions} [options] - Runtime options.
  */
+/**
+ * @typedef {object} BackgroundJobContext
+ * @property {typeof import("./platform-job.js").default} jobClass - Concrete job class.
+ * @property {string} jobName - Registered job name.
+ * @property {Array<ReturnType<typeof JSON.parse>>} args - Serialized job arguments.
+ * @property {BackgroundJobOptions} options - Resolved enqueue/runtime options.
+ * @property {BackgroundJobPayload} [payload] - Complete persisted runner payload when the job is performing.
+ */
 /**
  * @typedef {object} BackgroundJobRow
  * @property {string} id - Job id.

package/src/background-jobs/worker.js

@@ -1054,7 +1054,9 @@ export default class BackgroundJobsWorker {
       configuration,
       JobClass,
       jobArgs: payload.args || [],
-      name: `Background job worker inline: ${payload.jobName}`
+      jobOptions: payload.options || {},
+      name: `Background job worker inline: ${payload.jobName}`,
+      payload
     })
   }