velocious 1.0.665 → 1.0.667

package/src/background-jobs/client.js

@@ -1,11 +1,82 @@
 // @ts-check
 
-import timeout 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 {
   /**
@@ -57,17 +128,36 @@ export default class BackgroundJobsClient {
       ...(producerInvocationId ? {producerInvocationId} : {}),
       ...(producerProof ? {producerProof} : {})
     }
-    const acknowledgement = {explicitlyRejected: false, generationFenced: false, requestSent: false}
+    /**
+     * Creates safe observations for one attempt without retaining request data.
+     * @param {object} args - Attempt identity.
+     * @param {"initial" | "owned_replay"} args.attemptKind - Initial attempt or owned replay.
+     * @param {number} args.attemptNumber - One-based attempt number.
+     * @returns {import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt} - Mutable attempt observations.
+     */
+    const newAttemptObservation = ({attemptKind, attemptNumber}) => ({
+      acknowledgementWaitElapsedMs: 0,
+      attemptElapsedMs: 0,
+      attemptKind,
+      attemptNumber,
+      explicitlyRejected: false,
+      generationFenced: false,
+      requestSent: false
+    })
     /**
      * Sends one enqueue attempt. An owned caller may replay this exact message
      * once when transport acknowledgement remains ambiguous after send.
-     * @param {{explicitlyRejected: boolean, generationFenced: boolean, requestSent: boolean} | undefined} attemptAcknowledgement - First-attempt observations.
+     * @param {import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt} attemptObservation - Mutable attempt observations.
+     * @param {Readonly<Array<import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt>>} previousAttempts - Earlier timed-out attempts.
      * @returns {Promise<string>} - Job id.
      */
-    const enqueueAttempt = async (attemptAcknowledgement) => {
+    const enqueueAttempt = async (attemptObservation, previousAttempts) => {
+      const attemptStartedAtMs = Date.now()
       const request = await this._request()
       const requestAbortController = new AbortController()
       const timeoutErrorMessage = `Background job enqueue acknowledgement timed out after ${this.enqueueTimeoutMs}ms`
+      /** @type {number | undefined} */
+      let requestSentAtMs
       /**
        * Resolves the pre-send phase when the mutation has entered the socket.
        * @type {() => void}
@@ -99,10 +189,9 @@ export default class BackgroundJobsClient {
         signal: requestAbortController.signal,
         onConnect: (jsonSocket) => {
           jsonSocket.send(message)
-          if (attemptAcknowledgement) {
-            attemptAcknowledgement.generationFenced = Boolean(request.generationId)
-            attemptAcknowledgement.requestSent = true
-          }
+          attemptObservation.generationFenced = Boolean(request.generationId)
+          attemptObservation.requestSent = true
+          requestSentAtMs = Date.now()
           markRequestSent()
         },
         onMessage: ({message, resolve, reject}) => {
@@ -112,7 +201,7 @@ export default class BackgroundJobsClient {
           }
 
           if (message?.type === "enqueue-error") {
-            if (attemptAcknowledgement) attemptAcknowledgement.explicitlyRejected = true
+            attemptObservation.explicitlyRejected = true
             reject(new Error(message.error || "Failed to enqueue job"))
           }
         }
@@ -120,16 +209,43 @@ export default class BackgroundJobsClient {
 
       await withEnqueueTimeout(async () => await Promise.race([requestSent, requestPromise]))
 
-      return await withEnqueueTimeout(async () => await requestPromise)
+      try {
+        return await withEnqueueTimeout(async () => await requestPromise)
+      } catch (error) {
+        if (!(error instanceof TimeoutError)) throw error
+        if (requestSentAtMs === undefined) throw new Error("Background job enqueue acknowledgement wait started before the request was sent", {cause: error})
+
+        const timedOutAtMs = Date.now()
+        // The fired timer proves its logical deadline even when the adjustable wall clock reports a shorter interval.
+        const acknowledgementWaitElapsedMs = Math.max(this.enqueueTimeoutMs, timedOutAtMs - requestSentAtMs)
+
+        attemptObservation.acknowledgementWaitElapsedMs = acknowledgementWaitElapsedMs
+        attemptObservation.attemptElapsedMs = Math.max(acknowledgementWaitElapsedMs, timedOutAtMs - attemptStartedAtMs)
+
+        throw new BackgroundJobEnqueueAcknowledgementTimeoutError({
+          acknowledgementTimeoutMs: this.enqueueTimeoutMs,
+          attemptHistory: [...previousAttempts, attemptObservation],
+          cause: error,
+          generationId: request.generationId,
+          jobName,
+          producerInvocationId,
+          producerProofPresent: Boolean(producerProof)
+        })
+      }
     }
 
+    const initialAttempt = newAttemptObservation({attemptKind: "initial", attemptNumber: 1})
+
     try {
-      return await enqueueAttempt(acknowledgement)
+      return await enqueueAttempt(initialAttempt, [])
     } catch (error) {
-      if (!producerInvocationId || !producerProof || !acknowledgement.generationFenced || !acknowledgement.requestSent || acknowledgement.explicitlyRejected) throw error
-    }
+      if (!producerInvocationId || !producerProof || !initialAttempt.generationFenced || !initialAttempt.requestSent || initialAttempt.explicitlyRejected) throw error
+
+      const previousAttempts = error instanceof BackgroundJobEnqueueAcknowledgementTimeoutError ? error.attemptHistory : []
+      const replayAttempt = newAttemptObservation({attemptKind: "owned_replay", attemptNumber: 2})
 
-    return await enqueueAttempt(undefined)
+      return await enqueueAttempt(replayAttempt, previousAttempts)
+    }
   }
 
   /**
@@ -190,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/enqueue-acknowledgement-timeout-error.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import {TimeoutError} from "awaitery/build/timeout.js"
+
+/**
+ * @typedef {object} BackgroundJobEnqueueAttempt
+ * @property {number} acknowledgementWaitElapsedMs - Time spent waiting for the acknowledgement after send.
+ * @property {number} attemptElapsedMs - Total attempt time including connection and generation fencing.
+ * @property {"initial" | "owned_replay"} attemptKind - Initial attempt or the one eligible owned replay.
+ * @property {number} attemptNumber - One-based attempt number.
+ * @property {boolean} explicitlyRejected - Whether the main explicitly rejected the enqueue.
+ * @property {boolean} generationFenced - Whether the configured generation accepted the connection before send.
+ * @property {boolean} requestSent - Whether the enqueue request entered the socket.
+ */
+
+/** Safe typed failure for an ambiguous post-send enqueue acknowledgement timeout. */
+export default class BackgroundJobEnqueueAcknowledgementTimeoutError extends TimeoutError {
+  /**
+   * Builds an enqueue acknowledgement timeout error without request payload or connection details.
+   * @param {object} args - Safe timeout context.
+   * @param {number} args.acknowledgementTimeoutMs - Configured post-send acknowledgement deadline.
+   * @param {Array<BackgroundJobEnqueueAttempt>} args.attemptHistory - Safe observations for timed-out attempts.
+   * @param {TimeoutError} [args.cause] - Original Awaitery timeout.
+   * @param {string} [args.generationId] - Accepted release generation identity.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {string} [args.producerInvocationId] - Owned enqueue invocation identity.
+   * @param {boolean} args.producerProofPresent - Whether the request carried an internal producer proof.
+   */
+  constructor({acknowledgementTimeoutMs, attemptHistory, cause, generationId, jobName, producerInvocationId, producerProofPresent}) {
+    super(`Background job enqueue acknowledgement timed out after ${acknowledgementTimeoutMs}ms`, cause ? {cause} : undefined)
+
+    this.name = "BackgroundJobEnqueueAcknowledgementTimeoutError"
+    /** @type {"BACKGROUND_JOB_ENQUEUE_ACKNOWLEDGEMENT_TIMEOUT"} */
+    this.code = "BACKGROUND_JOB_ENQUEUE_ACKNOWLEDGEMENT_TIMEOUT"
+    this.acknowledgementTimeoutMs = acknowledgementTimeoutMs
+    this.attemptHistory = Object.freeze(attemptHistory.map((attempt) => Object.freeze({
+      acknowledgementWaitElapsedMs: attempt.acknowledgementWaitElapsedMs,
+      attemptElapsedMs: attempt.attemptElapsedMs,
+      attemptKind: attempt.attemptKind,
+      attemptNumber: attempt.attemptNumber,
+      explicitlyRejected: attempt.explicitlyRejected,
+      generationFenced: attempt.generationFenced,
+      requestSent: attempt.requestSent
+    })))
+    this.generationId = generationId
+    this.jobName = jobName
+    this.producerInvocationId = producerInvocationId
+    this.producerProofPresent = producerProofPresent
+  }
+}

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.