feat(dcr): Add Redis storage support for multi-replica deployments (#109)

- [x] Add file and Redis storage backends for DCR credentials
- [x] Implement storage abstraction with FileStore and RedisStore
- [x] Add factory function for automatic backend selection (auto/file/redis)
- [x] Integrate DCR credentials cache into UniversalCacheManager
- [x] Add comprehensive tests for storage backends and factory
- [x] Update configuration schema with storage backend options
- [x] Update documentation with multi-replica deployment guidance
- [x] Add Redis key prefix configuration for credential isolation

.github/workflows/release.yml

@@ -11,7 +11,9 @@ on:
   workflow_dispatch:
 
 permissions:
+  id-token: write
   contents: write
+  packages: write
 
 jobs:
   release:

.goreleaser.yaml

@@ -47,3 +47,14 @@ release:
   name_template: "v{{ .Version }}"
   draft: false
   prerelease: auto
+
+signs:
+  - cmd: cosign
+    signature: "${artifact}.sigstore.json"
+    args:
+      - sign-blob
+      - "--bundle=${signature}"
+      - "${artifact}"
+      - "--yes"
+    artifacts: checksum
+    output: true

.traefik.yml

@@ -1630,3 +1630,234 @@ configuration:
 
           Default: 30 seconds
         required: false
+
+  dynamicClientRegistration:
+    type: object
+    description: |
+      Configuration for OIDC Dynamic Client Registration (RFC 7591/7592).
+
+      Dynamic Client Registration allows the middleware to automatically register
+      itself as an OAuth 2.0 client with the OIDC provider, eliminating the need
+      to manually create and manage client credentials.
+
+      This is particularly useful for:
+      - Automated deployments where manual client creation is impractical
+      - Multi-tenant scenarios requiring per-deployment client isolation
+      - Development and testing environments
+      - Kubernetes environments with multiple replicas
+
+      For multi-replica deployments (Kubernetes), enable Redis storage to share
+      credentials across all instances and prevent registration race conditions.
+
+      Example configuration:
+      ```yaml
+      dynamicClientRegistration:
+        enabled: true
+        persistCredentials: true
+        storageBackend: "redis"  # Use Redis for distributed storage
+        clientMetadata:
+          redirect_uris:
+            - https://app.example.com/oauth2/callback
+          client_name: "My Application"
+          application_type: "web"
+      ```
+    required: false
+    properties:
+      enabled:
+        type: boolean
+        description: |
+          Enable dynamic client registration with the OIDC provider.
+          When enabled and clientID is not set, the middleware will automatically
+          register itself with the provider using the configuration in clientMetadata.
+
+          Default: false
+        required: false
+
+      persistCredentials:
+        type: boolean
+        description: |
+          Enable persistence of client credentials after registration.
+          When enabled, credentials are saved to the configured storage backend
+          and reloaded on restart to avoid re-registration.
+
+          Default: false
+        required: false
+
+      storageBackend:
+        type: string
+        description: |
+          Storage backend for persisting DCR credentials.
+
+          Options:
+          - "file": Store credentials in a local file (default for backward compatibility)
+          - "redis": Store credentials in Redis (recommended for multi-replica deployments)
+          - "auto": Use Redis if available, fall back to file storage
+
+          For Kubernetes deployments with multiple replicas, use "redis" to ensure
+          all instances share the same client credentials and prevent registration
+          race conditions where each replica registers its own client.
+
+          Default: "auto"
+        required: false
+        enum:
+          - file
+          - redis
+          - auto
+
+      credentialsFile:
+        type: string
+        description: |
+          Path to store client credentials when using file-based storage.
+          The file will be created with restrictive permissions (0600).
+
+          Default: "/tmp/oidc-client-credentials.json"
+        required: false
+
+      redisKeyPrefix:
+        type: string
+        description: |
+          Prefix for Redis keys when using Redis storage.
+          Useful for isolating credentials between different applications
+          or environments sharing the same Redis instance.
+
+          Default: "dcr:creds:"
+        required: false
+
+      registrationEndpoint:
+        type: string
+        description: |
+          Override the registration endpoint URL.
+          If not specified, the endpoint will be discovered from provider metadata.
+
+          Some providers may not advertise their registration endpoint in metadata,
+          in which case you need to specify it explicitly.
+
+          Example: "https://auth.example.com/oauth/register"
+        required: false
+
+      initialAccessToken:
+        type: string
+        description: |
+          Initial Access Token for protected registration endpoints.
+          Some providers require an access token to authorize client registration.
+
+          If your provider requires authentication for registration, obtain an
+          initial access token from the provider and configure it here.
+
+          For Kubernetes, you can use secret references:
+          urn:k8s:secret:namespace:secret-name:key
+        required: false
+
+      clientMetadata:
+        type: object
+        description: |
+          Client metadata to include in the registration request (RFC 7591).
+          This defines the properties of the OAuth 2.0 client to be registered.
+        required: false
+        properties:
+          redirect_uris:
+            type: array
+            description: |
+              Array of redirect URIs for the client. Required for registration.
+              These must match the callback URLs that will be used in authentication flows.
+
+              Example: ["https://app.example.com/oauth2/callback"]
+            required: true
+            items:
+              type: string
+
+          client_name:
+            type: string
+            description: |
+              Human-readable name of the client.
+              This is typically displayed in consent screens.
+
+              Example: "My Application"
+            required: false
+
+          application_type:
+            type: string
+            description: |
+              Type of application. Affects security defaults.
+
+              Options:
+              - "web": Server-side web application (default)
+              - "native": Native/mobile application
+
+              Default: "web"
+            required: false
+
+          grant_types:
+            type: array
+            description: |
+              OAuth 2.0 grant types the client will use.
+
+              Default: ["authorization_code", "refresh_token"]
+            required: false
+            items:
+              type: string
+
+          response_types:
+            type: array
+            description: |
+              OAuth 2.0 response types the client will use.
+
+              Default: ["code"]
+            required: false
+            items:
+              type: string
+
+          token_endpoint_auth_method:
+            type: string
+            description: |
+              Authentication method for the token endpoint.
+
+              Options:
+              - "client_secret_basic": HTTP Basic authentication (default)
+              - "client_secret_post": Client credentials in POST body
+              - "none": Public client (no authentication)
+
+              Default: "client_secret_basic"
+            required: false
+
+          scope:
+            type: string
+            description: |
+              Space-separated list of scopes the client is authorized to request.
+
+              Example: "openid profile email"
+            required: false
+
+          contacts:
+            type: array
+            description: |
+              Array of contact email addresses for the client administrator.
+
+              Example: ["admin@example.com"]
+            required: false
+            items:
+              type: string
+
+          logo_uri:
+            type: string
+            description: |
+              URL to the client's logo image for consent screens.
+            required: false
+
+          client_uri:
+            type: string
+            description: |
+              URL to the client's home page.
+            required: false
+
+          policy_uri:
+            type: string
+            description: |
+              URL to the client's privacy policy.
+            required: false
+
+          tos_uri:
+            type: string
+            description: |
+              URL to the client's terms of service.
+            required: false

README.md

@@ -8,7 +8,7 @@ The Traefik OIDC middleware provides a complete OIDC authentication solution wit
 
 - **Universal provider support**: Works with 9+ OIDC providers including Google, Azure AD, Auth0, Okta, Keycloak, AWS Cognito, GitLab, and more
 - **Automatic provider detection**: Automatically detects and configures provider-specific settings
-- **Dynamic Client Registration (RFC 7591)**: Automatic client registration with OIDC providers without manual pre-registration
+- **Dynamic Client Registration (RFC 7591)**: Automatic client registration with OIDC providers without manual pre-registration, with Redis storage support for multi-replica deployments
 - **Automatic scope filtering**: Intelligently filters OAuth scopes based on provider capabilities declared in OIDC discovery documents, preventing authentication failures with unsupported scopes
 - **Security headers**: Comprehensive security headers with CORS, CSP, HSTS, and custom profiles
 - **Domain restrictions**: Limit access to specific email domains or individual users
@@ -82,6 +82,19 @@ experimental:
 
 2. Configure the middleware in your dynamic configuration (see examples below).
 
+### Verifying Release Signatures
+
+All release checksums are signed with [cosign](https://github.com/sigstore/cosign) using keyless signing. To verify:
+
+```bash
+# Download the checksum file and its sigstore bundle from the release
+cosign verify-blob \
+  --certificate-identity-regexp "https://github.com/lukaszraczylo/traefikoidc/.*" \
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+  --bundle "traefikoidc_v<version>_checksums.txt.sigstore.json" \
+  traefikoidc_v<version>_checksums.txt
+```
+
 ### Local Development with Docker Compose
 
 For local development or testing, you can use the provided Docker Compose setup:

audience_test.go

@@ -84,8 +84,8 @@ func TestAudienceValidation(t *testing.T) {
 	tests := []struct {
 		name          string
 		audience      string
-		expectError   bool
 		errorContains string
+		expectError   bool
 	}{
 		{
 			name:        "valid custom audience URL",
@@ -163,8 +163,8 @@ func TestConfigAudienceValidation(t *testing.T) {
 	tests := []struct {
 		name        string
 		audience    string
-		wantErr     bool
 		errContains string
+		wantErr     bool
 	}{
 		{
 			name:     "Empty audience is valid for backward compatibility",
@@ -732,11 +732,11 @@ func TestJWTAudienceVerification(t *testing.T) {
 	tokenCache := tc.addTokenCache(NewTokenCache())
 
 	tests := []struct {
+		tokenAudience   interface{}
 		name            string
 		configAudience  string
-		tokenAudience   interface{}
-		wantErr         bool
 		errContains     string
+		wantErr         bool
 		skipReplayCheck bool
 	}{
 		{

auth_flow_behaviour_test.go

@@ -253,8 +253,8 @@ func (s *AuthFlowBehaviourSuite) TestPrepareSessionForAuthentication_WithPKCE()
 // TestIsAjaxRequest tests AJAX request detection
 func (s *AuthFlowBehaviourSuite) TestIsAjaxRequest() {
 	testCases := []struct {
-		name       string
 		headers    map[string]string
+		name       string
 		expectAjax bool
 	}{
 		{

autocleanup.go

@@ -222,17 +222,16 @@ func (bt *BackgroundTask) run() {
 // TaskCircuitBreaker implements circuit breaker pattern for background task creation
 // It limits concurrent task execution and tracks failures to prevent system overload
 type TaskCircuitBreaker struct {
-	state            int32 // CircuitBreakerState
-	failureCount     int32
-	lastFailureTime  int64 // Unix timestamp
-	failureThreshold int32
-	timeout          time.Duration
 	logger           *Logger
-	// Concurrency limiting
-	concurrentTasks int32               // Current number of running tasks
-	maxConcurrent   int32               // Maximum concurrent tasks allowed
-	activeTasks     map[string]struct{} // Track active task names
-	tasksMu         sync.RWMutex        // Separate mutex for task tracking
+	activeTasks      map[string]struct{}
+	lastFailureTime  int64
+	timeout          time.Duration
+	tasksMu          sync.RWMutex
+	state            int32
+	failureCount     int32
+	failureThreshold int32
+	concurrentTasks  int32
+	maxConcurrent    int32
 }
 
 // NewTaskCircuitBreaker creates a new circuit breaker for background tasks
@@ -266,18 +265,21 @@ func (cb *TaskCircuitBreaker) CanCreateTask(taskName string) error {
 	max := atomic.LoadInt32(&cb.maxConcurrent)
 
 	// For cleanup tasks, be more restrictive (singleton-like behavior)
+	// However, allow distinct realm-specific tasks (e.g., singleton-metadata-refresh-abc123 vs singleton-metadata-refresh-def456)
 	if strings.Contains(taskName, "cleanup") || strings.Contains(taskName, "singleton") {
 		cb.tasksMu.RLock()
-		hasCleanupTask := false
+		hasSameTask := false
 		for activeTask := range cb.activeTasks {
-			if strings.Contains(activeTask, "cleanup") || strings.Contains(activeTask, "singleton") {
-				hasCleanupTask = true
+			// Only block if the EXACT same task is already running
+			// This allows realm-specific tasks like singleton-metadata-refresh-{hash} to run concurrently
+			if activeTask == taskName {
+				hasSameTask = true
 				break
 			}
 		}
 		cb.tasksMu.RUnlock()
 
-		if hasCleanupTask {
+		if hasSameTask {
 			return fmt.Errorf("cleanup/singleton task already running: %s", taskName)
 		}
 	}
@@ -377,9 +379,9 @@ func (cb *TaskCircuitBreaker) OnTaskFailure(taskName string, err error) {
 // TaskRegistry maintains a registry of all active background tasks to prevent duplicates
 type TaskRegistry struct {
 	tasks  map[string]*BackgroundTask
-	mu     sync.RWMutex
 	cb     *TaskCircuitBreaker
 	logger *Logger
+	mu     sync.RWMutex
 }
 
 // GlobalTaskRegistry is the singleton instance for managing all background tasks

azure_oidc_test.go

@@ -330,12 +330,12 @@ func TestValidateGoogleTokens(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
-		name            string
 		setupSession    func() *SessionData
+		name            string
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name: "ValidGoogleTokens",
@@ -476,13 +476,13 @@ func TestIsUserAuthenticated(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
+		setupSession    func() *SessionData
 		name            string
 		providerType    string
-		setupSession    func() *SessionData
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name:         "AzureProvider",
@@ -660,12 +660,12 @@ func TestValidateAzureTokensEdgeCases(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
-		name            string
 		setupSession    func() *SessionData
+		name            string
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name: "UnauthenticatedWithRefreshToken",

background_tasks_ultra_test.go

@@ -97,15 +97,15 @@ func TestMemoryMonitorComprehensive(t *testing.T) {
 
 	t.Run("String method returns pressure name", func(t *testing.T) {
 		pressures := []struct {
-			level MemoryPressureLevel
 			name  string
+			level MemoryPressureLevel
 		}{
-			{MemoryPressureNone, "None"},
-			{MemoryPressureLow, "Low"},
-			{MemoryPressureModerate, "Moderate"},
-			{MemoryPressureHigh, "High"},
-			{MemoryPressureCritical, "Critical"},
-			{MemoryPressureLevel(999), "Unknown"},
+			{level: MemoryPressureNone, name: "None"},
+			{level: MemoryPressureLow, name: "Low"},
+			{level: MemoryPressureModerate, name: "Moderate"},
+			{level: MemoryPressureHigh, name: "High"},
+			{level: MemoryPressureCritical, name: "Critical"},
+			{level: MemoryPressureLevel(999), name: "Unknown"},
 		}
 
 		for _, p := range pressures {

cache_compat.go

@@ -155,9 +155,9 @@ type CacheStrategy interface {
 
 // CacheEntry for backward compatibility
 type CacheEntry struct {
-	Key       string
-	Value     interface{}
 	ExpiresAt time.Time
+	Value     interface{}
+	Key       string
 }
 
 // Cache is an alias for backward compatibility
@@ -175,10 +175,10 @@ func NewOptimizedCacheWithConfig(config OptimizedCacheConfig) *CacheInterfaceWra
 
 // ListNode for backward compatibility
 type ListNode struct {
-	Key   string
 	Value interface{}
 	Next  *ListNode
 	Prev  *ListNode
+	Key   string
 }
 
 // NewFixedMetadataCache creates a metadata cache with fixed configuration

cache_manager.go

@@ -61,7 +61,7 @@ func GetGlobalCacheManagerWithConfig(wg *sync.WaitGroup, config *Config) *CacheM
 func (cm *CacheManager) GetSharedTokenBlacklist() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetBlacklistCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetBlacklistCache(), managed: true}
 }
 
 // GetSharedTokenCache returns the shared token cache
@@ -93,7 +93,7 @@ func (cm *CacheManager) GetSharedJWKCache() JWKCacheInterface {
 func (cm *CacheManager) GetSharedIntrospectionCache() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetIntrospectionCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetIntrospectionCache(), managed: true}
 }
 
 // GetSharedTokenTypeCache returns the shared token type cache
@@ -101,7 +101,7 @@ func (cm *CacheManager) GetSharedIntrospectionCache() CacheInterface {
 func (cm *CacheManager) GetSharedTokenTypeCache() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetTokenTypeCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetTokenTypeCache(), managed: true}
 }
 
 // Close gracefully shuts down all cache components
@@ -121,7 +121,8 @@ func CleanupGlobalCacheManager() error {
 
 // CacheInterfaceWrapper wraps UniversalCache to implement CacheInterface
 type CacheInterfaceWrapper struct {
-	cache *UniversalCache
+	cache   *UniversalCache
+	managed bool // If true, cache is managed globally and Close() is a no-op
 }
 
 // Set stores a value
@@ -149,9 +150,15 @@ func (c *CacheInterfaceWrapper) Cleanup() {
 	c.cache.Cleanup()
 }
 
-// Close shuts down the cache
+// Close shuts down the cache if it's not managed globally.
+// For managed caches (from UniversalCacheManager), this is a no-op to prevent log flooding
+// when multiple plugin instances are closed during Traefik configuration reloads.
 func (c *CacheInterfaceWrapper) Close() {
-	// Close the underlying cache to stop goroutines
+	if c.managed {
+		// Cache is managed globally by UniversalCacheManager, so we don't close it here.
+		return
+	}
+	// Standalone cache - close it properly to stop cleanup goroutines
 	if c.cache != nil {
 		_ = c.cache.Close() // Safe to ignore: closing cache is best-effort during shutdown
 	}

cache_test.go

@@ -19,16 +19,16 @@ import (
 
 // CacheTestCase represents a comprehensive test case for cache operations
 type CacheTestCase struct {
+	setup      func(*TestFramework)
+	execute    func(*TestFramework) error
+	validate   func(*testing.T, error, *TestFramework)
+	cleanup    func(*TestFramework)
 	name       string
-	cacheType  string                                  // "universal", "metadata", "bounded"
-	operation  string                                  // "get", "set", "evict", "cleanup"
-	setup      func(*TestFramework)                    // Pre-test setup
-	execute    func(*TestFramework) error              // Test execution
-	validate   func(*testing.T, error, *TestFramework) // Validation logic
-	cleanup    func(*TestFramework)                    // Post-test cleanup
-	timeout    time.Duration                           // Test timeout
-	parallel   bool                                    // Can run in parallel
-	skipReason string                                  // Optional reason to skip
+	cacheType  string
+	operation  string
+	skipReason string
+	timeout    time.Duration
+	parallel   bool
 }
 
 // createTestCacheConfig creates a standard test configuration
@@ -219,6 +219,159 @@ func TestCacheInterfaceWrapper_Close(t *testing.T) {
 	nilWrapper.Close()
 }
 
+// TestCacheInterfaceWrapper_ManagedClose_Regression tests that managed cache wrappers
+// don't close the underlying cache when Close() is called. This is a regression test
+// for issue #105 where multiple plugin instances closing shared caches caused log flooding.
+func TestCacheInterfaceWrapper_ManagedClose_Regression(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	// Get a managed cache wrapper
+	cache := cm.GetSharedTokenBlacklist()
+	wrapper, ok := cache.(*CacheInterfaceWrapper)
+	if !ok {
+		t.Fatal("Expected CacheInterfaceWrapper")
+	}
+
+	// Verify it's marked as managed
+	if !wrapper.managed {
+		t.Error("Expected shared cache wrapper to be marked as managed")
+	}
+
+	// Set some data before Close
+	cache.Set("test-key", "test-value", time.Hour)
+
+	// Close the wrapper (should be a no-op for managed caches)
+	wrapper.Close()
+
+	// Verify the cache is still operational after Close
+	value, found := cache.Get("test-key")
+	if !found {
+		t.Error("Expected cache to still work after Close() on managed wrapper")
+	}
+	if value != "test-value" {
+		t.Errorf("Expected 'test-value', got %v", value)
+	}
+
+	// Can still set new values
+	cache.Set("new-key", "new-value", time.Hour)
+	newValue, found := cache.Get("new-key")
+	if !found || newValue != "new-value" {
+		t.Error("Expected to be able to set new values after Close() on managed wrapper")
+	}
+}
+
+// TestCacheInterfaceWrapper_StandaloneClose tests that standalone cache wrappers
+// properly close the underlying cache when Close() is called.
+func TestCacheInterfaceWrapper_StandaloneClose(t *testing.T) {
+	// Create a standalone cache (not from the global cache manager)
+	standaloneCache := NewCache()
+
+	wrapper, ok := standaloneCache.(*CacheInterfaceWrapper)
+	if !ok {
+		t.Fatal("Expected CacheInterfaceWrapper")
+	}
+
+	// Verify it's NOT marked as managed
+	if wrapper.managed {
+		t.Error("Expected standalone cache wrapper to NOT be marked as managed")
+	}
+
+	// Set some data
+	standaloneCache.Set("test-key", "test-value", time.Hour)
+
+	// Get baseline goroutine count
+	baselineGoroutines := runtime.NumGoroutine()
+
+	// Close the wrapper (should actually close the underlying cache)
+	wrapper.Close()
+
+	// Give cleanup goroutine time to stop
+	time.Sleep(100 * time.Millisecond)
+
+	// Goroutine count should decrease (cleanup routine stopped)
+	finalGoroutines := runtime.NumGoroutine()
+	if finalGoroutines > baselineGoroutines {
+		// This is acceptable - other tests might have started goroutines
+		t.Logf("Goroutine count: baseline=%d, final=%d", baselineGoroutines, finalGoroutines)
+	}
+}
+
+// TestCacheInterfaceWrapper_MultipleInstancesClose_Regression tests that multiple
+// plugin instances can close their cache wrappers without affecting shared caches.
+// This is a regression test for issue #105.
+func TestCacheInterfaceWrapper_MultipleInstancesClose_Regression(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	// Simulate multiple plugin instances getting cache references
+	instances := make([]*CacheInterfaceWrapper, 5)
+	for i := 0; i < 5; i++ {
+		cache := cm.GetSharedTokenBlacklist()
+		wrapper, ok := cache.(*CacheInterfaceWrapper)
+		if !ok {
+			t.Fatal("Expected CacheInterfaceWrapper")
+		}
+		instances[i] = wrapper
+
+		// Each instance might set some data
+		cache.Set(fmt.Sprintf("instance-%d-key", i), fmt.Sprintf("value-%d", i), time.Hour)
+	}
+
+	// Close all instances (simulating plugin shutdown/reload)
+	for _, wrapper := range instances {
+		wrapper.Close()
+	}
+
+	// The shared cache should still work after all instances closed their wrappers
+	newCache := cm.GetSharedTokenBlacklist()
+
+	// Data set by earlier instances should still be accessible
+	for i := 0; i < 5; i++ {
+		key := fmt.Sprintf("instance-%d-key", i)
+		value, found := newCache.Get(key)
+		if !found {
+			t.Errorf("Expected data from instance %d to still be accessible", i)
+		}
+		expectedValue := fmt.Sprintf("value-%d", i)
+		if value != expectedValue {
+			t.Errorf("Expected '%s', got '%v'", expectedValue, value)
+		}
+	}
+
+	// Should be able to add new data
+	newCache.Set("after-close-key", "after-close-value", time.Hour)
+	value, found := newCache.Get("after-close-key")
+	if !found || value != "after-close-value" {
+		t.Error("Expected to be able to use cache after all wrapper Close() calls")
+	}
+}
+
+// TestAllSharedCachesMarkedAsManaged verifies all shared cache getters
+// return managed wrappers to prevent the log flooding issue.
+func TestAllSharedCachesMarkedAsManaged(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	tests := []struct {
+		name  string
+		cache CacheInterface
+	}{
+		{"TokenBlacklist", cm.GetSharedTokenBlacklist()},
+		{"IntrospectionCache", cm.GetSharedIntrospectionCache()},
+		{"TokenTypeCache", cm.GetSharedTokenTypeCache()},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			wrapper, ok := tt.cache.(*CacheInterfaceWrapper)
+			if !ok {
+				t.Fatalf("Expected CacheInterfaceWrapper for %s", tt.name)
+			}
+			if !wrapper.managed {
+				t.Errorf("%s cache wrapper should be marked as managed", tt.name)
+			}
+		})
+	}
+}
+
 func TestCacheInterfaceWrapper_GetStats(t *testing.T) {
 	cm := getTestCacheManager(t)
 	cache := cm.GetSharedTokenBlacklist()
@@ -698,10 +851,10 @@ func TestUnifiedCache_SetMaxSize(t *testing.T) {
 
 func TestNewCacheAdapter(t *testing.T) {
 	tests := []struct {
-		name        string
 		cache       interface{}
-		expectNil   bool
+		name        string
 		description string
+		expectNil   bool
 	}{
 		{
 			name:        "UniversalCache",

dcr_storage_compat.go

@@ -0,0 +1,290 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik
+package traefikoidc
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/lukaszraczylo/traefikoidc/internal/dcrstorage"
+)
+
+// DCRStorageBackend represents the type of storage backend for DCR credentials.
+// Alias for internal package type for backward compatibility.
+type DCRStorageBackend = dcrstorage.StorageBackend
+
+const (
+	// DCRStorageBackendFile uses file-based storage (default for backward compatibility)
+	DCRStorageBackendFile DCRStorageBackend = dcrstorage.StorageBackendFile
+
+	// DCRStorageBackendRedis uses Redis for distributed storage
+	DCRStorageBackendRedis DCRStorageBackend = dcrstorage.StorageBackendRedis
+
+	// DCRStorageBackendAuto automatically selects Redis if available, otherwise file
+	DCRStorageBackendAuto DCRStorageBackend = dcrstorage.StorageBackendAuto
+)
+
+// DCRCredentialsStore defines the interface for storing DCR credentials.
+// This abstraction allows different storage backends (file, Redis) to be used
+// for persisting OIDC Dynamic Client Registration credentials across nodes.
+type DCRCredentialsStore interface {
+	// Save stores the client registration response for a provider
+	// The providerURL is used as a key to support multi-tenant scenarios
+	Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error
+
+	// Load retrieves stored credentials for a provider
+	// Returns nil, nil if no credentials exist (not an error)
+	Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error)
+
+	// Delete removes stored credentials for a provider
+	Delete(ctx context.Context, providerURL string) error
+
+	// Exists checks if credentials exist for a provider
+	Exists(ctx context.Context, providerURL string) (bool, error)
+}
+
+// loggerAdapter adapts our Logger to the dcrstorage.Logger interface
+type loggerAdapter struct {
+	logger *Logger
+}
+
+func (l *loggerAdapter) Debug(msg string)                  { l.logger.Debug("%s", msg) }
+func (l *loggerAdapter) Debugf(format string, args ...any) { l.logger.Debugf(format, args...) }
+func (l *loggerAdapter) Info(msg string)                   { l.logger.Info("%s", msg) }
+func (l *loggerAdapter) Infof(format string, args ...any)  { l.logger.Infof(format, args...) }
+func (l *loggerAdapter) Error(msg string)                  { l.logger.Error("%s", msg) }
+func (l *loggerAdapter) Errorf(format string, args ...any) { l.logger.Errorf(format, args...) }
+
+// cacheAdapter adapts UniversalCache to dcrstorage.Cache interface
+type cacheAdapter struct {
+	cache *UniversalCache
+}
+
+func (c *cacheAdapter) Get(key string) (any, bool) {
+	return c.cache.Get(key)
+}
+
+func (c *cacheAdapter) Set(key string, value any, ttl time.Duration) error {
+	return c.cache.Set(key, value, ttl)
+}
+
+func (c *cacheAdapter) Delete(key string) {
+	c.cache.Delete(key)
+}
+
+// fileStoreWrapper wraps dcrstorage.FileStore to implement DCRCredentialsStore
+type fileStoreWrapper struct {
+	inner *dcrstorage.FileStore
+}
+
+func (w *fileStoreWrapper) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	innerCreds := convertCredsToInternal(creds)
+	return w.inner.Save(ctx, providerURL, innerCreds)
+}
+
+func (w *fileStoreWrapper) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	innerCreds, err := w.inner.Load(ctx, providerURL)
+	if err != nil || innerCreds == nil {
+		return nil, err
+	}
+	return convertCredsFromInternal(innerCreds), nil
+}
+
+func (w *fileStoreWrapper) Delete(ctx context.Context, providerURL string) error {
+	return w.inner.Delete(ctx, providerURL)
+}
+
+func (w *fileStoreWrapper) Exists(ctx context.Context, providerURL string) (bool, error) {
+	return w.inner.Exists(ctx, providerURL)
+}
+
+// basePath returns the base path used for storing credentials (for backward compatibility in tests)
+func (w *fileStoreWrapper) basePath() string {
+	return w.inner.BasePath()
+}
+
+// getFilePath returns the file path for storing credentials for a specific provider (for backward compatibility in tests)
+func (w *fileStoreWrapper) getFilePath(providerURL string) string {
+	return w.inner.GetFilePath(providerURL)
+}
+
+// redisStoreWrapper wraps dcrstorage.RedisStore to implement DCRCredentialsStore
+type redisStoreWrapper struct {
+	inner *dcrstorage.RedisStore
+}
+
+func (w *redisStoreWrapper) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	innerCreds := convertCredsToInternal(creds)
+	return w.inner.Save(ctx, providerURL, innerCreds)
+}
+
+func (w *redisStoreWrapper) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	innerCreds, err := w.inner.Load(ctx, providerURL)
+	if err != nil || innerCreds == nil {
+		return nil, err
+	}
+	return convertCredsFromInternal(innerCreds), nil
+}
+
+func (w *redisStoreWrapper) Delete(ctx context.Context, providerURL string) error {
+	return w.inner.Delete(ctx, providerURL)
+}
+
+func (w *redisStoreWrapper) Exists(ctx context.Context, providerURL string) (bool, error) {
+	return w.inner.Exists(ctx, providerURL)
+}
+
+// FileCredentialsStore implements DCRCredentialsStore using file-based storage.
+// This is the default storage backend for backward compatibility with existing deployments.
+type FileCredentialsStore = fileStoreWrapper
+
+// RedisCredentialsStore implements DCRCredentialsStore using Redis-backed cache.
+// This storage backend enables sharing DCR credentials across multiple Traefik instances.
+type RedisCredentialsStore = redisStoreWrapper
+
+// NewFileCredentialsStore creates a new file-based credentials store.
+// If basePath is empty, defaults to /tmp/oidc-client-credentials.json
+func NewFileCredentialsStore(basePath string, logger *Logger) *FileCredentialsStore {
+	var dcrLogger dcrstorage.Logger
+	if logger != nil {
+		dcrLogger = &loggerAdapter{logger: logger}
+	}
+	inner := dcrstorage.NewFileStore(basePath, dcrLogger)
+	return &fileStoreWrapper{inner: inner}
+}
+
+// NewRedisCredentialsStore creates a new Redis-backed credentials store.
+// The cache should be configured with a Redis backend for distributed storage.
+// If keyPrefix is empty, defaults to "dcr:creds:"
+func NewRedisCredentialsStore(cache *UniversalCache, keyPrefix string, logger *Logger) *RedisCredentialsStore {
+	var dcrLogger dcrstorage.Logger
+	if logger != nil {
+		dcrLogger = &loggerAdapter{logger: logger}
+	}
+	cacheAdapt := &cacheAdapter{cache: cache}
+	inner := dcrstorage.NewRedisStore(cacheAdapt, keyPrefix, dcrLogger)
+	return &redisStoreWrapper{inner: inner}
+}
+
+// Helper functions to convert between main package and internal package types
+func convertCredsToInternal(creds *ClientRegistrationResponse) *dcrstorage.ClientRegistrationResponse {
+	if creds == nil {
+		return nil
+	}
+	return &dcrstorage.ClientRegistrationResponse{
+		SubjectType:             creds.SubjectType,
+		LogoURI:                 creds.LogoURI,
+		RegistrationAccessToken: creds.RegistrationAccessToken,
+		RegistrationClientURI:   creds.RegistrationClientURI,
+		Scope:                   creds.Scope,
+		TokenEndpointAuthMethod: creds.TokenEndpointAuthMethod,
+		TOSURI:                  creds.TOSURI,
+		PolicyURI:               creds.PolicyURI,
+		ClientSecret:            creds.ClientSecret,
+		ApplicationType:         creds.ApplicationType,
+		ClientID:                creds.ClientID,
+		ClientName:              creds.ClientName,
+		JWKSURI:                 creds.JWKSURI,
+		ClientURI:               creds.ClientURI,
+		Contacts:                creds.Contacts,
+		GrantTypes:              creds.GrantTypes,
+		ResponseTypes:           creds.ResponseTypes,
+		RedirectURIs:            creds.RedirectURIs,
+		ClientSecretExpiresAt:   creds.ClientSecretExpiresAt,
+		ClientIDIssuedAt:        creds.ClientIDIssuedAt,
+	}
+}
+
+func convertCredsFromInternal(creds *dcrstorage.ClientRegistrationResponse) *ClientRegistrationResponse {
+	if creds == nil {
+		return nil
+	}
+	return &ClientRegistrationResponse{
+		SubjectType:             creds.SubjectType,
+		LogoURI:                 creds.LogoURI,
+		RegistrationAccessToken: creds.RegistrationAccessToken,
+		RegistrationClientURI:   creds.RegistrationClientURI,
+		Scope:                   creds.Scope,
+		TokenEndpointAuthMethod: creds.TokenEndpointAuthMethod,
+		TOSURI:                  creds.TOSURI,
+		PolicyURI:               creds.PolicyURI,
+		ClientSecret:            creds.ClientSecret,
+		ApplicationType:         creds.ApplicationType,
+		ClientID:                creds.ClientID,
+		ClientName:              creds.ClientName,
+		JWKSURI:                 creds.JWKSURI,
+		ClientURI:               creds.ClientURI,
+		Contacts:                creds.Contacts,
+		GrantTypes:              creds.GrantTypes,
+		ResponseTypes:           creds.ResponseTypes,
+		RedirectURIs:            creds.RedirectURIs,
+		ClientSecretExpiresAt:   creds.ClientSecretExpiresAt,
+		ClientIDIssuedAt:        creds.ClientIDIssuedAt,
+	}
+}
+
+// NewDCRCredentialsStore creates a DCRCredentialsStore based on configuration.
+// This factory function handles backend selection logic:
+//   - "file": Use file-based storage (default for backward compatibility)
+//   - "redis": Use Redis exclusively (fails if Redis unavailable)
+//   - "auto": Use Redis if available, fallback to file
+func NewDCRCredentialsStore(
+	config *DynamicClientRegistrationConfig,
+	cacheManager *CacheManager,
+	logger *Logger,
+) (DCRCredentialsStore, error) {
+	if config == nil {
+		return nil, fmt.Errorf("DCR config is nil")
+	}
+
+	if logger == nil {
+		logger = GetSingletonNoOpLogger()
+	}
+
+	backend := config.StorageBackend
+	if backend == "" {
+		backend = string(DCRStorageBackendAuto) // Default to auto selection
+	}
+
+	switch DCRStorageBackend(backend) {
+	case DCRStorageBackendFile:
+		logger.Info("Using file-based storage for DCR credentials")
+		return NewFileCredentialsStore(config.CredentialsFile, logger), nil
+
+	case DCRStorageBackendRedis:
+		cache := getDCRCache(cacheManager)
+		if cache == nil {
+			return nil, fmt.Errorf("redis storage requested but Redis/cache not configured")
+		}
+		logger.Info("Using Redis storage for DCR credentials")
+		return NewRedisCredentialsStore(cache, config.RedisKeyPrefix, logger), nil
+
+	case DCRStorageBackendAuto:
+		// Try Redis first, fallback to file
+		cache := getDCRCache(cacheManager)
+		if cache != nil && cache.backend != nil {
+			logger.Info("Auto-selected Redis storage for DCR credentials")
+			return NewRedisCredentialsStore(cache, config.RedisKeyPrefix, logger), nil
+		}
+		logger.Info("Redis not available, using file storage for DCR credentials")
+		return NewFileCredentialsStore(config.CredentialsFile, logger), nil
+
+	default:
+		return nil, fmt.Errorf("unknown DCR storage backend: %s", backend)
+	}
+}
+
+// getDCRCache safely retrieves the DCR credentials cache from the cache manager
+func getDCRCache(cacheManager *CacheManager) *UniversalCache {
+	if cacheManager == nil {
+		return nil
+	}
+	cacheManager.mu.RLock()
+	defer cacheManager.mu.RUnlock()
+
+	if cacheManager.manager == nil {
+		return nil
+	}
+
+	return cacheManager.manager.GetDCRCredentialsCache()
+}

dcr_storage_test.go

@@ -0,0 +1,663 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik
+package traefikoidc
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestFileCredentialsStore_SaveLoad tests the file-based credentials store
+func TestFileCredentialsStore_SaveLoad(t *testing.T) {
+	t.Parallel()
+
+	// Create a temp directory for test files
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "test-client-id",
+		ClientSecret:            "test-client-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "test-access-token",
+		RegistrationClientURI:   "https://example.com/register/test-client-id",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+		GrantTypes:              []string{"authorization_code", "refresh_token"},
+		ResponseTypes:           []string{"code"},
+		TokenEndpointAuthMethod: "client_secret_basic",
+	}
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		// Save credentials
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		// Load credentials
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+
+		// Verify fields
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+		if loaded.RegistrationAccessToken != testCreds.RegistrationAccessToken {
+			t.Errorf("RegistrationAccessToken mismatch: got %s, want %s", loaded.RegistrationAccessToken, testCreds.RegistrationAccessToken)
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		tempDir2 := t.TempDir()
+		store2 := NewFileCredentialsStore(filepath.Join(tempDir2, "nonexistent.json"), logger)
+
+		loaded, err := store2.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent file: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+
+		exists, err = store.Exists(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if exists {
+			t.Error("Expected credentials to not exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("delete non-existent credentials", func(t *testing.T) {
+		// Should not error
+		err := store.Delete(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Delete should not error for non-existent: %v", err)
+		}
+	})
+}
+
+// TestFileCredentialsStore_MultiProvider tests multi-provider support
+func TestFileCredentialsStore_MultiProvider(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+
+	provider1 := "https://auth1.example.com"
+	provider2 := "https://auth2.example.com"
+
+	creds1 := &ClientRegistrationResponse{
+		ClientID:     "client-1",
+		ClientSecret: "secret-1",
+	}
+	creds2 := &ClientRegistrationResponse{
+		ClientID:     "client-2",
+		ClientSecret: "secret-2",
+	}
+
+	// Save credentials for both providers
+	if err := store.Save(ctx, provider1, creds1); err != nil {
+		t.Fatalf("Failed to save creds1: %v", err)
+	}
+	if err := store.Save(ctx, provider2, creds2); err != nil {
+		t.Fatalf("Failed to save creds2: %v", err)
+	}
+
+	// Load and verify each provider's credentials
+	loaded1, err := store.Load(ctx, provider1)
+	if err != nil {
+		t.Fatalf("Failed to load creds1: %v", err)
+	}
+	if loaded1.ClientID != "client-1" {
+		t.Errorf("Provider 1 ClientID mismatch: got %s", loaded1.ClientID)
+	}
+
+	loaded2, err := store.Load(ctx, provider2)
+	if err != nil {
+		t.Fatalf("Failed to load creds2: %v", err)
+	}
+	if loaded2.ClientID != "client-2" {
+		t.Errorf("Provider 2 ClientID mismatch: got %s", loaded2.ClientID)
+	}
+
+	// Delete one shouldn't affect the other
+	if err := store.Delete(ctx, provider1); err != nil {
+		t.Fatalf("Failed to delete creds1: %v", err)
+	}
+
+	exists, _ := store.Exists(ctx, provider2)
+	if !exists {
+		t.Error("Provider 2 credentials should still exist")
+	}
+}
+
+// TestFileCredentialsStore_ConcurrentAccess tests thread safety
+func TestFileCredentialsStore_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	creds := &ClientRegistrationResponse{
+		ClientID:     "test-client",
+		ClientSecret: "test-secret",
+	}
+
+	var wg sync.WaitGroup
+	concurrency := 10
+
+	// Concurrent saves
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_ = store.Save(ctx, providerURL, creds)
+		}()
+	}
+	wg.Wait()
+
+	// Concurrent loads
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = store.Load(ctx, providerURL)
+		}()
+	}
+	wg.Wait()
+
+	// Final verification
+	loaded, err := store.Load(ctx, providerURL)
+	if err != nil {
+		t.Fatalf("Failed to load after concurrent access: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test-client" {
+		t.Error("Credentials corrupted after concurrent access")
+	}
+}
+
+// TestFileCredentialsStore_InvalidInput tests error handling
+func TestFileCredentialsStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+
+	t.Run("empty provider URL uses default path", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{ClientID: "test"}
+		err := store.Save(ctx, "", creds)
+		if err != nil {
+			t.Fatalf("Save with empty provider URL failed: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, "")
+		if err != nil {
+			t.Fatalf("Load with empty provider URL failed: %v", err)
+		}
+		if loaded == nil || loaded.ClientID != "test" {
+			t.Error("Failed to load credentials with empty provider URL")
+		}
+	})
+}
+
+// TestFileCredentialsStore_DefaultPath tests default path behavior
+func TestFileCredentialsStore_DefaultPath(t *testing.T) {
+	t.Parallel()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore("", logger)
+
+	// Just verify we can create with empty path and it has a default
+	if store.basePath() == "" {
+		t.Error("Expected default base path")
+	}
+}
+
+// TestRedisCredentialsStore_WithMemoryCache tests Redis store with in-memory cache
+func TestRedisCredentialsStore_WithMemoryCache(t *testing.T) {
+	t.Parallel()
+
+	// Create an in-memory cache for testing
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "redis-test-client",
+		ClientSecret:            "redis-test-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "redis-test-token",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+	}
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		loaded, err := store.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+}
+
+// TestRedisCredentialsStore_TTLFromExpiry tests TTL calculation
+func TestRedisCredentialsStore_TTLFromExpiry(t *testing.T) {
+	t.Parallel()
+
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+
+	t.Run("expired credentials should fail", func(t *testing.T) {
+		expiredCreds := &ClientRegistrationResponse{
+			ClientID:              "expired-client",
+			ClientSecret:          "expired-secret",
+			ClientSecretExpiresAt: time.Now().Add(-1 * time.Hour).Unix(), // Already expired
+		}
+
+		err := store.Save(ctx, "https://expired.example.com", expiredCreds)
+		if err == nil {
+			t.Error("Expected error for expired credentials")
+		}
+	})
+
+	t.Run("credentials without expiry use default TTL", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{
+			ClientID:              "no-expiry-client",
+			ClientSecret:          "no-expiry-secret",
+			ClientSecretExpiresAt: 0, // No expiry
+		}
+
+		err := store.Save(ctx, "https://noexpiry.example.com", creds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials without expiry: %v", err)
+		}
+	})
+}
+
+// TestRedisCredentialsStore_InvalidInput tests error handling
+func TestRedisCredentialsStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+}
+
+// TestDCRStorageFactory tests the factory function
+func TestDCRStorageFactory(t *testing.T) {
+	t.Parallel()
+
+	logger := GetSingletonNoOpLogger()
+
+	t.Run("nil config returns error", func(t *testing.T) {
+		_, err := NewDCRCredentialsStore(nil, nil, logger)
+		if err == nil {
+			t.Error("Expected error for nil config")
+		}
+	})
+
+	t.Run("file backend creates file store", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "file",
+			CredentialsFile:    "/tmp/test-creds.json",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create file store: %v", err)
+		}
+		if store == nil {
+			t.Error("Expected store but got nil")
+		}
+
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore")
+		}
+	})
+
+	t.Run("redis backend without cache manager returns error", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "redis",
+		}
+
+		_, err := NewDCRCredentialsStore(config, nil, logger)
+		if err == nil {
+			t.Error("Expected error for redis backend without cache manager")
+		}
+	})
+
+	t.Run("auto backend without redis falls back to file", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "auto",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create auto store: %v", err)
+		}
+
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore for auto without redis")
+		}
+	})
+
+	t.Run("unknown backend returns error", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "unknown",
+		}
+
+		_, err := NewDCRCredentialsStore(config, nil, logger)
+		if err == nil {
+			t.Error("Expected error for unknown backend")
+		}
+	})
+
+	t.Run("empty backend defaults to auto", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create store with empty backend: %v", err)
+		}
+
+		// Should default to file (auto without redis)
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore for empty backend")
+		}
+	})
+}
+
+// TestDynamicClientRegistrar_WithStore tests registrar with store
+func TestDynamicClientRegistrar_WithStore(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	config := &DynamicClientRegistrationConfig{
+		Enabled:            true,
+		PersistCredentials: true,
+	}
+
+	registrar := NewDynamicClientRegistrarWithStore(
+		nil, // httpClient
+		logger,
+		config,
+		"https://auth.example.com",
+		store,
+	)
+
+	if registrar == nil {
+		t.Fatal("Expected registrar but got nil")
+	}
+
+	if registrar.store == nil {
+		t.Error("Expected store to be set")
+	}
+
+	// Test SetStore
+	newStore := NewFileCredentialsStore(filepath.Join(tempDir, "new.json"), logger)
+	registrar.SetStore(newStore)
+
+	if registrar.store != newStore {
+		t.Error("SetStore did not update the store")
+	}
+}
+
+// TestDynamicClientRegistrar_CredentialsFromStore tests loading from store
+func TestDynamicClientRegistrar_CredentialsFromStore(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	providerURL := "https://auth.example.com"
+	ctx := context.Background()
+
+	// Pre-save credentials
+	testCreds := &ClientRegistrationResponse{
+		ClientID:              "pre-saved-client",
+		ClientSecret:          "pre-saved-secret",
+		ClientSecretExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
+	}
+	if err := store.Save(ctx, providerURL, testCreds); err != nil {
+		t.Fatalf("Failed to pre-save credentials: %v", err)
+	}
+
+	config := &DynamicClientRegistrationConfig{
+		Enabled:            true,
+		PersistCredentials: true,
+	}
+
+	registrar := NewDynamicClientRegistrarWithStore(
+		nil,
+		logger,
+		config,
+		providerURL,
+		store,
+	)
+
+	// Test loading via the internal method
+	loaded, err := registrar.loadCredentialsFromStore(ctx)
+	if err != nil {
+		t.Fatalf("Failed to load from store: %v", err)
+	}
+	if loaded == nil {
+		t.Fatal("Expected credentials but got nil")
+	}
+	if loaded.ClientID != "pre-saved-client" {
+		t.Errorf("ClientID mismatch: got %s", loaded.ClientID)
+	}
+}
+
+// TestFileCredentialsStore_CorruptedFile tests handling of corrupted files
+func TestFileCredentialsStore_CorruptedFile(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	// Write corrupted JSON
+	filePath := store.getFilePath(providerURL)
+	if err := os.WriteFile(filePath, []byte("{corrupted json"), 0600); err != nil {
+		t.Fatalf("Failed to write corrupted file: %v", err)
+	}
+
+	// Should return error for corrupted file
+	_, err := store.Load(ctx, providerURL)
+	if err == nil {
+		t.Error("Expected error for corrupted JSON")
+	}
+}
+
+// TestFileCredentialsStore_DirectoryCreation tests auto directory creation
+func TestFileCredentialsStore_DirectoryCreation(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	deepPath := filepath.Join(tempDir, "deep", "nested", "path", "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(deepPath, logger)
+
+	ctx := context.Background()
+	creds := &ClientRegistrationResponse{ClientID: "test"}
+
+	err := store.Save(ctx, "https://example.com", creds)
+	if err != nil {
+		t.Fatalf("Failed to save with nested directory: %v", err)
+	}
+
+	loaded, err := store.Load(ctx, "https://example.com")
+	if err != nil {
+		t.Fatalf("Failed to load after nested directory creation: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test" {
+		t.Error("Failed to load credentials from nested directory")
+	}
+}

docs/CONFIGURATION.md

@@ -384,10 +384,14 @@ scopes:
 
 ### Dynamic Client Registration (RFC 7591)
 
+Dynamic Client Registration allows the middleware to automatically register itself with the OIDC provider, eliminating the need to manually create client credentials.
+
+**Basic Configuration (Single Instance):**
+
 ```yaml
 dynamicClientRegistration:
   enabled: true
-  initialAccessToken: "your-token"  # Optional
+  initialAccessToken: "your-token"  # Optional, if provider requires it
   persistCredentials: true
   credentialsFile: "/tmp/oidc-credentials.json"
   clientMetadata:
@@ -400,6 +404,35 @@ dynamicClientRegistration:
       - "refresh_token"
 ```
 
+**Multi-Replica Deployment (Kubernetes):**
+
+For Kubernetes deployments with multiple replicas, use Redis storage to share credentials across all instances and prevent registration race conditions:
+
+```yaml
+dynamicClientRegistration:
+  enabled: true
+  persistCredentials: true
+  storageBackend: "redis"  # Share credentials via Redis
+  redisKeyPrefix: "myapp:dcr:"  # Optional custom prefix
+  clientMetadata:
+    redirect_uris:
+      - "https://your-app.com/oauth2/callback"
+    client_name: "My Application"
+
+redis:
+  enabled: true
+  address: "redis:6379"
+  cacheMode: "redis"
+```
+
+**Storage Backend Options:**
+
+| Backend | Description | Use Case |
+|---------|-------------|----------|
+| `file` | Store credentials in local file | Single instance deployments |
+| `redis` | Store credentials in Redis | Multi-replica Kubernetes deployments |
+| `auto` | Use Redis if available, fallback to file | Flexible deployments (default) |
+
 ### Multi-Replica Deployment
 
 Without Redis, disable replay detection:

docs/PROVIDERS.md

@@ -353,6 +353,8 @@ allowPrivateIPAddresses: true  # Required for private IPs
    - Roles: User Client Role mapper with "Add to ID token" enabled
    - Groups: Group Membership mapper with "Add to ID token" enabled
 
+See [KEYCLOAK_SETUP_GUIDE.md](KEYCLOAK_SETUP_GUIDE.md) for detailed step-by-step setup instructions, mapper configuration, troubleshooting, and performance optimization.
+
 ---
 
 ## AWS Cognito

docs/index.html

@@ -193,7 +193,7 @@
                             </div>
                             <div>
                                 <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-1">Dynamic Registration</h3>
-                                <p class="text-sm text-gray-600 dark:text-gray-400">RFC 7591 Dynamic Client Registration for automatic client setup without manual configuration</p>
+                                <p class="text-sm text-gray-600 dark:text-gray-400">RFC 7591 Dynamic Client Registration with Redis storage support for multi-replica deployments</p>
                             </div>
                         </div>
                     </div>
@@ -862,6 +862,48 @@ spec:
                             </table>
                         </div>
                     </div>
+                    <div class="glass p-6 rounded-xl">
+                        <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-4">Dynamic Client Registration (RFC 7591)</h3>
+                        <p class="text-gray-600 dark:text-gray-400 mb-3 text-sm">Automatically register your application with the OIDC provider. Supports Redis storage for multi-replica deployments:</p>
+                        <div class="overflow-x-auto mb-4">
+                            <table class="w-full text-sm">
+                                <thead>
+                                    <tr class="border-b border-gray-200 dark:border-gray-700">
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Parameter</th>
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Default</th>
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Description</th>
+                                    </tr>
+                                </thead>
+                                <tbody class="text-gray-600 dark:text-gray-400">
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.enabled</code></td>
+                                        <td class="py-2 px-3">false</td>
+                                        <td class="py-2 px-3">Enable dynamic client registration</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.persistCredentials</code></td>
+                                        <td class="py-2 px-3">true</td>
+                                        <td class="py-2 px-3">Persist registered credentials across restarts</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.storageBackend</code></td>
+                                        <td class="py-2 px-3">auto</td>
+                                        <td class="py-2 px-3">Storage backend: <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">file</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">redis</code>, or <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">auto</code> (uses Redis if available)</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.redisKeyPrefix</code></td>
+                                        <td class="py-2 px-3">dcr:creds:</td>
+                                        <td class="py-2 px-3">Redis key prefix for DCR credentials</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.clientMetadata.redirect_uris</code></td>
+                                        <td class="py-2 px-3">-</td>
+                                        <td class="py-2 px-3">Redirect URIs for the registered client (required)</td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+                    </div>
                     <div class="glass p-6 rounded-xl">
                         <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-3">Example: Security Headers with CORS</h3>
 

dynamic_client_registration.go

@@ -16,35 +16,26 @@ import (
 
 // ClientRegistrationResponse represents the response from a successful client registration (RFC 7591)
 type ClientRegistrationResponse struct {
-	// Required fields
-	ClientID string `json:"client_id"`
-
-	// Conditional - only for confidential clients
-	ClientSecret string `json:"client_secret,omitempty"`
-
-	// Optional - for managing registration
-	RegistrationAccessToken string `json:"registration_access_token,omitempty"`
-	RegistrationClientURI   string `json:"registration_client_uri,omitempty"`
-
-	// Expiration
-	ClientIDIssuedAt      int64 `json:"client_id_issued_at,omitempty"`
-	ClientSecretExpiresAt int64 `json:"client_secret_expires_at,omitempty"`
-
-	// Echo back of registered metadata
-	RedirectURIs            []string `json:"redirect_uris,omitempty"`
-	ResponseTypes           []string `json:"response_types,omitempty"`
-	GrantTypes              []string `json:"grant_types,omitempty"`
-	ApplicationType         string   `json:"application_type,omitempty"`
-	Contacts                []string `json:"contacts,omitempty"`
-	ClientName              string   `json:"client_name,omitempty"`
-	LogoURI                 string   `json:"logo_uri,omitempty"`
-	ClientURI               string   `json:"client_uri,omitempty"`
-	PolicyURI               string   `json:"policy_uri,omitempty"`
-	TOSURI                  string   `json:"tos_uri,omitempty"`
-	JWKSURI                 string   `json:"jwks_uri,omitempty"`
 	SubjectType             string   `json:"subject_type,omitempty"`
-	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	LogoURI                 string   `json:"logo_uri,omitempty"`
+	RegistrationAccessToken string   `json:"registration_access_token,omitempty"`
+	RegistrationClientURI   string   `json:"registration_client_uri,omitempty"`
 	Scope                   string   `json:"scope,omitempty"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	TOSURI                  string   `json:"tos_uri,omitempty"`
+	PolicyURI               string   `json:"policy_uri,omitempty"`
+	ClientSecret            string   `json:"client_secret,omitempty"`
+	ApplicationType         string   `json:"application_type,omitempty"`
+	ClientID                string   `json:"client_id"`
+	ClientName              string   `json:"client_name,omitempty"`
+	JWKSURI                 string   `json:"jwks_uri,omitempty"`
+	ClientURI               string   `json:"client_uri,omitempty"`
+	Contacts                []string `json:"contacts,omitempty"`
+	GrantTypes              []string `json:"grant_types,omitempty"`
+	ResponseTypes           []string `json:"response_types,omitempty"`
+	RedirectURIs            []string `json:"redirect_uris,omitempty"`
+	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
+	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
 }
 
 // ClientRegistrationError represents an error response from client registration (RFC 7591)
@@ -55,14 +46,13 @@ type ClientRegistrationError struct {
 
 // DynamicClientRegistrar handles OIDC Dynamic Client Registration (RFC 7591)
 type DynamicClientRegistrar struct {
-	httpClient  *http.Client
-	logger      *Logger
-	config      *DynamicClientRegistrationConfig
-	providerURL string
-
-	// Cached registration response
-	mu                   sync.RWMutex
+	httpClient           *http.Client
+	logger               *Logger
+	config               *DynamicClientRegistrationConfig
 	registrationResponse *ClientRegistrationResponse
+	store                DCRCredentialsStore // Storage backend for credentials
+	providerURL          string
+	mu                   sync.RWMutex
 }
 
 // NewDynamicClientRegistrar creates a new dynamic client registrar
@@ -84,8 +74,37 @@ func NewDynamicClientRegistrar(
 	}
 }
 
+// NewDynamicClientRegistrarWithStore creates a new dynamic client registrar with a specific storage backend
+func NewDynamicClientRegistrarWithStore(
+	httpClient *http.Client,
+	logger *Logger,
+	dcrConfig *DynamicClientRegistrationConfig,
+	providerURL string,
+	store DCRCredentialsStore,
+) *DynamicClientRegistrar {
+	if logger == nil {
+		logger = GetSingletonNoOpLogger()
+	}
+
+	return &DynamicClientRegistrar{
+		httpClient:  httpClient,
+		logger:      logger,
+		config:      dcrConfig,
+		providerURL: providerURL,
+		store:       store,
+	}
+}
+
+// SetStore sets the credentials store for the registrar
+// This allows setting the store after creation when the cache manager is available
+func (r *DynamicClientRegistrar) SetStore(store DCRCredentialsStore) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.store = store
+}
+
 // RegisterClient performs dynamic client registration with the OIDC provider
-// It first attempts to load existing credentials from a file if persistence is enabled,
+// It first attempts to load existing credentials from storage if persistence is enabled,
 // then registers a new client if no valid credentials exist.
 func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registrationEndpoint string) (*ClientRegistrationResponse, error) {
 	if r.config == nil || !r.config.Enabled {
@@ -94,10 +113,13 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 
 	// Try to load existing credentials if persistence is enabled
 	if r.config.PersistCredentials {
-		if resp, err := r.loadCredentials(); err == nil && resp != nil {
+		resp, err := r.loadCredentialsFromStore(ctx)
+		if err != nil {
+			r.logger.Debugf("Failed to load credentials from store: %v", err)
+		} else if resp != nil {
 			// Check if credentials are still valid (not expired)
 			if r.areCredentialsValid(resp) {
-				r.logger.Info("Loaded existing client credentials from file")
+				r.logger.Info("Loaded existing client credentials from storage")
 				r.mu.Lock()
 				r.registrationResponse = resp
 				r.mu.Unlock()
@@ -190,7 +212,7 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 
 	// Persist credentials if enabled
 	if r.config.PersistCredentials {
-		if err := r.saveCredentials(&regResp); err != nil {
+		if err := r.saveCredentialsToStore(ctx, &regResp); err != nil {
 			r.logger.Errorf("Failed to persist client credentials: %v", err)
 			// Don't fail registration if persistence fails
 		}
@@ -326,7 +348,44 @@ func (r *DynamicClientRegistrar) credentialsFilePath() string {
 	return "/tmp/oidc-client-credentials.json"
 }
 
-// saveCredentials persists client credentials to a file
+// loadCredentialsFromStore loads client credentials from the configured storage backend
+// Falls back to legacy file-based loading if no store is configured
+func (r *DynamicClientRegistrar) loadCredentialsFromStore(ctx context.Context) (*ClientRegistrationResponse, error) {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Load(ctx, r.providerURL)
+	}
+	// Fallback to legacy file-based loading
+	return r.loadCredentials()
+}
+
+// saveCredentialsToStore persists client credentials to the configured storage backend
+// Falls back to legacy file-based saving if no store is configured
+func (r *DynamicClientRegistrar) saveCredentialsToStore(ctx context.Context, resp *ClientRegistrationResponse) error {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Save(ctx, r.providerURL, resp)
+	}
+	// Fallback to legacy file-based saving
+	return r.saveCredentials(resp)
+}
+
+// deleteCredentialsFromStore removes credentials from the configured storage backend
+// Falls back to legacy file-based deletion if no store is configured
+func (r *DynamicClientRegistrar) deleteCredentialsFromStore(ctx context.Context) error {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Delete(ctx, r.providerURL)
+	}
+	// Fallback to legacy file-based deletion
+	filePath := r.credentialsFilePath()
+	if err := os.Remove(filePath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// saveCredentials persists client credentials to a file (legacy method)
 func (r *DynamicClientRegistrar) saveCredentials(resp *ClientRegistrationResponse) error {
 	filePath := r.credentialsFilePath()
 
@@ -344,7 +403,7 @@ func (r *DynamicClientRegistrar) saveCredentials(resp *ClientRegistrationRespons
 	return nil
 }
 
-// loadCredentials loads client credentials from a file
+// loadCredentials loads client credentials from a file (legacy method)
 func (r *DynamicClientRegistrar) loadCredentials() (*ClientRegistrationResponse, error) {
 	filePath := r.credentialsFilePath()
 
@@ -431,7 +490,7 @@ func (r *DynamicClientRegistrar) UpdateClientRegistration(ctx context.Context) (
 
 	// Persist updated credentials if enabled
 	if r.config.PersistCredentials {
-		if err := r.saveCredentials(&regResp); err != nil {
+		if err := r.saveCredentialsToStore(ctx, &regResp); err != nil {
 			r.logger.Errorf("Failed to persist updated credentials: %v", err)
 		}
 	}
@@ -538,11 +597,10 @@ func (r *DynamicClientRegistrar) DeleteClientRegistration(ctx context.Context) e
 	r.registrationResponse = nil
 	r.mu.Unlock()
 
-	// Remove credentials file if persistence is enabled
+	// Remove credentials from storage if persistence is enabled
 	if r.config.PersistCredentials {
-		filePath := r.credentialsFilePath()
-		if err := os.Remove(filePath); err != nil && !os.IsNotExist(err) {
-			r.logger.Errorf("Failed to remove credentials file: %v", err)
+		if err := r.deleteCredentialsFromStore(ctx); err != nil {
+			r.logger.Errorf("Failed to remove credentials from storage: %v", err)
 		}
 	}
 

dynamic_client_registration_test.go

@@ -223,10 +223,10 @@ func TestRegisterClientWithInitialAccessToken(t *testing.T) {
 // TestRegisterClientError tests error handling during registration
 func TestRegisterClientError(t *testing.T) {
 	tests := []struct {
-		name           string
 		serverResponse func(w http.ResponseWriter, r *http.Request)
-		expectError    bool
+		name           string
 		errorContains  string
+		expectError    bool
 	}{
 		{
 			name: "invalid_redirect_uri error",
@@ -321,8 +321,8 @@ func TestRegisterClientError(t *testing.T) {
 // TestRegisterClientDisabled tests that registration fails when not enabled
 func TestRegisterClientDisabled(t *testing.T) {
 	tests := []struct {
-		name      string
 		dcrConfig *DynamicClientRegistrationConfig
+		name      string
 	}{
 		{
 			name:      "nil config",
@@ -521,8 +521,8 @@ func TestCredentialsValidation(t *testing.T) {
 	registrar := NewDynamicClientRegistrar(&http.Client{}, NewLogger("DEBUG"), dcrConfig, "https://example.com")
 
 	tests := []struct {
-		name     string
 		response *ClientRegistrationResponse
+		name     string
 		expected bool
 	}{
 		{
@@ -584,9 +584,9 @@ func TestCredentialsValidation(t *testing.T) {
 // TestBuildRegistrationRequest tests the request body construction
 func TestBuildRegistrationRequest(t *testing.T) {
 	tests := []struct {
-		name           string
 		metadata       *ClientRegistrationMetadata
 		expectedFields map[string]interface{}
+		name           string
 		expectError    bool
 	}{
 		{

enhanced_mocks_test.go

@@ -12,23 +12,19 @@ import (
 
 // EnhancedMockJWKCache is an improved state-based mock with call tracking
 type EnhancedMockJWKCache struct {
-	mu sync.RWMutex
-
-	// State (what to return)
-	JWKS *JWKSet
-	Err  error
-
-	// Call tracking
+	Err            error
+	JWKS           *JWKSet
 	GetJWKSCalls   []JWKSCall
+	mu             sync.RWMutex
+	getJWKSCallsMu sync.Mutex
 	CleanupCalls   int32
 	CloseCalls     int32
-	getJWKSCallsMu sync.Mutex
 }
 
 // JWKSCall records parameters from a GetJWKS call
 type JWKSCall struct {
-	URL       string
 	Timestamp time.Time
+	URL       string
 }
 
 func (m *EnhancedMockJWKCache) GetJWKS(ctx context.Context, jwksURL string, httpClient *http.Client) (*JWKSet, error) {
@@ -108,22 +104,18 @@ func (m *EnhancedMockJWKCache) Reset() {
 
 // EnhancedMockTokenVerifier is an improved state-based mock with call tracking
 type EnhancedMockTokenVerifier struct {
-	mu sync.RWMutex
-
-	// State (what to return) - can be a fixed error or a function
-	Err        error
-	VerifyFunc func(token string) error
-
-	// Call tracking
+	Err           error
+	VerifyFunc    func(token string) error
 	VerifyCalls   []TokenVerifyCall
+	mu            sync.RWMutex
 	verifyCallsMu sync.Mutex
 }
 
 // TokenVerifyCall records parameters from a VerifyToken call
 type TokenVerifyCall struct {
-	Token     string
 	Timestamp time.Time
 	Result    error
+	Token     string
 }
 
 func (m *EnhancedMockTokenVerifier) VerifyToken(token string) error {
@@ -207,49 +199,43 @@ func (m *EnhancedMockTokenVerifier) Reset() {
 
 // EnhancedMockTokenExchanger is an improved state-based mock with call tracking
 type EnhancedMockTokenExchanger struct {
-	mu sync.RWMutex
-
-	// State (what to return)
-	ExchangeResponse *TokenResponse
-	ExchangeErr      error
-	RefreshResponse  *TokenResponse
 	RefreshErr       error
 	RevokeErr        error
-
-	// Optional functions for dynamic behavior
+	ExchangeErr      error
 	ExchangeCodeFunc func(ctx context.Context, grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error)
+	RefreshResponse  *TokenResponse
+	ExchangeResponse *TokenResponse
 	RefreshTokenFunc func(refreshToken string) (*TokenResponse, error)
 	RevokeTokenFunc  func(token, tokenType string) error
-
-	// Call tracking
-	ExchangeCalls   []ExchangeCall
-	RefreshCalls    []RefreshCall
-	RevokeCalls     []RevokeCall
-	exchangeCallsMu sync.Mutex
-	refreshCallsMu  sync.Mutex
-	revokeCallsMu   sync.Mutex
+	ExchangeCalls    []ExchangeCall
+	RefreshCalls     []RefreshCall
+	RevokeCalls      []RevokeCall
+	mu               sync.RWMutex
+	exchangeCallsMu  sync.Mutex
+	refreshCallsMu   sync.Mutex
+	revokeCallsMu    sync.Mutex
 }
 
 // ExchangeCall records parameters from an ExchangeCodeForToken call
 type ExchangeCall struct {
+	Timestamp    time.Time
 	GrantType    string
 	CodeOrToken  string
 	RedirectURL  string
 	CodeVerifier string
-	Timestamp    time.Time
 }
 
 // RefreshCall records parameters from a GetNewTokenWithRefreshToken call
 type RefreshCall struct {
-	RefreshToken string
 	Timestamp    time.Time
+	RefreshToken string
 }
 
 // RevokeCall records parameters from a RevokeTokenWithProvider call
 type RevokeCall struct {
+	Timestamp time.Time
 	Token     string
 	TokenType string
-	Timestamp time.Time
 }
 
 func (m *EnhancedMockTokenExchanger) ExchangeCodeForToken(ctx context.Context, grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error) {
@@ -401,16 +387,12 @@ func (m *EnhancedMockTokenExchanger) Reset() {
 
 // EnhancedMockCacheInterface is an improved state-based mock for CacheInterface
 type EnhancedMockCacheInterface struct {
-	mu sync.RWMutex
-
-	// Internal storage
-	data    map[string]cacheEntry
-	maxSize int
-
-	// Call tracking
+	data        map[string]cacheEntry
 	GetCalls    []CacheGetCall
 	SetCalls    []CacheSetCall
 	DeleteCalls []string
+	maxSize     int
+	mu          sync.RWMutex
 	getCalls    sync.Mutex
 	setCalls    sync.Mutex
 	deleteCalls sync.Mutex
@@ -423,17 +405,17 @@ type cacheEntry struct {
 
 // CacheGetCall records parameters from a Get call
 type CacheGetCall struct {
+	Timestamp time.Time
 	Key       string
 	Found     bool
-	Timestamp time.Time
 }
 
 // CacheSetCall records parameters from a Set call
 type CacheSetCall struct {
-	Key       string
-	Value     any
-	TTL       time.Duration
 	Timestamp time.Time
+	Value     any
+	Key       string
+	TTL       time.Duration
 }
 
 // NewEnhancedMockCache creates a new enhanced cache mock

error_recovery.go

@@ -642,14 +642,10 @@ func (e *HTTPError) Error() string {
 // OIDCError represents OIDC-specific errors with context information.
 // It provides structured error reporting for authentication and authorization failures.
 type OIDCError struct {
-	// Code identifies the specific error type
-	Code string
-	// Message provides a human-readable description
-	Message string
-	// Context contains additional error context (e.g., provider, session details)
+	Cause   error
 	Context map[string]interface{}
-	// Cause is the underlying error that caused this error
-	Cause error
+	Code    string
+	Message string
 }
 
 // Error returns the string representation of the OIDC error.
@@ -669,14 +665,10 @@ func (e *OIDCError) Unwrap() error {
 // SessionError represents session-related errors with context.
 // Used for session management, validation, and storage errors.
 type SessionError struct {
-	// Operation describes what session operation failed
+	Cause     error
 	Operation string
-	// Message provides a human-readable description
-	Message string
-	// SessionID identifies the session (if available)
+	Message   string
 	SessionID string
-	// Cause is the underlying error that caused this error
-	Cause error
 }
 
 // Error returns the string representation of the session error.
@@ -696,14 +688,10 @@ func (e *SessionError) Unwrap() error {
 // TokenError represents token-related errors with validation context.
 // Used for JWT validation, token refresh, and token format errors.
 type TokenError struct {
-	// TokenType identifies the type of token (id_token, access_token, refresh_token)
+	Cause     error
 	TokenType string
-	// Reason describes why the token is invalid
-	Reason string
-	// Message provides a human-readable description
-	Message string
-	// Cause is the underlying error that caused this error
-	Cause error
+	Reason    string
+	Message   string
 }
 
 // Error returns the string representation of the token error.
@@ -765,24 +753,15 @@ func NewTokenError(tokenType, reason, message string, cause error) *TokenError {
 // It provides fallback mechanisms when primary services are unavailable and monitors
 // service health to automatically recover when services become available again.
 type GracefulDegradation struct {
-	// BaseRecoveryMechanism provides common functionality
 	*BaseRecoveryMechanism
-	// fallbacks stores service-specific fallback implementations
-	fallbacks map[string]func() (interface{}, error)
-	// healthChecks stores service health check functions
-	healthChecks map[string]func() bool
-	// degradedServices tracks which services are currently degraded
+	fallbacks        map[string]func() (interface{}, error)
+	healthChecks     map[string]func() bool
 	degradedServices map[string]time.Time
-	// config contains graceful degradation configuration
-	config GracefulDegradationConfig
-	// mutex protects shared state
-	mutex sync.RWMutex
-	// healthCheckTask manages background health checking
-	healthCheckTask *BackgroundTask
-	// stopChan signals shutdown
-	stopChan chan struct{}
-	// shutdownOnce ensures shutdown happens only once
-	shutdownOnce sync.Once
+	healthCheckTask  *BackgroundTask
+	stopChan         chan struct{}
+	config           GracefulDegradationConfig
+	mutex            sync.RWMutex
+	shutdownOnce     sync.Once
 }
 
 // GracefulDegradationConfig holds configuration for graceful degradation behavior.

error_recovery_test.go

@@ -20,10 +20,10 @@ import (
 func TestCircuitBreakerStateTransitions(t *testing.T) {
 	tests := []struct {
 		name                string
-		failures            int
-		maxFailures         int
 		expectedStateBefore string
 		expectedStateAfter  string
+		failures            int
+		maxFailures         int
 	}{
 		{
 			name:                "stays closed below threshold",
@@ -543,8 +543,8 @@ func TestRetryExecutorNetworkErrors(t *testing.T) {
 	}, nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1647,8 +1647,8 @@ func TestGracefulDegradationFullScenario(t *testing.T) {
 
 func TestIsTraefikDefaultCertError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1680,8 +1680,8 @@ func TestIsTraefikDefaultCertError(t *testing.T) {
 
 func TestIsEOFError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1723,8 +1723,8 @@ func TestIsEOFError(t *testing.T) {
 
 func TestIsCertificateError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1811,8 +1811,8 @@ func TestRetryExecutorStartupErrors(t *testing.T) {
 	_ = NewRetryExecutor(MetadataFetchRetryConfig(), nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1890,8 +1890,8 @@ func TestRetryExecutorIsRetryableErrorIntegration(t *testing.T) {
 	re := NewRetryExecutor(DefaultRetryConfig(), nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1977,9 +1977,9 @@ func circuitBreakerStateToString(state CircuitBreakerState) string {
 }
 
 type mockNetError struct {
+	msg       string
 	timeout   bool
 	temporary bool
-	msg       string
 }
 
 func (e *mockNetError) Error() string   { return e.msg }

goroutine_manager.go

@@ -10,16 +10,16 @@ import (
 type GoroutineManager struct {
 	ctx        context.Context
 	cancel     context.CancelFunc
-	wg         sync.WaitGroup
-	mu         sync.RWMutex
 	goroutines map[string]*managedGoroutine
 	logger     *Logger
+	wg         sync.WaitGroup
+	mu         sync.RWMutex
 }
 
 type managedGoroutine struct {
-	name      string
-	cancel    context.CancelFunc
 	startTime time.Time
+	cancel    context.CancelFunc
+	name      string
 	running   bool
 }
 
@@ -149,10 +149,10 @@ func (m *GoroutineManager) GetStatus() map[string]GoroutineStatus {
 
 // GoroutineStatus represents the status of a managed goroutine
 type GoroutineStatus struct {
-	Name      string
-	Running   bool
 	StartTime time.Time
+	Name      string
 	Runtime   time.Duration
+	Running   bool
 }
 
 // ErrShutdownTimeout is returned when shutdown times out

http_client_factory.go

@@ -12,30 +12,23 @@ import (
 
 // HTTPClientConfig provides configuration for creating HTTP clients
 type HTTPClientConfig struct {
-	// Timeout for the entire request
-	Timeout time.Duration
-	// MaxRedirects allowed (0 means follow Go's default of 10)
-	MaxRedirects int
-	// UseCookieJar enables cookie jar for the client
-	UseCookieJar bool
-	// Connection settings
+	IdleConnTimeout       time.Duration
+	MaxIdleConns          int
+	ReadBufferSize        int
 	DialTimeout           time.Duration
 	KeepAlive             time.Duration
 	TLSHandshakeTimeout   time.Duration
 	ResponseHeaderTimeout time.Duration
 	ExpectContinueTimeout time.Duration
-	IdleConnTimeout       time.Duration
-	// Connection pool settings
-	MaxIdleConns        int
-	MaxIdleConnsPerHost int
-	MaxConnsPerHost     int
-	// Buffer settings
-	WriteBufferSize int
-	ReadBufferSize  int
-	// Feature flags
-	ForceHTTP2         bool
-	DisableKeepAlives  bool
-	DisableCompression bool
+	MaxRedirects          int
+	MaxIdleConnsPerHost   int
+	Timeout               time.Duration
+	MaxConnsPerHost       int
+	WriteBufferSize       int
+	UseCookieJar          bool
+	ForceHTTP2            bool
+	DisableKeepAlives     bool
+	DisableCompression    bool
 }
 
 // DefaultHTTPClientConfig returns the default configuration for general use

http_client_factory_unit_test.go

@@ -110,9 +110,9 @@ func TestHTTPClientFactoryValidateHTTPClientConfig(t *testing.T) {
 
 	tests := []struct {
 		name      string
+		errorMsg  string
 		config    HTTPClientConfig
 		wantError bool
-		errorMsg  string
 	}{
 		{
 			name: "valid config",

http_client_pool.go

@@ -12,19 +12,19 @@ import (
 
 // SharedTransportPool manages a pool of shared HTTP transports to prevent connection exhaustion
 type SharedTransportPool struct {
-	mu          sync.RWMutex
-	transports  map[string]*sharedTransport
-	maxConns    int
 	ctx         context.Context
+	transports  map[string]*sharedTransport
 	cancel      context.CancelFunc
-	clientCount int32 // SECURITY FIX: Track total HTTP clients
-	maxClients  int32 // SECURITY FIX: Limit total clients to 5
+	maxConns    int
+	mu          sync.RWMutex
+	clientCount int32
+	maxClients  int32
 }
 
 type sharedTransport struct {
+	lastUsed  time.Time
 	transport *http.Transport
 	refCount  int
-	lastUsed  time.Time
 }
 
 var (

input_validation_test.go

@@ -14,7 +14,7 @@ func TestInputValidator(t *testing.T) {
 	}
 
 	t.Run("Valid token validation", func(t *testing.T) {
-		validToken := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHs3UjpMC6M6FNqI2J-I2NxrragtnDxGxdJUvDERDQVHzeNlVQiuqWDEeO_O-0KptafbfyuGqfQxH_6dp2_MeFpAc"
+		validToken := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHs3UjpMC6M6FNqI2J-I2NxrragtnDxGxdJUvDERDQVHzeNlVQiuqWDEeO_O-0KptafbfyuGqfQxH_6dp2_MeFpAc" // trufflehog:ignore
 
 		result := validator.ValidateToken(validToken)
 		if !result.IsValid {
@@ -428,12 +428,12 @@ func TestInputValidatorValidateToken(t *testing.T) {
 	tests := []struct {
 		name        string
 		token       string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidJWTToken",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.signature",
+			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.signature", // trufflehog:ignore
 			expectValid: true,
 			description: "Valid JWT token should pass validation",
 		},
@@ -475,7 +475,7 @@ func TestInputValidatorValidateToken(t *testing.T) {
 		},
 		{
 			name:        "MaliciousJWTWithExtraData",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig.malicious_extra",
+			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig.malicious_extra", // trufflehog:ignore
 			expectValid: false,
 			description: "JWT with extra malicious data should fail validation",
 		},
@@ -500,8 +500,8 @@ func TestInputValidatorValidateEmail(t *testing.T) {
 	tests := []struct {
 		name        string
 		email       string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidEmail",
@@ -578,8 +578,8 @@ func TestInputValidatorValidateURL(t *testing.T) {
 	tests := []struct {
 		name        string
 		url         string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidHTTPSURL",
@@ -669,8 +669,8 @@ func TestInputValidatorValidateClaim(t *testing.T) {
 		name        string
 		claimName   string
 		claimValue  string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidStringClaim",
@@ -750,8 +750,8 @@ func TestInputValidatorValidateHeader(t *testing.T) {
 		name        string
 		headerName  string
 		headerValue string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidHeader",
@@ -830,8 +830,8 @@ func TestInputValidatorValidateUsername(t *testing.T) {
 	tests := []struct {
 		name        string
 		username    string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidUsername",

integration/integration_consolidated_test.go

@@ -726,20 +726,20 @@ type MockConfig struct {
 }
 
 type MockSession struct {
-	id       string
-	userID   string
 	created  time.Time
 	lastUsed time.Time
 	data     map[string]interface{}
+	id       string
+	userID   string
 }
 
 type TestResult struct {
-	UserID    int
 	StartTime time.Time
 	EndTime   time.Time
+	Error     error
+	UserID    int
 	Duration  time.Duration
 	Success   bool
-	Error     error
 }
 
 // ============================================================================

internal/cache/backends/config.go

@@ -18,33 +18,22 @@ const (
 
 // Config provides common configuration for cache backends
 type Config struct {
-	// Type specifies the backend type
-	Type BackendType
-
-	// Memory backend settings
-	MaxSize         int
-	MaxMemoryBytes  int64
-	CleanupInterval time.Duration
-
-	// Redis backend settings
-	RedisAddr     string
-	RedisPassword string
-	RedisDB       int
-	RedisPrefix   string
-	PoolSize      int
-
-	// Hybrid backend settings
-	L1Config    *Config // Memory cache (L1)
-	L2Config    *Config // Redis cache (L2)
-	AsyncWrites bool    // Write to L2 asynchronously
-
-	// Resilience settings
+	L2Config             *Config
+	L1Config             *Config
+	RedisPrefix          string
+	Type                 BackendType
+	RedisAddr            string
+	RedisPassword        string
+	PoolSize             int
+	RedisDB              int
+	CleanupInterval      time.Duration
+	MaxMemoryBytes       int64
+	MaxSize              int
+	HealthCheckInterval  time.Duration
+	AsyncWrites          bool
 	EnableCircuitBreaker bool
 	EnableHealthCheck    bool
-	HealthCheckInterval  time.Duration
-
-	// Metrics
-	EnableMetrics bool
+	EnableMetrics        bool
 }
 
 // DefaultConfig returns a default configuration for in-memory caching

internal/cache/backends/hybrid.go

@@ -13,40 +13,30 @@ import (
 // HybridBackend implements a two-tier cache with L1 (memory) and L2 (Redis) backends
 // It provides automatic failover, async writes for non-critical data, and optimized read paths
 type HybridBackend struct {
-	primary   CacheBackend // L1: Memory cache for fast access
-	secondary CacheBackend // L2: Redis cache for distributed access
-
-	// Configuration
-	syncWriteCacheTypes map[string]bool // Which cache types require synchronous writes
+	lastL2Error         atomic.Value
+	secondary           CacheBackend
+	primary             CacheBackend
+	logger              Logger
+	ctx                 context.Context
+	syncWriteCacheTypes map[string]bool
 	asyncWriteBuffer    chan *asyncWriteItem
-
-	// Metrics
-	l1Hits   atomic.Int64
-	l2Hits   atomic.Int64
-	misses   atomic.Int64
-	l1Writes atomic.Int64
-	l2Writes atomic.Int64
-	errors   atomic.Int64
-
-	// Fallback tracking
-	fallbackMode atomic.Bool  // True when operating in degraded mode (L1 only)
-	lastL2Error  atomic.Value // Stores last L2 error timestamp
-
-	// Lifecycle
-	ctx    context.Context
-	cancel context.CancelFunc
-	wg     sync.WaitGroup
-
-	// Logging
-	logger Logger
+	cancel              context.CancelFunc
+	wg                  sync.WaitGroup
+	l1Hits              atomic.Int64
+	errors              atomic.Int64
+	l2Writes            atomic.Int64
+	l1Writes            atomic.Int64
+	misses              atomic.Int64
+	l2Hits              atomic.Int64
+	fallbackMode        atomic.Bool
 }
 
 // asyncWriteItem represents an async write operation
 type asyncWriteItem struct {
+	ctx   context.Context
 	key   string
 	value []byte
 	ttl   time.Duration
-	ctx   context.Context
 }
 
 // Logger interface for structured logging
@@ -82,9 +72,9 @@ func (l *defaultLogger) Errorf(format string, args ...interface{}) {
 type HybridConfig struct {
 	Primary             CacheBackend
 	Secondary           CacheBackend
-	SyncWriteCacheTypes map[string]bool // Cache types requiring synchronous L2 writes
-	AsyncBufferSize     int
 	Logger              Logger
+	SyncWriteCacheTypes map[string]bool
+	AsyncBufferSize     int
 }
 
 // NewHybridBackend creates a new hybrid cache backend with L1 (memory) and L2 (Redis) tiers

internal/cache/backends/hybrid_test.go

@@ -17,23 +17,23 @@ import (
 
 // mockBackend is a simple mock implementation of CacheBackend for testing
 type mockBackend struct {
+	pingError   error
 	data        map[string]mockEntry
+	stats       map[string]interface{}
 	mu          sync.RWMutex
+	getCalls    atomic.Int32
+	setCalls    atomic.Int32
+	deleteCalls atomic.Int32
 	failSet     bool
 	failGet     bool
 	failDelete  bool
 	failClear   bool
 	failPing    bool
-	pingError   error
-	stats       map[string]interface{}
-	getCalls    atomic.Int32
-	setCalls    atomic.Int32
-	deleteCalls atomic.Int32
 }
 
 type mockEntry struct {
-	value     []byte
 	expiresAt time.Time
+	value     []byte
 }
 
 // mockBatchBackend extends mockBackend with batch operations

internal/cache/backends/interface.go

@@ -41,53 +41,22 @@ type CacheBackend interface {
 
 // BackendStats represents statistics for a cache backend
 type BackendStats struct {
-	// Type is the backend type
-	Type BackendType
-
-	// Hits is the number of cache hits
-	Hits int64
-
-	// Misses is the number of cache misses
-	Misses int64
-
-	// Sets is the number of set operations
-	Sets int64
-
-	// Deletes is the number of delete operations
-	Deletes int64
-
-	// Errors is the number of errors
-	Errors int64
-
-	// Evictions is the number of evicted items
-	Evictions int64
-
-	// CurrentSize is the current number of items in cache
-	CurrentSize int64
-
-	// MaxSize is the maximum number of items (0 means unlimited)
-	MaxSize int64
-
-	// MemoryUsage is the approximate memory usage in bytes
-	MemoryUsage int64
-
-	// AverageGetLatency is the average latency for get operations
+	StartTime         time.Time
+	LastErrorTime     time.Time
+	Type              BackendType
+	LastError         string
+	Deletes           int64
+	Errors            int64
+	Evictions         int64
+	CurrentSize       int64
+	MaxSize           int64
+	MemoryUsage       int64
 	AverageGetLatency time.Duration
-
-	// AverageSetLatency is the average latency for set operations
 	AverageSetLatency time.Duration
-
-	// LastError is the last error encountered
-	LastError string
-
-	// LastErrorTime is when the last error occurred
-	LastErrorTime time.Time
-
-	// Uptime is how long the backend has been running
-	Uptime time.Duration
-
-	// StartTime is when the backend was started
-	StartTime time.Time
+	Sets              int64
+	Misses            int64
+	Uptime            time.Duration
+	Hits              int64
 }
 
 // BackendCapabilities describes the capabilities of a cache backend

internal/cache/backends/memory.go

@@ -2,23 +2,30 @@
 package backends
 
 import (
-	"container/list"
 	"context"
 	"sync"
 	"sync/atomic"
 	"time"
 )
 
+// Default configuration values
+const (
+	defaultShardCount      = 256
+	defaultMaxSize         = int64(10000)
+	defaultMaxMemory       = int64(100 * 1024 * 1024) // 100MB
+	defaultCleanupInterval = 5 * time.Minute
+)
+
 // memoryCacheItem represents an item in the memory cache
 type memoryCacheItem struct {
-	key         string
-	value       interface{}
 	expiresAt   time.Time
 	createdAt   time.Time
 	accessedAt  time.Time
+	value       interface{}
+	element     interface{} // *list.Element, using interface{} to avoid import cycle
+	key         string
 	accessCount int64
 	size        int64
-	element     *list.Element // for LRU tracking
 }
 
 // isExpired checks if the item is expired
@@ -29,17 +36,23 @@ func (item *memoryCacheItem) isExpired() bool {
 	return time.Now().After(item.expiresAt)
 }
 
-// MemoryCacheBackend implements the CacheBackend interface using in-memory storage
+// MemoryCacheBackend implements the CacheBackend interface using sharded in-memory storage
+// The sharded design reduces lock contention by partitioning keys across multiple shards,
+// each with its own lock.
 type MemoryCacheBackend struct {
-	mu            sync.RWMutex
-	items         map[string]*memoryCacheItem
-	lruList       *list.List
-	maxSize       int64
-	maxMemory     int64
-	currentSize   int64
-	currentMemory int64
+	shards          []*cacheShard
+	startTime       time.Time
+	lastErrorTime   time.Time
+	cleanupDone     chan struct{}
+	cleanupTicker   *time.Ticker
+	lastError       string
+	shardCount      uint32
+	shardMask       uint32
+	maxSize         int64
+	maxMemory       int64
+	cleanupInterval time.Duration
 
-	// Statistics
+	// Global stats (aggregated from shards)
 	hits      atomic.Int64
 	misses    atomic.Int64
 	sets      atomic.Int64
@@ -53,40 +66,59 @@ type MemoryCacheBackend struct {
 	getCount     atomic.Int64
 	setCount     atomic.Int64
 
-	// Status
-	startTime     time.Time
-	lastError     string
-	lastErrorTime time.Time
-	cleanupTicker *time.Ticker
-	cleanupDone   chan bool
-	closed        atomic.Bool
-
-	// Configuration
-	cleanupInterval time.Duration
-	evictionPolicy  string // "lru", "lfu", "fifo"
+	// State
+	closed atomic.Bool
+	mu     sync.RWMutex // For global operations like stats and error tracking
 }
 
-// NewMemoryCacheBackend creates a new memory cache backend
+// NewMemoryCacheBackend creates a new sharded memory cache backend
 func NewMemoryCacheBackend(maxSize int64, maxMemory int64, cleanupInterval time.Duration) *MemoryCacheBackend {
 	if maxSize <= 0 {
-		maxSize = 10000 // Default to 10k items
+		maxSize = defaultMaxSize
 	}
 	if maxMemory <= 0 {
-		maxMemory = 100 * 1024 * 1024 // Default to 100MB
+		maxMemory = defaultMaxMemory
 	}
 	if cleanupInterval <= 0 {
-		cleanupInterval = 5 * time.Minute
+		cleanupInterval = defaultCleanupInterval
+	}
+
+	shardCount := uint32(defaultShardCount)
+
+	// For very small caches, reduce shard count to maintain sensible per-shard limits
+	// Ensure each shard can hold at least 2 items for proper LRU behavior
+	for shardCount > 1 && maxSize/int64(shardCount) < 2 {
+		shardCount /= 2
+	}
+	if shardCount < 1 {
+		shardCount = 1
+	}
+
+	// Per-shard limits are soft hints; global limits are enforced
+	// Give shards 2x the average to allow for uneven distribution
+	shardMaxSize := (maxSize * 2) / int64(shardCount)
+	if shardMaxSize < 4 {
+		shardMaxSize = 4
+	}
+	shardMaxMemory := (maxMemory * 2) / int64(shardCount)
+	if shardMaxMemory < 4096 {
+		shardMaxMemory = 4096 // Minimum 4KB per shard
 	}
 
 	m := &MemoryCacheBackend{
-		items:           make(map[string]*memoryCacheItem),
-		lruList:         list.New(),
+		shards:          make([]*cacheShard, shardCount),
+		shardCount:      shardCount,
+		shardMask:       shardCount - 1, // For fast modulo with power-of-2
 		maxSize:         maxSize,
 		maxMemory:       maxMemory,
 		startTime:       time.Now(),
 		cleanupInterval: cleanupInterval,
-		evictionPolicy:  "lru",
-		cleanupDone:     make(chan bool),
+		cleanupDone:     make(chan struct{}),
+	}
+
+	// Initialize shards
+	for i := uint32(0); i < shardCount; i++ {
+		m.shards[i] = newCacheShard(shardMaxSize, shardMaxMemory)
 	}
 
 	// Start cleanup goroutine
@@ -96,6 +128,12 @@ func NewMemoryCacheBackend(maxSize int64, maxMemory int64, cleanupInterval time.
 	return m
 }
 
+// getShard returns the shard for a given key
+func (m *MemoryCacheBackend) getShard(key string) *cacheShard {
+	hash := fnv32(key)
+	return m.shards[hash&m.shardMask]
+}
+
 // cleanupLoop runs periodic cleanup of expired items
 func (m *MemoryCacheBackend) cleanupLoop() {
 	for {
@@ -108,20 +146,19 @@ func (m *MemoryCacheBackend) cleanupLoop() {
 	}
 }
 
-// cleanupExpired removes all expired items from the cache
+// cleanupExpired removes all expired items from all shards
 func (m *MemoryCacheBackend) cleanupExpired() {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	var keysToDelete []string
-	for key, item := range m.items {
-		if item.isExpired() {
-			keysToDelete = append(keysToDelete, key)
-		}
+	if m.closed.Load() {
+		return
 	}
 
-	for _, key := range keysToDelete {
-		m.deleteItemLocked(key)
+	totalRemoved := 0
+	for _, shard := range m.shards {
+		totalRemoved += shard.cleanup()
+	}
+
+	if totalRemoved > 0 {
+		m.evictions.Add(int64(totalRemoved))
 	}
 }
 
@@ -138,35 +175,23 @@ func (m *MemoryCacheBackend) Get(ctx context.Context, key string) (interface{},
 		m.getCount.Add(1)
 	}()
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
+	shard := m.getShard(key)
+	value, exists, expired := shard.get(key)
+
+	if expired {
+		// Clean up expired item
+		shard.delete(key)
+		m.misses.Add(1)
+		return nil, ErrCacheMiss
+	}
 
 	if !exists {
 		m.misses.Add(1)
 		return nil, ErrCacheMiss
 	}
 
-	if item.isExpired() {
-		m.mu.Lock()
-		m.deleteItemLocked(key)
-		m.mu.Unlock()
-		m.misses.Add(1)
-		return nil, ErrCacheMiss
-	}
-
-	// Update access time and count
-	m.mu.Lock()
-	item.accessedAt = time.Now()
-	item.accessCount++
-	// Move to front of LRU list
-	if m.evictionPolicy == "lru" && item.element != nil {
-		m.lruList.MoveToFront(item.element)
-	}
-	m.mu.Unlock()
-
 	m.hits.Add(1)
-	return item.value, nil
+	return value, nil
 }
 
 // Set stores a value in the cache with optional TTL
@@ -182,113 +207,105 @@ func (m *MemoryCacheBackend) Set(ctx context.Context, key string, value interfac
 		m.setCount.Add(1)
 	}()
 
-	// Calculate item size (simplified estimation)
+	// Calculate item size
 	itemSize := int64(len(key)) + estimateValueSize(value)
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
+	// Enforce global limits before adding new item
+	m.enforceGlobalLimits(itemSize)
 
-	// Check if we need to evict items
-	if m.currentSize >= m.maxSize || m.currentMemory+itemSize > m.maxMemory {
-		m.evictLocked()
-	}
-
-	// Check if key exists
-	if oldItem, exists := m.items[key]; exists {
-		m.currentMemory -= oldItem.size
-		if oldItem.element != nil {
-			m.lruList.Remove(oldItem.element)
-		}
-	} else {
-		m.currentSize++
-	}
-
-	now := time.Now()
 	var expiresAt time.Time
 	if ttl > 0 {
-		expiresAt = now.Add(ttl)
+		expiresAt = time.Now().Add(ttl)
 	}
 
-	item := &memoryCacheItem{
-		key:         key,
-		value:       value,
-		expiresAt:   expiresAt,
-		createdAt:   now,
-		accessedAt:  now,
-		accessCount: 0,
-		size:        itemSize,
-	}
+	shard := m.getShard(key)
+	shard.set(key, value, expiresAt, itemSize)
 
-	// Add to LRU list
-	if m.evictionPolicy == "lru" {
-		item.element = m.lruList.PushFront(item)
-	}
-
-	m.items[key] = item
-	m.currentMemory += itemSize
 	m.sets.Add(1)
-
 	return nil
 }
 
+// enforceGlobalLimits ensures global size and memory limits are respected
+// by evicting from shards when necessary
+func (m *MemoryCacheBackend) enforceGlobalLimits(newItemSize int64) {
+	// Check and enforce size limit
+	for {
+		totalSize, totalMemory := m.getGlobalStats()
+
+		needsSizeEviction := m.maxSize > 0 && totalSize >= m.maxSize
+		needsMemoryEviction := m.maxMemory > 0 && totalMemory+newItemSize > m.maxMemory
+
+		if !needsSizeEviction && !needsMemoryEviction {
+			break
+		}
+
+		// Find the shard with the most items and evict from it
+		evicted := m.evictFromLargestShard()
+		if !evicted {
+			break // No more items to evict
+		}
+		m.evictions.Add(1)
+	}
+}
+
+// getGlobalStats returns the total size and memory usage across all shards
+func (m *MemoryCacheBackend) getGlobalStats() (totalSize, totalMemory int64) {
+	for _, shard := range m.shards {
+		size, memory := shard.stats()
+		totalSize += size
+		totalMemory += memory
+	}
+	return
+}
+
+// evictFromLargestShard evicts the globally oldest item across all shards
+// This provides true LRU behavior even with sharding
+func (m *MemoryCacheBackend) evictFromLargestShard() bool {
+	var oldestShard *cacheShard
+	var oldestTime time.Time
+
+	for _, shard := range m.shards {
+		accessTime := shard.getOldestAccessTime()
+		// Skip empty shards
+		if accessTime.IsZero() {
+			continue
+		}
+		// Find the shard with the oldest (earliest) access time
+		if oldestShard == nil || accessTime.Before(oldestTime) {
+			oldestTime = accessTime
+			oldestShard = shard
+		}
+	}
+
+	if oldestShard == nil {
+		return false
+	}
+
+	return oldestShard.evictOne()
+}
+
 // Delete removes a key from the cache
 func (m *MemoryCacheBackend) Delete(ctx context.Context, key string) error {
 	if m.closed.Load() {
 		return ErrBackendUnavailable
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	if _, exists := m.items[key]; !exists {
-		return nil
+	shard := m.getShard(key)
+	if shard.delete(key) {
+		m.deletes.Add(1)
 	}
 
-	m.deleteItemLocked(key)
-	m.deletes.Add(1)
 	return nil
 }
 
-// deleteItemLocked deletes an item without acquiring the lock (must be called with lock held)
-func (m *MemoryCacheBackend) deleteItemLocked(key string) {
-	if item, exists := m.items[key]; exists {
-		m.currentMemory -= item.size
-		m.currentSize--
-		if item.element != nil {
-			m.lruList.Remove(item.element)
-		}
-		delete(m.items, key)
-	}
-}
-
-// evictLocked evicts items based on the eviction policy (must be called with lock held)
-func (m *MemoryCacheBackend) evictLocked() {
-	if m.evictionPolicy == "lru" && m.lruList.Len() > 0 {
-		// Evict least recently used item
-		element := m.lruList.Back()
-		if element != nil {
-			item := element.Value.(*memoryCacheItem)
-			m.deleteItemLocked(item.key)
-			m.evictions.Add(1)
-		}
-	}
-}
-
 // Exists checks if a key exists in the cache
 func (m *MemoryCacheBackend) Exists(ctx context.Context, key string) (bool, error) {
 	if m.closed.Load() {
 		return false, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
-
-	if !exists {
-		return false, nil
-	}
-
-	return !item.isExpired(), nil
+	shard := m.getShard(key)
+	return shard.exists(key), nil
 }
 
 // Clear removes all items from the cache
@@ -297,13 +314,9 @@ func (m *MemoryCacheBackend) Clear(ctx context.Context) error {
 		return ErrBackendUnavailable
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	m.items = make(map[string]*memoryCacheItem)
-	m.lruList = list.New()
-	m.currentSize = 0
-	m.currentMemory = 0
+	for _, shard := range m.shards {
+		shard.clear()
+	}
 
 	return nil
 }
@@ -314,29 +327,28 @@ func (m *MemoryCacheBackend) Keys(ctx context.Context, pattern string) ([]string
 		return nil, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	defer m.mu.RUnlock()
-
-	var keys []string
-	for key, item := range m.items {
-		if !item.isExpired() && matchPattern(pattern, key) {
-			keys = append(keys, key)
-		}
+	var allKeys []string
+	for _, shard := range m.shards {
+		keys := shard.keys(pattern)
+		allKeys = append(allKeys, keys...)
 	}
 
-	return keys, nil
+	return allKeys, nil
 }
 
-// Size returns the number of items in the cache
+// Size returns the total number of items in the cache
 func (m *MemoryCacheBackend) Size(ctx context.Context) (int64, error) {
 	if m.closed.Load() {
 		return 0, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	defer m.mu.RUnlock()
+	var total int64
+	for _, shard := range m.shards {
+		size, _ := shard.stats()
+		total += size
+	}
 
-	return m.currentSize, nil
+	return total, nil
 }
 
 // TTL returns the remaining time-to-live for a key
@@ -345,24 +357,13 @@ func (m *MemoryCacheBackend) TTL(ctx context.Context, key string) (time.Duration
 		return 0, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
-
-	if !exists || item.isExpired() {
+	shard := m.getShard(key)
+	ttl, exists := shard.ttl(key)
+	if !exists {
 		return 0, ErrCacheMiss
 	}
 
-	if item.expiresAt.IsZero() {
-		return 0, nil // No expiration
-	}
-
-	remaining := time.Until(item.expiresAt)
-	if remaining < 0 {
-		return 0, nil
-	}
-
-	return remaining, nil
+	return ttl, nil
 }
 
 // Expire updates the TTL for an existing key
@@ -371,20 +372,11 @@ func (m *MemoryCacheBackend) Expire(ctx context.Context, key string, ttl time.Du
 		return ErrBackendUnavailable
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	item, exists := m.items[key]
-	if !exists || item.isExpired() {
+	shard := m.getShard(key)
+	if !shard.expire(key, ttl) {
 		return ErrCacheMiss
 	}
 
-	if ttl > 0 {
-		item.expiresAt = time.Now().Add(ttl)
-	} else {
-		item.expiresAt = time.Time{} // Remove expiration
-	}
-
 	return nil
 }
 
@@ -394,6 +386,14 @@ func (m *MemoryCacheBackend) GetStats(ctx context.Context) (*BackendStats, error
 		return nil, ErrBackendUnavailable
 	}
 
+	// Aggregate stats from all shards
+	var totalSize, totalMemory int64
+	for _, shard := range m.shards {
+		size, memory := shard.stats()
+		totalSize += size
+		totalMemory += memory
+	}
+
 	m.mu.RLock()
 	lastError := m.lastError
 	lastErrorTime := m.lastErrorTime
@@ -417,9 +417,9 @@ func (m *MemoryCacheBackend) GetStats(ctx context.Context) (*BackendStats, error
 		Deletes:           m.deletes.Load(),
 		Errors:            m.errors.Load(),
 		Evictions:         m.evictions.Load(),
-		CurrentSize:       m.currentSize,
+		CurrentSize:       totalSize,
 		MaxSize:           m.maxSize,
-		MemoryUsage:       m.currentMemory,
+		MemoryUsage:       totalMemory,
 		AverageGetLatency: avgGetLatency,
 		AverageSetLatency: avgSetLatency,
 		LastError:         lastError,
@@ -446,10 +446,10 @@ func (m *MemoryCacheBackend) Close() error {
 	m.cleanupTicker.Stop()
 	close(m.cleanupDone)
 
-	m.mu.Lock()
-	m.items = nil
-	m.lruList = nil
-	m.mu.Unlock()
+	// Clear all shards
+	for _, shard := range m.shards {
+		shard.clear()
+	}
 
 	return nil
 }
@@ -482,12 +482,28 @@ func (m *MemoryCacheBackend) Capabilities() *BackendCapabilities {
 	}
 }
 
+// GetShardCount returns the number of shards (for testing/monitoring)
+func (m *MemoryCacheBackend) GetShardCount() uint32 {
+	return m.shardCount
+}
+
+// GetShardStats returns per-shard statistics (for monitoring)
+func (m *MemoryCacheBackend) GetShardStats() []map[string]int64 {
+	stats := make([]map[string]int64, m.shardCount)
+	for i, shard := range m.shards {
+		size, memory := shard.stats()
+		stats[i] = map[string]int64{
+			"size":   size,
+			"memory": memory,
+		}
+	}
+	return stats
+}
+
 // Helper functions
 
 // estimateValueSize estimates the size of a value in bytes
 func estimateValueSize(value interface{}) int64 {
-	// This is a simplified estimation
-	// In production, you might want to use a more accurate method
 	switch v := value.(type) {
 	case string:
 		return int64(len(v))
@@ -510,7 +526,10 @@ func matchPattern(pattern, key string) bool {
 	if pattern == "*" {
 		return true
 	}
-	// Simplified pattern matching - in production, use a proper glob library
-	return key == pattern || (len(pattern) > 0 && pattern[0] == '*' &&
-		len(key) >= len(pattern)-1 && key[len(key)-len(pattern)+1:] == pattern[1:])
+	// Simplified pattern matching
+	if len(pattern) > 0 && pattern[0] == '*' {
+		suffix := pattern[1:]
+		return len(key) >= len(suffix) && key[len(key)-len(suffix):] == suffix
+	}
+	return key == pattern
 }

internal/cache/backends/memory_shard.go

@@ -0,0 +1,290 @@
+package backends
+
+import (
+	"container/list"
+	"sync"
+	"time"
+)
+
+// cacheShard represents a single shard of the sharded cache
+// Each shard has its own lock for reduced contention
+type cacheShard struct {
+	items      map[string]*memoryCacheItem
+	lruList    *list.List
+	mu         sync.RWMutex
+	maxSize    int64
+	maxMemory  int64
+	size       int64
+	memoryUsed int64
+}
+
+// newCacheShard creates a new cache shard
+func newCacheShard(maxSize, maxMemory int64) *cacheShard {
+	return &cacheShard{
+		items:     make(map[string]*memoryCacheItem),
+		lruList:   list.New(),
+		maxSize:   maxSize,
+		maxMemory: maxMemory,
+	}
+}
+
+// get retrieves a value from this shard
+// Returns: value, exists, expired
+func (s *cacheShard) get(key string) (interface{}, bool, bool) {
+	s.mu.RLock()
+	item, exists := s.items[key]
+	s.mu.RUnlock()
+
+	if !exists {
+		return nil, false, false
+	}
+
+	if item.isExpired() {
+		return nil, true, true // exists but expired
+	}
+
+	// Update access time and LRU position under write lock
+	s.mu.Lock()
+	// Re-check item exists (could have been deleted)
+	item, exists = s.items[key]
+	if exists && !item.isExpired() {
+		item.accessedAt = time.Now()
+		item.accessCount++
+		if elem, ok := item.element.(*list.Element); ok && elem != nil {
+			s.lruList.MoveToFront(elem)
+		}
+	}
+	s.mu.Unlock()
+
+	if !exists || item.isExpired() {
+		return nil, false, false
+	}
+
+	return item.value, true, false
+}
+
+// set stores a value in this shard
+func (s *cacheShard) set(key string, value interface{}, expiresAt time.Time, size int64) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	// Check if we need to evict items
+	if s.maxSize > 0 && s.size >= s.maxSize {
+		s.evictLRULocked()
+	}
+	if s.maxMemory > 0 && s.memoryUsed+size > s.maxMemory {
+		s.evictLRULocked()
+	}
+
+	// Remove old item if exists
+	if oldItem, exists := s.items[key]; exists {
+		s.memoryUsed -= oldItem.size
+		if elem, ok := oldItem.element.(*list.Element); ok && elem != nil {
+			s.lruList.Remove(elem)
+		}
+		s.size--
+	}
+
+	now := time.Now()
+	item := &memoryCacheItem{
+		key:         key,
+		value:       value,
+		expiresAt:   expiresAt,
+		createdAt:   now,
+		accessedAt:  now,
+		accessCount: 0,
+		size:        size,
+	}
+
+	item.element = s.lruList.PushFront(item)
+	s.items[key] = item
+	s.size++
+	s.memoryUsed += size
+}
+
+// delete removes a key from this shard
+// Returns true if the key was deleted
+func (s *cacheShard) delete(key string) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	item, exists := s.items[key]
+	if !exists {
+		return false
+	}
+
+	s.deleteItemLocked(item)
+	return true
+}
+
+// exists checks if a key exists (and is not expired)
+func (s *cacheShard) exists(key string) bool {
+	s.mu.RLock()
+	item, exists := s.items[key]
+	s.mu.RUnlock()
+
+	if !exists {
+		return false
+	}
+
+	return !item.isExpired()
+}
+
+// ttl returns the remaining TTL for a key
+func (s *cacheShard) ttl(key string) (time.Duration, bool) {
+	s.mu.RLock()
+	item, exists := s.items[key]
+	s.mu.RUnlock()
+
+	if !exists || item.isExpired() {
+		return 0, false
+	}
+
+	if item.expiresAt.IsZero() {
+		return 0, true // No expiration
+	}
+
+	remaining := time.Until(item.expiresAt)
+	if remaining < 0 {
+		return 0, false
+	}
+
+	return remaining, true
+}
+
+// expire updates the TTL for an existing key
+func (s *cacheShard) expire(key string, ttl time.Duration) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	item, exists := s.items[key]
+	if !exists || item.isExpired() {
+		return false
+	}
+
+	if ttl > 0 {
+		item.expiresAt = time.Now().Add(ttl)
+	} else {
+		item.expiresAt = time.Time{} // Remove expiration
+	}
+
+	return true
+}
+
+// keys returns all non-expired keys matching the pattern
+func (s *cacheShard) keys(pattern string) []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	var keys []string
+	for key, item := range s.items {
+		if !item.isExpired() && matchPattern(pattern, key) {
+			keys = append(keys, key)
+		}
+	}
+	return keys
+}
+
+// clear removes all items from this shard
+func (s *cacheShard) clear() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.items = make(map[string]*memoryCacheItem)
+	s.lruList.Init()
+	s.size = 0
+	s.memoryUsed = 0
+}
+
+// cleanup removes expired items
+// Returns the number of items removed
+func (s *cacheShard) cleanup() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	var toRemove []*memoryCacheItem
+	for _, item := range s.items {
+		if item.isExpired() {
+			toRemove = append(toRemove, item)
+		}
+	}
+
+	for _, item := range toRemove {
+		s.deleteItemLocked(item)
+	}
+
+	return len(toRemove)
+}
+
+// stats returns statistics for this shard
+func (s *cacheShard) stats() (size, memory int64) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.size, s.memoryUsed
+}
+
+// deleteItemLocked removes an item (must be called with lock held)
+func (s *cacheShard) deleteItemLocked(item *memoryCacheItem) {
+	if elem, ok := item.element.(*list.Element); ok && elem != nil {
+		s.lruList.Remove(elem)
+	}
+	delete(s.items, item.key)
+	s.size--
+	s.memoryUsed -= item.size
+}
+
+// evictLRULocked evicts the least recently used item (must be called with lock held)
+func (s *cacheShard) evictLRULocked() bool {
+	if s.lruList.Len() == 0 {
+		return false
+	}
+
+	element := s.lruList.Back()
+	if element != nil {
+		item := element.Value.(*memoryCacheItem)
+		s.deleteItemLocked(item)
+		return true
+	}
+	return false
+}
+
+// evictOne evicts one item from this shard (for global limit enforcement)
+func (s *cacheShard) evictOne() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.evictLRULocked()
+}
+
+// getOldestAccessTime returns the access time of the LRU item (oldest) in this shard
+// Returns zero time if shard is empty
+func (s *cacheShard) getOldestAccessTime() time.Time {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if s.lruList.Len() == 0 {
+		return time.Time{}
+	}
+
+	element := s.lruList.Back()
+	if element != nil {
+		item := element.Value.(*memoryCacheItem)
+		return item.accessedAt
+	}
+	return time.Time{}
+}
+
+// fnv32 computes FNV-1a hash of a string
+// This is a fast, well-distributed hash function
+func fnv32(key string) uint32 {
+	const (
+		offset32 = uint32(2166136261)
+		prime32  = uint32(16777619)
+	)
+
+	hash := offset32
+	for i := 0; i < len(key); i++ {
+		hash ^= uint32(key[i])
+		hash *= prime32
+	}
+	return hash
+}

internal/cache/backends/memory_shard_test.go

@@ -0,0 +1,283 @@
+package backends
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestShardedCache_ShardDistribution tests that keys are distributed across shards
+func TestShardedCache_ShardDistribution(t *testing.T) {
+	t.Parallel()
+
+	// Create a cache with large enough size to have multiple shards
+	config := DefaultConfig()
+	config.MaxSize = 10000
+	config.MaxMemoryBytes = 100 * 1024 * 1024 // 100MB
+
+	backend, err := NewMemoryBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Add many items to see distribution
+	numItems := 1000
+	for i := 0; i < numItems; i++ {
+		key := fmt.Sprintf("dist-key-%d", i)
+		value := []byte(fmt.Sprintf("dist-value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+	}
+
+	// Check that items are distributed across multiple shards
+	shardStats := backend.MemoryCacheBackend.GetShardStats()
+	nonEmptyShards := 0
+	for _, stat := range shardStats {
+		if stat["size"] > 0 {
+			nonEmptyShards++
+		}
+	}
+
+	// With good hash distribution, we should have items in multiple shards
+	assert.Greater(t, nonEmptyShards, 1, "Items should be distributed across multiple shards")
+}
+
+// TestShardedCache_ShardCount tests that shard count adapts to cache size
+func TestShardedCache_ShardCount(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		maxSize         int
+		expectLowShards bool
+	}{
+		{5, true},      // Very small cache should have fewer shards
+		{100, true},    // Small cache should have fewer shards
+		{10000, false}, // Large cache should have default shards
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("MaxSize_%d", tt.maxSize), func(t *testing.T) {
+			config := DefaultConfig()
+			config.MaxSize = tt.maxSize
+
+			backend, err := NewMemoryBackend(config)
+			require.NoError(t, err)
+			defer backend.Close()
+
+			shardCount := backend.MemoryCacheBackend.GetShardCount()
+
+			if tt.expectLowShards {
+				assert.Less(t, shardCount, uint32(256), "Small cache should have fewer shards")
+			} else {
+				assert.Equal(t, uint32(256), shardCount, "Large cache should have default shard count")
+			}
+		})
+	}
+}
+
+// TestShardedCache_ConcurrentSameKey tests concurrent access to the same key
+func TestShardedCache_ConcurrentSameKey(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+	key := "concurrent-same-key"
+	initialValue := []byte("initial-value")
+
+	err = backend.Set(ctx, key, initialValue, time.Minute)
+	require.NoError(t, err)
+
+	var wg sync.WaitGroup
+	goroutines := 50
+	iterations := 100
+
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				// Mix of reads and writes
+				if j%3 == 0 {
+					newValue := []byte(fmt.Sprintf("value-%d-%d", id, j))
+					err := backend.Set(ctx, key, newValue, time.Minute)
+					assert.NoError(t, err)
+				} else {
+					_, _, _, err := backend.Get(ctx, key)
+					assert.NoError(t, err)
+				}
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Key should still exist
+	exists, err := backend.Exists(ctx, key)
+	require.NoError(t, err)
+	assert.True(t, exists)
+}
+
+// TestShardedCache_GlobalLRUEviction tests that global LRU is maintained
+func TestShardedCache_GlobalLRUEviction(t *testing.T) {
+	t.Parallel()
+
+	// Create a small cache to force eviction
+	config := DefaultConfig()
+	config.MaxSize = 10
+
+	backend, err := NewMemoryBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Add items
+	for i := 0; i < 10; i++ {
+		key := fmt.Sprintf("global-lru-%d", i)
+		value := []byte(fmt.Sprintf("value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+		// Small delay to ensure different access times
+		time.Sleep(time.Millisecond)
+	}
+
+	// Access some items to make them recently used
+	for i := 5; i < 10; i++ {
+		key := fmt.Sprintf("global-lru-%d", i)
+		_, _, _, err := backend.Get(ctx, key)
+		require.NoError(t, err)
+	}
+
+	// Add more items to trigger eviction
+	for i := 10; i < 15; i++ {
+		key := fmt.Sprintf("global-lru-%d", i)
+		value := []byte(fmt.Sprintf("value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+	}
+
+	// Recently accessed items (5-9) should still exist
+	for i := 5; i < 10; i++ {
+		key := fmt.Sprintf("global-lru-%d", i)
+		exists, err := backend.Exists(ctx, key)
+		require.NoError(t, err)
+		assert.True(t, exists, "Recently accessed item %d should exist", i)
+	}
+
+	// Check eviction stats
+	stats := backend.GetStats()
+	evictions := stats["evictions"].(int64)
+	assert.Greater(t, evictions, int64(0), "Should have evictions")
+}
+
+// TestShardedCache_StatsAggregation tests that stats are aggregated correctly
+func TestShardedCache_StatsAggregation(t *testing.T) {
+	t.Parallel()
+
+	config := DefaultConfig()
+	config.MaxSize = 10000
+
+	backend, err := NewMemoryBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Add items to multiple shards
+	numItems := 100
+	for i := 0; i < numItems; i++ {
+		key := fmt.Sprintf("stats-key-%d", i)
+		value := []byte(fmt.Sprintf("stats-value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+	}
+
+	// Read some items
+	for i := 0; i < numItems/2; i++ {
+		key := fmt.Sprintf("stats-key-%d", i)
+		backend.Get(ctx, key)
+	}
+
+	// Read non-existent items
+	for i := 0; i < 10; i++ {
+		backend.Get(ctx, fmt.Sprintf("nonexistent-%d", i))
+	}
+
+	stats := backend.GetStats()
+
+	// Verify stats
+	assert.Equal(t, int64(numItems), stats["sets"].(int64), "Sets should match")
+	assert.Equal(t, int64(numItems/2), stats["hits"].(int64), "Hits should match")
+	assert.Equal(t, int64(10), stats["misses"].(int64), "Misses should match")
+	assert.Equal(t, int64(numItems), stats["size"].(int64), "Size should match")
+
+	// Verify hit rate
+	hitRate := stats["hit_rate"].(float64)
+	expectedHitRate := float64(numItems/2) / float64(numItems/2+10)
+	assert.InDelta(t, expectedHitRate, hitRate, 0.01, "Hit rate should match")
+}
+
+// BenchmarkShardedCache_Parallel benchmarks parallel access
+func BenchmarkShardedCache_Parallel(b *testing.B) {
+	config := DefaultConfig()
+	config.MaxSize = 100000
+	config.MaxMemoryBytes = 100 * 1024 * 1024
+
+	backend, _ := NewMemoryBackend(config)
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Pre-populate cache
+	for i := 0; i < 10000; i++ {
+		key := fmt.Sprintf("bench-key-%d", i)
+		value := []byte(fmt.Sprintf("bench-value-%d", i))
+		backend.Set(ctx, key, value, time.Hour)
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			key := fmt.Sprintf("bench-key-%d", i%10000)
+			backend.Get(ctx, key)
+			i++
+		}
+	})
+}
+
+// BenchmarkShardedCache_MixedOps benchmarks mixed operations
+func BenchmarkShardedCache_MixedOps(b *testing.B) {
+	config := DefaultConfig()
+	config.MaxSize = 100000
+	config.MaxMemoryBytes = 100 * 1024 * 1024
+
+	backend, _ := NewMemoryBackend(config)
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			key := fmt.Sprintf("mixed-key-%d", i%1000)
+			if i%3 == 0 {
+				value := []byte(fmt.Sprintf("mixed-value-%d", i))
+				backend.Set(ctx, key, value, time.Hour)
+			} else {
+				backend.Get(ctx, key)
+			}
+			i++
+		}
+	})
+}

internal/cache/backends/memory_wrapper.go

@@ -45,21 +45,11 @@ func (m *MemoryBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 		return nil, 0, false, err
 	}
 
-	// Get the item directly to check TTL
-	m.MemoryCacheBackend.mu.RLock()
-	item, exists := m.MemoryCacheBackend.items[key]
-	m.MemoryCacheBackend.mu.RUnlock()
-
-	if !exists {
-		return nil, 0, false, nil
-	}
-
-	var ttl time.Duration
-	if !item.expiresAt.IsZero() {
-		ttl = time.Until(item.expiresAt)
-		if ttl < 0 {
-			ttl = 0
-		}
+	// Get TTL using the TTL method
+	ttl, ttlErr := m.MemoryCacheBackend.TTL(ctx, key)
+	if ttlErr != nil {
+		// If we can't get TTL, still return the value with 0 TTL
+		ttl = 0
 	}
 
 	// Convert interface{} to []byte
@@ -68,8 +58,7 @@ func (m *MemoryBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 		if bytes, ok := val.([]byte); ok {
 			valueBytes = bytes
 		} else {
-			// If it's not already []byte, we might need to handle other types
-			// For now, we'll just return an error
+			// If it's not already []byte, return an error
 			return nil, 0, false, ErrInvalidValue
 		}
 	}
@@ -123,19 +112,20 @@ func (m *MemoryBackend) GetStats() map[string]interface{} {
 	}
 
 	return map[string]interface{}{
-		"type":       stats.Type,
-		"hits":       stats.Hits,
-		"misses":     stats.Misses,
-		"sets":       stats.Sets,
-		"deletes":    stats.Deletes,
-		"errors":     stats.Errors,
-		"evictions":  stats.Evictions,
-		"size":       stats.CurrentSize,
-		"max_size":   stats.MaxSize,
-		"memory":     stats.MemoryUsage,
-		"hit_rate":   hitRate,
-		"uptime":     stats.Uptime,
-		"start_time": stats.StartTime,
+		"type":        stats.Type,
+		"hits":        stats.Hits,
+		"misses":      stats.Misses,
+		"sets":        stats.Sets,
+		"deletes":     stats.Deletes,
+		"errors":      stats.Errors,
+		"evictions":   stats.Evictions,
+		"size":        stats.CurrentSize,
+		"max_size":    stats.MaxSize,
+		"memory":      stats.MemoryUsage,
+		"hit_rate":    hitRate,
+		"uptime":      stats.Uptime,
+		"start_time":  stats.StartTime,
+		"shard_count": m.MemoryCacheBackend.GetShardCount(),
 	}
 }
 

internal/cache/backends/redis.go

@@ -431,39 +431,135 @@ func isRetryableError(err error) bool {
 	return false
 }
 
-// SetMany stores multiple values in Redis (batch operation)
+// SetMany stores multiple values in Redis using pipelining for efficiency
+// This reduces N round-trips to a single round-trip
 func (r *RedisBackend) SetMany(ctx context.Context, items map[string][]byte, ttl time.Duration) error {
 	if r.closed.Load() {
 		return ErrBackendClosed
 	}
 
-	// For simplicity, execute sequentially (can be optimized with pipelining later)
-	for key, value := range items {
-		if err := r.Set(ctx, key, value, ttl); err != nil {
-			return err
+	if len(items) == 0 {
+		return nil
+	}
+
+	// For single items, use regular Set
+	if len(items) == 1 {
+		for key, value := range items {
+			return r.Set(ctx, key, value, ttl)
 		}
 	}
 
+	conn, err := r.pool.Get(ctx)
+	if err != nil {
+		return err
+	}
+	defer r.pool.Put(conn)
+
+	pipeline := conn.NewPipeline()
+
+	// Queue all SET commands
+	ttlSeconds := int(ttl.Seconds())
+	ttlMillis := ttl.Milliseconds()
+
+	for key, value := range items {
+		prefixedKey := r.prefixKey(key)
+
+		if ttl > 0 {
+			if ttlMillis < 1000 {
+				// Use PSETEX for sub-second TTLs
+				pipeline.Queue("PSETEX", prefixedKey, fmt.Sprintf("%d", ttlMillis), string(value))
+			} else {
+				// Use SETEX for larger TTLs
+				pipeline.Queue("SETEX", prefixedKey, fmt.Sprintf("%d", ttlSeconds), string(value))
+			}
+		} else {
+			pipeline.Queue("SET", prefixedKey, string(value))
+		}
+	}
+
+	// Execute pipeline
+	responses, err := pipeline.Execute()
+	if err != nil {
+		return fmt.Errorf("pipeline SetMany failed: %w", err)
+	}
+
+	// Check responses for errors (each should be "OK")
+	for i, resp := range responses {
+		if resp == nil {
+			continue
+		}
+		if str, ok := resp.(string); ok && str == "OK" {
+			continue
+		}
+		return fmt.Errorf("SetMany: unexpected response at index %d: %v", i, resp)
+	}
+
 	return nil
 }
 
-// GetMany retrieves multiple values from Redis
+// GetMany retrieves multiple values from Redis using pipelining for efficiency
+// This reduces N round-trips to a single round-trip
 func (r *RedisBackend) GetMany(ctx context.Context, keys []string) (map[string][]byte, error) {
 	if r.closed.Load() {
 		return nil, ErrBackendClosed
 	}
 
-	result := make(map[string][]byte)
+	if len(keys) == 0 {
+		return make(map[string][]byte), nil
+	}
 
-	// For simplicity, execute sequentially
-	for _, key := range keys {
-		value, _, exists, err := r.Get(ctx, key)
+	// For single key, use regular Get
+	if len(keys) == 1 {
+		result := make(map[string][]byte)
+		value, _, exists, err := r.Get(ctx, keys[0])
 		if err != nil {
 			return nil, err
 		}
 		if exists {
-			result[key] = value
+			result[keys[0]] = value
 		}
+		return result, nil
+	}
+
+	conn, err := r.pool.Get(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer r.pool.Put(conn)
+
+	pipeline := conn.NewPipeline()
+
+	// Queue all GET commands
+	prefixedKeys := make([]string, len(keys))
+	for i, key := range keys {
+		prefixedKeys[i] = r.prefixKey(key)
+		pipeline.Queue("GET", prefixedKeys[i])
+	}
+
+	// Execute pipeline
+	responses, err := pipeline.Execute()
+	if err != nil {
+		return nil, fmt.Errorf("pipeline GetMany failed: %w", err)
+	}
+
+	// Process responses
+	result := make(map[string][]byte)
+	for i, resp := range responses {
+		if resp == nil {
+			// Key doesn't exist
+			r.misses.Add(1)
+			continue
+		}
+
+		value, err := RESPString(resp)
+		if err != nil {
+			// Invalid response, skip this key
+			r.misses.Add(1)
+			continue
+		}
+
+		r.hits.Add(1)
+		result[keys[i]] = []byte(value)
 	}
 
 	return result, nil

internal/cache/backends/redis_health.go

@@ -9,30 +9,24 @@ import (
 
 // HealthMonitor continuously monitors Redis connection health and triggers reconnections
 type HealthMonitor struct {
-	pool   *ConnectionPool
-	config *HealthMonitorConfig
-
-	// State
-	healthy       atomic.Bool
-	running       atomic.Bool
-	lastCheckTime atomic.Int64 // Unix timestamp
-
-	// Metrics
+	pool                *ConnectionPool
+	config              *HealthMonitorConfig
+	stopChan            chan struct{}
+	wg                  sync.WaitGroup
+	lastCheckTime       atomic.Int64
 	consecutiveFailures atomic.Int64
 	totalChecks         atomic.Int64
 	totalFailures       atomic.Int64
-
-	// Lifecycle
-	stopChan chan struct{}
-	wg       sync.WaitGroup
+	healthy             atomic.Bool
+	running             atomic.Bool
 }
 
 // HealthMonitorConfig configures the health monitor
 type HealthMonitorConfig struct {
-	CheckInterval      time.Duration // How often to check health
-	Timeout            time.Duration // Timeout for health check
-	UnhealthyThreshold int           // Consecutive failures before marking unhealthy
 	OnHealthChange     func(healthy bool)
+	CheckInterval      time.Duration
+	Timeout            time.Duration
+	UnhealthyThreshold int
 }
 
 // DefaultHealthMonitorConfig returns default health monitor configuration

internal/cache/backends/redis_pipeline_test.go

@@ -0,0 +1,461 @@
+package backends
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// setupTestRedis creates a miniredis instance for testing
+func setupTestRedis(t *testing.T) (*miniredis.Miniredis, *RedisBackend) {
+	t.Helper()
+
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		mr.Close()
+	})
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "test:",
+		PoolSize:    5,
+	})
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		backend.Close()
+	})
+
+	return mr, backend
+}
+
+// TestPipeline_Basic tests basic pipeline functionality
+func TestPipeline_Basic(t *testing.T) {
+	t.Parallel()
+
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+	defer mr.Close()
+
+	config := &PoolConfig{
+		Address:        mr.Addr(),
+		MaxConnections: 5,
+		ConnectTimeout: 5 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+	}
+
+	pool, err := NewConnectionPool(config)
+	require.NoError(t, err)
+	defer pool.Close()
+
+	ctx := context.Background()
+
+	conn, err := pool.Get(ctx)
+	require.NoError(t, err)
+	defer pool.Put(conn)
+
+	t.Run("SingleCommand", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("SET", "single-key", "single-value")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 1)
+		assert.Equal(t, "OK", responses[0])
+	})
+
+	t.Run("MultipleCommands", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("SET", "key1", "value1")
+		pipeline.Queue("SET", "key2", "value2")
+		pipeline.Queue("SET", "key3", "value3")
+		pipeline.Queue("GET", "key1")
+		pipeline.Queue("GET", "key2")
+		pipeline.Queue("GET", "key3")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 6)
+
+		// First 3 are SET responses
+		assert.Equal(t, "OK", responses[0])
+		assert.Equal(t, "OK", responses[1])
+		assert.Equal(t, "OK", responses[2])
+
+		// Last 3 are GET responses
+		assert.Equal(t, "value1", responses[3])
+		assert.Equal(t, "value2", responses[4])
+		assert.Equal(t, "value3", responses[5])
+	})
+
+	t.Run("EmptyPipeline", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		assert.Nil(t, responses)
+	})
+
+	t.Run("NilResponses", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("GET", "nonexistent-key")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 1)
+		assert.Nil(t, responses[0])
+	})
+}
+
+// TestPipeline_SetMany tests pipelined SetMany
+func TestPipeline_SetMany(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	t.Run("SetManyItems", func(t *testing.T) {
+		items := make(map[string][]byte)
+		for i := 0; i < 10; i++ {
+			items[fmt.Sprintf("setmany-key-%d", i)] = []byte(fmt.Sprintf("value-%d", i))
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		// Verify all items were set
+		for key, expectedValue := range items {
+			value, _, exists, err := backend.Get(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists, "Key %s should exist", key)
+			assert.Equal(t, expectedValue, value)
+		}
+	})
+
+	t.Run("SetManyEmpty", func(t *testing.T) {
+		err := backend.SetMany(ctx, map[string][]byte{}, time.Minute)
+		require.NoError(t, err)
+	})
+
+	t.Run("SetManySingleItem", func(t *testing.T) {
+		items := map[string][]byte{
+			"single-setmany": []byte("single-value"),
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		value, _, exists, err := backend.Get(ctx, "single-setmany")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("single-value"), value)
+	})
+
+	t.Run("SetManyNoTTL", func(t *testing.T) {
+		items := map[string][]byte{
+			"nottl-key1": []byte("value1"),
+			"nottl-key2": []byte("value2"),
+		}
+
+		err := backend.SetMany(ctx, items, 0)
+		require.NoError(t, err)
+
+		// Keys should exist
+		for key := range items {
+			exists, err := backend.Exists(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists)
+		}
+	})
+}
+
+// TestPipeline_GetMany tests pipelined GetMany
+func TestPipeline_GetMany(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	// Pre-populate cache
+	for i := 0; i < 10; i++ {
+		key := fmt.Sprintf("getmany-key-%d", i)
+		value := []byte(fmt.Sprintf("value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+	}
+
+	t.Run("GetManyExisting", func(t *testing.T) {
+		keys := make([]string, 10)
+		for i := 0; i < 10; i++ {
+			keys[i] = fmt.Sprintf("getmany-key-%d", i)
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 10)
+
+		for i, key := range keys {
+			assert.Equal(t, []byte(fmt.Sprintf("value-%d", i)), results[key])
+		}
+	})
+
+	t.Run("GetManyMixed", func(t *testing.T) {
+		keys := []string{
+			"getmany-key-0",     // exists
+			"nonexistent-key-1", // doesn't exist
+			"getmany-key-2",     // exists
+			"nonexistent-key-2", // doesn't exist
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 2) // Only existing keys
+
+		assert.Equal(t, []byte("value-0"), results["getmany-key-0"])
+		assert.Equal(t, []byte("value-2"), results["getmany-key-2"])
+		assert.NotContains(t, results, "nonexistent-key-1")
+		assert.NotContains(t, results, "nonexistent-key-2")
+	})
+
+	t.Run("GetManyEmpty", func(t *testing.T) {
+		results, err := backend.GetMany(ctx, []string{})
+		require.NoError(t, err)
+		assert.NotNil(t, results)
+		assert.Len(t, results, 0)
+	})
+
+	t.Run("GetManySingleKey", func(t *testing.T) {
+		results, err := backend.GetMany(ctx, []string{"getmany-key-5"})
+		require.NoError(t, err)
+		assert.Len(t, results, 1)
+		assert.Equal(t, []byte("value-5"), results["getmany-key-5"])
+	})
+
+	t.Run("GetManyAllNonexistent", func(t *testing.T) {
+		keys := []string{
+			"nonexistent-1",
+			"nonexistent-2",
+			"nonexistent-3",
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 0)
+	})
+}
+
+// TestPipeline_LargeBatch tests pipelining with large batches
+func TestPipeline_LargeBatch(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	t.Run("SetMany100Items", func(t *testing.T) {
+		items := make(map[string][]byte)
+		for i := 0; i < 100; i++ {
+			items[fmt.Sprintf("large-batch-%d", i)] = []byte(fmt.Sprintf("value-%d", i))
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		// Verify random samples
+		for _, i := range []int{0, 25, 50, 75, 99} {
+			key := fmt.Sprintf("large-batch-%d", i)
+			value, _, exists, err := backend.Get(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists)
+			assert.Equal(t, []byte(fmt.Sprintf("value-%d", i)), value)
+		}
+	})
+
+	t.Run("GetMany100Items", func(t *testing.T) {
+		keys := make([]string, 100)
+		for i := 0; i < 100; i++ {
+			keys[i] = fmt.Sprintf("large-batch-%d", i)
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 100)
+	})
+}
+
+// TestPipeline_Stats tests that stats are tracked correctly with pipelining
+func TestPipeline_Stats(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	// Set some items
+	items := map[string][]byte{
+		"stats-key-1": []byte("value1"),
+		"stats-key-2": []byte("value2"),
+	}
+	err := backend.SetMany(ctx, items, time.Minute)
+	require.NoError(t, err)
+
+	// Get items (some exist, some don't)
+	keys := []string{
+		"stats-key-1",
+		"stats-key-2",
+		"stats-key-nonexistent",
+	}
+	results, err := backend.GetMany(ctx, keys)
+	require.NoError(t, err)
+	assert.Len(t, results, 2)
+
+	// Check stats
+	stats := backend.GetStats()
+	hits := stats["hits"].(int64)
+	misses := stats["misses"].(int64)
+
+	assert.Equal(t, int64(2), hits, "Should have 2 hits")
+	assert.Equal(t, int64(1), misses, "Should have 1 miss")
+}
+
+// BenchmarkPipeline_SetMany benchmarks SetMany with pipelining
+func BenchmarkPipeline_SetMany(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Prepare items
+	items := make(map[string][]byte)
+	for i := 0; i < 100; i++ {
+		items[fmt.Sprintf("bench-key-%d", i)] = []byte(fmt.Sprintf("bench-value-%d", i))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = backend.SetMany(ctx, items, time.Minute)
+	}
+}
+
+// BenchmarkPipeline_GetMany benchmarks GetMany with pipelining
+func BenchmarkPipeline_GetMany(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Pre-populate cache
+	for i := 0; i < 100; i++ {
+		key := fmt.Sprintf("bench-key-%d", i)
+		value := []byte(fmt.Sprintf("bench-value-%d", i))
+		backend.Set(ctx, key, value, time.Hour)
+	}
+
+	// Prepare keys
+	keys := make([]string, 100)
+	for i := 0; i < 100; i++ {
+		keys[i] = fmt.Sprintf("bench-key-%d", i)
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = backend.GetMany(ctx, keys)
+	}
+}
+
+// BenchmarkPipeline_VsSequential benchmarks pipeline vs sequential operations
+func BenchmarkPipeline_VsSequential(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Prepare items
+	items := make(map[string][]byte)
+	keys := make([]string, 50)
+	for i := 0; i < 50; i++ {
+		key := fmt.Sprintf("compare-key-%d", i)
+		keys[i] = key
+		items[key] = []byte(fmt.Sprintf("compare-value-%d", i))
+	}
+
+	b.Run("Pipelined-Set", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			_ = backend.SetMany(ctx, items, time.Minute)
+		}
+	})
+
+	b.Run("Sequential-Set", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			for key, value := range items {
+				_ = backend.Set(ctx, key, value, time.Minute)
+			}
+		}
+	})
+
+	// Pre-populate for get benchmarks
+	_ = backend.SetMany(ctx, items, time.Hour)
+
+	b.Run("Pipelined-Get", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			_, _ = backend.GetMany(ctx, keys)
+		}
+	})
+
+	b.Run("Sequential-Get", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			for _, key := range keys {
+				_, _, _, _ = backend.Get(ctx, key)
+			}
+		}
+	})
+}

internal/cache/backends/redis_pool.go

@@ -336,3 +336,120 @@ func (p *ConnectionPool) isConnectionHealthy(conn *RedisConn) bool {
 	_, err := conn.Do("PING")
 	return err == nil
 }
+
+// Pipeline represents a Redis pipeline for batch operations
+// It queues multiple commands and executes them in a single round-trip
+type Pipeline struct {
+	conn     *RedisConn
+	commands []pipelineCommand
+	mu       sync.Mutex
+}
+
+// pipelineCommand represents a single command in the pipeline
+type pipelineCommand struct {
+	command string
+	args    []string
+}
+
+// NewPipeline creates a new pipeline for the connection
+func (c *RedisConn) NewPipeline() *Pipeline {
+	return &Pipeline{
+		conn:     c,
+		commands: make([]pipelineCommand, 0, 16), // Pre-allocate for typical batch size
+	}
+}
+
+// Queue adds a command to the pipeline
+func (p *Pipeline) Queue(command string, args ...string) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.commands = append(p.commands, pipelineCommand{
+		command: command,
+		args:    args,
+	})
+}
+
+// Execute sends all queued commands and returns all responses
+// Returns a slice of responses in the same order as commands were queued
+func (p *Pipeline) Execute() ([]interface{}, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if len(p.commands) == 0 {
+		return nil, nil
+	}
+
+	if p.conn.closed.Load() {
+		return nil, ErrBackendClosed
+	}
+
+	p.conn.mu.Lock()
+	defer p.conn.mu.Unlock()
+
+	// Set write timeout for all commands
+	if p.conn.writeTimeout > 0 {
+		// Use longer timeout for batch operations
+		timeout := p.conn.writeTimeout * time.Duration(len(p.commands))
+		if timeout > 30*time.Second {
+			timeout = 30 * time.Second // Cap at 30 seconds
+		}
+		_ = p.conn.conn.SetWriteDeadline(time.Now().Add(timeout))
+	}
+
+	// Write all commands (pipelining - send all before reading any responses)
+	writer := NewRESPWriter(p.conn.conn)
+	for _, cmd := range p.commands {
+		cmdArgs := append([]string{cmd.command}, cmd.args...)
+		if err := writer.WriteCommand(cmdArgs...); err != nil {
+			writer.Release()
+			p.conn.closed.Store(true)
+			return nil, fmt.Errorf("pipeline write error: %w", err)
+		}
+	}
+	writer.Release()
+
+	// Set read timeout for all responses
+	if p.conn.readTimeout > 0 {
+		timeout := p.conn.readTimeout * time.Duration(len(p.commands))
+		if timeout > 30*time.Second {
+			timeout = 30 * time.Second
+		}
+		_ = p.conn.conn.SetReadDeadline(time.Now().Add(timeout))
+	}
+
+	// Read all responses
+	responses := make([]interface{}, len(p.commands))
+	reader := NewRESPReader(p.conn.conn)
+	defer reader.Release()
+
+	for i := range p.commands {
+		resp, err := reader.ReadResponse()
+		if err != nil {
+			// For nil responses, store nil instead of erroring
+			if errors.Is(err, ErrNilResponse) {
+				responses[i] = nil
+				continue
+			}
+			p.conn.closed.Store(true)
+			return responses[:i], fmt.Errorf("pipeline read error at command %d: %w", i, err)
+		}
+		responses[i] = resp
+	}
+
+	return responses, nil
+}
+
+// Clear resets the pipeline for reuse
+func (p *Pipeline) Clear() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.commands = p.commands[:0]
+}
+
+// Len returns the number of queued commands
+func (p *Pipeline) Len() int {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return len(p.commands)
+}

internal/cache/backends/resp_test.go

@@ -15,8 +15,8 @@ import (
 func TestRESPWriter_WriteCommand(t *testing.T) {
 	tests := []struct {
 		name     string
-		args     []string
 		expected string
+		args     []string
 	}{
 		{
 			name:     "Simple command",
@@ -205,9 +205,9 @@ func TestRESPReader_ReadInteger(t *testing.T) {
 // TestRESPReader_ReadBulkString tests reading bulk strings
 func TestRESPReader_ReadBulkString(t *testing.T) {
 	tests := []struct {
+		expected interface{}
 		name     string
 		input    string
-		expected interface{}
 		wantErr  bool
 		isNil    bool
 	}{
@@ -440,10 +440,10 @@ func TestRESPHelpers(t *testing.T) {
 // TestRESPRoundTrip tests full round-trip encoding/decoding
 func TestRESPRoundTrip(t *testing.T) {
 	tests := []struct {
-		name     string
-		command  []string
-		response string
 		expected interface{}
+		name     string
+		response string
+		command  []string
 	}{
 		{
 			name:     "PING command",

internal/cache/backends/singleflight.go

@@ -0,0 +1,183 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// SingleflightCache wraps a CacheBackend with singleflight deduplication
+// to prevent thundering herd problems when multiple concurrent requests
+// try to fetch the same uncached key.
+type SingleflightCache struct {
+	backend CacheBackend
+	mu      sync.Mutex
+	calls   map[string]*singleflightCall
+
+	// Metrics
+	deduplicatedCalls atomic.Int64
+	totalCalls        atomic.Int64
+}
+
+// singleflightCall represents an in-flight or completed fetch call
+type singleflightCall struct {
+	wg   sync.WaitGroup
+	val  []byte
+	ttl  time.Duration
+	err  error
+	done bool
+}
+
+// NewSingleflightCache creates a new singleflight-wrapped cache backend
+func NewSingleflightCache(backend CacheBackend) *SingleflightCache {
+	return &SingleflightCache{
+		backend: backend,
+		calls:   make(map[string]*singleflightCall),
+	}
+}
+
+// Fetcher is a function type that fetches data when cache misses
+type Fetcher func(ctx context.Context) (value []byte, ttl time.Duration, err error)
+
+// GetOrFetch retrieves a value from cache or calls the fetcher exactly once
+// per key when there's a cache miss. Concurrent calls for the same key will
+// wait for the first call to complete and share its result.
+func (s *SingleflightCache) GetOrFetch(ctx context.Context, key string, fetcher Fetcher) ([]byte, error) {
+	s.totalCalls.Add(1)
+
+	// Try cache first
+	value, _, exists, err := s.backend.Get(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	if exists {
+		return value, nil
+	}
+
+	// Cache miss - use singleflight
+	s.mu.Lock()
+
+	// Check if there's already an in-flight call for this key
+	if call, ok := s.calls[key]; ok {
+		s.mu.Unlock()
+		s.deduplicatedCalls.Add(1)
+
+		// Wait for the in-flight call to complete
+		call.wg.Wait()
+
+		// Check context cancellation
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		return call.val, call.err
+	}
+
+	// Create new call
+	call := &singleflightCall{}
+	call.wg.Add(1)
+	s.calls[key] = call
+	s.mu.Unlock()
+
+	// Execute the fetcher
+	call.val, call.ttl, call.err = fetcher(ctx)
+	call.done = true
+
+	// If successful, store in cache
+	if call.err == nil && call.val != nil {
+		// Use a background context for cache storage to ensure it completes
+		// even if the original context is cancelled
+		storeCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		_ = s.backend.Set(storeCtx, key, call.val, call.ttl)
+		cancel()
+	}
+
+	// Signal waiting goroutines
+	call.wg.Done()
+
+	// Clean up the call from the map after a short delay
+	// This allows late arrivals to still benefit from the result
+	go func() {
+		time.Sleep(100 * time.Millisecond)
+		s.mu.Lock()
+		if c, ok := s.calls[key]; ok && c == call {
+			delete(s.calls, key)
+		}
+		s.mu.Unlock()
+	}()
+
+	return call.val, call.err
+}
+
+// Get retrieves a value from the underlying cache backend
+func (s *SingleflightCache) Get(ctx context.Context, key string) ([]byte, time.Duration, bool, error) {
+	return s.backend.Get(ctx, key)
+}
+
+// Set stores a value in the underlying cache backend
+func (s *SingleflightCache) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
+	return s.backend.Set(ctx, key, value, ttl)
+}
+
+// Delete removes a key from the underlying cache backend
+func (s *SingleflightCache) Delete(ctx context.Context, key string) (bool, error) {
+	return s.backend.Delete(ctx, key)
+}
+
+// Exists checks if a key exists in the underlying cache backend
+func (s *SingleflightCache) Exists(ctx context.Context, key string) (bool, error) {
+	return s.backend.Exists(ctx, key)
+}
+
+// Clear removes all keys from the underlying cache backend
+func (s *SingleflightCache) Clear(ctx context.Context) error {
+	return s.backend.Clear(ctx)
+}
+
+// GetStats returns cache statistics including singleflight metrics
+func (s *SingleflightCache) GetStats() map[string]interface{} {
+	stats := s.backend.GetStats()
+
+	// Add singleflight-specific stats
+	totalCalls := s.totalCalls.Load()
+	deduped := s.deduplicatedCalls.Load()
+
+	stats["singleflight_total_calls"] = totalCalls
+	stats["singleflight_deduplicated"] = deduped
+	if totalCalls > 0 {
+		stats["singleflight_dedup_rate"] = float64(deduped) / float64(totalCalls)
+	} else {
+		stats["singleflight_dedup_rate"] = float64(0)
+	}
+
+	s.mu.Lock()
+	stats["singleflight_inflight"] = len(s.calls)
+	s.mu.Unlock()
+
+	return stats
+}
+
+// Close shuts down the cache backend
+func (s *SingleflightCache) Close() error {
+	return s.backend.Close()
+}
+
+// Ping checks if the backend is healthy
+func (s *SingleflightCache) Ping(ctx context.Context) error {
+	return s.backend.Ping(ctx)
+}
+
+// GetBackend returns the underlying cache backend
+func (s *SingleflightCache) GetBackend() CacheBackend {
+	return s.backend
+}
+
+// ResetStats resets the singleflight statistics
+func (s *SingleflightCache) ResetStats() {
+	s.totalCalls.Store(0)
+	s.deduplicatedCalls.Store(0)
+}
+
+// Ensure SingleflightCache implements CacheBackend
+var _ CacheBackend = (*SingleflightCache)(nil)

internal/cache/backends/singleflight_test.go

@@ -0,0 +1,510 @@
+package backends
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSingleflightCache_BasicGetOrFetch tests basic GetOrFetch functionality
+func TestSingleflightCache_BasicGetOrFetch(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	t.Run("CacheHit", func(t *testing.T) {
+		key := "existing-key"
+		value := []byte("existing-value")
+
+		// Pre-populate cache
+		err := cache.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+
+		var fetchCalled bool
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCalled = true
+			return []byte("fetched-value"), time.Minute, nil
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		require.NoError(t, err)
+		assert.Equal(t, value, result)
+		assert.False(t, fetchCalled, "Fetcher should not be called on cache hit")
+	})
+
+	t.Run("CacheMiss", func(t *testing.T) {
+		key := "missing-key"
+		expectedValue := []byte("fetched-value")
+
+		var fetchCalled bool
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCalled = true
+			return expectedValue, time.Minute, nil
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		require.NoError(t, err)
+		assert.Equal(t, expectedValue, result)
+		assert.True(t, fetchCalled, "Fetcher should be called on cache miss")
+
+		// Verify value was stored in cache
+		cached, _, exists, err := cache.Get(ctx, key)
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, expectedValue, cached)
+	})
+
+	t.Run("FetcherError", func(t *testing.T) {
+		key := "error-key"
+		expectedErr := errors.New("fetch failed")
+
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			return nil, 0, expectedErr
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		assert.Error(t, err)
+		assert.Equal(t, expectedErr, err)
+		assert.Nil(t, result)
+
+		// Verify nothing was stored in cache
+		_, _, exists, err := cache.Get(ctx, key)
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+}
+
+// TestSingleflightCache_Deduplication tests that concurrent calls are deduplicated
+func TestSingleflightCache_Deduplication(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	key := "dedup-key"
+	expectedValue := []byte("dedup-value")
+
+	var fetchCount atomic.Int32
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		fetchCount.Add(1)
+		// Simulate slow fetch
+		time.Sleep(100 * time.Millisecond)
+		return expectedValue, time.Minute, nil
+	}
+
+	// Launch multiple concurrent requests
+	concurrency := 10
+	var wg sync.WaitGroup
+	results := make([][]byte, concurrency)
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			results[idx], errs[idx] = cache.GetOrFetch(ctx, key, fetcher)
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify all requests got the same result
+	for i := 0; i < concurrency; i++ {
+		assert.NoError(t, errs[i])
+		assert.Equal(t, expectedValue, results[i])
+	}
+
+	// Verify fetcher was only called once
+	assert.Equal(t, int32(1), fetchCount.Load(), "Fetcher should only be called once")
+
+	// Verify deduplication stats
+	stats := cache.GetStats()
+	deduped := stats["singleflight_deduplicated"].(int64)
+	assert.Equal(t, int64(concurrency-1), deduped, "Should have deduplicated N-1 calls")
+}
+
+// TestSingleflightCache_DifferentKeys tests that different keys can fetch in parallel
+func TestSingleflightCache_DifferentKeys(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	var fetchCount atomic.Int32
+	fetchStarted := make(chan struct{}, 3)
+	fetchComplete := make(chan struct{})
+
+	fetcher := func(key string) Fetcher {
+		return func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCount.Add(1)
+			fetchStarted <- struct{}{}
+			<-fetchComplete // Wait for signal
+			return []byte("value-" + key), time.Minute, nil
+		}
+	}
+
+	// Launch concurrent requests for different keys
+	var wg sync.WaitGroup
+	for i := 0; i < 3; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			key := fmt.Sprintf("key-%d", idx)
+			_, _ = cache.GetOrFetch(ctx, key, fetcher(key))
+		}(i)
+	}
+
+	// Wait for all fetches to start
+	for i := 0; i < 3; i++ {
+		<-fetchStarted
+	}
+
+	// All 3 fetches should be running in parallel
+	assert.Equal(t, int32(3), fetchCount.Load(), "All three fetches should run in parallel")
+
+	// Release all fetches
+	close(fetchComplete)
+	wg.Wait()
+}
+
+// TestSingleflightCache_ContextCancellation tests context cancellation
+func TestSingleflightCache_ContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	key := "cancel-key"
+	fetchStarted := make(chan struct{})
+
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		close(fetchStarted)
+		// Simulate slow fetch
+		time.Sleep(500 * time.Millisecond)
+		return []byte("value"), time.Minute, nil
+	}
+
+	// Start first request with long timeout
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		ctx := context.Background()
+		_, _ = cache.GetOrFetch(ctx, key, fetcher)
+	}()
+
+	// Wait for fetch to start
+	<-fetchStarted
+
+	// Start second request with short timeout
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	_, err = cache.GetOrFetch(ctx, key, fetcher)
+	assert.Error(t, err)
+	assert.Equal(t, context.DeadlineExceeded, err)
+
+	wg.Wait()
+}
+
+// TestSingleflightCache_ErrorPropagation tests that errors are properly propagated
+func TestSingleflightCache_ErrorPropagation(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	key := "error-prop-key"
+	expectedErr := errors.New("intentional error")
+
+	var fetchCount atomic.Int32
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		fetchCount.Add(1)
+		time.Sleep(50 * time.Millisecond)
+		return nil, 0, expectedErr
+	}
+
+	// Launch multiple concurrent requests
+	concurrency := 5
+	var wg sync.WaitGroup
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			_, errs[idx] = cache.GetOrFetch(ctx, key, fetcher)
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify all requests got the same error
+	for i := 0; i < concurrency; i++ {
+		assert.Error(t, errs[i])
+		assert.Equal(t, expectedErr, errs[i])
+	}
+
+	// Verify fetcher was only called once
+	assert.Equal(t, int32(1), fetchCount.Load())
+}
+
+// TestSingleflightCache_PassthroughMethods tests that passthrough methods work
+func TestSingleflightCache_PassthroughMethods(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	t.Run("Set", func(t *testing.T) {
+		err := cache.Set(ctx, "set-key", []byte("set-value"), time.Minute)
+		require.NoError(t, err)
+
+		val, _, exists, err := cache.Get(ctx, "set-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("set-value"), val)
+	})
+
+	t.Run("Get", func(t *testing.T) {
+		err := cache.Set(ctx, "get-key", []byte("get-value"), time.Minute)
+		require.NoError(t, err)
+
+		val, ttl, exists, err := cache.Get(ctx, "get-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("get-value"), val)
+		assert.Greater(t, ttl, time.Duration(0))
+	})
+
+	t.Run("Delete", func(t *testing.T) {
+		err := cache.Set(ctx, "delete-key", []byte("delete-value"), time.Minute)
+		require.NoError(t, err)
+
+		deleted, err := cache.Delete(ctx, "delete-key")
+		require.NoError(t, err)
+		assert.True(t, deleted)
+
+		exists, err := cache.Exists(ctx, "delete-key")
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+
+	t.Run("Exists", func(t *testing.T) {
+		exists, err := cache.Exists(ctx, "nonexistent")
+		require.NoError(t, err)
+		assert.False(t, exists)
+
+		err = cache.Set(ctx, "exists-key", []byte("value"), time.Minute)
+		require.NoError(t, err)
+
+		exists, err = cache.Exists(ctx, "exists-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+	})
+
+	t.Run("Clear", func(t *testing.T) {
+		err := cache.Set(ctx, "clear-key", []byte("value"), time.Minute)
+		require.NoError(t, err)
+
+		err = cache.Clear(ctx)
+		require.NoError(t, err)
+
+		exists, err := cache.Exists(ctx, "clear-key")
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+
+	t.Run("Ping", func(t *testing.T) {
+		err := cache.Ping(ctx)
+		require.NoError(t, err)
+	})
+}
+
+// TestSingleflightCache_Stats tests statistics tracking
+func TestSingleflightCache_Stats(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	// Make some calls
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(50 * time.Millisecond)
+		return []byte("value"), time.Minute, nil
+	}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 5; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = cache.GetOrFetch(ctx, "stats-key", fetcher)
+		}()
+	}
+	wg.Wait()
+
+	stats := cache.GetStats()
+
+	// Check singleflight stats exist
+	assert.Contains(t, stats, "singleflight_total_calls")
+	assert.Contains(t, stats, "singleflight_deduplicated")
+	assert.Contains(t, stats, "singleflight_dedup_rate")
+	assert.Contains(t, stats, "singleflight_inflight")
+
+	// Verify values
+	assert.Equal(t, int64(5), stats["singleflight_total_calls"])
+	assert.Equal(t, int64(4), stats["singleflight_deduplicated"])
+
+	// Also check underlying backend stats are included
+	assert.Contains(t, stats, "hits")
+	assert.Contains(t, stats, "misses")
+}
+
+// TestSingleflightCache_ResetStats tests stats reset
+func TestSingleflightCache_ResetStats(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		return []byte("value"), time.Minute, nil
+	}
+
+	// Make some calls
+	_, _ = cache.GetOrFetch(ctx, "key1", fetcher)
+	_, _ = cache.GetOrFetch(ctx, "key2", fetcher)
+
+	stats := cache.GetStats()
+	assert.Greater(t, stats["singleflight_total_calls"].(int64), int64(0))
+
+	// Reset stats
+	cache.ResetStats()
+
+	stats = cache.GetStats()
+	assert.Equal(t, int64(0), stats["singleflight_total_calls"])
+	assert.Equal(t, int64(0), stats["singleflight_deduplicated"])
+}
+
+// TestSingleflightCache_GetBackend tests GetBackend method
+func TestSingleflightCache_GetBackend(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	assert.Equal(t, backend, cache.GetBackend())
+}
+
+// BenchmarkSingleflightCache_Sequential benchmarks sequential access
+func BenchmarkSingleflightCache_Sequential(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		key := fmt.Sprintf("key-%d", i%100)
+		_, _ = cache.GetOrFetch(ctx, key, fetcher)
+	}
+}
+
+// BenchmarkSingleflightCache_Concurrent benchmarks concurrent access
+func BenchmarkSingleflightCache_Concurrent(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(time.Millisecond) // Simulate slow fetch
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			key := fmt.Sprintf("key-%d", i%10) // Only 10 unique keys to force deduplication
+			_, _ = cache.GetOrFetch(ctx, key, fetcher)
+			i++
+		}
+	})
+}
+
+// BenchmarkSingleflightCache_HighContention benchmarks high contention scenario
+func BenchmarkSingleflightCache_HighContention(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(10 * time.Millisecond) // Slow fetch to force queuing
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			// All goroutines hit the same key
+			_, _ = cache.GetOrFetch(ctx, "hot-key", fetcher)
+		}
+	})
+}

internal/cache/cache.go

@@ -33,21 +33,19 @@ type Logger interface {
 
 // Config provides configuration for the cache
 type Config struct {
+	Logger            Logger
+	JWKConfig         *JWKConfig
+	MetadataConfig    *MetadataConfig
+	TokenConfig       *TokenConfig
 	Type              Type
-	MaxSize           int
-	MaxMemoryBytes    int64
 	DefaultTTL        time.Duration
 	CleanupInterval   time.Duration
-	EnableCompression bool
+	MaxMemoryBytes    int64
+	MaxSize           int
 	EnableMetrics     bool
 	EnableAutoCleanup bool
 	EnableMemoryLimit bool
-	Logger            Logger
-
-	// Type-specific configurations
-	TokenConfig    *TokenConfig
-	MetadataConfig *MetadataConfig
-	JWKConfig      *JWKConfig
+	EnableCompression bool
 }
 
 // TokenConfig provides token-specific cache configuration
@@ -59,11 +57,11 @@ type TokenConfig struct {
 
 // MetadataConfig provides metadata-specific cache configuration
 type MetadataConfig struct {
+	SecurityCriticalFields         []string
 	GracePeriod                    time.Duration
 	ExtendedGracePeriod            time.Duration
 	MaxGracePeriod                 time.Duration
 	SecurityCriticalMaxGracePeriod time.Duration
-	SecurityCriticalFields         []string
 }
 
 // JWKConfig provides JWK-specific cache configuration
@@ -75,45 +73,35 @@ type JWKConfig struct {
 
 // Item represents a single cache entry
 type Item struct {
-	Key          string
-	Value        interface{}
-	Size         int64
 	ExpiresAt    time.Time
 	LastAccessed time.Time
-	AccessCount  int64
+	Value        interface{}
+	Metadata     map[string]interface{}
+	element      *list.Element
+	Key          string
 	CacheType    Type
-
-	// Type-specific metadata
-	Metadata map[string]interface{}
-
-	// LRU list element reference
-	element *list.Element
+	Size         int64
+	AccessCount  int64
 }
 
 // Cache provides a single, unified cache implementation
 type Cache struct {
-	mu      sync.RWMutex
-	items   map[string]*Item
-	lruList *list.List
-	config  Config
-	logger  Logger
-
-	// Memory management
+	config        Config
+	ctx           context.Context
+	logger        Logger
+	cancel        context.CancelFunc
+	lruList       *list.List
+	items         map[string]*Item
+	stopCleanup   chan bool
+	wg            sync.WaitGroup
 	currentSize   int64
 	currentMemory int64
-
-	// Metrics
-	hits      int64
-	misses    int64
-	evictions int64
-	sets      int64
-
-	// Lifecycle management
-	ctx         context.Context
-	cancel      context.CancelFunc
-	wg          sync.WaitGroup
-	stopCleanup chan bool
-	closed      int32
+	hits          int64
+	misses        int64
+	evictions     int64
+	sets          int64
+	mu            sync.RWMutex
+	closed        int32
 }
 
 // DefaultConfig returns a default cache configuration

internal/cache/cache_test.go

@@ -1750,19 +1750,19 @@ func TestAdvancedEdgeCases(t *testing.T) {
 
 	// Test with various data types
 	testCases := []struct {
-		key   string
 		value interface{}
+		key   string
 	}{
-		{"string", "test string"},
-		{"int", 42},
-		{"float", 3.14159},
-		{"bool", true},
-		{"slice", []string{"a", "b", "c"}},
-		{"map", map[string]int{"one": 1, "two": 2}},
-		{"nil", nil},
-		{"empty-string", ""},
-		{"empty-slice", []string{}},
-		{"empty-map", map[string]interface{}{}},
+		{key: "string", value: "test string"},
+		{key: "int", value: 42},
+		{key: "float", value: 3.14159},
+		{key: "bool", value: true},
+		{key: "slice", value: []string{"a", "b", "c"}},
+		{key: "map", value: map[string]int{"one": 1, "two": 2}},
+		{key: "nil", value: nil},
+		{key: "empty-string", value: ""},
+		{key: "empty-slice", value: []string{}},
+		{key: "empty-map", value: map[string]interface{}{}},
 	}
 
 	for _, tc := range testCases {

internal/cache/manager.go

@@ -7,22 +7,17 @@ import (
 
 // Manager manages multiple cache instances with singleton pattern
 type Manager struct {
-	mu sync.RWMutex
-
-	// Core caches
+	logger        Logger
 	tokenCache    *Cache
 	metadataCache *Cache
 	jwkCache      *Cache
 	sessionCache  *Cache
 	generalCache  *Cache
-
-	// Typed wrappers
 	typedToken    *TokenCache
 	typedMetadata *MetadataCache
 	typedJWK      *JWKCache
 	typedSession  *SessionCache
-
-	logger Logger
+	mu            sync.RWMutex
 }
 
 var (

internal/cache/resilience/circuit_breaker.go

@@ -48,23 +48,12 @@ func (s State) String() string {
 
 // CircuitBreakerConfig holds configuration for the circuit breaker
 type CircuitBreakerConfig struct {
-	// MaxFailures is the number of consecutive failures before opening the circuit
-	MaxFailures int
-
-	// FailureThreshold is the failure rate threshold (0.0 to 1.0)
-	FailureThreshold float64
-
-	// Timeout is how long the circuit stays open before trying half-open
-	Timeout time.Duration
-
-	// HalfOpenMaxRequests is the number of requests allowed in half-open state
+	OnStateChange       func(from, to State)
+	MaxFailures         int
+	FailureThreshold    float64
+	Timeout             time.Duration
 	HalfOpenMaxRequests int
-
-	// ResetTimeout is how long to wait before resetting counters in closed state
-	ResetTimeout time.Duration
-
-	// OnStateChange is called when the circuit breaker changes state
-	OnStateChange func(from, to State)
+	ResetTimeout        time.Duration
 }
 
 // DefaultCircuitBreakerConfig returns default configuration
@@ -80,28 +69,20 @@ func DefaultCircuitBreakerConfig() *CircuitBreakerConfig {
 
 // CircuitBreaker implements the circuit breaker pattern
 type CircuitBreaker struct {
-	config *CircuitBreakerConfig
-
-	// State management
-	state           atomic.Int32
-	lastStateChange time.Time
-	stateMu         sync.RWMutex
-
-	// Failure tracking
-	consecutiveFailures atomic.Int32
-	totalRequests       atomic.Int64
+	nextRetryTime       time.Time
+	lastStateChange     time.Time
+	lastSuccessTime     time.Time
+	lastFailureTime     time.Time
+	config              *CircuitBreakerConfig
 	totalFailures       atomic.Int64
+	totalRequests       atomic.Int64
+	stateTransitions    atomic.Int64
+	rejectedRequests    atomic.Int64
+	stateMu             sync.RWMutex
+	timeMu              sync.RWMutex
 	halfOpenRequests    atomic.Int32
-
-	// Timing
-	lastFailureTime time.Time
-	lastSuccessTime time.Time
-	nextRetryTime   time.Time
-	timeMu          sync.RWMutex
-
-	// Metrics
-	stateTransitions atomic.Int64
-	rejectedRequests atomic.Int64
+	consecutiveFailures atomic.Int32
+	state               atomic.Int32
 }
 
 // NewCircuitBreaker creates a new circuit breaker
@@ -313,17 +294,17 @@ func (cb *CircuitBreaker) Stats() CircuitBreakerStats {
 
 // CircuitBreakerStats holds statistics for the circuit breaker
 type CircuitBreakerStats struct {
-	State               State
-	ConsecutiveFailures int32
+	LastFailureTime     time.Time
+	LastSuccessTime     time.Time
+	LastStateChange     time.Time
+	NextRetryTime       time.Time
 	TotalRequests       int64
 	TotalFailures       int64
 	SuccessRate         float64
 	RejectedRequests    int64
 	StateTransitions    int64
-	LastFailureTime     time.Time
-	LastSuccessTime     time.Time
-	LastStateChange     time.Time
-	NextRetryTime       time.Time
+	State               State
+	ConsecutiveFailures int32
 }
 
 // IsHealthy returns true if the circuit breaker is in a healthy state

internal/cache/resilience/circuit_breaker_backend_test.go

@@ -28,8 +28,8 @@ type mockBackend struct {
 }
 
 type mockEntry struct {
-	value     []byte
 	expiresAt time.Time
+	value     []byte
 }
 
 func newMockBackend() *mockBackend {

internal/cache/resilience/health_check.go

@@ -41,26 +41,13 @@ func (h HealthStatus) String() string {
 
 // HealthCheckConfig holds configuration for the health checker
 type HealthCheckConfig struct {
-	// CheckInterval is how often to check health
-	CheckInterval time.Duration
-
-	// Timeout is the timeout for each health check
-	Timeout time.Duration
-
-	// HealthyThreshold is the number of consecutive successes to become healthy
-	HealthyThreshold int
-
-	// UnhealthyThreshold is the number of consecutive failures to become unhealthy
+	OnStatusChange     func(from, to HealthStatus)
+	CheckFunc          func(ctx context.Context) error
+	CheckInterval      time.Duration
+	Timeout            time.Duration
+	HealthyThreshold   int
 	UnhealthyThreshold int
-
-	// DegradedThreshold is the latency threshold in ms to mark as degraded
-	DegradedThreshold time.Duration
-
-	// OnStatusChange is called when health status changes
-	OnStatusChange func(from, to HealthStatus)
-
-	// CheckFunc is the function to check health
-	CheckFunc func(ctx context.Context) error
+	DegradedThreshold  time.Duration
 }
 
 // DefaultHealthCheckConfig returns default configuration
@@ -76,31 +63,23 @@ func DefaultHealthCheckConfig() *HealthCheckConfig {
 
 // HealthChecker monitors the health of a backend
 type HealthChecker struct {
-	config *HealthCheckConfig
-
-	// Status tracking
-	status               atomic.Int32
-	consecutiveSuccesses atomic.Int32
+	lastCheckTime        time.Time
+	lastSuccessTime      time.Time
+	lastFailureTime      time.Time
+	config               *HealthCheckConfig
+	stopChan             chan struct{}
+	ticker               *time.Ticker
+	wg                   sync.WaitGroup
+	statusChanges        atomic.Int64
+	totalChecks          atomic.Int64
+	totalSuccesses       atomic.Int64
+	totalFailures        atomic.Int64
+	averageLatency       atomic.Int64
+	timeMu               sync.RWMutex
 	consecutiveFailures  atomic.Int32
-
-	// Timing
-	lastCheckTime   time.Time
-	lastSuccessTime time.Time
-	lastFailureTime time.Time
-	averageLatency  atomic.Int64
-	timeMu          sync.RWMutex
-
-	// Metrics
-	totalChecks    atomic.Int64
-	totalSuccesses atomic.Int64
-	totalFailures  atomic.Int64
-	statusChanges  atomic.Int64
-
-	// Lifecycle
-	ticker   *time.Ticker
-	stopChan chan struct{}
-	stopped  atomic.Bool
-	wg       sync.WaitGroup
+	consecutiveSuccesses atomic.Int32
+	stopped              atomic.Bool
+	status               atomic.Int32
 }
 
 // NewHealthChecker creates a new health checker
@@ -342,19 +321,19 @@ func (hc *HealthChecker) Stats() HealthCheckerStats {
 
 // HealthCheckerStats holds statistics for the health checker
 type HealthCheckerStats struct {
-	Status               HealthStatus
-	ConsecutiveSuccesses int32
-	ConsecutiveFailures  int32
+	LastCheckTime        time.Time
+	LastFailureTime      time.Time
+	LastSuccessTime      time.Time
 	TotalChecks          int64
 	TotalSuccesses       int64
 	TotalFailures        int64
 	SuccessRate          float64
 	AverageLatency       time.Duration
 	StatusChanges        int64
-	LastCheckTime        time.Time
-	LastSuccessTime      time.Time
-	LastFailureTime      time.Time
 	HealthScore          float64
+	Status               HealthStatus
+	ConsecutiveFailures  int32
+	ConsecutiveSuccesses int32
 }
 
 // Reset resets the health checker statistics

internal/cache/resilience/health_check_backend.go

@@ -12,20 +12,16 @@ import (
 
 // HealthCheckBackend wraps a cache backend with health checking
 type HealthCheckBackend struct {
-	backend backends.CacheBackend
-	config  *HealthCheckConfig
-
-	// Health tracking
+	lastCheck        time.Time
+	backend          backends.CacheBackend
+	ctx              context.Context
+	config           *HealthCheckConfig
+	cancel           context.CancelFunc
+	wg               sync.WaitGroup
+	checkMutex       sync.RWMutex
 	status           atomic.Int32
 	consecutiveFails atomic.Int32
 	consecutiveOK    atomic.Int32
-	lastCheck        time.Time
-	checkMutex       sync.RWMutex
-
-	// Lifecycle
-	ctx    context.Context
-	cancel context.CancelFunc
-	wg     sync.WaitGroup
 }
 
 // NewHealthCheckBackend creates a new health check wrapped backend

internal/cache/typed_cache.go

@@ -292,12 +292,12 @@ type SessionCache struct {
 
 // SessionData represents session information
 type SessionData struct {
+	ExpiresAt    time.Time              `json:"expires_at"`
+	Claims       map[string]interface{} `json:"claims"`
 	ID           string                 `json:"id"`
 	UserID       string                 `json:"user_id"`
 	AccessToken  string                 `json:"access_token"`
 	RefreshToken string                 `json:"refresh_token"`
-	ExpiresAt    time.Time              `json:"expires_at"`
-	Claims       map[string]interface{} `json:"claims"`
 }
 
 // NewSessionCache creates a new session cache

internal/cleanup/cleanup_test.go

@@ -11,10 +11,10 @@ import (
 
 // Mock logger for testing
 type mockLogger struct {
-	mu       sync.Mutex
 	logs     []string
 	errLogs  []string
 	debugLog []string
+	mu       sync.Mutex
 }
 
 func (m *mockLogger) Logf(format string, args ...interface{}) {

internal/cleanup/manager.go

@@ -19,20 +19,20 @@ type Logger interface {
 
 // BackgroundTask represents a recurring background task
 type BackgroundTask struct {
-	name       string
-	interval   time.Duration
-	taskFunc   func()
+	lastRun    time.Time
+	logger     Logger
+	ctx        context.Context
 	ticker     *time.Ticker
 	stopChan   chan bool
-	isRunning  int32
-	logger     Logger
 	waitGroup  *sync.WaitGroup
-	lastRun    time.Time
+	taskFunc   func()
+	cancelFunc context.CancelFunc
+	name       string
 	runCount   int64
 	errorCount int64
+	interval   time.Duration
 	mu         sync.RWMutex
-	ctx        context.Context
-	cancelFunc context.CancelFunc
+	isRunning  int32
 }
 
 // NewBackgroundTask creates a new background task
@@ -183,11 +183,11 @@ func (bt *BackgroundTask) IsRunning() bool {
 
 // TaskRegistry manages all background tasks
 type TaskRegistry struct {
-	tasks          map[string]*BackgroundTask
-	mu             sync.RWMutex
 	logger         Logger
-	maxTasks       int
+	tasks          map[string]*BackgroundTask
 	circuitBreaker *TaskCircuitBreaker
+	maxTasks       int
+	mu             sync.RWMutex
 }
 
 // globalTaskRegistry is the singleton task registry

internal/cleanup/workers.go

@@ -11,14 +11,14 @@ import (
 
 // TaskCircuitBreaker prevents task creation failures from cascading
 type TaskCircuitBreaker struct {
+	lastFailureTime  time.Time
+	logger           Logger
+	taskFailures     map[string]int32
+	timeout          time.Duration
+	mu               sync.RWMutex
 	failureThreshold int32
 	failureCount     int32
-	lastFailureTime  time.Time
-	timeout          time.Duration
-	state            int32 // 0: closed, 1: open
-	logger           Logger
-	mu               sync.RWMutex
-	taskFailures     map[string]int32
+	state            int32
 }
 
 // CircuitBreakerState represents the state of the circuit breaker
@@ -140,14 +140,14 @@ func (cb *TaskCircuitBreaker) GetState() CircuitBreakerState {
 
 // TaskMemoryMonitor monitors memory usage and can trigger cleanup
 type TaskMemoryMonitor struct {
+	lastCheck       time.Time
 	logger          Logger
 	registry        *TaskRegistry
+	stopChan        chan bool
 	memoryThreshold uint64
 	checkInterval   time.Duration
-	isMonitoring    int32
-	stopChan        chan bool
-	lastCheck       time.Time
 	mu              sync.RWMutex
+	isMonitoring    int32
 }
 
 var (
@@ -310,13 +310,13 @@ func (tmm *TaskMemoryMonitor) GetStats() map[string]interface{} {
 
 // WorkerPool manages a pool of worker goroutines for task execution
 type WorkerPool struct {
-	workers   int
-	taskQueue chan func()
-	workerWg  sync.WaitGroup
-	isRunning int32
 	logger    Logger
+	taskQueue chan func()
 	stopChan  chan bool
 	metrics   WorkerPoolMetrics
+	workerWg  sync.WaitGroup
+	workers   int
+	isRunning int32
 }
 
 // WorkerPoolMetrics tracks worker pool performance

internal/dcrstorage/file.go

@@ -0,0 +1,155 @@
+package dcrstorage
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+)
+
+// FileStore implements Store using file-based storage.
+// This is the default storage backend for backward compatibility with existing deployments.
+// For distributed environments, consider using RedisStore instead.
+type FileStore struct {
+	basePath string
+	logger   Logger
+	mu       sync.RWMutex
+}
+
+// NewFileStore creates a new file-based credentials store.
+// If basePath is empty, defaults to /tmp/oidc-client-credentials.json
+func NewFileStore(basePath string, logger Logger) *FileStore {
+	if basePath == "" {
+		basePath = "/tmp/oidc-client-credentials.json"
+	}
+	if logger == nil {
+		logger = NoOpLogger()
+	}
+	return &FileStore{
+		basePath: basePath,
+		logger:   logger,
+	}
+}
+
+// BasePath returns the base path used for storing credentials
+func (s *FileStore) BasePath() string {
+	return s.basePath
+}
+
+// GetFilePath returns the file path for storing credentials for a specific provider.
+// For multi-tenant scenarios, each provider gets a separate file based on URL hash.
+func (s *FileStore) GetFilePath(providerURL string) string {
+	if providerURL == "" {
+		return s.basePath
+	}
+
+	// Hash provider URL for filename safety and uniqueness
+	hash := sha256.Sum256([]byte(providerURL))
+	hashStr := hex.EncodeToString(hash[:8]) // Use first 8 bytes for shorter filename
+
+	ext := filepath.Ext(s.basePath)
+	base := strings.TrimSuffix(s.basePath, ext)
+	if ext == "" {
+		ext = ".json"
+	}
+
+	return fmt.Sprintf("%s-%s%s", base, hashStr, ext)
+}
+
+// Save stores the client registration response to a file
+func (s *FileStore) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	if creds == nil {
+		return fmt.Errorf("credentials cannot be nil")
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	// Ensure parent directory exists
+	dir := filepath.Dir(filePath)
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return fmt.Errorf("failed to create credentials directory: %w", err)
+	}
+
+	data, err := json.MarshalIndent(creds, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal credentials: %w", err)
+	}
+
+	// Write with restrictive permissions (owner read/write only)
+	if err := os.WriteFile(filePath, data, 0600); err != nil {
+		return fmt.Errorf("failed to write credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Saved client credentials to %s", filePath)
+	return nil
+}
+
+// Load retrieves stored credentials from a file.
+// Returns nil, nil if no credentials file exists (not an error).
+func (s *FileStore) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	// #nosec G304 -- path is constructed from trusted config values via GetFilePath()
+	data, err := os.ReadFile(filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil // No credentials file exists - not an error
+		}
+		return nil, fmt.Errorf("failed to read credentials file: %w", err)
+	}
+
+	var creds ClientRegistrationResponse
+	if err := json.Unmarshal(data, &creds); err != nil {
+		return nil, fmt.Errorf("failed to parse credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Loaded client credentials from %s", filePath)
+	return &creds, nil
+}
+
+// Delete removes the credentials file for a provider
+func (s *FileStore) Delete(ctx context.Context, providerURL string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	if err := os.Remove(filePath); err != nil {
+		if os.IsNotExist(err) {
+			return nil // File doesn't exist, nothing to delete
+		}
+		return fmt.Errorf("failed to remove credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Deleted client credentials from %s", filePath)
+	return nil
+}
+
+// Exists checks if credentials exist for a provider
+func (s *FileStore) Exists(ctx context.Context, providerURL string) (bool, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	_, err := os.Stat(filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, fmt.Errorf("failed to check credentials file: %w", err)
+	}
+
+	return true, nil
+}

internal/dcrstorage/redis.go

@@ -0,0 +1,161 @@
+package dcrstorage
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+)
+
+// Cache defines the interface for cache operations needed by RedisStore.
+// This allows the main package to provide a cache implementation without
+// creating circular dependencies.
+type Cache interface {
+	// Get retrieves a value from the cache
+	Get(key string) (any, bool)
+	// Set stores a value in the cache with a TTL
+	Set(key string, value any, ttl time.Duration) error
+	// Delete removes a value from the cache
+	Delete(key string)
+}
+
+// RedisStore implements Store using a Cache-backed storage.
+// This storage backend enables sharing DCR credentials across multiple Traefik instances
+// in distributed environments (e.g., Kubernetes with multiple ingress pods).
+type RedisStore struct {
+	cache     Cache
+	keyPrefix string
+	logger    Logger
+	mu        sync.RWMutex
+}
+
+// NewRedisStore creates a new cache-backed credentials store.
+// The cache should be configured with a Redis backend for distributed storage.
+// If keyPrefix is empty, defaults to "dcr:creds:"
+func NewRedisStore(cache Cache, keyPrefix string, logger Logger) *RedisStore {
+	if keyPrefix == "" {
+		keyPrefix = "dcr:creds:"
+	}
+	if logger == nil {
+		logger = NoOpLogger()
+	}
+	return &RedisStore{
+		cache:     cache,
+		keyPrefix: keyPrefix,
+		logger:    logger,
+	}
+}
+
+// makeKey creates a unique cache key for a provider URL.
+// Uses SHA256 hash of the provider URL for consistent key generation across nodes.
+func (s *RedisStore) makeKey(providerURL string) string {
+	if providerURL == "" {
+		return s.keyPrefix + "default"
+	}
+	hash := sha256.Sum256([]byte(providerURL))
+	return s.keyPrefix + hex.EncodeToString(hash[:])
+}
+
+// Save stores the client registration response in the cache.
+// TTL is calculated based on client_secret_expires_at if available.
+func (s *RedisStore) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	if creds == nil {
+		return fmt.Errorf("credentials cannot be nil")
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	key := s.makeKey(providerURL)
+
+	// Calculate TTL based on client_secret_expires_at if available
+	ttl := 30 * 24 * time.Hour // Default: 30 days
+	if creds.ClientSecretExpiresAt > 0 {
+		expiresAt := time.Unix(creds.ClientSecretExpiresAt, 0)
+		ttl = time.Until(expiresAt)
+		if ttl < 0 {
+			return fmt.Errorf("credentials already expired")
+		}
+		// Add a small buffer to ensure we don't serve expired credentials
+		if ttl > time.Minute {
+			ttl -= time.Minute
+		}
+	}
+
+	// Serialize credentials to JSON for storage
+	data, err := json.Marshal(creds)
+	if err != nil {
+		return fmt.Errorf("failed to marshal credentials: %w", err)
+	}
+
+	// Store as string in cache (will be serialized by the cache backend)
+	if err := s.cache.Set(key, string(data), ttl); err != nil {
+		return fmt.Errorf("failed to store credentials in cache: %w", err)
+	}
+
+	s.logger.Debugf("Saved client credentials to cache with key %s (TTL: %v)", key, ttl)
+	return nil
+}
+
+// Load retrieves stored credentials from the cache.
+// Returns nil, nil if no credentials exist (not an error).
+func (s *RedisStore) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	key := s.makeKey(providerURL)
+
+	value, exists := s.cache.Get(key)
+	if !exists {
+		return nil, nil // No credentials stored - not an error
+	}
+
+	// Handle different value types from cache
+	var jsonData string
+	switch v := value.(type) {
+	case string:
+		jsonData = v
+	case []byte:
+		jsonData = string(v)
+	default:
+		// Try to see if it's already the struct (from local cache)
+		if creds, ok := value.(*ClientRegistrationResponse); ok {
+			return creds, nil
+		}
+		return nil, fmt.Errorf("unexpected credentials type in cache: %T", value)
+	}
+
+	var creds ClientRegistrationResponse
+	if err := json.Unmarshal([]byte(jsonData), &creds); err != nil {
+		return nil, fmt.Errorf("failed to parse credentials from cache: %w", err)
+	}
+
+	s.logger.Debugf("Loaded client credentials from cache with key %s", key)
+	return &creds, nil
+}
+
+// Delete removes stored credentials from the cache
+func (s *RedisStore) Delete(ctx context.Context, providerURL string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	key := s.makeKey(providerURL)
+	s.cache.Delete(key)
+
+	s.logger.Debugf("Deleted client credentials from cache with key %s", key)
+	return nil
+}
+
+// Exists checks if credentials exist in the cache for a provider
+func (s *RedisStore) Exists(ctx context.Context, providerURL string) (bool, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	key := s.makeKey(providerURL)
+	_, exists := s.cache.Get(key)
+
+	return exists, nil
+}

internal/dcrstorage/storage.go

@@ -0,0 +1,90 @@
+// Package dcrstorage provides storage backends for OIDC Dynamic Client Registration credentials.
+// It supports both file-based and Redis-based storage for persisting client credentials
+// across application restarts and distributed deployments.
+package dcrstorage
+
+import (
+	"context"
+)
+
+// StorageBackend represents the type of storage backend for DCR credentials
+type StorageBackend string
+
+const (
+	// StorageBackendFile uses file-based storage (default for backward compatibility)
+	StorageBackendFile StorageBackend = "file"
+
+	// StorageBackendRedis uses Redis for distributed storage
+	StorageBackendRedis StorageBackend = "redis"
+
+	// StorageBackendAuto automatically selects Redis if available, otherwise file
+	StorageBackendAuto StorageBackend = "auto"
+)
+
+// Logger interface for DCR storage operations
+type Logger interface {
+	Debug(msg string)
+	Debugf(format string, args ...any)
+	Info(msg string)
+	Infof(format string, args ...any)
+	Error(msg string)
+	Errorf(format string, args ...any)
+}
+
+// ClientRegistrationResponse represents the response from a successful client registration (RFC 7591)
+type ClientRegistrationResponse struct {
+	SubjectType             string   `json:"subject_type,omitempty"`
+	LogoURI                 string   `json:"logo_uri,omitempty"`
+	RegistrationAccessToken string   `json:"registration_access_token,omitempty"`
+	RegistrationClientURI   string   `json:"registration_client_uri,omitempty"`
+	Scope                   string   `json:"scope,omitempty"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	TOSURI                  string   `json:"tos_uri,omitempty"`
+	PolicyURI               string   `json:"policy_uri,omitempty"`
+	ClientSecret            string   `json:"client_secret,omitempty"`
+	ApplicationType         string   `json:"application_type,omitempty"`
+	ClientID                string   `json:"client_id"`
+	ClientName              string   `json:"client_name,omitempty"`
+	JWKSURI                 string   `json:"jwks_uri,omitempty"`
+	ClientURI               string   `json:"client_uri,omitempty"`
+	Contacts                []string `json:"contacts,omitempty"`
+	GrantTypes              []string `json:"grant_types,omitempty"`
+	ResponseTypes           []string `json:"response_types,omitempty"`
+	RedirectURIs            []string `json:"redirect_uris,omitempty"`
+	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
+	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
+}
+
+// Store defines the interface for storing DCR credentials.
+// This abstraction allows different storage backends (file, Redis) to be used
+// for persisting OIDC Dynamic Client Registration credentials across nodes.
+type Store interface {
+	// Save stores the client registration response for a provider
+	// The providerURL is used as a key to support multi-tenant scenarios
+	Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error
+
+	// Load retrieves stored credentials for a provider
+	// Returns nil, nil if no credentials exist (not an error)
+	Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error)
+
+	// Delete removes stored credentials for a provider
+	Delete(ctx context.Context, providerURL string) error
+
+	// Exists checks if credentials exist for a provider
+	Exists(ctx context.Context, providerURL string) (bool, error)
+}
+
+// noOpLogger is a no-op implementation of Logger for default use
+type noOpLogger struct{}
+
+func (n noOpLogger) Debug(msg string)                  {}
+func (n noOpLogger) Debugf(format string, args ...any) {}
+func (n noOpLogger) Info(msg string)                   {}
+func (n noOpLogger) Infof(format string, args ...any)  {}
+func (n noOpLogger) Error(msg string)                  {}
+func (n noOpLogger) Errorf(format string, args ...any) {}
+
+// NoOpLogger returns a no-op logger instance
+func NoOpLogger() Logger {
+	return noOpLogger{}
+}

internal/dcrstorage/storage_test.go

@@ -0,0 +1,464 @@
+package dcrstorage
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+// mockCache implements Cache for testing
+type mockCache struct {
+	data map[string]cacheEntry
+	mu   sync.RWMutex
+}
+
+type cacheEntry struct {
+	value     any
+	expiresAt time.Time
+}
+
+func newMockCache() *mockCache {
+	return &mockCache{data: make(map[string]cacheEntry)}
+}
+
+func (m *mockCache) Get(key string) (any, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	entry, ok := m.data[key]
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(entry.expiresAt) {
+		return nil, false
+	}
+	return entry.value, true
+}
+
+func (m *mockCache) Set(key string, value any, ttl time.Duration) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.data[key] = cacheEntry{
+		value:     value,
+		expiresAt: time.Now().Add(ttl),
+	}
+	return nil
+}
+
+func (m *mockCache) Delete(key string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.data, key)
+}
+
+func TestFileStore_SaveLoad(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+
+	store := NewFileStore(basePath, nil)
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "test-client-id",
+		ClientSecret:            "test-client-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "test-access-token",
+		RegistrationClientURI:   "https://example.com/register/test-client-id",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+		GrantTypes:              []string{"authorization_code", "refresh_token"},
+		ResponseTypes:           []string{"code"},
+		TokenEndpointAuthMethod: "client_secret_basic",
+	}
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+		if loaded.RegistrationAccessToken != testCreds.RegistrationAccessToken {
+			t.Errorf("RegistrationAccessToken mismatch: got %s, want %s", loaded.RegistrationAccessToken, testCreds.RegistrationAccessToken)
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		tempDir2 := t.TempDir()
+		store2 := NewFileStore(filepath.Join(tempDir2, "nonexistent.json"), nil)
+
+		loaded, err := store2.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent file: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+
+		exists, err = store.Exists(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if exists {
+			t.Error("Expected credentials to not exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("delete non-existent credentials", func(t *testing.T) {
+		err := store.Delete(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Delete should not error for non-existent: %v", err)
+		}
+	})
+}
+
+func TestFileStore_MultiProvider(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+
+	provider1 := "https://auth1.example.com"
+	provider2 := "https://auth2.example.com"
+
+	creds1 := &ClientRegistrationResponse{
+		ClientID:     "client-1",
+		ClientSecret: "secret-1",
+	}
+	creds2 := &ClientRegistrationResponse{
+		ClientID:     "client-2",
+		ClientSecret: "secret-2",
+	}
+
+	if err := store.Save(ctx, provider1, creds1); err != nil {
+		t.Fatalf("Failed to save creds1: %v", err)
+	}
+	if err := store.Save(ctx, provider2, creds2); err != nil {
+		t.Fatalf("Failed to save creds2: %v", err)
+	}
+
+	loaded1, err := store.Load(ctx, provider1)
+	if err != nil {
+		t.Fatalf("Failed to load creds1: %v", err)
+	}
+	if loaded1.ClientID != "client-1" {
+		t.Errorf("Provider 1 ClientID mismatch: got %s", loaded1.ClientID)
+	}
+
+	loaded2, err := store.Load(ctx, provider2)
+	if err != nil {
+		t.Fatalf("Failed to load creds2: %v", err)
+	}
+	if loaded2.ClientID != "client-2" {
+		t.Errorf("Provider 2 ClientID mismatch: got %s", loaded2.ClientID)
+	}
+
+	if err := store.Delete(ctx, provider1); err != nil {
+		t.Fatalf("Failed to delete creds1: %v", err)
+	}
+
+	exists, _ := store.Exists(ctx, provider2)
+	if !exists {
+		t.Error("Provider 2 credentials should still exist")
+	}
+}
+
+func TestFileStore_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	creds := &ClientRegistrationResponse{
+		ClientID:     "test-client",
+		ClientSecret: "test-secret",
+	}
+
+	var wg sync.WaitGroup
+	concurrency := 10
+
+	for range concurrency {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_ = store.Save(ctx, providerURL, creds)
+		}()
+	}
+	wg.Wait()
+
+	for range concurrency {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = store.Load(ctx, providerURL)
+		}()
+	}
+	wg.Wait()
+
+	loaded, err := store.Load(ctx, providerURL)
+	if err != nil {
+		t.Fatalf("Failed to load after concurrent access: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test-client" {
+		t.Error("Credentials corrupted after concurrent access")
+	}
+}
+
+func TestFileStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+
+	t.Run("empty provider URL uses default path", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{ClientID: "test"}
+		err := store.Save(ctx, "", creds)
+		if err != nil {
+			t.Fatalf("Save with empty provider URL failed: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, "")
+		if err != nil {
+			t.Fatalf("Load with empty provider URL failed: %v", err)
+		}
+		if loaded == nil || loaded.ClientID != "test" {
+			t.Error("Failed to load credentials with empty provider URL")
+		}
+	})
+}
+
+func TestFileStore_DefaultPath(t *testing.T) {
+	t.Parallel()
+
+	store := NewFileStore("", nil)
+
+	if store.BasePath() == "" {
+		t.Error("Expected default base path")
+	}
+}
+
+func TestRedisStore_WithMockCache(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "redis-test-client",
+		ClientSecret:            "redis-test-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "redis-test-token",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+	}
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		loaded, err := store.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+}
+
+func TestRedisStore_TTLFromExpiry(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+
+	t.Run("expired credentials should fail", func(t *testing.T) {
+		expiredCreds := &ClientRegistrationResponse{
+			ClientID:              "expired-client",
+			ClientSecret:          "expired-secret",
+			ClientSecretExpiresAt: time.Now().Add(-1 * time.Hour).Unix(),
+		}
+
+		err := store.Save(ctx, "https://expired.example.com", expiredCreds)
+		if err == nil {
+			t.Error("Expected error for expired credentials")
+		}
+	})
+
+	t.Run("credentials without expiry use default TTL", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{
+			ClientID:              "no-expiry-client",
+			ClientSecret:          "no-expiry-secret",
+			ClientSecretExpiresAt: 0,
+		}
+
+		err := store.Save(ctx, "https://noexpiry.example.com", creds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials without expiry: %v", err)
+		}
+	})
+}
+
+func TestRedisStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+}
+
+func TestFileStore_CorruptedFile(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	filePath := store.GetFilePath(providerURL)
+	if err := os.WriteFile(filePath, []byte("{corrupted json"), 0600); err != nil {
+		t.Fatalf("Failed to write corrupted file: %v", err)
+	}
+
+	_, err := store.Load(ctx, providerURL)
+	if err == nil {
+		t.Error("Expected error for corrupted JSON")
+	}
+}
+
+func TestFileStore_DirectoryCreation(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	deepPath := filepath.Join(tempDir, "deep", "nested", "path", "credentials.json")
+	store := NewFileStore(deepPath, nil)
+
+	ctx := context.Background()
+	creds := &ClientRegistrationResponse{ClientID: "test"}
+
+	err := store.Save(ctx, "https://example.com", creds)
+	if err != nil {
+		t.Fatalf("Failed to save with nested directory: %v", err)
+	}
+
+	loaded, err := store.Load(ctx, "https://example.com")
+	if err != nil {
+		t.Fatalf("Failed to load after nested directory creation: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test" {
+		t.Error("Failed to load credentials from nested directory")
+	}
+}

internal/features/flags.go

@@ -12,9 +12,9 @@ import (
 type FeatureFlag struct {
 	name        string
 	description string
-	enabled     atomic.Bool
-	mu          sync.RWMutex
 	callbacks   []func(bool)
+	mu          sync.RWMutex
+	enabled     atomic.Bool
 }
 
 // FeatureManager manages all feature flags in the application

internal/pool/transport.go

@@ -14,50 +14,41 @@ import (
 // and resource leaks. It provides centralized management of HTTP client transports with
 // proper lifecycle management and security controls.
 type TransportPool struct {
-	mu          sync.RWMutex
-	transports  map[string]*sharedTransport
-	maxConns    int
 	ctx         context.Context
+	transports  map[string]*sharedTransport
 	cancel      context.CancelFunc
-	clientCount int32 // Track total HTTP clients
-	maxClients  int32 // Limit total clients
+	maxConns    int
+	mu          sync.RWMutex
+	clientCount int32
+	maxClients  int32
 }
 
 // sharedTransport wraps an HTTP transport with reference counting
 type sharedTransport struct {
-	transport *http.Transport
-	refCount  int32
 	lastUsed  time.Time
+	transport *http.Transport
 	config    TransportConfig
+	refCount  int32
 }
 
 // TransportConfig defines configuration for HTTP transports
 type TransportConfig struct {
-	// Timeouts
-	DialTimeout           time.Duration
-	TLSHandshakeTimeout   time.Duration
+	MaxConnsPerHost       int
+	WriteBufferSize       int
 	ResponseHeaderTimeout time.Duration
 	ExpectContinueTimeout time.Duration
 	IdleConnTimeout       time.Duration
 	KeepAlive             time.Duration
-
-	// Connection limits
-	MaxIdleConns        int
-	MaxIdleConnsPerHost int
-	MaxConnsPerHost     int
-
-	// Features
-	ForceHTTP2         bool
-	DisableKeepAlives  bool
-	DisableCompression bool
-
-	// Buffer sizes
-	WriteBufferSize int
-	ReadBufferSize  int
-
-	// TLS
-	InsecureSkipVerify bool
-	MinTLSVersion      uint16
+	TLSHandshakeTimeout   time.Duration
+	MaxIdleConns          int
+	DialTimeout           time.Duration
+	MaxIdleConnsPerHost   int
+	ReadBufferSize        int
+	MinTLSVersion         uint16
+	ForceHTTP2            bool
+	DisableCompression    bool
+	InsecureSkipVerify    bool
+	DisableKeepAlives     bool
 }
 
 var (

internal/providers/azure_test.go

@@ -154,10 +154,10 @@ func TestAzureProvider_ValidateTokens(t *testing.T) {
 	provider := NewAzureProvider()
 
 	tests := []struct {
-		name           string
-		session        *mockSession
 		verifierError  error
+		session        *mockSession
 		cacheData      map[string]interface{}
+		name           string
 		expectedResult ValidationResult
 	}{
 		{
@@ -369,9 +369,9 @@ func TestAzureProvider_OfflineAccessHandling(t *testing.T) {
 
 	tests := []struct {
 		name          string
-		inputScopes   []string
-		expectedCount int // Expected number of offline_access scopes (should be 1)
 		description   string
+		inputScopes   []string
+		expectedCount int
 	}{
 		{
 			name:          "No offline_access - should add one",

internal/providers/base_test.go

@@ -8,10 +8,10 @@ import (
 
 // Mock implementations for testing
 type mockSession struct {
-	authenticated bool
 	idToken       string
 	accessToken   string
 	refreshToken  string
+	authenticated bool
 }
 
 func (s *mockSession) GetIDToken() string      { return s.idToken }
@@ -338,10 +338,10 @@ func TestBaseProvider_ValidateTokenExpiry(t *testing.T) {
 	gracePeriod := 5 * time.Minute
 
 	tests := []struct {
-		name           string
 		claims         map[string]interface{}
-		cacheFound     bool
+		name           string
 		expectedResult ValidationResult
+		cacheFound     bool
 	}{
 		{
 			name:       "Token not found in cache, has refresh token",
@@ -438,10 +438,10 @@ func TestBaseProvider_ValidateTokenExpiry_NoRefreshToken(t *testing.T) {
 	gracePeriod := 5 * time.Minute
 
 	tests := []struct {
-		name           string
 		claims         map[string]interface{}
-		cacheFound     bool
+		name           string
 		expectedResult ValidationResult
+		cacheFound     bool
 	}{
 		{
 			name:       "Token not found in cache, no refresh token",

internal/providers/factory_test.go

@@ -25,9 +25,9 @@ func TestProviderFactory_CreateProvider(t *testing.T) {
 	tests := []struct {
 		name         string
 		issuerURL    string
+		errMsg       string
 		expectedType ProviderType
 		wantErr      bool
-		errMsg       string
 	}{
 		{
 			name:         "Google provider",
@@ -158,10 +158,10 @@ func TestProviderFactory_CreateProviderByType(t *testing.T) {
 
 	tests := []struct {
 		name         string
+		errMsg       string
 		providerType ProviderType
 		expectedType ProviderType
 		wantErr      bool
-		errMsg       string
 	}{
 		{
 			name:         "Generic provider",

internal/providers/generic_test.go

@@ -136,9 +136,9 @@ func TestGenericProvider_ValidateTokens(t *testing.T) {
 	provider := NewGenericProvider()
 
 	tests := []struct {
-		name           string
-		session        *mockSession
 		verifierError  error
+		session        *mockSession
+		name           string
 		expectedResult ValidationResult
 	}{
 		{

internal/providers/google_test.go

@@ -172,8 +172,8 @@ func TestGoogleProvider_OfflineAccessFiltering(t *testing.T) {
 
 	tests := []struct {
 		name        string
-		inputScopes []string
 		description string
+		inputScopes []string
 	}{
 		{
 			name:        "Multiple offline_access occurrences",

internal/providers/registry_test.go

@@ -82,9 +82,9 @@ func TestProviderRegistry_GetProviderByType(t *testing.T) {
 	registry.RegisterProvider(googleProvider)
 
 	tests := []struct {
+		expected     OIDCProvider
 		name         string
 		providerType ProviderType
-		expected     OIDCProvider
 	}{
 		{
 			name:         "Get Generic provider",
@@ -180,9 +180,9 @@ func TestProviderRegistry_DetectProvider(t *testing.T) {
 	registry.RegisterProvider(gitlabProvider)
 
 	tests := []struct {
+		expected  OIDCProvider
 		name      string
 		issuerURL string
-		expected  OIDCProvider
 	}{
 		{
 			name:      "Google provider detection",
@@ -640,9 +640,9 @@ func TestProviderRegistry_GitLabDetection_RealWorldURLs(t *testing.T) {
 	registry.RegisterProvider(githubProvider)
 
 	realWorldTests := []struct {
+		expected  OIDCProvider
 		name      string
 		issuerURL string
-		expected  OIDCProvider
 	}{
 		// Actual self-hosted GitLab examples from issue #61
 		{

internal/providers/validation_test.go

@@ -20,8 +20,8 @@ func TestValidateIssuerURL(t *testing.T) {
 	tests := []struct {
 		name      string
 		issuerURL string
-		wantErr   bool
 		errMsg    string
+		wantErr   bool
 	}{
 		{
 			name:      "valid https URL",
@@ -106,8 +106,8 @@ func TestValidateClientID(t *testing.T) {
 	tests := []struct {
 		name     string
 		clientID string
-		wantErr  bool
 		errMsg   string
+		wantErr  bool
 	}{
 		{
 			name:     "valid client ID",
@@ -173,9 +173,9 @@ func TestValidateClientID(t *testing.T) {
 func TestValidateScopes(t *testing.T) {
 	tests := []struct {
 		name    string
+		errMsg  string
 		scopes  []string
 		wantErr bool
-		errMsg  string
 	}{
 		{
 			name:    "valid scopes with openid",
@@ -248,8 +248,8 @@ func TestValidateRedirectURL(t *testing.T) {
 	tests := []struct {
 		name        string
 		redirectURL string
-		wantErr     bool
 		errMsg      string
+		wantErr     bool
 	}{
 		{
 			name:        "valid https redirect URL",
@@ -315,11 +315,11 @@ func TestValidateRedirectURL(t *testing.T) {
 // TestValidateProviderSpecificConfig tests provider-specific configuration validation
 func TestValidateProviderSpecificConfig(t *testing.T) {
 	tests := []struct {
-		name     string
 		provider OIDCProvider
 		config   map[string]interface{}
-		wantErr  bool
+		name     string
 		errMsg   string
+		wantErr  bool
 	}{
 		{
 			name:     "valid Google config",
@@ -458,8 +458,8 @@ func TestValidateGoogleConfig_EdgeCases(t *testing.T) {
 	googleProvider := NewGoogleProvider()
 
 	tests := []struct {
-		name    string
 		config  map[string]interface{}
+		name    string
 		wantErr bool
 	}{
 		{
@@ -502,10 +502,10 @@ func TestValidateAzureConfig_EdgeCases(t *testing.T) {
 	azureProvider := NewAzureProvider()
 
 	tests := []struct {
-		name    string
 		config  map[string]interface{}
-		wantErr bool
+		name    string
 		errMsg  string
+		wantErr bool
 	}{
 		{
 			name: "valid tenant ID format",

internal/providers/warnings.go

@@ -7,9 +7,9 @@ import (
 
 // ProviderWarning represents a warning about provider limitations or requirements.
 type ProviderWarning struct {
-	ProviderType ProviderType
-	Level        string // "info", "warning", "error"
+	Level        string
 	Message      string
+	ProviderType ProviderType
 }
 
 // GetProviderWarnings returns warnings about provider-specific limitations.

internal/providers/warnings_test.go

@@ -9,9 +9,9 @@ import (
 func TestGetProviderWarnings(t *testing.T) {
 	tests := []struct {
 		name         string
+		checkContent string
 		providerType ProviderType
 		expectCount  int
-		checkContent string
 	}{
 		{
 			name:         "GitHub has OAuth 2.0 warning",

internal/recovery/base.go

@@ -34,21 +34,15 @@ type Logger interface {
 // for all recovery mechanism implementations. It handles request counting,
 // success/failure tracking, and timestamp management in a thread-safe manner.
 type BaseRecoveryMechanism struct {
-	// name identifies the recovery mechanism instance
-	name string
-	// logger provides structured logging capabilities
-	logger Logger
-
-	// Metrics tracked with atomic operations for thread safety
+	logger         Logger
+	name           string
+	lastSuccessStr string
+	lastFailureStr string
 	totalRequests  int64
 	successCount   int64
 	failureCount   int64
-	lastSuccessStr string
-	lastFailureStr string
-
-	// mutexes for thread-safe timestamp updates
-	successMutex sync.RWMutex
-	failureMutex sync.RWMutex
+	successMutex   sync.RWMutex
+	failureMutex   sync.RWMutex
 }
 
 // NewBaseRecoveryMechanism creates a new base recovery mechanism with the given name and logger.
@@ -182,10 +176,10 @@ const (
 
 // HTTPError represents an HTTP error with status code and message
 type HTTPError struct {
-	StatusCode int
+	Headers    map[string]string
 	Message    string
 	Body       []byte
-	Headers    map[string]string
+	StatusCode int
 }
 
 // Error implements the error interface

internal/recovery/circuit_breaker.go

@@ -60,20 +60,14 @@ func DefaultCircuitBreakerConfig() CircuitBreakerConfig {
 // CircuitBreaker implements the circuit breaker pattern for fault tolerance.
 // It prevents cascading failures by temporarily blocking requests to a failing service.
 type CircuitBreaker struct {
-	*BaseRecoveryMechanism
-	config CircuitBreakerConfig
-
-	// State management
-	state           int32 // atomic: CircuitBreakerState
 	lastStateChange time.Time
-	stateMutex      sync.RWMutex
-
-	// Failure tracking
-	consecutiveFailures  int32 // atomic
-	consecutiveSuccesses int32 // atomic
-
-	// Half-open state management
-	halfOpenRequests int32 // atomic
+	*BaseRecoveryMechanism
+	config               CircuitBreakerConfig
+	stateMutex           sync.RWMutex
+	state                int32
+	consecutiveFailures  int32
+	consecutiveSuccesses int32
+	halfOpenRequests     int32
 }
 
 // NewCircuitBreaker creates a new circuit breaker with the given configuration

internal/recovery/metrics.go

@@ -15,20 +15,13 @@ import (
 
 // RetryConfig defines configuration for the retry executor
 type RetryConfig struct {
-	// MaxAttempts is the maximum number of retry attempts
-	MaxAttempts int
-	// InitialDelay is the initial delay between retries
-	InitialDelay time.Duration
-	// MaxDelay is the maximum delay between retries
-	MaxDelay time.Duration
-	// Multiplier is the backoff multiplier
-	Multiplier float64
-	// RandomizationFactor adds jitter to delays (0.0 to 1.0)
-	RandomizationFactor float64
-	// RetryableErrors defines which errors should trigger a retry
-	RetryableErrors []string
-	// RetryableStatusCodes defines which HTTP status codes should trigger a retry
+	RetryableErrors      []string
 	RetryableStatusCodes []int
+	MaxAttempts          int
+	InitialDelay         time.Duration
+	MaxDelay             time.Duration
+	Multiplier           float64
+	RandomizationFactor  float64
 }
 
 // DefaultRetryConfig returns sensible default retry configuration
@@ -46,13 +39,11 @@ func DefaultRetryConfig() RetryConfig {
 
 // RetryExecutor implements retry logic with exponential backoff
 type RetryExecutor struct {
+	lastRetryTime time.Time
 	*BaseRecoveryMechanism
-	config RetryConfig
-
-	// Metrics
+	config         RetryConfig
 	totalRetries   int64
 	maxRetriesHit  int64
-	lastRetryTime  time.Time
 	retryTimeMutex sync.RWMutex
 }
 

internal/recovery/metrics_test.go

@@ -273,17 +273,17 @@ func TestRetryExecutor_isRetryableError(t *testing.T) {
 	executor := NewRetryExecutor(config, logger)
 
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
-		{"nil error", nil, false},
-		{"connection refused", errors.New("connection refused"), true},
-		{"timeout", errors.New("TIMEOUT"), true}, // case insensitive
-		{"EOF", errors.New("EOF"), false},
-		{"random error", errors.New("something else"), false},
-		{"context cancelled", context.Canceled, false},
-		{"context deadline exceeded", context.DeadlineExceeded, false},
+		{name: "nil error", err: nil, expected: false},
+		{name: "connection refused", err: errors.New("connection refused"), expected: true},
+		{name: "timeout", err: errors.New("TIMEOUT"), expected: true}, // case insensitive
+		{name: "EOF", err: errors.New("EOF"), expected: false},
+		{name: "random error", err: errors.New("something else"), expected: false},
+		{name: "context cancelled", err: context.Canceled, expected: false},
+		{name: "context deadline exceeded", err: context.DeadlineExceeded, expected: false},
 	}
 
 	for _, tt := range tests {

internal/recovery/recovery_test.go

@@ -13,10 +13,10 @@ import (
 
 // Mock logger for testing
 type mockLogger struct {
-	mu       sync.Mutex
 	logs     []string
 	errLogs  []string
 	debugLog []string
+	mu       sync.Mutex
 }
 
 func (m *mockLogger) Logf(format string, args ...interface{}) {
@@ -202,13 +202,13 @@ func TestBaseRecoveryMechanism_ConcurrentAccess(t *testing.T) {
 // CircuitBreakerState tests
 func TestCircuitBreakerState_String(t *testing.T) {
 	tests := []struct {
-		state    CircuitBreakerState
 		expected string
+		state    CircuitBreakerState
 	}{
-		{CircuitBreakerClosed, "closed"},
-		{CircuitBreakerOpen, "open"},
-		{CircuitBreakerHalfOpen, "half-open"},
-		{CircuitBreakerState(99), "unknown"},
+		{state: CircuitBreakerClosed, expected: "closed"},
+		{state: CircuitBreakerOpen, expected: "open"},
+		{state: CircuitBreakerHalfOpen, expected: "half-open"},
+		{state: CircuitBreakerState(99), expected: "unknown"},
 	}
 
 	for _, tt := range tests {

internal/testutil/mocks/interfaces.go

@@ -29,26 +29,26 @@ type JWK struct {
 type TokenResponse struct {
 	AccessToken  string `json:"access_token"`
 	TokenType    string `json:"token_type"`
-	ExpiresIn    int    `json:"expires_in"`
 	RefreshToken string `json:"refresh_token,omitempty"`
 	IDToken      string `json:"id_token,omitempty"`
 	Scope        string `json:"scope,omitempty"`
+	ExpiresIn    int    `json:"expires_in"`
 }
 
 // IntrospectionResponse represents a token introspection response
 type IntrospectionResponse struct {
-	Active    bool   `json:"active"`
 	Scope     string `json:"scope,omitempty"`
 	ClientID  string `json:"client_id,omitempty"`
 	Username  string `json:"username,omitempty"`
 	TokenType string `json:"token_type,omitempty"`
-	Exp       int64  `json:"exp,omitempty"`
-	Iat       int64  `json:"iat,omitempty"`
-	Nbf       int64  `json:"nbf,omitempty"`
 	Sub       string `json:"sub,omitempty"`
 	Aud       string `json:"aud,omitempty"`
 	Iss       string `json:"iss,omitempty"`
 	Jti       string `json:"jti,omitempty"`
+	Exp       int64  `json:"exp,omitempty"`
+	Iat       int64  `json:"iat,omitempty"`
+	Nbf       int64  `json:"nbf,omitempty"`
+	Active    bool   `json:"active"`
 }
 
 // JWKCache is a testify mock for JWK caching operations

internal/testutil/mocks/session.go

@@ -8,16 +8,16 @@ import (
 
 // SessionData represents session data for testing
 type SessionData struct {
+	Claims       map[string]interface{}
 	Email        string
 	AccessToken  string
 	RefreshToken string
 	IDToken      string
-	Expiry       int64
 	Nonce        string
 	State        string
 	CodeVerifier string
 	RedirectURL  string
-	Claims       map[string]interface{}
+	Expiry       int64
 }
 
 // SessionManager is a testify mock for session management

internal/testutil/servers/oidc.go

@@ -16,45 +16,30 @@ import (
 
 // OIDCServerConfig configures the mock OIDC server behavior
 type OIDCServerConfig struct {
-	// Identity
-	Issuer string
-
-	// Discovery
-	ScopesSupported          []string
-	ResponseTypesSupported   []string
+	JWKSResponse             map[string]interface{}
+	TokenFixture             *fixtures.TokenFixture
+	UserinfoError            *OIDCError
+	UserinfoResponse         map[string]interface{}
+	IntrospectionResponse    map[string]interface{}
+	JWKSError                *OIDCError
+	RefreshError             *OIDCError
+	TokenResponse            map[string]interface{}
+	TokenError               *OIDCError
+	IntrospectionError       *OIDCError
+	RefreshResponse          map[string]interface{}
+	Issuer                   string
 	GrantTypesSupported      []string
-	ClaimsSupported          []string
 	TokenEndpointAuthMethods []string
-
-	// Token fixture for signing
-	TokenFixture *fixtures.TokenFixture
-
-	// Token endpoint behavior
-	TokenResponse   map[string]interface{}
-	TokenError      *OIDCError
-	TokenDelay      time.Duration
-	RefreshResponse map[string]interface{}
-	RefreshError    *OIDCError
-
-	// JWKS behavior
-	JWKSResponse map[string]interface{}
-	JWKSError    *OIDCError
-	JWKSDelay    time.Duration
-
-	// Introspection behavior
-	IntrospectionResponse map[string]interface{}
-	IntrospectionError    *OIDCError
-
-	// Userinfo behavior
-	UserinfoResponse map[string]interface{}
-	UserinfoError    *OIDCError
-
-	// Simulation flags
-	SimulateTimeout bool
-	TimeoutDuration time.Duration
-	RateLimitAfter  int
-	FailAfterN      int
-	FailWithStatus  int
+	ScopesSupported          []string
+	ClaimsSupported          []string
+	ResponseTypesSupported   []string
+	FailAfterN               int
+	JWKSDelay                time.Duration
+	TimeoutDuration          time.Duration
+	RateLimitAfter           int
+	TokenDelay               time.Duration
+	FailWithStatus           int
+	SimulateTimeout          bool
 }
 
 // OIDCError represents an OAuth error response
@@ -67,9 +52,9 @@ type OIDCError struct {
 type OIDCServer struct {
 	*httptest.Server
 	Config       *OIDCServerConfig
-	RequestCount int32
-	mu           sync.Mutex
 	requests     []*http.Request
+	mu           sync.Mutex
+	RequestCount int32
 }
 
 // NewOIDCServer creates a new mock OIDC server

internal/utils/utils_test.go

@@ -135,9 +135,9 @@ func TestIsTestMode(t *testing.T) {
 	// We'll test what we can control via environment variables.
 
 	tests := []struct {
-		name     string
 		setup    func()
 		cleanup  func()
+		name     string
 		expected bool
 	}{
 		{
@@ -206,8 +206,8 @@ func TestIsTestMode(t *testing.T) {
 func TestIsTestModeEdgeCases(t *testing.T) {
 	// Test with various environment variable combinations
 	tests := []struct {
-		name string
 		env  map[string]string
+		name string
 	}{
 		{
 			name: "all env vars empty",
@@ -560,11 +560,11 @@ func TestIsTestModeYaegiCompiler(t *testing.T) {
 
 // mockLogger is a simple mock implementation for testing
 type mockLogger struct {
+	lastFormat string
+	lastArgs   []interface{}
 	infoCalls  int
 	debugCalls int
 	errorCalls int
-	lastFormat string
-	lastArgs   []interface{}
 }
 
 func (m *mockLogger) Infof(format string, args ...interface{}) {

jwk.go

@@ -21,25 +21,16 @@ import (
 // JWK represents a JSON Web Key as defined in RFC 7517.
 // It can represent different key types including RSA, EC, and symmetric keys.
 type JWK struct {
-	// Key type (e.g., "RSA", "EC", "oct")
-	Kty string `json:"kty"`
-	// Key use (e.g., "sig" for signature, "enc" for encryption)
-	Use string `json:"use,omitempty"`
-	// Key operations allowed
+	Kty    string   `json:"kty"`
+	Use    string   `json:"use,omitempty"`
+	Alg    string   `json:"alg,omitempty"`
+	Kid    string   `json:"kid,omitempty"`
+	N      string   `json:"n,omitempty"`
+	E      string   `json:"e,omitempty"`
+	Crv    string   `json:"crv,omitempty"`
+	X      string   `json:"x,omitempty"`
+	Y      string   `json:"y,omitempty"`
 	KeyOps []string `json:"key_ops,omitempty"`
-	// Algorithm intended for use with this key
-	Alg string `json:"alg,omitempty"`
-	// Key ID
-	Kid string `json:"kid,omitempty"`
-
-	// RSA specific fields
-	N string `json:"n,omitempty"` // Modulus
-	E string `json:"e,omitempty"` // Exponent
-
-	// EC specific fields
-	Crv string `json:"crv,omitempty"` // Curve
-	X   string `json:"x,omitempty"`   // X coordinate
-	Y   string `json:"y,omitempty"`   // Y coordinate
 }
 
 // JWKSet represents a set of JSON Web Keys.

jwk_caching_test.go

@@ -309,18 +309,18 @@ func TestJWKCacheCleanupAndClose(t *testing.T) {
 func TestFetchJWKSEdgeCases(t *testing.T) {
 	t.Run("handles various HTTP status codes", func(t *testing.T) {
 		testCases := []struct {
+			errContains string
 			status      int
 			wantErr     bool
-			errContains string
 		}{
-			{200, false, ""},
-			{400, true, "400"},
-			{401, true, "401"},
-			{403, true, "403"},
-			{404, true, "404"},
-			{500, true, "500"},
-			{502, true, "502"},
-			{503, true, "503"},
+			{status: 200, wantErr: false, errContains: ""},
+			{status: 400, wantErr: true, errContains: "400"},
+			{status: 401, wantErr: true, errContains: "401"},
+			{status: 403, wantErr: true, errContains: "403"},
+			{status: 404, wantErr: true, errContains: "404"},
+			{status: 500, wantErr: true, errContains: "500"},
+			{status: 502, wantErr: true, errContains: "502"},
+			{status: 503, wantErr: true, errContains: "503"},
 		}
 
 		for _, tc := range testCases {

main.go

@@ -5,6 +5,8 @@ package traefikoidc
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"net/http"
 	"os"
@@ -392,11 +394,15 @@ func (t *TraefikOidc) updateMetadataEndpoints(metadata *ProviderMetadata) {
 	t.introspectionURL = metadata.IntrospectionURL // OAuth 2.0 Token Introspection endpoint (RFC 7662)
 	t.registrationURL = metadata.RegistrationURL   // OIDC Dynamic Client Registration endpoint (RFC 7591)
 
+	// Copy values for logging after unlock to avoid race conditions
+	introspectionURL := t.introspectionURL
+	registrationURL := t.registrationURL
+
 	t.metadataMu.Unlock()
 
 	// Log introspection endpoint availability for opaque token support
-	if t.introspectionURL != "" {
-		t.logger.Debugf("Token introspection endpoint discovered: %s", t.introspectionURL)
+	if introspectionURL != "" {
+		t.logger.Debugf("Token introspection endpoint discovered: %s", introspectionURL)
 		if t.allowOpaqueTokens {
 			t.logger.Debugf("Opaque token support enabled with introspection endpoint")
 		}
@@ -405,8 +411,8 @@ func (t *TraefikOidc) updateMetadataEndpoints(metadata *ProviderMetadata) {
 	}
 
 	// Log registration endpoint availability
-	if t.registrationURL != "" {
-		t.logger.Debugf("Dynamic client registration endpoint discovered: %s", t.registrationURL)
+	if registrationURL != "" {
+		t.logger.Debugf("Dynamic client registration endpoint discovered: %s", registrationURL)
 	}
 
 	// Perform Dynamic Client Registration if enabled and ClientID is not set
@@ -427,6 +433,19 @@ func (t *TraefikOidc) performDynamicClientRegistration() {
 			t.dcrConfig,
 			t.providerURL,
 		)
+
+		// Set up storage backend for credentials persistence
+		if t.dcrConfig.PersistCredentials {
+			cacheManager := GetGlobalCacheManagerWithConfig(t.goroutineWG, nil)
+			store, err := NewDCRCredentialsStore(t.dcrConfig, cacheManager, t.logger)
+			if err != nil {
+				t.logger.Errorf("Failed to create DCR credentials store: %v", err)
+				// Continue without persistence - registration will still work
+			} else {
+				t.dynamicClientRegistrar.SetStore(store)
+				t.logger.Debugf("DCR credentials store initialized with backend: %s", t.dcrConfig.StorageBackend)
+			}
+		}
 	}
 
 	// Get registration endpoint (from metadata or config override)
@@ -474,7 +493,10 @@ func (t *TraefikOidc) performDynamicClientRegistration() {
 func (t *TraefikOidc) startMetadataRefresh(providerURL string) {
 	// Use singleton resource manager for metadata refresh
 	rm := GetResourceManager()
-	taskName := "singleton-metadata-refresh"
+	// Use last 6 chars of provider URL hash to create unique task name per realm
+	// This fixes multi-realm support where different Keycloak realms need separate refresh tasks
+	hash := sha256.Sum256([]byte(providerURL))
+	taskName := "singleton-metadata-refresh-" + hex.EncodeToString(hash[:])[0:6]
 
 	// Create refresh function
 	refreshFunc := func() {
@@ -510,6 +532,27 @@ func (t *TraefikOidc) startMetadataRefresh(providerURL string) {
 	}
 }
 
+// attemptMetadataRecovery tries to fetch provider metadata when the system is in a failed state.
+// This is called periodically (every 30s) when requests come in and metadata is unavailable.
+// It allows automatic recovery when the OIDC provider becomes available again.
+func (t *TraefikOidc) attemptMetadataRecovery() {
+	if t.metadataCache == nil || t.httpClient == nil {
+		return
+	}
+
+	// Try to fetch metadata (single attempt, no aggressive retry here since this runs every 30s)
+	metadata, err := t.metadataCache.GetMetadata(t.providerURL, t.httpClient, t.logger)
+	if err != nil {
+		t.safeLogDebugf("Metadata recovery attempt failed: %v", err)
+		return
+	}
+
+	if metadata != nil {
+		t.updateMetadataEndpoints(metadata)
+		t.safeLogInfo("Successfully recovered OIDC provider metadata - service restored")
+	}
+}
+
 // createCaseInsensitiveStringMap creates a map with lowercase keys for case-insensitive matching.
 // This is used for case-insensitive matching of email addresses.
 // Parameters:

main_exchange_test.go

@@ -18,15 +18,15 @@ import (
 // TestExchangeCodeForToken_Comprehensive tests the ExchangeCodeForToken function comprehensively
 func TestExchangeCodeForToken_Comprehensive(t *testing.T) {
 	tests := []struct {
+		setupMock     func(*httptest.Server) *TraefikOidc
+		validateFunc  func(*testing.T, *TokenResponse, error)
 		name          string
 		grantType     string
 		code          string
 		redirectURL   string
 		codeVerifier  string
-		setupMock     func(*httptest.Server) *TraefikOidc
-		validateFunc  func(*testing.T, *TokenResponse, error)
-		wantErr       bool
 		expectedError string
+		wantErr       bool
 	}{
 		{
 			name:         "successful authorization code exchange",

main_goroutine_leak_test.go

@@ -13,9 +13,9 @@ import (
 func TestGoroutineLeakPrevention_ContextCancellation(t *testing.T) {
 	tests := []struct {
 		name          string
-		cancelAfter   time.Duration
-		expectedLeaks int // Maximum expected goroutines after cleanup
 		description   string
+		cancelAfter   time.Duration
+		expectedLeaks int
 	}{
 		{
 			name:          "immediate_cancellation",

main_initialization_test.go

@@ -15,10 +15,10 @@ import (
 // TestInitializeMetadata tests the initializeMetadata function
 func TestInitializeMetadata(t *testing.T) {
 	tests := []struct {
-		name         string
-		providerURL  string
 		setupMock    func() *httptest.Server
 		validateFunc func(*testing.T, *TraefikOidc)
+		name         string
+		providerURL  string
 		wantPanic    bool
 	}{
 		{

main_refresh_test.go

@@ -16,12 +16,12 @@ import (
 // TestGetNewTokenWithRefreshToken tests the GetNewTokenWithRefreshToken function
 func TestGetNewTokenWithRefreshToken(t *testing.T) {
 	tests := []struct {
-		name          string
-		refreshToken  string
 		setupMock     func(*httptest.Server) *TraefikOidc
 		validateFunc  func(*testing.T, *TokenResponse, error)
-		wantErr       bool
+		name          string
+		refreshToken  string
 		expectedError string
+		wantErr       bool
 	}{
 		{
 			name:         "successful token refresh",

main_servehttp_test.go

@@ -10,9 +10,9 @@ import (
 // TestServeHTTP_ExcludedURLs tests the excluded URLs functionality
 func TestServeHTTP_ExcludedURLs(t *testing.T) {
 	tests := []struct {
+		excludedURLs map[string]struct{}
 		name         string
 		path         string
-		excludedURLs map[string]struct{}
 		shouldBypass bool
 	}{
 		{
@@ -506,12 +506,12 @@ type MockSessionData struct {
 	idToken       string
 	accessToken   string
 	refreshToken  string
-	authenticated bool
-	isDirty       bool
-	redirectCount int
 	csrf          string
 	nonce         string
 	codeVerifier  string
+	redirectCount int
+	authenticated bool
+	isDirty       bool
 }
 
 func (m *MockSessionData) GetEmail() string                                   { return m.email }

main_simple_test.go

@@ -81,11 +81,11 @@ func TestIsTestMode_DefaultBehavior(t *testing.T) {
 // TestVerifyAudience tests the verifyAudience function
 func TestVerifyAudience(t *testing.T) {
 	tests := []struct {
-		name             string
 		tokenAudience    interface{}
+		name             string
 		expectedAudience string
-		expectError      bool
 		description      string
+		expectError      bool
 	}{
 		{
 			name:             "Audience matches",

main_test.go

@@ -192,9 +192,9 @@ func (ts *TestSuite) Setup() {
 
 // MockJWKCache implements JWKCacheInterface
 type MockJWKCache struct {
-	mu   sync.RWMutex
-	JWKS *JWKSet
 	Err  error
+	JWKS *JWKSet
+	mu   sync.RWMutex
 }
 
 // Close is a no-op for the mock.
@@ -209,11 +209,8 @@ func (m *MockJWKCache) GetJWKS(ctx context.Context, jwksURL string, httpClient *
 }
 
 func (m *MockJWKCache) Cleanup() {
-	// Mock cleanup implementation
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	m.JWKS = nil
-	m.Err = nil
+	// Mock cleanup is a no-op - we don't want to destroy the mock JWKS data
+	// Real cleanup is for expired entries, not resetting all data
 }
 
 // MockTokenVerifier implements TokenVerifier for testing, allowing interception of VerifyToken calls.
@@ -2427,6 +2424,276 @@ func TestMultipleMiddlewareInstances(t *testing.T) {
 	}
 }
 
+// TestMultiRealmMetadataRefreshIsolation verifies that multiple middleware instances
+// with different provider URLs (e.g., different Keycloak realms) get separate
+// metadata refresh tasks. This addresses the issue reported in PR #88.
+func TestMultiRealmMetadataRefreshIsolation(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping test in short mode")
+	}
+
+	// Create two mock provider metadata servers simulating different Keycloak realms
+	realm1Server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		metadata := ProviderMetadata{
+			Issuer:        "https://keycloak.example.com/realms/realm1",
+			AuthURL:       "https://keycloak.example.com/realms/realm1/protocol/openid-connect/auth",
+			TokenURL:      "https://keycloak.example.com/realms/realm1/protocol/openid-connect/token",
+			JWKSURL:       "https://keycloak.example.com/realms/realm1/protocol/openid-connect/certs",
+			EndSessionURL: "https://keycloak.example.com/realms/realm1/protocol/openid-connect/logout",
+		}
+		json.NewEncoder(w).Encode(metadata)
+	}))
+	defer realm1Server.Close()
+
+	realm2Server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		metadata := ProviderMetadata{
+			Issuer:        "https://keycloak.example.com/realms/realm2",
+			AuthURL:       "https://keycloak.example.com/realms/realm2/protocol/openid-connect/auth",
+			TokenURL:      "https://keycloak.example.com/realms/realm2/protocol/openid-connect/token",
+			JWKSURL:       "https://keycloak.example.com/realms/realm2/protocol/openid-connect/certs",
+			EndSessionURL: "https://keycloak.example.com/realms/realm2/protocol/openid-connect/logout",
+		}
+		json.NewEncoder(w).Encode(metadata)
+	}))
+	defer realm2Server.Close()
+
+	// Config for realm1
+	config1 := &Config{
+		ProviderURL:          realm1Server.URL,
+		ClientID:             "realm1-client",
+		ClientSecret:         "realm1-secret",
+		CallbackURL:          "/realm1/callback",
+		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
+		CookiePrefix:         "_oidc_realm1_",
+	}
+
+	// Config for realm2
+	config2 := &Config{
+		ProviderURL:          realm2Server.URL,
+		ClientID:             "realm2-client",
+		ClientSecret:         "realm2-secret",
+		CallbackURL:          "/realm2/callback",
+		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
+		CookiePrefix:         "_oidc_realm2_",
+	}
+
+	// Create middleware instances for both realms
+	middleware1, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}), config1, "realm1-middleware")
+	if err != nil {
+		t.Fatalf("Failed to create middleware for realm1: %v", err)
+	}
+
+	middleware2, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}), config2, "realm2-middleware")
+	if err != nil {
+		t.Fatalf("Failed to create middleware for realm2: %v", err)
+	}
+
+	m1, ok1 := middleware1.(*TraefikOidc)
+	m2, ok2 := middleware2.(*TraefikOidc)
+	if !ok1 || !ok2 {
+		t.Fatalf("Middleware is not of type *TraefikOidc")
+	}
+
+	// Clean up middleware instances
+	defer func() {
+		if err := m1.Close(); err != nil {
+			t.Errorf("Failed to close realm1 middleware: %v", err)
+		}
+		if err := m2.Close(); err != nil {
+			t.Errorf("Failed to close realm2 middleware: %v", err)
+		}
+	}()
+
+	// Wait for both instances to initialize
+	select {
+	case <-m1.initComplete:
+	case <-time.After(5 * time.Second):
+		t.Fatalf("Realm1 middleware failed to initialize")
+	}
+
+	select {
+	case <-m2.initComplete:
+	case <-time.After(5 * time.Second):
+		t.Fatalf("Realm2 middleware failed to initialize")
+	}
+
+	// Verify each instance has the correct issuer URL from their respective realms
+	if !strings.Contains(m1.issuerURL, "realm1") {
+		t.Errorf("Realm1 middleware expected issuer with realm1, got %s", m1.issuerURL)
+	}
+	if !strings.Contains(m2.issuerURL, "realm2") {
+		t.Errorf("Realm2 middleware expected issuer with realm2, got %s", m2.issuerURL)
+	}
+
+	// Verify provider URLs are different
+	if m1.providerURL == m2.providerURL {
+		t.Errorf("Both middlewares should have different provider URLs, got same: %s", m1.providerURL)
+	}
+
+	// Test that each middleware can handle requests independently
+	req1 := httptest.NewRequest("GET", "/realm1/protected", nil)
+	rr1 := httptest.NewRecorder()
+	m1.ServeHTTP(rr1, req1)
+
+	req2 := httptest.NewRequest("GET", "/realm2/protected", nil)
+	rr2 := httptest.NewRecorder()
+	m2.ServeHTTP(rr2, req2)
+
+	// Both should redirect to their respective auth URLs
+	if rr1.Code != http.StatusFound {
+		t.Errorf("Realm1: Expected redirect status %d, got %d", http.StatusFound, rr1.Code)
+	}
+	if rr2.Code != http.StatusFound {
+		t.Errorf("Realm2: Expected redirect status %d, got %d", http.StatusFound, rr2.Code)
+	}
+
+	location1 := rr1.Header().Get("Location")
+	location2 := rr2.Header().Get("Location")
+
+	if !strings.Contains(location1, "realm1") {
+		t.Errorf("Realm1: Expected redirect to realm1 auth URL, got %s", location1)
+	}
+	if !strings.Contains(location2, "realm2") {
+		t.Errorf("Realm2: Expected redirect to realm2 auth URL, got %s", location2)
+	}
+}
+
+// TestMetadataRecoveryOnProviderFailure verifies that the middleware automatically
+// recovers when the OIDC provider becomes available after initial failure.
+func TestMetadataRecoveryOnProviderFailure(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping test in short mode")
+	}
+
+	// Track whether the provider is "available"
+	providerAvailable := false
+	var mu sync.Mutex
+
+	// Create mock provider that initially fails, then becomes available
+	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		available := providerAvailable
+		mu.Unlock()
+
+		if !available {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+
+		if r.URL.Path == "/.well-known/openid-configuration" {
+			metadata := ProviderMetadata{
+				Issuer:        "https://test-issuer.com",
+				AuthURL:       "https://test-issuer.com/auth",
+				TokenURL:      "https://test-issuer.com/token",
+				JWKSURL:       "https://test-issuer.com/jwks",
+				EndSessionURL: "https://test-issuer.com/logout",
+			}
+			json.NewEncoder(w).Encode(metadata)
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer mockServer.Close()
+
+	config := &Config{
+		ProviderURL:          mockServer.URL,
+		ClientID:             "test-client",
+		ClientSecret:         "test-secret",
+		CallbackURL:          "/callback",
+		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
+	}
+
+	// Create middleware while provider is unavailable
+	middleware, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}), config, "test-recovery")
+	if err != nil {
+		t.Fatalf("Failed to create middleware: %v", err)
+	}
+
+	m, ok := middleware.(*TraefikOidc)
+	if !ok {
+		t.Fatalf("Middleware is not of type *TraefikOidc")
+	}
+	defer m.Close()
+
+	// Wait for initial initialization to complete (it should fail)
+	select {
+	case <-m.initComplete:
+	case <-time.After(15 * time.Second):
+		t.Fatal("Initialization did not complete in time")
+	}
+
+	// Verify initial state - should be in failed state (no issuerURL)
+	m.metadataMu.RLock()
+	initialIssuer := m.issuerURL
+	m.metadataMu.RUnlock()
+
+	if initialIssuer != "" {
+		t.Errorf("Expected empty issuerURL after failed init, got: %s", initialIssuer)
+	}
+
+	// First request should get 503
+	req1 := httptest.NewRequest("GET", "/protected", nil)
+	rr1 := httptest.NewRecorder()
+	m.ServeHTTP(rr1, req1)
+
+	if rr1.Code != http.StatusServiceUnavailable {
+		t.Errorf("Expected 503 when provider unavailable, got %d", rr1.Code)
+	}
+
+	// Now make the provider available
+	mu.Lock()
+	providerAvailable = true
+	mu.Unlock()
+
+	// Reset the retry timer to allow immediate retry
+	m.metadataRetryMutex.Lock()
+	m.lastMetadataRetryTime = time.Time{} // Reset to zero time
+	m.metadataRetryMutex.Unlock()
+
+	// Second request should trigger recovery attempt
+	req2 := httptest.NewRequest("GET", "/protected", nil)
+	rr2 := httptest.NewRecorder()
+	m.ServeHTTP(rr2, req2)
+
+	// Give the async recovery a moment to complete
+	time.Sleep(100 * time.Millisecond)
+
+	// Check if recovery happened
+	m.metadataMu.RLock()
+	recoveredIssuer := m.issuerURL
+	m.metadataMu.RUnlock()
+
+	if recoveredIssuer == "" {
+		t.Error("Expected issuerURL to be recovered after provider became available")
+	}
+
+	// Third request should succeed (redirect to auth, not 503)
+	req3 := httptest.NewRequest("GET", "/protected", nil)
+	rr3 := httptest.NewRecorder()
+	m.ServeHTTP(rr3, req3)
+
+	if rr3.Code == http.StatusServiceUnavailable {
+		t.Errorf("Expected redirect after recovery, still got 503")
+	}
+
+	t.Logf("Recovery test: initial_issuer=%q, recovered_issuer=%q, final_status=%d",
+		initialIssuer, recoveredIssuer, rr3.Code)
+}
+
 func TestServeHTTPRolesAndGroups(t *testing.T) {
 	ts := NewTestSuite(t)
 	ts.Setup()

memory_leak_test.go

@@ -42,27 +42,27 @@ func NewMemoryLeakFixesTestSuite() *MemoryLeakFixesTestSuite {
 
 // MemoryTestCase defines a memory leak test scenario
 type MemoryTestCase struct {
-	name         string
-	component    string // "cache", "session", "token", "plugin", "pool"
-	scenario     string // "concurrent", "longrunning", "stress", "lifecycle"
-	iterations   int
-	concurrency  int
 	setup        func(*MemoryTestFramework) error
 	execute      func(*MemoryTestFramework) error
 	validateLeak func(*testing.T, runtime.MemStats, runtime.MemStats)
 	cleanup      func(*MemoryTestFramework) error
+	name         string
+	component    string
+	scenario     string
+	iterations   int
+	concurrency  int
 }
 
 // MemoryTestFramework provides common test infrastructure for memory tests
 type MemoryTestFramework struct {
-	t       *testing.T
 	cache   CacheInterface
+	ctx     context.Context
+	t       *testing.T
 	plugin  *TraefikOidc
 	logger  *Logger
+	cancel  context.CancelFunc
 	servers []*httptest.Server
 	configs []*Config
-	ctx     context.Context
-	cancel  context.CancelFunc
 }
 
 // NewMemoryTestFramework creates a new test framework instance
@@ -97,12 +97,12 @@ func (tf *MemoryTestFramework) Cleanup() {
 // ConsolidatedMemorySnapshot captures memory statistics at a point in time
 type ConsolidatedMemorySnapshot struct {
 	Timestamp   time.Time
+	Description string
 	Alloc       uint64
 	TotalAlloc  uint64
 	Sys         uint64
-	NumGC       uint32
 	Goroutines  int
-	Description string
+	NumGC       uint32
 }
 
 // VerifyNoGoroutineLeaks checks for goroutine leaks
@@ -1601,8 +1601,8 @@ func TestMemoryLeakConsolidated(t *testing.T) {
 
 func TestGoroutineLeaks(t *testing.T) {
 	testCases := []struct {
-		name string
 		test func(t *testing.T)
+		name string
 	}{
 		{
 			name: "cache_no_leak",

memory_monitor.go

@@ -10,30 +10,24 @@ import (
 
 // MemoryStats holds comprehensive memory statistics
 type MemoryStats struct {
-	// Go runtime memory stats
-	HeapAllocBytes    uint64    // bytes allocated and still in use
-	HeapSysBytes      uint64    // bytes obtained from system
-	HeapIdleBytes     uint64    // bytes in idle (unused) spans
-	HeapInuseBytes    uint64    // bytes in in-use spans
-	HeapReleasedBytes uint64    // bytes released to the OS
-	HeapObjects       uint64    // total number of allocated objects
-	StackInuseBytes   uint64    // bytes in stack spans
-	StackSysBytes     uint64    // bytes obtained from system for stack
-	GCSysBytes        uint64    // bytes used for garbage collection system metadata
-	NumGoroutines     int       // number of goroutines that currently exist
-	LastGCTime        time.Time // time of last garbage collection
-
-	// Application-specific memory tracking
-	SessionCount    int   // current number of sessions
-	TaskCount       int   // current number of background tasks
-	CacheSize       int64 // estimated cache memory usage
-	ConnectionPools int   // number of HTTP connection pools
-
-	// Memory pressure indicators
-	MemoryPressure MemoryPressureLevel // overall memory pressure level
-	GCFrequency    float64             // garbage collections per minute
-
-	Timestamp time.Time
+	LastGCTime        time.Time
+	Timestamp         time.Time
+	GCSysBytes        uint64
+	NumGoroutines     int
+	HeapReleasedBytes uint64
+	HeapObjects       uint64
+	StackInuseBytes   uint64
+	StackSysBytes     uint64
+	HeapAllocBytes    uint64
+	HeapInuseBytes    uint64
+	HeapIdleBytes     uint64
+	SessionCount      int
+	TaskCount         int
+	CacheSize         int64
+	ConnectionPools   int
+	MemoryPressure    MemoryPressureLevel
+	GCFrequency       float64
+	HeapSysBytes      uint64
 }
 
 // MemoryPressureLevel indicates the current memory pressure
@@ -66,22 +60,18 @@ func (mpl MemoryPressureLevel) String() string {
 
 // MemoryMonitor provides comprehensive memory monitoring and alerting
 type MemoryMonitor struct {
-	logger          *Logger
-	mu              sync.RWMutex
-	lastStats       *MemoryStats
-	lastGCCount     uint32
-	lastGCTime      time.Time
-	startTime       time.Time
-	alertThresholds MemoryAlertThresholds
-
-	// Memory leak detection
-	baselineHeap     uint64
-	heapGrowthRate   float64 // bytes per second
-	suspiciousGrowth bool
-
-	// Goroutine tracking
+	lastGCTime         time.Time
+	startTime          time.Time
+	lastStats          *MemoryStats
+	logger             *Logger
+	alertThresholds    MemoryAlertThresholds
 	baselineGoroutines int
+	baselineHeap       uint64
+	heapGrowthRate     float64
 	maxGoroutines      int64
+	mu                 sync.RWMutex
+	lastGCCount        uint32
+	suspiciousGrowth   bool
 	goroutineLeakAlert bool
 }
 

middleware.go

@@ -50,6 +50,20 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 		t.metadataMu.RUnlock()
 
 		if issuerURL == "" {
+			// Provider metadata initialization failed - try to recover
+			// Retry every 30 seconds to allow automatic recovery when provider comes back online
+			t.metadataRetryMutex.Lock()
+			shouldRetry := time.Since(t.lastMetadataRetryTime) >= 30*time.Second
+			if shouldRetry {
+				t.lastMetadataRetryTime = time.Now()
+			}
+			t.metadataRetryMutex.Unlock()
+
+			if shouldRetry && t.providerURL != "" {
+				t.logger.Info("Attempting to recover OIDC provider metadata...")
+				go t.attemptMetadataRecovery()
+			}
+
 			t.logger.Error("OIDC provider metadata initialization failed or incomplete")
 			t.sendErrorResponse(rw, req, "OIDC provider metadata initialization failed - please check provider availability and configuration", http.StatusServiceUnavailable)
 			return

mocks_test.go

@@ -19,31 +19,25 @@ import (
 
 // MockOAuthProvider simulates an OAuth/OIDC provider for testing
 type MockOAuthProvider struct {
-	TokenEndpoint      string
-	AuthEndpoint       string
-	JWKSEndpoint       string
-	RevokeEndpoint     string
-	EndSessionEndpoint string
-
-	// Configurable behaviors
-	TokenExchangeFunc func(grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error)
-	RefreshTokenFunc  func(refreshToken string) (*TokenResponse, error)
-	RevokeTokenFunc   func(token, tokenType string) error
-	JWKSResponseFunc  func() ([]byte, error)
-
-	// Simulation flags
-	SimulateTimeout     bool
-	SimulateRateLimit   bool
-	SimulateServerError bool
+	TokenExchangeFunc   func(grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error)
+	LastRequest         *http.Request
+	JWKSResponseFunc    func() ([]byte, error)
+	RevokeTokenFunc     func(token, tokenType string) error
+	RefreshTokenFunc    func(refreshToken string) (*TokenResponse, error)
+	EndSessionEndpoint  string
+	TokenEndpoint       string
+	RevokeEndpoint      string
+	JWKSEndpoint        string
+	AuthEndpoint        string
+	RequestHistory      []*http.Request
+	LastRequestBody     []byte
 	TimeoutDuration     time.Duration
 	ResponseDelay       time.Duration
-
-	// Request tracking
-	RequestCount    int32
-	LastRequest     *http.Request
-	LastRequestBody []byte
-	RequestHistory  []*http.Request
-	mu              sync.Mutex
+	mu                  sync.Mutex
+	RequestCount        int32
+	SimulateServerError bool
+	SimulateRateLimit   bool
+	SimulateTimeout     bool
 }
 
 // NewMockOAuthProvider creates a new mock OAuth provider with default endpoints
@@ -236,22 +230,16 @@ func (m *MockOAuthProvider) Reset() {
 
 // MockSessionManager implements a mock session manager for testing
 type MockSessionManager struct {
-	Sessions map[string]*SessionData
-	mu       sync.RWMutex
-
-	// Configurable behaviors
+	Sessions          map[string]*SessionData
 	GetSessionFunc    func(r *http.Request) (*SessionData, error)
 	SaveSessionFunc   func(r *http.Request, w http.ResponseWriter, session *SessionData) error
 	DeleteSessionFunc func(r *http.Request, w http.ResponseWriter) error
-
-	// Simulation flags
-	SimulateError    bool
-	SimulateNotFound bool
-
-	// Tracking
-	GetCallCount    int32
-	SaveCallCount   int32
-	DeleteCallCount int32
+	mu                sync.RWMutex
+	GetCallCount      int32
+	SaveCallCount     int32
+	DeleteCallCount   int32
+	SimulateError     bool
+	SimulateNotFound  bool
 }
 
 // NewMockSessionManager creates a new mock session manager
@@ -370,23 +358,16 @@ func (m *MockSessionManager) Reset() {
 
 // MockHTTPClient implements a mock HTTP client for testing
 type MockHTTPClient struct {
-	// Response configuration
-	ResponseFunc func(req *http.Request) (*http.Response, error)
-
-	// Default response settings
-	DefaultStatusCode int
-	DefaultBody       string
+	ResponseFunc      func(req *http.Request) (*http.Response, error)
 	DefaultHeaders    map[string]string
-
-	// Simulation flags
-	SimulateTimeout bool
-	SimulateError   bool
-	TimeoutDuration time.Duration
-
-	// Request tracking
-	Requests      []*http.Request
-	RequestBodies [][]byte
-	mu            sync.Mutex
+	DefaultBody       string
+	Requests          []*http.Request
+	RequestBodies     [][]byte
+	DefaultStatusCode int
+	TimeoutDuration   time.Duration
+	mu                sync.Mutex
+	SimulateTimeout   bool
+	SimulateError     bool
 }
 
 // NewMockHTTPClient creates a new mock HTTP client

refresh_coordinator.go

@@ -15,38 +15,19 @@ import (
 // It implements request coalescing, rate limiting, and circuit breaking
 // specifically for token refresh operations.
 type RefreshCoordinator struct {
-	// inFlightRefreshes tracks active refresh operations by refresh token hash
-	inFlightRefreshes map[string]*refreshOperation
-	// refreshMutex protects the inFlightRefreshes map
-	refreshMutex sync.RWMutex
-
-	// sessionRefreshAttempts tracks refresh attempts per session
+	inFlightRefreshes      map[string]*refreshOperation
+	cleanupTimers          map[string]*time.Timer
 	sessionRefreshAttempts map[string]*refreshAttemptTracker
-	// attemptsMutex protects sessionRefreshAttempts map
-	attemptsMutex sync.RWMutex
-
-	// Circuit breaker for refresh operations
-	circuitBreaker *RefreshCircuitBreaker
-
-	// Configuration
-	config RefreshCoordinatorConfig
-
-	// Metrics
-	metrics *RefreshMetrics
-
-	// Logger
-	logger *Logger
-
-	// Cleanup goroutine control
-	stopChan chan struct{}
-	wg       sync.WaitGroup
-
-	// delayedCleanupQueue stores items to be cleaned up after delay
-	// Uses a timer-based approach instead of spawning goroutines per cleanup
-	delayedCleanupQueue chan delayedCleanupItem
-	// cleanupTimerPool reuses timers to avoid goroutine-per-cleanup
-	cleanupTimerMu sync.Mutex
-	cleanupTimers  map[string]*time.Timer
+	delayedCleanupQueue    chan delayedCleanupItem
+	circuitBreaker         *RefreshCircuitBreaker
+	metrics                *RefreshMetrics
+	logger                 *Logger
+	stopChan               chan struct{}
+	config                 RefreshCoordinatorConfig
+	wg                     sync.WaitGroup
+	attemptsMutex          sync.RWMutex
+	refreshMutex           sync.RWMutex
+	cleanupTimerMu         sync.Mutex
 }
 
 // RefreshCoordinatorConfig configures the refresh coordinator behavior
@@ -89,18 +70,12 @@ func DefaultRefreshCoordinatorConfig() RefreshCoordinatorConfig {
 
 // refreshOperation represents an in-flight refresh operation
 type refreshOperation struct {
-	// refreshToken being refreshed (for validation)
+	startTime    time.Time
+	result       *refreshResult
+	done         chan struct{}
 	refreshToken string
-	// result stores the final result
-	result *refreshResult
-	// done signals when the operation is complete
-	done chan struct{}
-	// startTime tracks when the operation started
-	startTime time.Time
-	// waiterCount tracks number of goroutines waiting
-	waiterCount int32
-	// mutex protects the result field
-	mutex sync.RWMutex
+	mutex        sync.RWMutex
+	waiterCount  int32
 }
 
 // refreshResult contains the result of a refresh operation
@@ -112,18 +87,12 @@ type refreshResult struct {
 
 // refreshAttemptTracker tracks refresh attempts for a session
 type refreshAttemptTracker struct {
-	// attempts counts refresh attempts in current window
-	attempts int32
-	// lastAttemptTime is the timestamp of the last attempt
-	lastAttemptTime time.Time
-	// windowStartTime is when the current tracking window started
-	windowStartTime time.Time
-	// inCooldown indicates if this session is in cooldown
-	inCooldown bool
-	// cooldownEndTime is when cooldown period ends
-	cooldownEndTime time.Time
-	// consecutiveFailures tracks consecutive refresh failures
+	lastAttemptTime     time.Time
+	windowStartTime     time.Time
+	cooldownEndTime     time.Time
+	attempts            int32
 	consecutiveFailures int32
+	inCooldown          bool
 }
 
 // RefreshMetrics tracks coordinator performance metrics
@@ -140,18 +109,18 @@ type RefreshMetrics struct {
 
 // delayedCleanupItem represents an item scheduled for delayed cleanup
 type delayedCleanupItem struct {
-	tokenHash string
 	cleanupAt time.Time
+	tokenHash string
 }
 
 // RefreshCircuitBreaker implements a circuit breaker specifically for refresh operations
 type RefreshCircuitBreaker struct {
-	state           int32 // 0=closed, 1=open, 2=half-open
-	failures        int32
 	lastFailureTime time.Time
 	lastSuccessTime time.Time
 	config          RefreshCircuitBreakerConfig
 	mutex           sync.RWMutex
+	state           int32
+	failures        int32
 }
 
 // RefreshCircuitBreakerConfig configures the refresh circuit breaker

regression/regression_test.go

@@ -132,7 +132,7 @@ func testIssue53ReverseProxyHTTPS(t *testing.T) {
 	session.SetEmail("user@example.com")
 	// Azure may use opaque access tokens
 	session.SetAccessToken("opaque-azure-access-token")
-	session.SetIDToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.NHVaYe26MbtOYhSKkoKYdFVomg4i8ZJd8_-RU8VNbftc4TSMb4bXP3l3YlNWACwyXPGffz5aXHc6lty1Y2t4SWRqGteragsVdZufDn5BlnJl9pdR_kdVFUsra2rWKEofkZeIC4yWytE58sMIihvo9H1ScmmVwBcQP6XETqYd0aSHp1gOa9RdUPDvoXQ5oqygTqVtxaDr6wUFKrKItgBMzWIdNZ6y7O9E0DhEPTbE9rfBo6KTFsHAZnMg4k68CDp2woYIaXbmYTWcvbzIuHO7_37GT79XdIwkm95QJ7hYC9RiwrV7mesbY4PAahERJawntho0my942XheVLmGwLMBkQ")
+	session.SetIDToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.NHVaYe26MbtOYhSKkoKYdFVomg4i8ZJd8_-RU8VNbftc4TSMb4bXP3l3YlNWACwyXPGffz5aXHc6lty1Y2t4SWRqGteragsVdZufDn5BlnJl9pdR_kdVFUsra2rWKEofkZeIC4yWytE58sMIihvo9H1ScmmVwBcQP6XETqYd0aSHp1gOa9RdUPDvoXQ5oqygTqVtxaDr6wUFKrKItgBMzWIdNZ6y7O9E0DhEPTbE9rfBo6KTFsHAZnMg4k68CDp2woYIaXbmYTWcvbzIuHO7_37GT79XdIwkm95QJ7hYC9RiwrV7mesbY4PAahERJawntho0my942XheVLmGwLMBkQ") // trufflehog:ignore
 	session.SetRefreshToken("azure-refresh-token")
 
 	// Save with proper security
@@ -178,9 +178,9 @@ func testIssue53SameSiteCookies(t *testing.T) {
 	testCases := []struct {
 		name             string
 		proto            string
-		expectedSecure   bool
-		expectedSameSite http.SameSite
 		description      string
+		expectedSameSite http.SameSite
+		expectedSecure   bool
 	}{
 		{
 			name:             "HTTPS via proxy",
@@ -240,9 +240,9 @@ func testIssue60MissingClaimFields(t *testing.T) {
 
 	testCases := []struct {
 		name           string
+		description    string
 		headers        []traefikoidc.TemplatedHeader
 		shouldValidate bool
-		description    string
 	}{
 		{
 			name: "Direct claim access",

session.go

@@ -8,6 +8,7 @@ import (
 	"crypto/subtle"
 	"encoding/base64"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -66,23 +67,160 @@ func generateSecureRandomString(length int) (string, error) {
 // These are appended to the cookiePrefix to create full cookie names
 // #nosec G101 -- These are cookie name suffixes, not hardcoded credentials
 const (
-	mainCookieSuffix    = "m"
-	accessTokenSuffix   = "a"
-	refreshTokenSuffix  = "r"
-	idTokenSuffix       = "id"
-	defaultCookiePrefix = "_oidc_raczylo_"
+	mainCookieSuffix     = "m"
+	accessTokenSuffix    = "a"
+	refreshTokenSuffix   = "r"
+	idTokenSuffix        = "id"
+	combinedCookieSuffix = "s" // Combined session cookie suffix
+	defaultCookiePrefix  = "_oidc_raczylo_"
 )
 
 const (
-	maxBrowserCookieSize = 3500
+	// maxCookieSize is the maximum raw data size per chunk before securecookie encoding.
+	//
+	// Browser cookie limit: 4096 bytes
+	// Securecookie overhead: ~2x (gob + AES encryption + MAC + double base64)
+	// Safety headroom: 1000 bytes for cookie metadata, headers, edge cases
+	//
+	// Math: 1400 raw → ~2800 encoded → safely under (4096 - 1000 = 3096) limit
+	maxCookieSize = 1400
 
-	maxCookieSize = 1200
+	// maxCombinedChunks is the maximum number of chunks allowed for combined session
+	maxCombinedChunks = 10
 
 	absoluteSessionTimeout = 24 * time.Hour
 
 	minEncryptionKeyLength = 32
 )
 
+// combinedSessionPayload is the JSON structure for combined cookie storage.
+// Uses short field names to minimize size.
+type combinedSessionPayload struct {
+	X  map[string]interface{} `json:"x,omitempty"`
+	A  string                 `json:"a,omitempty"`
+	R  string                 `json:"r,omitempty"`
+	I  string                 `json:"i,omitempty"`
+	E  string                 `json:"e,omitempty"`
+	Cs string                 `json:"cs,omitempty"`
+	N  string                 `json:"n,omitempty"`
+	Cv string                 `json:"cv,omitempty"`
+	Ip string                 `json:"ip,omitempty"`
+	Ca int64                  `json:"ca,omitempty"`
+	Rc int                    `json:"rc,omitempty"`
+	Au bool                   `json:"au,omitempty"`
+}
+
+// knownSessionKeys are the standard keys that are handled explicitly in the combined payload.
+// All other mainSession.Values keys are stored in the X (extra) field.
+var knownSessionKeys = map[string]bool{
+	"access_token":   true,
+	"refresh_token":  true,
+	"id_token":       true,
+	"email":          true,
+	"authenticated":  true,
+	"csrf":           true,
+	"nonce":          true,
+	"code_verifier":  true,
+	"incoming_path":  true,
+	"created_at":     true,
+	"redirect_count": true,
+}
+
+// compressCombinedPayload compresses the combined session payload using gzip.
+// It serializes the payload to JSON, compresses it, and returns base64-encoded data.
+// Returns the compressed string and any error encountered.
+func compressCombinedPayload(payload *combinedSessionPayload) (string, error) {
+	jsonData, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal combined payload: %w", err)
+	}
+
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	if _, err := gz.Write(jsonData); err != nil {
+		return "", fmt.Errorf("failed to compress combined payload: %w", err)
+	}
+	if err := gz.Close(); err != nil {
+		return "", fmt.Errorf("failed to close gzip writer: %w", err)
+	}
+
+	compressed := base64.StdEncoding.EncodeToString(buf.Bytes())
+	return compressed, nil
+}
+
+// decompressCombinedPayload decompresses a base64+gzip encoded combined session payload.
+// Returns the deserialized payload and any error encountered.
+func decompressCombinedPayload(compressed string) (*combinedSessionPayload, error) {
+	if compressed == "" {
+		return nil, fmt.Errorf("empty compressed data")
+	}
+
+	data, err := base64.StdEncoding.DecodeString(compressed)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode base64: %w", err)
+	}
+
+	gr, err := gzip.NewReader(bytes.NewReader(data))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create gzip reader: %w", err)
+	}
+	defer gr.Close()
+
+	// Limit decompressed size to prevent zip bombs
+	limitedReader := io.LimitReader(gr, 512*1024) // 512KB max
+	decompressed, err := io.ReadAll(limitedReader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decompress: %w", err)
+	}
+
+	var payload combinedSessionPayload
+	if err := json.Unmarshal(decompressed, &payload); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal combined payload: %w", err)
+	}
+
+	return &payload, nil
+}
+
+// splitCombinedIntoChunks splits compressed data into chunks of maxCookieSize.
+// Returns the chunks and the total number of chunks.
+func splitCombinedIntoChunks(data string, chunkSize int) []string {
+	if len(data) <= chunkSize {
+		return []string{data}
+	}
+
+	var chunks []string
+	for i := 0; i < len(data); i += chunkSize {
+		end := i + chunkSize
+		if end > len(data) {
+			end = len(data)
+		}
+		chunks = append(chunks, data[i:end])
+	}
+	return chunks
+}
+
+// assembleCombinedChunks reassembles chunks back into the original compressed data.
+// It reads chunks from session values in order (chunk_0, chunk_1, etc.).
+func assembleCombinedChunks(sessions []*sessions.Session) string {
+	if len(sessions) == 0 {
+		return ""
+	}
+
+	var parts []string
+	for i := 0; i < len(sessions); i++ {
+		session := sessions[i]
+		if session == nil {
+			break
+		}
+		chunk, ok := session.Values["d"].(string) // "d" for data
+		if !ok || chunk == "" {
+			break
+		}
+		parts = append(parts, chunk)
+	}
+	return strings.Join(parts, "")
+}
+
 // compressToken compresses a JWT token using gzip compression if beneficial.
 // It validates the token format, attempts compression, and verifies the compressed
 // data can be decompressed correctly. Only compresses if it reduces size.
@@ -236,22 +374,22 @@ func decompressTokenInternal(compressed string) string {
 // session object reuse and supports both HTTP and HTTPS schemes.
 type SessionManager struct {
 	sessionPool    sync.Pool
+	ctx            context.Context
 	store          sessions.Store
 	logger         *Logger
 	chunkManager   *ChunkManager
-	cookieDomain   string
-	cookiePrefix   string        // Prefix for cookie names (default: "_oidc_raczylo_")
-	sessionMaxAge  time.Duration // Maximum session age (default: 24 hours)
-	cleanupMutex   sync.RWMutex
-	forceHTTPS     bool
-	cleanupDone    bool
-	ctx            context.Context
-	cancel         context.CancelFunc
 	memoryMonitor  *TaskMemoryMonitor
+	cancel         context.CancelFunc
+	cookieDomain   string
+	cookiePrefix   string
+	sessionMaxAge  time.Duration
 	activeSessions int64
 	poolHits       int64
 	poolMisses     int64
+	cleanupMutex   sync.RWMutex
 	shutdownOnce   sync.Once
+	forceHTTPS     bool
+	cleanupDone    bool
 }
 
 // NewSessionManager creates a new SessionManager instance with secure defaults.
@@ -312,6 +450,8 @@ func NewSessionManager(encryptionKey string, forceHTTPS bool, cookieDomain strin
 			accessTokenChunks:  make(map[int]*sessions.Session),
 			refreshTokenChunks: make(map[int]*sessions.Session),
 			idTokenChunks:      make(map[int]*sessions.Session),
+			combinedChunks:     make(map[int]*sessions.Session),
+			useCombinedStorage: true, // Use combined storage by default for new sessions
 			refreshMutex:       sync.Mutex{},
 			sessionMutex:       sync.RWMutex{},
 			dirty:              false,
@@ -349,6 +489,17 @@ func (sm *SessionManager) idTokenCookieName() string {
 	return sm.cookiePrefix + idTokenSuffix
 }
 
+// combinedCookieName returns the combined session cookie base name with the configured prefix
+// Chunk cookies are named: prefix + "s" + "_" + chunkIndex (e.g., "_oidc_raczylo_s_0")
+func (sm *SessionManager) combinedCookieName() string {
+	return sm.cookiePrefix + combinedCookieSuffix
+}
+
+// combinedChunkCookieName returns the name for a specific combined session chunk
+func (sm *SessionManager) combinedChunkCookieName(chunkIndex int) string {
+	return fmt.Sprintf("%s_%d", sm.combinedCookieName(), chunkIndex)
+}
+
 // Shutdown gracefully shuts down the SessionManager and all its background tasks
 func (sm *SessionManager) Shutdown() error {
 	var shutdownErr error
@@ -650,7 +801,7 @@ func (sm *SessionManager) GetSessionMetrics() map[string]interface{} {
 	metrics["force_https"] = sm.forceHTTPS
 	metrics["absolute_timeout_hours"] = sm.sessionMaxAge.Hours()
 	metrics["max_cookie_size"] = maxCookieSize
-	metrics["max_browser_cookie_size"] = maxBrowserCookieSize
+	metrics["max_encoded_cookie_size"] = maxCookieSize * 2 // ~2x encoding overhead
 
 	if cookieStore, ok := sm.store.(*sessions.CookieStore); ok && len(cookieStore.Codecs) > 0 {
 		metrics["has_encryption"] = true
@@ -824,9 +975,10 @@ func (sm *SessionManager) CleanupOldCookies(w http.ResponseWriter, r *http.Reque
 }
 
 // GetSession retrieves or creates session data from the HTTP request.
-// It loads the main session and all token chunk sessions, performing validation
-// and timeout checks. The returned session must be explicitly returned to the pool
-// by calling returnToPoolSafely() to prevent memory leaks.
+// It first tries to load from combined cookies (new format), falling back to legacy
+// cookies if combined cookies don't exist. Performs validation and timeout checks.
+// The returned session must be explicitly returned to the pool by calling
+// returnToPoolSafely() to prevent memory leaks.
 // MEMORY LEAK FIX: Session is NOT returned to pool here - caller must call ReturnToPool() when done.
 // Parameters:
 //   - r: The HTTP request containing session cookies.
@@ -853,6 +1005,26 @@ func (sm *SessionManager) GetSession(r *http.Request) (*SessionData, error) {
 		return nil, fmt.Errorf("%s: %w", message, err)
 	}
 
+	// Try to load from combined cookies first (new format)
+	if sm.loadFromCombinedCookies(r, sessionData) {
+		sessionData.useCombinedStorage = true
+		sm.logger.Debug("Loaded session from combined cookies")
+
+		// Check session timeout
+		if sessionData.getCreatedAtUnsafe() > 0 {
+			if time.Since(time.Unix(sessionData.getCreatedAtUnsafe(), 0)) > sm.sessionMaxAge {
+				_ = sessionData.Clear(r, nil) // Safe to ignore: session is being invalidated
+				return handleError(fmt.Errorf("session timeout"), "session expired")
+			}
+		}
+
+		return sessionData, nil
+	}
+
+	// Fall back to legacy cookies
+	sessionData.useCombinedStorage = false
+	sm.logger.Debug("Loading session from legacy cookies")
+
 	var err error
 	sessionData.mainSession, err = sm.store.Get(r, sm.mainCookieName())
 	if err != nil {
@@ -895,9 +1067,94 @@ func (sm *SessionManager) GetSession(r *http.Request) (*SessionData, error) {
 	sm.getTokenChunkSessions(r, sm.refreshTokenCookieName(), sessionData.refreshTokenChunks)
 	sm.getTokenChunkSessions(r, sm.idTokenCookieName(), sessionData.idTokenChunks)
 
+	// If legacy session has data, migrate to combined storage on next save
+	if !sessionData.mainSession.IsNew {
+		sessionData.useCombinedStorage = true
+		sessionData.dirty = true // Mark dirty to trigger migration on save
+		sm.logger.Debug("Legacy session found, will migrate to combined storage on save")
+	}
+
 	return sessionData, nil
 }
 
+// loadFromCombinedCookies attempts to load session data from combined cookies.
+// Returns true if combined cookies were found and successfully loaded.
+func (sm *SessionManager) loadFromCombinedCookies(r *http.Request, sessionData *SessionData) bool {
+	// Check if first combined chunk exists
+	firstChunk, err := sm.store.Get(r, sm.combinedChunkCookieName(0))
+	if err != nil || firstChunk.IsNew {
+		return false
+	}
+
+	// Get total chunk count from first chunk
+	totalChunks, ok := firstChunk.Values["n"].(int)
+	if !ok || totalChunks < 1 || totalChunks > maxCombinedChunks {
+		sm.logger.Debugf("Invalid combined cookie chunk count: %v", firstChunk.Values["n"])
+		return false
+	}
+
+	// Load all chunks
+	chunkSessions := make([]*sessions.Session, totalChunks)
+	chunkSessions[0] = firstChunk
+	sessionData.combinedChunks[0] = firstChunk
+
+	for i := 1; i < totalChunks; i++ {
+		chunk, err := sm.store.Get(r, sm.combinedChunkCookieName(i))
+		if err != nil || chunk.IsNew {
+			sm.logger.Debugf("Missing combined cookie chunk %d", i)
+			return false
+		}
+		chunkSessions[i] = chunk
+		sessionData.combinedChunks[i] = chunk
+	}
+
+	// Assemble and decompress
+	compressed := assembleCombinedChunks(chunkSessions)
+	if compressed == "" {
+		sm.logger.Debug("Failed to assemble combined chunks")
+		return false
+	}
+
+	payload, err := decompressCombinedPayload(compressed)
+	if err != nil {
+		sm.logger.Debugf("Failed to decompress combined payload: %v", err)
+		return false
+	}
+
+	// Hydrate the legacy session objects for compatibility with existing getter methods
+	// We need to initialize them even though we're using combined storage
+	sessionData.mainSession, _ = sm.store.Get(r, sm.mainCookieName())
+	sessionData.accessSession, _ = sm.store.Get(r, sm.accessTokenCookieName())
+	sessionData.refreshSession, _ = sm.store.Get(r, sm.refreshTokenCookieName())
+	sessionData.idTokenSession, _ = sm.store.Get(r, sm.idTokenCookieName())
+
+	// Populate legacy session values from combined payload
+	sessionData.mainSession.Values["email"] = payload.E
+	sessionData.mainSession.Values["authenticated"] = payload.Au
+	sessionData.mainSession.Values["csrf"] = payload.Cs
+	sessionData.mainSession.Values["nonce"] = payload.N
+	sessionData.mainSession.Values["code_verifier"] = payload.Cv
+	sessionData.mainSession.Values["incoming_path"] = payload.Ip
+	sessionData.mainSession.Values["created_at"] = payload.Ca
+	sessionData.mainSession.Values["redirect_count"] = payload.Rc
+
+	// Restore extra custom session values
+	for key, val := range payload.X {
+		sessionData.mainSession.Values[key] = val
+	}
+
+	sessionData.accessSession.Values["token"] = payload.A
+	sessionData.accessSession.Values["compressed"] = false
+
+	sessionData.refreshSession.Values["token"] = payload.R
+	sessionData.refreshSession.Values["compressed"] = false
+
+	sessionData.idTokenSession.Values["token"] = payload.I
+	sessionData.idTokenSession.Values["compressed"] = false
+
+	return true
+}
+
 // getTokenChunkSessions loads all available token chunk sessions for a given token type.
 // It iterates through numbered chunk sessions until no more are found,
 // populating the provided chunks map with the loaded sessions.
@@ -920,11 +1177,13 @@ func (sm *SessionManager) getTokenChunkSessions(r *http.Request, baseName string
 // SessionData represents a user's authentication session with comprehensive token management.
 // It handles main session data and supports large tokens that need to be
 // split across multiple cookies due to browser size limitations.
+// Supports both legacy (separate cookies) and combined (single compressed cookie) storage.
 type SessionData struct {
 	manager *SessionManager
 
 	request *http.Request
 
+	// Legacy storage (kept for backward compatibility during migration)
 	mainSession *sessions.Session
 
 	accessSession *sessions.Session
@@ -939,6 +1198,12 @@ type SessionData struct {
 
 	idTokenChunks map[int]*sessions.Session
 
+	// Combined storage (new approach - single compressed cookie)
+	combinedChunks map[int]*sessions.Session
+
+	// useCombinedStorage indicates whether to use the new combined storage format
+	useCombinedStorage bool
+
 	refreshMutex sync.Mutex
 
 	sessionMutex sync.RWMutex
@@ -966,6 +1231,7 @@ func (sd *SessionData) MarkDirty() {
 // Save persists all session data including main session and token chunks.
 // It applies security options, saves all session components, and handles
 // errors gracefully by continuing to save other components even if one fails.
+// Uses combined cookie storage for efficiency when useCombinedStorage is true.
 // Parameters:
 //   - r: The HTTP request context for security option configuration.
 //   - w: The HTTP response writer for setting session cookies.
@@ -978,6 +1244,117 @@ func (sd *SessionData) Save(r *http.Request, w http.ResponseWriter) error {
 	options := sd.manager.getSessionOptions(isSecure)
 	options = sd.manager.EnhanceSessionSecurity(options, r)
 
+	// Use combined storage for new sessions
+	if sd.useCombinedStorage {
+		return sd.saveCombined(r, w, options)
+	}
+
+	// Legacy storage path (for backward compatibility)
+	return sd.saveLegacy(r, w, options)
+}
+
+// saveCombined saves all session data in a single compressed, chunked cookie.
+// This reduces cookie count and total size through combined compression.
+func (sd *SessionData) saveCombined(r *http.Request, w http.ResponseWriter, options *sessions.Options) error {
+	// Build the combined payload
+	payload := &combinedSessionPayload{
+		A:  sd.getAccessTokenUnsafe(),
+		R:  sd.getRefreshTokenUnsafe(),
+		I:  sd.getIDTokenUnsafe(),
+		E:  sd.getEmailUnsafe(),
+		Au: sd.getAuthenticatedUnsafe(),
+		Cs: sd.getCSRFUnsafe(),
+		N:  sd.getNonceUnsafe(),
+		Cv: sd.getCodeVerifierUnsafe(),
+		Ip: sd.getIncomingPathUnsafe(),
+		Ca: sd.getCreatedAtUnsafe(),
+		Rc: sd.getRedirectCountUnsafe(),
+	}
+
+	// Collect extra session values not handled by the standard fields
+	sd.sessionMutex.RLock()
+	if sd.mainSession != nil && len(sd.mainSession.Values) > 0 {
+		extra := make(map[string]interface{})
+		for key, val := range sd.mainSession.Values {
+			keyStr, ok := key.(string)
+			if !ok {
+				continue
+			}
+			// Skip known session keys that are already in the payload
+			if knownSessionKeys[keyStr] {
+				continue
+			}
+			// Store the extra value (must be JSON-serializable)
+			extra[keyStr] = val
+		}
+		if len(extra) > 0 {
+			payload.X = extra
+		}
+	}
+	sd.sessionMutex.RUnlock()
+
+	// Compress the payload
+	compressed, err := compressCombinedPayload(payload)
+	if err != nil {
+		sd.manager.logger.Errorf("Failed to compress combined payload: %v", err)
+		// Fall back to legacy storage on compression failure
+		return sd.saveLegacy(r, w, options)
+	}
+
+	sd.manager.logger.Debugf("Combined session: raw payload compressed to %d bytes", len(compressed))
+
+	// Split into chunks
+	chunks := splitCombinedIntoChunks(compressed, maxCookieSize)
+	if len(chunks) > maxCombinedChunks {
+		sd.manager.logger.Errorf("Combined session requires %d chunks, exceeds max %d", len(chunks), maxCombinedChunks)
+		return fmt.Errorf("session data too large: requires %d chunks, max is %d", len(chunks), maxCombinedChunks)
+	}
+
+	sd.manager.logger.Debugf("Combined session split into %d chunks", len(chunks))
+
+	var firstErr error
+
+	// Save each chunk
+	for i, chunkData := range chunks {
+		cookieName := sd.manager.combinedChunkCookieName(i)
+		session, err := sd.manager.store.Get(r, cookieName)
+		if err != nil {
+			sd.manager.logger.Errorf("Failed to get combined chunk session %s: %v", cookieName, err)
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+
+		session.Values["d"] = chunkData   // "d" for data
+		session.Values["n"] = len(chunks) // "n" for total number of chunks
+		session.Values["i"] = i           // "i" for index
+		session.Options = options
+
+		if err := session.Save(r, w); err != nil {
+			sd.manager.logger.Errorf("Failed to save combined chunk %d: %v", i, err)
+			if firstErr == nil {
+				firstErr = err
+			}
+		}
+		sd.combinedChunks[i] = session
+	}
+
+	// Expire old combined chunks that are no longer needed
+	sd.expireOldCombinedChunks(r, w, options, len(chunks))
+
+	// Expire legacy cookies if they exist (migration)
+	sd.expireLegacyCookies(r, w, options)
+
+	if firstErr == nil {
+		sd.dirty = false
+	}
+	return firstErr
+}
+
+// saveLegacy saves session data using the old separate cookie approach.
+// Kept for backward compatibility during migration.
+func (sd *SessionData) saveLegacy(r *http.Request, w http.ResponseWriter, options *sessions.Options) error {
 	sd.mainSession.Options = options
 	sd.accessSession.Options = options
 	sd.refreshSession.Options = options
@@ -1002,11 +1379,8 @@ func (sd *SessionData) Save(r *http.Request, w http.ResponseWriter) error {
 	}
 
 	saveOrLogError(sd.mainSession, "main")
-
 	saveOrLogError(sd.accessSession, "access token")
-
 	saveOrLogError(sd.refreshSession, "refresh token")
-
 	saveOrLogError(sd.idTokenSession, "ID token")
 
 	for i, sessionChunk := range sd.accessTokenChunks {
@@ -1030,6 +1404,84 @@ func (sd *SessionData) Save(r *http.Request, w http.ResponseWriter) error {
 	return firstErr
 }
 
+// expireOldCombinedChunks expires combined cookie chunks that are no longer needed.
+func (sd *SessionData) expireOldCombinedChunks(r *http.Request, w http.ResponseWriter, options *sessions.Options, currentChunks int) {
+	// Expire chunks beyond the current count
+	for i := currentChunks; i < maxCombinedChunks; i++ {
+		cookieName := sd.manager.combinedChunkCookieName(i)
+		session, err := sd.manager.store.Get(r, cookieName)
+		if err != nil || session.IsNew {
+			// No more old chunks
+			break
+		}
+		// Expire this chunk
+		expireOptions := *options
+		expireOptions.MaxAge = -1
+		session.Options = &expireOptions
+		for k := range session.Values {
+			delete(session.Values, k)
+		}
+		if err := session.Save(r, w); err != nil {
+			sd.manager.logger.Debugf("Failed to expire old combined chunk %d: %v", i, err)
+		}
+	}
+}
+
+// expireLegacyCookies expires old legacy format cookies during migration.
+func (sd *SessionData) expireLegacyCookies(r *http.Request, w http.ResponseWriter, options *sessions.Options) {
+	expireOptions := *options
+	expireOptions.MaxAge = -1
+
+	// Helper to expire a legacy session cookie without clearing in-memory values
+	// IMPORTANT: We must NOT clear values from sessions that sd is holding,
+	// as store.Get() returns the same cached session object
+	expireLegacyChunk := func(cookieName string) {
+		session, err := sd.manager.store.Get(r, cookieName)
+		if err != nil || session.IsNew {
+			return // Cookie doesn't exist
+		}
+		session.Options = &expireOptions
+		// Clear values from chunk cookies (not the main session objects)
+		for k := range session.Values {
+			delete(session.Values, k)
+		}
+		_ = session.Save(r, w) // Best effort
+	}
+
+	// For main session cookies, only set expiration WITHOUT clearing values
+	// because sd.mainSession, sd.accessSession, etc. point to these same objects
+	expireLegacyMain := func(cookieName string) {
+		session, err := sd.manager.store.Get(r, cookieName)
+		if err != nil || session.IsNew {
+			return // Cookie doesn't exist
+		}
+		// Just expire the cookie, don't clear values (they're still needed in memory)
+		session.Options = &expireOptions
+		_ = session.Save(r, w) // Best effort
+	}
+
+	// Expire main legacy cookies (don't clear in-memory values)
+	expireLegacyMain(sd.manager.mainCookieName())
+	expireLegacyMain(sd.manager.accessTokenCookieName())
+	expireLegacyMain(sd.manager.refreshTokenCookieName())
+	expireLegacyMain(sd.manager.idTokenCookieName())
+
+	// Expire legacy chunk cookies (safe to clear values, they're separate from main sessions)
+	for i := 0; i < 50; i++ { // Max legacy chunks was 50
+		accessChunk := fmt.Sprintf("%s_%d", sd.manager.accessTokenCookieName(), i)
+		refreshChunk := fmt.Sprintf("%s_%d", sd.manager.refreshTokenCookieName(), i)
+		idChunk := fmt.Sprintf("%s_%d", sd.manager.idTokenCookieName(), i)
+
+		session, err := sd.manager.store.Get(r, accessChunk)
+		if err != nil || session.IsNew {
+			break // No more chunks
+		}
+		expireLegacyChunk(accessChunk)
+		expireLegacyChunk(refreshChunk)
+		expireLegacyChunk(idChunk)
+	}
+}
+
 // clearSessionValues removes all values from a session and optionally expires it.
 // This is used during session cleanup and logout operations.
 // Parameters:
@@ -1263,6 +1715,12 @@ func (sd *SessionData) Reset() {
 	resetSession(sd.refreshSession)
 	resetSession(sd.idTokenSession)
 
+	// Clear combined chunks
+	for k, session := range sd.combinedChunks {
+		resetSession(session)
+		delete(sd.combinedChunks, k)
+	}
+
 	// Clear redirect count to prevent leaking between sessions
 	if sd.mainSession != nil && sd.mainSession.Values != nil {
 		delete(sd.mainSession.Values, "redirect_count")
@@ -1271,6 +1729,7 @@ func (sd *SessionData) Reset() {
 	sd.dirty = false
 	sd.inUse = false
 	sd.request = nil
+	sd.useCombinedStorage = true // Reset to use combined storage by default
 
 	// Reset the refresh mutex to ensure clean state
 	// Note: We don't need to lock it since sessionMutex is already held
@@ -1886,8 +2345,9 @@ func splitIntoChunks(s string, chunkSize int) []string {
 // Returns:
 //   - true if the chunk is safe to store, false if it may exceed browser limits.
 func validateChunkSize(chunkData string) bool {
+	// Estimate ~50% overhead for encoding, compare against ~2x maxCookieSize limit
 	estimatedEncodedSize := len(chunkData) + (len(chunkData) * 50 / 100)
-	return estimatedEncodedSize <= maxBrowserCookieSize
+	return estimatedEncodedSize <= maxCookieSize*2
 }
 
 // isCorruptionMarker detects if data contains known corruption indicators.
@@ -2088,6 +2548,78 @@ func (sd *SessionData) getIDTokenUnsafe() string {
 	return result.Token
 }
 
+// getRefreshTokenUnsafe retrieves the refresh token without acquiring locks.
+// Used when the session mutex is already held to prevent deadlocks.
+func (sd *SessionData) getRefreshTokenUnsafe() string {
+	token, _ := sd.refreshSession.Values["token"].(string)
+	compressed, _ := sd.refreshSession.Values["compressed"].(bool)
+
+	if sd.manager == nil || sd.manager.chunkManager == nil {
+		return token
+	}
+
+	result := sd.manager.chunkManager.GetToken(
+		token,
+		compressed,
+		sd.refreshTokenChunks,
+		RefreshTokenConfig,
+	)
+
+	if result.Error != nil {
+		// Handle opaque tokens
+		if token != "" && !compressed && len(sd.refreshTokenChunks) == 0 {
+			if strings.Count(token, ".") != 2 {
+				return token
+			}
+		}
+		return ""
+	}
+
+	return result.Token
+}
+
+// getEmailUnsafe retrieves the email without acquiring locks.
+func (sd *SessionData) getEmailUnsafe() string {
+	email, _ := sd.mainSession.Values["email"].(string)
+	return email
+}
+
+// getCSRFUnsafe retrieves the CSRF token without acquiring locks.
+func (sd *SessionData) getCSRFUnsafe() string {
+	csrf, _ := sd.mainSession.Values["csrf"].(string)
+	return csrf
+}
+
+// getNonceUnsafe retrieves the nonce without acquiring locks.
+func (sd *SessionData) getNonceUnsafe() string {
+	nonce, _ := sd.mainSession.Values["nonce"].(string)
+	return nonce
+}
+
+// getCodeVerifierUnsafe retrieves the code verifier without acquiring locks.
+func (sd *SessionData) getCodeVerifierUnsafe() string {
+	codeVerifier, _ := sd.mainSession.Values["code_verifier"].(string)
+	return codeVerifier
+}
+
+// getIncomingPathUnsafe retrieves the incoming path without acquiring locks.
+func (sd *SessionData) getIncomingPathUnsafe() string {
+	path, _ := sd.mainSession.Values["incoming_path"].(string)
+	return path
+}
+
+// getCreatedAtUnsafe retrieves the created_at timestamp without acquiring locks.
+func (sd *SessionData) getCreatedAtUnsafe() int64 {
+	createdAt, _ := sd.mainSession.Values["created_at"].(int64)
+	return createdAt
+}
+
+// getRedirectCountUnsafe retrieves the redirect count without acquiring locks.
+func (sd *SessionData) getRedirectCountUnsafe() int {
+	count, _ := sd.mainSession.Values["redirect_count"].(int)
+	return count
+}
+
 // SetIDToken stores an ID token with automatic compression and chunking.
 // It validates the JWT format, compresses if beneficial, and splits into chunks
 // if the token exceeds cookie size limits. Includes comprehensive validation.

session/chunking/chunk_manager.go

@@ -100,13 +100,12 @@ type Logger interface {
 // and error handling to ensure data integrity and prevent security vulnerabilities
 // throughout the process.
 type ChunkManager struct {
-	logger Logger
-	mutex  *sync.RWMutex
-	// sessionMap provides bounded session storage to prevent memory leaks
+	lastCleanup time.Time
+	logger      Logger
+	mutex       *sync.RWMutex
 	sessionMap  map[string]*SessionEntry
 	maxSessions int
 	sessionTTL  time.Duration
-	lastCleanup time.Time
 }
 
 // NewChunkManager creates a new ChunkManager instance with proper initialization.
@@ -361,8 +360,8 @@ func (cm *ChunkManager) StoreSession(key string, session *sessions.Session) {
 	if shouldEvict {
 		// Find oldest sessions to remove
 		type sessionAge struct {
-			key      string
 			lastUsed time.Time
+			key      string
 		}
 
 		sessions := make([]sessionAge, 0, currentLocal)

session/chunking/chunk_manager_test.go

@@ -16,7 +16,7 @@ func TestTokenValidatorJWT(t *testing.T) {
 	validator := NewTokenValidator()
 
 	// Test valid JWT format (using base64url encoded parts that are long enough)
-	validJWT := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+	validJWT := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" // trufflehog:ignore
 	err := validator.ValidateJWTFormat(validJWT, "test")
 	if err != nil {
 		t.Errorf("Expected valid JWT to pass, got error: %v", err)
@@ -186,10 +186,10 @@ func TestTokenConfigValidation(t *testing.T) {
 func TestSessionMapBounds_HardLimitEnforcement(t *testing.T) {
 	tests := []struct {
 		name           string
+		description    string
 		maxSessions    int
 		sessionCount   int
 		expectEviction bool
-		description    string
 	}{
 		{
 			name:           "within_limit",
@@ -760,18 +760,18 @@ func TestValidateJWTContent(t *testing.T) {
 	tests := []struct {
 		name        string
 		token       string
-		expectError bool
 		description string
+		expectError bool
 	}{
 		{
 			name:        "Valid JWT with required ID token claims",
-			token:       "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tIiwic3ViIjoiMTIzNDU2Nzg5MCIsImF1ZCI6ImNsaWVudElkIiwiZXhwIjoxNjQ2MDY0MDAwLCJpYXQiOjE2NDYwNjA0MDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+			token:       "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tIiwic3ViIjoiMTIzNDU2Nzg5MCIsImF1ZCI6ImNsaWVudElkIiwiZXhwIjoxNjQ2MDY0MDAwLCJpYXQiOjE2NDYwNjA0MDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", // trufflehog:ignore
 			expectError: false,
 			description: "JWT with all required ID token claims should pass",
 		},
 		{
 			name:        "JWT missing required claims",
-			token:       "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+			token:       "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", // trufflehog:ignore
 			expectError: true,
 			description: "JWT missing required claims should fail",
 		},
@@ -810,8 +810,8 @@ func TestValidateJWTHeader(t *testing.T) {
 	tests := []struct {
 		name        string
 		header      string
-		expectError bool
 		description string
+		expectError bool
 	}{
 		{
 			name:        "Valid JWT header",
@@ -865,9 +865,9 @@ func TestValidateJWTPayload(t *testing.T) {
 	tests := []struct {
 		name        string
 		payload     string
+		description string
 		config      TokenConfig
 		expectError bool
-		description string
 	}{
 		{
 			name:        "Valid ID token payload",
@@ -927,8 +927,8 @@ func TestValidateJWTSignature(t *testing.T) {
 	tests := []struct {
 		name        string
 		signature   string
-		expectError bool
 		description string
+		expectError bool
 	}{
 		{
 			name:        "Valid signature",
@@ -976,9 +976,9 @@ func TestValidateChunkStructure(t *testing.T) {
 
 	tests := []struct {
 		name        string
+		description string
 		chunks      []ChunkData
 		expectError bool
-		description string
 	}{
 		{
 			name: "Valid chunk structure",
@@ -1055,11 +1055,11 @@ func TestValidateChunkData(t *testing.T) {
 	config := AccessTokenConfig
 
 	tests := []struct {
-		name          string
 		chunk         ChunkData
+		name          string
+		description   string
 		expectedTotal int
 		expectError   bool
-		description   string
 	}{
 		{
 			name:          "Valid chunk data",
@@ -1218,13 +1218,13 @@ func TestGetToken(t *testing.T) {
 	cm := NewChunkManager(nil)
 
 	tests := []struct {
-		name          string
 		mainSession   *sessions.Session
 		chunks        map[int]*sessions.Session
-		config        TokenConfig
+		name          string
 		expectedToken string
-		expectError   bool
 		description   string
+		config        TokenConfig
+		expectError   bool
 	}{
 		{
 			name: "Token from main session",
@@ -1363,8 +1363,8 @@ func TestSerializeTokenToChunks(t *testing.T) {
 	tests := []struct {
 		name        string
 		token       string
-		expectError bool
 		description string
+		expectError bool
 	}{
 		{
 			name:        "Valid token serialization",
@@ -1436,10 +1436,10 @@ func TestDeserializeTokenFromChunks(t *testing.T) {
 
 	tests := []struct {
 		name          string
-		chunks        []ChunkData
 		expectedToken string
-		expectError   bool
 		description   string
+		chunks        []ChunkData
+		expectError   bool
 	}{
 		{
 			name:          "Valid chunks deserialization",
@@ -1522,10 +1522,10 @@ func TestEncodeDecodeChunk(t *testing.T) {
 	cs := NewChunkSerializer(NewNoOpLogger())
 
 	tests := []struct {
-		name        string
 		chunk       ChunkData
-		expectError bool
+		name        string
 		description string
+		expectError bool
 	}{
 		{
 			name: "Valid chunk encoding/decoding",
@@ -1619,10 +1619,10 @@ func TestValidateChunkIntegrity(t *testing.T) {
 	cs := NewChunkSerializer(NewNoOpLogger())
 
 	tests := []struct {
-		name        string
 		chunk       ChunkData
-		expectError bool
+		name        string
 		description string
+		expectError bool
 	}{
 		{
 			name: "Valid chunk integrity",

session/chunking/chunk_serializer.go

@@ -254,10 +254,10 @@ func (cs *ChunkSerializer) calculateChecksum(content string) string {
 
 // ChunkData represents a single chunk of token data
 type ChunkData struct {
-	Index    int    // Position of this chunk in the sequence
-	Total    int    // Total number of chunks for this token
-	Content  string // The actual chunk content
-	Checksum string // Simple checksum for integrity verification
+	Content  string
+	Checksum string
+	Index    int
+	Total    int
 }
 
 // EstimateChunkCount estimates how many chunks a token will need

session_chunk_manager.go

@@ -84,21 +84,19 @@ type TokenRetrievalResult struct {
 // and error handling to ensure data integrity and prevent security vulnerabilities
 // throughout the process.
 type ChunkManager struct {
-	logger *Logger
-	mutex  *sync.RWMutex
-	ctx    context.Context
-	cancel context.CancelFunc
-	wg     sync.WaitGroup // WaitGroup to track background goroutine completion
-	// sessionMap provides bounded session storage to prevent memory leaks
+	lastCleanup    time.Time
+	ctx            context.Context
+	mutex          *sync.RWMutex
+	cancel         context.CancelFunc
 	sessionMap     map[string]*SessionEntry
+	logger         *Logger
+	wg             sync.WaitGroup
 	maxSessions    int
 	sessionTTL     time.Duration
-	lastCleanup    time.Time
-	cleanupRunning int32 // atomic flag to prevent concurrent cleanups
-	// Memory usage tracking
 	bytesAllocated int64
 	peakSessions   int64
 	cleanupCount   int64
+	cleanupRunning int32
 }
 
 // SessionEntry represents a session with expiration tracking
@@ -393,7 +391,8 @@ func (cm *ChunkManager) processChunkedToken(chunks map[int]*sessions.Session, co
 			return TokenRetrievalResult{Token: "", Error: err}
 		}
 
-		if len(chunk) > maxBrowserCookieSize {
+		// Secondary check: ensure chunk won't exceed browser limit after encoding (~2x overhead)
+		if len(chunk) > maxCookieSize*2 {
 			err := fmt.Errorf("%s token chunk %d exceeds browser limit (%d bytes)",
 				config.Type, i, len(chunk))
 			return TokenRetrievalResult{Token: "", Error: err}
@@ -1199,8 +1198,8 @@ func (cm *ChunkManager) findOldestSessions(k int) []string {
 
 	// Collect all timestamps with keys
 	type sessionAge struct {
-		key      string
 		lastUsed time.Time
+		key      string
 	}
 
 	sessions := make([]sessionAge, 0, len(cm.sessionMap))

session_test.go

@@ -24,31 +24,31 @@ import (
 
 // SessionTestCase represents a comprehensive session test scenario
 type SessionTestCase struct {
-	name        string
-	scenario    string // "creation", "validation", "expiration", "persistence", "cleanup", "chunking", "security"
-	sessionType string // "user", "admin", "api", "guest", "csrf"
 	setup       func(*SessionTestFramework)
 	execute     func(*SessionTestFramework) error
 	validate    func(*testing.T, error, *SessionTestFramework)
 	cleanup     func(*SessionTestFramework)
-	concurrent  bool
+	name        string
+	scenario    string
+	sessionType string
+	skipReason  string
 	iterations  int
 	timeout     time.Duration
-	skipReason  string
+	concurrent  bool
 }
 
 // SessionTestFramework provides shared test infrastructure for session tests
 type SessionTestFramework struct {
 	t            *testing.T
 	mockProvider *httptest.Server
+	testTokens   map[string]string
+	metrics      *SessionTestMetrics
+	config       *SessionTestConfig
 	requests     []*http.Request
 	responses    []*httptest.ResponseRecorder
-	testTokens   map[string]string
 	sessionIDs   []string
-	mu           sync.RWMutex
-	metrics      *SessionTestMetrics
 	cleanupFuncs []func()
-	config       *SessionTestConfig
+	mu           sync.RWMutex
 }
 
 // SessionTestMetrics tracks test performance metrics
@@ -65,12 +65,12 @@ type SessionTestMetrics struct {
 
 // SessionTestConfig holds test configuration
 type SessionTestConfig struct {
+	CookieDomain      string
+	EncryptionKey     string
 	MaxChunkSize      int
 	MaxSessions       int
-	EnableHTTPS       bool
-	CookieDomain      string
 	SessionTimeout    time.Duration
-	EncryptionKey     string
+	EnableHTTPS       bool
 	EnableCompression bool
 }
 
@@ -2849,9 +2849,9 @@ func TestSessionExpiryVsTokenExpiry(t *testing.T) {
 
 	scenarios := []struct {
 		name                string
+		expectedBehavior    string
 		sessionAge          time.Duration
 		tokenExpiry         time.Duration
-		expectedBehavior    string
 		sessionShouldExpire bool
 		tokenShouldRefresh  bool
 	}{
@@ -2975,10 +2975,10 @@ func TestSessionCleanupOnTokenExpiry(t *testing.T) {
 
 	scenarios := []struct {
 		name           string
-		tokenExpiry    time.Duration
-		shouldCleanup  bool
 		shouldPreserve []string
 		shouldRemove   []string
+		tokenExpiry    time.Duration
+		shouldCleanup  bool
 	}{
 		{
 			name:           "Recently expired tokens - preserve session",