Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

createStartHandler.ts

1,042 lines31.4 KB

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 isPromise,
15 isRedirect,
16} from '@tanstack/router-core'
17import {
18 attachRouterServerSsrUtils,
19 bindSsrResponseToRequest,
20 disposeSsrResponse,
21 getNormalizedURL,
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>
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
87​
88interface PluginAdaptersEntry {
89 hasPluginAdapters: boolean
90 pluginSerializationAdapters: Array<AnySerializationAdapter>
92​
93interface Entries {
94 startEntry: StartEntry
95 routerEntry: RouterEntry
96 pluginAdapters: PluginAdaptersEntry
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(),
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 }
133​
134function getEntries() {
135 if (!entriesPromise) {
136 entriesPromise = loadEntries()
137 }
138 return entriesPromise
140​
141function hasCsrfMiddleware(
142 middlewares: Array<AnyRequestMiddleware | AnyFunctionMiddleware>,
143): boolean {
144 return middlewares.some((middleware) => csrfSymbol in middleware)
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 })`)
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)
193​
194function throwIfMayNotDefer(): never {
195 throw new Error(ERR_NO_DEFER)
197​
198function getResponseFromResult(result: TODO): TODO {
199 return isSsrResponse(result) || result instanceof Response
200 ? result
201 : result?.response
203​
204type StreamSsrResponse = Extract<SsrResponse, { serverSsrCleanup: 'stream' }>
205​
206type ResponseBody = NonNullable<Response['body']>
207type ResponseWithBody = Response & { readonly body: ResponseBody }
208​
209/** The context object threaded through one middleware pipeline. */
210interface PipelineContext {
211 request: Request
212 pathname: string
213 handlerType: 'serverFn' | 'router'
214 context: Record<string, unknown>
215 params?: Record<string, unknown>
216 response?: Response
217 // Middleware may add arbitrary own properties through `next(ctx)`.
218 [key: string]: unknown
220​
221interface MiddlewareResponseOwnership {
222 response: ResponseWithBody
223 sourceBody: ResponseBody
224 streamResponse?: StreamSsrResponse
226​
227// Entries are released with their response; the map is never cleared by hand.
228const responseBodySources = new WeakMap<Response, Response>()
229​
230function disposeResponseResult(result: TODO, reason: unknown): void {
231 const response = getResponseFromResult(result)
232 if (isSsrResponse(response) || response instanceof Response) {
233 disposeSsrResponse(response, reason)
234 }
236​
237/**
238 * Marks `response` as directly derived from the current `source`.
239 * Middleware must consume or cancel any other `clone()` or `tee()` branches.
240 */
241export function transferResponseBodyOwnership<TResponse extends Response>(
242 source: Response,
243 response: TResponse,
244): TResponse {
245 if (!source.body || !response.body) {
246 throw new Error('Response body ownership requires two response bodies')
247 }
248 responseBodySources.set(response, source)
249 return response
251​
252function hasResponseBody(value: unknown): value is ResponseWithBody {
253 return value instanceof Response && value.body !== null
255​
256function inheritsResponseOwnership(
257 ownership: MiddlewareResponseOwnership,
258 candidate: unknown,
259): candidate is ResponseWithBody {
260 return (
261 hasResponseBody(candidate) &&
262 (candidate.body === ownership.response.body ||
263 responseBodySources.get(candidate) === ownership.response)
264 )
266​
267function disposeResponseOwnership(
268 ownership: MiddlewareResponseOwnership,
269 reason: unknown,
270): void {
271 const { response, sourceBody, streamResponse } = ownership
272 streamResponse?.dispose(reason)
273 if (!streamResponse || response.body !== sourceBody) {
274 void response.body.cancel(reason).catch(() => {})
275 }
277​
278function getOwnedResponse(
279 ownership: MiddlewareResponseOwnership,
280): HandlerCallbackResult {
281 const { response, sourceBody, streamResponse } = ownership
282 if (!streamResponse) {
283 return response
284 }
285 if (streamResponse.response === response && response.body === sourceBody) {
286 return streamResponse
287 }
288 if (response.body === sourceBody) {
289 return { ...streamResponse, response }
290 }
291 return {
292 ...streamResponse,
293 response,
294 dispose(reason): undefined {
295 disposeResponseOwnership(ownership, reason)
296 },
297 }
299​
300function createLateResponseDisposer(signal: AbortSignal) {
301 return (result: TODO) => disposeResponseResult(result, signal.reason)
303​
304/**
305 * Compose middleware around a terminal response handler. With no middleware
306 * the terminal runs directly.
307 */
308async function executeMiddleware(
309 middlewares: Array<TODO>,
310 terminal: TODO,
311 ctx: PipelineContext,
312 signal: AbortSignal,
313 terminalNext?: TODO,
314): Promise<HandlerCallbackResult> {
315 let index = -1
316 let responseOwnership: MiddlewareResponseOwnership | undefined
317 // Once the pipeline returned, the HTTP runtime owns the response. A result
318 // that settles later (for example the loser of a `Promise.race`) must not
319 // replace or cancel it.
320 let settled = false
321 const disposeAbandonedResult = createLateResponseDisposer(signal)
322​
323 const setResponse = (response: TODO) => {
324 const ssrResponse = isSsrResponse(response) ? response : undefined
325 const streamResponse =
326 ssrResponse?.serverSsrCleanup === 'stream' ? ssrResponse : undefined
327 const exposed: Response | undefined = ssrResponse
328 ? ssrResponse.response
329 : response
330 const current = responseOwnership
331​
332 if (settled) {
333 if (exposed !== ctx.response) {
334 disposeResponseResult(response, 'late middleware response')
335 }
336 return
337 }
338 if (current && current.response === exposed) {
339 current.streamResponse ??= streamResponse
340 } else if (current && inheritsResponseOwnership(current, exposed)) {
341 current.response = exposed
342 current.streamResponse ??= streamResponse
343 } else {
344 if (current) {
345 disposeResponseOwnership(current, 'middleware response replaced')
346 }
347 if (hasResponseBody(exposed)) {
348 responseOwnership = {
349 response: exposed,
350 sourceBody: exposed.body,
351 streamResponse,
352 }
353 } else {
354 responseOwnership = undefined
355 }
356 }
357 ctx.response = exposed
358 }
359​
360 const reconcileCtxResponse = () => {
361 if (ctx.response !== responseOwnership?.response) {
362 setResponse(ctx.response)
363 }
364 }
365​
366 let nextPromise: Promise<TODO> | undefined
367​
368 function next(nextCtx?: TODO): Promise<TODO> {
369 const result = runNext(nextCtx)
370 nextPromise = result
371 return result
372 }
373​
374 async function runNext(nextCtx?: TODO): Promise<TODO> {
375 signal.throwIfAborted()
376​
377 // Merge context if provided using safeObjectMerge for prototype pollution prevention
378 if (nextCtx) {
379 if (nextCtx.context) {
380 ctx.context = safeObjectMerge(ctx.context, nextCtx.context)
381 }
382 // Copy own properties except context (Object.keys returns only own enumerable properties)
383 for (const key of Object.keys(nextCtx)) {
384 if (key === 'response') {
385 setResponse(nextCtx.response)
386 } else if (key !== 'context') {
387 ctx[key] = nextCtx[key]
388 }
389 }
390 }
391​
392 index++
393 const isTerminal = index === middlewares.length
394 const middleware =
395 index < middlewares.length
396 ? middlewares[index]
397 : isTerminal
398 ? terminal
399 : undefined
400 const middlewareNext = isTerminal && terminalNext ? terminalNext : next
401 if (!middleware) {
402 return ctx
403 }
404​
405 let result: TODO
406 try {
407 const pending = middleware({ ...ctx, next: middlewareNext })
408 // A directly returned next() promise already propagates request aborts.
409 if (nextPromise && pending === nextPromise) {
410 nextPromise = undefined
411 await pending
412 if (signal.aborted) {
413 throw signal.reason
414 }
415 return ctx
416 } else if (!isPromise(pending)) {
417 result = pending
418 signal.throwIfAborted()
419 } else {
420 result = await waitForRequest(
421 pending,
422 signal,
423 disposeAbandonedResult,
424 disposeAbandonedResult,
425 )
426 }
427 } catch (err) {
428 reconcileCtxResponse()
429 if (signal.aborted) {
430 if (result !== undefined) {
431 disposeAbandonedResult(result)
432 }
433 if (err !== signal.reason) {
434 disposeAbandonedResult(err)
435 }
436 throw signal.reason
437 }
438 if (err instanceof Response) {
439 setResponse(err)
440 return ctx
441 }
442 throw err
443 }
444​
445 if (isTerminal && terminalNext && !result) {
446 throwRouteHandlerError()
447 }
448​
449 reconcileCtxResponse()
450 if (result && result !== ctx) {
451 const response = getResponseFromResult(result)
452 if (response !== undefined && response !== ctx.response) {
453 setResponse(response)
454 }
455 if (
456 response !== result &&
457 result.context &&
458 result.context !== ctx.context
459 ) {
460 ctx.context = safeObjectMerge(ctx.context, result.context)
461 }
462 }
463​
464 return ctx
465 }
466​
467 try {
468 await runNext()
469 const response = ctx.response
470 if (!response) {
471 throwRouteHandlerError()
472 }
473 reconcileCtxResponse()
474 if (signal.aborted) {
475 throw signal.reason
476 }
477 settled = true
478 return responseOwnership ? getOwnedResponse(responseOwnership) : response
479 } catch (err) {
480 settled = true
481 if (responseOwnership) {
482 disposeResponseOwnership(
483 responseOwnership,
484 signal.aborted ? signal.reason : err,
485 )
486 }
487 throw err
488 }
490​
491/**
492 * Creates the TanStack Start request handler.
493 *
494 * @example Backwards-compatible usage (handler callback only):
495 * ```ts
496 * export default createStartHandler(defaultStreamHandler)
497 * ```
498 *
499 * @example With CDN URL rewriting:
500 * ```ts
501 * export default createStartHandler({
502 * handler: defaultStreamHandler,
503 * transformAssets: 'https://cdn.example.com',
504 * })
505 * ```
506 *
507 * @example With per-request URL rewriting:
508 * ```ts
509 * export default createStartHandler({
510 * handler: defaultStreamHandler,
511 * transformAssets: {
512 * transform: ({ url }) => {
513 * const cdnBase = getRequest().headers.get('x-cdn-base') || ''
514 * return { href: `${cdnBase}${url}` }
515 * },
516 * cache: false,
517 * },
518 * })
519 * ```
520 */
521export function createStartHandler<TRegister = Register>(
522 cbOrOptions: HandlerCallback<AnyRouter> | CreateStartHandlerOptions,
523): RequestHandler<TRegister> {
524 const handlerOptions: FinalManifestOptions =
525 typeof cbOrOptions === 'function' ? {} : cbOrOptions
526 const cb: HandlerCallback<AnyRouter> =
527 typeof cbOrOptions === 'function' ? cbOrOptions : cbOrOptions.handler
528 const finalManifestResolver = createFinalManifestResolver({
529 ...handlerOptions,
530 cacheCreateTransform: process.env.TSS_DEV_SERVER !== 'true',
531 })
532 const resolveManifestForRequest =
533 process.env.TSS_DEV_SERVER === 'true'
534 ? finalManifestResolver.resolveUncached
535 : finalManifestResolver.resolveCached
536​
537 if (process.env.TSS_DEV_SERVER !== 'true') {
538 finalManifestResolver.warmup({
539 getBaseManifest: () => getBaseManifest(undefined),
540 })
541 }
542​
543 const startRequestResolver: RequestHandler<Register> = async (
544 request,
545 requestOpts,
546 ) => {
547 const signal = request.signal
548 let router: AnyRouter | undefined
549 let routerPromise: Promise<AnyRouter> | undefined
550 let responseOwnsCleanup = false
551​
552 try {
553 signal.throwIfAborted()
554 // normalizing and sanitizing the pathname here for server, so we always deal with the same format during SSR.
555 // during normalization paths like '//posts' are flattened to '/posts'.
556 // in these cases we would prefer to redirect to the new path
557 const { url, handledProtocolRelativeURL } = getNormalizedURL(request.url)
558 const href = url.pathname + url.search + url.hash
559 const origin = url.origin
560​
561 if (handledProtocolRelativeURL) {
562 return Response.redirect(url, 308)
563 }
564​
565 const entries = await waitForRequest(getEntries(), signal)
566 const isServerFnRequest =
567 !!SERVER_FN_BASE && url.pathname.startsWith(SERVER_FN_BASE)
568 const startInstance = entries.startEntry.startInstance
569 let startOptions: AnyStartInstanceOptions
570 if (startInstance) {
571 const pendingStartOptions = startInstance.getOptions()
572 startOptions = isPromise(pendingStartOptions)
573 ? await waitForRequest(pendingStartOptions, signal)
574 : pendingStartOptions
575 signal.throwIfAborted()
576 } else {
577 startOptions = {} as AnyStartInstanceOptions
578 }
579​
580 const { hasPluginAdapters, pluginSerializationAdapters } =
581 entries.pluginAdapters
582​
583 const serializationAdapters = [
584 ...(startOptions.serializationAdapters || []),
585 ...(hasPluginAdapters ? pluginSerializationAdapters : []),
586 ServerFunctionSerializationAdapter,
587 ]
588​
589 const requestStartOptions = {
590 ...startOptions,
591 requestMiddleware: startInstance
592 ? startOptions.requestMiddleware
593 : isServerFnRequest
594 ? [defaultCsrfMiddleware]
595 : undefined,
596 serializationAdapters,
597 }
598​
599 // Flatten request middlewares once
600 const flattenedRequestMiddlewares = requestStartOptions.requestMiddleware
601 ? flattenMiddlewares(requestStartOptions.requestMiddleware)
602 : []
603​
604 // Create set for deduplication
605 const executedRequestMiddlewares = new Set<TODO>(
606 flattenedRequestMiddlewares,
607 )
608​
609 // Memoized router getter
610 const getRouter = (): Promise<AnyRouter> => {
611 routerPromise ??= (async () => {
612 signal.throwIfAborted()
613 const requestRouter = await waitForRequest(
614 entries.routerEntry.getRouter(),
615 signal,
616 )
617​
618 let isShell = IS_SHELL_ENV
619 if (IS_PRERENDERING && !isShell) {
620 isShell = request.headers.get(HEADERS.TSS_SHELL) === 'true'
621 }
622​
623 const history = createServerHistory(href)
624​
625 requestRouter.update({
626 history,
627 isShell,
628 isPrerendering: IS_PRERENDERING,
629 origin: requestRouter.options.origin ?? origin,
630 // Start-owned options that RouterConstructorOptions omits.
631 ...{
632 defaultSsr: requestStartOptions.defaultSsr,
633 serializationAdapters: [
634 ...requestStartOptions.serializationAdapters,
635 ...(requestRouter.options.serializationAdapters || []),
636 ],
637 },
638 basepath: ROUTER_BASEPATH,
639 })
640​
641 router = requestRouter
642 return requestRouter
643 })()
644​
645 return routerPromise
646 }
647​
648 const handlerType = isServerFnRequest
649 ? ('serverFn' as const)
650 : ('router' as const)
651 const startContext = {
652 getRouter,
653 startOptions: requestStartOptions,
654 request,
655 executedRequestMiddlewares,
656 handlerType,
657 }
658 let terminal: (ctx: PipelineContext) => unknown
659​
660 if (isServerFnRequest) {
661 if (
662 process.env.NODE_ENV !== 'production' &&
663 process.env.TSS_DISABLE_CSRF_MIDDLEWARE_WARNING !== 'true' &&
664 !hasCsrfMiddleware(flattenedRequestMiddlewares)
665 ) {
666 warnMissingCsrfMiddlewareOnce()
667 }
668​
669 const serverFnId = url.pathname
670 .slice(SERVER_FN_BASE.length)
671 .split('/')[0]
672​
673 if (!serverFnId) {
674 throw new Error('Invalid server action param for serverFnId')
675 }
676​
677 terminal = ({ context }) =>
678 runWithStartContext(
679 { ...startContext, contextAfterGlobalMiddlewares: context },
680 () =>
681 handleServerAction({
682 request,
683 context: requestOpts?.context,
684 serverFnId,
685 }),
686 )
687 } else {
688 const executeRouter = async (
689 serverContext: TODO,
690 matchedRoutes?: ReadonlyArray<AnyRoute>,
691 ): Promise<SsrResponse> => {
692 if (
693 !/(^|,)\s*(\*\/\*|text\/html)/.test(
694 request.headers.get('Accept') || '*/*',
695 )
696 ) {
697 return normalizeSsrResponse(
698 Response.json(
699 { error: 'Only HTML requests are supported here' },
700 { status: 406 },
701 ),
702 )
703 }
704​
705 const manifest = await waitForRequest(
706 resolveManifestForRequest({
707 request,
708 requestInlineCss: requestOpts?.inlineCss,
709 getBaseManifest: () => getBaseManifest(matchedRoutes),
710 }),
711 signal,
712 )
713​
714 const earlyHints = createEarlyHintsForRequest({
715 onEarlyHints: requestOpts?.onEarlyHints,
716 responseLinkHeader: requestOpts?.responseLinkHeader,
717 })
718​
719 earlyHints?.collectStatic({ manifest, matchedRoutes })
720​
721 const routerInstance = await getRouter()
722​
723 attachRouterServerSsrUtils({
724 router: routerInstance,
725 manifest,
726 getRequestAssets: () =>
727 getStartContext({ throwIfNotFound: false })?.requestAssets,
728 })
729​
730 // `additionalContext` is request-scoped and only read from router.options
731 // during load; avoid a full router.update() and redundant location parse.
732 routerInstance.options.additionalContext = { serverContext }
733 await routerInstance.load({ _signal: signal })
734 signal.throwIfAborted()
735​
736 if (routerInstance._serverResult?.type === 'redirect') {
737 return normalizeSsrResponse(routerInstance._serverResult.redirect)
738 }
739​
740 earlyHints?.collectDynamic(
741 _getRenderedMatches(routerInstance.stores.matches.get()),
742 )
743​
744 // Pass request-scoped assets to dehydrate for manifest injection
745 const ctx = getStartContext({ throwIfNotFound: false })
746 await routerInstance.serverSsr!.dehydrate({
747 requestAssets: ctx?.requestAssets,
748 signal,
749 })
750 signal.throwIfAborted()
751​
752 const responseHeaders = getStartResponseHeaders({
753 router: routerInstance,
754 })
755 earlyHints?.appendResponseHeaders(responseHeaders)
756 signal.throwIfAborted()
757 const disposeLate = createLateResponseDisposer(signal)
758 const response = await waitForRequest(
759 cb({
760 request,
761 router: routerInstance,
762 responseHeaders,
763 }),
764 signal,
765 disposeLate,
766 disposeLate,
767 )
768 return normalizeSsrResponse(response)
769 }
770​
771 terminal = ({ context }) =>
772 runWithStartContext(
773 { ...startContext, contextAfterGlobalMiddlewares: context },
774 () =>
775 handleServerRoutes({
776 getRouter,
777 request,
778 url,
779 executeRouter,
780 context,
781 executedRequestMiddlewares,
782 }),
783 )
784 }
785​
786 const middlewareResponse = await executeMiddleware(
787 flattenedRequestMiddlewares.map((d) => d.options.server),
788 terminal,
789 {
790 request,
791 pathname: url.pathname,
792 handlerType,
793 context: createNullProtoObject(requestOpts?.context),
794 },
795 signal,
796 )
797​
798 let result: SsrResponse
799 try {
800 result = await handleRedirectResponse(
801 middlewareResponse,
802 getRouter,
803 signal,
804 isServerFnRequest && request.headers.get('x-tsr-serverFn') === 'true',
805 )
806 if (request.method === 'HEAD') {
807 result = stripSsrResponseBody(result, 'HEAD body stripped')
808 }
809 } catch (error) {
810 disposeResponseResult(
811 middlewareResponse,
812 signal.aborted ? signal.reason : error,
813 )
814 throw error
815 }
816 bindSsrResponseToRequest(router, result, signal)
817 signal.throwIfAborted()
818 responseOwnsCleanup = result.serverSsrCleanup === 'stream'
819 return result.response
820 } finally {
821 if (router?.serverSsr && !responseOwnsCleanup) {
822 // Clean up router SSR state if it was set up but won't be cleaned up by the callback
823 // (e.g., in redirect cases or early returns before the callback is invoked).
824 // Transformed streaming response bodies clean up when consumed/cancelled.
825 router.serverSsr.cleanup()
826 }
827 // `routerPromise` stays memoized: a streamed Suspense boundary or a late
828 // server function may still ask for this request's router.
829 }
830 }
831​
832 return requestHandler(startRequestResolver)
834​
835const relativeRedirectProtocols = new Set<string>()
836​
837async function handleRedirectResponse(
838 response: HandlerCallbackResult,
839 getRouter: () => Promise<AnyRouter>,
840 signal: AbortSignal,
841 serializeRedirect: boolean,
842): Promise<SsrResponse> {
843 signal.throwIfAborted()
844 const ssrResponse = normalizeSsrResponse(response)
845 const redirect = ssrResponse.response
846 if (!isRedirect(redirect)) {
847 return ssrResponse
848 }
849​
850 const opts = redirect.options
851 const href = redirect.headers.get('Location') || opts.href
852 if (
853 !href &&
854 opts.to &&
855 typeof opts.to === 'string' &&
856 !opts.to.startsWith('/')
857 ) {
858 throw new Error(
859 `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)}`,
860 )
861 }
862​
863 if (
864 !href &&
865 ['params', 'search', 'hash'].some(
866 (d) => typeof (opts as TODO)[d] === 'function',
867 )
868 ) {
869 throw new Error(
870 `Server side redirects must use static search, params, and hash values and do not support functional values. Received functional values for: ${Object.keys(
871 opts,
872 )
873 .filter((d) => typeof (opts as TODO)[d] === 'function')
874 .map((d) => `"${d}"`)
875 .join(', ')}`,
876 )
877 }
878​
879 signal.throwIfAborted()
880 // Unambiguous relative hrefs need no route resolution or protocol policy.
881 // Every scheme falls back to the router to honor its custom allowlist.
882 if (href && !isDangerousProtocol(href, relativeRedirectProtocols)) {
883 opts.href = href
884 redirect.headers.set('Location', href)
885 } else {
886 const router = await getRouter()
887 signal.throwIfAborted()
888 // Resolves `redirect` in place.
889 router.resolveRedirect(redirect)
890 }
891​
892 if (serializeRedirect) {
893 const redirectOptions = { ...(opts as TODO) }
894 delete redirectOptions.headers
895 const responseHeaders = new Headers(redirect.headers)
896 responseHeaders.set('content-type', 'application/json')
897 return replaceSsrResponse(
898 ssrResponse,
899 Response.json(
900 { ...redirectOptions, isSerializedRedirect: true },
901 { headers: responseHeaders },
902 ),
903 'redirect response replaced',
904 )
905 }
906​
907 return ssrResponse
909​
910function withParsedParams(
911 handler: RouteMethodHandlerFn<any, AnyRoute, any, any, any, any, any>,
912 matchedRoutes: ReadonlyArray<AnyRoute>,
913): TODO {
914 if (
915 !matchedRoutes.some(
916 (route) => route.options.params?.parse ?? route.options.parseParams,
917 )
918 ) {
919 return handler
920 }
921​
922 return (ctx: TODO) => {
923 // Parse inside the pipeline so middleware can catch errors. Keep the raw
924 // params for app-router validation when the handler defers to rendering.
925 const params = Object.assign(Object.create(null), ctx.params)
926 for (const route of matchedRoutes) {
927 const parse = route.options.params?.parse ?? route.options.parseParams
928 if (parse) {
929 Object.assign(params, parse(params))
930 }
931 }
932 return handler({ ...ctx, params })
933 }
935​
936async function handleServerRoutes({
937 getRouter,
938 request,
939 url,
940 executeRouter,
941 context,
942 executedRequestMiddlewares,
943}: {
944 getRouter: () => Promise<AnyRouter>
945 request: Request
946 url: URL
947 executeRouter: (
948 serverContext: any,
949 matchedRoutes?: ReadonlyArray<AnyRoute>,
950 ) => Promise<SsrResponse>
951 context: any
952 executedRequestMiddlewares: Set<AnyRequestMiddleware>
953}): Promise<SsrResponse> {
954 const router = await getRouter()
955 const rewrittenUrl = executeRewriteInput(router.rewrite, url)
956 const pathname = rewrittenUrl.pathname
957 // this will perform a fuzzy match, however for server routes we need an exact match
958 // if the route is not an exact match, executeRouter will handle rendering the app router
959 // the match will be cached internally, so no extra work is done during the app router render
960 const [matchedRoutes, rawParams, foundRoute] =
961 router.getMatchedRoutes(pathname)
962​
963 const isExactMatch = foundRoute && rawParams['**'] === undefined
964​
965 // Collect and dedupe route middlewares
966 const routeMiddlewares: Array<AnyMiddlewareServerFn> = []
967 let terminalHandler: TODO = (ctx: TODO) =>
968 executeRouter(ctx.context, matchedRoutes)
969 let terminalNext: TODO
970​
971 // Collect middleware from matched routes, filtering out those already executed
972 // in the request phase
973 for (const route of matchedRoutes) {
974 const serverMiddleware = route.options.server?.middleware as
975 | Array<AnyRequestMiddleware>
976 | undefined
977 if (serverMiddleware) {
978 const flattened = flattenMiddlewares(serverMiddleware)
979 for (const m of flattened) {
980 if (!executedRequestMiddlewares.has(m)) {
981 routeMiddlewares.push(m.options.server)
982 }
983 }
984 }
985 }
986​
987 // Add handler middleware if exact match
988 const server = foundRoute?.options.server
989 if (server?.handlers && isExactMatch) {
990 const handlers =
991 typeof server.handlers === 'function'
992 ? server.handlers({ createHandlers: (d: any) => d })
993 : server.handlers
994​
995 const requestMethod = request.method.toUpperCase() as RouteMethod
996 // Per RFC 9110 Β§9.3.2, HEAD must return the same header fields as GET.
997 // Priority for HEAD: explicit HEAD handler β†’ GET β†’ ANY (last resort).
998 const handler =
999 requestMethod === 'HEAD'
1000 ? (handlers['HEAD'] ?? handlers['GET'] ?? handlers['ANY'])
1001 : (handlers[requestMethod] ?? handlers['ANY'])
1002 if (handler) {
1003 const mayDefer = !!foundRoute.options.component
1004​
1005 if (typeof handler !== 'function') {
1006 if (handler.middleware?.length) {
1007 const handlerMiddlewares = flattenMiddlewares(handler.middleware)
1008 for (const m of handlerMiddlewares) {
1009 routeMiddlewares.push(m.options.server)
1013 const routeHandler =
1014 typeof handler === 'function' ? handler : handler.handler
1015 if (routeHandler) {
1016 const parsedHandler = withParsedParams(routeHandler, matchedRoutes)
1017 if (!mayDefer) {
1018 terminalHandler = parsedHandler
1019 terminalNext = throwIfMayNotDefer
1020 } else {
1021 routeMiddlewares.push(parsedHandler)
1026​
1027 const response = await executeMiddleware(
1028 routeMiddlewares,
1029 terminalHandler,
1031 request,
1032 context,
1033 params: rawParams,
1034 pathname,
1035 handlerType: 'router',
1036 },
1037 request.signal,
1038 terminalNext,
1040​
1041 return normalizeSsrResponse(response)