cds-caching 3.0.0 → 3.1.0

package/README.md

@@ -77,7 +77,7 @@ This uses the in-memory store — no additional setup needed for development.
 
 The plugin ships CDS entity definitions for database-backed features. These load **conditionally** based on your configuration — no manual `model` property needed.
 
-> **Full guide:** [Feature Activation](docs/feature-activation.md) — decision tree, BTP/MTX best practices, and rules for avoiding duplicate model loading.
+> **Full guide:** [Feature Activation](docs/feature-activation.md) — decision tree, BTP/MTX guidance, and rules for avoiding duplicate model loading.
 
 | Option | Entities loaded | Purpose |
 |--------|-----------------|---------|
@@ -258,7 +258,7 @@ For detailed key configuration and deployment instructions, see [Key Management]
 
 The plugin includes `CachingApiService`, an OData service for managing caches, browsing entries, and viewing metrics. It powers the [dashboard](docs/dashboard.md) and can be consumed by any OData client.
 
-See **[Feature Activation](docs/feature-activation.md)** for reuse vs own activation, BTP/MTX best practices, and API authorization.
+See **[Feature Activation](docs/feature-activation.md)** for reuse vs own activation, BTP/MTX guidance, and API authorization.
 
 **Quick reference:**
 

package/db/statistics.cds

@@ -5,10 +5,13 @@ entity Caches {
         config            : String;
         metricsEnabled    : Boolean default false;
         keyMetricsEnabled : Boolean default false;
+        tagMetricsEnabled : Boolean default false;
         metrics           : Composition of many Metrics
                                 on metrics.cache = $self.name;
         keyMetrics        : Composition of many KeyMetrics
                                 on keyMetrics.cache = $self.name;
+        tagMetrics        : Composition of many TagMetrics
+                                on tagMetrics.cache = $self.name;
 }
 
 entity Metrics {
@@ -126,3 +129,56 @@ entity KeyMetrics {
         timestamp             : DateTime; // When this key was first accessed
         cacheOptions          : String; // JSON string with cache options
 }
+
+/**
+ * Per-tag metrics. Opt-in via `tagMetricsEnabled` / `metrics.tagMetricsEnabled`.
+ *
+ * An entry can carry several tags, so a single hit increments every matching tag
+ * row. Tag totals can therefore exceed cache-level `Metrics` totals — that is
+ * expected, not a bug. Query by the resolved tag string (exact match), e.g.
+ * `tag eq 'federation:Airports'`.
+ */
+entity TagMetrics {
+    key ID                    : String;
+    key cache                 : String;
+    key tag                   : String;
+        lastAccess            : DateTime;
+        period                : String enum {
+            current;
+            hourly;
+            daily;
+        };
+
+        // Read-through metrics (hits and misses only)
+        hits                  : Integer default 0;
+        misses                : Integer default 0;
+        errors                : Integer default 0;
+        totalRequests         : Integer default 0;
+        hitRatio              : Double;
+        cacheEfficiency       : Double;
+
+        // Read-through latency metrics
+        avgHitLatency         : Double;
+        minHitLatency         : Double;
+        maxHitLatency         : Double;
+        avgMissLatency        : Double;
+        minMissLatency        : Double;
+        maxMissLatency        : Double;
+        avgReadThroughLatency : Double;
+
+        // Read-through performance metrics
+        throughput            : Double;
+        errorRate             : Double;
+
+        // Native function metrics (counts only)
+        nativeHits            : Integer default 0;
+        nativeMisses          : Integer default 0;
+        nativeSets            : Integer default 0;
+        nativeDeletes         : Integer default 0;
+        nativeErrors          : Integer default 0;
+        totalNativeOperations : Integer default 0;
+        nativeThroughput      : Double;
+        nativeErrorRate       : Double;
+
+        timestamp             : DateTime;
+}

package/index.cds

@@ -39,8 +39,10 @@ context plugin.cds_caching {
                 action   clear()                                               returns Boolean;
                 action   clearMetrics()                                        returns Boolean;
                 action   clearKeyMetrics()                                     returns Boolean;
+                action   clearTagMetrics()                                     returns Boolean;
                 action   setMetricsEnabled(enabled : Boolean)                  returns Boolean;
                 action   setKeyMetricsEnabled(enabled : Boolean)               returns Boolean;
+                action   setTagMetricsEnabled(enabled : Boolean)               returns Boolean;
             };
 
         @readonly
@@ -49,5 +51,8 @@ context plugin.cds_caching {
         @readonly
         entity KeyMetrics as projection on plugin.cds_caching.KeyMetrics;
 
+        @readonly
+        entity TagMetrics as projection on plugin.cds_caching.TagMetrics;
+
     }
 }

