Skip to content

Commit 3134b44

Browse files
feat: Link header
1 parent e0fb8ec commit 3134b44

9 files changed

Lines changed: 291 additions & 71 deletions

File tree

‎.changeset/fresh-ligers-clean.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@tanstack/start-server-core': patch
3+
'@tanstack/react-start-server': patch
4+
'@tanstack/solid-start-server': patch
5+
'@tanstack/vue-start-server': patch
6+
---
7+
8+
Add opt-in Start response Link headers for collected Early Hints.

‎docs/start/framework/react/guide/early-hints.md‎

Lines changed: 20 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -129,18 +129,18 @@ export const Route = createFileRoute('/posts/$postId')({
129129

130130
The `dynamic` phase is skipped when `router.load()` produces a redirect.
131131

132-
## Final `Link` Headers and CDNs
132+
## Response `Link` Header and CDNs
133133

134-
You can also attach the same serialized values to the final HTML response as HTTP `Link` headers. A final `Link` header does not hide server think time like a `103` response does, but the browser receives it before parsing the HTML body, so it can still start supported preloads and preconnects somewhat earlier.
134+
You can also attach the same serialized values to the HTML response's HTTP `Link` header. A response `Link` header does not hide server think time like a `103` response does, but the browser receives it before parsing the HTML body, so it can still start supported preloads and preconnects somewhat earlier.
135135

136-
Final `Link` headers are also useful for CDNs that generate their own Early Hints. For example, [Cloudflare Early Hints](https://developers.cloudflare.com/cache/advanced-configuration/early-hints/) can read `Link` headers from HTML responses, cache them, and emit `103` responses for later requests.
136+
Response `Link` headers are also useful for CDNs that generate their own Early Hints. For example, [Cloudflare Early Hints](https://developers.cloudflare.com/cache/advanced-configuration/early-hints/) can read `Link` headers from HTML responses, cache them, and emit `103` responses for later requests.
137137

138-
Start does not add final `Link` headers automatically. It cannot know whether those headers will be used only by the browser for the current response, stored by a shared cache, or replayed later as CDN-generated Early Hints.
138+
Start does not add response `Link` headers automatically. It cannot know whether those headers will be used only by the browser for the current response, stored by a shared cache, or replayed later as CDN-generated Early Hints.
139139

140-
Final `Link` headers are most useful when:
140+
Response `Link` headers are most useful when:
141141

142142
- You need a fallback for runtimes that cannot write `103` responses
143-
- Your CDN can generate Early Hints from final response `Link` headers
143+
- Your CDN can generate Early Hints from response `Link` headers
144144

145145
Good links to include are public and cache-stable for the response's cache boundary, such as:
146146

@@ -157,50 +157,33 @@ Avoid or filter links before they reach a shared cache or CDN when they are:
157157

158158
Cloudflare documents several important caveats: its Early Hints cache ignores query strings, it can emit cached hints before reaching your origin or Worker, and it only generates hints from selected final response status codes and `Link` relations.
159159

160-
Because of those cache semantics, prefer public static links for CDN-generated Early Hints. Use `allLinks` only when every dynamic `head().links` entry is public and cache-stable for the request URI.
160+
Because of those cache semantics, use response `Link` headers only when every emitted static or dynamic link is public and cache-stable for the request URI. Use `responseLinkHeader.filter` to remove links that are not safe for your cache boundary.
161161

162-
This example appends static links to the final HTML response. It gives non-`103` runtimes a fallback and lets CDNs such as Cloudflare generate Early Hints from public route assets:
162+
This example appends all collected static and dynamic links to non-redirect HTML responses. It gives non-`103` runtimes a fallback and lets CDNs such as Cloudflare generate Early Hints from route assets and `head().links` entries that are public and cache-safe:
163163

164164
```tsx
165165
// src/server.ts
166166
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
167167

168168
export default createServerEntry({
169-
async fetch(request) {
170-
let finalLinks: Array<string> = []
171-
172-
const response = await handler.fetch(request, {
173-
onEarlyHints: ({ phase, links }) => {
174-
if (phase === 'static') {
175-
finalLinks = links
176-
}
177-
},
169+
fetch(request) {
170+
return handler.fetch(request, {
171+
responseLinkHeader: true,
178172
})
173+
},
174+
})
175+
```
179176

180-
if (
181-
!finalLinks.length ||
182-
!response.headers.get('content-type')?.includes('text/html')
183-
) {
184-
return response
185-
}
186-
187-
const headers = new Headers(response.headers)
188-
189-
for (const link of finalLinks) {
190-
headers.append('Link', link)
191-
}
177+
Use `filter` to keep only links that are safe for your deployment. For example, this keeps only static manifest assets:
192178

193-
return new Response(response.body, {
194-
status: response.status,
195-
statusText: response.statusText,
196-
headers,
197-
})
179+
```tsx
180+
handler.fetch(request, {
181+
responseLinkHeader: {
182+
filter: ({ phase }) => phase === 'static',
198183
},
199184
})
200185
```
201186

202-
If your dynamic links are also public and cache-stable, collect `allLinks` in the `dynamic` phase instead of `links` in the `static` phase.
203-
204187
## Runtime Example: Node
205188

206189
If your runtime exposes Node's `ServerResponse`, call `writeEarlyHints` with `links`. This example sends the earliest `static` hints:
@@ -260,7 +243,7 @@ export default {
260243
## Limitations
261244

262245
- Early Hints are skipped in the Start dev server.
263-
- Start does not mutate the final response `Link` header.
246+
- Start only mutates the response `Link` header when `responseLinkHeader` is enabled.
264247
- Browsers generally process only the first `103` response for a navigation.
265248
- Static hints can be sent before `beforeLoad` redirects are known.
266249
- The runtime or proxy in front of your app must support HTTP `103` responses.

‎e2e/react-start/early-hints/src/server.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export default {
77
const serverRequest = request as ServerRequest
88

99
return handler.fetch(request, {
10+
responseLinkHeader: true,
1011
onEarlyHints: ({ allLinks, phase }) => {
1112
if (phase !== 'dynamic') return
1213

‎e2e/react-start/early-hints/tests/early-hints-protocol.spec.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,10 +143,19 @@ test.describe('Early Hints - HTTP/2 Protocol', () => {
143143
expect(link).toContain('<https://early-hints.test>; rel=preconnect')
144144
})
145145

146+
test('response Link header includes static and dynamic links', async () => {
147+
const response = await makeRequest(baseURL, '/')
148+
const link = linkHeader(response.finalHeaders)
149+
150+
expect(link).toContain('rel=modulepreload; as=script')
151+
expect(link).toContain('<https://early-hints.test>; rel=preconnect')
152+
})
153+
146154
test('coalesced hints are skipped for redirects', async () => {
147155
const response = await makeRequest(baseURL, '/redirect')
148156

149157
expect(response.earlyHints.length).toBe(0)
150158
expect(response.finalHeaders[':status']).toBe(307)
159+
expect(linkHeader(response.finalHeaders)).toBe('')
151160
})
152161
})

‎packages/start-server-core/src/createStartHandler.ts‎

Lines changed: 139 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ import {
3232
collectDynamicHintsFromMatches,
3333
collectStaticHintsFromManifest,
3434
createEarlyHintsEvent,
35+
createResponseLinkHeaderEntries,
36+
getResponseLinkHeaderEntries,
3537
} from './early-hints'
3638

3739
import { HEADERS } from './constants'
@@ -46,7 +48,15 @@ import type {
4648
StartEntry,
4749
} from '@tanstack/start-client-core'
4850
import type { RequestHandler } from './request-handler'
49-
import type { EarlyHint, EarlyHintsPhase, OnEarlyHints } from './early-hints'
51+
import type {
52+
EarlyHint,
53+
EarlyHintsEvent,
54+
EarlyHintsPhase,
55+
OnEarlyHints,
56+
ResponseLinkHeaderEntry,
57+
ResponseLinkHeaderFilter,
58+
ResponseLinkHeaderOptions,
59+
} from './early-hints'
5060
import type {
5161
AnyRoute,
5262
AnyRouter,
@@ -215,28 +225,106 @@ function getStartResponseHeaders(opts: { router: AnyRouter }) {
215225
return headers
216226
}
217227

218-
function sendEarlyHintsEvent(opts: {
219-
phase: EarlyHintsPhase
220-
hints: ReadonlyArray<EarlyHint>
221-
onEarlyHints: OnEarlyHints
222-
sentLinks: Set<string>
223-
sentHints: Array<EarlyHint>
224-
}) {
225-
const event = createEarlyHintsEvent(opts)
226-
if (!event) return
227-
228+
function notifyEarlyHints(
229+
phase: EarlyHintsPhase,
230+
event: EarlyHintsEvent,
231+
onEarlyHints: OnEarlyHints,
232+
) {
228233
try {
229-
const result = opts.onEarlyHints(event)
234+
const result = onEarlyHints(event)
230235
if (result) {
231236
void Promise.resolve(result).catch((err) => {
232-
console.error(`Error sending ${opts.phase} early hints:`, err)
237+
console.error(`Error sending ${phase} early hints:`, err)
233238
})
234239
}
235240
} catch (err) {
236-
console.error(`Error sending ${opts.phase} early hints:`, err)
241+
console.error(`Error sending ${phase} early hints:`, err)
242+
}
243+
}
244+
245+
function getResponseLinkHeaderFilter(
246+
responseLinkHeader: boolean | ResponseLinkHeaderOptions | undefined,
247+
): ResponseLinkHeaderFilter | undefined {
248+
if (typeof responseLinkHeader !== 'object') {
249+
return undefined
250+
}
251+
252+
return responseLinkHeader.filter
253+
}
254+
255+
function appendResponseLinkHeaders(opts: {
256+
responseHeaders: Headers
257+
entries: ReadonlyArray<ResponseLinkHeaderEntry>
258+
filter?: ResponseLinkHeaderFilter
259+
}) {
260+
if (!opts.filter) {
261+
for (const entry of opts.entries) {
262+
opts.responseHeaders.append('Link', entry.link)
263+
}
264+
return
265+
}
266+
267+
const links = getResponseLinkHeaderEntries(opts)
268+
269+
for (const link of links) {
270+
opts.responseHeaders.append('Link', link)
237271
}
238272
}
239273

274+
function collectResponseLinkHeaderEntries(opts: {
275+
phase: EarlyHintsPhase
276+
event: EarlyHintsEvent
277+
entries: Array<ResponseLinkHeaderEntry>
278+
}) {
279+
for (let index = 0; index < opts.event.hints.length; index++) {
280+
opts.entries.push({
281+
phase: opts.phase,
282+
hint: opts.event.hints[index]!,
283+
link: opts.event.links[index]!,
284+
})
285+
}
286+
}
287+
288+
function handleCollectedEarlyHints(opts: {
289+
phase: EarlyHintsPhase
290+
hints: ReadonlyArray<EarlyHint>
291+
sentLinks: Set<string>
292+
sentHints?: Array<EarlyHint>
293+
onEarlyHints?: OnEarlyHints
294+
responseLinkHeaderEntries?: Array<ResponseLinkHeaderEntry>
295+
}) {
296+
const event = opts.onEarlyHints
297+
? createEarlyHintsEvent({
298+
phase: opts.phase,
299+
hints: opts.hints,
300+
sentLinks: opts.sentLinks,
301+
sentHints: opts.sentHints!,
302+
})
303+
: undefined
304+
305+
if (event) {
306+
notifyEarlyHints(opts.phase, event, opts.onEarlyHints!)
307+
}
308+
309+
if (!opts.responseLinkHeaderEntries) return
310+
311+
if (event) {
312+
collectResponseLinkHeaderEntries({
313+
phase: opts.phase,
314+
event,
315+
entries: opts.responseLinkHeaderEntries,
316+
})
317+
return
318+
}
319+
320+
createResponseLinkHeaderEntries({
321+
phase: opts.phase,
322+
hints: opts.hints,
323+
sentLinks: opts.sentLinks,
324+
entries: opts.responseLinkHeaderEntries,
325+
})
326+
}
327+
240328
interface PluginAdaptersEntry {
241329
hasPluginAdapters: boolean
242330
pluginSerializationAdapters: Array<AnySerializationAdapter>
@@ -722,27 +810,36 @@ export function createStartHandler<TRegister = Register>(
722810
cache,
723811
)
724812

725-
const onEarlyHints =
726-
process.env.TSS_DEV_SERVER === 'true'
727-
? undefined
728-
: requestOpts?.onEarlyHints
729-
const earlyHintsSentLinks = onEarlyHints ? new Set<string>() : undefined
730-
const earlyHintsSentHints = onEarlyHints
731-
? new Array<EarlyHint>()
813+
const onEarlyHints = requestOpts?.onEarlyHints
814+
const responseLinkHeader = requestOpts?.responseLinkHeader
815+
const shouldCollectEarlyHints =
816+
process.env.TSS_DEV_SERVER !== 'true' &&
817+
(!!onEarlyHints || !!responseLinkHeader)
818+
const sentEarlyHintLinks = shouldCollectEarlyHints
819+
? new Set<string>()
820+
: undefined
821+
const sentEarlyHints = onEarlyHints ? new Array<EarlyHint>() : undefined
822+
const responseLinkHeaderEntries =
823+
shouldCollectEarlyHints && responseLinkHeader
824+
? new Array<ResponseLinkHeaderEntry>()
825+
: undefined
826+
const responseLinkHeaderFilter = shouldCollectEarlyHints
827+
? getResponseLinkHeaderFilter(responseLinkHeader)
732828
: undefined
733829

734830
if (
735-
onEarlyHints &&
736-
earlyHintsSentLinks &&
737-
earlyHintsSentHints &&
831+
shouldCollectEarlyHints &&
832+
sentEarlyHintLinks &&
738833
matchedRoutes?.length
739834
) {
740-
sendEarlyHintsEvent({
835+
const hints = collectStaticHintsFromManifest(manifest, matchedRoutes)
836+
handleCollectedEarlyHints({
741837
phase: 'static',
742-
hints: collectStaticHintsFromManifest(manifest, matchedRoutes),
838+
hints,
839+
sentLinks: sentEarlyHintLinks,
840+
sentHints: sentEarlyHints,
743841
onEarlyHints,
744-
sentLinks: earlyHintsSentLinks,
745-
sentHints: earlyHintsSentHints,
842+
responseLinkHeaderEntries,
746843
})
747844
}
748845

@@ -763,14 +860,16 @@ export function createStartHandler<TRegister = Register>(
763860
return routerInstance.state.redirect
764861
}
765862

766-
if (onEarlyHints && earlyHintsSentLinks && earlyHintsSentHints) {
863+
if (shouldCollectEarlyHints && sentEarlyHintLinks) {
767864
const loadedMatches = routerInstance.stores.matches.get()
768-
sendEarlyHintsEvent({
865+
const hints = collectDynamicHintsFromMatches(loadedMatches)
866+
handleCollectedEarlyHints({
769867
phase: 'dynamic',
770-
hints: collectDynamicHintsFromMatches(loadedMatches),
868+
hints,
869+
sentLinks: sentEarlyHintLinks,
870+
sentHints: sentEarlyHints,
771871
onEarlyHints,
772-
sentLinks: earlyHintsSentLinks,
773-
sentHints: earlyHintsSentHints,
872+
responseLinkHeaderEntries,
774873
})
775874
}
776875

@@ -783,6 +882,13 @@ export function createStartHandler<TRegister = Register>(
783882
const responseHeaders = getStartResponseHeaders({
784883
router: routerInstance,
785884
})
885+
if (responseLinkHeaderEntries?.length) {
886+
appendResponseLinkHeaders({
887+
responseHeaders,
888+
entries: responseLinkHeaderEntries,
889+
filter: responseLinkHeaderFilter,
890+
})
891+
}
786892
cbWillCleanup = true
787893

788894
return cb({

0 commit comments

Comments
 (0)