Enhances cache key generation and validation

Introduces `CacheKeyAttribute` for explicit cache key strings on enum members, making them refactor-safe. Adds URL encoding for optional keys and optional length validation for distributed cache keys to improve compatibility and performance. Includes new unit tests for these features.

Author: neoscie

Neolution.Extensions.Caching.Abstractions/CacheKeyAttribute.cs

@@ -0,0 +1,38 @@
+namespace Neolution.Extensions.Caching.Abstractions
+{
+    using System;
+
+    /// <summary>
+    /// Specifies the explicit cache key string to use for an enum value.
+    /// This makes cache keys refactor-safe by decoupling them from the enum member name.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Field, AllowMultiple = false)]
+    public sealed class CacheKeyAttribute : Attribute
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CacheKeyAttribute"/> class.
+        /// </summary>
+        /// <param name="key">The explicit cache key string to use.</param>
+        /// <exception cref="ArgumentNullException">Thrown when key is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when key is empty or whitespace.</exception>
+        public CacheKeyAttribute(string key)
+        {
+            if (key == null)
+            {
+                throw new ArgumentNullException(nameof(key));
+            }
+
+            if (string.IsNullOrWhiteSpace(key))
+            {
+                throw new ArgumentException("Cache key cannot be empty or whitespace.", nameof(key));
+            }
+
+            this.Key = key;
+        }
+
+        /// <summary>
+        /// Gets the explicit cache key string.
+        /// </summary>
+        public string Key { get; }
+    }
+}

Neolution.Extensions.Caching.Abstractions/DistributedCache.cs

