Unverified Commit e194a065 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Fix local fonts in statically prerendered `ImageResponse` metadata route (#95121)

Follow-up to #94957, which made cached `ImageResponse` routes statically
prerenderable by serializing the constructor arguments through React
Flight (to build a cache key and to run the element's async Server
Components once). A custom font passed as a `Buffer` in the options was
corrupted by that round-trip: Flight applies the `toJSON` method that
Node's `Buffer` carries, so the font reached satori as a `{ type:
'Buffer', data: [...] }` plain object rather than binary, and satori's
font parser threw `TypeError: First argument to DataView constructor
must be an ArrayBuffer`. The crash happened even without a user `'use
cache'` directive, because the serialization runs unconditionally during
the prerender.

We now serialize only the element through Flight, which is the only part
that needs async resolution and dynamic-input detection, and pair the
resolved element with the original in-memory options when handing the
tree to satori. The font `Buffer` is therefore never serialized and
reaches satori intact. The cache key no longer comes from the serialized
arguments either; it is derived from a SHA-256 hash of the serialized
element combined with a content hash of the options, with binary font
data hashed by its bytes and everything else by a sorted, type-tagged
walk. Besides fixing the crash, this keeps font bytes out of the cache
key and removes the "Uint8Array objects are not supported" warning that
the dev React runtime emitted during `next build --debug-prerender`.

