cds-caching 1.2.1 → 1.3.0

package/lib/support/RuntimeConfigurationManager.js

@@ -1,4 +1,6 @@
 const cds = require('@sap/cds');
+const { isMultitenantMode, hasTenantContext } = require('./MultitenancyDetector');
+const { isPluginModelAvailable } = require('../util');
 
 /**
  * Manages runtime configuration for cache services
@@ -10,25 +12,50 @@ class RuntimeConfigurationManager {
         this.options = options;
     }
 
+    /**
+     * Resolve the effective keyManagement settings.
+     * In MTX mode, isTenantAware defaults to true unless explicitly set to false.
+     * @returns {object} keyManagement object
+     * @private
+     */
+    _resolveKeyManagement() {
+        const keyManagementConfig = this.options?.keyManagement || {};
+        return {
+            isUserAware: keyManagementConfig.isUserAware === true,
+            isTenantAware: keyManagementConfig.isTenantAware !== undefined
+                ? keyManagementConfig.isTenantAware === true
+                : isMultitenantMode(),
+            isLocaleAware: keyManagementConfig.isLocaleAware === true
+        };
+    }
+
     /**
      * Load runtime configuration from database and package.json
      * @returns {Promise<object>} Configuration object
      */
     async loadRuntimeConfiguration() {
+        const keyManagement = this._resolveKeyManagement();
+
+        if (!isPluginModelAvailable()) {
+            return { enableKeyTracking: false, enableStatistics: false, keyManagement };
+        }
+
+        // In MTX mode without tenant context, skip DB access — return defaults
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.info(`Loading runtime configuration for cache ${this.cacheName} (MTX mode, no tenant context — using defaults)`);
+            return {
+                enableKeyTracking: false,
+                enableStatistics: false,
+                keyManagement
+            };
+        }
+
         try {
             this.log.info(`Loading runtime configuration for cache ${this.cacheName}...`);
 
             const cacheConfig = await SELECT.one.from("plugin_cds_caching_Caches")
                 .where({ name: this.cacheName });
 
-            // Get key management configuration from package.json options (defaults to false)
-            const keyManagementConfig = this.options?.keyManagement || {};
-            const keyManagement = {
-                isUserAware: keyManagementConfig.isUserAware === true, // Default to false
-                isTenantAware: keyManagementConfig.isTenantAware === true, // Default to false
-                isLocaleAware: keyManagementConfig.isLocaleAware === true // Default to false
-            };
-
             if (cacheConfig) {
                 return {
                     enableKeyTracking: cacheConfig.enableKeyTracking || false,
@@ -48,11 +75,7 @@ class RuntimeConfigurationManager {
             return {
                 enableKeyTracking: false,
                 enableStatistics: false,
-                keyManagement: {
-                    isUserAware: false,
-                    isTenantAware: false,
-                    isLocaleAware: false
-                }
+                keyManagement
             };
         }
     }
@@ -62,6 +85,11 @@ class RuntimeConfigurationManager {
      * @param {boolean} enabled - Whether metrics should be enabled
      */
     async setMetricsEnabled(enabled) {
+        if (!isPluginModelAvailable()) return;
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping setMetricsEnabled in MTX mode (no tenant context)`);
+            return;
+        }
         await UPDATE('plugin_cds_caching_Caches')
             .set({ metricsEnabled: enabled })
             .where({ name: this.cacheName });
@@ -74,6 +102,11 @@ class RuntimeConfigurationManager {
      * @param {boolean} enabled - Whether key metrics should be enabled
      */
     async setKeyMetricsEnabled(enabled) {
+        if (!isPluginModelAvailable()) return;
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping setKeyMetricsEnabled in MTX mode (no tenant context)`);
+            return;
+        }
         await UPDATE('plugin_cds_caching_Caches')
             .set({ keyMetricsEnabled: enabled })
             .where({ name: this.cacheName });
@@ -88,18 +121,26 @@ class RuntimeConfigurationManager {
      * @returns {Promise<object>} Current configuration
      */
     async getRuntimeConfiguration() {
+        const keyManagement = this._resolveKeyManagement();
+
+        if (!isPluginModelAvailable()) {
+            return { metricsEnabled: false, keyMetricsEnabled: false, keyManagement, throwOnErrors: this.options.throwOnErrors };
+        }
+
+        // In MTX mode without tenant context, skip DB access — return defaults
+        if (isMultitenantMode() && !hasTenantContext()) {
+            return {
+                metricsEnabled: false,
+                keyMetricsEnabled: false,
+                keyManagement,
+                throwOnErrors: this.options.throwOnErrors
+            };
+        }
+
         try {
             const cacheConfig = await SELECT.one.from("plugin_cds_caching_Caches")
                 .where({ name: this.cacheName });
 
-            // Get key management configuration from package.json options (defaults to false)
-            const keyManagementConfig = this.options?.keyManagement || {};
-            const keyManagement = {
-                isUserAware: keyManagementConfig.isUserAware === true,
-                isTenantAware: keyManagementConfig.isTenantAware === true,
-                isLocaleAware: keyManagementConfig.isLocaleAware === true
-            };
-
             return {
                 metricsEnabled: cacheConfig?.metricsEnabled === true || cacheConfig?.metricsEnabled === 1 || false,
                 keyMetricsEnabled: cacheConfig?.keyMetricsEnabled === true || cacheConfig?.keyMetricsEnabled === 1 || false,
@@ -111,36 +152,27 @@ class RuntimeConfigurationManager {
             return {
                 metricsEnabled: false,
                 keyMetricsEnabled: false,
-                keyManagement: {
-                    isUserAware: false,
-                    isTenantAware: false,
-                    isLocaleAware: false
-                },
+                keyManagement,
                 throwOnErrors: this.options.throwOnErrors
             };
         }
     }
 
     /**
-     * Get default key template based on runtime configuration
+     * Get default key template based on runtime configuration.
+     * In MTX mode, isTenantAware is automatically enabled unless explicitly disabled.
      * @returns {string} Default template string
      */
     getDefaultKeyTemplate() {
-        // Get key management configuration from package.json options (defaults to false)
-        const keyManagementConfig = this.options?.keyManagement || {};
-        const keyManagement = {
-            isUserAware: keyManagementConfig.isUserAware === true, // Default to false
-            isTenantAware: keyManagementConfig.isTenantAware === true, // Default to false
-            isLocaleAware: keyManagementConfig.isLocaleAware === true // Default to false
-        };
-        
+        const keyManagement = this._resolveKeyManagement();
+
         const parts = [];
-        
+
         if (keyManagement.isTenantAware) parts.push('{tenant}');
         if (keyManagement.isUserAware) parts.push('{user}');
         if (keyManagement.isLocaleAware) parts.push('{locale}');
         parts.push('{hash}');
-        
+
         return parts.join(':');
     }
 }

package/lib/support/StatisticsPersistenceManager.js

@@ -1,4 +1,6 @@
 const cds = require('@sap/cds');
+const { isMultitenantMode, hasTenantContext } = require('./MultitenancyDetector');
+const { isPluginModelAvailable } = require('../util');
 
 // Helper to merge min values, treating 0 as unset
 function mergeMin(a, b) {
@@ -25,7 +27,13 @@ class StatisticsPersistenceManager {
      * @param {boolean} enabled - Whether main metrics are enabled
      */
     async persistHourlyStats(stats, hourlyId, hourlyTimestamp, enabled) {
-        if (!enabled) return;
+        if (!enabled || !isPluginModelAvailable()) return;
+
+        // In MTX mode, only persist when we have a tenant context
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping hourly stats persistence in MTX mode (no tenant context)`);
+            return;
+        }
 
         try {
             const existingHourly = await SELECT.one.from("plugin_cds_caching_Metrics")
@@ -47,7 +55,13 @@ class StatisticsPersistenceManager {
      * @param {boolean} keyMetricsEnabled - Whether key metrics are enabled
      */
     async persistKeyMetrics(keyAccess, keyMetricsEnabled) {
-        if (!keyMetricsEnabled || keyAccess.size === 0) return;
+        if (!keyMetricsEnabled || keyAccess.size === 0 || !isPluginModelAvailable()) return;
+
+        // In MTX mode, only persist when we have a tenant context
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping key metrics persistence in MTX mode (no tenant context)`);
+            return;
+        }
 
         this.log.debug(`Persisting ${keyAccess.size} key access records for cache ${this.cacheName}`);
 
@@ -64,6 +78,7 @@ class StatisticsPersistenceManager {
      * Delete metrics for this cache
      */
     async deleteMetrics() {
+        if (!isPluginModelAvailable()) return;
         await DELETE('plugin_cds_caching_Metrics')
             .where({ cache: this.cacheName });
         this.log.debug(`Deleted metrics for cache ${this.cacheName}`);
@@ -73,6 +88,7 @@ class StatisticsPersistenceManager {
      * Delete key metrics for this cache
      */
     async deleteKeyMetrics() {
+        if (!isPluginModelAvailable()) return;
         await DELETE('plugin_cds_caching_KeyMetrics')
             .where({ cache: this.cacheName });
         this.log.debug(`Deleted key metrics for cache ${this.cacheName}`);

package/lib/support/Telemetry.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * Optional OpenTelemetry integration for cds-caching.
+ *
+ * If `@opentelemetry/api` is installed (e.g. via `@cap-js/telemetry`), this
+ * module exposes helpers to enrich auto-created spans and emit cache-specific
+ * OTel metrics.  When the dependency is absent everything is a safe no-op —
+ * no runtime errors, no performance impact.
+ */
+
+let otel;
+try {
+    otel = require('@opentelemetry/api');
+} catch (err) {
+    if (err && (err.code === 'MODULE_NOT_FOUND' || err.code === 'ERR_MODULE_NOT_FOUND')) {
+        otel = null;
+    } else {
+        throw err;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Default attributes (set once during CachingService.init)
+// ---------------------------------------------------------------------------
+let _defaults = {};
+
+// ---------------------------------------------------------------------------
+// Lazy metric instances — created on first use so the MeterProvider set up
+// by @cap-js/telemetry is already in place.
+// ---------------------------------------------------------------------------
+let _meter;
+let _hitCounter;
+let _missCounter;
+let _setCounter;
+let _deleteCounter;
+let _errorCounter;
+let _latencyHistogram;
+
+function ensureMetrics() {
+    if (_meter) return;
+    if (!otel) return;
+    _meter = otel.metrics.getMeter('cds-caching');
+    _hitCounter = _meter.createCounter('cds_caching.hits', {
+        description: 'Number of cache hits'
+    });
+    _missCounter = _meter.createCounter('cds_caching.misses', {
+        description: 'Number of cache misses'
+    });
+    _setCounter = _meter.createCounter('cds_caching.sets', {
+        description: 'Number of cache set operations'
+    });
+    _deleteCounter = _meter.createCounter('cds_caching.deletes', {
+        description: 'Number of cache delete operations'
+    });
+    _errorCounter = _meter.createCounter('cds_caching.errors', {
+        description: 'Number of cache operation errors'
+    });
+    _latencyHistogram = _meter.createHistogram('cds_caching.latency', {
+        description: 'Cache operation latency in milliseconds',
+        unit: 'ms'
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function attrs(extra) {
+    return { ..._defaults, ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+module.exports = {
+
+    /** Whether `@opentelemetry/api` could be loaded. */
+    isAvailable() { return !!otel; },
+
+    /** Return the currently active span, or `undefined`. */
+    getActiveSpan() { return otel?.trace?.getActiveSpan(); },
+
+    /** Return a Tracer scoped to the given name. */
+    getTracer(name) { return otel?.trace?.getTracer(name); },
+
+    /** Return a Meter scoped to the given name. */
+    getMeter(name) { return otel?.metrics?.getMeter(name); },
+
+    /** Convenience re-export so callers don't need to require `@opentelemetry/api`. */
+    SpanStatusCode: otel?.SpanStatusCode ?? { ERROR: 2, OK: 1 },
+
+    // -- configuration ------------------------------------------------------
+
+    /**
+     * Set attributes that will be merged into every metric recording.
+     * Typically called once during `CachingService.init()`.
+     */
+    setDefaultAttributes(attributes) {
+        _defaults = { ..._defaults, ...attributes };
+    },
+
+    // -- metric convenience methods -----------------------------------------
+
+    recordHit(latency, extra = {}) {
+        if (!otel) return;
+        ensureMetrics();
+        const a = attrs({ 'cache.operation': 'hit', ...extra });
+        _hitCounter.add(1, a);
+        if (latency != null) _latencyHistogram.record(latency, a);
+    },
+
+    recordMiss(latency, extra = {}) {
+        if (!otel) return;
+        ensureMetrics();
+        const a = attrs({ 'cache.operation': 'miss', ...extra });
+        _missCounter.add(1, a);
+        if (latency != null) _latencyHistogram.record(latency, a);
+    },
+
+    recordSet(extra = {}) {
+        if (!otel) return;
+        ensureMetrics();
+        _setCounter.add(1, attrs({ 'cache.operation': 'set', ...extra }));
+    },
+
+    recordDelete(extra = {}) {
+        if (!otel) return;
+        ensureMetrics();
+        _deleteCounter.add(1, attrs({ 'cache.operation': 'delete', ...extra }));
+    },
+
+    recordError(extra = {}) {
+        if (!otel) return;
+        ensureMetrics();
+        _errorCounter.add(1, attrs({ 'cache.operation': 'error', ...extra }));
+    }
+};

package/lib/util.js

@@ -1,4 +1,13 @@
 const cds = require("@sap/cds")
+const { isMultitenantMode } = require("./support/MultitenancyDetector")
+
+let _modelAvailable = null;
+
+const isPluginModelAvailable = () => {
+    if (_modelAvailable !== null) return _modelAvailable;
+    _modelAvailable = !!cds.model?.definitions?.['plugin.cds_caching.Caches'];
+    return _modelAvailable;
+};
 
 const extractCacheProperties = (entity, prefix) => {
     const result = {};
@@ -91,24 +100,20 @@ const bindEntity = async (service, entity) => {
 }
 
 const createCacheEntry = async (cacheName, serviceConfig = {}) => {
+    if (!isPluginModelAvailable()) return;
     try {
         const db = await cds.connect.to('db');
         const { Caches } = cds.entities('plugin.cds_caching');
 
-        // Check if cache entry already exists
         const existingCache = await db.read(Caches).where({ name: cacheName });
 
         if (existingCache.length === 0) {
-            // Create new cache entry
-            const cacheEntry = {
+            await db.create(Caches).entries({
                 name: cacheName,
                 config: JSON.stringify(serviceConfig)
-            };
-
-            await db.create(Caches).entries(cacheEntry);
+            });
             cds.log('cds-caching').info(`Created cache entry for: ${cacheName}`);
         } else {
-            // Update existing cache entry
             await db.update(Caches)
                 .set({ config: JSON.stringify(serviceConfig) })
                 .where({ name: cacheName });
@@ -122,6 +127,14 @@ const createCacheEntry = async (cacheName, serviceConfig = {}) => {
 const scanCachingAnnotations = async (srvs) => {
     LOG = cds.log('cds-caching')
 
+    if (!isPluginModelAvailable()) {
+        LOG.warn(
+            `Plugin data model not compiled into cds.model. Database features (dashboard, metrics persistence, CDS store) are disabled. ` +
+            `The model auto-loads when 'statistics' is configured or 'store: cds' is used. ` +
+            `For the dashboard, add: using {plugin.cds_caching.CachingApiService} from 'cds-caching/index.cds';`
+        );
+    }
+
     // Grep all app services
     const services = [];
     for (const [name, config] of Object.entries(srvs)) {
@@ -192,10 +205,15 @@ const scanCachingAnnotations = async (srvs) => {
         }
     }
 
-    const cachingServices = getCachingServicesFromConfig(srvs);
-    for (const service of cachingServices) {
-        await createCacheEntry(service.name, service);
+    // In MTX mode, skip DB persistence at startup — no tenant context available.
+    // Cache entries are informational (mirrors package.json config) and will be
+    // created lazily via CachingApiService when a tenant accesses the dashboard.
+    if (!isMultitenantMode()) {
+        const cachingServices = getCachingServicesFromConfig(srvs);
+        for (const service of cachingServices) {
+            await createCacheEntry(service.name, service);
+        }
     }
 }
 
-module.exports = { scanCachingAnnotations }
+module.exports = { scanCachingAnnotations, isPluginModelAvailable }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cds-caching",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A caching plugin for SAP CAP applications",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
     "cds",
     "caching",
     "redis",
+    "hana",
     "keyv"
   ],
   "author": "Mike Zaschka <opensource@mikezaschka.com>",
@@ -23,26 +24,38 @@
   "main": "cds-plugin.js",
   "types": "lib/CachingService.d.ts",
   "files": [
+    "db/**",
     "srv/**",
     "index.cds",
-    "lib/**"
+    "lib/**",
+    "app/dashboard/**"
   ],
   "scripts": {
     "test": "jest --runInBand --silent",
     "test:watch": "jest --watch",
+    "test:docker:start": "docker compose -f test/docker/docker-compose.yaml up -d --wait",
+    "test:docker:stop": "docker compose -f test/docker/docker-compose.yaml down",
+    "test:all": "npm run test:docker:start && npm test; status=$?; npm run test:docker:stop; exit $status",
     "lint": "eslint .",
-    "release": "release-it"
+    "release": "release-it",
+    "prepublishOnly": "cd examples/dashboard && npx ui5 build self-contained --clean-dest --dest ../../app/dashboard"
   },
   "peerDependencies": {
-    "@sap/cds": ">=8",
     "@keyv/compress-gzip": "^2.0.3",
     "@keyv/compress-lz4": "^1.0.1",
+    "@keyv/postgres": "^4.0.5",
     "@keyv/redis": "^5.0.0",
     "@keyv/sqlite": "^4.0.5",
+    "@opentelemetry/api": "^1.0.0",
     "@resolid/keyv-sqlite": "^4.0.5",
-    "@keyv/postgres": "^4.0.5"
+    "@sap/cds": ">=8",
+    "@sap/cds-dk": ">=9",
+    "keyv-hana": ">=1.0.0"
   },
   "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "@keyv/redis": {
       "optional": true
     },
@@ -60,6 +73,9 @@
     },
     "@keyv/postgres": {
       "optional": true
+    },
+    "keyv-hana": {
+      "optional": true
     }
   },
   "workspaces": [
@@ -73,18 +89,34 @@
   },
   "devDependencies": {
     "@cap-js/cds-test": "^0.4.1",
+    "@keyv/compress-gzip": "~2.0.3",
+    "@keyv/compress-lz4": "~1.0.1",
+    "@keyv/postgres": "~2.2.3",
+    "@keyv/sqlite": "~4.0.8",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/sdk-trace-node": "^1.30.1",
     "@release-it/conventional-changelog": "^10.0.5",
+    "@resolid/keyv-sqlite": "~5.0.1",
     "eslint": "^10.0.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
-    "release-it": "^19.2.4",
-    "@resolid/keyv-sqlite": "~5.0.1",
-    "@keyv/sqlite": "~4.0.8",
-    "@keyv/compress-lz4": "~1.0.1",
-    "@keyv/compress-gzip": "~2.0.3",
-    "@keyv/postgres": "~2.2.3"
+    "release-it": "^19.2.4"
   },
   "engines": {
     "node": ">=20"
+  },
+  "cds": {
+    "requires": {
+      "kinds": {
+        "cds-caching": {
+          "impl": "cds-caching"
+        },
+        "caching": {
+          "impl": "cds-caching"
+        }
+      }
+    }
   }
 }

package/srv/caching-api-service.js

@@ -1,10 +1,22 @@
 const cds = require('@sap/cds')
+const { isMultitenantMode } = require('../lib/support/MultitenancyDetector')
+const { isPluginModelAvailable } = require('../lib/util')
+
+const DEFAULT_TENANT = '_default';
 
 class CachingApiService extends cds.ApplicationService {
     log = cds.log('cds-caching');
 
     async init() {
 
+        // In MTX mode, lazily create cache entries on first dashboard access
+        // (skipped at startup because there's no tenant context)
+        if (isMultitenantMode()) {
+            this.before('READ', 'Caches', async () => {
+                await this._ensureCacheEntries();
+            });
+        }
+
         // Handle setMetricsEnabled action
         this.on('setMetricsEnabled', async (req) => {
             const { enabled } = req.data
@@ -117,8 +129,41 @@ class CachingApiService extends cds.ApplicationService {
         await super.init()
     }
 
-   
+    /**
+     * Ensure cache entries exist in the current tenant's DB.
+     * Called lazily in MTX mode on first dashboard access.
+     */
+    async _ensureCacheEntries() {
+        const tenant = cds.context?.tenant ?? DEFAULT_TENANT;
+        if (!this._cacheEntriesInitialized) this._cacheEntriesInitialized = new Set();
+        if (this._cacheEntriesInitialized.has(tenant) || !isPluginModelAvailable()) return;
 
+        try {
+            const { Caches } = cds.entities('plugin.cds_caching');
+            const requires = cds.env.requires || {};
+
+            for (const [name, config] of Object.entries(requires)) {
+                if (config.impl === 'cds-caching') {
+                    const existing = await SELECT.one.from(Caches).where({ name });
+                    if (!existing) {
+                        await INSERT.into(Caches).entries({
+                            name,
+                            config: JSON.stringify({
+                                impl: config.impl,
+                                store: config.store || 'memory',
+                                namespace: config.namespace || name
+                            })
+                        });
+                        this.log.info(`Created cache entry for: ${name} (lazy init)`);
+                    }
+                }
+            }
+
+            this._cacheEntriesInitialized.add(tenant);
+        } catch (error) {
+            this.log.warn('Failed to lazily initialize cache entries:', error);
+        }
+    }
 }
 
-module.exports = CachingApiService 
+module.exports = CachingApiService