velocious 1.0.666 → 1.0.668

package/src/background-jobs/client.js

@@ -1,12 +1,82 @@
 // @ts-check
 
-import timeout, {TimeoutError} from "awaitery/build/timeout.js"
+import timeout, { TimeoutError } from "awaitery/build/timeout.js"
 import configurationResolver from "../configuration-resolver.js"
+import isPlainObject from "../utils/plain-object.js"
 import BackgroundJobEnqueueAcknowledgementTimeoutError from "./enqueue-acknowledgement-timeout-error.js"
 import BackgroundJobsSocketRequest from "./socket-request.js"
 import { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
+import { BACKGROUND_JOB_ACTIVE_STATUSES, BACKGROUND_JOB_EXECUTION_MODES, BACKGROUND_JOB_STATUSES, BACKGROUND_JOB_TERMINAL_STATUSES } from "./job-semantics.js"
 
 const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
+const BACKGROUND_JOB_WAKE_OUTCOMES = ["woken", "already_due", "handed_off", "not_found"]
+const BACKGROUND_JOB_NULLABLE_NUMBER_FIELDS = [
+  "attempts",
+  "childPid",
+  "childReceivedAtMs",
+  "childStartedAtMs",
+  "completedAtMs",
+  "createdAtMs",
+  "failedAtMs",
+  "handedOffAtMs",
+  "maxConcurrency",
+  "maxRetries",
+  "orphanedAtMs",
+  "scheduleOrder",
+  "scheduledAtMs",
+  "timeoutMs"
+]
+const BACKGROUND_JOB_NULLABLE_STRING_FIELDS = ["childInstanceId", "concurrencyKey", "handoffId", "lastError", "scheduleKey", "workerId"]
+
+/**
+ * Checks a required nullable number from a normalized wire row.
+ * @param {ReturnType<typeof JSON.parse>} value - Field value.
+ * @returns {boolean} - Whether the field is null or a finite number.
+ */
+function isNullableBackgroundJobNumber(value) {
+  return value === null || (typeof value === "number" && Number.isFinite(value))
+}
+
+/**
+ * Checks a required nullable string from a normalized wire row.
+ * @param {ReturnType<typeof JSON.parse>} value - Field value.
+ * @returns {boolean} - Whether the field is null or a string.
+ */
+function isNullableBackgroundJobString(value) {
+  return value === null || typeof value === "string"
+}
+
+/**
+ * Checks that a transport job uses the normalized public camel-case shape.
+ * @param {ReturnType<typeof JSON.parse>} value - Transport value.
+ * @returns {value is import("./types.js").BackgroundJobRow} - Whether normalized.
+ */
+function isNormalizedBackgroundJob(value) {
+  if (!isPlainObject(value)) return false
+
+  const job = value
+
+  return typeof job.id === "string"
+    && typeof job.jobName === "string"
+    && Array.isArray(job.args)
+    && BACKGROUND_JOB_EXECUTION_MODES.some((executionMode) => executionMode === job.executionMode)
+    && typeof job.queue === "string"
+    && BACKGROUND_JOB_STATUSES.some((status) => status === job.status)
+    && BACKGROUND_JOB_NULLABLE_NUMBER_FIELDS.every((field) => isNullableBackgroundJobNumber(job[field]))
+    && BACKGROUND_JOB_NULLABLE_STRING_FIELDS.every((field) => isNullableBackgroundJobString(job[field]))
+}
+
+/**
+ * Describes an unexpected protocol response without echoing its payload.
+ * @param {string} operation - Public operation name.
+ * @param {import("./types.js").BackgroundJobSocketMessage} message - Response.
+ * @returns {Error} - Protocol error.
+ */
+function unexpectedResponseError(operation, message) {
+  const responseType = message && typeof message.type === "string" ? message.type : "missing type"
+
+  return new Error(`Unexpected ${operation} response: ${responseType}`)
+}
 
 export default class BackgroundJobsClient {
   /**
@@ -236,4 +306,80 @@ export default class BackgroundJobsClient {
       }
     })
   }
+
+  /**
+   * Reads current stable ownership and optional terminal history.
+   * @param {{scheduleKey: string, includeLatestTerminal?: boolean}} args - Lookup request.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+   */
+  async getScheduledJob({scheduleKey, includeLatestTerminal}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "get-scheduled-job", scheduleKey, includeLatestTerminal})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "scheduled-job") {
+          const {currentJob, latestTerminalJob} = message
+          const currentJobValid = currentJob === null
+            || (isNormalizedBackgroundJob(currentJob) && BACKGROUND_JOB_ACTIVE_STATUSES.some((status) => status === currentJob.status))
+          const latestTerminalJobValid = latestTerminalJob === null
+            || (isNormalizedBackgroundJob(latestTerminalJob) && BACKGROUND_JOB_TERMINAL_STATUSES.some((status) => status === latestTerminalJob.status))
+
+          if (!currentJobValid || !latestTerminalJobValid) {
+            reject(new Error("Invalid getScheduledJob response: expected normalized public job values"))
+            return
+          }
+
+          resolve({currentJob, latestTerminalJob})
+          return
+        }
+
+        if (message?.type === "get-scheduled-job-error") {
+          reject(new Error(message.error || "Failed to read scheduled job"))
+          return
+        }
+
+        reject(unexpectedResponseError("getScheduledJob", message))
+      }
+    })
+  }
+
+  /**
+   * Expedites a future queued stable owner without changing job identity.
+   * @param {{scheduleKey: string}} args - Wake request.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  async wakeScheduled({scheduleKey}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "wake-scheduled", scheduleKey})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "schedule-woken") {
+          const outcome = message.outcome
+          const knownOutcome = BACKGROUND_JOB_WAKE_OUTCOMES.includes(outcome)
+          const validJobId = outcome === "not_found" ? message.jobId === null : typeof message.jobId === "string" && message.jobId.length > 0
+
+          if (!knownOutcome || !validJobId) {
+            reject(new Error("Invalid wakeScheduled response"))
+            return
+          }
+
+          resolve({jobId: message.jobId, outcome})
+          return
+        }
+
+        if (message?.type === "wake-scheduled-error") {
+          reject(new Error(message.error || "Failed to wake scheduled job"))
+          return
+        }
+
+        reject(unexpectedResponseError("wakeScheduled", message))
+      }
+    })
+  }
 }

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

@@ -8,6 +8,36 @@ export const DEFAULT_BACKGROUND_JOB_QUEUE = "default"
 export const QUEUE_CONCURRENCY_KEY_PREFIX = "queue:"
 /** @type {import("./types.js").BackgroundJobExecutionMode[]} */
 export const BACKGROUND_JOB_EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
