@cap-js-community/event-queue 1.6.6 → 1.7.0

package/cds-plugin.js

@@ -1,10 +1,22 @@
 "use strict";
 
 const cds = require("@sap/cds");
+const cdsPackage = require("@sap/cds/package.json");
 
 const eventQueue = require("./src");
 const COMPONENT_NAME = "/eventQueue/plugin";
+const SERVE_COMMAND = "serve";
 
-if (!cds.build?.register && Object.keys(cds.env.eventQueue ?? {}).length) {
+const isServe = cds.cli?.command === SERVE_COMMAND;
+const isBuild = cds.build?.register;
+// NOTE: for sap/cds < 8.2.3 there was no consistent way to detect cds is running as a server, not for build, compile,
+//   etc...
+const doLegacyBuildDetection =
+  cdsPackage.version.localeCompare("8.2.3", undefined, { numeric: true, sensitivity: "base" }) < 0;
+if ((doLegacyBuildDetection && isBuild) || (!doLegacyBuildDetection && !isServe)) {
+  return;
+}
+
+if (Object.keys(cds.env.eventQueue ?? {}).length) {
   module.exports = eventQueue.initialize().catch((err) => cds.log(COMPONENT_NAME).error(err));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js-community/event-queue",
-  "version": "1.6.6",
+  "version": "1.7.0",
   "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",
@@ -43,22 +43,23 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@sap/xssec": "^4.2.1",
+    "@sap/xssec": "^4.2.4",
+    "cron-parser": "^4.9.0",
     "redis": "^4.7.0",
     "verror": "^1.10.1",
-    "yaml": "^2.5.0"
+    "yaml": "^2.5.1"
   },
   "devDependencies": {
-    "@cap-js/hana": "^1.1.1",
+    "@cap-js/hana": "^1.3.0",
     "@cap-js/sqlite": "^1.7.3",
-    "@sap/cds": "^8.1.0",
-    "@sap/cds-dk": "^8.1.0",
+    "@sap/cds": "^8.3.0",
+    "@sap/cds-dk": "^8.3.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-jest": "^28.6.0",
     "eslint-plugin-node": "^11.1.0",
-    "express": "^4.18.2",
-    "hdb": "^0.19.7",
+    "express": "^4.21.0",
+    "hdb": "^0.19.10",
     "jest": "^29.7.0",
     "prettier": "^2.8.8",
     "sqlite3": "^5.1.7"
@@ -74,9 +75,10 @@
         "disableRedis": false
       },
       "[test]": {
-        "registerAsEventProcessor": false,
         "isRunnerDeactivated": true,
-        "updatePeriodicEvents": false
+        "registerAsEventProcessor": false,
+        "updatePeriodicEvents": false,
+        "insertEventsBeforeCommit": false
       }
     },
     "requires": {

package/src/EventQueueError.js

@@ -13,12 +13,17 @@ const ERROR_CODES = {
   TYPE_MISMATCH_TABLE: "TYPE_MISMATCH_TABLE",
   NO_VALID_DATE: "NO_VALID_DATE",
   INVALID_INTERVAL: "INVALID_INTERVAL",
+  CANT_PARSE_CRON: "CANT_PARSE_CRON",
+  CRON_INTERVAL: "CRON_INTERVAL",
+  NO_INTERVAL_OR_CRON: "NO_INTERVAL_OR_CRON",
+  INTERVAL_AND_CRON: "INTERVAL_AND_CRON",
   MISSING_IMPL: "MISSING_IMPL",
   DUPLICATE_EVENT_REGISTRATION: "DUPLICATE_EVENT_REGISTRATION",
   NO_MANUEL_INSERT_OF_PERIODIC: "NO_MANUEL_INSERT_OF_PERIODIC",
   LOAD_HIGHER_THAN_LIMIT: "LOAD_HIGHER_THAN_LIMIT",
   NOT_ALLOWED_PRIORITY: "NOT_ALLOWED_PRIORITY",
   APP_NAMES_FORMAT: "APP_NAMES_FORMAT",
+  APP_INSTANCES_FORMAT: "APP_INSTANCES_FORMAT",
 };
 
 const ERROR_CODES_META = {
@@ -71,6 +76,21 @@ const ERROR_CODES_META = {
   [ERROR_CODES.APP_NAMES_FORMAT]: {
     message: "The app names property must be an array and only contain strings.",
   },
+  [ERROR_CODES.APP_INSTANCES_FORMAT]: {
+    message: "The app instances property must be an array and only contain numbers.",
+  },
+  [ERROR_CODES.CANT_PARSE_CRON]: {
+    message: "The cron expression is syntactically not correct and can't be parsed!",
+  },
+  [ERROR_CODES.CRON_INTERVAL]: {
+    message: "The difference between two cron execution must be greater than 10 seconds.",
+  },
+  [ERROR_CODES.NO_INTERVAL_OR_CRON]: {
+    message: "For periodic events either the cron or interval parameter must be defined!",
+  },
+  [ERROR_CODES.INTERVAL_AND_CRON]: {
+    message: "For periodic events only the cron or interval parameter can be defined!",
+  },
 };
 
 class EventQueueError extends VError {
@@ -186,6 +206,50 @@ class EventQueueError extends VError {
     );
   }
 
+  static cantParseCronExpression(type, subType, expression) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.CANT_PARSE_CRON];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.CANT_PARSE_CRON,
+        info: { type, subType, expression },
+      },
+      message
+    );
+  }
+
+  static invalidIntervalBetweenCron(type, subType, interval) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.CRON_INTERVAL];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.CRON_INTERVAL,
+        info: { type, subType, interval },
+      },
+      message
+    );
+  }
+
+  static noCronOrInterval(type, subType) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.NO_INTERVAL_OR_CRON];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.CRON_INTERVAL,
+        info: { type, subType },
+      },
+      message
+    );
+  }
+
+  static cronAndInterval(type, subType) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.INTERVAL_AND_CRON];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.INTERVAL_AND_CRON,
+        info: { type, subType },
+      },
+      message
+    );
+  }
+
   static missingImpl(type, subType) {
     const { message } = ERROR_CODES_META[ERROR_CODES.MISSING_IMPL];
     return new EventQueueError(
@@ -250,6 +314,17 @@ class EventQueueError extends VError {
       message
     );
   }
+
+  static appInstancesFormat(type, subType, appInstances) {
+    const { message } = ERROR_CODES_META[ERROR_CODES.APP_INSTANCES_FORMAT];
+    return new EventQueueError(
+      {
+        name: ERROR_CODES.APP_INSTANCES_FORMAT,
+        info: { type, subType, appInstances },
+      },
+      message
+    );
+  }
 }
 
 module.exports = EventQueueError;

