backport: implement LRU cache with invocation ID scoping for minimal mode response cache (#89122)

Backports:
- #88509

Co-authored-by: Wyatt Johnson <accounts+github@wyattjoh.ca>

Author: ztanner

packages/next/src/server/lib/lru-cache.test.ts

@@ -226,4 +226,75 @@ describe('LRUCache', () => {
       expect(cache.has('key149')).toBe(true) // recent keys retained
     })
   })
+
+  describe('onEvict Callback', () => {
+    it('should call onEvict when an entry is evicted', () => {
+      const evicted: Array<{ key: string; value: string }> = []
+      const cache = new LRUCache<string>(2, undefined, (key, value) => {
+        evicted.push({ key, value })
+      })
+
+      cache.set('a', 'value-a')
+      cache.set('b', 'value-b')
+      expect(evicted.length).toBe(0)
+
+      cache.set('c', 'value-c') // should evict 'a'
+      expect(evicted.length).toBe(1)
+      expect(evicted[0]).toEqual({ key: 'a', value: 'value-a' })
+    })
+
+    it('should not call onEvict when updating existing entry', () => {
+      const evicted: string[] = []
+      const cache = new LRUCache<string>(2, undefined, (key) => {
+        evicted.push(key)
+      })
+
+      cache.set('a', 'value-a')
+      cache.set('a', 'new-value-a')
+      expect(evicted.length).toBe(0)
+    })
+
+    it('should call onEvict for each evicted entry when multiple are evicted', () => {
+      const evicted: string[] = []
+      const cache = new LRUCache<string>(
+        10,
+        (value) => value.length,
+        (key) => {
+          evicted.push(key)
+        }
+      )
+
+      cache.set('key1', 'ab') // size 2
+      cache.set('key2', 'cd') // size 2
+      cache.set('key3', 'ef') // size 2, total = 6
+      cache.set('key4', 'ghijklmno') // size 9, should evict key1, key2, key3
+
+      expect(evicted).toEqual(['key1', 'key2', 'key3'])
+    })
+
+    it('should work without onEvict callback', () => {
+      const cache = new LRUCache<string>(2)
+      cache.set('a', 'value-a')
+      cache.set('b', 'value-b')
+      cache.set('c', 'value-c') // should evict without error
+      expect(cache.has('a')).toBe(false)
+    })
+
+    it('should pass the evicted value to the callback', () => {
+      const evicted: Array<{ id: number }> = []
+      const cache = new LRUCache<{ id: number }>(
+        1,
+        undefined,
+        (_key, value) => {
+          evicted.push(value)
+        }
+      )
+
+      cache.set('obj1', { id: 1 })
+      cache.set('obj2', { id: 2 }) // should evict obj1
+
+      expect(evicted.length).toBe(1)
+      expect(evicted[0]).toEqual({ id: 1 })
+    })
+  })
 })

packages/next/src/server/lib/lru-cache.ts

@@ -50,10 +50,16 @@ export class LRUCache<T> {
   private totalSize: number = 0
   private readonly maxSize: number
   private readonly calculateSize: ((value: T) => number) | undefined
+  private readonly onEvict: ((key: string, value: T) => void) | undefined
 
-  constructor(maxSize: number, calculateSize?: (value: T) => number) {
+  constructor(
+    maxSize: number,
+    calculateSize?: (value: T) => number,
+    onEvict?: (key: string, value: T) => void
+  ) {
     this.maxSize = maxSize
     this.calculateSize = calculateSize
+    this.onEvict = onEvict
 
     // Create sentinel nodes to simplify doubly-linked list operations
     // HEAD <-> TAIL (empty list)
@@ -144,6 +150,7 @@ export class LRUCache<T> {
       const tail = this.removeTail()
       this.cache.delete(tail.key)
       this.totalSize -= tail.size
+      this.onEvict?.(tail.key, tail.data)
     }
   }
 
@@ -191,6 +198,10 @@ export class LRUCache<T> {
    * Removes a specific key from the cache.
    * Updates both the hash map and doubly-linked list.
    *
+   * Note: This is an explicit removal and does NOT trigger the `onEvict`
+   * callback. Use this for intentional deletions where eviction tracking
+   * is not needed.
+   *
    * Time Complexity: O(1)
    */
   public remove(key: string): void {