Skip to content

Commit 9dbb357

Browse files
authored
[backport] Encode the cache item name built by unstable_cache (#97313)
Backports #96936 ("[refactor] Rename `encodeCacheTag` to `encodeHeaderSafe`") and #96937 ("Encode the cache item name built by `unstable_cache`") to `next-16-3`. Fixes #76286. A cache implementation may serialize cache metadata into HTTP request headers, whose values are limited to Latin-1. `unstable_cache` assembles a cache item name from the request URL and the name of the cached callback, and neither part was encoded. When that name holds a character above U+00FF the conversion throws before the request is dispatched, so the read never reaches the cache and the write that follows it fails the same way. Nothing is stored, nothing is found, and the entry falls back to the origin on every render. The reachable case is a non-ASCII query parameter on any dynamic route that calls `unstable_cache`, whether or not the route reads `searchParams`, because `URLSearchParams` returns decoded keys and values while the pathname stays percent-encoded. The rename is folded in because it is the prerequisite: #96937 imports `encodeHeaderSafe` from `server/lib/encode-header-safe`, which the rename creates. It carries no behavior change, the function body is identical apart from the parameter name, and the two were stacked in this same order on canary. ### Verification on this branch Cherry-picked from `1f0cd93b83` and `4286a42e2c` in that order, with no conflicts. `packages/next/src/server/web/spec-extension/unstable-cache.ts` is not byte-identical to canary, because the release branch predates the unrelated `willConsumerServerCache` change and keeps `workStore.isStaticGeneration` at those two call sites. The diff this backport applies to that file is exactly the encoding change and nothing else. Every other source file is byte-identical to canary, and no reference to the old `encodeCacheTag` name remains. Behavioral verification is left to CI on this branch; the change carries the `non-ascii-cache-item-name` end-to-end suite, which exercises a real cache handler. <!-- NEXT_JS_LLM -->
1 parent 323a17c commit 9dbb357

13 files changed

Lines changed: 344 additions & 47 deletions

File tree

‎packages/next/src/server/lib/encode-cache-tag.ts‎

Lines changed: 0 additions & 37 deletions
This file was deleted.
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/**
2+
* Percent-encode every character other than horizontal tab and printable ASCII
3+
* so a value can be safely serialized into an HTTP header.
4+
*
5+
* Node's `validateHeaderValue` and `fetch`'s ByteString conversion accept
6+
* different character ranges. Restricting values to `\t\x20-\x7e` produces a
7+
* conservative representation that both can serialize. Characters outside a
8+
* transport's accepted range (Hebrew, Arabic, Chinese, emoji, …) would
9+
* otherwise throw `ERR_INVALID_CHAR` or a `TypeError`, which crashes ISR or
10+
* fails a cache read on every affected request.
11+
*
12+
* Cache tags are encoded at the public boundaries — tag construction
13+
* (`getImplicitTags`, `validateTags`) and invalidation input
14+
* (`revalidatePath`, `revalidateTag`, `updateTag`) — so storage, comparison,
15+
* and the wire all see the same canonical form.
16+
*
17+
* The class is narrower than either transport accepts. Everything inside it
18+
* passes through byte-for-byte, including `,`, `/`, `%`, `[`, `]`, `_`, `-` and
19+
* `\t`, which preserves the comma-separated header format and the
20+
* dynamic-segment markers in derived tags (`_N_T_/[slug]/page`).
21+
*
22+
* Properties:
23+
* - Fast-path: input that already fits the class is returned unchanged. This
24+
* makes the encoder idempotent on already-encoded `%xx` sequences.
25+
* - Matches *runs* of out-of-class code units so surrogate pairs (e.g. an
26+
* emoji) are handed to `encodeURIComponent` as a complete code point — a
27+
* per-code-unit regex would split the pair and throw `URIError`.
28+
*/
29+
const OUT_OF_CLASS_CHAR = /[^\t\x20-\x7e]/
30+
const OUT_OF_CLASS_RUN = /[^\t\x20-\x7e]+/g
31+
32+
export function encodeHeaderSafe(value: string): string {
33+
return OUT_OF_CLASS_CHAR.test(value)
34+
? value.replace(OUT_OF_CLASS_RUN, (run) => encodeURIComponent(run))
35+
: value
36+
}

‎packages/next/src/server/lib/implicit-tags.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { NEXT_CACHE_IMPLICIT_TAG_ID } from '../../lib/constants'
22
import type { OpaqueFallbackRouteParams } from '../request/fallback-params'
33
import { getCacheHandlerEntries } from '../use-cache/handlers'
4-
import { encodeCacheTag } from './encode-cache-tag'
4+
import { encodeHeaderSafe } from './encode-header-safe'
55
import { createLazyResult, type LazyResult } from './lazy-result'
66

77
export interface ImplicitTags {
@@ -92,14 +92,14 @@ export async function getImplicitTags(
9292
// `x-next-cache-tags`. Idempotent on already-ASCII input.
9393
const derivedTags = getDerivedTags(page)
9494
for (let tag of derivedTags) {
95-
tag = encodeCacheTag(`${NEXT_CACHE_IMPLICIT_TAG_ID}${tag}`)
95+
tag = encodeHeaderSafe(`${NEXT_CACHE_IMPLICIT_TAG_ID}${tag}`)
9696
tags.add(tag)
9797
}
9898

9999
// Add the tags from the pathname. If the route has unknown params, we don't
100100
// want to add the pathname as a tag, as it will be invalid.
101101
if (pathname && (!fallbackRouteParams || fallbackRouteParams.size === 0)) {
102-
const tag = encodeCacheTag(`${NEXT_CACHE_IMPLICIT_TAG_ID}${pathname}`)
102+
const tag = encodeHeaderSafe(`${NEXT_CACHE_IMPLICIT_TAG_ID}${pathname}`)
103103
tags.add(tag)
104104
}
105105

‎packages/next/src/server/lib/patch-fetch.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ import {
3535
import { cloneResponse } from './clone-response'
3636
import type { IncrementalCache } from './incremental-cache'
3737
import { RenderStage } from '../app-render/staged-rendering'
38-
import { encodeCacheTag } from './encode-cache-tag'
38+
import { encodeHeaderSafe } from './encode-header-safe'
3939
import type { Span } from './trace/tracer'
4040

4141
const isEdgeRuntime = process.env.NEXT_RUNTIME === 'edge'
@@ -107,7 +107,7 @@ export function validateTags(tags: any[], description: string) {
107107
// Encode so a non-ASCII tag can be safely serialized into the
108108
// `x-next-cache-tags` HTTP header without tripping Node's header
109109
// validation. Length is checked on the raw input above.
110-
validTags.push(encodeCacheTag(tag))
110+
validTags.push(encodeHeaderSafe(tag))
111111
}
112112

113113
if (validTags.length > NEXT_CACHE_TAG_MAX_ITEMS) {

‎packages/next/src/server/web/spec-extension/revalidate.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616
ActionDidRevalidateStaticAndDynamic as ActionDidRevalidate,
1717
} from '../../../shared/lib/action-revalidation-kind'
1818
import { removeTrailingSlash } from '../../../shared/lib/router/utils/remove-trailing-slash'
19-
import { encodeCacheTag } from '../../lib/encode-cache-tag'
19+
import { encodeHeaderSafe } from '../../lib/encode-header-safe'
2020
import { validateAndNormalizeCacheLifeProfile } from '../../use-cache/cache-life-profile'
2121

2222
type CacheLifeConfig = {
@@ -40,7 +40,7 @@ export function revalidateTag(tag: string, profile: string | CacheLifeConfig) {
4040
} else if (typeof profile === 'object') {
4141
profile = validateAndNormalizeCacheLifeProfile(profile, { kind: 'inline' })
4242
}
43-
return revalidate([encodeCacheTag(tag)], `revalidateTag ${tag}`, profile)
43+
return revalidate([encodeHeaderSafe(tag)], `revalidateTag ${tag}`, profile)
4444
}
4545

4646
/**
@@ -62,7 +62,7 @@ export function updateTag(tag: string) {
6262
)
6363
}
6464
// updateTag uses immediate expiration (no profile) without deprecation warning
65-
return revalidate([encodeCacheTag(tag)], `updateTag ${tag}`, undefined)
65+
return revalidate([encodeHeaderSafe(tag)], `updateTag ${tag}`, undefined)
6666
}
6767

6868
/**
@@ -105,7 +105,7 @@ export function revalidatePath(originalPath: string, type?: 'layout' | 'page') {
105105
return
106106
}
107107

108-
let normalizedPath = `${NEXT_CACHE_IMPLICIT_TAG_ID}${encodeCacheTag(removeTrailingSlash(originalPath))}`
108+
let normalizedPath = `${NEXT_CACHE_IMPLICIT_TAG_ID}${encodeHeaderSafe(removeTrailingSlash(originalPath))}`
109109

110110
if (type) {
111111
normalizedPath += `${normalizedPath.endsWith('/') ? '' : '/'}${type}`

‎packages/next/src/server/web/spec-extension/unstable-cache.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import type { IncrementalCache } from '../../lib/incremental-cache'
22

33
import { CACHE_ONE_YEAR_SECONDS } from '../../../lib/constants'
44
import { validateRevalidate, validateTags } from '../../lib/patch-fetch'
5+
import { encodeHeaderSafe } from '../../lib/encode-header-safe'
56
import {
67
workAsyncStorage,
78
type WorkStore,
@@ -137,7 +138,20 @@ export function unstable_cache<T extends Callback>(
137138
const cacheKey =
138139
await incrementalCache.generateSimpleCacheKey(invocationKey)
139140
// $urlWithPath,$sortedQueryStringKeys,$hashOfEveryThingElse
140-
const fetchUrl = `unstable_cache ${fetchUrlPrefix} ${cb.name ? ` ${cb.name}` : cacheKey}`
141+
//
142+
// A cache implementation may serialize this name into an HTTP request
143+
// header, so it is encoded here. Both parts can carry a character above
144+
// U+00FF: the search parameters are decoded, and a JavaScript identifier
145+
// may hold one. The character class leaves the separating spaces and the
146+
// URL punctuation untouched, so the shape above is preserved.
147+
//
148+
// `toWellFormed` replaces lone surrogates, which `cb.name` can hold and
149+
// which `encodeURIComponent` rejects. The name identifies the call for
150+
// debug metrics, so a replacement character is an acceptable trade for
151+
// not failing the render.
152+
const fetchUrl = encodeHeaderSafe(
153+
`unstable_cache ${fetchUrlPrefix} ${cb.name ? ` ${cb.name}` : cacheKey}`.toWellFormed()
154+
)
141155
const fetchIdx =
142156
(workStore ? workStore.nextFetchId : noStoreFetchIdx) ?? 1
143157

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { unstable_cache } from 'next/cache'
2+
import { connection } from 'next/server'
3+
4+
// Returns a different value on every call, so a cache that is not working is
5+
// visible in the rendered output.
6+
const RANDOM_ENDPOINT = 'https://next-data-api-endpoint.vercel.app/api/random'
7+
8+
// The callback is anonymous, so the item name is the request URL plus a hash.
9+
// This route covers the part of the name that comes from the URL.
10+
const getConfiguration = unstable_cache(
11+
async () => {
12+
const res = await fetch(`${RANDOM_ENDPOINT}?unstable-cache`)
13+
14+
return (await res.text()).trim()
15+
},
16+
['configuration'],
17+
{ tags: ['ascii-tag'], revalidate: 3600 }
18+
)
19+
20+
// The fetch cache reaches the same cache layer, but derives its item name from
21+
// the request URL, which is already percent-encoded. It is a control: it has to
22+
// keep caching for the very request that breaks the entry above.
23+
async function getFetchedValue() {
24+
const res = await fetch(`${RANDOM_ENDPOINT}?fetch-cache`, {
25+
next: { revalidate: 3600, tags: ['ascii-fetch-tag'] },
26+
})
27+
28+
return (await res.text()).trim()
29+
}
30+
31+
export default async function Page() {
32+
// The item name only carries the request URL for a dynamic render. A
33+
// prerender uses the route pattern instead, which is always ASCII.
34+
//
35+
// The page never reads `searchParams`. The query string reaches the item name
36+
// through the request URL either way, so a dynamic route is affected by a
37+
// query it does not look at, and by one a caller appends to it.
38+
await connection()
39+
40+
return (
41+
<>
42+
<p id="cached">{await getConfiguration()}</p>
43+
<p id="fetched">{await getFetchedValue()}</p>
44+
</>
45+
)
46+
}
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import { ReactNode, Suspense } from 'react'
2+
export default function Root({ children }: { children: ReactNode }) {
3+
return (
4+
<html>
5+
<body>
6+
<Suspense fallback={<p>Loading...</p>}>{children}</Suspense>
7+
</body>
8+
</html>
9+
)
10+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { unstable_cache } from 'next/cache'
2+
import { connection } from 'next/server'
3+
4+
const RANDOM_ENDPOINT = 'https://next-data-api-endpoint.vercel.app/api/random'
5+
6+
// `encodeURIComponent` rejects a lone surrogate outright, so an item name
7+
// holding one fails the render rather than the cache read. That makes this a
8+
// stricter case than a name that is merely unrepresentable in a header.
9+
//
10+
// A lone surrogate cannot be written as an identifier, so the name is attached
11+
// through a computed key. The key is a string literal, which a bundler cannot
12+
// rename, so this route carries the constraint in every mode.
13+
const LONE_SURROGATE = '\uD800'
14+
15+
const getConfiguration = unstable_cache(
16+
{
17+
[LONE_SURROGATE]: async () => {
18+
const res = await fetch(`${RANDOM_ENDPOINT}?lone-surrogate`)
19+
20+
return (await res.text()).trim()
21+
},
22+
}[LONE_SURROGATE],
23+
['lone-surrogate'],
24+
{ revalidate: 3600 }
25+
)
26+
27+
export default async function Page() {
28+
await connection()
29+
30+
return <p id="cached">{await getConfiguration()}</p>
31+
}
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
import { unstable_cache } from 'next/cache'
2+
import { connection } from 'next/server'
3+
4+
const RANDOM_ENDPOINT = 'https://next-data-api-endpoint.vercel.app/api/random'
5+
6+
// A JavaScript identifier may hold characters above U+00FF, and a named
7+
// callback puts its name into the cache item name. This route is requested
8+
// under a pure ASCII URL, so the name is the only part of the item name that
9+
// can be unrepresentable, and a failure here points at nothing else.
10+
//
11+
// A production build renames the binding, so this route only carries the
12+
// constraint in development.
13+
const pobierzKonfigurację = async () => {
14+
const res = await fetch(`${RANDOM_ENDPOINT}?named-callback`)
15+
16+
return (await res.text()).trim()
17+
}
18+
19+
const getConfiguration = unstable_cache(
20+
pobierzKonfigurację,
21+
['named-configuration'],
22+
{ revalidate: 3600 }
23+
)
24+
25+
export default async function Page() {
26+
await connection()
27+
28+
return <p id="cached">{await getConfiguration()}</p>
29+
}

0 commit comments

Comments
 (0)