+/** @type {import("./types.js").BackgroundJobActiveStatus[]} */
+export const BACKGROUND_JOB_ACTIVE_STATUSES = ["queued", "handed_off"]
+/** @type {import("./types.js").BackgroundJobTerminalStatus[]} */
+export const BACKGROUND_JOB_TERMINAL_STATUSES = ["cancelled", "completed", "failed", "orphaned"]
+/** @type {import("./types.js").BackgroundJobStatus[]} */
+export const BACKGROUND_JOB_STATUSES = [...BACKGROUND_JOB_ACTIVE_STATUSES, ...BACKGROUND_JOB_TERMINAL_STATUSES]
+
+/**
+ * Normalizes persisted or transported job status vocabulary.
+ * @param {string} value - Candidate status.
+ * @returns {import("./types.js").BackgroundJobStatus} - Known status.
+ */
+export function normalizeBackgroundJobStatus(value) {
+  const status = BACKGROUND_JOB_STATUSES.find((candidate) => candidate === value)
+
+  if (status) return status
+
+  throw new Error(`Unknown background job status: ${value}`)
+}
+
+/**
+ * Validates a stable logical schedule key at every persistence boundary.
+ * @param {string} scheduleKey - Stable schedule key.
+ * @returns {string} - Validated key.
+ */
+export function normalizeBackgroundJobScheduleKey(scheduleKey) {
+  if (typeof scheduleKey === "string" && scheduleKey.length > 0 && scheduleKey.length <= 255) return scheduleKey
+
+  throw VelociousError.safe("background job scheduleKey must be a non-empty string of at most 255 characters")
+}
 
 /**
  * Normalizes a job queue.

package/src/background-jobs/job.js

@@ -8,7 +8,9 @@ import PlatformVelociousJob from "./platform-job.js"
 import {
   cancelScheduledBackgroundJobForConfiguration,
   enqueueBackgroundJobForConfiguration,
-  replaceScheduledBackgroundJobForConfiguration
+  getScheduledBackgroundJobForConfiguration,
+  replaceScheduledBackgroundJobForConfiguration,
+  wakeScheduledBackgroundJobForConfiguration
 } from "./runtime.js"
 
 /**
@@ -84,4 +86,27 @@ export default class VelociousJob extends PlatformVelociousJob {
 
     return await cancelScheduledBackgroundJobForConfiguration({configuration, 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 = {}) {
+    const configuration = await configurationResolver()
+
+    return await getScheduledBackgroundJobForConfiguration({configuration, 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) {
+    const configuration = await configurationResolver()
+
+    return await wakeScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
+  }
 }

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

@@ -67,18 +67,46 @@ export default class LocalBackgroundJobsAdapter extends BackgroundJobsAdapter {
   }
 
   /**
-   * Rejects stable-key cancellation, which is outside the local adapter contract.
-   * @param {string} _scheduleKey - Unsupported stable key.
-   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Never resolves.
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
    */
-  async cancelScheduled(_scheduleKey) { throw new Error("cancelScheduled is not supported by the local background-jobs adapter") }
+  async cancelScheduled(scheduleKey) {
+    await this.ensureReady()
+    return await this.store.cancelScheduled(scheduleKey)
+  }
+
+  /**
+   * Replaces the current owner of a stable schedule key.
+   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Replacement request.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  async replaceScheduled(args) {
+    await this.ensureReady()
+    this.registry.resolve(args.jobName)
+    return await this.store.replaceScheduled(args)
+  }
 
   /**
-   * Rejects stable-key replacement, which is outside the local adapter contract.
-   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Unsupported request.
-   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Never resolves.
+   * Reads stable ownership and optional terminal history.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @param {{includeLatestTerminal?: boolean}} [options] - Lookup options.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized local jobs.
    */
-  async replaceScheduled(_args) { throw new Error("replaceScheduled is not supported by the local background-jobs adapter") }
+  async getScheduledJob(scheduleKey, options) {
+    await this.ensureReady()
+    return await this.store.getScheduledJob(scheduleKey, options)
+  }
+
+  /**
+   * Makes a future queued stable owner due without replacing it.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Exact wake result.
+   */
+  async wakeScheduled(scheduleKey) {
+    await this.ensureReady()
+    return await this.store.wakeScheduled(scheduleKey)
+  }
 
   /**
    * Finds the next eligible local job.