package/lib/CachingService.d.ts

@@ -58,6 +58,15 @@ export interface CacheKeyMetrics {
   lastAccessed: Date;
 }
 
+export interface CacheTagMetrics {
+  tag: string;
+  hits: number;
+  misses: number;
+  totalRequests: number;
+  hitRatio: number;
+  lastAccess: Date;
+}
+
 export interface CachableFunctionOptions {
   '@cache.ttl'?: number;
   '@cache.key'?: string | object;
@@ -280,6 +289,16 @@ export declare class CachingService extends Service {
    */
   getCurrentKeyMetrics(): Promise<CacheKeyMetrics>;
 
+  /**
+   * Get tag-specific metrics for a specific period
+   */
+  getTagMetrics(tag: string, from: Date, to: Date): Promise<CacheTagMetrics>;
+
+  /**
+   * Get current tag metrics
+   */
+  getCurrentTagMetrics(): Promise<Map<string, CacheTagMetrics> | null>;
+
   /**
    * Clear all metrics
    */
@@ -290,6 +309,11 @@ export declare class CachingService extends Service {
    */
   clearKeyMetrics(): Promise<void>;
 
+  /**
+   * Clear tag metrics
+   */
+  clearTagMetrics(): Promise<void>;
+
   /**
    * Enable or disable statistics at runtime
    */
@@ -300,6 +324,11 @@ export declare class CachingService extends Service {
    */
   setKeyMetricsEnabled(enabled: boolean): Promise<void>;
 
+  /**
+   * Enable or disable tag tracking at runtime
+   */
+  setTagMetricsEnabled(enabled: boolean): Promise<void>;
+
   /**
    * Persist metrics to database
    */

package/lib/CachingService.js

@@ -129,12 +129,16 @@ class CachingService extends cds.Service {
 
         let metricsEnabled = config.metricsEnabled;
         let keyMetricsEnabled = config.keyMetricsEnabled;
+        let tagMetricsEnabled = config.tagMetricsEnabled;
         if (normalized.metrics?.enabled === true) {
             metricsEnabled = true;
         }
         if (normalized.metrics?.keyMetricsEnabled === true) {
             keyMetricsEnabled = true;
         }
+        if (normalized.metrics?.tagMetricsEnabled === true) {
+            tagMetricsEnabled = true;
+        }
 
         // Initialize statistics with runtime configuration support
         this.statistics = new CacheStatisticsHandler({
@@ -142,6 +146,7 @@ class CachingService extends cds.Service {
             ...statsOpts,
         });
         this.statistics.enableKeyMetrics(keyMetricsEnabled);
+        this.statistics.enableTagMetrics(tagMetricsEnabled);
         this.statistics.enableMetrics(metricsEnabled);
 
         if (normalized.metrics?.enabled === true && isPluginModelAvailable()) {
@@ -158,6 +163,13 @@ class CachingService extends cds.Service {
                 this.log.warn(`Failed to persist keyMetricsEnabled from config for ${this.name}:`, error);
             }
         }
+        if (normalized.metrics?.tagMetricsEnabled === true && isPluginModelAvailable()) {
+            try {
+                await this.runtimeConfigManager.setTagMetricsEnabled(true);
+            } catch (error) {
+                this.log.warn(`Failed to persist tagMetricsEnabled from config for ${this.name}:`, error);
+            }
+        }
 
         // Initialize operation managers
         this.basicOperations = new BasicOperations(
@@ -402,6 +414,25 @@ class CachingService extends cds.Service {
         return this.statistics.getCurrentKeyMetrics();
     }
 
+    /**
+     * Get tag-specific metrics for a specific period
+     * @param {string} tag - resolved tag string
+     * @param {Date} from
+     * @param {Date} to
+     * @returns {Promise<object>}
+     */
+    async getTagMetrics(tag, from, to) {
+        return this.statistics.getTagMetrics(tag, from, to);
+    }
+
+    /**
+     * Get current tag metrics
+     * @returns {Promise<Map|null>}
+     */
+    async getCurrentTagMetrics() {
+        return this.statistics.getCurrentTagMetrics();
+    }
+
 
 
     /**
@@ -420,6 +451,14 @@ class CachingService extends cds.Service {
         return this.statistics.clearKeyMetrics();
     }
 
+    /**
+     * Clear tag metrics
+     * @returns {Promise<void>}
+     */
+    async clearTagMetrics() {
+        return this.statistics.clearTagMetrics();
+    }
+
     /**
      * Enable or disable statistics at runtime
      * @param {boolean} enabled - whether to enable statistics
@@ -440,6 +479,16 @@ class CachingService extends cds.Service {
         this.statistics.enableKeyMetrics(enabled);
     }
 
+    /**
+     * Enable or disable tag tracking at runtime
+     * @param {boolean} enabled - whether to enable tag tracking
+     * @returns {Promise<void>}
+     */
+    async setTagMetricsEnabled(enabled) {
+        await this.runtimeConfigManager.setTagMetricsEnabled(enabled);
+        this.statistics.enableTagMetrics(enabled);
+    }
+
     /**
      * Persist metrics to database
      * @returns {Promise<void>}

package/lib/config-normalizer.js

@@ -97,9 +97,11 @@ function getStatisticsHandlerOptions(metrics) {
     if (metrics.persistenceInterval != null) opts.persistenceInterval = metrics.persistenceInterval
     if (metrics.maxLatencies != null) opts.maxLatencies = metrics.maxLatencies
     if (metrics.maxKeyMetrics != null) opts.maxKeyMetrics = metrics.maxKeyMetrics
+    if (metrics.maxTagMetrics != null) opts.maxTagMetrics = metrics.maxTagMetrics
     if (metrics.maxMetricFieldLength != null) opts.maxMetricFieldLength = metrics.maxMetricFieldLength
     if (metrics.enabled === true) opts.metricsEnabled = true
     if (metrics.keyMetricsEnabled === true) opts.keyMetricsEnabled = true
+    if (metrics.tagMetricsEnabled === true) opts.tagMetricsEnabled = true
     return opts
 }
 

package/lib/operations/AsyncOperations.js

@@ -122,6 +122,22 @@ class AsyncOperations {
         };
     }
 
+    /** @private */
+    _resolveTags(options, value) {
+        const resolver = this.cache?.tagResolver;
+        if (resolver) {
+            return resolver.resolveTags(options?.tags, value, {
+                user: cds.context?.user?.id,
+                tenant: cds.context?.tenant,
+                locale: cds.context?.locale,
+            }) || [];
+        }
+        if (!Array.isArray(options?.tags)) return [];
+        return options.tags
+            .map((t) => (typeof t === 'string' ? t : t?.value))
+            .filter((t) => typeof t === 'string' && t);
+    }
+
     /** @private */
     async _wrap(key, asyncFunction, options, args) {
         // Create dynamic key based on function arguments
@@ -140,7 +156,8 @@ class AsyncOperations {
                 args: args,
                 cacheKey: cacheKey
             }),
-            cacheOptions: JSON.stringify(options)
+            cacheOptions: JSON.stringify(options),
+            tags: this._resolveTags(options, undefined),
         };
 
         // Safely check if key exists in cache
@@ -156,16 +173,6 @@ class AsyncOperations {
         if (hasKey) {
             const latency = this.getElapsedMs(startTime);
 
-            // Safely record hit statistics
-            const hitStatsResult = await this.safeCacheOperation(
-                () => this.statistics.recordHit(latency, cacheKey, metadata),
-                'recordHit',
-                { key: cacheKey, latency }
-            );
-            if (!hitStatsResult.success) {
-                cacheErrors.push(hitStatsResult.error);
-            }
-
             // Safely get value from cache
             const getResult = await this.safeCacheOperation(
                 () => this.cache.send("GET", { key: cacheKey }),
@@ -174,6 +181,19 @@ class AsyncOperations {
             );
 
             if (getResult.success && getResult.result?.value !== undefined) {
+                if (Array.isArray(getResult.result.tags) && getResult.result.tags.length > 0) {
+                    metadata.tags = getResult.result.tags;
+                }
+
+                const hitStatsResult = await this.safeCacheOperation(
+                    () => this.statistics.recordHit(latency, cacheKey, metadata),
+                    'recordHit',
+                    { key: cacheKey, latency }
+                );
+                if (!hitStatsResult.success) {
+                    cacheErrors.push(hitStatsResult.error);
+                }
+
                 return {
                     result: getResult.result.value,
                     cacheKey,
@@ -187,6 +207,8 @@ class AsyncOperations {
         try {
             const response = await asyncFunction(...args);
             const latency = this.getElapsedMs(startTime);
+            const tags = this._resolveTags(options, response);
+            metadata.tags = tags;
 
             // Safely record miss statistics
             const missStatsResult = await this.safeCacheOperation(
@@ -201,7 +223,7 @@ class AsyncOperations {
             // Safely store in cache
             const wrappedValue = {
                 value: response,
-                tags: options.tags || [],
+                tags,
                 timestamp: Date.now()
             };
 
@@ -281,7 +303,8 @@ class AsyncOperations {
                 args: args,
                 cacheKey: cacheKey
             }),
-            cacheOptions: JSON.stringify(options)
+            cacheOptions: JSON.stringify(options),
+            tags: this._resolveTags(options, undefined),
         };
 
         // Safely check if key exists in cache
@@ -297,16 +320,6 @@ class AsyncOperations {
         if (hasKey) {
             const latency = this.getElapsedMs(startTime);
 
-            // Safely record hit statistics
-            const hitStatsResult = await this.safeCacheOperation(
-                () => this.statistics.recordHit(latency, cacheKey, metadata),
-                'recordHit',
-                { key: cacheKey, latency }
-            );
-            if (!hitStatsResult.success) {
-                cacheErrors.push(hitStatsResult.error);
-            }
-
             // Safely get value from cache
             const getResult = await this.safeCacheOperation(
                 () => this.cache.send("GET", { key: cacheKey }),
@@ -315,6 +328,19 @@ class AsyncOperations {
             );
 
             if (getResult.success && getResult.result?.value !== undefined) {
+                if (Array.isArray(getResult.result.tags) && getResult.result.tags.length > 0) {
+                    metadata.tags = getResult.result.tags;
+                }
+
+                const hitStatsResult = await this.safeCacheOperation(
+                    () => this.statistics.recordHit(latency, cacheKey, metadata),
+                    'recordHit',
+                    { key: cacheKey, latency }
+                );
+                if (!hitStatsResult.success) {
+                    cacheErrors.push(hitStatsResult.error);
+                }
+
                 return {
                     result: getResult.result.value,
                     cacheKey,
@@ -328,6 +354,8 @@ class AsyncOperations {
         try {
             const response = await asyncFunction(...args);
             const latency = this.getElapsedMs(startTime);
+            const tags = this._resolveTags(options, response);
+            metadata.tags = tags;
 
             // Safely record miss statistics
             const missStatsResult = await this.safeCacheOperation(
@@ -342,7 +370,7 @@ class AsyncOperations {
             // Safely store in cache
             const wrappedValue = {
                 value: response,
-                tags: options.tags || [],
+                tags,
                 timestamp: Date.now()
             };
 

package/lib/operations/BasicOperations.js

@@ -28,9 +28,10 @@ class BasicOperations {
      * @returns {Promise<void>}
      */
     async set(key, value, options = {}, tx = null) {
+        const tags = this.tagResolver.resolveTags(options.tags, value, options.params) || [];
         const wrappedValue = {
             value,
-            tags: this.tagResolver.resolveTags(options.tags, value, options.params) || [],
+            tags,
             timestamp: Date.now()
         };
         const createdKey = this.keyManager.createKey(key, {}, options.key);
@@ -48,7 +49,8 @@ class BasicOperations {
             operation: 'SET',
             operationType: 'BASIC',
             metadata: JSON.stringify({ key: createdKey, ttl: options.ttl || 0 }),
-            cacheOptions: JSON.stringify(options)
+            cacheOptions: JSON.stringify(options),
+            tags,
         };
         this.statistics.recordNativeSet(createdKey, metadata);
 
@@ -84,7 +86,8 @@ class BasicOperations {
             dataType: 'Operation',
             operation: 'GET',
             operationType: 'BASIC',
-            metadata: JSON.stringify({ key: createdKey })
+            metadata: JSON.stringify({ key: createdKey }),
+            tags: wrappedValue?.tags || [],
         };
         const isHit = wrappedValue !== undefined && wrappedValue !== null;
         this.statistics.recordNativeGet(createdKey, isHit, metadata);

package/lib/operations/CapOperations.js

@@ -129,6 +129,13 @@ class CapOperations {
 
         const key = this.keyManager.createKey(request, keyParts, requestOptions.key);
         const startTime = process.hrtime();
+        const tagParams = {
+            ...request.params,
+            user: request.user?.id,
+            tenant: request.tenant,
+            locale: request.locale,
+            hash: this.keyManager.createContentHash(request),
+        };
 
         // Track the miss with total latency (cache lookup + backend operation)
         const metadata = {
@@ -153,7 +160,9 @@ class CapOperations {
                 event: request.event,
                 headers: redactHeaders(request.headers),
             }),
-            cacheOptions: JSON.stringify(requestOptions)
+            cacheOptions: JSON.stringify(requestOptions),
+            // Static tags resolve without a payload; data tags fill in on miss after the response.
+            tags: this.tagResolver.resolveTags(requestOptions.tags, undefined, tagParams) || [],
         };
 
         // Safely check if key exists in cache
@@ -169,17 +178,7 @@ class CapOperations {
         if (hasKey) {
             const latency = this.getElapsedMs(startTime);
 
-            // Safely record hit statistics
-            const hitStatsResult = await this.safeCacheOperation(
-                () => this.statistics.recordHit(latency, key, metadata),
-                'recordHit',
-                { key, latency }
-            );
-            if (!hitStatsResult.success) {
-                cacheErrors.push(hitStatsResult.error);
-            }
-
-            // Safely get value from cache
+            // Safely get value from cache (before recording so entry tags are available)
             const getResult = await this.safeCacheOperation(
                 () => this.cache.send("GET", { key }),
                 'get',
@@ -187,6 +186,19 @@ class CapOperations {
             );
 
             if (getResult.success && getResult.result?.value !== undefined) {
+                if (Array.isArray(getResult.result.tags) && getResult.result.tags.length > 0) {
+                    metadata.tags = getResult.result.tags;
+                }
+
+                const hitStatsResult = await this.safeCacheOperation(
+                    () => this.statistics.recordHit(latency, key, metadata),
+                    'recordHit',
+                    { key, latency }
+                );
+                if (!hitStatsResult.success) {
+                    cacheErrors.push(hitStatsResult.error);
+                }
+
                 return {
                     result: getResult.result.value,
                     cacheKey: key,
@@ -200,6 +212,8 @@ class CapOperations {
         try {
             const response = await service.send(request);
             const totalLatency = this.getElapsedMs(startTime);
+            const tags = this.tagResolver.resolveTags(requestOptions.tags, response, tagParams) || [];
+            metadata.tags = tags;
 
             // Safely record miss statistics
             const missStatsResult = await this.safeCacheOperation(
@@ -214,7 +228,7 @@ class CapOperations {
             // Safely store in cache
             const wrappedValue = {
                 value: response,
-                tags: this.tagResolver.resolveTags(requestOptions.tags, response, { ...request.params, user: request.user?.id, tenant: request.tenant, locale: request.locale, hash: this.keyManager.createContentHash(request) }),
+                tags,
                 timestamp: Date.now()
             };
 
@@ -311,9 +325,14 @@ class CapOperations {
                     const cacheHit = getResult.success && getResult.result?.value !== undefined;
                     const cacheLatency = this.getElapsedMs(startTime);
                     const metadata = this.extractMetadataFromRequest(req);
+                    const tagParams = { ...req.params, hash: this.keyManager.createContentHash(req) };
                     const cacheErrors = [];
 
                     if (cacheHit) {
+                        metadata.tags = (Array.isArray(getResult.result.tags) && getResult.result.tags.length > 0)
+                            ? getResult.result.tags
+                            : (this.tagResolver.resolveTags(req.cacheOptions.tags, getResult.result.value, tagParams) || []);
+
                         // Cache hit
                         const hitStatsResult = await this.safeCacheOperation(
                             () => this.statistics.recordHit(cacheLatency, req.cacheKey, metadata),
@@ -336,6 +355,8 @@ class CapOperations {
                         try {
                             const response = await next();
                             const totalLatency = this.getElapsedMs(startTime);
+                            const tags = this.tagResolver.resolveTags(req.cacheOptions.tags, response, tagParams) || [];
+                            metadata.tags = tags;
 
                             // Safely record miss statistics
                             const missStatsResult = await this.safeCacheOperation(
@@ -352,7 +373,7 @@ class CapOperations {
                             // Safely store in cache
                             const wrappedValue = {
                                 value: response,
-                                tags: this.tagResolver.resolveTags(req.cacheOptions.tags, response, { ...req.params, hash: this.keyManager.createContentHash(req) }),
+                                tags,
                                 timestamp: Date.now()
                             };
 
@@ -407,6 +428,7 @@ class CapOperations {
 
                         const hasCachedValue = hasCachedValueResult.success && hasCachedValueResult.result;
                         const cacheLatency = this.getElapsedMs(startTime);
+                        const tagParams = { ...query.params, hash: this.keyManager.createContentHash(query) };
                         const metadata = {
                             dataType: 'Query',
                             operation: 'SELECT',
@@ -423,21 +445,12 @@ class CapOperations {
                                 serviceName: srv?.name,
                                 path: query.path,
                             }),
-                            cacheOptions: JSON.stringify(options)
+                            cacheOptions: JSON.stringify(options),
+                            tags: this.tagResolver.resolveTags(options.tags, undefined, tagParams) || [],
                         };
                         const cacheErrors = [];
 
                         if (hasCachedValue) {
-                            // Cache hit
-                            const hitStatsResult = await this.safeCacheOperation(
-                                () => this.statistics.recordHit(cacheLatency, query.cacheKey, metadata),
-                                'recordHit',
-                                { key: query.cacheKey, latency: cacheLatency }
-                            );
-                            if (!hitStatsResult.success) {
-                                cacheErrors.push(hitStatsResult.error);
-                            }
-
                             const getResult = await this.safeCacheOperation(
                                 () => this.cache.send("GET", { key: query.cacheKey }),
                                 'get',
@@ -445,6 +458,19 @@ class CapOperations {
                             );
 
                             if (getResult.success && getResult.result?.value !== undefined) {
+                                if (Array.isArray(getResult.result.tags) && getResult.result.tags.length > 0) {
+                                    metadata.tags = getResult.result.tags;
+                                }
+
+                                const hitStatsResult = await this.safeCacheOperation(
+                                    () => this.statistics.recordHit(cacheLatency, query.cacheKey, metadata),
+                                    'recordHit',
+                                    { key: query.cacheKey, latency: cacheLatency }
+                                );
+                                if (!hitStatsResult.success) {
+                                    cacheErrors.push(hitStatsResult.error);
+                                }
+
                                 return {
                                     result: getResult.result.value,
                                     cacheKey: query.cacheKey,
@@ -458,6 +484,8 @@ class CapOperations {
                         try {
                             const data = await srv.run(query);
                             const totalLatency = this.getElapsedMs(startTime);
+                            const tags = this.tagResolver.resolveTags(options.tags, data, tagParams) || [];
+                            metadata.tags = tags;
 
                             // Safely record miss statistics
                             const missStatsResult = await this.safeCacheOperation(
@@ -472,7 +500,7 @@ class CapOperations {
                             // Safely store in cache
                             const wrappedValue = {
                                 value: data,
-                                tags: this.tagResolver.resolveTags(options.tags, data, { ...query.params, hash: this.keyManager.createContentHash(query) }),
+                                tags,
                                 timestamp: Date.now()
                             };
 
@@ -590,7 +618,11 @@ class CapOperations {
                 path: req.http?.req?.path,
                 url: req.http?.req?.url
             }),
-            cacheOptions: JSON.stringify(req.cacheOptions)
+            cacheOptions: JSON.stringify(req.cacheOptions),
+            tags: this.tagResolver.resolveTags(req.cacheOptions?.tags, undefined, {
+                ...req.params,
+                hash: this.keyManager.createContentHash(req),
+            }) || [],
         };
 
         return metadata;