Open History to see the last commit
1import { createServerHistory } from '@tanstack/history'
2import {
3 X_TSS_RAW_RESPONSE,
4 X_TSS_SERIALIZED,
5 createCsrfMiddleware,
6 createNullProtoObject,
7 csrfSymbol,
8 flattenMiddlewares,
9 mergeHeaders,
10 safeObjectMerge,
11} from '@tanstack/start-client-core'
12import {
13 _getRenderedMatches,
14 executeRewriteInput,
15 isDangerousProtocol,
16 isPromise,
17 isRedirect,
18} from '@tanstack/router-core'
19import {
20 attachRouterServerSsrUtils,
21 bindSsrResponseToRequest,
22 disposeSsrResponse,
23 getNormalizedURL,
24 isSsrResponse,
25 normalizeSsrResponse,
26 stripSsrResponseBody,
27 waitForRequest,
28} from '@tanstack/router-core/ssr/server'
29import {
30 getStartContext,
31 runWithStartContext,
32} from '@tanstack/start-storage-context'
33import {
34 createFinalizedResponse,
35 finalizeResponse,
36 reconcileResponse,
37 restoreResponseProtocol,
38 transferResponseMetadata,
39 transferResponseProtocol,
40 withStartRequest,
41} from './internal-request-response'
42import { getStartManifest } from './router-manifest'
43import {
44 DeferredResponse,
45 createServerFnErrorResponse,
46 handleServerAction,
47 toThrownServerFnResponse,
48} from './server-functions-handler'
49import { createEarlyHintsCollector } from './early-hints'
50import {
51 createCachedBaseManifestLoader,
52 createFinalManifestResolver,
53} from './finalManifest'
54β
55import { HEADERS } from './constants'
56import { ServerFunctionSerializationAdapter } from './serializer/ServerFunctionSerializationAdapter'
57import type {
58 AnyFunctionMiddleware,
59 AnyRequestMiddleware,
60 AnyStartInstanceOptions,
61 RouteMethod,
62 RouteMethodHandlerFn,
63 RouterEntry,
64 StartEntry,
65} from '@tanstack/start-client-core'
66import type { RequestHandler, RequestOptions } from './request-handler'
67import type { StartEvent } from './internal-request-response'
68import type {
69 AnyRoute,
70 AnyRouter,
71 AnySerializationAdapter,
72 Register,
73} from '@tanstack/router-core'
74import type {
75 HandlerCallback,
76 HandlerCallbackResult,
77 SsrResponse,
78} from '@tanstack/router-core/ssr/server'
79import type { FinalManifestOptions } from './finalManifest'
80β
81type TODO = any
82β
83type AnyMiddlewareServerFn =
84 | AnyRequestMiddleware['options']['server']
85 | AnyFunctionMiddleware['options']['server']
86β
87export interface CreateStartHandlerOptions extends FinalManifestOptions {
88 handler: HandlerCallback<AnyRouter>
89}
90β
91function getStartResponseHeaders(router: AnyRouter) {
92 const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' })
93 const matches = _getRenderedMatches(router.stores.matches.get())
94 // Most matches set no headers; merge only when one does.
95 return matches.some((match) => match.headers)
96 ? mergeHeaders(headers, ...matches.map((match) => match.headers))
97 : headers
98}
99β
100interface PluginAdaptersEntry {
101 hasPluginAdapters: boolean
102 pluginSerializationAdapters: Array<AnySerializationAdapter>
103}
104β
105interface Entries {
106 startEntry: StartEntry
107 routerEntry: RouterEntry
108 pluginAdapters: PluginAdaptersEntry
109}
110β
111// Share initialization, then reuse the loaded entries without a promise wait.
112let cachedEntries: Entries | Promise<Entries> | undefined
113let hasWarnedMissingCsrfMiddleware = false
114const defaultCsrfMiddleware = createCsrfMiddleware({
115 filter: (ctx) => ctx.handlerType === 'serverFn',
116})
117const getCachedBaseManifest = createCachedBaseManifestLoader(() =>
118 getStartManifest(),
119)
120const getProdBaseManifest: typeof getStartManifest = () =>
121 getCachedBaseManifest()
122const getBaseManifest =
123 process.env.TSS_DEV_SERVER === 'true' ? getStartManifest : getProdBaseManifest
124const createEarlyHintsForRequest: typeof createEarlyHintsCollector =
125 process.env.TSS_DEV_SERVER === 'true'
126 ? () => undefined
127 : createEarlyHintsCollector
128β
129async function loadEntries(): Promise<Entries> {
130 const [routerEntry, startEntry, pluginAdapters] = await Promise.all([
131 // @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
132 import('#tanstack-router-entry'),
133 // @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
134 import('#tanstack-start-entry'),
135 // @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
136 import('#tanstack-start-plugin-adapters'),
137 ])
138 return {
139 routerEntry: routerEntry as unknown as RouterEntry,
140 startEntry: startEntry as unknown as StartEntry,
141 pluginAdapters: pluginAdapters as unknown as PluginAdaptersEntry,
142 }
143}
144β
145function getEntries() {
146 if (!cachedEntries) {
147 cachedEntries = loadEntries().then((entries) => {
148 cachedEntries = entries
149 return entries
150 })
151 }
152 return cachedEntries
153}
154β
155function hasCsrfMiddleware(
156 middlewares: Array<AnyRequestMiddleware | AnyFunctionMiddleware>,
157): boolean {
158 return middlewares.some((middleware) => csrfSymbol in middleware)
159}
160β
161function warnMissingCsrfMiddlewareOnce() {
162 if (hasWarnedMissingCsrfMiddleware) return
163 hasWarnedMissingCsrfMiddleware = true
164β
165 console.warn(`TanStack Start server functions are not protected by the CSRF middleware.
166β
167Server functions are same-origin RPC endpoints and should be protected from cross-site requests.
168β
169Add the CSRF middleware in src/start.ts:
170β
171 const csrfMiddleware = createCsrfMiddleware({
172 filter: (ctx) => ctx.handlerType === 'serverFn',
173 })
174β
175 export const startInstance = createStart(() => ({
176 requestMiddleware: [csrfMiddleware],
177 }))
178β
179If you intentionally handle CSRF another way, disable this warning:
180β
181 tanstackStart({
182 serverFns: {
183 disableCsrfMiddlewareWarning: true,
184 },
185 })`)
186}
187β
188// Pre-computed constants
189const ROUTER_BASEPATH = process.env.TSS_ROUTER_BASEPATH || '/'
190const SERVER_FN_BASE = process.env.TSS_SERVER_FN_BASE
191const IS_PRERENDERING = process.env.TSS_PRERENDERING === 'true'
192const IS_SHELL_ENV = process.env.TSS_SHELL === 'true'
193const IS_DEV = process.env.NODE_ENV === 'development'
194β
195// Reusable error messages
196const ERR_NO_RESPONSE = IS_DEV
197 ? `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.`
198 : 'Internal Server Error'
199β
200const ERR_NO_DEFER = IS_DEV
201 ? `You cannot defer to the app router if there is no component defined on this route.`
202 : 'Internal Server Error'
203β
204function throwRouteHandlerError(): never {
205 throw new Error(ERR_NO_RESPONSE)
206}
207β
208function throwIfMayNotDefer(): never {
209 throw new Error(ERR_NO_DEFER)
210}
211β
212function getResponseFromResult(result: TODO): TODO {
213 return isSsrResponse(result) || result instanceof Response
214 ? result
215 : result?.response
216}
217β
218type StreamSsrResponse = Extract<SsrResponse, { serverSsrCleanup: 'stream' }>
219β
220type ResponseBody = NonNullable<Response['body']>
221type ResponseWithBody = Response & { readonly body: ResponseBody }
222β
223/** The context object threaded through one middleware pipeline. */
224interface PipelineContext {
225 request: Request
226 pathname: string
227 handlerType: 'serverFn' | 'router'
228 context: Record<string, unknown>
229 params?: Record<string, unknown>
230 response?: Response
231 // Middleware may add arbitrary own properties through `next(ctx)`.
232 [key: string]: unknown
233}
234β
235interface MiddlewareResponseOwnership {
236 response: ResponseWithBody
237 sourceBody: ResponseBody
238 streamResponse?: StreamSsrResponse
239}
240β
241function disposeResponseResult(result: TODO, reason: unknown): void {
242 const response = getResponseFromResult(result)
243 if (isSsrResponse(response) || response instanceof Response) {
244 disposeSsrResponse(response, reason)
245 }
246}
247β
248/**
249 * A new body continues the owned one when it is the same stream, or when the
250 * owned body is already being read, as by a pipe, a tee, or a `Response` that
251 * copies a body by reading it (Bun, or a wrapped global `Response`). Start
252 * cannot tell such a reader from one that stops early, so it disposes only an
253 * unread body. A stream whose reader stops early ends with the request's abort
254 * or the SSR stream's lifetime limit.
255 */
256function inheritsResponseOwnership(
257 ownership: MiddlewareResponseOwnership,
258 body: ResponseBody,
259): boolean {
260 const ownedBody = ownership.response.body
261 return body === ownedBody || ownedBody.locked
262}
263β
264function disposeResponseOwnership(
265 ownership: MiddlewareResponseOwnership,
266 reason: unknown,
267): void {
268 const { response, sourceBody, streamResponse } = ownership
269 streamResponse?.dispose(reason)
270 if (!streamResponse || response.body !== sourceBody) {
271 void response.body.cancel(reason).catch(() => {})
272 }
273}
274β
275function getOwnedResponse(
276 ownership: MiddlewareResponseOwnership,
277): HandlerCallbackResult {
278 const { response, sourceBody, streamResponse } = ownership
279 if (!streamResponse) {
280 return response
281 }
282 if (streamResponse.response === response && response.body === sourceBody) {
283 return streamResponse
284 }
285 if (response.body === sourceBody) {
286 return { ...streamResponse, response }
287 }
288 return {
289 ...streamResponse,
290 response,
291 dispose(reason): undefined {
292 disposeResponseOwnership(ownership, reason)
293 },
294 }
295}
296β
297function createLateResponseDisposer(signal: AbortSignal) {
298 return (result: TODO) => disposeResponseResult(result, signal.reason)
299}
300β
301/**
302 * Compose middleware around a terminal response handler. With no middleware
303 * the terminal runs directly.
304 */
305async function executeMiddleware(
306 middlewares: Array<TODO>,
307 terminal: TODO,
308 ctx: PipelineContext,
309 signal: AbortSignal,
310 event: StartEvent,
311 terminalNext?: TODO,
312): Promise<HandlerCallbackResult> {
313 let index = -1
314 let responseOwnership: MiddlewareResponseOwnership | undefined
315 // Invocations form one chain: invocation `d` runs middleware `d` and calls
316 // next() at most once; the pipeline itself is depth -1. Once an invocation
317 // returns, a result of next() still pending below it is abandoned: it must
318 // not replace or cancel the response that invocation chose (for example the
319 // winner of a `Promise.race`). A caller at depth `d` is therefore abandoned
320 // when `returnedDepth <= d`, where this is the shallowest returned depth.
321 let returnedDepth = Infinity
322 const disposeAbandonedResult = createLateResponseDisposer(signal)
323β
324 const adoptResponse = (
325 exposed: Response | undefined,
326 streamResponse?: StreamSsrResponse,
327 ) => {
328 const current = responseOwnership
329 // Read the body once: the getter can allocate a stream for a response
330 // that has not exposed one yet.
331 const body = exposed instanceof Response ? exposed.body : null
332 // `exposed` is a Response with this body whenever `body` is set.
333 const response = exposed as ResponseWithBody
334 if (streamResponse && !body && streamResponse !== current?.streamResponse) {
335 streamResponse.dispose('Response body dropped by Start reconciliation')
336 }
337 if (current && current.response === exposed) {
338 current.streamResponse ??= streamResponse
339 } else if (current && body && inheritsResponseOwnership(current, body)) {
340 // A wrapper around the same body stream carries the same encoded bytes,
341 // so it keeps the transport requirements that decode them.
342 if (body === current.response.body) {
343 transferResponseProtocol(current.response, response)
344 }
345 current.response = response
346 current.streamResponse ??= streamResponse
347 } else {
348 if (current) {
349 responseOwnership = undefined
350 disposeResponseOwnership(current, 'middleware response replaced')
351 }
352 responseOwnership = body
353 ? { response, sourceBody: body, streamResponse }
354 : undefined
355 }
356 ctx.response = exposed
357 }
358β
359 const disposeCurrentBody = (reason: string) => {
360 const current = responseOwnership
361 responseOwnership = undefined
362 if (current) {
363 disposeResponseOwnership(current, reason)
364 }
365 }
366β
367 const setResponse = (response: TODO, caller: number) => {
368 // The owned response is already adopted; only helper state can still
369 // change it.
370 const owned =
371 response !== undefined && response === responseOwnership?.response
372 const ssrResponse = !owned && isSsrResponse(response) ? response : undefined
373 const exposed: Response | undefined = ssrResponse
374 ? ssrResponse.response
375 : response
376β
377 if (returnedDepth <= caller) {
378 if (exposed !== ctx.response) {
379 disposeResponseResult(response, 'late middleware response')
380 }
381 return
382 }
383 if (!owned) {
384 // Dispose a replaced body before reading helper state: cancellation and
385 // SSR cleanup callbacks may set headers on the response that replaces it.
386 adoptResponse(
387 exposed,
388 ssrResponse?.serverSsrCleanup === 'stream' ? ssrResponse : undefined,
389 )
390 }
391 if (exposed instanceof Response) {
392 const reconciled = reconcileResponse(exposed, event, disposeCurrentBody)
393 if (reconciled !== exposed) {
394 adoptRebuilt(exposed, reconciled)
395 }
396 }
397 }
398β
399 // Start rebuilds the owned response around its body, or without a body when
400 // the response cannot have one. A rebuilt body takes over ownership without
401 // comparing streams: a wrapped global `Response` copies it into a new one.
402 const adoptRebuilt = (exposed: Response, rebuilt: Response) => {
403 const current = responseOwnership
404 if (current?.response === exposed && rebuilt.body) {
405 current.response = rebuilt as ResponseWithBody
406 ctx.response = rebuilt
407 } else {
408 adoptResponse(rebuilt)
409 }
410 }
411β
412 let nextPromise: Promise<TODO> | undefined
413β
414 function next(nextCtx?: TODO): Promise<TODO> {
415 // Only the deepest started invocation can call next().
416 const result = runNext(index, nextCtx)
417 nextPromise = result
418 return result
419 }
420β
421 async function runNext(caller: number, nextCtx?: TODO): Promise<TODO> {
422 signal.throwIfAborted()
423β
424 // Merge context if provided using safeObjectMerge for prototype pollution prevention
425 if (nextCtx) {
426 if (nextCtx.context) {
427 ctx.context = safeObjectMerge(ctx.context, nextCtx.context)
428 }
429 // Copy own properties except context (Object.keys returns only own
430 // enumerable properties). An indexed loop avoids the iterator protocol.
431 const keys = Object.keys(nextCtx)
432 // eslint-disable-next-line @typescript-eslint/prefer-for-of
433 for (let i = 0; i < keys.length; i++) {
434 const key = keys[i]!
435 if (key === 'response') {
436 setResponse(nextCtx.response, caller)
437 } else if (key !== 'context') {
438 ctx[key] = nextCtx[key]
439 }
440 }
441 }
442β
443 const depth = ++index
444 const isTerminal = depth === middlewares.length
445 const middleware =
446 depth < middlewares.length
447 ? middlewares[depth]
448 : isTerminal
449 ? terminal
450 : undefined
451 const middlewareNext = isTerminal && terminalNext ? terminalNext : next
452 if (!middleware) {
453 return ctx
454 }
455β
456 let result: TODO
457 try {
458 const pending = middleware({ ...ctx, next: middlewareNext })
459 // A directly returned next() promise already propagates request aborts.
460 if (nextPromise && pending === nextPromise) {
461 nextPromise = undefined
462 result = await pending
463 signal.throwIfAborted()
464 } else if (!isPromise(pending)) {
465 result = pending
466 signal.throwIfAborted()
467 } else {
468 result = await waitForRequest(
469 pending,
470 signal,
471 disposeAbandonedResult,
472 disposeAbandonedResult,
473 )
474 }
475 } catch (err) {
476 if (depth < returnedDepth) {
477 returnedDepth = depth
478 }
479 if (returnedDepth > caller) {
480 // Middleware can replace next()'s shared response before throwing.
481 // Track that body for cleanup without rebuilding a body it may have
482 // already locked, consumed, or transferred.
483 adoptResponse(ctx.response)
484 }
485 if (signal.aborted) {
486 if (result !== undefined) {
487 disposeAbandonedResult(result)
488 }
489 if (err !== signal.reason) {
490 disposeAbandonedResult(err)
491 }
492 throw signal.reason
493 }
494 if (err instanceof Response) {
495 // A thrown Response replies to the request. For a server function
496 // call, the client rejects the call with it.
497 setResponse(
498 ctx.handlerType === 'serverFn' ? toThrownServerFnResponse(err) : err,
499 caller,
500 )
501 return ctx
502 }
503 throw err
504 }
505 if (depth < returnedDepth) {
506 returnedDepth = depth
507 }
508β
509 if (isTerminal && terminalNext && !result) {
510 throwRouteHandlerError()
511 }
512β
513 if (isTerminal && !terminalNext && result instanceof DeferredResponse) {
514 if (returnedDepth > caller) {
515 // Cleanup may write response helpers. Construct only after it has run,
516 // then publish without rechecking headers that no user has received.
517 adoptResponse(undefined)
518 adoptResponse(result.createResponse(event))
519 }
520 return ctx
521 }
522β
523 if (result && result !== ctx) {
524 const response = getResponseFromResult(result)
525 // Select the replacement before reconciling: middleware may already
526 // have transferred or piped the previous response's body.
527 if (response !== undefined) {
528 // Middleware can assign next()'s shared response and then return
529 // another one, such as a 304 after transforming the body. Track the
530 // assigned body first, so the replacement disposes it, without
531 // rebuilding a body it may have already locked or consumed.
532 if (
533 ctx.response !== responseOwnership?.response &&
534 ctx.response !== response &&
535 returnedDepth > caller
536 ) {
537 adoptResponse(ctx.response)
538 }
539 setResponse(response, caller)
540 } else {
541 setResponse(ctx.response, caller)
542 }
543 if (
544 returnedDepth > caller &&
545 response !== result &&
546 result.context &&
547 result.context !== ctx.context
548 ) {
549 ctx.context = safeObjectMerge(ctx.context, result.context)
550 }
551 } else {
552 setResponse(ctx.response, caller)
553 }
554β
555 return ctx
556 }
557β
558 try {
559 await runNext(-1)
560 let response = ctx.response
561 if (!response) {
562 throwRouteHandlerError()
563 }
564 if (signal.aborted) {
565 throw signal.reason
566 }
567 returnedDepth = -1
568 // Middleware can change protocol headers directly on a server-function
569 // reply, the only response that has them. Restore them once, as the reply
570 // leaves the pipeline; without middleware only Start has handled it.
571 if (middlewares.length && ctx.handlerType === 'serverFn') {
572 const restored = restoreResponseProtocol(response, event)
573 if (restored !== response) {
574 adoptRebuilt(response, restored)
575 response = restored
576 }
577 }
578 return responseOwnership ? getOwnedResponse(responseOwnership) : response
579 } catch (err) {
580 returnedDepth = -1
581 if (responseOwnership) {
582 disposeResponseOwnership(
583 responseOwnership,
584 signal.aborted ? signal.reason : err,
585 )
586 }
587 throw err
588 }
589}
590β
591/**
592 * Creates the TanStack Start request handler.
593 *
594 * @example Backwards-compatible usage (handler callback only):
595 * ```ts
596 * export default createStartHandler(defaultStreamHandler)
597 * ```
598 *
599 * @example With CDN URL rewriting:
600 * ```ts
601 * export default createStartHandler({
602 * handler: defaultStreamHandler,
603 * transformAssets: 'https://cdn.example.com',
604 * })
605 * ```
606 *
607 * @example With per-request URL rewriting:
608 * ```ts
609 * export default createStartHandler({
610 * handler: defaultStreamHandler,
611 * transformAssets: {
612 * transform: ({ url }) => {
613 * const cdnBase = getRequest().headers.get('x-cdn-base') || ''
614 * return { href: `${cdnBase}${url}` }
615 * },
616 * cache: false,
617 * },
618 * })
619 * ```
620 */
621export function createStartHandler<TRegister = Register>(
622 cbOrOptions: HandlerCallback<AnyRouter> | CreateStartHandlerOptions,
623): RequestHandler<TRegister> {
624 const handlerOptions: FinalManifestOptions =
625 typeof cbOrOptions === 'function' ? {} : cbOrOptions
626 const cb: HandlerCallback<AnyRouter> =
627 typeof cbOrOptions === 'function' ? cbOrOptions : cbOrOptions.handler
628 const finalManifestResolver = createFinalManifestResolver({
629 ...handlerOptions,
630 cacheCreateTransform: process.env.TSS_DEV_SERVER !== 'true',
631 })
632 const resolveManifestForRequest =
633 process.env.TSS_DEV_SERVER === 'true'
634 ? finalManifestResolver.resolveUncached
635 : finalManifestResolver.resolveCached
636β
637 if (process.env.TSS_DEV_SERVER !== 'true') {
638 finalManifestResolver.warmup({
639 getBaseManifest: () => getBaseManifest(undefined),
640 })
641 }
642β
643 const startRequestResolver = async (
644 request: Request,
645 requestOpts: RequestOptions<Register> | undefined,
646 event: StartEvent,
647 ): Promise<Response> => {
648 const signal = request.signal
649 let router: AnyRouter | undefined
650 let routerPromise: Promise<AnyRouter> | undefined
651 let responseOwnsCleanup = false
652 let response: Response | undefined
653β
654 try {
655 signal.throwIfAborted()
656 // The Start event already parsed and validated the request URL; reuse
657 // it instead of re-parsing. The memoized URL must not be mutated.
658 const requestUrl = event.requestUrl
659 let url = requestUrl
660 const pathname = url.pathname
661 // Plain RPC paths need no routing normalization. Their payload is read
662 // from the original query; normalize only if they later request a router.
663 if (
664 !SERVER_FN_BASE ||
665 !pathname.startsWith(SERVER_FN_BASE) ||
666 pathname.includes('%') ||
667 pathname.startsWith('//')
668 ) {
669 const normalized = getNormalizedURL(requestUrl)
670 url = normalized.url
671 if (normalized.handledProtocolRelativeURL) {
672 return finalizeResponse(Response.redirect(url, 308), event)
673 }
674 }
675β
676 const pendingEntries = getEntries()
677 const entries = isPromise(pendingEntries)
678 ? await waitForRequest(pendingEntries, signal)
679 : pendingEntries
680 const isServerFnRequest =
681 !!SERVER_FN_BASE && url.pathname.startsWith(SERVER_FN_BASE)
682 const startInstance = entries.startEntry.startInstance
683 let startOptions: AnyStartInstanceOptions
684 if (startInstance) {
685 const pendingStartOptions = startInstance.getOptions()
686 startOptions = isPromise(pendingStartOptions)
687 ? await waitForRequest(pendingStartOptions, signal)
688 : pendingStartOptions
689 signal.throwIfAborted()
690 } else {
691 startOptions = {} as AnyStartInstanceOptions
692 }
693β
694 const { hasPluginAdapters, pluginSerializationAdapters } =
695 entries.pluginAdapters
696β
697 const serializationAdapters = [
698 ...(startOptions.serializationAdapters || []),
699 ...(hasPluginAdapters ? pluginSerializationAdapters : []),
700 ServerFunctionSerializationAdapter,
701 ]
702β
703 const requestStartOptions = {
704 ...startOptions,
705 requestMiddleware: startInstance
706 ? startOptions.requestMiddleware
707 : isServerFnRequest
708 ? [defaultCsrfMiddleware]
709 : undefined,
710 serializationAdapters,
711 }
712β
713 // Reuse the flattening set for request middleware deduplication.
714 const executedRequestMiddlewares = new Set<TODO>()
715 const flattenedRequestMiddlewares = requestStartOptions.requestMiddleware
716 ? flattenMiddlewares(
717 requestStartOptions.requestMiddleware,
718 undefined,
719 executedRequestMiddlewares,
720 )
721 : []
722β
723 // Memoized router getter
724 const getRouter = (): Promise<AnyRouter> => {
725 routerPromise ??= (async () => {
726 signal.throwIfAborted()
727 const routerUrl = url === requestUrl ? getNormalizedURL(url).url : url
728 const pendingRouter = entries.routerEntry.getRouter()
729 const requestRouter = isPromise(pendingRouter)
730 ? await waitForRequest(pendingRouter, signal)
731 : pendingRouter
732β
733 let isShell = IS_SHELL_ENV
734 if (IS_PRERENDERING && !isShell) {
735 isShell = request.headers.get(HEADERS.TSS_SHELL) === 'true'
736 }
737β
738 const history = createServerHistory(
739 routerUrl.pathname + routerUrl.search + routerUrl.hash,
740 )
741β
742 requestRouter.update({
743 history,
744 isShell,
745 isPrerendering: IS_PRERENDERING,
746 origin: requestRouter.options.origin ?? routerUrl.origin,
747 // Start-owned options that RouterConstructorOptions omits.
748 ...{
749 defaultSsr: requestStartOptions.defaultSsr,
750 serializationAdapters: [
751 ...requestStartOptions.serializationAdapters,
752 ...(requestRouter.options.serializationAdapters || []),
753 ],
754 },
755 basepath: ROUTER_BASEPATH,
756 })
757β
758 router = requestRouter
759 return requestRouter
760 })()
761β
762 return routerPromise
763 }
764β
765 const handlerType = isServerFnRequest
766 ? ('serverFn' as const)
767 : ('router' as const)
768 const startContext = {
769 getRouter,
770 startOptions: requestStartOptions,
771 request,
772 executedRequestMiddlewares,
773 handlerType,
774 }
775 let terminal: (
776 ctx: PipelineContext,
777 ) => Promise<HandlerCallbackResult | DeferredResponse>
778β
779 if (isServerFnRequest) {
780 if (
781 process.env.NODE_ENV !== 'production' &&
782 process.env.TSS_DISABLE_CSRF_MIDDLEWARE_WARNING !== 'true' &&
783 !hasCsrfMiddleware(flattenedRequestMiddlewares)
784 ) {
785 warnMissingCsrfMiddlewareOnce()
786 }
787β
788 const serverFnId = url.pathname
789 .slice(SERVER_FN_BASE.length)
790 .split('/')[0]
791β
792 if (!serverFnId) {
793 throw new Error('Invalid server action param for serverFnId')
794 }
795β
796 terminal = ({ context }) =>
797 runWithStartContext(
798 { ...startContext, contextAfterGlobalMiddlewares: context },
799 () =>
800 handleServerAction({
801 request,
802 serverFnId,
803 }),
804 )
805 } else {
806 // Runs as the route pipeline's terminal, which waits on the request
807 // signal and disposes a result that settles after an abort.
808 const executeRouter = async (
809 serverContext: TODO,
810 matchedRoutes: ReadonlyArray<AnyRoute>,
811 routerInstance: AnyRouter,
812 ): Promise<SsrResponse> => {
813 if (
814 !/(^|,)\s*(\*\/\*|text\/html)/.test(
815 request.headers.get('Accept') || '*/*',
816 )
817 ) {
818 return normalizeSsrResponse(
819 Response.json(
820 { error: 'Only HTML requests are supported here' },
821 { status: 406 },
822 ),
823 )
824 }
825β
826 const pendingManifest = resolveManifestForRequest({
827 request,
828 requestInlineCss: requestOpts?.inlineCss,
829 getBaseManifest: () => getBaseManifest(matchedRoutes),
830 })
831 const manifest = isPromise(pendingManifest)
832 ? await waitForRequest(pendingManifest, signal)
833 : pendingManifest
834β
835 const earlyHints = createEarlyHintsForRequest(requestOpts)
836β
837 earlyHints?.collectStatic({ manifest, matchedRoutes })
838β
839 // The request's stored context, not the resolver's template: RSC
840 // adds request assets to it, so read them at call time.
841 const storedStartContext = getStartContext({ throwIfNotFound: false })
842 attachRouterServerSsrUtils({
843 router: routerInstance,
844 manifest,
845 getRequestAssets: () => storedStartContext?.requestAssets,
846 })
847β
848 // `additionalContext` is request-scoped and only read from router.options
849 // during load; avoid a full router.update() and redundant location parse.
850 routerInstance.options.additionalContext = { serverContext }
851 await routerInstance.load({ _signal: signal })
852 signal.throwIfAborted()
853β
854 if (routerInstance._serverResult?.type === 'redirect') {
855 return normalizeSsrResponse(routerInstance._serverResult.redirect)
856 }
857β
858 earlyHints?.collectDynamic(
859 _getRenderedMatches(routerInstance.stores.matches.get()),
860 )
861β
862 // Pass request-scoped assets to dehydrate for manifest injection
863 await routerInstance.serverSsr!.dehydrate({
864 requestAssets: storedStartContext?.requestAssets,
865 signal,
866 })
867 signal.throwIfAborted()
868β
869 const responseHeaders = getStartResponseHeaders(routerInstance)
870 earlyHints?.appendResponseHeaders(responseHeaders)
871 signal.throwIfAborted()
872 return normalizeSsrResponse(
873 await cb({
874 request,
875 router: routerInstance,
876 responseHeaders,
877 }),
878 )
879 }
880β
881 terminal = ({ context }) =>
882 runWithStartContext(
883 { ...startContext, contextAfterGlobalMiddlewares: context },
884 () =>
885 handleServerRoutes({
886 getRouter,
887 request,
888 url,
889 executeRouter,
890 context,
891 executedRequestMiddlewares,
892 signal,
893 event,
894 }),
895 )
896 }
897β
898 const middlewareCtx: PipelineContext = {
899 request,
900 pathname: url.pathname,
901 handlerType,
902 context: createNullProtoObject(requestOpts?.context),
903 }
904 let middlewareResponse: HandlerCallbackResult
905 try {
906 if (!isServerFnRequest && flattenedRequestMiddlewares.length === 0) {
907 // An empty global pipeline has no additional middleware to run. The
908 // route pipeline already reconciles responses, owns cleanup, and
909 // waits on the request signal for every pending result. Only
910 // server-function terminals can defer JSON construction.
911 middlewareResponse = await (terminal(
912 middlewareCtx,
913 ) as Promise<HandlerCallbackResult>)
914 } else {
915 middlewareResponse = await executeMiddleware(
916 flattenedRequestMiddlewares.map((d) => d.options.server),
917 terminal,
918 middlewareCtx,
919 signal,
920 event,
921 )
922 }
923 } catch (error) {
924 if (signal.aborted) {
925 throw error
926 }
927 if (error instanceof Response) {
928 middlewareResponse = reconcileResponse(error, event)
929 } else if (!isServerFnRequest) {
930 throw error
931 } else {
932 // Request middleware can throw before the server function runs.
933 const disposeLate = createLateResponseDisposer(signal)
934 middlewareResponse = await waitForRequest(
935 runWithStartContext(
936 {
937 ...startContext,
938 contextAfterGlobalMiddlewares: middlewareCtx.context,
939 },
940 () => createServerFnErrorResponse(error),
941 ),
942 signal,
943 disposeLate,
944 disposeLate,
945 )
946 middlewareResponse = reconcileResponse(middlewareResponse, event)
947 }
948 }
949β
950 let result: SsrResponse
951 try {
952 result = normalizeSsrResponse(middlewareResponse)
953 if (isRedirect(result.response)) {
954 result = await handleRedirectResponse(
955 result,
956 getRouter,
957 signal,
958 isServerFnRequest &&
959 request.headers.get('x-tsr-serverFn') === 'true',
960 event,
961 )
962 }
963 // Request middleware can read a HEAD body, for example to compute an
964 // ETag, so it is stripped only when the response leaves the pipeline.
965 if (request.method === 'HEAD' && result.response.body !== null) {
966 const source = result.response
967 result = stripSsrResponseBody(result, 'HEAD body stripped')
968 transferResponseMetadata(source, result.response)
969 }
970 } catch (error) {
971 disposeResponseResult(
972 middlewareResponse,
973 signal.aborted ? signal.reason : error,
974 )
975 throw error
976 }
977 bindSsrResponseToRequest(router, result, signal)
978 signal.throwIfAborted()
979 responseOwnsCleanup = result.serverSsrCleanup === 'stream'
980 response = result.response
981 } finally {
982 if (router?.serverSsr && !responseOwnsCleanup) {
983 // Stream disposal already publishes its cleanup writes at the pipeline
984 // boundary. Only live eager SSR state can still add response helpers.
985 router.serverSsr.cleanup()
986 if (response) {
987 response = finalizeResponse(response, event)
988 }
989 }
990 // `routerPromise` stays memoized: a streamed Suspense boundary or a late
991 // server function may still ask for this request's router.
992 }
993 return response
994 }
995β
996 return withStartRequest(startRequestResolver)
997}
998β
999const relativeRedirectProtocols = new Set<string>()
1000const SERIALIZED_REDIRECT_HEADERS: ReadonlyMap<string, string | null> = new Map(
1001 [
1002 ['content-type', 'application/json'],
1003 ['location', null],
1004 [X_TSS_RAW_RESPONSE, null],
1005 [X_TSS_SERIALIZED, null],
1006 ],
1007)
1008β
1009async function handleRedirectResponse(
1010 ssrResponse: SsrResponse,
1011 getRouter: () => Promise<AnyRouter>,
1012 signal: AbortSignal,
1013 serializeRedirect: boolean,
1014 event: StartEvent,
1015): Promise<SsrResponse> {
1016 signal.throwIfAborted()
1017 const redirect = ssrResponse.response
1018 if (!isRedirect(redirect)) {
1019 return ssrResponse
1020 }
1021β
1022 const opts = redirect.options
1023 const href = redirect.headers.get('Location') || opts.href
1024 if (
1025 !href &&
1026 opts.to &&
1027 typeof opts.to === 'string' &&
1028 !opts.to.startsWith('/')
1029 ) {
1030 throw new Error(
1031 `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)}`,
1032 )
1033 }
1034β
1035 if (
1036 !href &&
1037 ['params', 'search', 'hash'].some(
1038 (d) => typeof (opts as TODO)[d] === 'function',
1039 )
1040 ) {
1041 throw new Error(
1042 `Server side redirects must use static search, params, and hash values and do not support functional values. Received functional values for: ${Object.keys(
1043 opts,
1044 )
1045 .filter((d) => typeof (opts as TODO)[d] === 'function')
1046 .map((d) => `"${d}"`)
1047 .join(', ')}`,
1048 )
1049 }
1050β
1051 signal.throwIfAborted()
1052 // Unambiguous relative hrefs need no route resolution or protocol policy.
1053 // Every scheme falls back to the router to honor its custom allowlist.
1054 if (href && !isDangerousProtocol(href, relativeRedirectProtocols)) {
1055 opts.href = href
1056 redirect.headers.set('Location', href)
1057 } else {
1058 const router = await getRouter()
1059 signal.throwIfAborted()
1060 // Resolves `redirect` in place.
1061 router.resolveRedirect(redirect)
1062 }
1063β
1064 if (serializeRedirect) {
1065 const redirectOptions = { ...(opts as TODO) }
1066 delete redirectOptions.headers
1067 redirectOptions.isSerializedRedirect = true
1068 const responseHeaders = new Headers(redirect.headers)
1069 responseHeaders.set('content-type', 'application/json')
1070 // The client follows the href in this JSON envelope. An HTTP Location
1071 // would let fetch follow it first if a response helper selected 3xx.
1072 responseHeaders.delete('location')
1073 responseHeaders.delete(X_TSS_RAW_RESPONSE)
1074 responseHeaders.delete(X_TSS_SERIALIZED)
1075 // A caller-supplied toJSON can return undefined despite the library type.
1076 const body = JSON.stringify(redirectOptions) as string | undefined
1077 if (body === undefined) {
1078 throw new TypeError('Value is not JSON serializable')
1079 }
1080 // Both serialization and disposal can write helpers. Construct the envelope
1081 // afterward with its final state instead of reconciling a temporary response.
1082 disposeSsrResponse(ssrResponse, 'redirect response replaced')
1083 return {
1084 response: createFinalizedResponse(
1085 body,
1086 responseHeaders,
1087 SERIALIZED_REDIRECT_HEADERS,
1088 event,
1089 ),
1090 serverSsrCleanup: 'none',
1091 }
1092 }
1093β
1094 ssrResponse.response = finalizeResponse(redirect, event)
1095 return ssrResponse
1096}
1097β
1098function withParsedParams(
1099 handler: RouteMethodHandlerFn<any, AnyRoute, any, any, any, any, any>,
1100 matchedRoutes: ReadonlyArray<AnyRoute>,
1101): TODO {
1102 if (
1103 !matchedRoutes.some(
1104 (route) => route.options.params?.parse ?? route.options.parseParams,
1105 )
1106 ) {
1107 return handler
1108 }
1109β
1110 return (ctx: TODO) => {
1111 // Parse inside the pipeline so middleware can catch errors. Keep the raw
1112 // params for app-router validation when the handler defers to rendering.
1113 const params = Object.assign(Object.create(null), ctx.params)
1114 for (const route of matchedRoutes) {
1115 const parse = route.options.params?.parse ?? route.options.parseParams
1116 if (parse) {
1117 Object.assign(params, parse(params))
1118 }
1119 }
1120 return handler({ ...ctx, params })
1121 }
1122}
1123β
1124async function handleServerRoutes({
1125 getRouter,
1126 request,
1127 url,
1128 executeRouter,
1129 context,
1130 executedRequestMiddlewares,
1131 signal,
1132 event,
1133}: {
1134 getRouter: () => Promise<AnyRouter>
1135 request: Request
1136 url: URL
1137 executeRouter: (
1138 serverContext: any,
1139 matchedRoutes: ReadonlyArray<AnyRoute>,
1140 router: AnyRouter,
1141 ) => Promise<SsrResponse>
1142 context: any
1143 executedRequestMiddlewares: Set<AnyRequestMiddleware>
1144 signal: AbortSignal
1145 event: StartEvent
1146}): Promise<SsrResponse> {
1147 const router = await getRouter()
1148 // Pass a clone to user rewrite code: `url` may be the request-scoped
1149 // memoized URL, which must not be mutated.
1150 const rewrittenUrl = router.rewrite
1151 ? executeRewriteInput(router.rewrite, new URL(url))
1152 : url
1153 const pathname = rewrittenUrl.pathname
1154 // this will perform a fuzzy match, however for server routes we need an exact match
1155 // if the route is not an exact match, executeRouter will handle rendering the app router
1156 // the match will be cached internally, so no extra work is done during the app router render
1157 const [matchedRoutes, rawParams, foundRoute] =
1158 router.getMatchedRoutes(pathname)
1159β
1160 const isExactMatch = foundRoute && rawParams['**'] === undefined
1161β
1162 // Collect and dedupe route middlewares
1163 const routeMiddlewares: Array<AnyMiddlewareServerFn> = []
1164 let terminalHandler: TODO = (ctx: TODO) =>
1165 executeRouter(ctx.context, matchedRoutes, router)
1166 let terminalNext: TODO
1167β
1168 // Collect middleware from matched routes, filtering out those already executed
1169 // in the request phase
1170 for (const route of matchedRoutes) {
1171 const serverMiddleware = route.options.server?.middleware as
1172 | Array<AnyRequestMiddleware>
1173 | undefined
1174 if (serverMiddleware) {
1175 const flattened = flattenMiddlewares(serverMiddleware)
1176 for (const m of flattened) {
1177 if (!executedRequestMiddlewares.has(m)) {
1178 routeMiddlewares.push(m.options.server)
1179 }
1180 }
1181 }
1182 }
1183β
1184 // Add handler middleware if exact match
1185 const server = foundRoute?.options.server
1186 if (server?.handlers && isExactMatch) {
1187 const handlers =
1188 typeof server.handlers === 'function'
1189 ? server.handlers({ createHandlers: (d: any) => d })
1190 : server.handlers
1191β
1192 const requestMethod = request.method.toUpperCase() as RouteMethod
1193 // Per RFC 9110 Β§9.3.2, HEAD must return the same header fields as GET.
1194 // Priority for HEAD: explicit HEAD handler β GET β ANY (last resort).
1195 const handler =
1196 requestMethod === 'HEAD'
1197 ? (handlers['HEAD'] ?? handlers['GET'] ?? handlers['ANY'])
1198 : (handlers[requestMethod] ?? handlers['ANY'])
1199 if (handler) {
1200 const mayDefer = !!foundRoute.options.component
1201β
1202 if (typeof handler !== 'function') {
1203 if (handler.middleware?.length) {
1204 const handlerMiddlewares = flattenMiddlewares(handler.middleware)
1205 for (const m of handlerMiddlewares) {
1206 routeMiddlewares.push(m.options.server)
1207 }
1208 }
1209 }
1210 const routeHandler =
1211 typeof handler === 'function' ? handler : handler.handler
1212 if (routeHandler) {
1213 const parsedHandler = withParsedParams(routeHandler, matchedRoutes)
1214 if (!mayDefer) {
1215 terminalHandler = parsedHandler
1216 terminalNext = throwIfMayNotDefer
1217 } else {
1218 routeMiddlewares.push(parsedHandler)
1219 }
1220 }
1221 }
1222 }
1223β
1224 const response = await executeMiddleware(
1225 routeMiddlewares,
1226 terminalHandler,
1227 {
1228 request,
1229 context,
1230 params: rawParams,
1231 pathname,
1232 handlerType: 'router',
1233 },
1234 signal,
1235 event,
1236 terminalNext,
1237 )
1238β
1239 return normalizeSsrResponse(response)
1240}