Open History to see the last commit
1import { createServerHistory } from '@tanstack/history'
2import {
3 createCsrfMiddleware,
4 createNullProtoObject,
5 csrfSymbol,
6 flattenMiddlewares,
7 mergeHeaders,
8 safeObjectMerge,
9} from '@tanstack/start-client-core'
10import {
11 _getRenderedMatches,
12 executeRewriteInput,
13 isDangerousProtocol,
14 isRedirect,
15} from '@tanstack/router-core'
16import {
17 attachRouterServerSsrUtils,
18 bindSsrResponseToRequest,
19 disposeSsrResponseDetached,
20 getNormalizedURL,
21 getOrigin,
22 isSsrResponse,
23 normalizeSsrResponse,
24 replaceSsrResponse,
25 stripSsrResponseBody,
26 waitForRequest,
27} from '@tanstack/router-core/ssr/server'
28import {
29 getStartContext,
30 runWithStartContext,
31} from '@tanstack/start-storage-context'
32import { requestHandler } from './request-response'
33import { getStartManifest } from './router-manifest'
34import { handleServerAction } from './server-functions-handler'
35import { createEarlyHintsCollector } from './early-hints'
36import {
37 createCachedBaseManifestLoader,
38 createFinalManifestResolver,
39} from './finalManifest'
40
41import { HEADERS } from './constants'
42import { ServerFunctionSerializationAdapter } from './serializer/ServerFunctionSerializationAdapter'
43import type {
44 AnyFunctionMiddleware,
45 AnyRequestMiddleware,
46 AnyStartInstanceOptions,
47 RouteMethod,
48 RouteMethodHandlerFn,
49 RouterEntry,
50 StartEntry,
51} from '@tanstack/start-client-core'
52import type { RequestHandler } from './request-handler'
53import type {
54 AnyRoute,
55 AnyRouter,
56 AnySerializationAdapter,
57 Register,
58} from '@tanstack/router-core'
59import type {
60 HandlerCallback,
61 HandlerCallbackResult,
62 SsrResponse,
63} from '@tanstack/router-core/ssr/server'
64import type { FinalManifestOptions } from './finalManifest'
65
66type TODO = any
67
68type AnyMiddlewareServerFn =
69 | AnyRequestMiddleware['options']['server']
70 | AnyFunctionMiddleware['options']['server']
71
72export interface CreateStartHandlerOptions extends FinalManifestOptions {
73 handler: HandlerCallback<AnyRouter>
74}
75
76function getStartResponseHeaders(opts: { router: AnyRouter }) {
77 const headers = mergeHeaders(
78 {
79 'Content-Type': 'text/html; charset=utf-8',
80 },
81 ..._getRenderedMatches(opts.router.stores.matches.get()).map((match) => {
82 return match.headers
83 }),
84 )
85 return headers
86}
87
88interface PluginAdaptersEntry {
89 hasPluginAdapters: boolean
90 pluginSerializationAdapters: Array<AnySerializationAdapter>
91}
92
93interface Entries {
94 startEntry: StartEntry
95 routerEntry: RouterEntry
96 pluginAdapters: PluginAdaptersEntry
97}
98
99// Cached entries - promises stored immediately to prevent concurrent imports
100// that can cause race conditions during module initialization
101let entriesPromise: Promise<Entries> | undefined
102let hasWarnedMissingCsrfMiddleware = false
103const defaultCsrfMiddleware = createCsrfMiddleware({
104 filter: (ctx) => ctx.handlerType === 'serverFn',
105})
106const getCachedBaseManifest = createCachedBaseManifestLoader(() =>
107 getStartManifest(),
108)
109const getProdBaseManifest: typeof getStartManifest = () =>
110 getCachedBaseManifest()
111const getBaseManifest =
112 process.env.TSS_DEV_SERVER === 'true' ? getStartManifest : getProdBaseManifest
113const createEarlyHintsForRequest: typeof createEarlyHintsCollector =
114 process.env.TSS_DEV_SERVER === 'true'
115 ? () => undefined
116 : createEarlyHintsCollector
117
118async function loadEntries(): Promise<Entries> {
119 const [routerEntry, startEntry, pluginAdapters] = await Promise.all([
120 // @ts-ignore When building, we currently don't respect tsconfig.ts' `include` so we are not picking up the .d.ts from start-client-core
121 import('#tanstack-router-entry'),
122 // @ts-ignore When building, we currently don't respect tsconfig.ts' `include` so we are not picking up the .d.ts from start-client-core
123 import('#tanstack-start-entry'),
124 // @ts-ignore When building, we currently don't respect tsconfig.ts' `include` so we are not picking up the .d.ts from start-client-core
125 import('#tanstack-start-plugin-adapters'),
126 ])
127 return {
128 routerEntry: routerEntry as unknown as RouterEntry,
129 startEntry: startEntry as unknown as StartEntry,
130 pluginAdapters: pluginAdapters as unknown as PluginAdaptersEntry,
131 }
132}
133
134function getEntries() {
135 if (!entriesPromise) {
136 entriesPromise = loadEntries()
137 }
138 return entriesPromise
139}
140
141function hasCsrfMiddleware(
142 middlewares: Array<AnyRequestMiddleware | AnyFunctionMiddleware>,
143): boolean {
144 return middlewares.some((middleware) => csrfSymbol in middleware)
145}
146
147function warnMissingCsrfMiddlewareOnce() {
148 if (hasWarnedMissingCsrfMiddleware) return
149 hasWarnedMissingCsrfMiddleware = true
150
151 console.warn(`TanStack Start server functions are not protected by the CSRF middleware.
152
153Server functions are same-origin RPC endpoints and should be protected from cross-site requests.
154
155Add the CSRF middleware in src/start.ts:
156
157 const csrfMiddleware = createCsrfMiddleware({
158 filter: (ctx) => ctx.handlerType === 'serverFn',
159 })
160
161 export const startInstance = createStart(() => ({
162 requestMiddleware: [csrfMiddleware],
163 }))
164
165If you intentionally handle CSRF another way, disable this warning:
166
167 tanstackStart({
168 serverFns: {
169 disableCsrfMiddlewareWarning: true,
170 },
171 })`)
172}
173
174// Pre-computed constants
175const ROUTER_BASEPATH = process.env.TSS_ROUTER_BASEPATH || '/'
176const SERVER_FN_BASE = process.env.TSS_SERVER_FN_BASE
177const IS_PRERENDERING = process.env.TSS_PRERENDERING === 'true'
178const IS_SHELL_ENV = process.env.TSS_SHELL === 'true'
179const IS_DEV = process.env.NODE_ENV === 'development'
180
181// Reusable error messages
182const ERR_NO_RESPONSE = IS_DEV
183 ? `It looks like you forgot to return a response from your server route handler. If you want to defer to the app router, make sure to have a component set in this route.`
184 : 'Internal Server Error'
185
186const ERR_NO_DEFER = IS_DEV
187 ? `You cannot defer to the app router if there is no component defined on this route.`
188 : 'Internal Server Error'
189
190function throwRouteHandlerError(): never {
191 throw new Error(ERR_NO_RESPONSE)
192}
193
194function throwIfMayNotDefer(): never {
195 throw new Error(ERR_NO_DEFER)
196}
197
198/**
199 * Check if a value is a special response (Response or Redirect)
200 */
201function isSpecialResponse(value: unknown): value is Response {
202 return value instanceof Response || isRedirect(value)
203}
204
205/**
206 * Normalize middleware result to context shape
207 */
208function handleCtxResult(result: TODO) {
209 if (isSsrResponse(result) || isSpecialResponse(result)) {
210 return { response: result }
211 }
212 return result
213}
214
215function disposeLateResponse(result: TODO, signal: AbortSignal): void {
216 const response = handleCtxResult(result)?.response
217 if (isSsrResponse(response) || isSpecialResponse(response)) {
218 disposeSsrResponseDetached(response, signal.reason)
219 }
220}
221
222function isSignalAborted(signal: AbortSignal): boolean {
223 return signal.aborted
224}
225
226/**
227 * Execute a middleware chain
228 */
229async function executeMiddleware(
230 middlewares: Array<TODO>,
231 ctx: TODO,
232 signal: AbortSignal,
233): Promise<{ ctx: TODO; response: HandlerCallbackResult }> {
234 let index = -1
235 let streamResponse:
236 | Extract<SsrResponse, { serverSsrCleanup: 'stream' }>
237 | undefined
238 let retiredStreamIdentities: WeakSet<object> | undefined
239
240 const isResponseAlias = (candidate: unknown, response: Response) =>
241 candidate === response ||
242 (candidate instanceof Response &&
243 response.body !== null &&
244 candidate.body === response.body)
245
246 const setResponse = (response: TODO) => {
247 if (isSsrResponse(response)) {
248 if (response.serverSsrCleanup === 'stream') {
249 streamResponse = response
250 }
251 ctx.response = response.response
252 return
253 }
254
255 ctx.response = response
256 }
257
258 const disposeStreamResponse = async (reason: unknown) => {
259 const response = streamResponse
260 if (!response) {
261 return
262 }
263
264 streamResponse = undefined
265 retiredStreamIdentities ??= new WeakSet()
266 retiredStreamIdentities.add(response.response)
267 if (response.response.body) {
268 retiredStreamIdentities.add(response.response.body)
269 }
270 const currentResponse = ctx.response
271 if (isResponseAlias(currentResponse, response.response)) {
272 ctx.response = undefined
273 }
274 await response.dispose(reason)
275 }
276
277 const disposeAbandonedResult = (result: TODO) => {
278 const exposed = handleCtxResult(result)?.response
279 const response = isSsrResponse(exposed) ? exposed.response : exposed
280 if (streamResponse && isResponseAlias(response, streamResponse.response)) {
281 void disposeStreamResponse(signal.reason).catch(console.error)
282 return
283 }
284 if (
285 response instanceof Response &&
286 retiredStreamIdentities &&
287 (retiredStreamIdentities.has(response) ||
288 (response.body !== null && retiredStreamIdentities.has(response.body)))
289 ) {
290 return
291 }
292
293 disposeLateResponse(result, signal)
294 }
295
296 const getFinalResponse = async (): Promise<HandlerCallbackResult> => {
297 const response = ctx.response
298 if (!response) {
299 throwRouteHandlerError()
300 }
301
302 if (!streamResponse) {
303 return response
304 }
305
306 if (response === streamResponse.response) {
307 return streamResponse
308 }
309
310 if (
311 streamResponse.response.body !== null &&
312 response.body === streamResponse.response.body
313 ) {
314 return { ...streamResponse, response }
315 }
316
317 await disposeStreamResponse('middleware response replaced')
318 return response
319 }
320
321 let nextPromise: Promise<TODO> | undefined
322
323 function next(nextCtx?: TODO): Promise<TODO> {
324 const result = runNext(nextCtx)
325 nextPromise = result
326 return result
327 }
328
329 async function runNext(nextCtx?: TODO): Promise<TODO> {
330 if (signal.aborted) {
331 throw signal.reason
332 }
333
334 // Merge context if provided using safeObjectMerge for prototype pollution prevention
335 if (nextCtx) {
336 if (nextCtx.context) {
337 ctx.context = safeObjectMerge(ctx.context, nextCtx.context)
338 }
339 // Copy own properties except context (Object.keys returns only own enumerable properties)
340 for (const key of Object.keys(nextCtx)) {
341 if (key === 'response') {
342 setResponse(nextCtx.response)
343 } else if (key !== 'context') {
344 ctx[key] = nextCtx[key]
345 }
346 }
347 }
348
349 index++
350 const middleware = middlewares[index]
351 if (!middleware) return ctx
352
353 let result: TODO
354 try {
355 const pending = middleware({ ...ctx, next })
356 // A directly returned next() promise already propagates request aborts.
357 if (pending === nextPromise) {
358 nextPromise = undefined
359 result = await pending
360 if (isSignalAborted(signal)) {
361 disposeAbandonedResult(result)
362 throw signal.reason
363 }
364 } else {
365 result = await waitForRequest(pending, signal, disposeAbandonedResult)
366 }
367 } catch (err) {
368 if (isSignalAborted(signal)) {
369 throw signal.reason
370 }
371 if (isSpecialResponse(err)) {
372 setResponse(err)
373 return ctx
374 }
375 throw err
376 }
377
378 const normalized = handleCtxResult(result)
379 if (normalized) {
380 if (normalized.response !== undefined) {
381 setResponse(normalized.response)
382 }
383 if (normalized.context) {
384 ctx.context = safeObjectMerge(ctx.context, normalized.context)
385 }
386 }
387
388 return ctx
389 }
390
391 try {
392 await runNext()
393 const response = await waitForRequest(
394 getFinalResponse(),
395 signal,
396 disposeAbandonedResult,
397 )
398 if (signal.aborted) {
399 disposeAbandonedResult(response)
400 throw signal.reason
401 }
402 return { ctx, response }
403 } catch (err) {
404 const disposal = disposeStreamResponse(signal.aborted ? signal.reason : err)
405 if (signal.aborted) {
406 void disposal.catch(console.error)
407 } else {
408 await disposal
409 }
410 throw err
411 }
412}
413
414/**
415 * Wrap a route handler as middleware
416 */
417function handlerToMiddleware(
418 handler: RouteMethodHandlerFn<any, AnyRoute, any, any, any, any, any>,
419 mayDefer: boolean = false,
420): TODO {
421 if (mayDefer) {
422 return handler
423 }
424 return async (ctx: TODO) => {
425 const response = await handler({ ...ctx, next: throwIfMayNotDefer })
426 if (!response) {
427 throwRouteHandlerError()
428 }
429 return response
430 }
431}
432
433/**
434 * Creates the TanStack Start request handler.
435 *
436 * @example Backwards-compatible usage (handler callback only):
437 * ```ts
438 * export default createStartHandler(defaultStreamHandler)
439 * ```
440 *
441 * @example With CDN URL rewriting:
442 * ```ts
443 * export default createStartHandler({
444 * handler: defaultStreamHandler,
445 * transformAssets: 'https://cdn.example.com',
446 * })
447 * ```
448 *
449 * @example With per-request URL rewriting:
450 * ```ts
451 * export default createStartHandler({
452 * handler: defaultStreamHandler,
453 * transformAssets: {
454 * transform: ({ url }) => {
455 * const cdnBase = getRequest().headers.get('x-cdn-base') || ''
456 * return { href: `${cdnBase}${url}` }
457 * },
458 * cache: false,
459 * },
460 * })
461 * ```
462 */
463export function createStartHandler<TRegister = Register>(
464 cbOrOptions: HandlerCallback<AnyRouter> | CreateStartHandlerOptions,
465): RequestHandler<TRegister> {
466 const handlerOptions: FinalManifestOptions =
467 typeof cbOrOptions === 'function' ? {} : cbOrOptions
468 const cb: HandlerCallback<AnyRouter> =
469 typeof cbOrOptions === 'function' ? cbOrOptions : cbOrOptions.handler
470 const finalManifestResolver = createFinalManifestResolver({
471 ...handlerOptions,
472 cacheCreateTransform: process.env.TSS_DEV_SERVER !== 'true',
473 })
474 const resolveManifestForRequest =
475 process.env.TSS_DEV_SERVER === 'true'
476 ? finalManifestResolver.resolveUncached
477 : finalManifestResolver.resolveCached
478
479 if (process.env.TSS_DEV_SERVER !== 'true') {
480 finalManifestResolver.warmup({
481 getBaseManifest: () => getBaseManifest(undefined),
482 })
483 }
484
485 const startRequestResolver: RequestHandler<Register> = async (
486 request,
487 requestOpts,
488 ) => {
489 let router: AnyRouter | null = null as AnyRouter | null
490 let responseOwnsCleanup = false as boolean
491
492 try {
493 request.signal.throwIfAborted()
494 // normalizing and sanitizing the pathname here for server, so we always deal with the same format during SSR.
495 // during normalization paths like '//posts' are flattened to '/posts'.
496 // in these cases we would prefer to redirect to the new path
497 const { url, handledProtocolRelativeURL } = getNormalizedURL(request.url)
498 const href = url.pathname + url.search + url.hash
499 const origin = getOrigin(request)
500
501 if (handledProtocolRelativeURL) {
502 return Response.redirect(url, 308)
503 }
504
505 const entries = await waitForRequest(getEntries(), request.signal)
506 const hasStartInstance = !!entries.startEntry.startInstance
507 const startOptions: AnyStartInstanceOptions =
508 (await waitForRequest(
509 entries.startEntry.startInstance?.getOptions(),
510 request.signal,
511 )) || ({} as AnyStartInstanceOptions)
512
513 const { hasPluginAdapters, pluginSerializationAdapters } =
514 entries.pluginAdapters
515
516 const serializationAdapters = [
517 ...(startOptions.serializationAdapters || []),
518 ...(hasPluginAdapters ? pluginSerializationAdapters : []),
519 ServerFunctionSerializationAdapter,
520 ]
521
522 const requestStartOptions = {
523 ...startOptions,
524 requestMiddleware: hasStartInstance
525 ? startOptions.requestMiddleware
526 : [defaultCsrfMiddleware],
527 serializationAdapters,
528 }
529
530 // Flatten request middlewares once
531 const flattenedRequestMiddlewares = requestStartOptions.requestMiddleware
532 ? flattenMiddlewares(requestStartOptions.requestMiddleware)
533 : []
534
535 // Create set for deduplication
536 const executedRequestMiddlewares = new Set<TODO>(
537 flattenedRequestMiddlewares,
538 )
539
540 // Memoized router getter
541 const getRouter = async (): Promise<AnyRouter> => {
542 if (router) return router
543
544 router = await waitForRequest(
545 entries.routerEntry.getRouter(),
546 request.signal,
547 )
548
549 let isShell = IS_SHELL_ENV
550 if (IS_PRERENDERING && !isShell) {
551 isShell = request.headers.get(HEADERS.TSS_SHELL) === 'true'
552 }
553
554 const history = createServerHistory(href)
555
556 router.update({
557 history,
558 isShell,
559 isPrerendering: IS_PRERENDERING,
560 origin: router.options.origin ?? origin,
561 ...{
562 defaultSsr: requestStartOptions.defaultSsr,
563 serializationAdapters: [
564 ...requestStartOptions.serializationAdapters,
565 ...(router.options.serializationAdapters || []),
566 ],
567 },
568 basepath: ROUTER_BASEPATH,
569 })
570
571 return router
572 }
573
574 // Check for server function requests first (early exit)
575 if (SERVER_FN_BASE && url.pathname.startsWith(SERVER_FN_BASE)) {
576 if (
577 process.env.NODE_ENV !== 'production' &&
578 process.env.TSS_DISABLE_CSRF_MIDDLEWARE_WARNING !== 'true' &&
579 !hasCsrfMiddleware(flattenedRequestMiddlewares)
580 ) {
581 warnMissingCsrfMiddlewareOnce()
582 }
583
584 const serverFnId = url.pathname
585 .slice(SERVER_FN_BASE.length)
586 .split('/')[0]
587
588 if (!serverFnId) {
589 throw new Error('Invalid server action param for serverFnId')
590 }
591
592 const serverFnHandler = async ({ context }: TODO) => {
593 return runWithStartContext(
594 {
595 getRouter,
596 startOptions: requestStartOptions,
597 contextAfterGlobalMiddlewares: context,
598 request,
599 executedRequestMiddlewares,
600 handlerType: 'serverFn',
601 },
602 () =>
603 handleServerAction({
604 request,
605 context: requestOpts?.context,
606 serverFnId,
607 }),
608 )
609 }
610
611 const middlewares = flattenedRequestMiddlewares.map(
612 (d) => d.options.server,
613 )
614 const { response: middlewareResponse } = await executeMiddleware(
615 [...middlewares, serverFnHandler],
616 {
617 request,
618 pathname: url.pathname,
619 handlerType: 'serverFn',
620 context: createNullProtoObject(requestOpts?.context),
621 },
622 request.signal,
623 )
624
625 const result = await handleRedirectResponse(
626 middlewareResponse,
627 getRouter,
628 request.signal,
629 request.headers.get('x-tsr-serverFn') === 'true',
630 )
631 bindSsrResponseToRequest(router ?? undefined, result, request.signal)
632 request.signal.throwIfAborted()
633 responseOwnsCleanup = result.serverSsrCleanup === 'stream'
634 return result.response
635 }
636
637 // Router execution function
638 const executeRouter = async (
639 serverContext: TODO,
640 matchedRoutes?: ReadonlyArray<AnyRoute>,
641 ): Promise<SsrResponse> => {
642 const acceptHeader = request.headers.get('Accept') || '*/*'
643 const acceptParts = acceptHeader.split(',')
644 const supportedMimeTypes = ['*/*', 'text/html']
645
646 const isSupported = supportedMimeTypes.some((mimeType) =>
647 acceptParts.some((part) => part.trim().startsWith(mimeType)),
648 )
649
650 if (!isSupported) {
651 return normalizeSsrResponse(
652 Response.json(
653 { error: 'Only HTML requests are supported here' },
654 { status: 500 },
655 ),
656 )
657 }
658
659 const manifest = await waitForRequest(
660 resolveManifestForRequest({
661 request,
662 requestInlineCss: requestOpts?.inlineCss,
663 getBaseManifest: () => getBaseManifest(matchedRoutes),
664 }),
665 request.signal,
666 )
667
668 const earlyHints = createEarlyHintsForRequest({
669 onEarlyHints: requestOpts?.onEarlyHints,
670 responseLinkHeader: requestOpts?.responseLinkHeader,
671 })
672
673 earlyHints?.collectStatic({ manifest, matchedRoutes })
674
675 const routerInstance = await getRouter()
676
677 attachRouterServerSsrUtils({
678 router: routerInstance,
679 manifest,
680 getRequestAssets: () =>
681 getStartContext({ throwIfNotFound: false })?.requestAssets,
682 })
683
684 // `additionalContext` is request-scoped and only read from router.options
685 // during load; avoid a full router.update() and redundant location parse.
686 routerInstance.options.additionalContext = { serverContext }
687 await routerInstance.load({ _signal: request.signal })
688 request.signal.throwIfAborted()
689
690 if (routerInstance._serverResult?.type === 'redirect') {
691 return normalizeSsrResponse(routerInstance._serverResult.redirect)
692 }
693
694 earlyHints?.collectDynamic(
695 _getRenderedMatches(routerInstance.stores.matches.get()),
696 )
697
698 // Pass request-scoped assets to dehydrate for manifest injection
699 const ctx = getStartContext({ throwIfNotFound: false })
700 await waitForRequest(
701 routerInstance.serverSsr!.dehydrate({
702 requestAssets: ctx?.requestAssets,
703 }),
704 request.signal,
705 )
706 request.signal.throwIfAborted()
707
708 const responseHeaders = getStartResponseHeaders({
709 router: routerInstance,
710 })
711 earlyHints?.appendResponseHeaders(responseHeaders)
712 request.signal.throwIfAborted()
713 const response = await waitForRequest(
714 cb({
715 request,
716 router: routerInstance,
717 responseHeaders,
718 }),
719 request.signal,
720 (late) => disposeLateResponse(late, request.signal),
721 )
722 return normalizeSsrResponse(response)
723 }
724
725 // Main request handler
726 const requestHandlerMiddleware = async ({ context }: TODO) => {
727 return runWithStartContext(
728 {
729 getRouter,
730 startOptions: requestStartOptions,
731 contextAfterGlobalMiddlewares: context,
732 request,
733 executedRequestMiddlewares,
734 handlerType: 'router',
735 },
736 async () => {
737 try {
738 return await handleServerRoutes({
739 getRouter,
740 request,
741 url,
742 executeRouter,
743 context,
744 executedRequestMiddlewares,
745 })
746 } catch (err) {
747 if (err instanceof Response) {
748 return err
749 }
750 throw err
751 }
752 },
753 )
754 }
755
756 const middlewares = flattenedRequestMiddlewares.map(
757 (d) => d.options.server,
758 )
759 const { response: middlewareResponse } = await executeMiddleware(
760 [...middlewares, requestHandlerMiddleware],
761 {
762 request,
763 pathname: url.pathname,
764 handlerType: 'router',
765 context: createNullProtoObject(requestOpts?.context),
766 },
767 request.signal,
768 )
769
770 const response = await handleRedirectResponse(
771 middlewareResponse,
772 getRouter,
773 request.signal,
774 false,
775 )
776 bindSsrResponseToRequest(router ?? undefined, response, request.signal)
777 request.signal.throwIfAborted()
778 responseOwnsCleanup = response.serverSsrCleanup === 'stream'
779 return response.response
780 } finally {
781 if (router?.serverSsr && !responseOwnsCleanup) {
782 // Clean up router SSR state if it was set up but won't be cleaned up by the callback
783 // (e.g., in redirect cases or early returns before the callback is invoked).
784 // Transformed streaming response bodies clean up when consumed/cancelled.
785 router.serverSsr.cleanup()
786 }
787 router = null
788 }
789 }
790
791 return requestHandler(startRequestResolver)
792}
793
794const relativeRedirectProtocols = new Set<string>()
795
796async function handleRedirectResponse(
797 response: HandlerCallbackResult,
798 getRouter: () => Promise<AnyRouter>,
799 signal: AbortSignal,
800 serializeRedirect: boolean,
801): Promise<SsrResponse> {
802 signal.throwIfAborted()
803 const ssrResponse = normalizeSsrResponse(response)
804 if (!isRedirect(ssrResponse.response)) {
805 return ssrResponse
806 }
807
808 const opts = ssrResponse.response.options
809 const href = ssrResponse.response.headers.get('Location') || opts.href
810 if (
811 !href &&
812 opts.to &&
813 typeof opts.to === 'string' &&
814 !opts.to.startsWith('/')
815 ) {
816 throw new Error(
817 `Server side redirects must use absolute paths via the 'href' or 'to' options. The redirect() method's "to" property accepts an internal path only. Use the "href" property to provide an external URL. Received: ${JSON.stringify(opts)}`,
818 )
819 }
820
821 if (
822 !href &&
823 ['params', 'search', 'hash'].some(
824 (d) => typeof (opts as TODO)[d] === 'function',
825 )
826 ) {
827 throw new Error(
828 `Server side redirects must use static search, params, and hash values and do not support functional values. Received functional values for: ${Object.keys(
829 opts,
830 )
831 .filter((d) => typeof (opts as TODO)[d] === 'function')
832 .map((d) => `"${d}"`)
833 .join(', ')}`,
834 )
835 }
836
837 signal.throwIfAborted()
838 let redirect = ssrResponse.response
839 // Unambiguous relative hrefs need no route resolution or protocol policy.
840 // Every scheme falls back to the router to honor its custom allowlist.
841 if (href && !isDangerousProtocol(href, relativeRedirectProtocols)) {
842 redirect.options.href = href
843 redirect.headers.set('Location', href)
844 } else {
845 const router = await waitForRequest(getRouter(), signal)
846 signal.throwIfAborted()
847 redirect = router.resolveRedirect(redirect)
848 }
849
850 if (serializeRedirect) {
851 const redirectOptions = { ...(redirect.options as TODO) }
852 delete redirectOptions.headers
853 const responseHeaders = new Headers(redirect.headers)
854 responseHeaders.set('content-type', 'application/json')
855 return waitForRequest(
856 replaceSsrResponse(
857 ssrResponse,
858 Response.json(
859 {
860 ...redirectOptions,
861 isSerializedRedirect: true,
862 },
863 { headers: responseHeaders },
864 ),
865 'redirect response replaced',
866 ),
867 signal,
868 )
869 }
870
871 return waitForRequest(
872 replaceSsrResponse(ssrResponse, redirect, 'redirect response replaced'),
873 signal,
874 )
875}
876
877async function handleServerRoutes({
878 getRouter,
879 request,
880 url,
881 executeRouter,
882 context,
883 executedRequestMiddlewares,
884}: {
885 getRouter: () => Promise<AnyRouter>
886 request: Request
887 url: URL
888 executeRouter: (
889 serverContext: any,
890 matchedRoutes?: ReadonlyArray<AnyRoute>,
891 ) => Promise<SsrResponse>
892 context: any
893 executedRequestMiddlewares: Set<AnyRequestMiddleware>
894}): Promise<SsrResponse> {
895 const router = await getRouter()
896 const rewrittenUrl = executeRewriteInput(router.rewrite, url)
897 const pathname = rewrittenUrl.pathname
898 // this will perform a fuzzy match, however for server routes we need an exact match
899 // if the route is not an exact match, executeRouter will handle rendering the app router
900 // the match will be cached internally, so no extra work is done during the app router render
901 const [matchedRoutes, rawParams, foundRoute] =
902 router.getMatchedRoutes(pathname)
903
904 const isExactMatch = foundRoute && rawParams['**'] === undefined
905
906 // Collect and dedupe route middlewares
907 const routeMiddlewares: Array<AnyMiddlewareServerFn> = []
908
909 // Collect middleware from matched routes, filtering out those already executed
910 // in the request phase
911 for (const route of matchedRoutes) {
912 const serverMiddleware = route.options.server?.middleware as
913 | Array<AnyRequestMiddleware>
914 | undefined
915 if (serverMiddleware) {
916 const flattened = flattenMiddlewares(serverMiddleware)
917 for (const m of flattened) {
918 if (!executedRequestMiddlewares.has(m)) {
919 routeMiddlewares.push(m.options.server)
920 }
921 }
922 }
923 }
924
925 // Add handler middleware if exact match
926 const server = foundRoute?.options.server
927 let isHeadFallback = false
928 if (server?.handlers && isExactMatch) {
929 const handlers =
930 typeof server.handlers === 'function'
931 ? server.handlers({ createHandlers: (d: any) => d })
932 : server.handlers
933
934 const requestMethod = request.method.toUpperCase() as RouteMethod
935 // Per RFC 9110 §9.3.2, HEAD must return the same header fields as GET.
936 // Priority for HEAD: explicit HEAD handler → GET → ANY (last resort).
937 const handler =
938 requestMethod === 'HEAD'
939 ? (handlers['HEAD'] ?? handlers['GET'] ?? handlers['ANY'])
940 : (handlers[requestMethod] ?? handlers['ANY'])
941 isHeadFallback =
942 requestMethod === 'HEAD' && handler !== undefined && !handlers['HEAD']
943
944 if (handler) {
945 const mayDefer = !!foundRoute.options.component
946
947 if (typeof handler === 'function') {
948 routeMiddlewares.push(handlerToMiddleware(handler, mayDefer))
949 } else {
950 if (handler.middleware?.length) {
951 const handlerMiddlewares = flattenMiddlewares(handler.middleware)
952 for (const m of handlerMiddlewares) {
953 routeMiddlewares.push(m.options.server)
954 }
955 }
956 if (handler.handler) {
957 routeMiddlewares.push(handlerToMiddleware(handler.handler, mayDefer))
958 }
959 }
960 }
961 }
962
963 // Final middleware: execute router with matched routes for dev styles
964 routeMiddlewares.push(((ctx: TODO) =>
965 executeRouter(ctx.context, matchedRoutes)) as TODO)
966
967 const { ctx, response } = await executeMiddleware(
968 routeMiddlewares,
969 {
970 request,
971 context,
972 params: rawParams,
973 pathname,
974 handlerType: 'router',
975 },
976 request.signal,
977 )
978
979 // RFC 9110 §9.3.2: HEAD must carry the same header fields as GET but no body.
980 // Resolve any redirect before stripping so the Location header survives.
981 if (isHeadFallback) {
982 if (!ctx.response) {
983 throwRouteHandlerError()
984 }
985
986 const resolved = await handleRedirectResponse(
987 response,
988 getRouter,
989 request.signal,
990 false,
991 )
992 return waitForRequest(
993 stripSsrResponseBody(resolved, 'HEAD body stripped'),
994 request.signal,
995 )
996 }
997
998 return normalizeSsrResponse(response)
999}