@holo-js/queue 0.3.28 → 0.4.0

package/dist/index.mjs

@@ -7,182 +7,16 @@ import {
   DEFAULT_QUEUE_NAME,
   DEFAULT_QUEUE_RETRY_AFTER,
   DEFAULT_QUEUE_SLEEP,
+  QUEUE_TIMER_MAX_SECONDS,
+  assertQueueTimeoutBelowRetryAfter,
+  defineJob,
   holoQueueDefaults,
+  isQueueJobDefinition,
   normalizeQueueConfig,
-  queueInternals
-} from "./chunk-5MPOVBVE.mjs";
-
-// src/contracts.ts
-function getQueueJobDispatcher() {
-  return globalThis.__holoQueueJobDispatcher__;
-}
-function setQueueJobDispatcher(dispatcher) {
-  const runtime = globalThis;
-  runtime.__holoQueueJobDispatcher__ = dispatcher;
-}
-function getQueueJobSyncDispatcher() {
-  return globalThis.__holoQueueJobSyncDispatcher__;
-}
-function setQueueJobSyncDispatcher(dispatcher) {
-  const runtime = globalThis;
-  runtime.__holoQueueJobSyncDispatcher__ = dispatcher;
-}
-function getQueueJobDefinitionNames() {
-  const runtime = globalThis;
-  runtime.__holoQueueJobDefinitionNames__ ??= /* @__PURE__ */ new WeakMap();
-  return runtime.__holoQueueJobDefinitionNames__;
-}
-function getQueueJobDefinitionsByName() {
-  const runtime = globalThis;
-  runtime.__holoQueueJobDefinitionsByName__ ??= /* @__PURE__ */ new Map();
-  return runtime.__holoQueueJobDefinitionsByName__;
-}
-function setQueueJobDefinitionName(definition, name) {
-  getQueueJobDefinitionNames().set(definition, name);
-  const definitions = getQueueJobDefinitionsByName().get(name) ?? /* @__PURE__ */ new Set();
-  definitions.add(definition);
-  getQueueJobDefinitionsByName().set(name, definitions);
-}
-function deleteQueueJobDefinitionName(name) {
-  const definitions = getQueueJobDefinitionsByName().get(name);
-  for (const definition of definitions ?? []) {
-    if (getQueueJobDefinitionNames().get(definition) === name) {
-      getQueueJobDefinitionNames().delete(definition);
-    }
-  }
-  getQueueJobDefinitionsByName().delete(name);
-}
-function clearQueueJobDefinitionNames() {
-  for (const name of getQueueJobDefinitionsByName().keys()) {
-    deleteQueueJobDefinitionName(name);
-  }
-}
-function resolveQueueJobDefinitionName(definition) {
-  const name = getQueueJobDefinitionNames().get(definition);
-  if (name) {
-    return name;
-  }
-  throw new Error("[Holo Queue] Job definitions cannot dispatch before the job is registered.");
-}
-function dispatchDefinedQueueJob(definition, payload) {
-  const dispatcher = getQueueJobDispatcher();
-  if (!dispatcher) {
-    throw new Error("[Holo Queue] Job definitions cannot dispatch before the queue runtime is loaded.");
-  }
-  return dispatcher(resolveQueueJobDefinitionName(definition), payload);
-}
-function dispatchDefinedQueueJobSync(definition, payload) {
-  const dispatcher = getQueueJobSyncDispatcher();
-  if (!dispatcher) {
-    throw new Error("[Holo Queue] Job definitions cannot dispatch before the queue runtime is loaded.");
-  }
-  return dispatcher(resolveQueueJobDefinitionName(definition), payload);
-}
-function normalizeOptionalString(value, label) {
-  if (typeof value === "undefined") {
-    return void 0;
-  }
-  const normalized = value.trim();
-  if (!normalized) {
-    throw new Error(`[Holo Queue] ${label} must be a non-empty string when provided.`);
-  }
-  return normalized;
-}
-function normalizeOptionalInteger(value, label, options = {}) {
-  if (typeof value === "undefined") {
-    return void 0;
-  }
-  if (!Number.isInteger(value)) {
-    throw new Error(`[Holo Queue] ${label} must be an integer when provided.`);
-  }
-  if (typeof options.minimum === "number" && value < options.minimum) {
-    throw new Error(`[Holo Queue] ${label} must be greater than or equal to ${options.minimum}.`);
-  }
-  return value;
-}
-function normalizeBackoff(value) {
-  if (typeof value === "undefined") {
-    return void 0;
-  }
-  if (typeof value === "number") {
-    return normalizeOptionalInteger(value, "Job backoff", { minimum: 0 });
-  }
-  if (!Array.isArray(value)) {
-    throw new Error("[Holo Queue] Job backoff must be a number or an array of integers.");
-  }
-  const normalized = value.map((entry, index) => {
-    if (!Number.isInteger(entry)) {
-      throw new Error(`[Holo Queue] Job backoff entry at index ${index} must be an integer.`);
-    }
-    if (entry < 0) {
-      throw new Error(`[Holo Queue] Job backoff entry at index ${index} must be greater than or equal to 0.`);
-    }
-    return entry;
-  });
-  return Object.freeze(normalized);
-}
-function normalizeOptionalHook(value, label) {
-  if (typeof value === "undefined") {
-    return void 0;
-  }
-  if (typeof value !== "function") {
-    throw new Error(`[Holo Queue] ${label} must be a function when provided.`);
-  }
-  return value;
-}
-function isQueueJobDefinition(value) {
-  return value !== null && typeof value === "object" && "handle" in value && typeof value.handle === "function";
-}
-function normalizeQueueJobDefinition(job) {
-  if (!isQueueJobDefinition(job)) {
-    throw new Error('[Holo Queue] Jobs must define a "handle" function.');
-  }
-  return {
-    ...job,
-    ...typeof job.connection === "undefined" ? {} : { connection: normalizeOptionalString(job.connection, "Job connection") },
-    ...typeof job.queue === "undefined" ? {} : { queue: normalizeOptionalString(job.queue, "Job queue") },
-    ...typeof job.tries === "undefined" ? {} : { tries: normalizeOptionalInteger(job.tries, "Job tries", { minimum: 1 }) },
-    ...typeof job.timeout === "undefined" ? {} : { timeout: normalizeOptionalInteger(job.timeout, "Job timeout", { minimum: 0 }) },
-    ...typeof job.backoff === "undefined" ? {} : { backoff: normalizeBackoff(job.backoff) },
-    ...typeof job.onCompleted === "undefined" ? {} : { onCompleted: normalizeOptionalHook(job.onCompleted, "Job onCompleted hook") },
-    ...typeof job.onFailed === "undefined" ? {} : { onFailed: normalizeOptionalHook(job.onFailed, "Job onFailed hook") }
-  };
-}
-function defineJob(job) {
-  const normalized = normalizeQueueJobDefinition(job);
-  const registeredName = getQueueJobDefinitionNames().get(job);
-  if (registeredName) {
-    setQueueJobDefinitionName(normalized, registeredName);
-  }
-  Object.defineProperty(normalized, "dispatch", {
-    value(payload) {
-      return dispatchDefinedQueueJob(normalized, payload);
-    },
-    enumerable: false
-  });
-  Object.defineProperty(normalized, "dispatchSync", {
-    value(payload) {
-      return dispatchDefinedQueueJobSync(normalized, payload);
-    },
-    enumerable: false
-  });
-  return Object.freeze(normalized);
-}
-var queueJobInternals = {
-  clearQueueJobDefinitionNames,
-  deleteQueueJobDefinitionName,
-  dispatchDefinedQueueJob,
-  dispatchDefinedQueueJobSync,
   normalizeQueueJobDefinition,
-  normalizeBackoff,
-  normalizeOptionalHook,
-  normalizeOptionalInteger,
-  normalizeOptionalString,
-  resolveQueueJobDefinitionName,
-  setQueueJobDefinitionName,
-  setQueueJobDispatcher,
-  setQueueJobSyncDispatcher
-};
+  queueInternals,
+  queueJobInternals
+} from "./chunk-CYZWPHVL.mjs";
 
 // src/registry.ts
 function toPosixPath(value) {
@@ -212,6 +46,10 @@ function resolveRegistrationName(definition, options = {}) {
   }
   throw new Error("[Holo Queue] Registered jobs require an explicit name or a sourcePath-derived name.");
 }
