feat: add response compression, health checks, traceId in errors, tag-based cache invalidation, per-version OpenAPI docs, and code quality improvements

- Add Brotli + Gzip response compression middleware
- Add Redis and Hangfire health checks on /health/ready
- Surface traceId and correlationId in ProblemDetails error responses
- Add tag-based cache invalidation (SetItemAsync with tags, RemoveByTagAsync) to ICacheService
- Generate per-version OpenAPI documents (configurable via OpenApiOptions.Versions)
- Add AsNoTracking to read-only EF queries in Group handlers and UpdateGroupCommandHandler
- Replace read-then-delete with ExecuteDeleteAsync in session cleanup
- Add explanatory comments to all intentional broad catch blocks across caching, eventing, jobs, auditing, identity, and multitenancy
- Fix MultitenancyOptionsTests to match actual default values

Author: iammukeshm

src/BuildingBlocks/Caching/DistributedCacheService.cs

@@ -47,6 +47,7 @@ public DistributedCacheService(
             if (bytes is null || bytes.Length == 0) return default;
             return JsonSerializer.Deserialize<T>(Utf8.GetString(bytes), JsonOpts);
         }
+        // Graceful degradation: cache failures must not crash the caller — return default and log
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache get failed for key (length={KeyLength})", key.Length);
@@ -64,16 +65,34 @@ public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = defau
             await _cache.SetAsync(key, bytes, BuildEntryOptions(sliding), ct).ConfigureAwait(false);
             LogCached(key);
         }
+        // Graceful degradation: cache failures must not crash the caller
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache set failed for key (length={KeyLength})", key.Length);
         }
     }
 
+    /// <inheritdoc />
+    public async Task SetItemAsync<T>(string key, T value, IReadOnlyList<string> tags, TimeSpan? sliding = default, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(tags);
+        await SetItemAsync(key, value, sliding, ct).ConfigureAwait(false);
+
+        // Store the key in each tag's set so we can invalidate by tag later
+        foreach (var tag in tags)
+        {
+            var tagKey = NormalizeTagKey(tag);
+            var existing = await GetItemAsync<HashSet<string>>(tagKey, ct).ConfigureAwait(false) ?? [];
+            existing.Add(Normalize(key));
+            await SetItemAsync(tagKey, existing, sliding, ct).ConfigureAwait(false);
+        }
+    }
+
     /// <inheritdoc />
     public async Task RemoveItemAsync(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
+        // Graceful degradation: cache failures must not crash the caller
         try { await _cache.RemoveAsync(key, ct).ConfigureAwait(false); }
         catch (Exception ex) when (ex is not OperationCanceledException)
         { _logger.LogWarning(ex, "Cache remove failed for {Key}", key); }
@@ -88,10 +107,36 @@ public async Task RefreshItemAsync(string key, CancellationToken ct = default)
             await _cache.RefreshAsync(key, ct).ConfigureAwait(false);
             LogRefreshed(key);
         }
+        // Graceful degradation: cache operations must not crash the caller
         catch (Exception ex) when (ex is not OperationCanceledException)
         { _logger.LogWarning(ex, "Cache refresh failed for {Key}", key); }
     }
 
+    /// <inheritdoc />
+    public async Task RemoveByTagAsync(string tag, CancellationToken ct = default)
+    {
+        var tagKey = NormalizeTagKey(tag);
+        var keys = await GetItemAsync<HashSet<string>>(tagKey, ct).ConfigureAwait(false);
+        if (keys is null || keys.Count == 0) return;
+
+        foreach (var key in keys)
+        {
+            try
+            {
+                await _cache.RemoveAsync(key, ct).ConfigureAwait(false);
+            }
+            // Graceful degradation: best-effort removal per key
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                _logger.LogWarning(ex, "Cache remove by tag failed for {Key}", key);
+            }
+        }
+
+        await RemoveItemAsync(tagKey, ct).ConfigureAwait(false);
+    }
+
+    private string NormalizeTagKey(string tag) => Normalize($"__tag:{tag}");
+
     /// <summary>
     /// Builds cache entry options with configured expiration settings.
     /// </summary>