package/src/EventQueueProcessorBase.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const cds = require("@sap/cds");
+const cronParser = require("cron-parser");
 
 const { executeInNewTransaction, TriggerRollback } = require("./shared/cdsHelper");
 const { EventProcessingStatus, TransactionMode } = require("./constants");
@@ -944,12 +945,27 @@ class EventQueueProcessorBase {
     }
   }
 
+  #calculateCronDates() {
+    if (!this.#eventConfig.cron) {
+      return null;
+    }
+
+    // NOTE: do not pass current date as we always want to calc. a future date
+    const cronExpression = cronParser.parseExpression(this.#eventConfig.cron, {
+      utc: this.#eventConfig.utc,
+      ...(this.#eventConfig.useCronTimezone && { tz: this.#config.cronTimezone }),
+    });
+    return cronExpression.next();
+  }
+
   async scheduleNextPeriodEvent(queueEntry) {
-    const intervalInMs = this.#eventConfig.interval * 1000;
+    const intervalInMs = this.#eventConfig.cron ? null : this.#eventConfig.interval * 1000;
+    const next = this.#calculateCronDates();
+
     const newEvent = {
       type: this.#eventType,
       subType: this.#eventSubType,
-      startAfter: new Date(new Date(queueEntry.startAfter).getTime() + intervalInMs),
+      startAfter: next ?? new Date(new Date(queueEntry.startAfter).getTime() + intervalInMs),
     };
     const { relative } = this.#eventSchedulerInstance.calculateOffset(
       this.#eventType,
@@ -958,6 +974,7 @@ class EventQueueProcessorBase {
     );
 
     // more than one interval behind - shift tick to keep up
+    // cron package always calc the next future date --> not needed for crone
     if (relative < 0 && Math.abs(relative) >= intervalInMs) {
       const plannedStartAfter = newEvent.startAfter;
       newEvent.startAfter = new Date(Date.now() + 5 * 1000);
@@ -970,7 +987,12 @@ class EventQueueProcessorBase {
     }
 
     this.tx._skipEventQueueBroadcase = true;
-    await this.tx.run(INSERT.into(this.#config.tableNameEventQueue).entries({ ...newEvent }));
+    await this.tx.run(
+      INSERT.into(this.#config.tableNameEventQueue).entries({
+        ...newEvent,
+        startAfter: newEvent.startAfter.toISOString(),
+      })
+    );
     this.tx._skipEventQueueBroadcase = false;
     if (intervalInMs < this.#config.runInterval * 1.5) {
       this.#handleDelayedEvents([newEvent]);
@@ -979,7 +1001,7 @@ class EventQueueProcessorBase {
         this.#eventSubType,
         newEvent.startAfter
       );
-      // next tick is already behind schedule --> execute direct
+      // NOTE: can only happen for interval events: next tick is already behind schedule --> execute direct
       if (relativeAfterSchedule <= 0) {
         this.logger.info("running behind schedule - executing next tick immediately", {
           eventType: this.#eventType,

package/src/config.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const cds = require("@sap/cds");
+const cronParser = require("cron-parser");
 
 const { getEnvInstance } = require("./shared/env");
 const redis = require("./shared/redis");
@@ -22,6 +23,9 @@ const COMMAND_UNBLOCK = "EVENT_QUEUE_EVENT_UNBLOCK";
 const CAP_EVENT_TYPE = "CAP_OUTBOX";
 const CAP_PARALLEL_DEFAULT = 5;
 const DELETE_TENANT_BLOCK_AFTER_MS = 5 * 60 * 1000;
+const PRIORITIES = Object.values(Priorities);
+const UTC_DEFAULT = false;
+const USE_CRON_TZ_DEFAULT = true;
 
 const BASE_PERIODIC_EVENTS = [
   {
@@ -71,6 +75,8 @@ class Config {
   #enableCAPTelemetry;
   #unsubscribeHandlers = [];
   #unsubscribedTenants = {};
+  #cronTimezone;
+  #publishEventBlockList;
   static #instance;
   constructor() {
     this.#logger = cds.log(COMPONENT_NAME);
@@ -110,7 +116,27 @@ class Config {
 
   shouldBeProcessedInThisApplication(type, subType) {
     const config = this.#eventMap[this.generateKey(type, subType)];
-    return !config._appNameMap || config._appNameMap[this.#env.applicationName];
+    const appNameConfig = config._appNameMap;
+    const appInstanceConfig = config._appInstancesMap;
+    if (!appNameConfig && !appInstanceConfig) {
+      return true;
+    }
+
+    if (appNameConfig) {
+      const shouldBeProcessedBasedOnAppName = appNameConfig[this.#env.applicationName];
+      if (!shouldBeProcessedBasedOnAppName) {
+        return false;
+      }
+    }
+
+    if (appInstanceConfig) {
+      const shouldBeProcessedBasedOnAppInstance = appInstanceConfig[this.#env.applicationInstance];
+      if (!shouldBeProcessedBasedOnAppInstance) {
+        return false;
+      }
+    }
+
+    return true;
   }
 
   checkRedisEnabled() {
@@ -215,7 +241,7 @@ class Config {
     }
     const key = this.generateKey(typeWithSuffix, subType);
     this.#blockEventLocalState(key, tenant);
-    if (!this.redisEnabled) {
+    if (!this.redisEnabled || !this.publishEventBlockList) {
       return;
     }
 
@@ -282,12 +308,11 @@ class Config {
       checkForNextChunk: config.checkForNextChunk,
       deleteFinishedEventsAfterDays: config.deleteFinishedEventsAfterDays,
       appNames: config.appNames,
+      appInstances: config.appInstances,
       useEventQueueUser: config.useEventQueueUser,
       internalEvent: true,
     };
-    eventConfig._appNameMap = eventConfig.appNames
-      ? Object.fromEntries(new Map(eventConfig.appNames.map((a) => [a, true])))
-      : null;
+    this.#basicEventTransformationAfterValidate(eventConfig);
     this.#config.events.push(eventConfig);
     this.#eventMap[this.generateKey(CAP_EVENT_TYPE, serviceName)] = eventConfig;
   }
@@ -324,55 +349,109 @@ class Config {
     config.events = config.events ?? [];
     config.periodicEvents = (config.periodicEvents ?? []).concat(BASE_PERIODIC_EVENTS.map((event) => ({ ...event })));
     this.#eventMap = config.events.reduce((result, event) => {
-      event.load = event.load ?? DEFAULT_LOAD;
-      event.priority = event.priority ?? DEFAULT_PRIORITY;
-      this.validateAdHocEvents(result, event);
-      event._appNameMap = event.appNames ? Object.fromEntries(new Map(event.appNames.map((a) => [a, true]))) : null;
+      this.#basicEventTransformation(event);
+      this.#validateAdHocEvents(result, event);
+      this.#basicEventTransformationAfterValidate(event);
       result[this.generateKey(event.type, event.subType)] = event;
       return result;
     }, {});
     this.#eventMap = config.periodicEvents.reduce((result, event) => {
-      event.load = event.load ?? DEFAULT_LOAD;
       event.priority = event.priority ?? DEFAULT_PRIORITY;
       event.type = `${event.type}${SUFFIX_PERIODIC}`;
       event.isPeriodic = true;
-      this.validatePeriodicConfig(result, event);
-      event._appNameMap = event.appNames ? Object.fromEntries(new Map(event.appNames.map((a) => [a, true]))) : null;
+      this.#basicEventTransformation(event);
+      this.#validatePeriodicConfig(result, event);
+      this.#basicEventTransformationAfterValidate(event);
       result[this.generateKey(event.type, event.subType)] = event;
       return result;
     }, this.#eventMap);
   }
 
-  validatePeriodicConfig(eventMap, config) {
-    const key = this.generateKey(config.type, config.subType);
-    if (eventMap[key] && eventMap[key].isPeriodic) {
-      throw EventQueueError.duplicateEventRegistration(config.type, config.subType);
+  #basicEventTransformation(event) {
+    event.load = event.load ?? DEFAULT_LOAD;
+    event.priority = event.priority ?? DEFAULT_PRIORITY;
+  }
+
+  #basicEventTransformationAfterValidate(event) {
+    event._appNameMap = event.appNames ? Object.fromEntries(new Map(event.appNames.map((a) => [a, true]))) : null;
+    event._appInstancesMap = event.appInstances
+      ? Object.fromEntries(new Map(event.appInstances.map((a) => [a, true])))
+      : null;
+  }
+
+  #basicEventValidation(event) {
+    if (!event.impl) {
+      throw EventQueueError.missingImpl(event.type, event.subType);
     }
 
-    if (!config.interval || config.interval <= MIN_INTERVAL_SEC) {
-      throw EventQueueError.invalidInterval(config.type, config.subType, config.interval);
+    if (event.appNames) {
+      if (!Array.isArray(event.appNames) || event.appNames.some((appName) => typeof appName !== "string")) {
+        throw EventQueueError.appNamesFormat(event.type, event.subType, event.appNames);
+      }
     }
 
-    if (!config.impl) {
-      throw EventQueueError.missingImpl(config.type, config.subType);
+    if (event.appInstances) {
+      if (
+        !Array.isArray(event.appInstances) ||
+        event.appInstances.some((appInstance) => typeof appInstance !== "number")
+      ) {
+        throw EventQueueError.appInstancesFormat(event.type, event.subType, event.appInstances);
+      }
+    }
+
+    if (!PRIORITIES.includes(event.priority)) {
+      throw EventQueueError.priorityNotAllowed(event.priority, "initEvent");
+    }
+
+    if (event.load > this.#instanceLoadLimit) {
+      throw EventQueueError.loadHigherThanLimit(event.load, "initEvent");
     }
   }
 
-  validateAdHocEvents(eventMap, config) {
-    const key = this.generateKey(config.type, config.subType);
-    if (eventMap[key] && !eventMap[key].isPeriodic) {
-      throw EventQueueError.duplicateEventRegistration(config.type, config.subType);
+  #validatePeriodicConfig(eventMap, event) {
+    const key = this.generateKey(event.type, event.subType);
+    if (eventMap[key] && eventMap[key].isPeriodic) {
+      throw EventQueueError.duplicateEventRegistration(event.type, event.subType);
     }
 
-    if (!config.impl) {
-      throw EventQueueError.missingImpl(config.type, config.subType);
+    if (!event.cron && !event.interval) {
+      throw EventQueueError.noCronOrInterval(event.type, event.subType);
     }
 
-    if (config.appNames) {
-      if (!Array.isArray(config.appNames) || config.appNames.some((appName) => typeof appName !== "string")) {
-        throw EventQueueError.appNamesFormat(config.type, config.subType, config.appNames);
+    if (event.cron && event.interval) {
+      throw EventQueueError.cronAndInterval(event.type, event.subType);
+    }
+
+    if (event.cron) {
+      let cron;
+      event.utc = event.utc ?? UTC_DEFAULT;
+      event.useCronTimezone = event.useCronTimezone ?? USE_CRON_TZ_DEFAULT;
+      try {
+        cron = cronParser.parseExpression(event.cron);
+      } catch {
+        throw EventQueueError.cantParseCronExpression(event.type, event.subType, event.cron);
       }
+      const next = cron.next();
+      const afterNext = cron.next();
+      const diffInSeconds = (afterNext.getTime() - next.getTime()) / 1000;
+      if (diffInSeconds <= MIN_INTERVAL_SEC) {
+        throw EventQueueError.invalidIntervalBetweenCron(event.type, event.subType, diffInSeconds);
+      }
+      return this.#basicEventValidation(event);
+    }
+
+    if (!event.interval || event.interval <= MIN_INTERVAL_SEC) {
+      throw EventQueueError.invalidInterval(event.type, event.subType, event.interval);
     }
+    this.#basicEventValidation(event);
+  }
+
+  #validateAdHocEvents(eventMap, event) {
+    const key = this.generateKey(event.type, event.subType);
+    if (eventMap[key] && !eventMap[key].isPeriodic) {
+      throw EventQueueError.duplicateEventRegistration(event.type, event.subType);
+    }
+    this.#basicEventValidation(event);
   }
 
   generateKey(type, subType) {
@@ -423,6 +502,14 @@ class Config {
     this.#forUpdateTimeout = value;
   }
 
+  get publishEventBlockList() {
+    return this.#publishEventBlockList;
+  }
+
+  set publishEventBlockList(value) {
+    this.#publishEventBlockList = value;
+  }
+
   set globalTxTimeout(value) {
     this.#globalTxTimeout = value;
   }
@@ -454,6 +541,14 @@ class Config {
     this.#initialized = value;
   }
 
+  get cronTimezone() {
+    return this.#cronTimezone;
+  }
+
+  set cronTimezone(value) {
+    this.#cronTimezone = value;
+  }
+
   get instanceLoadLimit() {
     return this.#instanceLoadLimit;
   }

package/src/index.d.ts

@@ -106,6 +106,11 @@ interface EventEntityPublish {
   payload?: string;
 }
 
+interface EventTriggerProcessing {
+  type: string;
+  subType: string;
+}
+
 interface QueueEntriesPayloadMap {
   [key: string]: {
     queueEntry: EventEntity;
@@ -163,6 +168,12 @@ export function processEventQueue(
   startTime: Date
 ): Promise<any>;
 
+export function triggerEventProcessingRedis(
+  tenantId: string,
+  events: EventTriggerProcessing[],
+  forceBroadcast?: boolean
+): Promise<any>;
+
 declare class Config {
   constructor();
 

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 
-// TODO: add tests for config --> similar to csn check
+const redisPubSub = require("./redis/redisPub");
 
 module.exports = {
   ...require("./initialize"),
@@ -11,4 +11,5 @@ module.exports = {
   ...require("./publishEvent"),
   EventQueueProcessorBase: require("./EventQueueProcessorBase"),
   WorkerQueue: require("./shared/WorkerQueue"),
+  triggerEventProcessingRedis: redisPubSub.broadcastEvent,
 };

package/src/initialize.js

@@ -35,47 +35,40 @@ const CONFIG_VARS = [
   ["userId", null],
   ["cleanupLocksAndEventsForDev", false],
   ["redisOptions", {}],
-  ["insertEventsBeforeCommit", false],
+  ["insertEventsBeforeCommit", true],
   ["enableCAPTelemetry", false],
+  ["defaultTimezoneForCron", null],
+  ["publishEventBlockList", true],
 ];
 
-const initialize = async ({
-  configFilePath,
-  registerAsEventProcessor,
-  processEventsAfterPublish,
-  isEventQueueActive,
-  runInterval,
-  disableRedis,
-  updatePeriodicEvents,
-  thresholdLoggingEventProcessing,
-  useAsCAPOutbox,
-  userId,
-  cleanupLocksAndEventsForDev,
-  redisOptions,
-  insertEventsBeforeCommit,
-  enableCAPTelemetry,
-} = {}) => {
+/**
+ * Initializes the event queue with the provided options.
+ *
+ * @param {Object} options - The configuration options.
+ * @param {string} [options.configFilePath=null] - Path to the configuration file.
+ * @param {boolean} [options.registerAsEventProcessor=true] - Register the instance as an event processor.
+ * @param {boolean} [options.processEventsAfterPublish=true] - Process events immediately after publishing.
+ * @param {boolean} [options.isEventQueueActive=true] - Flag to activate/deactivate the event queue.
+ * @param {number} [options.runInterval=1500000] - Interval for running event queue processing (in milliseconds).
+ * @param {boolean} [options.disableRedis=true] - Disable Redis usage for event handling.
+ * @param {boolean} [options.updatePeriodicEvents=true] - Automatically update periodic events.
+ * @param {number} [options.thresholdLoggingEventProcessing=50] - Threshold for logging event processing time (in milliseconds).
+ * @param {boolean} [options.useAsCAPOutbox=false] - Use the event queue as a CAP Outbox.
+ * @param {string} [options.userId=null] - ID of the user initiating the process.
+ * @param {boolean} [options.cleanupLocksAndEventsForDev=false] - Cleanup locks and events for development environments.
+ * @param {Object} [options.redisOptions={}] - Configuration options for Redis.
+ * @param {boolean} [options.insertEventsBeforeCommit=true] - Insert events into the queue before committing the transaction.
+ * @param {boolean} [options.enableCAPTelemetry=false] - Enable telemetry for CAP.
+ * @param {string} [options.defaultTimezoneForCron=null] - Default timezone for cron jobs.
+ * @param {string} [options.publishEventBlockList=true] - If redis is available event blocklist is distributed to all application instances
+ */
+const initialize = async (options = {}) => {
   if (config.initialized) {
     return;
   }
   config.initialized = true;
 
-  mixConfigVarsWithEnv(
-    configFilePath,
-    registerAsEventProcessor,
-    processEventsAfterPublish,
-    isEventQueueActive,
-    runInterval,
-    disableRedis,
-    updatePeriodicEvents,
-    thresholdLoggingEventProcessing,
-    useAsCAPOutbox,
-    userId,
-    cleanupLocksAndEventsForDev,
-    redisOptions,
-    insertEventsBeforeCommit,
-    enableCAPTelemetry
-  );
+  mixConfigVarsWithEnv(options);
 
   const logger = cds.log(COMPONENT);
   const redisEnabled = config.checkRedisEnabled();
@@ -167,9 +160,9 @@ const monkeyPatchCAPOutbox = () => {
   }
 };
 
-const mixConfigVarsWithEnv = (...args) => {
-  CONFIG_VARS.forEach(([configName, defaultValue], index) => {
-    const configValue = args[index];
+const mixConfigVarsWithEnv = (options) => {
+  CONFIG_VARS.forEach(([configName, defaultValue]) => {
+    const configValue = options[configName];
     config[configName] = configValue ?? cds.env.eventQueue?.[configName] ?? defaultValue;
   });
 };

package/src/outbox/eventQueueAsOutbox.js

@@ -7,10 +7,9 @@ const config = require("../config");
 
 const OUTBOXED = Symbol("outboxed");
 const UNBOXED = Symbol("unboxed");
-
 const CDS_EVENT_TYPE = "CAP_OUTBOX";
-
 const COMPONENT_NAME = "/eventQueue/eventQueueAsOutbox";
+const EVENT_QUEUE_SPECIFIC_FIELDS = ["startAfter", "referenceEntity", "referenceEntityKey"];
 
 function outboxed(srv, customOpts) {
   // outbox max. once
@@ -74,12 +73,14 @@ function unboxed(srv) {
 }
 
 const _mapToEventAndPublish = async (context, name, req) => {
-  let startAfter;
+  const eventQueueSpecificValues = {};
   for (const header in req.headers ?? {}) {
-    if (header.toLocaleLowerCase() === "x-eventqueue-startafter") {
-      startAfter = req.headers[header];
-      delete req.headers[header];
-      break;
+    for (const field of EVENT_QUEUE_SPECIFIC_FIELDS) {
+      if (header.toLocaleLowerCase() === `x-eventqueue-${field.toLocaleLowerCase()}`) {
+        eventQueueSpecificValues[field] = req.headers[header];
+        delete req.headers[header];
+        break;
+      }
     }
   }
   const event = {
@@ -96,7 +97,7 @@ const _mapToEventAndPublish = async (context, name, req) => {
     type: CDS_EVENT_TYPE,
     subType: name,
     payload: JSON.stringify(event),
-    ...(startAfter && { startAfter }),
+    ...eventQueueSpecificValues,
   });
 };
 

package/src/periodicEvents.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const cds = require("@sap/cds");
+const cronParser = require("cron-parser");
 
 const { EventProcessingStatus } = require("./constants");
 const { processChunkedSync } = require("./shared/common");
@@ -10,6 +11,7 @@ const COMPONENT_NAME = "/eventQueue/periodicEvents";
 const CHUNK_SIZE_INSERT_PERIODIC_EVENTS = 4;
 
 const checkAndInsertPeriodicEvents = async (context) => {
+  const now = new Date();
   const tx = cds.tx(context);
   const baseCqn = SELECT.from(eventConfig.tableNameEventQueue)
     .where([
@@ -27,12 +29,15 @@ const checkAndInsertPeriodicEvents = async (context) => {
         list: [{ val: EventProcessingStatus.Open }, { val: EventProcessingStatus.InProgress }],
       },
     ])
-    .columns(["ID", "type", "subType", "startAfter"]);
+    .groupBy("type", "subType", "createdAt")
+    .columns(["type", "subType", "createdAt", "max(startAfter) as startAfter"]);
   const currentPeriodEvents = await tx.run(baseCqn);
+  currentPeriodEvents.length &&
+    (await tx.run(_addWhere(SELECT.from(eventConfig.tableNameEventQueue).columns("ID"), currentPeriodEvents)));
 
   if (!currentPeriodEvents.length) {
     // fresh insert all
-    return await insertPeriodEvents(tx, eventConfig.periodicEvents);
+    return await _insertPeriodEvents(tx, eventConfig.periodicEvents, now);
   }
 
   const exitingEventMap = currentPeriodEvents.reduce((result, current) => {
@@ -41,26 +46,27 @@ const checkAndInsertPeriodicEvents = async (context) => {
     return result;
   }, {});
 
-  const { newEvents, existingEvents } = eventConfig.periodicEvents.reduce(
+  const { newEvents, existingEventsCron, existingEventsInterval } = eventConfig.periodicEvents.reduce(
     (result, event) => {
-      if (exitingEventMap[_generateKey(event)]) {
-        result.existingEvents.push(exitingEventMap[_generateKey(event)]);
+      const existingEvent = exitingEventMap[_generateKey(event)];
+      if (existingEvent) {
+        const config = eventConfig.getEventConfig(existingEvent.type, existingEvent.subType);
+        if (config.cron) {
+          result.existingEventsCron.push(exitingEventMap[_generateKey(event)]);
+        } else {
+          result.existingEventsInterval.push(exitingEventMap[_generateKey(event)]);
+        }
       } else {
         result.newEvents.push(event);
       }
       return result;
     },
-    { newEvents: [], existingEvents: [] }
+    { newEvents: [], existingEventsCron: [], existingEventsInterval: [] }
   );
 
-  const currentDate = new Date();
-  const exitingWithNotMatchingInterval = existingEvents.filter((existingEvent) => {
-    const config = eventConfig.getEventConfig(existingEvent.type, existingEvent.subType);
-    const eventStartAfter = new Date(existingEvent.startAfter);
-    // check if to far in future
-    const dueInWithNewInterval = new Date(currentDate.getTime() + config.interval * 1000);
-    return eventStartAfter >= dueInWithNewInterval;
-  });
+  const exitingWithNotMatchingInterval = []
+    .concat(_determineChangedInterval(existingEventsInterval, now))
+    .concat(_determineChangedCron(existingEventsCron, now));
 
   exitingWithNotMatchingInterval.length &&
     cds.log(COMPONENT_NAME).info("deleting periodic events because they have changed", {
@@ -68,12 +74,14 @@ const checkAndInsertPeriodicEvents = async (context) => {
     });
 
   if (exitingWithNotMatchingInterval.length) {
-    await tx.run(
-      DELETE.from(eventConfig.tableNameEventQueue).where(
-        "ID IN",
-        exitingWithNotMatchingInterval.map(({ ID }) => ID)
-      )
-    );
+    const cqnBase = DELETE.from(eventConfig.tableNameEventQueue);
+    _addWhere(cqnBase, exitingWithNotMatchingInterval);
+    const deleteCount = await tx.run(cqnBase);
+    if (deleteCount !== exitingWithNotMatchingInterval.length) {
+      cds.log(COMPONENT_NAME).warn("deletion count doesn't match expected count", {
+        deleteCount,
+      });
+    }
   }
 
   const newOrChangedEvents = newEvents.concat(exitingWithNotMatchingInterval);
@@ -82,31 +90,74 @@ const checkAndInsertPeriodicEvents = async (context) => {
     return;
   }
 
-  return await insertPeriodEvents(tx, newOrChangedEvents);
+  return await _insertPeriodEvents(tx, newOrChangedEvents, now);
+};
+
+const _addWhere = (cqnBase, events) => {
+  let or = false;
+  for (const { type, subType, createdAt, startAfter } of events) {
+    cqnBase[or ? "or" : "where"]({ type, subType, createdAt, startAfter });
+    or = true;
+  }
+  return cqnBase;
+};
+
+const _determineChangedInterval = (existingEvents, currentDate) => {
+  return existingEvents.filter((existingEvent) => {
+    const config = eventConfig.getEventConfig(existingEvent.type, existingEvent.subType);
+    const eventStartAfter = new Date(existingEvent.startAfter);
+    // check if too far in future
+    const dueInWithNewInterval = new Date(currentDate.getTime() + config.interval * 1000);
+    return eventStartAfter >= dueInWithNewInterval;
+  });
+};
+
+const _determineChangedCron = (existingEventsCron) => {
+  return existingEventsCron.filter((event) => {
+    const config = eventConfig.getEventConfig(event.type, event.subType);
+    const eventStartAfter = new Date(event.startAfter);
+    const eventCreatedAt = new Date(event.createdAt);
+    const cronExpression = cronParser.parseExpression(config.cron, {
+      currentDate: eventCreatedAt,
+      utc: config.utc,
+      ...(config.useCronTimezone && { tz: eventConfig.cronTimezone }),
+    });
+    return cronExpression.next().getTime() - eventStartAfter.getTime() > 30 * 1000; // report as changed if diff created than 30 seconds
+  });
 };
 
-const insertPeriodEvents = async (tx, events) => {
-  const startAfter = new Date();
+const _insertPeriodEvents = async (tx, events, now) => {
   let counter = 1;
   const chunks = Math.ceil(events.length / CHUNK_SIZE_INSERT_PERIODIC_EVENTS);
   const logger = cds.log(COMPONENT_NAME);
-  processChunkedSync(events, CHUNK_SIZE_INSERT_PERIODIC_EVENTS, (chunk) => {
+  const eventsToBeInserted = events.map((event) => {
+    const base = { type: event.type, subType: event.subType };
+    let startTime = now;
+    if (event.cron) {
+      startTime = cronParser
+        .parseExpression(event.cron, {
+          currentDate: now,
+          utc: event.utc,
+          ...(event.useCronTimezone && { tz: eventConfig.cronTimezone }),
+        })
+        .next();
+    }
+    base.startAfter = startTime.toISOString();
+    return base;
+  }, []);
+
+  processChunkedSync(eventsToBeInserted, CHUNK_SIZE_INSERT_PERIODIC_EVENTS, (chunk) => {
     logger.info(`${counter}/${chunks} | inserting chunk of changed or new periodic events`, {
-      events: chunk.map(({ type, subType }) => {
+      events: chunk.map(({ type, subType, startAfter }) => {
         const { interval } = eventConfig.getEventConfig(type, subType);
-        return { type, subType, interval };
+        return { type, subType, interval, ...(startAfter && { startAfter }) };
       }),
     });
     counter++;
   });
-  const periodEventsInsert = events.map((periodicEvent) => ({
-    type: periodicEvent.type,
-    subType: periodicEvent.subType,
-    startAfter: startAfter,
-  }));
 
   tx._skipEventQueueBroadcase = true;
-  await tx.run(INSERT.into(eventConfig.tableNameEventQueue).entries(periodEventsInsert));
+  await tx.run(INSERT.into(eventConfig.tableNameEventQueue).entries(eventsToBeInserted));
   tx._skipEventQueueBroadcase = false;
 };
 

package/src/redis/redisPub.js

@@ -18,7 +18,37 @@ const SLEEP_TIME_FOR_PUBLISH_PERIODIC_EVENT = 30 * 1000;
 
 const wait = promisify(setTimeout);
 
-const broadcastEvent = async (tenantId, events) => {
+/**
+ * Broadcasts events to the event queue, either locally or through Redis.
+ *
+ * This function checks if the event queue is active before proceeding to broadcast the events.
+ * If the event queue is deactivated, broadcasting is skipped. If Redis is not enabled,
+ * events will be processed locally without Redis. The function handles periodic events
+ * by checking for locks and only publishing when locks are available.
+ *
+ * @async
+ * @param {string} tenantId - The ID of the tenant for which the events are being broadcasted.
+ * @param {Array<{ type: string; subType: string }>} events - An array of event objects, each containing
+ *        a type and a subtype that specify the kind of event to be broadcasted.
+ * @param {boolean} [forceBroadcast=false] - If true, forces the broadcast of periodic events even
+ *        when locks are not available. Defaults to false.
+ * @returns {Promise<void>} A promise that resolves when the events have been successfully broadcasted.
+ *
+ * @throws {Error} Throws an error if publishing events fails.
+ *
+ * @example
+ * // Example usage of broadcastEvent function
+ * const tenantId = '12345';
+ * const events = [
+ *   { type: 'orderCreated', subType: 'online' },
+ *   { type: 'paymentProcessed', subType: 'creditCard' }
+ * ];
+ *
+ * broadcastEvent(tenantId, events)
+ *   .then(() => console.log('Events broadcasted successfully!'))
+ *   .catch(err => console.error('Failed to broadcast events:', err));
+ */
+const broadcastEvent = async (tenantId, events, forceBroadcast = false) => {
   const logger = cds.log(COMPONENT_NAME);
 
   if (!config.isEventQueueActive) {
@@ -46,7 +76,7 @@ const broadcastEvent = async (tenantId, events) => {
                 isPeriodic: eventConfig.isPeriodic,
                 waitInterval: SLEEP_TIME_FOR_PUBLISH_PERIODIC_EVENT,
               });
-              if (!eventConfig.isPeriodic) {
+              if (!eventConfig.isPeriodic && !forceBroadcast) {
                 break;
               }
               await wait(SLEEP_TIME_FOR_PUBLISH_PERIODIC_EVENT);

package/src/runner/openEvents.js

@@ -5,7 +5,7 @@ const cds = require("@sap/cds");
 const eventConfig = require("../config");
 const { EventProcessingStatus } = require("../constants");
 
-const getOpenQueueEntries = async (tx) => {
+const getOpenQueueEntries = async (tx, filterAppSpecificEvents = true) => {
   const startTime = new Date();
   const refDateStartAfter = new Date(startTime.getTime() + eventConfig.runInterval * 1.2);
   const entries = await tx.run(
@@ -37,14 +37,25 @@ const getOpenQueueEntries = async (tx) => {
             return;
           }
           cds.outboxed(service);
-          if (eventConfig.shouldBeProcessedInThisApplication(type, subType)) {
+          if (filterAppSpecificEvents) {
+            if (eventConfig.shouldBeProcessedInThisApplication(type, subType)) {
+              result.push({ type, subType });
+            }
+          } else {
             result.push({ type, subType });
           }
         })
         .catch(() => {});
     } else {
-      if (eventConfig.getEventConfig(type, subType) && eventConfig.shouldBeProcessedInThisApplication(type, subType)) {
-        result.push({ type, subType });
+      if (filterAppSpecificEvents) {
+        if (
+          eventConfig.getEventConfig(type, subType) &&
+          eventConfig.shouldBeProcessedInThisApplication(type, subType)
+        ) {
+          result.push({ type, subType });
+        }
+      } else {
+        eventConfig.getEventConfig(type, subType) && result.push({ type, subType });
       }
     }
   }

package/src/runner/runner.js

@@ -134,7 +134,7 @@ const _executeEventsAllTenantsRedis = async (tenantIds) => {
               id: config.userId,
               authInfo: await common.getAuthInfo(tenantId),
             });
-            const entries = await openEvents.getOpenQueueEntries(tx);
+            const entries = await openEvents.getOpenQueueEntries(tx, false);
             logger.info("broadcasting events for run", {
               tenantId,
               entries: entries.length,

package/src/shared/env.js

@@ -5,6 +5,7 @@ let instance;
 class Env {
   #vcapServices;
   #vcapApplication;
+  #vcapApplicationInstance;
 
   constructor() {
     try {
@@ -14,6 +15,7 @@ class Env {
       this.#vcapServices = {};
       this.#vcapApplication = {};
     }
+    this.#vcapApplicationInstance = Number(process.env.CF_INSTANCE_INDEX);
   }
 
   get redisCredentialsFromEnv() {
@@ -24,6 +26,10 @@ class Env {
     return this.#vcapApplication.application_name;
   }
 
+  get applicationInstance() {
+    return this.#vcapApplicationInstance;
+  }
+
   set vcapServices(value) {
     this.#vcapServices = value;
   }
@@ -32,6 +38,10 @@ class Env {
     return this.#vcapServices;
   }
 
+  set applicationInstance(value) {
+    this.#vcapApplicationInstance = value;
+  }
+
   set vcapApplication(value) {
     this.#vcapApplication = value;
   }