The custom-fonts documentation example now loads the font once at module
scope. This keeps the route statically generated, since reading inside
the component would be uncached I/O that Cache Components treats as
dynamic, and it steers users away from wrapping the read in `'use
cache'`, which would route the font `Buffer` through use-cache's own
Flight serialization and reintroduce the same corruption upstream of
`ImageResponse`, where this fix cannot reach it. A regression test loads
a local font via a module-scope `readFile` and asserts the route
prerenders statically.
parent 37dfdce5
...@@ -174,13 +174,15 @@ export const size = { ...@@ -174,13 +174,15 @@ export const size = {
export const contentType = 'image/png' export const contentType = 'image/png'
// Load the font once at module scope. process.cwd() is the Next.js project
// directory. Reading it inside the component would be treated as dynamic I/O
// under Cache Components and opt the route out of static generation.
const interSemiBold = await readFile(
join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)
// Image generation // Image generation
export default async function Image() { export default async function Image() {
// Font loading, process.cwd() is Next.js project directory
const interSemiBold = await readFile(
join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)
return new ImageResponse( return new ImageResponse(
( (
// ... // ...
......
import { Readable } from 'node:stream' import { Readable } from 'node:stream'
import { createHash, type Hash } from 'node:crypto'
import { InvariantError } from '../../shared/lib/invariant-error' import { InvariantError } from '../../shared/lib/invariant-error'
import { workAsyncStorage } from '../app-render/work-async-storage.external' import { workAsyncStorage } from '../app-render/work-async-storage.external'
...@@ -98,6 +99,8 @@ async function getCachedImageResponseArrayBuffer( ...@@ -98,6 +99,8 @@ async function getCachedImageResponseArrayBuffer(
) )
} }
const [element, options] = args
// `createHangingInputAbortSignal` aborts once the prerender's cache-sourced // `createHangingInputAbortSignal` aborts once the prerender's cache-sourced
// input is ready, so anything the serialization below is still awaiting past // input is ready, so anything the serialization below is still awaiting past
// that point can be treated as dynamic (non-cache) input. In the prospective // that point can be treated as dynamic (non-cache) input. In the prospective
...@@ -162,7 +165,11 @@ async function getCachedImageResponseArrayBuffer( ...@@ -162,7 +165,11 @@ async function getCachedImageResponseArrayBuffer(
const { clientModules, rscModuleMapping } = getClientReferenceManifest() const { clientModules, rscModuleMapping } = getClientReferenceManifest()
try { try {
const { prelude } = await prerenderToNodeStream(args, clientModules, { // We serialize only the `element`. It's the part that needs Flight, to run
// its async Server Components once and to surface any dynamic input. The
// `options` are already-resolved plain data; they're folded into the cache
// key directly and passed to satori as-is below.
const { prelude } = await prerenderToNodeStream(element, clientModules, {
signal: hangingInputAbortSignal, signal: hangingInputAbortSignal,
filterStackFrame: undefined, filterStackFrame: undefined,
onError(error) { onError(error) {
...@@ -203,10 +210,19 @@ async function getCachedImageResponseArrayBuffer( ...@@ -203,10 +210,19 @@ async function getCachedImageResponseArrayBuffer(
chunks.push(chunk) chunks.push(chunk)
} }
const buffer = Buffer.concat(chunks) const elementBuffer = Buffer.concat(chunks)
// Base64-encode the serialized output to use it as a stable string key
// (the Flight stream is binary, so it isn't safe to treat as UTF-8 text). // Derive a stable cache key from the serialized element plus the options.
const cacheKey = buffer.toString('base64') // We hash rather than reuse the raw serialized bytes so the key stays
// compact even for large inputs (e.g. embedded fonts), and we fold the
// options in by content so two images that differ only in their options
// (size, fonts, ...) don't collide. The options are hashed directly here,
// never serialized through Flight, which would both bloat the key and apply
// `Buffer.prototype .toJSON` to font data.
const hash = createHash('sha256')
hash.update(elementBuffer)
updateHashWithOptions(hash, options)
const cacheKey = hash.digest('base64')
const cached = resumeDataCache.imageResponses.get(cacheKey) const cached = resumeDataCache.imageResponses.get(cacheKey)
...@@ -214,28 +230,35 @@ async function getCachedImageResponseArrayBuffer( ...@@ -214,28 +230,35 @@ async function getCachedImageResponseArrayBuffer(
return await cached return await cached
} }
// Deserialize the resolved tree and hand it to satori. Because the user's // Deserialize the element and hand it to satori. Because the user's
// components already ran during serialization, satori only walks resolved // components already ran during serialization, satori only walks resolved
// host elements and never re-runs them, confining user-space I/O to the // host elements and never re-runs them, confining user-space I/O to the
// in-store serialization above. // in-store serialization above.
// const deserializedElement = await createFromNodeStream(
Readable.from([elementBuffer]),
{
// We don't want to trigger preloads of client references here.
moduleLoading: null,
moduleMap: rscModuleMapping,
serverModuleMap: getServerModuleMap(),
},
{ findSourceMapURL: undefined }
)
// The Flight client hands back the output of an async Server Component as // The Flight client hands back the output of an async Server Component as
// a `React.lazy` (sync components and plain host elements are inlined). // a `React.lazy` (sync components and plain host elements are inlined).
// satori can't unwrap lazies, so we resolve them into plain elements first. // satori can't unwrap lazies, so we resolve them into plain elements first.
// We only reach here once the serialization completed, so every lazy is // We only reach here once the serialization completed, so every lazy is
// already resolved and `_init` returns synchronously. // already resolved and `_init` returns synchronously.
const resolvedArgs = resolveFlightLazies( const resolvedElement = resolveFlightLazies(deserializedElement)
await createFromNodeStream(
Readable.from([buffer]), // Pair the resolved element with the original, in-memory `options`, which
{ // never went through Flight. This keeps the font `Buffer` intact: had it
// We don't want to trigger preloads of client references here. // been serialized, Flight would apply the `toJSON` method that Node's
moduleLoading: null, // `Buffer` carries, turning it into a `{ type: 'Buffer', data: [...] }`
moduleMap: rscModuleMapping, // object that satori's font parser rejects (it needs an `ArrayBuffer` or a
serverModuleMap: getServerModuleMap(), // typed array).
}, const resolvedArgs = [resolvedElement, options] as ImageResponseArgs
{ findSourceMapURL: undefined }
)
) as ImageResponseArgs
// Render satori outside the prerender work-unit store. It does uncached // Render satori outside the prerender work-unit store. It does uncached
// `fetch` calls (e.g. loading a font), and inside a Cache Components // `fetch` calls (e.g. loading a font), and inside a Cache Components
...@@ -256,6 +279,103 @@ async function getCachedImageResponseArrayBuffer( ...@@ -256,6 +279,103 @@ async function getCachedImageResponseArrayBuffer(
} }
} }
/**
* Updates a hash with a stable encoding of the `ImageResponse` options so they
* can participate in the cache key without being serialized through Flight.
* Binary values (font `Buffer`s, `ArrayBuffer`s, typed arrays) are hashed by
* their raw bytes; objects are walked in sorted-key order.
*
* `ImageResponse` options are plain data: numbers, strings, booleans, nested
* plain objects/arrays, and binary font data. Exotic objects such as `Map` or
* `Date` keep their state outside their enumerable own keys, so the key walk
* below would hash them incorrectly. Options never contain these, but we warn
* if one ever shows up so a mis-keyed cache can be reported.
*
* The encoding is self-delimiting: every node starts with a type tag, and
* variable-length parts (byte runs, primitives, keys) are length-prefixed,
* while arrays and objects are count-prefixed. This makes it injective, so no
* concatenation of values can be mistaken for a differently shaped input.
*/
function updateHashWithOptions(hash: Hash, value: unknown): void {
if (value === undefined) {
hash.update('u')
return
}
if (value === null) {
hash.update('n')
return
}
const type = typeof value
if (type !== 'object') {
// Tag with the primitive type so e.g. the number `1` and the string `'1'`
// don't hash the same.
updateHashWithBytes(hash, 'p', Buffer.from(`${type}:${String(value)}`))
return
}
if (value instanceof ArrayBuffer) {
updateHashWithBytes(hash, 'a', new Uint8Array(value))
return
}
if (ArrayBuffer.isView(value)) {
updateHashWithBytes(
hash,
'v',
new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
)
return
}
if (Array.isArray(value)) {
hash.update(`[${value.length},`)
for (const item of value) {
updateHashWithOptions(hash, item)
}
return
}
// The key walk below captures a plain object faithfully, but an exotic object
// keeps its state elsewhere (a `Map`'s/`Set`'s entries, a `Date`'s time), so
// two different values would hash the same and could return the wrong cached
// image. This shouldn't happen for `ImageResponse` options, so we warn rather
// than fail, then hash best-effort, so it can be reported. Not gated on
// `NODE_ENV`: this runs during the production `next build` prerender, where
// the warning is most useful.
const prototype = Object.getPrototypeOf(value)
if (prototype !== Object.prototype && prototype !== null) {
const typeName =
(value as { constructor?: { name?: string } }).constructor?.name ??
'object'
console.warn(
`Cannot reliably include an \`ImageResponse\` option of type ` +
`\`${typeName}\` in the cache key, so different images may collide and ` +
`return an incorrect cached result. Please report this to the Next.js ` +
`team.`
)
}
const keys = Object.keys(value).sort()
hash.update(`{${keys.length},`)
for (const key of keys) {
updateHashWithBytes(hash, 'k', Buffer.from(key))
updateHashWithOptions(hash, (value as Record<string, unknown>)[key])
}
}
/**
* Hashes a length-prefixed, tagged byte run: `<tag><byteLength>:<bytes>`. The
* length prefix keeps the run self-delimiting so it can't blend into adjacent
* nodes.
*/
function updateHashWithBytes(hash: Hash, tag: string, bytes: Uint8Array): void {
hash.update(`${tag}${bytes.byteLength}:`)
hash.update(bytes)
}
async function renderImageResponseArrayBuffer( async function renderImageResponseArrayBuffer(
args: ImageResponseArgs args: ImageResponseArgs
): Promise<ArrayBuffer> { ): Promise<ArrayBuffer> {
......
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'
// Load the font once at module scope with a top-level await, using the
// documented `readFile` API. Reading it inside the handler instead would be
// uncached I/O during the prerender, which Cache Components treats as dynamic,
// opting the route out of static generation.
const font = await readFile(join(process.cwd(), 'assets/typewr__.ttf'))
export default async function Image() {
return new ImageResponse(
(
<div
style={{
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
fontSize: 88,
fontFamily: 'Typewriter',
background: '#fff',
color: '#000',
}}
>
Typewriter
</div>
),
{ ...size, fonts: [{ name: 'Typewriter', data: font, style: 'normal' }] }
)
}
...@@ -17,6 +17,20 @@ describe('use-cache-metadata-route-handler', () => { ...@@ -17,6 +17,20 @@ describe('use-cache-metadata-route-handler', () => {
} }
}) })
it('should generate an opengraph image with a custom (local) font', async () => {
const res = await next.fetch('/custom-font/opengraph-image')
expect(res.status).toBe(200)
expect(res.headers.get('content-type')).toBe('image/png')
if (isNextStart) {
const [buildStatus] = next.cliOutput.match(
/. \/custom-font\/opengraph-image/
)
expect(buildStatus).toBe('○ /custom-font/opengraph-image')
}
})
it('should generate an icon image with a metadata route handler that uses "use cache"', async () => { it('should generate an icon image with a metadata route handler that uses "use cache"', async () => {
const res = await next.fetch('/icon') const res = await next.fetch('/icon')
expect(res.status).toBe(200) expect(res.status).toBe(200)
......
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