src/BuildingBlocks/Caching/HybridCacheService.cs

@@ -80,6 +80,7 @@ public HybridCacheService(
 
             return value;
         }
+        // Graceful degradation: cache failures must not crash the caller — return default and log
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache get failed for key (length={KeyLength})", key.Length);
@@ -105,12 +106,29 @@ public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = defau
 
             LogCachedBoth(key);
         }
+        // Graceful degradation: cache failures must not crash the caller
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache set failed for key (length={KeyLength})", key.Length);
         }
     }
 
+    /// <inheritdoc />
+    public async Task SetItemAsync<T>(string key, T value, IReadOnlyList<string> tags, TimeSpan? sliding = default, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(tags);
+        await SetItemAsync(key, value, sliding, ct).ConfigureAwait(false);
+
+        // Store the key in each tag's set so we can invalidate by tag later
+        foreach (var tag in tags)
+        {
+            var tagKey = NormalizeTagKey(tag);
+            var existing = await GetItemAsync<HashSet<string>>(tagKey, ct).ConfigureAwait(false) ?? [];
+            existing.Add(Normalize(key));
+            await SetItemAsync(tagKey, existing, sliding, ct).ConfigureAwait(false);
+        }
+    }
+
     /// <inheritdoc />
     /// <remarks>
     /// Removes from both L1 memory cache and L2 distributed cache.
@@ -125,6 +143,7 @@ public async Task RemoveItemAsync(string key, CancellationToken ct = default)
             await _distributedCache.RemoveAsync(key, ct).ConfigureAwait(false);
             LogRemovedBoth(key);
         }
+        // Graceful degradation: cache failures must not crash the caller
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache remove failed for {Key}", key);
@@ -140,12 +159,40 @@ public async Task RefreshItemAsync(string key, CancellationToken ct = default)
             await _distributedCache.RefreshAsync(key, ct).ConfigureAwait(false);
             LogRefreshed(key);
         }
+        // Graceful degradation: cache operations must not crash the caller
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogWarning(ex, "Cache refresh failed for {Key}", key);
         }
     }
 
+    /// <inheritdoc />
+    public async Task RemoveByTagAsync(string tag, CancellationToken ct = default)
+    {
+        var tagKey = NormalizeTagKey(tag);
+        var keys = await GetItemAsync<HashSet<string>>(tagKey, ct).ConfigureAwait(false);
+        if (keys is null || keys.Count == 0) return;
+
+        foreach (var key in keys)
+        {
+            try
+            {
+                _memoryCache.Remove(key);
+                await _distributedCache.RemoveAsync(key, ct).ConfigureAwait(false);
+            }
+            // Graceful degradation: best-effort removal per key
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                _logger.LogWarning(ex, "Cache remove by tag failed for {Key}", key);
+            }
+        }
+
+        _memoryCache.Remove(tagKey);
+        await _distributedCache.RemoveAsync(tagKey, ct).ConfigureAwait(false);
+    }
+
+    private string NormalizeTagKey(string tag) => Normalize($"__tag:{tag}");
+
     /// <summary>
     /// Builds distributed cache entry options with configured expiration settings.
     /// </summary>

src/BuildingBlocks/Caching/ICacheService.cs

@@ -25,6 +25,17 @@ public interface ICacheService
     /// <param name="ct">Cancellation token for the operation.</param>
     Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = default, CancellationToken ct = default);
 
+    /// <summary>
+    /// Asynchronously stores an item in the cache with associated tags for group invalidation.
+    /// </summary>
+    /// <typeparam name="T">The type of the item to cache.</typeparam>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="value">The value to cache.</param>
+    /// <param name="tags">Tags to associate with this cache entry for group invalidation.</param>
+    /// <param name="sliding">Optional sliding expiration. Uses default if not specified.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
+    Task SetItemAsync<T>(string key, T value, IReadOnlyList<string> tags, TimeSpan? sliding = default, CancellationToken ct = default);
+
     /// <summary>
     /// Asynchronously removes an item from the cache.
     /// </summary>