+var registrationTimeoutCheck;
+function setQueueJobRegistrationTimeoutCheck(check) {
+  registrationTimeoutCheck = check;
+}
 function registerQueueJob(definition, options = {}) {
   if (!isQueueJobDefinition(definition)) {
     throw new Error('[Holo Queue] Jobs must define a "handle" function.');
@@ -222,6 +60,7 @@ function registerQueueJob(definition, options = {}) {
   if (registry.has(name) && options.replaceExisting !== true) {
     throw new Error(`[Holo Queue] Queue job "${name}" is already registered.`);
   }
+  registrationTimeoutCheck?.({ name, definition: normalizedDefinition });
   const entry = Object.freeze({
     name,
     ...options.sourcePath ? { sourcePath: options.sourcePath } : {},
@@ -262,6 +101,7 @@ var SyncQueueDriver = class {
   name;
   driver = "sync";
   mode = "sync";
+  acceptsJobId = true;
   context;
   constructor(connection, context) {
     this.name = connection.name;
@@ -292,6 +132,7 @@ var syncQueueDriverInternals = {
 };
 
 // src/runtime.ts
+import { reportError } from "@holo-js/kernel/error-reporting";
 import { randomUUID } from "crypto";
 
 // src/plugins.ts
@@ -546,8 +387,7 @@ async function executeRegisteredQueueJobCompletedHook(envelope, result, contextO
       createJobContext(envelope, contextOverrides)
     );
   } catch (error) {
-    const resolvedError = error instanceof Error ? error : new Error(String(error));
-    console.warn(`[Holo Queue] onCompleted hook failed for job "${envelope.name}": ${resolvedError.message}`);
+    reportError(error, { capability: "queue", operation: "job.onCompleted" });
   }
 }
 async function executeRegisteredQueueJobFailedHook(envelope, error, contextOverrides = {}) {
@@ -562,8 +402,7 @@ async function executeRegisteredQueueJobFailedHook(envelope, error, contextOverr
       createJobContext(envelope, contextOverrides)
     );
   } catch (hookError) {
-    const resolvedError = hookError instanceof Error ? hookError : new Error(String(hookError));
-    console.warn(`[Holo Queue] onFailed hook failed for job "${envelope.name}": ${resolvedError.message}`);
+    reportError(hookError, { capability: "queue", operation: "job.onFailed" });
   }
 }
 async function dispatchThroughDriver(driver, envelope) {
@@ -646,7 +485,7 @@ function resolveSyncExecutionDriver() {
   state.drivers.set(INLINE_SYNC_DRIVER_KEY, driver);
   return driver;
 }
-function createJobEnvelope(jobName, payload, options) {
+function createJobEnvelope(jobName, payload, options, { validateTimeout = true } = {}) {
   const runtime = getQueueRuntimeState();
   const registered = requireRegisteredQueueJob(jobName);
   const connection = resolveConnectionConfig(
@@ -654,6 +493,10 @@ function createJobEnvelope(jobName, payload, options) {
     options.connection ?? registered.definition.connection
   );
   const queue = normalizeQueueName(options.queue ?? registered.definition.queue ?? connection.queue ?? DEFAULT_QUEUE_NAME);
+  const tries = queueJobInternals.normalizeOptionalInteger(options.tries, "Queue dispatch tries", { minimum: 1 }) ?? registered.definition.tries ?? 1;
+  if (validateTimeout) {
+    assertQueueTimeoutBelowRetryAfter(`Queue job "${registered.name}"`, registered.definition.timeout, connection);
+  }
   return Object.freeze({
     id: randomUUID(),
     name: registered.name,
@@ -661,18 +504,36 @@ function createJobEnvelope(jobName, payload, options) {
     queue,
     payload,
     attempts: 0,
-    maxAttempts: registered.definition.tries ?? 1,
+    maxAttempts: tries,
     ...typeof options.delay === "undefined" ? {} : { availableAt: normalizeDelay(options.delay) },
     createdAt: Date.now()
   });
 }
-function createDispatchEnvelope(jobName, payload, options = {}) {
+function createDispatchEnvelope(jobName, payload, options = {}, { runsInline = false } = {}) {
   validateQueuePayload(payload);
-  return createJobEnvelope(jobName, payload, options);
+  const snapshot = JSON.parse(JSON.stringify(payload));
+  return createJobEnvelope(jobName, snapshot, options, { validateTimeout: !runsInline });
+}
+var databaseSpecifier = "@holo-js/db";
+async function loadDatabaseModule() {
+  try {
+    return await import(databaseSpecifier);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && (error.code === "ERR_MODULE_NOT_FOUND" || error.code === "MODULE_NOT_FOUND")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function resolveOpenDatabaseTransaction() {
+  const database = await loadDatabaseModule();
+  const active = database?.connectionAsyncContext.getActive()?.connection;
+  if (!active || active.getScope().kind === "root") {
+    return void 0;
+  }
+  return active;
 }
-async function dispatchRecord(envelope) {
-  const driver = resolveConnectionDriver(envelope.connection);
-  const result = await dispatchThroughDriver(driver, envelope);
+function toDispatchResult(envelope, result) {
   return {
     jobId: result.jobId,
     connection: envelope.connection,
@@ -680,6 +541,47 @@ async function dispatchRecord(envelope) {
     synchronous: result.synchronous
   };
 }
+async function dispatchRecord(envelope, options, handlers) {
+  try {
+    const driver = resolveConnectionDriver(envelope.connection);
+    const connection = resolveConnectionConfig(getQueueRuntimeState().config, envelope.connection);
+    const afterCommit = options.afterCommit ?? connection.afterCommit;
+    if (afterCommit && driver.acceptsJobId !== true) {
+      throw new Error(
+        `[Holo Queue] Queue connection "${envelope.connection}" uses driver "${driver.driver}", which does not accept a caller-supplied job ID, so afterCommit needs a driver that accepts the job ID.`
+      );
+    }
+    const transaction = afterCommit ? await resolveOpenDatabaseTransaction() : void 0;
+    if (transaction) {
+      transaction.afterCommit(async () => {
+        try {
+          const result = await dispatchThroughDriver(driver, envelope);
+          if (result.jobId !== envelope.id) {
+            throw new Error(
+              `[Holo Queue] Queue connection "${envelope.connection}" driver "${driver.driver}" returned job ID "${result.jobId}" for job "${envelope.id}", but it declares that it accepts the job ID.`
+            );
+          }
+          await handlers.completed(toDispatchResult(envelope, result));
+        } catch (error) {
+          await handlers.failed(error);
+          throw error;
+        }
+      });
+      return {
+        jobId: envelope.id,
+        connection: envelope.connection,
+        queue: envelope.queue,
+        synchronous: driver.mode === "sync"
+      };
+    }
+    const dispatched = toDispatchResult(envelope, await dispatchThroughDriver(driver, envelope));
+    await handlers.completed(dispatched);
+    return dispatched;
+  } catch (error) {
+    await handlers.failed(error);
+    throw error;
+  }
+}
 var PendingQueueDispatch = class _PendingQueueDispatch {
   jobName;
   payload;
@@ -713,6 +615,12 @@ var PendingQueueDispatch = class _PendingQueueDispatch {
       delay: value
     }, this.completedHooks, this.failedHooks);
   }
+  afterCommit() {
+    return new _PendingQueueDispatch(this.jobName, this.payload, {
+      ...this.options,
+      afterCommit: true
+    }, this.completedHooks, this.failedHooks);
+  }
   onComplete(callback) {
     return new _PendingQueueDispatch(
       this.jobName,
@@ -745,32 +653,38 @@ var PendingQueueDispatch = class _PendingQueueDispatch {
   }
   execute() {
     this.executionPromise ??= (async () => {
+      let envelope;
       try {
-        const envelope = createDispatchEnvelope(this.jobName, this.payload, this.options);
-        const result = await dispatchRecord(envelope);
-        for (const hook of this.completedHooks) {
-          try {
-            await hook(result);
-          } catch (error) {
-            const resolvedError = error instanceof Error ? error : new Error(String(error));
-            console.warn(`[Holo Queue] onComplete hook failed during dispatch of "${this.jobName}": ${resolvedError.message}`);
-          }
-        }
-        return result;
+        envelope = createDispatchEnvelope(this.jobName, this.payload, this.options);
       } catch (error) {
-        for (const hook of this.failedHooks) {
-          try {
-            await hook(error);
-          } catch (hookError) {
-            const resolvedError = hookError instanceof Error ? hookError : new Error(String(hookError));
-            console.warn(`[Holo Queue] onFailed hook failed during dispatch of "${this.jobName}": ${resolvedError.message}`);
-          }
-        }
+        await this.runFailedHooks(error);
         throw error;
       }
+      return dispatchRecord(envelope, { afterCommit: this.options.afterCommit }, {
+        completed: (result) => this.runCompletedHooks(result),
+        failed: (error) => this.runFailedHooks(error)
+      });
     })();
     return this.executionPromise;
   }
+  async runCompletedHooks(result) {
+    for (const hook of this.completedHooks) {
+      try {
+        await hook(result);
+      } catch (error) {
+        reportError(error, { capability: "queue", operation: "dispatch.onComplete" });
+      }
+    }
+  }
+  async runFailedHooks(error) {
+    for (const hook of this.failedHooks) {
+      try {
+        await hook(error);
+      } catch (hookError) {
+        reportError(hookError, { capability: "queue", operation: "dispatch.onFailed" });
+      }
+    }
+  }
 };
 function createQueueConnection(name) {
   const resolvedName = name ? normalizeConnectionName(name) : getQueueRuntimeState().config.default;
@@ -791,11 +705,27 @@ function createQueueConnection(name) {
     dispatchSync: dispatchSyncViaConnection
   };
 }
+function assertJobTimeoutsBelowRetryAfter(config, jobs) {
+  for (const job of jobs) {
+    const connectionName = job.definition.connection ? normalizeConnectionName(job.definition.connection) : config.default;
+    const connection = config.connections[connectionName];
+    if (!connection) {
+      continue;
+    }
+    assertQueueTimeoutBelowRetryAfter(`Queue job "${job.name}"`, job.definition.timeout, connection);
+  }
+}
+function assertQueueJobTimeouts(jobs) {
+  assertJobTimeoutsBelowRetryAfter(getQueueRuntimeState().config, jobs);
+}
+setQueueJobRegistrationTimeoutCheck((job) => assertJobTimeoutsBelowRetryAfter(getQueueRuntimeState().config, [job]));
 function configureQueueRuntime(options = {}) {
   const state = getQueueRuntimeState();
   let shouldResetDrivers = false;
   if (options.config) {
-    state.config = isNormalizedQueueConfig(options.config) ? options.config : normalizeQueueConfig(options.config, options.redisConfig);
+    const config = isNormalizedQueueConfig(options.config) ? options.config : normalizeQueueConfig(options.config, options.redisConfig);
+    assertJobTimeoutsBelowRetryAfter(config, listRegisteredQueueJobs().filter((job) => !job.sourcePath));
+    state.config = config;
     shouldResetDrivers = true;
   }
   if (options.driverFactories) {
@@ -843,7 +773,7 @@ function useQueueConnection(name) {
 }
 function dispatchSyncInternal(jobName, payload, options = {}) {
   return (async () => {
-    const envelope = createDispatchEnvelope(jobName, payload, options);
+    const envelope = createDispatchEnvelope(jobName, payload, options, { runsInline: true });
     const result = await dispatchThroughDriver(
       resolveSyncExecutionDriver(),
       envelope
@@ -1006,6 +936,7 @@ var queueFailedInternals = {
 };
 
 // src/worker.ts
+import { reportError as reportError2 } from "@holo-js/kernel/error-reporting";
 import { randomUUID as randomUUID2 } from "crypto";
 var QueueWorkerUnsupportedDriverError = class extends Error {
   constructor(connectionName, driverName) {
@@ -1028,13 +959,6 @@ function requireAsyncDriver(driver, connectionName) {
   }
   return driver;
 }
-function requireRegisteredDefinition(jobName) {
-  const registered = getRegisteredQueueJob(jobName);
-  if (!registered) {
-    throw new Error(`[Holo Queue] Queue job "${jobName}" is not registered.`);
-  }
-  return registered.definition;
-}
 function normalizeQueueNames(queueNames, fallbackQueueName) {
   if (!queueNames || queueNames.length === 0) {
     return Object.freeze([fallbackQueueName ?? DEFAULT_QUEUE_NAME]);
@@ -1045,13 +969,16 @@ function normalizeQueueNames(queueNames, fallbackQueueName) {
   }
   return Object.freeze(normalized);
 }
-function normalizeNonNegativeInteger(value, label) {
+function normalizeNonNegativeInteger(value, label, options = {}) {
   if (typeof value === "undefined") {
     return void 0;
   }
   if (!Number.isInteger(value) || value < 0) {
     throw new Error(`[Holo Queue] ${label} must be a non-negative integer.`);
   }
+  if (typeof options.maximum === "number" && value > options.maximum) {
+    throw new Error(`[Holo Queue] ${label} must be less than or equal to ${options.maximum}.`);
+  }
   return value;
 }
 function normalizePositiveInteger(value, label) {
@@ -1073,8 +1000,7 @@ function createWorkerEvent(envelope, maxAttempts) {
     maxAttempts
   };
 }
-function resolveRetryDelaySeconds(definition, attempt) {
-  const { backoff } = definition;
+function resolveRetryDelaySeconds(backoff, attempt) {
   if (typeof backoff === "undefined") {
     return void 0;
   }
@@ -1083,15 +1009,14 @@ function resolveRetryDelaySeconds(definition, attempt) {
   }
   return backoff[Math.min(Math.max(attempt - 1, 0), backoff.length - 1)];
 }
-function normalizeHookError(error) {
+function normalizeHandlerError(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
-async function runWorkerHook(jobName, hookName, callback) {
+async function runWorkerHook(hookName, callback) {
   try {
     await callback();
   } catch (error) {
-    const resolvedError = normalizeHookError(error);
-    console.warn(`[Holo Queue] ${hookName} hook failed for job "${jobName}": ${resolvedError.message}`);
+    reportError2(error, { capability: "queue", operation: `worker.${hookName}` });
   }
 }
 async function runWithTimeout(callback, jobName, timeoutSeconds, onTimeout) {
@@ -1112,11 +1037,51 @@ async function runWithTimeout(callback, jobName, timeoutSeconds, onTimeout) {
     })
   ]);
 }
+async function failReservedJob(driver, reserved, event, options, failure) {
+  const { error, runJobFailedHook } = failure;
+  await queueRuntimeInternals.getQueueRuntimeState().failedJobStore?.persistFailedJob(reserved, error);
+  await driver.delete(reserved);
+  if (runJobFailedHook) {
+    await queueRuntimeInternals.executeRegisteredQueueJobFailedHook(reserved.envelope, error, { maxAttempts: event.maxAttempts });
+  }
+  if (options.onJobFailed) {
+    await runWorkerHook("onJobFailed", async () => {
+      await options.onJobFailed?.({ ...event, error });
+    });
+  }
+  return { kind: "failed", error };
+}
 async function processReservedJob(driver, reserved, options) {
   const envelope = reserved.envelope;
-  const definition = requireRegisteredDefinition(envelope.name);
+  const registered = getRegisteredQueueJob(envelope.name);
   const maxAttempts = options.tries ?? envelope.maxAttempts;
   const event = createWorkerEvent(envelope, maxAttempts);
+  if (!registered) {
+    return await failReservedJob(driver, reserved, event, options, {
+      error: new Error(`[Holo Queue] Queue job "${envelope.name}" is not registered.`),
+      runJobFailedHook: false
+    });
+  }
+  if (event.attempt > maxAttempts) {
+    return await failReservedJob(driver, reserved, event, options, {
+      error: new Error(`[Holo Queue] Queue job "${envelope.name}" has been attempted too many times.`),
+      runJobFailedHook: true
+    });
+  }
+  const definition = registered.definition;
+  const timeoutSeconds = options.timeout ?? definition.timeout;
+  try {
+    assertQueueTimeoutBelowRetryAfter(
+      `Queue job "${envelope.name}"`,
+      timeoutSeconds,
+      queueRuntimeInternals.resolveConnectionConfig(queueRuntimeInternals.getQueueRuntimeState().config, envelope.connection)
+    );
+  } catch (error) {
+    return await failReservedJob(driver, reserved, event, options, {
+      error: normalizeHandlerError(error),
+      runJobFailedHook: true
+    });
+  }
   const executionState = {
     timedOut: false
   };
@@ -1146,19 +1111,24 @@ async function processReservedJob(driver, reserved, options) {
         }
       }),
       envelope.name,
-      options.timeout ?? definition.timeout,
+      timeoutSeconds,
       () => {
         executionState.timedOut = true;
       }
     );
   } catch (error) {
-    handlerError = normalizeHookError(error);
+    handlerError = normalizeHandlerError(error);
+  }
+  if (executionState.timedOut && handlerError) {
+    if (definition.failOnTimeout === true) {
+      await failReservedJob(driver, reserved, event, options, { error: handlerError, runJobFailedHook: true });
+    }
+    throw handlerError;
   }
-  const failure = handlerError instanceof QueueWorkerTimeoutError ? handlerError : requestedFailure ?? handlerError;
+  const failure = requestedFailure ?? handlerError;
+  const backoff = definition.backoff ?? options.backoff;
   let outcome;
-  if (handlerError instanceof QueueWorkerTimeoutError) {
-    outcome = { kind: "failed", error: handlerError };
-  } else if (action === "release") {
+  if (action === "release") {
     outcome = {
       kind: "released",
       ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {},
@@ -1167,7 +1137,7 @@ async function processReservedJob(driver, reserved, options) {
   } else if (failure) {
     outcome = action === "fail" || event.attempt >= maxAttempts ? { kind: "failed", error: failure } : {
       kind: "released",
-      delaySeconds: resolveRetryDelaySeconds(definition, event.attempt),
+      delaySeconds: resolveRetryDelaySeconds(backoff, event.attempt),
       error: failure
     };
   } else {
@@ -1176,7 +1146,7 @@ async function processReservedJob(driver, reserved, options) {
   if (outcome.kind === "released") {
     await driver.release(reserved, typeof outcome.delaySeconds === "number" ? { delaySeconds: outcome.delaySeconds } : void 0);
     if (options.onJobReleased) {
-      await runWorkerHook(envelope.name, "onJobReleased", async () => {
+      await runWorkerHook("onJobReleased", async () => {
         await options.onJobReleased?.({
           ...event,
           ...typeof outcome.delaySeconds === "number" ? { delaySeconds: outcome.delaySeconds } : {},
@@ -1185,24 +1155,24 @@ async function processReservedJob(driver, reserved, options) {
       });
     }
   } else if (outcome.kind === "failed") {
-    await queueRuntimeInternals.getQueueRuntimeState().failedJobStore?.persistFailedJob(reserved, outcome.error);
-    await driver.delete(reserved);
-    await queueRuntimeInternals.executeRegisteredQueueJobFailedHook(envelope, outcome.error, { maxAttempts });
-    if (options.onJobFailed) {
-      await runWorkerHook(envelope.name, "onJobFailed", async () => {
-        await options.onJobFailed?.({ ...event, error: outcome.error });
-      });
-    }
+    await failReservedJob(driver, reserved, event, options, { error: outcome.error, runJobFailedHook: true });
   } else {
     await driver.acknowledge(reserved);
     if (options.onJobProcessed) {
-      await runWorkerHook(envelope.name, "onJobProcessed", async () => {
+      await runWorkerHook("onJobProcessed", async () => {
         await options.onJobProcessed?.(event);
       });
     }
   }
   return outcome;
 }
+function abandonReservation(driver, reserved) {
+  try {
+    driver.abandon?.(reserved);
+  } catch (error) {
+    reportError2(error, { capability: "queue", operation: "worker.abandonReservation" });
+  }
+}
 function resolveWorkerStopReason(options, state) {
   const now = Date.now();
   if (typeof options.maxJobs === "number" && state.processed >= options.maxJobs) {
@@ -1220,7 +1190,10 @@ async function runQueueWorker(options = {}) {
     connectionName
   );
   const queueNames = normalizeQueueNames(options.queueNames, connection.queue);
-  const sleepSeconds = normalizeNonNegativeInteger(options.sleep, "Queue worker sleep") ?? ("sleep" in connection && typeof connection.sleep === "number" ? connection.sleep : 1);
+  const sleepSeconds = normalizeNonNegativeInteger(options.sleep, "Queue worker sleep", { maximum: QUEUE_TIMER_MAX_SECONDS }) ?? ("sleep" in connection && typeof connection.sleep === "number" ? connection.sleep : 1);
+  const timeout = normalizeNonNegativeInteger(options.timeout, "Queue worker timeout", { maximum: QUEUE_TIMER_MAX_SECONDS });
+  assertQueueTimeoutBelowRetryAfter("Queue worker", timeout, connection);
+  const backoff = queueJobInternals.normalizeBackoff(options.backoff);
   const maxJobs = normalizePositiveInteger(options.maxJobs, "Queue worker maxJobs");
   const maxTime = normalizePositiveInteger(options.maxTime, "Queue worker maxTime");
   const workerId = options.workerId?.trim() || randomUUID2();
@@ -1236,6 +1209,7 @@ async function runQueueWorker(options = {}) {
     maxJobs,
     maxTime
   };
+  const jobOptions = { ...options, timeout, backoff };
   while (true) {
     if (await options.shouldStop?.()) {
       return {
@@ -1286,7 +1260,10 @@ async function runQueueWorker(options = {}) {
       }
       continue;
     }
-    const outcome = await processReservedJob(driver, reserved, options);
+    const outcome = await processReservedJob(driver, reserved, jobOptions).catch((error) => {
+      abandonReservation(driver, reserved);
+      throw error;
+    });
     if (outcome.kind === "processed") {
       processed += 1;
     } else if (outcome.kind === "released") {
@@ -1319,7 +1296,6 @@ var queueWorkerInternals = {
   normalizeQueueNames,
   processReservedJob,
   requireAsyncDriver,
-  requireRegisteredDefinition,
   resolveRetryDelaySeconds,
   resolveWorkerStopReason,
   runWithTimeout,
@@ -1348,6 +1324,7 @@ export {
   QueueReleaseUnsupportedError,
   QueueWorkerTimeoutError,
   QueueWorkerUnsupportedDriverError,
+  assertQueueJobTimeouts,
   clearQueueConnection,
   configureQueueRuntime,
   defineJob,