@cap-js-community/event-queue 2.1.0 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js-community/event-queue",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "An event queue that enables secure transactional processing of asynchronous and periodic events, featuring instant event processing with Redis Pub/Sub and load distribution across all application instances.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -41,30 +41,30 @@
     "upgrade-lock": "npx shx rm -rf package-lock.json node_modules && npm i --package-lock"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || ^22.13.0 || >=24"
   },
   "dependencies": {
     "@cap-js-community/common": "^0.4.0",
     "@sap/xssec": "^4.13.0",
     "cron-parser": "^5.5.0",
     "verror": "^1.10.1",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.4"
   },
   "devDependencies": {
-    "@actions/core": "^2.0.2",
-    "@cap-js/cds-test": "^0.4.1",
-    "@cap-js/db-service": "^2.8.2",
-    "@cap-js/hana": "^2.6.0",
-    "@cap-js/sqlite": "^2.1.3",
+    "@cap-js/cds-test": "^1.0.1",
+    "@cap-js/db-service": "^2.11.0",
+    "@cap-js/hana": "^2.8.0",
+    "@cap-js/sqlite": "^2.4.0",
+    "@eslint/js": "^10.0.1",
     "@opentelemetry/api": "^1.9.1",
-    "@sap/cds": "^9.8.4",
-    "@sap/cds-dk": "^9.8.2",
-    "eslint": "^8.57.1",
+    "@sap/cds": "^9.9.1",
+    "@sap/cds-dk": "^9.9.0",
+    "eslint": "^10.3.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jest": "^29.12.1",
-    "eslint-plugin-node": "^11.1.0",
-    "jest": "^29.7.0",
-    "prettier": "^2.8.8"
+    "eslint-plugin-jest": "^29.15.2",
+    "globals": "^17.6.0",
+    "jest": "^30.3.0",
+    "prettier": "^3.8.3"
   },
   "homepage": "https://cap-js-community.github.io/event-queue/",
   "repository": {

package/src/EventQueueError.js

@@ -28,6 +28,7 @@ const ERROR_CODES = {
   APP_INSTANCES_FORMAT: "APP_INSTANCES_FORMAT",
   MULTI_INSTANCE_PROCESSING_NOT_ALLOWED: "MULTI_INSTANCE_PROCESSING_NOT_ALLOWED",
   INVALID_CLUSTER_HANDLER_RESULT: "INVALID_CLUSTER_HANDLER_RESULT",
+  INVALID_AUTH_CACHE_EXPIRY_REDUCTION_MAX_PERCENT: "INVALID_AUTH_CACHE_EXPIRY_REDUCTION_MAX_PERCENT",
 };
 
 const ERROR_CODES_META = {
@@ -107,6 +108,9 @@ const ERROR_CODES_META = {
   [ERROR_CODES.MULTI_INSTANCE_PROCESSING_NOT_ALLOWED]: {
     message: "The config multiInstanceProcessing is currently only allowed for ad-hoc events and single-tenant-apps.",
   },
+  [ERROR_CODES.INVALID_AUTH_CACHE_EXPIRY_REDUCTION_MAX_PERCENT]: {
+    message: "authCacheExpiryReductionMaxPercent must be a number between 0 and 80.",
+  },
 };
 
 class EventQueueError extends VError {
@@ -375,6 +379,17 @@ class EventQueueError extends VError {
     );
   }
 
+  static invalidAuthCacheExpiryReductionMaxPercent(value) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.INVALID_AUTH_CACHE_EXPIRY_REDUCTION_MAX_PERCENT];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.INVALID_AUTH_CACHE_EXPIRY_REDUCTION_MAX_PERCENT,
+        info: { value },
+      },
+      message
+    );
+  }
+
   static invalidClusterHandlerResult(clusterKey, propertyName) {
     const { message } = ERROR_CODES_META[ERROR_CODES.INVALID_CLUSTER_HANDLER_RESULT];
     return new EventQueueError(

package/src/EventQueueProcessorBase.js

@@ -69,7 +69,7 @@ class EventQueueProcessorBase {
       this.__parallelEventProcessing = LIMIT_PARALLEL_EVENT_PROCESSING;
     }
     this.__concurrentEventProcessing = this.#eventConfig.multiInstanceProcessing;
-    this.__retryAttempts = this.#isPeriodic ? 1 : this.#eventConfig.retryAttempts ?? DEFAULT_RETRY_ATTEMPTS;
+    this.__retryAttempts = this.#isPeriodic ? 1 : (this.#eventConfig.retryAttempts ?? DEFAULT_RETRY_ATTEMPTS);
     this.__selectMaxChunkSize = this.#eventConfig.selectMaxChunkSize ?? SELECT_LIMIT_EVENTS_PER_TICK;
     this.__selectNextChunk = !!this.#eventConfig.checkForNextChunk;
     this.__transactionMode = this.#eventConfig.transactionMode ?? TransactionMode.isolated;
@@ -457,7 +457,8 @@ class EventQueueProcessorBase {
         eventSubType: this.#eventSubType,
         statusMap,
       });
-      const ts = new Date().toISOString();
+      const tsMs = Date.now();
+      const ts = new Date(tsMs).toISOString();
       const updateData = Object.entries(statusMap).reduce((result, [id, data]) => {
         const key = this.allowedFieldsEventHandler
           .map((name) => [name, data[name]])
@@ -503,7 +504,7 @@ class EventQueueProcessorBase {
 
         if (!data.startAfter && [EventProcessingStatus.Error, EventProcessingStatus.Open].includes(data.status)) {
           data.startAfter = new Date(
-            Date.now() +
+            tsMs +
               (data.status === EventProcessingStatus.Error
                 ? this.#eventConfig.retryFailedAfter
                 : this.#eventConfig.retryOpenAfter)
@@ -954,7 +955,7 @@ class EventQueueProcessorBase {
    * the function 'addEventWithPayloadForProcessing'. This function is called after the clustering and before the
    * process-events-steps. The event data is available with this.eventProcessingMap.
    */
-  // eslint-disable-next-line no-unused-vars
+
   async beforeProcessingEvents() {}
 
   async isOutdatedAndKeepAlive() {
@@ -1109,13 +1110,15 @@ class EventQueueProcessorBase {
     }
   }
 
-  #calculateCronDates() {
+  #calculateCronDates(queueEntry) {
     if (!this.#eventConfig.cron) {
       return null;
     }
 
-    // NOTE: do not pass current date as we always want to calc. a future date
+    // NOTE: base the calculation on the planned startAfter if the event was picked up early; otherwise on now to always calc. a future date
+    const currentDate = new Date(Math.max(Date.now(), new Date(queueEntry.startAfter).getTime()));
     const cronExpression = CronExpressionParser.parse(this.#eventConfig.cron, {
+      currentDate,
       tz: this.#eventConfig.tz,
     });
     return cronExpression.next();
@@ -1123,7 +1126,7 @@ class EventQueueProcessorBase {
 
   async scheduleNextPeriodEvent(queueEntry) {
     const intervalInMs = this.#eventConfig.cron ? null : this.#eventConfig.interval * 1000;
-    const next = this.#calculateCronDates();
+    const next = this.#calculateCronDates(queueEntry);
     let newStartAfter;
 
     if (this.#eventConfig.cron) {
@@ -1166,7 +1169,8 @@ class EventQueueProcessorBase {
       })
     );
     this.tx._skipEventQueueBroadcast = false;
-    if (intervalInMs < this.#config.runInterval * 1.5) {
+    const msUntilNextOccurrence = intervalInMs ?? newEvent.startAfter.getTime() - Date.now();
+    if (msUntilNextOccurrence < this.#config.runInterval * 1.5) {
       this.#handleDelayedEvents([newEvent], { skipExcludeDelayedEventIds: true });
       const { relative: relativeAfterSchedule } = this.#eventSchedulerInstance.calculateOffset(
         this.#eventType,

package/src/config.js

@@ -90,8 +90,6 @@ class Config {
   #redisEnabled;
   #initialized;
   #instanceLoadLimit;
-  #tableNameEventQueue;
-  #tableNameEventLock;
   #isEventQueueActive;
   #configFilePath;
   #processEventsAfterPublish;
@@ -122,6 +120,7 @@ class Config {
   #disableProcessingOfSuspendedTenants;
   #namespace;
   #processingNamespaces;
+  #authCacheExpiryReductionMaxPercent;
   static #instance;
   constructor() {
     this.#logger = cds.log(COMPONENT_NAME);
@@ -132,12 +131,11 @@ class Config {
     this.#redisEnabled = null;
     this.#initialized = false;
     this.#instanceLoadLimit = 100;
-    this.#tableNameEventQueue = null;
-    this.#tableNameEventLock = null;
     this.#isEventQueueActive = true;
     this.#configFilePath = null;
     this.#processEventsAfterPublish = null;
     this.#disableRedis = null;
+    this.#authCacheExpiryReductionMaxPercent = 10;
     this.#env = getEnvInstance();
   }
 
@@ -337,6 +335,7 @@ class Config {
       (typeof cds.requires.outbox === "object" && cds.requires.outbox) || {},
       (typeof cds.requires.queue === "object" && cds.requires.queue) || {},
       (typeof cds.env.requires[serviceName]?.outbox === "object" && cds.env.requires[serviceName].outbox) || {},
+      (typeof cds.env.requires[serviceName]?.outboxed === "object" && cds.env.requires[serviceName].outboxed) || {},
       (typeof cds.env.requires[serviceName]?.queued === "object" && cds.env.requires[serviceName].queued) || {}
     );
   }
@@ -799,6 +798,17 @@ class Config {
     return this.#configFilePath;
   }
 
+  set authCacheExpiryReductionMaxPercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 80) {
+      throw EventQueueError.invalidAuthCacheExpiryReductionMaxPercent(value);
+    }
+    this.#authCacheExpiryReductionMaxPercent = value;
+  }
+
+  get authCacheExpiryReductionMaxPercent() {
+    return this.#authCacheExpiryReductionMaxPercent;
+  }
+
   set processEventsAfterPublish(value) {
     this.#processEventsAfterPublish = value;
   }

package/src/initialize.js

@@ -51,6 +51,7 @@ const CONFIG_VARS = [
   ["namespace", "default"],
   ["processingNamespaces", ["default"]],
   ["collectEventQueueMetrics", false],
+  ["authCacheExpiryReductionMaxPercent", 10],
 ];
 
 /**
@@ -81,6 +82,7 @@ const CONFIG_VARS = [
  * @param {string} [options.namespace=default] - Default namespace in which events are published
  * @param {string} [options.processingNamespaces=[default]] - Namespaces which the application processes
  * @param {boolean} [options.collectEventQueueMetrics=false] - Enable collection of event queue metrics (pending/inProgress counters) stored in Redis and exposed via OpenTelemetry gauges.
+ * @param {number} [options.authCacheExpiryReductionMaxPercent=10] - Maximum percentage (allowed range 0-80) by which the XSUAA token TTL is shortened when stored in the authContext cache. The actual reduction is randomized per token fetch in `[0, value]` so multi-tenant deployments do not all expire their cached tokens at the same time and stampede the XSUAA token endpoint. Values outside the allowed range throw on initialization.
  */
 const initialize = async (options = {}) => {
   if (config.initialized) {

package/src/shared/SetIntervalDriftSafe.js

@@ -1,20 +1,15 @@
 "use strict";
 
-const COMPONENT = "eventQueue/SetIntervalDriftSafe";
-
 class SetIntervalDriftSafe {
   #adjustedInterval;
   #interval;
   #expectedCycleTime = 0;
-  #nextTickScheduledFor;
-  #logger;
   #shouldRun = true;
   #lastTimeoutId;
 
   constructor(interval) {
     this.#interval = interval;
     this.#adjustedInterval = interval;
-    this.#logger = cds.log(COMPONENT);
   }
 
   start(fn) {
@@ -34,7 +29,6 @@ class SetIntervalDriftSafe {
       this.#adjustedInterval = this.#interval - (now - this.#expectedCycleTime);
       this.#expectedCycleTime += this.#interval;
     }
-    this.#nextTickScheduledFor = now + this.#adjustedInterval;
     const timeoutId = setTimeout(() => {
       if (!this.#shouldRun) {
         return;

package/src/shared/common.js

@@ -99,7 +99,10 @@ const _getNewAuthContext = async (tenantId) => {
     const token = await authService.fetchClientCredentialsToken({ zid: tenantId });
     const tokenInfo = new xssec.XsuaaToken(token.access_token);
     const authInfo = new xssec.XsuaaSecurityContext(authService, tokenInfo);
-    return [tokenInfo.getExpirationDate().getTime() - Date.now(), [null, authInfo]];
+    const ttl = tokenInfo.getExpirationDate().getTime() - Date.now();
+    // Randomized to avoid synchronized cache expiry across tenants stampeding XSUAA on token refresh.
+    const reductionPercent = Math.random() * config.authCacheExpiryReductionMaxPercent;
+    return [ttl * (1 - reductionPercent / 100), [null, authInfo]];
   } catch (err) {
     cds.log(COMPONENT_NAME).warn("failed to request authContext", {
       err: err.message,