@@ -39,4 +50,10 @@ public interface ICacheService
     /// <param name="ct">Cancellation token for the operation.</param>
     Task RefreshItemAsync(string key, CancellationToken ct = default);
 
+    /// <summary>
+    /// Asynchronously removes all cache entries associated with the specified tag.
+    /// </summary>
+    /// <param name="tag">The tag whose associated entries should be removed.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
+    Task RemoveByTagAsync(string tag, CancellationToken ct = default);
 }

src/BuildingBlocks/Eventing/RabbitMq/RabbitMqEventBus.cs

@@ -198,6 +198,7 @@ private async Task DisposeConnectionAsync()
                 await _channel.CloseAsync().ConfigureAwait(false);
                 _channel.Dispose();
             }
+            // Cleanup must not throw: connection may already be closed or faulted
             catch (Exception ex)
             {
                 _logger.LogDebug(ex, "Error closing RabbitMQ channel during cleanup");
@@ -213,6 +214,7 @@ private async Task DisposeConnectionAsync()
                 await _connection.CloseAsync().ConfigureAwait(false);
                 _connection.Dispose();
             }
+            // Cleanup must not throw: connection may already be closed or faulted
             catch (Exception ex)
             {
                 _logger.LogDebug(ex, "Error closing RabbitMQ connection during cleanup");

src/BuildingBlocks/Jobs/HangfireStaleLockCleanupService.cs

@@ -50,6 +50,7 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
                 _logger.LogWarning("Cleaned up {Count} stale Hangfire locks", deleted);
             }
         }
+        // Best-effort cleanup: table may not exist yet on first startup, or DB may be temporarily unreachable
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             _logger.LogDebug(ex, "Could not cleanup stale Hangfire locks (table may not exist yet)");

src/BuildingBlocks/Web/Exceptions/GlobalExceptionHandler.cs

@@ -1,4 +1,5 @@
-using FSH.Framework.Core.Exceptions;
+using System.Diagnostics;
+using FSH.Framework.Core.Exceptions;
 using Microsoft.AspNetCore.Diagnostics;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@@ -62,6 +63,14 @@ public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception e
 
         httpContext.Response.StatusCode = statusCode;
 
+        // Surface trace and correlation IDs so clients/support can correlate errors to traces
+        var traceId = Activity.Current?.TraceId.ToString() ?? httpContext.TraceIdentifier;
+        problemDetails.Extensions["traceId"] = traceId;
+
+        var correlationId = httpContext.Request.Headers["X-Correlation-ID"].FirstOrDefault()
+            ?? httpContext.TraceIdentifier;
+        problemDetails.Extensions["correlationId"] = correlationId;
+
         LogContext.PushProperty("exception_title", problemDetails.Title);
         LogContext.PushProperty("exception_detail", problemDetails.Detail);
         LogContext.PushProperty("exception_statusCode", problemDetails.Status);

src/BuildingBlocks/Web/Extensions.cs

@@ -18,12 +18,14 @@
 using FSH.Framework.Web.RateLimiting;
 using FSH.Framework.Web.Security;
 using FSH.Framework.Web.Versioning;
-using Mediator;
 using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.ResponseCompression;
+using Microsoft.Extensions.Caching.Distributed;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
 using Microsoft.Extensions.Hosting;
+using Mediator;
 
 namespace FSH.Framework.Web;
 
