velocious 1.0.666 → 1.0.668

package/build/background-jobs/main.js

@@ -529,7 +529,6 @@ export default class BackgroundJobsMain {
     await this.store.reconcileQueueConcurrency()
     if (this.lifecycleState !== expectedLifecycleState) return false
     this._setupDispatchTriggers()
-    this._setupStartupHandoffReclaim()
     this._startOrphanSweep()
     await this._startScheduler()
     if (this.lifecycleState !== expectedLifecycleState) {
@@ -542,6 +541,7 @@ export default class BackgroundJobsMain {
     this._activeOwnershipReady = true
     this._creditReadyWorkers()
     await this._drain()
+    if (this.lifecycleState === expectedLifecycleState) this._setupStartupHandoffReclaim()
     return this.lifecycleState === expectedLifecycleState
   }
 
@@ -1157,6 +1157,8 @@ export default class BackgroundJobsMain {
       if (message?.type === "enqueue" && !message.producerProof) jsonSocket.send({type: "enqueue-error", error: "Background jobs generation is retired"})
       if (message?.type === "replace-scheduled") jsonSocket.send({type: "replace-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "cancel-scheduled") jsonSocket.send({type: "cancel-scheduled-error", error: "Background jobs generation is retired"})
+      if (message?.type === "get-scheduled-job") jsonSocket.send({type: "get-scheduled-job-error", error: "Background jobs generation is retired"})
+      if (message?.type === "wake-scheduled") jsonSocket.send({type: "wake-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type !== "enqueue" || !message.producerProof) return
     }
 
@@ -1172,6 +1174,16 @@ export default class BackgroundJobsMain {
 
     if (message?.type === "cancel-scheduled") {
       await this._handleCancelScheduled({jsonSocket, message})
+      return
+    }
+
+    if (message?.type === "get-scheduled-job") {
+      await this._handleGetScheduledJob({jsonSocket, message})
+      return
+    }
+
+    if (message?.type === "wake-scheduled") {
+      await this._handleWakeScheduled({jsonSocket, message})
     }
   }
 
@@ -1599,6 +1611,61 @@ export default class BackgroundJobsMain {
     }
   }
 
+  /**
+   * Handles a stable schedule lookup and returns only normalized adapter jobs.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobGetScheduledMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleGetScheduledJob({jsonSocket, message}) {
+    try {
+      const result = await this.store.getScheduledJob(message.scheduleKey, {
+        includeLatestTerminal: message.includeLatestTerminal
+      })
+
+      jsonSocket.send({type: "scheduled-job", ...result})
+    } catch (error) {
+      this._handleClientMutationError({
+        context: {scheduleKey: message.scheduleKey, stage: "background-job-get-scheduled"},
+        error,
+        fallbackMessage: "Failed to read scheduled job",
+        jsonSocket,
+        logMessage: "Failed to read scheduled background job:",
+        responseType: "get-scheduled-job-error"
+      })
+    }
+  }
+
+  /**
+   * Handles a stable schedule wake and re-arms dispatch after its transaction commits.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobWakeScheduledMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleWakeScheduled({jsonSocket, message}) {
+    try {
+      const result = await this.store.wakeScheduled(message.scheduleKey)
+
+      if (result.outcome === "woken" || result.outcome === "already_due") {
+        this._notifyEnqueued()
+        await this._drain()
+      }
+
+      jsonSocket.send({type: "schedule-woken", ...result})
+    } catch (error) {
+      this._handleClientMutationError({
+        context: {scheduleKey: message.scheduleKey, stage: "background-job-wake-scheduled"},
+        error,
+        fallbackMessage: "Failed to wake scheduled job",
+        jsonSocket,
+        logMessage: "Failed to wake scheduled background job:",
+        responseType: "wake-scheduled-error"
+      })
+    }
+  }
+
   /**
    * Returns safe validation failures and reports unexpected client mutations.
    * @param {object} args - Options.
@@ -1607,7 +1674,7 @@ export default class BackgroundJobsMain {
    * @param {string} args.fallbackMessage - Client-safe fallback message.
    * @param {JsonSocket} args.jsonSocket - JSON socket.
    * @param {string} args.logMessage - Error log prefix.
-   * @param {"enqueue-error" | "replace-scheduled-error" | "cancel-scheduled-error"} args.responseType - Response type.
+   * @param {"enqueue-error" | "replace-scheduled-error" | "cancel-scheduled-error" | "get-scheduled-job-error" | "wake-scheduled-error"} args.responseType - Response type.
    * @returns {void}
    */
   _handleClientMutationError({context, error, fallbackMessage, jsonSocket, logMessage, responseType}) {

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

@@ -1,7 +1,13 @@
 // @ts-check
 
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
-import {cancelScheduledBackgroundJob, enqueueBackgroundJob, replaceScheduledBackgroundJob} from "./runtime.js"
+import {
+  cancelScheduledBackgroundJob,
+  enqueueBackgroundJob,
+  getScheduledBackgroundJob,
+  replaceScheduledBackgroundJob,
+  wakeScheduledBackgroundJob
+} from "./runtime.js"
 
 /**
  * Base class for background jobs.
@@ -186,6 +192,25 @@ export default class VelociousJob {
     return await cancelScheduledBackgroundJob(scheduleKey)
   }
 
+  /**
+   * Reads current ownership and optional terminal history for a stable key.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @param {{includeLatestTerminal?: boolean}} [options] - Lookup options.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+   */
+  static async getScheduledJob(scheduleKey, options = {}) {
+    return await getScheduledBackgroundJob(scheduleKey, options)
+  }
+
+  /**
+   * Expedites a future queued owner without creating another job.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  static async wakeScheduled(scheduleKey) {
+    return await wakeScheduledBackgroundJob(scheduleKey)
+  }
+
   /**
    * Runs split args and options.
    * @param {Array<ReturnType<typeof JSON.parse>>} args - Job args.

package/build/background-jobs/runtime.js

@@ -161,3 +161,61 @@ export async function cancelScheduledBackgroundJobForConfiguration({configuratio
 
   return await client.cancelScheduled({scheduleKey})
 }
+
+/**
+ * Reads stable schedule ownership in background mode.
+ * @param {string} scheduleKey - Stable logical schedule key.
+ * @param {{includeLatestTerminal?: boolean}} [options] - Lookup options.
+ * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+ */
+export async function getScheduledBackgroundJob(scheduleKey, options = {}) {
+  const configuration = currentConfiguration()
+
+  return await getScheduledBackgroundJobForConfiguration({configuration, scheduleKey, ...options})
+}
+
+/**
+ * Reads stable schedule ownership using an explicitly resolved configuration.
+ * @param {object} args - Lookup request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {string} args.scheduleKey - Stable logical schedule key.
+ * @param {boolean} [args.includeLatestTerminal] - Whether to include latest terminal history.
+ * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+ */
+export async function getScheduledBackgroundJobForConfiguration({configuration, scheduleKey, includeLatestTerminal}) {
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("getScheduledJob is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.getScheduledJob({scheduleKey, includeLatestTerminal})
+}
+
+/**
+ * Wakes a stable schedule owner in background mode.
+ * @param {string} scheduleKey - Stable logical schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+ */
+export async function wakeScheduledBackgroundJob(scheduleKey) {
+  const configuration = currentConfiguration()
+
+  return await wakeScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
+}
+
+/**
+ * Wakes a stable schedule owner using an explicitly resolved configuration.
+ * @param {object} args - Wake request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {string} args.scheduleKey - Stable logical schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+ */
+export async function wakeScheduledBackgroundJobForConfiguration({configuration, scheduleKey}) {
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("wakeScheduled is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.wakeScheduled({scheduleKey})
+}