larry-dalmeida
diff --git a/‎docs/operation/operation.md‎
Lines changed: 34 additions & 0 deletions b/‎docs/operation/operation.md‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎docs/reference/filters.md‎
Lines changed: 0 additions & 32 deletions b/‎docs/reference/filters.md‎
Lines changed: 0 additions & 32 deletions
diff --git a/‎filters/cache/filter.go‎
Lines changed: 94 additions & 55 deletions b/‎filters/cache/filter.go‎
Lines changed: 94 additions & 55 deletions
@@ -1839,3 +1839,37 @@ will be changed to
 ```
 r: SourceFromLast("9.0.0.0/24","2001:67c:20a0::/48") -> ...`
 ```
+
+## Cache
+
+By default entries are stored in an in-process LRU (L1) local to each Skipper process.
+When `--swarm-valkey-urls` is configured, Valkey becomes the primary shared
+store (L2) accessible by all Skipper instances via a client-side consistent hash ring. Every
+read checks L1 first; an L1 hit returns without contacting Valkey.
+
+On every successful Valkey write the entry is also written to L1
+(write-through) with a TTL of `min(--cache-l1-ttl, entry.TTL)`. The default is
+60 seconds, bounding how long Skipper serves a locally-cached entry before
+falling back to Valkey. Set `--cache-l1-ttl=0` to disable L1 warming and
+restore write-around behaviour (L1 used only when Valkey is unavailable).
+
+Explicit deletes (unsafe methods or operator-initiated invalidation) always
+remove the L1 entry unconditionally, regardless of `--cache-l1-ttl`.
+
+!!! note
+    The in-process LRU (L1) is shared across all `cache()` filter instances in the same process.
+    When Valkey is configured it acts as a shared store (L2). The L1 storage budget is divided evenly
+    across 256 internal shards; a single entry larger than one shard's budget is
+    dropped with a warning log.
+
+### Metrics
+
+- `lru_eviction`: Counter, incremented each time an L1 entry is evicted due to memory pressure
+- `lru_bytes`: Gauge, current L1 usage in bytes
+- `lru_oversized`: Counter, incremented when an entry is too large for any shard and silently dropped
+
+When Valkey is configured:
+
+- `l1_hit`: Counter, L1 hits that bypassed Valkey
+- `valkey_miss`: Counter, Valkey misses that proceeded to an upstream fetch
+- `valkey_get_fallback`, `valkey_set_fallback`: Counters, reads/writes that fell back to L1 due to Valkey errors
@@ -3893,38 +3893,6 @@ matching the same key. It has no awareness of other filters in the chain.
 * **`Cache-Control: private` is ignored in force mode.** Audit the upstream
   response before enabling force mode on any authenticated route.
 
-**Storage**
-
-By default entries are stored in an in-process LRU (L1) local to each pod.
-When `--swarm-valkey-urls` is configured, Valkey becomes the primary shared
-store (L2) accessible by all pods via a client-side consistent hash ring. Every
-read checks L1 first; an L1 hit returns without contacting Valkey.
-
-On every successful Valkey write the entry is also written to L1
-(write-through) with a TTL of `min(--cache-l1-ttl, entry.TTL)`. The default is
-60 seconds, bounding how long a pod serves a locally-cached entry before
-falling back to Valkey. Set `--cache-l1-ttl=0` to disable L1 warming and
-restore write-around behaviour (L1 used only when Valkey is unavailable).
-
-Explicit deletes (unsafe methods or operator-initiated invalidation) always
-remove the L1 entry unconditionally, regardless of `--cache-l1-ttl`.
-
-!!! note
-    The in-process LRU (L1) is shared across all `cache()` filter instances on
-    the same pod but is local to that pod. When Valkey is configured it acts as
-    the cross-pod shared store (L2). The L1 storage budget is divided evenly
-    across 256 internal shards; a single entry larger than one shard's budget is
-    dropped with a warning log.
-
-!!! note
-    Metrics: `lru_eviction` (counter, incremented each time an L1 entry is
-    evicted due to memory pressure), `lru_bytes` (gauge, current L1 usage in
-    bytes), `lru_oversized` (counter, entry too large for any shard and
-    silently dropped). When Valkey is configured: `l1_hit` (counter, L1 hit
-    that bypassed Valkey), `valkey_miss` (counter, Valkey miss that proceeded
-    to an upstream fetch), `valkey_get_fallback` and `valkey_set_fallback`
-    (counters, reads/writes that fell back to L1 due to a Valkey error).
-
 !!! note
     `s-maxage` implies `proxy-revalidate` per [RFC 9111 §5.2.2.10](https://www.rfc-editor.org/rfc/rfc9111#section-5.2.2.10): stale entries
     stored under `s-maxage` are never served without revalidation, regardless of
 
@@ -42,17 +42,23 @@ const (
 	cacheStatusMiss   = "MISS"
 	cacheStatusStale  = "STALE"
 
-	// revalQueueSize is the capacity of the per-filter revalidation job queue.
+	// revalQueueSize is the capacity of the shared revalidation job queue.
 	// Sized to absorb short bursts; jobs are dropped (with reval_dropped metric)
 	// if the worker cannot keep up.
 	revalQueueSize = 256
 )
 
-// NewCacheFilter returns a Spec for the cache() filter. maxBytes is the
-// in-memory storage budget for the shared LRU cache backing all filter
-// instances created from this Spec.
-// listenAddr is Skipper's own listener address (e.g. ":9090"); revalidation
-// requests are sent back through Skipper so the full filter chain runs.
+// Options configures the cache filter. All fields are required unless stated otherwise.
+type Options struct {
+	MaxBytes   int64                    // in-memory storage budget for the LRU
+	ListenAddr string                   // Skipper's own listener address (e.g., ":9090")
+	NetOpts    skpnet.Options           // network options for revalidation requests
+	ValkeyRing *skpnet.ValkeyRingClient // optional L2 cache backend; nil = LRU only
+	L1TTL      time.Duration            // max TTL to use when warming L1 from Valkey writes
+	Metrics    metrics.Metrics          // optional; defaults to metrics.Default if nil
+}
+
+// NewCacheFilter returns a Spec for the cache() filter.
 //
 // Route usage (RFC mode — upstream Cache-Control is fully authoritative):
 //
@@ -65,38 +71,67 @@ const (
 // Combining force mode with stale-if-error:
 //
 //	-> cache("5m", "15s", "30s", "60s") -> "https://example.org"
-func NewCacheFilter(maxBytes int64, listenAddr string, netOpts skpnet.Options, valkeyRing *skpnet.ValkeyRingClient, l1TTL time.Duration) filters.Spec {
-	m := metrics.Default
-	lru := NewLRUStorage(maxBytes, func() {
+func NewCacheFilter(opts Options) filters.Spec {
+	if opts.Metrics == nil {
+		opts.Metrics = metrics.Default
+	}
+
+	m := opts.Metrics
+	lru := NewLRUStorage(opts.MaxBytes, func() {
 		m.IncCounter("lru_eviction")
 	}, m)
 
 	var store Storage = lru
-	if valkeyRing != nil {
-		store = NewValkeyStorage(valkeyRing, lru, m, l1TTL)
+	if opts.ValkeyRing != nil {
+		store = NewValkeyStorage(opts.ValkeyRing, lru, m, opts.L1TTL)
 	}
 
-	return &cacheSpec{
-		maxBytes:   maxBytes,
-		listenAddr: listenAddr,
-		client:     skpnet.NewClient(netOpts),
-		storage:    store,
-		lruStorage: lru,
-		metrics:    m,
+	spec := &cacheSpec{
+		maxBytes:     opts.MaxBytes,
+		listenAddr:   opts.ListenAddr,
+		client:       skpnet.NewClient(opts.NetOpts),
+		storage:      store,
+		lruStorage:   lru,
+		metrics:      m,
+		revalJobs:    make(chan revalJob, revalQueueSize),
+		lruBytesDone: make(chan struct{}),
 	}
+
+	// Start shared background goroutines (one worker + one scraper for all filter instances)
+	spec.bgWg.Add(2)
+	go spec.revalidationWorker()
+	go spec.lruBytesScraper()
+
+	return spec
 }
 
 type cacheSpec struct {
-	maxBytes   int64
-	listenAddr string
-	client     *skpnet.Client
-	storage    Storage     // shared across all filter instances
-	lruStorage *LRUStorage // always non-nil; direct reference to L1, even when storage is ValkeyStorage
-	metrics    metrics.Metrics
+	maxBytes     int64
+	listenAddr   string
+	client       *skpnet.Client
+	storage      Storage     // shared across all filter instances
+	lruStorage   *LRUStorage // always non-nil; direct reference to L1, even when storage is ValkeyStorage
+	metrics      metrics.Metrics
+	revalJobs    chan revalJob  // shared queue; one spec-level worker drains this
+	lruBytesDone chan struct{}  // closed to signal lruBytesScraper to stop
+	bgWg         sync.WaitGroup // tracks spec-level background goroutines
 }
 
 func (s *cacheSpec) Name() string { return filterName }
 
+// Close shuts down the background revalidation worker and lru_bytes scraper.
+// Safe to call multiple times; idempotent via a guard.
+func (s *cacheSpec) Close() {
+	select {
+	case <-s.lruBytesDone:
+		// Already closed; prevent panic on double-close.
+	default:
+		close(s.revalJobs)
+		close(s.lruBytesDone)
+		s.bgWg.Wait()
+	}
+}
+
 func (s *cacheSpec) CreateFilter(args []interface{}) (filters.Filter, error) {
 	if len(args) != 0 && (len(args) < 3 || len(args) > 5) {
 		return nil, fmt.Errorf("cache: expected 0 or 3-5 args (ttl, errorTTL, swrWindow[, staleIfError[, keyHeaders]]), got %d: %w", len(args), filters.ErrInvalidFilterParameters)
@@ -157,57 +192,50 @@ func (s *cacheSpec) CreateFilter(args []interface{}) (filters.Filter, error) {
 		rfcMode:      rfcMode,
 		metrics:      s.metrics,
 		keyHeaders:   keyHeaders,
-		revalJobs:    make(chan revalJob, revalQueueSize),
-		lruBytesDone: make(chan struct{}),
+		revalJobs:    s.revalJobs,    // use spec-level shared channel
+		lruBytesDone: s.lruBytesDone, // use spec-level shared signal
 	}
 
 	cf.fetch = s.client.Do
-	cf.bgWg.Add(2)
-	go cf.revalidationWorker()
-	go cf.lruBytesScraper()
 	return cf, nil
 }
 
-// Close shuts down the background revalidation worker and the lru_bytes scraper,
-// blocking until both goroutines have exited.
-func (f *cacheFilter) Close() {
-	close(f.revalJobs)
-	close(f.lruBytesDone)
-	f.bgWg.Wait()
-}
-
-// revalidationWorker is the single background goroutine per filter that
-// processes revalidation jobs sequentially. It exits when revalJobs is closed.
-func (f *cacheFilter) revalidationWorker() {
-	defer f.bgWg.Done()
-	for job := range f.revalJobs {
-		f.doRevalidate(job.key, job.req)
+// revalidationWorker is the single background goroutine (spec-level, shared across
+// all filter instances) that processes revalidation jobs sequentially. It calls
+// the per-instance doRevalidateFn closure to respect each route's configuration.
+func (s *cacheSpec) revalidationWorker() {
+	defer s.bgWg.Done()
+	for job := range s.revalJobs {
+		if job.doRevalFn != nil {
+			job.doRevalFn()
+		}
 	}
 	log.Debug("cache: revalidation worker stopped")
 }
 
 const lruBytesScrapeInterval = 10 * time.Second
 
 // lruBytesScraper periodically updates the lru_bytes gauge so it stays current
-// even when no evictions occur (large Sets without exceeding capacity never
-// trigger the onEvict callback). It exits when lruBytesDone is closed.
-func (f *cacheFilter) lruBytesScraper() {
-	defer f.bgWg.Done()
+// even when no evictions occur. It's spec-level and shared across all filter instances.
+// It exits when lruBytesDone is closed (via cacheSpec.Close).
+func (s *cacheSpec) lruBytesScraper() {
+	defer s.bgWg.Done()
 	ticker := time.NewTicker(lruBytesScrapeInterval)
 	defer ticker.Stop()
 	for {
 		select {
 		case <-ticker.C:
-			f.metrics.UpdateGauge("lru_bytes", float64(f.lruStorage.lru.Bytes()))
-		case <-f.lruBytesDone:
+			s.metrics.UpdateGauge("lru_bytes", float64(s.lruStorage.lru.Bytes()))
+		case <-s.lruBytesDone:
 			return
 		}
 	}
 }
 
 type revalJob struct {
-	key string
-	req *http.Request // pre-cloned, safe to use after the originating request ends
+	key       string
+	req       *http.Request // pre-cloned, safe to use after the originating request ends
+	doRevalFn func()        // closure with access to per-instance doRevalidate
 }
 
 type cacheFilter struct {
@@ -225,13 +253,16 @@ type cacheFilter struct {
 	rfcMode      bool
 	coldSF       singleflight.Group // cold-miss coalescing
 	revalSF      singleflight.Group // coalesces concurrent background revalidations per key
-	revalJobs    chan revalJob      // background revalidation queue; worker drains this
-	lruBytesDone chan struct{}      // closed by Close() to stop the lruBytesScraper goroutine
-	bgWg         sync.WaitGroup     // tracks background goroutines; Wait()ed in Close()
+	revalJobs    chan revalJob      // shared background revalidation queue from cacheSpec
+	lruBytesDone chan struct{}      // shared channel from cacheSpec; closed to stop scraper
 	fetch        func(*http.Request) (*http.Response, error)
 	metrics      metrics.Metrics
 }
 
+// Close is a no-op on individual filter instances; the real Close is on cacheSpec.
+// This exists for test compatibility.
+func (f *cacheFilter) Close() {}
+
 // tagSpan sets cache_status, cache_key, and (when >= 0) cache_ttl_remaining_ms
 // on the active OpenTracing span. No-op when no span is present.
 func tagSpan(ctx filters.FilterContext, status, key string, ttlRemainingMs int64) {
@@ -669,10 +700,18 @@ func (f *cacheFilter) Response(ctx filters.FilterContext) {
 // enqueueRevalidation sends a revalidation job to the background worker.
 // The request is cloned in the calling goroutine before orig is released.
 // If the queue is full the job is dropped and reval_dropped is incremented.
+// The closure captures f.doRevalidate so the spec-level worker respects this route's config.
 func (f *cacheFilter) enqueueRevalidation(key string, orig *http.Request) {
 	cloned := orig.Clone(context.Background())
+	job := revalJob{
+		key: key,
+		req: cloned,
+		doRevalFn: func() {
+			f.doRevalidate(key, cloned)
+		},
+	}
 	select {
-	case f.revalJobs <- revalJob{key: key, req: cloned}:
+	case f.revalJobs <- job:
 	default:
 		f.metrics.IncCounter("reval_dropped")
 	}