@@ -38,6 +40,17 @@ public static IHostApplicationBuilder AddHeroPlatform(this IHostApplicationBuild
 
         builder.Services.AddScoped<CurrentUserMiddleware>();
 
+        builder.Services.AddResponseCompression(options =>
+        {
+            options.EnableForHttps = true;
+            options.Providers.Add<BrotliCompressionProvider>();
+            options.Providers.Add<GzipCompressionProvider>();
+        });
+        builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
+        {
+            options.Level = System.IO.Compression.CompressionLevel.Fastest;
+        });
+
         builder.AddHeroLogging();
         if (options.EnableOpenTelemetry)
         {
@@ -68,6 +81,7 @@ public static IHostApplicationBuilder AddHeroPlatform(this IHostApplicationBuild
         if (options.EnableJobs)
         {
             builder.Services.AddHeroJobs();
+            builder.Services.AddHealthChecks().AddCheck<HangfireHealthCheck>("hangfire");
         }
 
         if (options.EnableMailing)
@@ -78,6 +92,11 @@ public static IHostApplicationBuilder AddHeroPlatform(this IHostApplicationBuild
         if (options.EnableCaching)
         {
             builder.Services.AddHeroCaching(builder.Configuration);
+            var cacheConfig = builder.Configuration.GetSection(nameof(CachingOptions)).Get<CachingOptions>();
+            if (cacheConfig is not null && !string.IsNullOrEmpty(cacheConfig.Redis))
+            {
+                builder.Services.AddHealthChecks().AddCheck<RedisHealthCheck>("redis");
+            }
         }
 
         if (options.EnableFeatureFlags)
@@ -116,6 +135,7 @@ public static WebApplication UseHeroPlatform(this WebApplication app, Action<Fsh
         var openApiEnabled = options.UseOpenApi && IsOpenApiEnabled(app.Configuration);
 
         app.UseExceptionHandler();
+        app.UseResponseCompression();
         app.UseHttpsRedirection();
 
         app.UseHeroSecurityHeaders();

src/BuildingBlocks/Web/Health/HangfireHealthCheck.cs

@@ -0,0 +1,26 @@
+using Hangfire;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace FSH.Framework.Web.Health;
+
+/// <summary>
+/// Health check that verifies Hangfire storage is accessible.
+/// </summary>
+public sealed class HangfireHealthCheck : IHealthCheck
+{
+    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var storage = JobStorage.Current;
+            using var connection = storage.GetConnection();
+            return Task.FromResult(HealthCheckResult.Healthy("Hangfire storage is accessible."));
+        }
+#pragma warning disable CA1031 // Health checks must catch all exceptions to report degraded/unhealthy
+        catch (Exception ex)
+        {
+            return Task.FromResult(HealthCheckResult.Unhealthy("Hangfire storage is not accessible.", ex));
+        }
+#pragma warning restore CA1031
+    }
+}

src/BuildingBlocks/Web/Health/RedisHealthCheck.cs

@@ -0,0 +1,38 @@
+using Microsoft.Extensions.Caching.Distributed;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace FSH.Framework.Web.Health;
+
+/// <summary>
+/// Health check that verifies Redis connectivity by performing a round-trip set/remove.
+/// </summary>
+public sealed class RedisHealthCheck : IHealthCheck
+{
+    private readonly IDistributedCache _cache;
+
+    public RedisHealthCheck(IDistributedCache cache)
+    {
+        _cache = cache;
+    }
+
+    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            const string key = "__health_check__";
+            var options = new DistributedCacheEntryOptions
+            {
+                AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(5)
+            };
+            await _cache.SetStringAsync(key, "ok", options, cancellationToken).ConfigureAwait(false);
+            await _cache.RemoveAsync(key, cancellationToken).ConfigureAwait(false);
+            return HealthCheckResult.Healthy("Redis is accessible.");
+        }
+#pragma warning disable CA1031 // Health checks must catch all exceptions to report degraded/unhealthy
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy("Redis is not accessible.", ex);
+        }
+#pragma warning restore CA1031
+    }
+}

src/BuildingBlocks/Web/Idempotency/IdempotencyEndpointFilter.cs

@@ -85,6 +85,7 @@ public sealed class IdempotencyEndpointFilter : IEndpointFilter
 
             await cache.SetItemAsync(cacheKey, responseToCache, options.DefaultTtl, httpContext.RequestAborted).ConfigureAwait(false);
         }
+        // Best-effort caching: idempotency replay is a convenience, not a correctness requirement
         catch (Exception ex) when (ex is not OperationCanceledException)
         {
             logger.LogWarning(ex, "Failed to cache idempotent response for key {KeyHash}", HashKey(idempotencyKey));