add base for new caching approach, deprecate legacy

Author: pokornyd

Kontent.Ai.Delivery.Abstractions/Caching/IDeliveryCacheManager.cs

@@ -0,0 +1,113 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Kontent.Ai.Delivery.Abstractions;
+
+/// <summary>
+/// Manages caching of Delivery API responses with automatic dependency tracking and invalidation.
+/// Implementations should provide thread-safe operations suitable for concurrent access.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This interface follows modern .NET caching patterns, separating retrieval (<see cref="GetAsync{T}"/>),
+/// storage (<see cref="SetAsync{T}"/>), and invalidation (<see cref="InvalidateAsync"/>) concerns.
+/// </para>
+/// <para>
+/// The dependency tracking system enables automatic cache invalidation when content changes.
+/// When storing a cache entry, you specify which content items, assets, or taxonomies it depends on.
+/// Later, calling <see cref="InvalidateAsync"/> with any of those dependency keys will invalidate
+/// all cache entries that reference them.
+/// </para>
+/// <para>
+/// Dependency key format conventions:
+/// <list type="bullet">
+/// <item><description>Content items: <c>item_{codename}</c> (e.g., "item_hero")</description></item>
+/// <item><description>Assets: <c>asset_{guid}</c> (e.g., "asset_a5e1c4b2-...")</description></item>
+/// <item><description>Taxonomies: <c>taxonomy_{group}</c> (e.g., "taxonomy_categories")</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+public interface IDeliveryCacheManager
+{
+    /// <summary>
+    /// Attempts to retrieve a cached value by its key.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached value.</typeparam>
+    /// <param name="cacheKey">The unique key identifying the cache entry.</param>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <returns>
+    /// A task representing the asynchronous operation, containing the cached value if found;
+    /// otherwise, <c>null</c>.
+    /// </returns>
+    /// <remarks>
+    /// This method should return <c>null</c> for cache misses or expired entries, not throw exceptions.
+    /// Implementations should handle deserialization errors gracefully by treating them as cache misses.
+    /// </remarks>
+    Task<T?> GetAsync<T>(string cacheKey, CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Stores a value in the cache with associated dependency keys for automatic invalidation.
+    /// </summary>
+    /// <typeparam name="T">The type of the value to cache.</typeparam>
+    /// <param name="cacheKey">The unique key under which to store the value. Must not be <c>null</c> or empty.</param>
+    /// <param name="value">The value to cache. Must not be <c>null</c>.</param>
+    /// <param name="dependencies">
+    /// A collection of dependency keys that, when invalidated, will also invalidate this cache entry.
+    /// Use standardized key formats (see <see cref="IDeliveryCacheManager"/> remarks).
+    /// Must not be <c>null</c>, but may be empty.
+    /// </param>
+    /// <param name="expiration">
+    /// Optional absolute expiration timespan. If <c>null</c>, the implementation's default expiration is used.
+    /// </param>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <returns>A task representing the asynchronous storage operation.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="cacheKey"/>, <paramref name="value"/>, or <paramref name="dependencies"/> is <c>null</c>.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="cacheKey"/> is empty or whitespace.
+    /// </exception>
+    /// <remarks>
+    /// <para>
+    /// Implementations should create a reverse index mapping each dependency key to all cache entries
+    /// that reference it, enabling efficient invalidation via <see cref="InvalidateAsync"/>.
+    /// </para>
+    /// <para>
+    /// If the cache write fails, implementations should throw an exception rather than silently fail,
+    /// allowing the calling code to handle the error appropriately.
+    /// </para>
+    /// </remarks>
+    Task SetAsync<T>(
+        string cacheKey,
+        T value,
+        IEnumerable<string> dependencies,
+        TimeSpan? expiration = null,
+        CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Invalidates all cache entries that depend on the specified dependency keys.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <param name="dependencyKeys">
+    /// One or more dependency keys to invalidate. All cache entries referencing any of these keys
+    /// will be removed from the cache.
+    /// </param>
+    /// <returns>A task representing the asynchronous invalidation operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method performs cascade invalidation: if a cache entry depends on any of the specified keys,
+    /// it will be removed, regardless of what other dependencies it may have.
+    /// </para>
+    /// <para>
+    /// Invalidating a non-existent dependency key should succeed without error (idempotent operation).
+    /// </para>
+    /// <para>
+    /// Example: If a cached items list depends on "item_hero" and "item_author", calling
+    /// <c>InvalidateAsync(dependencyKeys: "item_hero")</c> will invalidate the entire list,
+    /// even though "item_author" was not invalidated.
+    /// </para>
+    /// </remarks>
+    Task InvalidateAsync(CancellationToken cancellationToken = default, params string[] dependencyKeys);
+}

Kontent.Ai.Delivery.Abstractions/Configuration/DeliveryOptions.cs

@@ -21,6 +21,39 @@ public sealed class DeliveryOptions : IValidatableObject
     /// </summary>
     public bool EnableResilience { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets a value that determines if the client uses integrated caching for API responses.
+    /// When enabled, the client will cache responses and automatically track dependencies for invalidation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When caching is enabled, an implementation of <see cref="IDeliveryCacheManager"/> must be
+    /// registered in the dependency injection container. If no cache manager is found, requests will
+    /// fail with a clear error message.
+    /// </para>
+    /// <para>
+    /// To enable caching:
+    /// <code>
+    /// services
+    ///     .AddDeliveryClient(options => {
+    ///         options.EnvironmentId = "your-environment-id";
+    ///         options.EnableCaching = true;
+    ///     })
+    ///     .AddDeliveryMemoryCache(); // or AddDeliveryDistributedCache()
+    /// </code>
+    /// </para>
+    /// <para>
+    /// Caching significantly improves performance by eliminating redundant API calls. The cache
+    /// automatically tracks dependencies on content items, assets, and taxonomies, allowing
+    /// precise invalidation when content changes.
+    /// </para>
+    /// <para>
+    /// Default: <c>false</c> (caching disabled).
+    /// </para>
+    /// </remarks>
+    /// <seealso cref="IDeliveryCacheManager"/>
+    public bool EnableCaching { get; set; } = false;
+
     /// <summary>
     /// Gets or sets the format of the Production API endpoint address.
     /// </summary>

Kontent.Ai.Delivery.Abstractions/ContentItems/IElementsPostProcessor.cs

@@ -2,6 +2,7 @@
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using Kontent.Ai.Delivery.Abstractions.ContentItems.Processing;
 
 namespace Kontent.Ai.Delivery.Abstractions;
 
@@ -17,10 +18,16 @@ public interface IElementsPostProcessor
     /// <typeparam name="TModel">Elements model type.</typeparam>
     /// <param name="item">The content item to process.</param>
     /// <param name="modularContent">Raw modular content dictionary from the API response.</param>
+    /// <param name="dependencyContext">
+    /// Optional context for tracking cache dependencies discovered during element hydration.
+    /// When provided, dependencies on referenced assets, taxonomies, and linked items are tracked.
+    /// Pass null when caching is disabled to avoid tracking overhead.
+    /// </param>
     /// <param name="cancellationToken">Cancellation token.</param>
     Task ProcessAsync<TModel>(
         IContentItem<TModel> item,
         IReadOnlyDictionary<string, JsonElement>? modularContent,
+        DependencyTrackingContext? dependencyContext = null,
         CancellationToken cancellationToken = default)
         where TModel : IElementsModel;
 }

Kontent.Ai.Delivery.Abstractions/ContentItems/Processing/DependencyTrackingContext.cs

@@ -0,0 +1,165 @@
+using System;
+using System.Collections.Generic;
+
+namespace Kontent.Ai.Delivery.Abstractions.ContentItems.Processing;
+
+/// <summary>
+/// Tracks cache dependencies discovered during content item processing.
+/// Used internally to build the set of dependency keys that should invalidate
+/// a cached API response when the referenced content changes.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class is designed to be used during a single API response processing pipeline.
+/// As elements are hydrated (rich text, taxonomies, linked items), dependencies are
+/// tracked by calling <see cref="TrackItem"/>, <see cref="TrackAsset"/>, or <see cref="TrackTaxonomy"/>.
+/// </para>
+/// <para>
+/// Thread-safety: This class is thread-safe and can be safely accessed from multiple
+/// concurrent operations during async processing. However, it's typically used within
+/// a single request context where such concurrency is unlikely.
+/// </para>
+/// <para>
+/// Dependency key formats:
+/// <list type="bullet">
+/// <item><description>Content items: <c>item_{codename}</c></description></item>
+/// <item><description>Assets: <c>asset_{guid}</c></description></item>
+/// <item><description>Taxonomies: <c>taxonomy_{group_codename}</c></description></item>
+/// </list>
+/// These formats align with the cache invalidation strategy in <see cref="IDeliveryCacheManager"/>.
+/// </para>
+/// </remarks>
+public sealed class DependencyTrackingContext
+{
+    /// <summary>
+    /// Prefix for content item dependency keys.
+    /// </summary>
+    public const string ItemPrefix = "item_";
+
+    /// <summary>
+    /// Prefix for asset dependency keys.
+    /// </summary>
+    public const string AssetPrefix = "asset_";
+
+    /// <summary>
+    /// Prefix for taxonomy group dependency keys.
+    /// </summary>
+    public const string TaxonomyPrefix = "taxonomy_";
+
+    private readonly HashSet<string> _dependencies = new(StringComparer.OrdinalIgnoreCase);
+    private readonly object _lock = new();
+
+    /// <summary>
+    /// Gets the collected set of dependency keys.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Returns an enumerable over the current dependencies using deferred execution.
+    /// The enumeration is thread-safe (protected by a lock), but the collection may change
+    /// between enumerations if dependencies are added concurrently.
+    /// </para>
+    /// <para>
+    /// To get a stable snapshot, enumerate into a collection:
+    /// <code>var snapshot = context.Dependencies.ToList();</code>
+    /// </para>
+    /// </remarks>
+    public IEnumerable<string> Dependencies
+    {
+        get
+        {
+            lock (_lock)
+            {
+                // Use deferred execution to avoid allocation on every access
+                foreach (var dependency in _dependencies)
+                {
+                    yield return dependency;
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// Tracks a dependency on a content item by its codename.
+    /// </summary>
+    /// <param name="codename">
+    /// The codename of the content item. If <c>null</c> or empty, the call is ignored.
+    /// </param>
+    /// <remarks>
+    /// Call this method for:
+    /// <list type="bullet">
+    /// <item><description>The primary content item(s) in the response</description></item>
+    /// <item><description>Linked content items (modular content)</description></item>
+    /// <item><description>Rich text inline content items</description></item>
+    /// </list>
+    /// Codenames are case-insensitive and duplicate calls with the same codename are ignored.
+    /// </remarks>
+    public void TrackItem(string? codename)
+    {
+        if (string.IsNullOrWhiteSpace(codename))
+        {
+            return;
+        }
+
+        lock (_lock)
+        {
+            _dependencies.Add($"{ItemPrefix}{codename}");
+        }
+    }
+
+    /// <summary>
+    /// Tracks a dependency on an asset by its ID.
+    /// </summary>
+    /// <param name="assetId">The unique identifier of the asset.</param>
+    /// <remarks>
+    /// <para>
+    /// Call this method for assets referenced in:
+    /// <list type="bullet">
+    /// <item><description>Rich text image elements</description></item>
+    /// <item><description>Asset element values</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// Asset IDs are globally unique, so Guid.Empty is a valid value and will be tracked.
+    /// Duplicate calls with the same asset ID are ignored.
+    /// </para>
+    /// </remarks>
+    public void TrackAsset(Guid assetId)
+    {
+        lock (_lock)
+        {
+            _dependencies.Add($"{AssetPrefix}{assetId}");
+        }
+    }
+
+    /// <summary>
+    /// Tracks a dependency on a taxonomy group by its codename.
+    /// </summary>
+    /// <param name="taxonomyGroup">
+    /// The codename of the taxonomy group. If <c>null</c> or empty, the call is ignored.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// Call this method when processing taxonomy elements to track dependencies on the
+    /// taxonomy group structure itself, not individual terms.
+    /// </para>
+    /// <para>
+    /// Taxonomy group codenames are case-insensitive and duplicate calls are ignored.
+    /// </para>
+    /// <para>
+    /// Note: This tracks the taxonomy group definition. Changes to individual term names
+    /// or the term hierarchy will invalidate caches depending on this group.
+    /// </para>
+    /// </remarks>
+    public void TrackTaxonomy(string? taxonomyGroup)
+    {
+        if (string.IsNullOrWhiteSpace(taxonomyGroup))
+        {
+            return;
+        }
+
+        lock (_lock)
+        {
+            _dependencies.Add($"{TaxonomyPrefix}{taxonomyGroup}");
+        }
+    }
+}

Kontent.Ai.Delivery.Abstractions/IDeliveryCacheManager.cs renamed to Kontent.Ai.Delivery.Abstractions/IDeliveryCacheManager.Old.cs

@@ -7,7 +7,8 @@ namespace Kontent.Ai.Delivery.Abstractions;
 /// <summary>
 /// Cache responses against the Kontent.ai Delivery API.
 /// </summary>
-public interface IDeliveryCacheManager
+[Obsolete("This interface is deprecated and will be removed in a future version. Use the new IDeliveryCacheManager interface with Get/Set/Invalidate pattern. See caching-v3.md for migration guidance.", false)]
+public interface IDeliveryCacheManagerLegacy
 {
     /// <summary>
     /// Returns the cached data or fetches the data using a factory and caches it before returning.

Kontent.Ai.Delivery.Caching/DeliveryClientCache.cs

@@ -12,10 +12,10 @@ namespace Kontent.Ai.Delivery.Caching;
 /// </remarks>
 /// <param name="cacheManager">The cache manager for storing and retrieving cached responses.</param>
 /// <param name="deliveryClient">The underlying delivery client.</param>
-public class DeliveryClientCache(IDeliveryCacheManager cacheManager, IDeliveryClient deliveryClient) : IDeliveryClient
+public class DeliveryClientCache(IDeliveryCacheManagerLegacy cacheManager, IDeliveryClient deliveryClient) : IDeliveryClient
 {
     private readonly IDeliveryClient _deliveryClient = deliveryClient ?? throw new ArgumentNullException(nameof(deliveryClient));
-    private readonly IDeliveryCacheManager _deliveryCacheManager = cacheManager ?? throw new ArgumentNullException(nameof(cacheManager));
+    private readonly IDeliveryCacheManagerLegacy _deliveryCacheManager = cacheManager ?? throw new ArgumentNullException(nameof(cacheManager));
 
     /// <summary>
     /// Returns a query builder for retrieving a single strongly typed content item.

Kontent.Ai.Delivery.Caching/DistributedCacheManager.cs

@@ -13,7 +13,7 @@ namespace Kontent.Ai.Delivery.Caching;
 /// <summary>
 /// Cache responses against the Kontent.ai Delivery API.
 /// </summary>
-internal class DistributedCacheManager : IDeliveryCacheManager
+internal class DistributedCacheManager : IDeliveryCacheManagerLegacy
 {
     private readonly IDistributedCache _distributedCache;
     private readonly DeliveryCacheOptions _cacheOptions;

Kontent.Ai.Delivery.Caching/Extensions/ServiceCollectionExtensions.cs

@@ -35,12 +35,12 @@ private static IServiceCollection RegisterDependencies(this IServiceCollection s
         switch (cacheType)
         {
             case CacheTypeEnum.Memory:
-                services.TryAddSingleton<IDeliveryCacheManager, MemoryCacheManager>();
+                services.TryAddSingleton<IDeliveryCacheManagerLegacy, MemoryCacheManager>();
                 services.TryAddSingleton<IMemoryCache, MemoryCache>();
                 break;
 
             case CacheTypeEnum.Distributed:
-                services.TryAddSingleton<IDeliveryCacheManager, DistributedCacheManager>();
+                services.TryAddSingleton<IDeliveryCacheManagerLegacy, DistributedCacheManager>();
                 services.TryAddSingleton<IDistributedCache, MemoryDistributedCache>();
                 break;
         }