Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.

src/Router/__Libraries/StellaOps.Messaging/Abstractions/IDistributedCache.cs

@@ -0,0 +1,69 @@
+namespace StellaOps.Messaging.Abstractions;
+
+/// <summary>
+/// Transport-agnostic distributed cache interface.
+/// </summary>
+/// <typeparam name="TKey">The key type.</typeparam>
+/// <typeparam name="TValue">The value type.</typeparam>
+public interface IDistributedCache<TKey, TValue>
+{
+    /// <summary>
+    /// Gets the provider name for diagnostics (e.g., "valkey", "postgres").
+    /// </summary>
+    string ProviderName { get; }
+
+    /// <summary>
+    /// Gets a value from the cache.
+    /// </summary>
+    /// <param name="key">The cache key.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The cache result.</returns>
+    ValueTask<CacheResult<TValue>> GetAsync(TKey key, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sets a value in the cache.
+    /// </summary>
+    /// <param name="key">The cache key.</param>
+    /// <param name="value">The value to cache.</param>
+    /// <param name="options">Optional cache entry options.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    ValueTask SetAsync(TKey key, TValue value, CacheEntryOptions? options = null, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a value from the cache.
+    /// </summary>
+    /// <param name="key">The cache key.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if the key existed and was removed.</returns>
+    ValueTask<bool> InvalidateAsync(TKey key, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes values matching a pattern from the cache.
+    /// </summary>
+    /// <param name="pattern">The key pattern (supports wildcards).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The number of keys invalidated.</returns>
+    ValueTask<long> InvalidateByPatternAsync(string pattern, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets or sets a value in the cache, using a factory function if the value is not present.
+    /// </summary>
+    /// <param name="key">The cache key.</param>
+    /// <param name="factory">Factory function to create the value if not cached.</param>
+    /// <param name="options">Optional cache entry options.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The cached or newly created value.</returns>
+    ValueTask<TValue> GetOrSetAsync(
+        TKey key,
+        Func<CancellationToken, ValueTask<TValue>> factory,
+        CacheEntryOptions? options = null,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Simple string-keyed distributed cache interface.
+/// </summary>
+/// <typeparam name="TValue">The value type.</typeparam>
+public interface IDistributedCache<TValue> : IDistributedCache<string, TValue>
+{
+}