@@ -1,6 +1,7 @@
 namespace Neolution.Extensions.Caching.Abstractions
 {
     using System;
+    using System.Text;
     using System.Threading;
     using System.Threading.Tasks;
 
@@ -11,6 +12,12 @@
     public abstract class DistributedCache<TCacheId> : IDistributedCache<TCacheId>
         where TCacheId : struct, Enum
     {
+        /// <summary>
+        /// Maximum allowed cache key length in bytes (UTF-8 encoded).
+        /// This ensures performance and compatibility with limits of certain cache backends.
+        /// </summary>
+        private const int MaxCacheKeyBytes = 250;
+
         /// <summary>
         /// Gets the name of the cache.
         /// </summary>
@@ -19,6 +26,20 @@ public abstract class DistributedCache<TCacheId> : IDistributedCache<TCacheId>
         /// </value>
         private static string CacheIdName => typeof(TCacheId).Name;
 
+        /// <summary>
+        /// Gets a value indicating whether optional cache keys should be URL-encoded.
+        /// Default is true for safe handling of special characters.
+        /// Set to false to maintain backwards compatibility with existing cache keys.
+        /// </summary>
+        protected virtual bool EnableKeyEncoding => true;
+
+        /// <summary>
+        /// Gets a value indicating whether cache key length should be validated.
+        /// Default is true to ensure performance and compatibility with many cache backends.
+        /// Set to false to disable length validation if your cache backend supports longer keys.
+        /// </summary>
+        protected virtual bool EnableKeyLengthValidation => true;
+
         /// <summary>
         /// Gets the cache key version for invalidation purposes.
         /// If null, version is not included in the cache key.
@@ -212,6 +233,30 @@ protected abstract Task SetCacheObjectAsync<T>(string key, T value, CacheEntryOp
         /// <returns>The <see cref="Task"/>.</returns>
         protected abstract Task RemoveCacheObjectAsync(string key, CancellationToken token);
 
+        /// <summary>
+        /// Gets the cache key string for an enum value.
+        /// If the enum value has a <see cref="CacheKeyAttribute"/>, uses the explicit key.
+        /// Otherwise, uses the enum member name (ToString()).
+        /// </summary>
+        /// <param name="id">The cache identifier enum value.</param>
+        /// <returns>The cache key string to use.</returns>
+        private static string GetCacheKeyString(TCacheId id)
+        {
+            var enumType = typeof(TCacheId);
+            var memberName = id.ToString();
+            var memberInfo = enumType.GetField(memberName);
+
+            if (memberInfo == null)
+            {
+                return memberName;
+            }
+
+            // Check for CacheKeyAttribute
+            var attribute = (CacheKeyAttribute?)Attribute.GetCustomAttribute(memberInfo, typeof(CacheKeyAttribute));
+
+            return attribute?.Key ?? memberName;
+        }
+
         /// <summary>
         /// Creates the full key to use for the underlying cache implementation.
         /// </summary>
@@ -220,10 +265,14 @@ protected abstract Task SetCacheObjectAsync<T>(string key, T value, CacheEntryOp
         /// <returns>The caching key.</returns>
         private string CreateCacheKey(TCacheId id, string? key = null)
         {
-            var cacheKey = id.ToString();
+            // Use attribute value if present, otherwise enum name
+            var cacheKey = GetCacheKeyString(id);
+
             if (!string.IsNullOrWhiteSpace(key))
             {
-                cacheKey = $"{cacheKey}_{key}";
+                // URL-encode the key if enabled
+                var processedKey = this.EnableKeyEncoding ? Uri.EscapeDataString(key) : key;
+                cacheKey = $"{cacheKey}_{processedKey}";
             }
 
             var fullKey = CacheIdName;
@@ -242,6 +291,21 @@ private string CreateCacheKey(TCacheId id, string? key = null)
                 fullKey = $"{this.EnvironmentPrefix}:{fullKey}";
             }
 
+            // Optional validation - check total key length if enabled
+            if (this.EnableKeyLengthValidation)
+            {
+                var keyBytes = Encoding.UTF8.GetByteCount(fullKey);
+
+                if (keyBytes > MaxCacheKeyBytes)
+                {
+                    throw new ArgumentException(
+                        $"Generated cache key exceeds maximum length of {MaxCacheKeyBytes} bytes. " +
+                        $"Current key is {keyBytes} bytes: '{fullKey}'. " +
+                        $"Consider using a shorter optional key or shorter enum names.",
+                        nameof(key));
+                }
+            }
+
             return fullKey;
         }
     }

Neolution.Extensions.Caching.Abstractions/MemoryCache.cs

@@ -102,6 +102,7 @@ public void Remove(TCacheId id, string key)
         private static string CreateCacheKey(TCacheId container, string? key = null)
         {
             var containerName = container.ToString();
+
             if (!string.IsNullOrWhiteSpace(key))
             {
                 containerName = $"{containerName}_{key}";

Neolution.Extensions.Caching.UnitTests/CacheKeyImprovementsTests.cs

@@ -0,0 +1,118 @@
+namespace Neolution.Extensions.Caching.UnitTests
+{
+    using System;
+    using Microsoft.Extensions.DependencyInjection;
+    using Neolution.Extensions.Caching.Abstractions;
+    using Neolution.Extensions.Caching.UnitTests.Models;
+    using Shouldly;
+    using Xunit;
+
+    /// <summary>
+    /// Tests for cache key improvements (explicit string values for in-memory cache)
+    /// </summary>
+    public class CacheKeyImprovementsTests
+    {
+        /// <summary>
+        /// Tests that in-memory cache handles special characters without encoding
+        /// </summary>
+        [Fact]
+        public void MemoryCacheHandlesSpecialCharactersWithoutEncoding()
+        {
+            // Arrange
+            using var serviceProvider = CreateServiceCollection().BuildServiceProvider();
+            var cache = GetCache(serviceProvider);
+            var key = "user:123 test@example.com";
+            const string value = "test-value";
+
+            // Act
+            cache.Set(TestCacheId.Foobar, key, value);
+            var result = cache.Get<string>(TestCacheId.Foobar, key);
+
+            // Assert
+            result.ShouldBe(value);
+        }
+
+        /// <summary>
+        /// Tests that in-memory cache handles unicode characters
+        /// </summary>
+        [Fact]
+        public void MemoryCacheHandlesUnicodeCharacters()
+        {
+            // Arrange
+            using var serviceProvider = CreateServiceCollection().BuildServiceProvider();
+            var cache = GetCache(serviceProvider);
+            var key = "用户-123"; // Chinese characters
+            const string value = "test-value";
+
+            // Act
+            cache.Set(TestCacheId.Foobar, key, value);
+            var result = cache.Get<string>(TestCacheId.Foobar, key);
+
+            // Assert
+            result.ShouldBe(value);
+        }
+
+        /// <summary>
+        /// Tests that in-memory cache handles URL-unsafe characters
+        /// </summary>
+        [Fact]
+        public void MemoryCacheHandlesUrlUnsafeCharacters()
+        {
+            // Arrange
+            using var serviceProvider = CreateServiceCollection().BuildServiceProvider();
+            var cache = GetCache(serviceProvider);
+            var key = "key/with%special&chars?param=value";
+            const string value = "test-value";
+
+            // Act
+            cache.Set(TestCacheId.Foobar, key, value);
+            var result = cache.Get<string>(TestCacheId.Foobar, key);
+
+            // Assert
+            result.ShouldBe(value);
+        }
+
+        /// <summary>
+        /// Tests that in-memory cache accepts very long keys (no length restriction)
+        /// </summary>
+        [Fact]
+        public void MemoryCacheAcceptsVeryLongKeys()
+        {
+            // Arrange
+            using var serviceProvider = CreateServiceCollection().BuildServiceProvider();
+            var cache = GetCache(serviceProvider);
+            // In-memory cache has no length restriction
+            var longKey = new string('x', 500);
+            const string value = "test-value";
+
+            // Act & Assert - Should not throw
+            Should.NotThrow(() =>
+            {
+                cache.Set(TestCacheId.Foobar, longKey, value);
+                var result = cache.Get<string>(TestCacheId.Foobar, longKey);
+                result.ShouldBe(value);
+            });
+        }
+
+        /// <summary>
+        /// Gets the cache.
+        /// </summary>
+        /// <param name="serviceProvider">The service provider.</param>
+        /// <returns>Get the cache service from the specified service provider.</returns>
+        private static IMemoryCache<TestCacheId> GetCache(IServiceProvider serviceProvider)
+        {
+            return serviceProvider.GetRequiredService<IMemoryCache<TestCacheId>>();
+        }
+
+        /// <summary>
+        /// Creates the service collection needed for these tests.
+        /// </summary>
+        /// <returns>The service collection.</returns>
+        private static ServiceCollection CreateServiceCollection()
+        {
+            var services = new ServiceCollection();
+            services.AddInMemoryCache();
+            return services;
+        }
+    }
+}