Skip to content

Commit afa40ef

Browse files
fix(start-server-core): fall back to GET handler for HEAD requests (RFC 9110 §9.3.2) (#7325)
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent 9902eb4 commit afa40ef

7 files changed

Lines changed: 204 additions & 1 deletion

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@tanstack/start-server-core': patch
3+
---
4+
5+
fix(start-server-core): fall back HEAD requests to GET then ANY per RFC 9110 §9.3.2

‎e2e/react-start/server-routes/src/routeTree.gen.ts‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ import { Route as MethodsIndexRouteImport } from './routes/methods/index'
1616
import { Route as MethodsOnlyAnyRouteImport } from './routes/methods/only-any'
1717
import { Route as ApiOnlyAnyRouteImport } from './routes/api/only-any'
1818
import { Route as ApiMiddlewareContextRouteImport } from './routes/api/middleware-context'
19+
import { Route as ApiHeadFallbackRouteImport } from './routes/api/head-fallback'
20+
import { Route as ApiGetAndAnyRouteImport } from './routes/api/get-and-any'
21+
import { Route as ApiHeadRedirectFallbackRouteImport } from './routes/api/head-redirect-fallback'
1922
import { Route as ApiParamsFooRouteRouteImport } from './routes/api/params/$foo/route'
2023
import { Route as ApiParamsFooBarRouteImport } from './routes/api/params/$foo/$bar'
2124

@@ -49,6 +52,21 @@ const ApiOnlyAnyRoute = ApiOnlyAnyRouteImport.update({
4952
path: '/api/only-any',
5053
getParentRoute: () => rootRouteImport,
5154
} as any)
55+
const ApiHeadFallbackRoute = ApiHeadFallbackRouteImport.update({
56+
id: '/api/head-fallback',
57+
path: '/api/head-fallback',
58+
getParentRoute: () => rootRouteImport,
59+
} as any)
60+
const ApiGetAndAnyRoute = ApiGetAndAnyRouteImport.update({
61+
id: '/api/get-and-any',
62+
path: '/api/get-and-any',
63+
getParentRoute: () => rootRouteImport,
64+
} as any)
65+
const ApiHeadRedirectFallbackRoute = ApiHeadRedirectFallbackRouteImport.update({
66+
id: '/api/head-redirect-fallback',
67+
path: '/api/head-redirect-fallback',
68+
getParentRoute: () => rootRouteImport,
69+
} as any)
5270
const ApiMiddlewareContextRoute = ApiMiddlewareContextRouteImport.update({
5371
id: '/api/middleware-context',
5472
path: '/api/middleware-context',
@@ -71,6 +89,9 @@ export interface FileRoutesByFullPath {
7189
'/merge-middleware-context': typeof MergeMiddlewareContextRoute
7290
'/api/middleware-context': typeof ApiMiddlewareContextRoute
7391
'/api/only-any': typeof ApiOnlyAnyRoute
92+
'/api/head-fallback': typeof ApiHeadFallbackRoute
93+
'/api/get-and-any': typeof ApiGetAndAnyRoute
94+
'/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
7495
'/methods/only-any': typeof MethodsOnlyAnyRoute
7596
'/methods/': typeof MethodsIndexRoute
7697
'/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -81,6 +102,9 @@ export interface FileRoutesByTo {
81102
'/merge-middleware-context': typeof MergeMiddlewareContextRoute
82103
'/api/middleware-context': typeof ApiMiddlewareContextRoute
83104
'/api/only-any': typeof ApiOnlyAnyRoute
105+
'/api/head-fallback': typeof ApiHeadFallbackRoute
106+
'/api/get-and-any': typeof ApiGetAndAnyRoute
107+
'/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
84108
'/methods/only-any': typeof MethodsOnlyAnyRoute
85109
'/methods': typeof MethodsIndexRoute
86110
'/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -93,6 +117,9 @@ export interface FileRoutesById {
93117
'/merge-middleware-context': typeof MergeMiddlewareContextRoute
94118
'/api/middleware-context': typeof ApiMiddlewareContextRoute
95119
'/api/only-any': typeof ApiOnlyAnyRoute
120+
'/api/head-fallback': typeof ApiHeadFallbackRoute
121+
'/api/get-and-any': typeof ApiGetAndAnyRoute
122+
'/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
96123
'/methods/only-any': typeof MethodsOnlyAnyRoute
97124
'/methods/': typeof MethodsIndexRoute
98125
'/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -106,6 +133,9 @@ export interface FileRouteTypes {
106133
| '/merge-middleware-context'
107134
| '/api/middleware-context'
108135
| '/api/only-any'
136+
| '/api/head-fallback'
137+
| '/api/get-and-any'
138+
| '/api/head-redirect-fallback'
109139
| '/methods/only-any'
110140
| '/methods/'
111141
| '/api/params/$foo'
@@ -116,6 +146,9 @@ export interface FileRouteTypes {
116146
| '/merge-middleware-context'
117147
| '/api/middleware-context'
118148
| '/api/only-any'
149+
| '/api/head-fallback'
150+
| '/api/get-and-any'
151+
| '/api/head-redirect-fallback'
119152
| '/methods/only-any'
120153
| '/methods'
121154
| '/api/params/$foo'
@@ -127,6 +160,9 @@ export interface FileRouteTypes {
127160
| '/merge-middleware-context'
128161
| '/api/middleware-context'
129162
| '/api/only-any'
163+
| '/api/head-fallback'
164+
| '/api/get-and-any'
165+
| '/api/head-redirect-fallback'
130166
| '/methods/only-any'
131167
| '/methods/'
132168
| '/api/params/$foo'
@@ -139,6 +175,9 @@ export interface RootRouteChildren {
139175
MergeMiddlewareContextRoute: typeof MergeMiddlewareContextRoute
140176
ApiMiddlewareContextRoute: typeof ApiMiddlewareContextRoute
141177
ApiOnlyAnyRoute: typeof ApiOnlyAnyRoute
178+
ApiHeadFallbackRoute: typeof ApiHeadFallbackRoute
179+
ApiGetAndAnyRoute: typeof ApiGetAndAnyRoute
180+
ApiHeadRedirectFallbackRoute: typeof ApiHeadRedirectFallbackRoute
142181
ApiParamsFooRouteRoute: typeof ApiParamsFooRouteRouteWithChildren
143182
}
144183

@@ -186,6 +225,27 @@ declare module '@tanstack/react-router' {
186225
preLoaderRoute: typeof ApiOnlyAnyRouteImport
187226
parentRoute: typeof rootRouteImport
188227
}
228+
'/api/head-fallback': {
229+
id: '/api/head-fallback'
230+
path: '/api/head-fallback'
231+
fullPath: '/api/head-fallback'
232+
preLoaderRoute: typeof ApiHeadFallbackRouteImport
233+
parentRoute: typeof rootRouteImport
234+
}
235+
'/api/get-and-any': {
236+
id: '/api/get-and-any'
237+
path: '/api/get-and-any'
238+
fullPath: '/api/get-and-any'
239+
preLoaderRoute: typeof ApiGetAndAnyRouteImport
240+
parentRoute: typeof rootRouteImport
241+
}
242+
'/api/head-redirect-fallback': {
243+
id: '/api/head-redirect-fallback'
244+
path: '/api/head-redirect-fallback'
245+
fullPath: '/api/head-redirect-fallback'
246+
preLoaderRoute: typeof ApiHeadRedirectFallbackRouteImport
247+
parentRoute: typeof rootRouteImport
248+
}
189249
'/api/middleware-context': {
190250
id: '/api/middleware-context'
191251
path: '/api/middleware-context'
@@ -241,6 +301,9 @@ const rootRouteChildren: RootRouteChildren = {
241301
MergeMiddlewareContextRoute: MergeMiddlewareContextRoute,
242302
ApiMiddlewareContextRoute: ApiMiddlewareContextRoute,
243303
ApiOnlyAnyRoute: ApiOnlyAnyRoute,
304+
ApiHeadFallbackRoute: ApiHeadFallbackRoute,
305+
ApiGetAndAnyRoute: ApiGetAndAnyRoute,
306+
ApiHeadRedirectFallbackRoute: ApiHeadRedirectFallbackRoute,
244307
ApiParamsFooRouteRoute: ApiParamsFooRouteRouteWithChildren,
245308
}
246309
export const routeTree = rootRouteImport
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { createFileRoute } from '@tanstack/react-router'
2+
3+
export const Route = createFileRoute('/api/get-and-any')({
4+
server: {
5+
handlers: {
6+
GET: () =>
7+
new Response(null, {
8+
headers: { 'x-handler': 'GET' },
9+
}),
10+
ANY: ({ request }) =>
11+
new Response(null, {
12+
headers: { 'x-handler': 'ANY', 'x-method': request.method },
13+
}),
14+
},
15+
},
16+
})
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { createFileRoute } from '@tanstack/react-router'
2+
3+
// A server-only route with only a GET handler.
4+
// Used to test that HEAD requests fall back to the GET handler per RFC 9110.
5+
export const Route = createFileRoute('/api/head-fallback')({
6+
server: {
7+
handlers: {
8+
GET: () =>
9+
new Response('body', {
10+
headers: { 'content-type': 'application/xml; charset=utf-8' },
11+
}),
12+
},
13+
},
14+
})
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { createFileRoute, redirect } from '@tanstack/react-router'
2+
3+
export const Route = createFileRoute('/api/head-redirect-fallback')({
4+
server: {
5+
handlers: {
6+
GET: () => redirect({ to: '/api/head-fallback', statusCode: 307 }),
7+
},
8+
},
9+
})

‎e2e/react-start/server-routes/tests/server-routes.spec.ts‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,79 @@ test('merge-middleware-context', async ({ page }) => {
1717
expect(contextResult).toContain('test')
1818
})
1919

20+
test.describe('HEAD fallback', () => {
21+
test('strips body and preserves headers when falling back to GET', async ({
22+
page,
23+
}) => {
24+
await page.goto('/')
25+
const result = await page.evaluate(async () => {
26+
const res = await fetch('/api/head-fallback', { method: 'HEAD' })
27+
return {
28+
status: res.status,
29+
contentType: res.headers.get('content-type'),
30+
body: await res.text(),
31+
}
32+
})
33+
expect(result.status).toBe(200)
34+
expect(result.contentType).toBe('application/xml; charset=utf-8')
35+
expect(result.body).toBe('')
36+
})
37+
38+
test('strips body and preserves headers when falling back to ANY', async ({
39+
page,
40+
}) => {
41+
await page.goto('/')
42+
const result = await page.evaluate(async () => {
43+
const res = await fetch('/api/only-any', { method: 'HEAD' })
44+
return {
45+
status: res.status,
46+
xHandler: res.headers.get('x-handler'),
47+
xMethod: res.headers.get('x-method'),
48+
body: await res.text(),
49+
}
50+
})
51+
expect(result.status).toBe(200)
52+
expect(result.xHandler).toBe('ANY')
53+
expect(result.xMethod).toBe('HEAD')
54+
expect(result.body).toBe('')
55+
})
56+
57+
test('prefers GET over ANY for HEAD requests', async ({ page }) => {
58+
await page.goto('/')
59+
const result = await page.evaluate(async () => {
60+
const res = await fetch('/api/get-and-any', { method: 'HEAD' })
61+
return {
62+
status: res.status,
63+
xHandler: res.headers.get('x-handler'),
64+
body: await res.text(),
65+
}
66+
})
67+
expect(result.status).toBe(200)
68+
expect(result.xHandler).toBe('GET')
69+
expect(result.body).toBe('')
70+
})
71+
72+
test('preserves Location header when GET handler returns a redirect', async ({
73+
page,
74+
}) => {
75+
await page.goto('/')
76+
// HEAD /api/head-redirect-fallback → server returns 307 Location:/api/head-fallback
77+
// Browser follows the redirect: HEAD /api/head-fallback → 200 with correct headers
78+
// If the Location header were lost, the browser could not follow and would see a 307.
79+
const result = await page.evaluate(async () => {
80+
const res = await fetch('/api/head-redirect-fallback', { method: 'HEAD' })
81+
return {
82+
status: res.status,
83+
contentType: res.headers.get('content-type'),
84+
body: await res.text(),
85+
}
86+
})
87+
expect(result.status).toBe(200)
88+
expect(result.contentType).toBe('application/xml; charset=utf-8')
89+
expect(result.body).toBe('')
90+
})
91+
})
92+
2093
test.describe('methods', () => {
2194
test('only ANY', async ({ page }) => {
2295
await page.goto('/methods/only-any')

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

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1061,14 +1061,22 @@ async function handleServerRoutes({
10611061

10621062
// Add handler middleware if exact match
10631063
const server = foundRoute?.options.server
1064+
let isHeadFallback = false
10641065
if (server?.handlers && isExactMatch) {
10651066
const handlers =
10661067
typeof server.handlers === 'function'
10671068
? server.handlers({ createHandlers: (d: any) => d })
10681069
: server.handlers
10691070

10701071
const requestMethod = request.method.toUpperCase() as RouteMethod
1071-
const handler = handlers[requestMethod] ?? handlers['ANY']
1072+
// Per RFC 9110 §9.3.2, HEAD must return the same header fields as GET.
1073+
// Priority for HEAD: explicit HEAD handler → GET → ANY (last resort).
1074+
const handler =
1075+
requestMethod === 'HEAD'
1076+
? (handlers['HEAD'] ?? handlers['GET'] ?? handlers['ANY'])
1077+
: (handlers[requestMethod] ?? handlers['ANY'])
1078+
isHeadFallback =
1079+
requestMethod === 'HEAD' && handler !== undefined && !handlers['HEAD']
10721080

10731081
if (handler) {
10741082
const mayDefer = !!foundRoute.options.component
@@ -1101,5 +1109,20 @@ async function handleServerRoutes({
11011109
pathname,
11021110
})
11031111

1112+
// RFC 9110 §9.3.2: HEAD must carry the same header fields as GET but no body.
1113+
// Resolve any redirect before stripping so the Location header survives.
1114+
if (isHeadFallback) {
1115+
if (!ctx.response) {
1116+
throwRouteHandlerError()
1117+
}
1118+
1119+
const resolved = await handleRedirectResponse(
1120+
ctx.response,
1121+
request,
1122+
getRouter,
1123+
)
1124+
return new Response(null, resolved)
1125+
}
1126+
11041127
return ctx.response
11051128
}

0 commit comments

Comments
 (0)