Unverified Commit 092458fd authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

feat: implement LRU cache with invocation ID scoping for minimal mode response cache (#88509)

## Summary

Implements an LRU cache with compound keys for the minimal mode response
cache to improve cache hit rates during parallel revalidation scenarios.

**Problem**: The previous single-entry cache (`previousCacheItem`) keyed
by pathname caused cache collisions when multiple concurrent invocations
(e.g., during ISR revalidation) accessed the same pathname. Each
invocation would overwrite the previous entry, leading to cache misses
and redundant work.

**Solution**: An LRU cache using compound keys (`pathname +
invocationID`) that allows multiple invocations to cache entries for the
same pathname independently:

```
Cache Key Structure
─────────────────────
/blog/post-1\0inv-abc  →  {entry, expiresAt}
/blog/post-1\0inv-def  →  {entry, expiresAt}
/blog/post-1\0__ttl__  →  {entry, expiresAt}  (TTL fallback)
/api/data\0inv-ghi     →  {entry, expiresAt}
```

### Cache Key Strategy

- **With `x-invocation-id` header**: Entries are keyed by invocation ID
for exact-match lookups (always a cache hit if the entry exists)
- **Without header (TTL fallback)**: Entries use a `__ttl__` sentinel
key and validate via expiration timestamp

### Configuration via Environment Variables

Cache sizing can be tuned via environment variables (using
`NEXT_PRIVATE_*` prefix for infrastructure-level settings):

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `NEXT_PRIVATE_RESPONSE_CACHE_MAX_SIZE` | 150 | Max entries in the LRU
cache |
| `NEXT_PRIVATE_RESPONSE_CACHE_TTL` | 10000 | TTL in ms for cache
entries (fallback validation) |

### LRU Cache Enhancement

Added an optional `onEvict` callback to `LRUCache` that fires when
entries are evicted due to capacity limits. This enables tracking
evicted invocation IDs for warning detection without introducing
timer-based cleanup.

### Eviction Warnings

When a cache entry is evicted and later accessed by the same invocation,
a warning is logged suggesting to increase
`NEXT_PRIVATE_RESPONSE_CACHE_MAX_SIZE`. This helps developers tune cache
sizes for their workload.

### Additional Changes

- Renamed header from `x-vercel-id` to `x-invocation-id` for clarity
- Added `withInvocationId()` test helper for cache testing

## Test Plan

- Existing response cache tests pass with updated header name
- Unit tests for `LRUCache` including `onEvict` callback behavior
- Updated standalone mode tests to use `withInvocationId()` helper
parent 4e8671cf
...@@ -226,4 +226,75 @@ describe('LRUCache', () => { ...@@ -226,4 +226,75 @@ describe('LRUCache', () => {
expect(cache.has('key149')).toBe(true) // recent keys retained 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 })
})
})
}) })
...@@ -50,10 +50,16 @@ export class LRUCache<T> { ...@@ -50,10 +50,16 @@ export class LRUCache<T> {
private totalSize: number = 0 private totalSize: number = 0
private readonly maxSize: number private readonly maxSize: number
private readonly calculateSize: ((value: T) => number) | undefined 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.maxSize = maxSize
this.calculateSize = calculateSize this.calculateSize = calculateSize
this.onEvict = onEvict
// Create sentinel nodes to simplify doubly-linked list operations // Create sentinel nodes to simplify doubly-linked list operations
// HEAD <-> TAIL (empty list) // HEAD <-> TAIL (empty list)
...@@ -144,6 +150,7 @@ export class LRUCache<T> { ...@@ -144,6 +150,7 @@ export class LRUCache<T> {
const tail = this.removeTail() const tail = this.removeTail()
this.cache.delete(tail.key) this.cache.delete(tail.key)
this.totalSize -= tail.size this.totalSize -= tail.size
this.onEvict?.(tail.key, tail.data)
} }
} }
...@@ -191,6 +198,10 @@ export class LRUCache<T> { ...@@ -191,6 +198,10 @@ export class LRUCache<T> {
* Removes a specific key from the cache. * Removes a specific key from the cache.
* Updates both the hash map and doubly-linked list. * 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) * Time Complexity: O(1)
*/ */
public remove(key: string): void { public remove(key: string): void {
......
...@@ -1018,6 +1018,9 @@ export abstract class RouteModule< ...@@ -1018,6 +1018,9 @@ export abstract class RouteModule<
isRoutePPREnabled, isRoutePPREnabled,
isOnDemandRevalidate, isOnDemandRevalidate,
isPrefetch: req.headers.purpose === 'prefetch', isPrefetch: req.headers.purpose === 'prefetch',
// Use x-invocation-id header to scope the in-memory cache to a single
// revalidation request in minimal mode.
invocationID: req.headers['x-invocation-id'] as string | undefined,
incrementalCache: await this.getIncrementalCache( incrementalCache: await this.getIncrementalCache(
req, req,
nextConfig, nextConfig,
......
...@@ -16,6 +16,7 @@ import { writeFile } from 'fs-extra' ...@@ -16,6 +16,7 @@ import { writeFile } from 'fs-extra'
import getPort from 'get-port' import getPort from 'get-port'
import { getRandomPort } from 'get-port-please' import { getRandomPort } from 'get-port-please'
import fetch from 'node-fetch' import fetch from 'node-fetch'
import { nanoid } from 'nanoid'
import qs from 'querystring' import qs from 'querystring'
import treeKill from 'tree-kill' import treeKill from 'tree-kill'
import { once } from 'events' import { once } from 'events'
...@@ -199,6 +200,37 @@ export function fetchViaHTTP( ...@@ -199,6 +200,37 @@ export function fetchViaHTTP(
return fetch(getFullUrl(appPort, url), opts) return fetch(getFullUrl(appPort, url), opts)
} }
/**
* Creates request options with a unique x-invocation-id header for testing
* cache deduplication in minimal mode. Use this when you need to ensure each
* request is treated as independent, or when multiple requests need to share
* the same invocation ID.
*
* @example
* // Independent requests (each gets its own invocation ID)
* const res1 = await fetchViaHTTP(appPort, '/page', undefined, withInvocationId())
* const res2 = await fetchViaHTTP(appPort, '/page', undefined, withInvocationId())
*
* @example
* // Grouped requests (share the same invocation ID for cache testing)
* const sharedOpts = withInvocationId()
* const res1 = await fetchViaHTTP(appPort, '/page', undefined, sharedOpts)
* const res2 = await fetchViaHTTP(appPort, '/_next/data/.../page.json', undefined, sharedOpts)
*
* @param opts - Optional existing RequestInit to merge with
* @returns RequestInit with x-invocation-id header added
*/
export function withInvocationId(opts?: RequestInit): RequestInit {
const invocationId = `test:${nanoid()}`
return {
...opts,
headers: {
...opts?.headers,
'x-invocation-id': invocationId,
},
}
}
export function renderViaHTTP( export function renderViaHTTP(
appPort: string | number, appPort: string | number,
pathname: string, pathname: string,
......
...@@ -96,7 +96,7 @@ describe('minimal-mode-response-cache', () => { ...@@ -96,7 +96,7 @@ describe('minimal-mode-response-cache', () => {
vary: 'rsc, next-router-state-tree, next-router-prefetch', vary: 'rsc, next-router-state-tree, next-router-prefetch',
'x-now-route-matches': '1=compare&rsc=1', 'x-now-route-matches': '1=compare&rsc=1',
'x-matched-path': '/app-blog/compare.rsc', 'x-matched-path': '/app-blog/compare.rsc',
'x-vercel-id': '1', 'x-invocation-id': '1',
rsc: '1', rsc: '1',
} }
const res1 = await fetchViaHTTP( const res1 = await fetchViaHTTP(
...@@ -126,7 +126,7 @@ describe('minimal-mode-response-cache', () => { ...@@ -126,7 +126,7 @@ describe('minimal-mode-response-cache', () => {
vary: 'rsc, next-router-state-tree, next-router-prefetch', vary: 'rsc, next-router-state-tree, next-router-prefetch',
'x-now-route-matches': '1=app-another&rsc=1', 'x-now-route-matches': '1=app-another&rsc=1',
'x-matched-path': '/app-another.rsc', 'x-matched-path': '/app-another.rsc',
'x-vercel-id': '1', 'x-invocation-id': '1',
rsc: '1', rsc: '1',
} }
const res1 = await fetchViaHTTP(appPort, '/app-another.rsc', undefined, { const res1 = await fetchViaHTTP(appPort, '/app-another.rsc', undefined, {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment