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

createStartHandler.ts

1,241 lines40.2 KB

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