Skip to content

Commit e59db59

Browse files
authored
feat(cache): key cache entries by configured vary headers (#4915)
1 parent 48a7ccb commit e59db59

2 files changed

Lines changed: 227 additions & 41 deletions

File tree

‎src/middleware/cache/index.test.ts‎

Lines changed: 184 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,24 @@ describe('Cache Middleware', () => {
379379
})
380380

381381
describe('Cache Skipping Logic', () => {
382+
const stubStoreBackedCache = () => {
383+
const store = new Map<string | Request, Response>()
384+
const mockCache = {
385+
match: vi.fn((key: string | Request) => Promise.resolve(store.get(key)?.clone())),
386+
put: vi.fn((key: string | Request, response: Response) => {
387+
store.set(key, response.clone())
388+
return Promise.resolve()
389+
}),
390+
keys: vi.fn(() => Promise.resolve(Array.from(store.keys()))),
391+
}
392+
393+
vi.stubGlobal('caches', {
394+
open: vi.fn().mockResolvedValue(mockCache),
395+
})
396+
397+
return { mockCache }
398+
}
399+
382400
let putSpy: ReturnType<typeof vi.fn>
383401
let matchSpy: ReturnType<typeof vi.fn>
384402

@@ -477,7 +495,8 @@ describe('Cache Skipping Logic', () => {
477495
}
478496
)
479497

480-
it('Should set configured Vary header but not cache the response', async () => {
498+
it('Should set configured Vary header and cache by the configured request header value', async () => {
499+
const { mockCache } = stubStoreBackedCache()
481500
const app = new Hono()
482501
let count = 0
483502
app.use('*', cache({ cacheName: 'skip-test', wait: true, vary: 'Accept' }))
@@ -490,7 +509,170 @@ describe('Cache Skipping Logic', () => {
490509
await app.request('/')
491510
const res = await app.request('/')
492511
expect(res.headers.get('Vary')).toBe('accept')
493-
expect(res.headers.get('X-Count')).toBe('2')
512+
expect(res.headers.get('X-Count')).toBe('1')
513+
expect(mockCache.put).toHaveBeenCalledOnce()
514+
})
515+
516+
it('Should store separate variants for different Accept-Language request values', async () => {
517+
const { mockCache } = stubStoreBackedCache()
518+
const app = new Hono()
519+
let count = 0
520+
app.use('*', cache({ cacheName: 'vary-language-test', wait: true, vary: 'Accept-Language' }))
521+
app.get('/', (c) => {
522+
count++
523+
c.header('X-Count', `${count}`)
524+
return c.text(c.req.header('Accept-Language') ?? 'missing')
525+
})
526+
527+
await app.request('/', {
528+
headers: {
529+
'Accept-Language': 'en',
530+
},
531+
})
532+
const en = await app.request('/', {
533+
headers: {
534+
'Accept-Language': 'en',
535+
},
536+
})
537+
await app.request('/', {
538+
headers: {
539+
'Accept-Language': 'ja',
540+
},
541+
})
542+
const ja = await app.request('/', {
543+
headers: {
544+
'Accept-Language': 'ja',
545+
},
546+
})
547+
548+
expect(await en.text()).toBe('en')
549+
expect(en.headers.get('X-Count')).toBe('1')
550+
expect(await ja.text()).toBe('ja')
551+
expect(ja.headers.get('X-Count')).toBe('2')
552+
expect(mockCache.put).toHaveBeenCalledTimes(2)
553+
})
554+
555+
it('Should keep missing and present Vary request header values in separate variants', async () => {
556+
stubStoreBackedCache()
557+
const app = new Hono()
558+
let count = 0
559+
app.use('*', cache({ cacheName: 'vary-missing-test', wait: true, vary: 'Accept-Language' }))
560+
app.get('/', (c) => {
561+
count++
562+
c.header('X-Count', `${count}`)
563+
return c.text(c.req.header('Accept-Language') ?? 'missing')
564+
})
565+
566+
await app.request('/')
567+
await app.request('/', {
568+
headers: {
569+
'Accept-Language': 'en',
570+
},
571+
})
572+
const missing = await app.request('/')
573+
const present = await app.request('/', {
574+
headers: {
575+
'Accept-Language': 'en',
576+
},
577+
})
578+
579+
expect(await missing.text()).toBe('missing')
580+
expect(missing.headers.get('X-Count')).toBe('1')
581+
expect(await present.text()).toBe('en')
582+
expect(present.headers.get('X-Count')).toBe('2')
583+
})
584+
585+
it('Should store separate variants using multiple configured request headers', async () => {
586+
const { mockCache } = stubStoreBackedCache()
587+
const app = new Hono()
588+
let count = 0
589+
app.use(
590+
'*',
591+
cache({ cacheName: 'vary-multiple-test', wait: true, vary: ['Accept', 'Accept-Encoding'] })
592+
)
593+
app.get('/', (c) => {
594+
count++
595+
c.header('X-Count', `${count}`)
596+
return c.text(`${c.req.header('Accept')}:${c.req.header('Accept-Encoding')}`)
597+
})
598+
599+
await app.request('/', {
600+
headers: {
601+
Accept: 'text/plain',
602+
'Accept-Encoding': 'gzip',
603+
},
604+
})
605+
const same = await app.request('/', {
606+
headers: {
607+
Accept: 'text/plain',
608+
'Accept-Encoding': 'gzip',
609+
},
610+
})
611+
await app.request('/', {
612+
headers: {
613+
Accept: 'application/json',
614+
'Accept-Encoding': 'gzip',
615+
},
616+
})
617+
const differentAccept = await app.request('/', {
618+
headers: {
619+
Accept: 'application/json',
620+
'Accept-Encoding': 'gzip',
621+
},
622+
})
623+
await app.request('/', {
624+
headers: {
625+
Accept: 'text/plain',
626+
'Accept-Encoding': 'br',
627+
},
628+
})
629+
const differentEncoding = await app.request('/', {
630+
headers: {
631+
Accept: 'text/plain',
632+
'Accept-Encoding': 'br',
633+
},
634+
})
635+
636+
expect(same.headers.get('X-Count')).toBe('1')
637+
expect(differentAccept.headers.get('X-Count')).toBe('2')
638+
expect(differentEncoding.headers.get('X-Count')).toBe('3')
639+
expect(mockCache.put).toHaveBeenCalledTimes(3)
640+
})
641+
642+
it('Should store when the handler Vary header is covered by configured Vary headers', async () => {
643+
const { mockCache } = stubStoreBackedCache()
644+
const app = new Hono()
645+
app.use('*', cache({ cacheName: 'vary-covered-test', wait: true, vary: 'Accept-Language' }))
646+
app.get('/', (c) => {
647+
c.header('Vary', 'Accept-Language')
648+
return c.text('response')
649+
})
650+
651+
await app.request('/')
652+
expect(mockCache.put).toHaveBeenCalledOnce()
653+
})
654+
655+
it('Should not store when the handler adds Vary headers not covered by configured Vary headers', async () => {
656+
const app = new Hono()
657+
app.use('*', cache({ cacheName: 'skip-test', wait: true, vary: 'Accept-Language' }))
658+
app.get('/', (c) => {
659+
c.header('Vary', 'Accept-Language, Cookie')
660+
return c.text('response')
661+
})
662+
663+
await app.request('/')
664+
expect(putSpy).not.toHaveBeenCalled()
665+
})
666+
667+
it('Should not store Vary: * responses even when Vary headers are configured', async () => {
668+
const app = new Hono()
669+
app.use('*', cache({ cacheName: 'skip-test', wait: true, vary: 'Accept-Language' }))
670+
app.get('/', (c) => {
671+
c.header('Vary', '*')
672+
return c.text('response')
673+
})
674+
675+
await app.request('/')
494676
expect(putSpy).not.toHaveBeenCalled()
495677
})
496678

‎src/middleware/cache/index.ts‎

Lines changed: 43 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -12,26 +12,28 @@ import type { StatusCode } from '../../utils/http-status'
1212
*/
1313
const defaultCacheableStatusCodes: ReadonlyArray<StatusCode> = [200]
1414

15-
const shouldSkipCache = (res: Response) => {
16-
if (res.headers.has('Vary')) {
17-
return true
18-
}
19-
20-
const cacheControl = res.headers.get('Cache-Control')
21-
if (
22-
cacheControl &&
23-
/(?:^|,\s*)(?:private|no-(?:store|cache))(?:\s*(?:=|,|$))/i.test(cacheControl)
24-
) {
25-
return true
26-
}
15+
const shouldSkipCacheControl = (cacheControl: string | null): boolean =>
16+
!!cacheControl && /(?:^|,\s*)(?:private|no-(?:store|cache))(?:\s*(?:=|,|$))/i.test(cacheControl)
2717

28-
if (res.headers.has('Set-Cookie')) {
29-
return true
18+
const parseVaryDirectives = (vary: string | string[] | null | undefined): string[] => {
19+
if (vary == null) {
20+
return []
3021
}
31-
32-
return false
22+
return (Array.isArray(vary) ? vary : vary.split(','))
23+
.map((directive) => directive.trim().toLowerCase())
24+
.filter(Boolean)
3325
}
3426

27+
const shouldSkipCache = (
28+
res: Response,
29+
optionsVaryDirectives: Set<string> | undefined,
30+
responseVary: string[]
31+
): boolean =>
32+
(responseVary.length &&
33+
(!optionsVaryDirectives || responseVary.some((name) => !optionsVaryDirectives.has(name)))) ||
34+
shouldSkipCacheControl(res.headers.get('Cache-Control')) ||
35+
res.headers.has('Set-Cookie')
36+
3537
/**
3638
* Cache Middleware for Hono.
3739
*
@@ -41,7 +43,7 @@ const shouldSkipCache = (res: Response) => {
4143
* @param {string | Function} options.cacheName - The name of the cache. Can be used to store multiple caches with different identifiers.
4244
* @param {boolean} [options.wait=false] - A boolean indicating if Hono should wait for the Promise of the `cache.put` function to resolve before continuing with the request. Required to be true for the Deno environment.
4345
* @param {string} [options.cacheControl] - A string of directives for the `Cache-Control` header.
44-
* @param {string | string[]} [options.vary] - Sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates.
46+
* @param {string | string[]} [options.vary] - Adds the configured request headers to the cache key variants and sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates.
4547
* @param {Function} [options.keyGenerator] - Generates keys for every request in the `cacheName` store. This can be used to cache data based on request parameters or context parameters.
4648
* @param {number[]} [options.cacheableStatusCodes=[200]] - An array of status codes that can be cached.
4749
* @param {Function | false} [options.onCacheNotAvailable] - A callback invoked when `globalThis.caches` is not available. By default, a message is logged to the console. Set to `false` to suppress the log, or provide a custom function.
@@ -86,12 +88,11 @@ export const cache = (options: {
8688
const cacheControlDirectives = options.cacheControl
8789
?.split(',')
8890
.map((directive) => directive.toLowerCase())
89-
const varyDirectives = Array.isArray(options.vary)
90-
? options.vary
91-
: options.vary?.split(',').map((directive) => directive.trim())
91+
const optionsVaryList = parseVaryDirectives(options.vary)
92+
const varyDirectives = optionsVaryList.length ? new Set(optionsVaryList) : undefined
9293
// RFC 7231 Section 7.1.4 specifies that "*" is not allowed in Vary header.
9394
// See: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.4
94-
if (options.vary?.includes('*')) {
95+
if (varyDirectives?.has('*')) {
9596
throw new Error(
9697
'Middleware vary configuration cannot include "*", as it disallows effective caching.'
9798
)
@@ -101,7 +102,7 @@ export const cache = (options: {
101102
options.cacheableStatusCodes ?? defaultCacheableStatusCodes
102103
)
103104

104-
const addHeader = (c: Context) => {
105+
const addHeader = (c: Context, responseVary: string[]) => {
105106
if (cacheControlDirectives) {
106107
const existingDirectives =
107108
c.res.headers
@@ -118,22 +119,18 @@ export const cache = (options: {
118119
}
119120

120121
if (varyDirectives) {
121-
const existingDirectives =
122-
c.res.headers
123-
.get('Vary')
124-
?.split(',')
125-
.map((d) => d.trim()) ?? []
126-
127-
const vary = Array.from(
128-
new Set(
129-
[...existingDirectives, ...varyDirectives].map((directive) => directive.toLowerCase())
130-
)
131-
).sort()
132-
133-
if (vary.includes('*')) {
134-
c.header('Vary', '*')
122+
if (responseVary.length === 0) {
123+
c.header('Vary', Array.from(varyDirectives).join(', '))
135124
} else {
136-
c.header('Vary', vary.join(', '))
125+
const merged = new Set(varyDirectives)
126+
for (const directive of responseVary) {
127+
merged.add(directive)
128+
}
129+
if (merged.has('*')) {
130+
c.header('Vary', '*')
131+
} else {
132+
c.header('Vary', Array.from(merged).join(', '))
133+
}
137134
}
138135
}
139136
}
@@ -148,6 +145,12 @@ export const cache = (options: {
148145
if (options.keyGenerator) {
149146
key = await options.keyGenerator(c)
150147
}
148+
if (varyDirectives) {
149+
for (const directive of varyDirectives) {
150+
const value = c.req.raw.headers.get(directive) ?? ''
151+
key += `::${directive}=${encodeURIComponent(value)}`
152+
}
153+
}
151154

152155
const cacheName =
153156
typeof options.cacheName === 'function' ? await options.cacheName(c) : options.cacheName
@@ -161,9 +164,10 @@ export const cache = (options: {
161164
if (!cacheableStatusCodes.has(c.res.status)) {
162165
return
163166
}
164-
addHeader(c)
167+
const responseVary = parseVaryDirectives(c.res.headers.get('Vary'))
168+
addHeader(c, responseVary)
165169

166-
if (shouldSkipCache(c.res)) {
170+
if (shouldSkipCache(c.res, varyDirectives, responseVary)) {
167171
return
168172
}
169173

0 commit comments

Comments
 (0)