fix: complete issue 193 requirements (#193) (#195)

* feat: implement Redis metadata cache with in-memory fallback (#37)

- Add ICacheService and ICacheHealthChecker abstractions in Honua.Core
- Add CacheOptions configuration with TTL settings
- Implement RedisCacheService using IDistributedCache from Aspire
- Support automatic fallback to in-memory cache when Redis unavailable
- Create CachingLayerCatalog decorator for transparent caching
- Integrate cache health status into ReadinessCheckService
- Add cache metrics (hits/misses/evictions) using PerformanceMetrics
- Add configuration documentation in appsettings.json
- Add comprehensive unit tests for caching functionality

Configuration options:
- Cache:Enabled - enable/disable caching (default: true)
- Cache:DefaultTtlSeconds - default TTL (default: 300)
- Cache:LayerTtlSeconds - layer metadata TTL (default: 300)
- Cache:ServiceTtlSeconds - service metadata TTL (default: 300)
- Cache:EnableFallback - use in-memory when Redis unavailable (default: true)
- Cache:FallbackMaxEntries - max in-memory entries (default: 1000)
- Cache:RetryIntervalSeconds - retry Redis connection interval (default: 30)
- Cache:KeyPrefix - key prefix for Redis (default: "honua:")

* fix: complete issue 193 requirements (#193)

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Mike McDougall <mike@honua.io>

Author: 3 people

src/Honua.Core/Features/Infrastructure/Monitoring/DefaultPerformanceMonitor.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Honua. All rights reserved.
 // Licensed under the Elastic License 2.0. See LICENSE in the project root.
 
+using System.Collections.Concurrent;
 using System.Diagnostics;
 using System.Globalization;
 
@@ -13,8 +14,10 @@ namespace Honua.Core.Features.Infrastructure.Monitoring;
 /// This implementation provides comprehensive performance monitoring using the .NET Metrics API
 /// and integrates with OpenTelemetry for telemetry export.
 /// </remarks>
-internal sealed class DefaultPerformanceMonitor : IPerformanceMonitor
+internal sealed class DefaultPerformanceMonitor : IPerformanceMonitor, ICacheMetricsSnapshotProvider
 {
+    private readonly ConcurrentDictionary<string, CacheOperationCounters> _cacheCounters = new(StringComparer.OrdinalIgnoreCase);
+
     /// <inheritdoc />
     public void RecordDatabaseQuery(string queryType, string layerId, TimeSpan duration, int recordCount)
     {
@@ -72,6 +75,37 @@ public void RecordCacheMetrics(string cacheType, string operation)
         };
 
         PerformanceMetrics.CacheOperationCount.Add(1, tags);
+
+        var normalizedType = string.IsNullOrWhiteSpace(cacheType) ? "unknown" : cacheType;
+        var normalizedOperation = string.IsNullOrWhiteSpace(operation) ? "unknown" : operation;
+        var counters = _cacheCounters.GetOrAdd(normalizedType, _ => new CacheOperationCounters());
+        counters.Record(normalizedOperation);
+    }
+
+    /// <inheritdoc />
+    public CacheMetricsSnapshot GetCacheMetricsSnapshot()
+    {
+        var types = new Dictionary<string, CacheTypeMetricsSnapshot>(StringComparer.OrdinalIgnoreCase);
+        long totalHits = 0;
+        long totalMisses = 0;
+        long totalEvictions = 0;
+
+        foreach (var (cacheType, counters) in _cacheCounters)
+        {
+            var snapshot = counters.Snapshot();
+            types[cacheType] = snapshot;
+            totalHits += snapshot.Hits;
+            totalMisses += snapshot.Misses;
+            totalEvictions += snapshot.Evictions;
+        }
+
+        return new CacheMetricsSnapshot
+        {
+            TotalHits = totalHits,
+            TotalMisses = totalMisses,
+            TotalEvictions = totalEvictions,
+            Types = types
+        };
     }
 
     /// <inheritdoc />
@@ -149,4 +183,38 @@ public void Dispose()
             PerformanceMetrics.OperationCount.Add(1, tagPairs);
         }
     }
+
+    private sealed class CacheOperationCounters
+    {
+        private long _hits;
+        private long _misses;
+        private long _evictions;
+
+        public void Record(string operation)
+        {
+            switch (operation.ToLowerInvariant())
+            {
+                case "hit":
+                    Interlocked.Increment(ref _hits);
+                    break;
+                case "miss":
+                    Interlocked.Increment(ref _misses);
+                    break;
+                case "eviction":
+                case "pattern_eviction":
+                    Interlocked.Increment(ref _evictions);
+                    break;
+            }
+        }
+
+        public CacheTypeMetricsSnapshot Snapshot()
+        {
+            return new CacheTypeMetricsSnapshot
+            {
+                Hits = Interlocked.Read(ref _hits),
+                Misses = Interlocked.Read(ref _misses),
+                Evictions = Interlocked.Read(ref _evictions)
+            };
+        }
+    }
 }

src/Honua.Core/Features/Infrastructure/Monitoring/PerformanceMetricsSnapshots.cs

@@ -0,0 +1,133 @@
+// Copyright (c) Honua. All rights reserved.
+// Licensed under the Elastic License 2.0. See LICENSE in the project root.
+
+namespace Honua.Core.Features.Infrastructure.Monitoring;
+
+/// <summary>
+/// Provides access to database performance metrics snapshots.
+/// </summary>
+public interface IDatabasePerformanceMetricsProvider
+{
+    /// <summary>
+    /// Gets a snapshot of database performance metrics.
+    /// </summary>
+    DatabasePerformanceMetricsSnapshot GetMetrics();
+}
+
+/// <summary>
+/// Provides access to cache performance metrics snapshots.
+/// </summary>
+public interface ICacheMetricsSnapshotProvider
+{
+    /// <summary>
+    /// Gets a snapshot of cache performance metrics.
+    /// </summary>
+    CacheMetricsSnapshot GetCacheMetricsSnapshot();
+}
+
+/// <summary>
+/// Snapshot of database performance metrics.
+/// </summary>
+public sealed record DatabasePerformanceMetricsSnapshot
+{
+    /// <summary>
+    /// Cache hit rate as a decimal (0.0 to 1.0).
+    /// </summary>
+    public double CacheHitRate { get; init; }
+
+    /// <summary>
+    /// Total number of cache hits.
+    /// </summary>
+    public long CacheHits { get; init; }
+
+    /// <summary>
+    /// Total number of cache misses.
+    /// </summary>
+    public long CacheMisses { get; init; }
+
+    /// <summary>
+    /// Performance metrics by operation type.
+    /// </summary>
+    public Dictionary<string, DatabaseOperationMetricsSnapshot> Operations { get; init; } = new();
+}
+
+/// <summary>
+/// Snapshot of performance metrics for a specific database operation.
+/// </summary>
+public sealed record DatabaseOperationMetricsSnapshot
+{
+    /// <summary>
+    /// Total number of operations executed.
+    /// </summary>
+    public long Count { get; init; }
+
+    /// <summary>
+    /// Total execution time in milliseconds.
+    /// </summary>
+    public long TotalTimeMs { get; init; }
+
+    /// <summary>
+    /// Maximum execution time in milliseconds.
+    /// </summary>
+    public long MaxTimeMs { get; init; }
+
+    /// <summary>
+    /// Average execution time in milliseconds.
+    /// </summary>
+    public double AvgTimeMs { get; init; }
+}
+
+/// <summary>
+/// Snapshot of cache performance metrics.
+/// </summary>
+public sealed record CacheMetricsSnapshot
+{
+    /// <summary>
+    /// Total number of cache hits.
+    /// </summary>
+    public long TotalHits { get; init; }
+
+    /// <summary>
+    /// Total number of cache misses.
+    /// </summary>
+    public long TotalMisses { get; init; }
+
+    /// <summary>
+    /// Total number of cache evictions.
+    /// </summary>
+    public long TotalEvictions { get; init; }
+
+    /// <summary>
+    /// Metrics by cache type.
+    /// </summary>
+    public Dictionary<string, CacheTypeMetricsSnapshot> Types { get; init; } = new();
+}
+
+/// <summary>
+/// Snapshot of cache metrics for a specific cache type.
+/// </summary>
+public sealed record CacheTypeMetricsSnapshot
+{
+    /// <summary>
+    /// Number of cache hits for this type.
+    /// </summary>
+    public long Hits { get; init; }
+
+    /// <summary>
+    /// Number of cache misses for this type.
+    /// </summary>
+    public long Misses { get; init; }
+
+    /// <summary>
+    /// Number of evictions for this type.
+    /// </summary>
+    public long Evictions { get; init; }
+}
+
+/// <summary>
+/// Default database metrics provider when no implementation is registered.
+/// </summary>
+internal sealed class NullDatabasePerformanceMetricsProvider : IDatabasePerformanceMetricsProvider
+{
+    public DatabasePerformanceMetricsSnapshot GetMetrics() => new();
+}

src/Honua.Core/Features/Infrastructure/Monitoring/PerformanceMonitoringServiceCollectionExtensions.cs

@@ -2,6 +2,7 @@
 // Licensed under the Elastic License 2.0. See LICENSE in the project root.
 
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
 
 namespace Honua.Core.Features.Infrastructure.Monitoring;
 
@@ -17,7 +18,10 @@ public static class PerformanceMonitoringServiceCollectionExtensions
     /// <returns>The service collection for chaining</returns>
     public static IServiceCollection AddDefaultPerformanceMonitor(this IServiceCollection services)
     {
-        services.AddSingleton<IPerformanceMonitor, DefaultPerformanceMonitor>();
+        services.AddSingleton<DefaultPerformanceMonitor>();
+        services.AddSingleton<IPerformanceMonitor>(sp => sp.GetRequiredService<DefaultPerformanceMonitor>());
+        services.AddSingleton<ICacheMetricsSnapshotProvider>(sp => sp.GetRequiredService<DefaultPerformanceMonitor>());
+        services.TryAddSingleton<IDatabasePerformanceMetricsProvider, NullDatabasePerformanceMetricsProvider>();
         return services;
     }
 }