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

internal-request-response.ts

1,490 lines44.9 KB

1import { AsyncLocalStorage } from 'node:async_hooks'
2import { isRedirect } from '@tanstack/router-core'
3​
4import { parseCookie, parseSetCookie, serializeCookie } from 'cookie-es'
5import { getSetCookieValues } from './headers'
6import type {
7 RequestHeaderMap,
8 RequestHeaderName,
9 ResponseHeaderMap,
10 ResponseHeaderName,
11 TypedHeaders,
12} from 'fetchdts'
13​
14import type { CookieSerializeOptions } from 'cookie-es'
15import type { RequestHandler } from './request-handler'
16​
17export interface StartEvent {
18 request: Request
19 /** The parsed request URL. Callers must not mutate it. */
20 requestUrl: URL
21 /**
22 * Lazily created response state. Stays `undefined` until the first
23 * response helper write so requests that never use helpers pay nothing.
24 */
25 responseState?: ResponseState
26 /** The most recently reconciled response, used by response read helpers. */
27 currentResponse?: Response
28 /** Applied helper operations belong to this invocation, across runtime copies. */
29 responseHeaderAppends?: WeakMap<Response, Map<string, HeaderAppendOperation>>
31​
32/**
33 * Event-owned mutable response state, recorded by the response helpers.
34 *
35 * A plain `Headers` object cannot distinguish between "not set" and
36 * "explicitly removed", so removals and Set-Cookie intent are tracked
37 * alongside the headers. All mutations flow through the helper functions in
38 * this module (`setResponseHeader`, `setCookie`, ...), which record that
39 * intent directly.
40 */
41interface ResponseState {
42 status?: number
43 statusText?: string
44 headers: Headers
45 removedHeaders?: Set<string>
46 clearHeaders: boolean
47 setCookieBehavior?: 'merge' | 'replace'
48 headerAppends?: Map<string, HeaderAppendOperation>
49 /** Outside production: a discarded bodyless status was already reported. */
50 bodylessStatusWarned?: boolean
51 /** Identity of each Set-Cookie string seen by this request's merges. */
52 setCookieKeys?: Map<string, string>
54​
55interface HeaderAppendOperation {
56 value: string
57 previous?: HeaderAppendOperation
59​
60// Use a global symbol to ensure the same AsyncLocalStorage instance is shared
61// across different bundles that may each bundle this module.
62const GLOBAL_EVENT_STORAGE_KEY = Symbol.for('tanstack-start:event-storage')
63​
64const globalObj = globalThis as typeof globalThis & {
65 [GLOBAL_EVENT_STORAGE_KEY]?: AsyncLocalStorage<StartEvent>
67​
68if (!globalObj[GLOBAL_EVENT_STORAGE_KEY]) {
69 globalObj[GLOBAL_EVENT_STORAGE_KEY] = new AsyncLocalStorage<StartEvent>()
71​
72const eventStorage = globalObj[GLOBAL_EVENT_STORAGE_KEY]
73​
74export type { ResponseHeaderName, RequestHeaderName }
75​
76/** A detached view of outgoing headers. Use the response helpers for writes. */
77export type ReadonlyResponseHeaders = Omit<
78 TypedHeaders<ResponseHeaderMap>,
79 'append' | 'delete' | 'set' | 'forEach'
80> & {
81 forEach: (
82 callback: (
83 value: string,
84 name: ResponseHeaderName,
85 headers: ReadonlyResponseHeaders,
86 ) => void,
87 thisArg?: unknown,
88 ) => void
90​
91// Lowercase protocol header names mapped to a required value, or to null when
92// the header must be absent. Set-Cookie is never protected: it has one value
93// per cookie.
94type ProtectedHeaders = ReadonlyMap<string, string | null>
95​
96type MaybePromise<T> = T | Promise<T>
97​
98// Protocol requirements describe the response body, so they follow the response
99// through delegated requests as well as separately bundled runtime copies.
100const PROTECTED_RESPONSE_HEADERS = Symbol.for(
101 'tanstack-start:protected-response-headers',
103type ProtectedResponse = Response & {
104 [PROTECTED_RESPONSE_HEADERS]?: ProtectedHeaders
106​
107function getProtectedResponseHeaders(
108 response: Response,
109): ProtectedHeaders | undefined {
110 return (response as ProtectedResponse)[PROTECTED_RESPONSE_HEADERS]
112​
113function installProtectedResponseHeaders(
114 response: Response,
115 headers: ProtectedHeaders,
116): void {
117 Object.defineProperty(response, PROTECTED_RESPONSE_HEADERS, {
118 value: headers,
119 configurable: true,
120 })
122​
123/** Transport requirements belong to the encoded body, not its wrapper. */
124export function transferResponseProtocol(
125 source: Response,
126 target: Response,
127): void {
128 const protectedHeaders = getProtectedResponseHeaders(source)
129 if (
130 protectedHeaders &&
131 getProtectedResponseHeaders(target) !== protectedHeaders
132 ) {
133 installProtectedResponseHeaders(target, protectedHeaders)
134 }
136​
137/** Preserve metadata when Start reconstructs an existing response. */
138export function transferResponseMetadata(
139 source: Response,
140 target: Response,
141): void {
142 transferResponseProtocol(source, target)
143 const event = eventStorage.getStore()
144 const appliedHeaderAppends = event?.responseHeaderAppends?.get(source)
145 if (appliedHeaderAppends) {
146 event!.responseHeaderAppends!.set(target, appliedHeaderAppends)
147 }
149​
150function normalizeHeaderName(name: string): string {
151 return name.toLowerCase()
153​
154function sanitizeStatusMessage(statusMessage: string): string {
155 // Strip everything except horizontal tab and printable ASCII (space–'~')
156 // to prevent header injection through status text.
157 return statusMessage.replace(/[^\t\x20-\x7e]/g, '')
159​
160// The Fetch `Response` constructor only accepts statuses in the 200-599
161// range (anything else throws a RangeError). Start responses are always
162// represented as `Response` objects β€” for server routes and SSR documents
163// just like for server functions β€” so out-of-range statuses (1xx, or exotic
164// codes like 783/999) cannot be carried through the pipeline at all.
165function sanitizeStatusCode(
166 statusCode: string | number | undefined,
167): number | undefined {
168 const code = typeof statusCode === 'string' ? Number(statusCode) : statusCode
169 if (
170 code === undefined ||
171 !Number.isInteger(code) ||
172 code < 200 ||
173 code > 599
174 ) {
175 return undefined
176 }
177 return code
179​
180function getObjectProperty(value: unknown, key: string): unknown {
181 if ((typeof value === 'object' && value) || typeof value === 'function') {
182 return (value as Record<string, unknown>)[key]
183 }
184 return undefined
186​
187function getStatusCodeProperty(
188 value: unknown,
189 key: 'status' | 'statusCode',
190): string | number | undefined {
191 const property = getObjectProperty(value, key)
192 if (typeof property === 'string' || typeof property === 'number') {
193 return property
194 }
195 return undefined
197​
198function getErrorStatus(error: unknown): number | undefined {
199 const cause = getObjectProperty(error, 'cause')
200 return sanitizeStatusCode(
201 getStatusCodeProperty(error, 'status') ??
202 getStatusCodeProperty(error, 'statusCode') ??
203 getStatusCodeProperty(cause, 'status') ??
204 getStatusCodeProperty(cause, 'statusCode'),
205 )
207​
208function getErrorStatusText(error: unknown): string | undefined {
209 const cause = getObjectProperty(error, 'cause')
210 const statusText =
211 getObjectProperty(error, 'statusText') ??
212 getObjectProperty(error, 'statusMessage') ??
213 getObjectProperty(cause, 'statusText') ??
214 getObjectProperty(cause, 'statusMessage')
215 if (typeof statusText === 'string') {
216 return sanitizeStatusMessage(statusText)
217 }
218 return undefined
220​
221// Start builds error bodies and serialized replies itself. These headers
222// describe another body's framing or its connection, whether they come from
223// error metadata or from helpers, so they would corrupt that body on the wire.
224const GENERATED_BODY_EXCLUDED_HEADERS: ReadonlySet<string> = new Set([
225 'connection',
226 'content-encoding',
227 'content-length',
228 'keep-alive',
229 'proxy-connection',
230 'te',
231 'trailer',
232 'transfer-encoding',
233])
234​
235// Responses from another fetch implementation or realm fail instanceof.
236function isResponse(value: unknown): boolean {
237 return (
238 value instanceof Response ||
239 Object.prototype.toString.call(value) === '[object Response]'
240 )
242​
243export function getErrorHeaders(error: unknown): Headers | undefined {
244 let init = getObjectProperty(error, 'headers')
245 if (!init) {
246 const cause = getObjectProperty(error, 'cause')
247 // A Response cause is another server's reply, such as a failed upstream
248 // fetch. Its headers were written for that reply, not for this client.
249 if (isResponse(cause)) {
250 return undefined
251 }
252 init = getObjectProperty(cause, 'headers')
253 }
254 if (!init) {
255 return undefined
256 }
257 let headers: Headers
258 try {
259 headers = new Headers(init as HeadersInit)
260 } catch {
261 return undefined
262 }
263 for (const name of GENERATED_BODY_EXCLUDED_HEADERS) {
264 headers.delete(name)
265 }
266 return headers
268​
269function getResponseState(event: StartEvent): ResponseState {
270 return (event.responseState ||= {
271 headers: new Headers(),
272 clearHeaders: false,
273 })
275​
276function setHeaderState(event: StartEvent, name: string, value: string): void {
277 const state = getResponseState(event)
278 const normalizedName = normalizeHeaderName(name)
279 state.headers.set(name, value)
280 state.headerAppends?.delete(normalizedName)
281 state.removedHeaders?.delete(normalizedName)
282 if (normalizedName === 'set-cookie') {
283 state.setCookieBehavior = 'replace'
284 }
286​
287function appendHeaderState(
288 event: StartEvent,
289 name: string,
290 value: string,
291): void {
292 const state = getResponseState(event)
293 const normalizedName = normalizeHeaderName(name)
294 const appendToReturnedHeader =
295 normalizedName !== 'set-cookie' &&
296 !state.clearHeaders &&
297 !state.removedHeaders?.has(normalizedName) &&
298 (!state.headers.has(normalizedName) ||
299 state.headerAppends?.has(normalizedName))
300 // Validate and normalize through native Headers before recording intent.
301 state.headers.append(name, value)
302 if (appendToReturnedHeader) {
303 const appends = (state.headerAppends ||= new Map())
304 appends.set(normalizedName, {
305 value,
306 previous: appends.get(normalizedName),
307 })
308 }
309 state.removedHeaders?.delete(normalizedName)
310 if (
311 normalizedName === 'set-cookie' &&
312 state.setCookieBehavior !== 'replace'
313 ) {
314 state.setCookieBehavior = 'merge'
315 }
317​
318function deleteHeaderState(event: StartEvent, name: string): void {
319 const state = getResponseState(event)
320 const normalizedName = normalizeHeaderName(name)
321 state.headers.delete(name)
322 state.headerAppends?.delete(normalizedName)
323 ;(state.removedHeaders ||= new Set()).add(normalizedName)
324 if (normalizedName === 'set-cookie') {
325 state.setCookieBehavior = 'replace'
326 }
328​
329function getDistinctCookieKey(
330 name: string,
331 options: { domain?: string; path?: string },
332 defaultPath = '',
333): string {
334 return [name, options.domain || '', options.path ?? defaultPath].join(';')
336​
337function getDistinctCookieKeyFromHeader(cookie: string): string {
338 const parsed = parseSetCookie(cookie)
339 // A cookie the parser rejects is identified by its exact string, so merging
340 // it again replaces it. Header values cannot contain NUL, so this key cannot
341 // match a parsed name, domain, and path.
342 return parsed ? getDistinctCookieKey(parsed.name, parsed) : `\0${cookie}`
344​
345function replaceSetCookieValues(
346 headers: Headers,
347 cookies: Array<string>,
348): void {
349 headers.delete('set-cookie')
350 for (const cookie of cookies) {
351 headers.append('set-cookie', cookie)
352 }
354​
355// Every reconcile pass merges the same immutable cookie strings again, so
356// parse each string's identity once per request.
357function getCookieKey(state: ResponseState, cookie: string): string {
358 const keys = (state.setCookieKeys ||= new Map())
359 let key = keys.get(cookie)
360 if (key === undefined) {
361 key = getDistinctCookieKeyFromHeader(cookie)
362 keys.set(cookie, key)
363 }
364 return key
366​
367function getMergedSetCookieValues(
368 state: ResponseState,
369 currentCookies: Array<string>,
370 cookiesToMerge: Array<string>,
371): Array<string> {
372 if (currentCookies.length === 0) {
373 return cookiesToMerge
374 }
375 const cookieKeysToMerge = new Set<string>()
376 for (const cookie of cookiesToMerge) {
377 cookieKeysToMerge.add(getCookieKey(state, cookie))
378 }
379 return currentCookies
380 .filter((cookie) => !cookieKeysToMerge.has(getCookieKey(state, cookie)))
381 .concat(cookiesToMerge)
383​
384function mergeStartSetCookieValues(
385 event: StartEvent,
386 cookies: Array<string>,
387): void {
388 if (cookies.length === 0) {
389 return
390 }
391​
392 const state = getResponseState(event)
393 state.removedHeaders?.delete('set-cookie')
394 if (state.setCookieBehavior !== 'replace') {
395 state.setCookieBehavior = 'merge'
396 }
397 replaceSetCookieValues(
398 state.headers,
399 getMergedSetCookieValues(state, getSetCookieValues(state.headers), cookies),
400 )
402​
403function hasProtectedHeaderChanges(
404 response: Response,
405 protectedHeaders: ProtectedHeaders,
406): boolean {
407 const headers = response.headers
408 for (const [name, value] of protectedHeaders) {
409 if (headers.get(name) !== value) {
410 return true
411 }
412 }
413 return false
415​
416function applyProtectedHeaders(
417 protectedHeaders: ProtectedHeaders,
418 headers: Headers,
419): void {
420 for (const [name, value] of protectedHeaders) {
421 if (value === null) {
422 headers.delete(name)
423 } else {
424 headers.set(name, value)
425 }
426 }
428​
429function applyHeaderState(
430 target: Headers,
431 state: ResponseState,
432 generatedBody: boolean,
433 protectedHeaders?: ProtectedHeaders,
434 appliedHeaderAppends?: Map<string, HeaderAppendOperation>,
435): Headers {
436 let headers = target
437 const mutableHeaders = () => {
438 if (headers === target) {
439 headers = new Headers(target)
440 }
441 return headers
442 }
443​
444 if (state.clearHeaders) {
445 // Snapshot the keys before deleting: deleting during live Headers
446 // iteration skips entries.
447 for (const name of Array.from(target.keys())) {
448 if (!protectedHeaders?.has(name)) {
449 mutableHeaders().delete(name)
450 }
451 }
452 }
453​
454 if (!state.clearHeaders && state.removedHeaders) {
455 for (const name of state.removedHeaders) {
456 if (!protectedHeaders?.has(name) && headers.has(name)) {
457 mutableHeaders().delete(name)
458 }
459 }
460 }
461​
462 // Headers iteration combines repeated header values into one comma-joined
463 // value, so `set` carries multi-value headers (Link, Vary, ...) losslessly.
464 // Set-Cookie is the one header where comma-joining is unsafe (cookie
465 // attributes like Expires contain commas), so it is handled separately.
466 for (const [name, value] of state.headers) {
467 if (
468 name !== 'set-cookie' &&
469 !protectedHeaders?.has(name) &&
470 !(generatedBody && GENERATED_BODY_EXCLUDED_HEADERS.has(name))
471 ) {
472 let append = state.headerAppends?.get(name)
473 if (!append) {
474 if (headers.get(name) !== value) {
475 mutableHeaders().set(name, value)
476 }
477 continue
478 }
479 const applied = appliedHeaderAppends?.get(name)
480 const pending: Array<string> = []
481 while (append && append !== applied) {
482 pending.push(append.value)
483 append = append.previous
484 }
485 for (let index = pending.length - 1; index >= 0; index--) {
486 mutableHeaders().append(name, pending[index]!)
487 }
488 }
489 }
490​
491 if (state.setCookieBehavior && !protectedHeaders?.has('set-cookie')) {
492 const eventSetCookies = getSetCookieValues(state.headers)
493 const currentCookies = getSetCookieValues(headers)
494 const cookies =
495 state.setCookieBehavior === 'replace'
496 ? eventSetCookies
497 : getMergedSetCookieValues(state, currentCookies, eventSetCookies)
498 if (
499 cookies.length !== currentCookies.length ||
500 cookies.some((cookie, index) => cookie !== currentCookies[index])
501 ) {
502 replaceSetCookieValues(mutableHeaders(), cookies)
503 }
504 }
505 return headers
507​
508function canHaveBody(method: string, status: number): boolean {
509 return method !== 'HEAD' && status !== 204 && status !== 205 && status !== 304
511​
512/** A protected content type marks a Start-serialized body the client decodes. */
513function isSerializedResponse(protectedHeaders: ProtectedHeaders | undefined) {
514 return typeof protectedHeaders?.get('content-type') === 'string'
516​
517/**
518 * A helper status that forbids a body never applies to a serialized
519 * server-function reply, because the client must decode it. Only a HEAD request
520 * drops its body.
521 */
522function getHelperStatus(
523 state: ResponseState | undefined,
524 serialized: boolean,
525): number | undefined {
526 const status = state?.status
527 if (!serialized || status === undefined || canHaveBody('GET', status)) {
528 return status
529 }
530 if (process.env.NODE_ENV !== 'production' && !state!.bodylessStatusWarned) {
531 state!.bodylessStatusWarned = true
532 console.warn(
533 `setResponseStatus(${status}) does not apply to serialized server function responses, because the client must decode their body. Return a Response from the server function to send a response without a body.`,
534 )
535 }
536 return undefined
538​
539/** Helper status text describes the helper status and is ignored with it. */
540function getHelperStatusText(
541 state: ResponseState | undefined,
542 helperStatus: number | undefined,
543): string | undefined {
544 return helperStatus === state?.status ? state?.statusText : undefined
546​
547function cancelDroppedBody(response: Response, reason: string): void {
548 try {
549 response.body?.cancel(reason).catch(() => {})
550 } catch {
551 // Ignore locked or already-consumed bodies.
552 }
554​
555function createReconciledResponse(
556 body: Response['body'],
557 status: number,
558 statusText: string,
559 headers: Headers,
560): Response {
561 try {
562 return new Response(body, {
563 status,
564 statusText,
565 headers,
566 })
567 } catch (cause) {
568 throw new Error(
569 'Unable to reconcile response because its body has already been consumed or locked.',
570 { cause },
571 )
572 }
574​
575/** Apply helper state to a response that leaves Start. */
576export function finalizeResponse(
577 response: Response,
578 event: StartEvent,
579): Response {
580 return applyResponseState(response, event, event.request.method)
582​
583/**
584 * Apply helper state with the body rules of `method`. Request middleware still
585 * reads a HEAD response's body, so the pipeline applies GET rules and strips a
586 * HEAD body only when the response leaves it.
587 */
588function applyResponseState(
589 response: Response,
590 event: StartEvent,
591 method: string,
592 disposeBody?: (reason: string) => void,
593): Response {
594 const protectedHeaders = getProtectedResponseHeaders(response)
595 const serialized = isSerializedResponse(protectedHeaders)
596 let helperStatus = getHelperStatus(event.responseState, serialized)
597 // Some runtimes, such as Bun, allow a body on a 204, 205, or 304 response,
598 // so check the response's own status too. Read the body last: the getter
599 // allocates a stream for responses that have not exposed one yet.
600 const mustDropBody =
601 !canHaveBody(method, helperStatus ?? response.status) &&
602 response.body !== null
603 if (mustDropBody) {
604 const reason =
605 method === 'HEAD'
606 ? 'HEAD body stripped'
607 : 'Response body dropped by Start reconciliation'
608 if (disposeBody) {
609 disposeBody(reason)
610 } else {
611 cancelDroppedBody(response, reason)
612 }
613 // Cancellation/SSR cleanup can write helpers. Read their final state
614 // before applying headers or recording appends.
615 helperStatus = getHelperStatus(event.responseState, serialized)
616 }
617 const state = event.responseState
618​
619 // Without helper writes, preserve the response.
620 if (!state && !mustDropBody) {
621 event.currentResponse = response
622 return response
623 }
624​
625 const status = helperStatus ?? response.status
626 const statusText =
627 getHelperStatusText(state, helperStatus) ?? response.statusText
628 const statusChanged = status !== response.status
629 const statusTextChanged = statusText !== response.statusText
630 // applyHeaderState returns the same headers when helper intent changes
631 // nothing.
632 const headers = state
633 ? applyHeaderState(
634 response.headers,
635 state,
636 serialized,
637 protectedHeaders,
638 event.responseHeaderAppends?.get(response),
639 )
640 : response.headers
641​
642 const reconciled =
643 statusChanged ||
644 statusTextChanged ||
645 mustDropBody ||
646 headers !== response.headers
647 ? createReconciledResponse(
648 mustDropBody ? null : response.body,
649 status,
650 statusText,
651 headers,
652 )
653 : response
654 if (protectedHeaders && reconciled !== response) {
655 installProtectedResponseHeaders(reconciled, protectedHeaders)
656 }
657 return publishResponse(reconciled, event)
659​
660function publishResponse(response: Response, event: StartEvent): Response {
661 const headerAppends = event.responseState?.headerAppends
662 if (headerAppends?.size) {
663 ;(event.responseHeaderAppends ||= new WeakMap()).set(
664 response,
665 new Map(headerAppends),
666 )
667 }
668 event.currentResponse = response
669 return response
671​
672function getHttpErrorStatus(status: number | undefined): number | undefined {
673 return status !== undefined && status >= 400 ? status : undefined
675​
676/**
677 * Status for a response built from an uncaught error. Only an error status
678 * (400-599) from a helper or from error metadata describes the failure, so a
679 * success or redirect status set before the throw cannot hide it. The error is
680 * logged unless its own metadata marks it as an HTTP error. Reporting runs
681 * before helper state is read, so hooks that write helpers are included.
682 */
683function resolveErrorStatus(
684 error: unknown,
685 event: Pick<StartEvent, 'responseState'> | undefined,
686): { status: number; statusText: string } {
687 const metadataStatus = getErrorStatus(error)
688 const errorStatus = getHttpErrorStatus(metadataStatus)
689 if (errorStatus === undefined) {
690 console.error(error)
691 }
692 const state = event?.responseState
693 const helperStatus = getHttpErrorStatus(state?.status)
694 const status = helperStatus ?? errorStatus ?? 500
695 const statusText =
696 getHelperStatusText(state, helperStatus) ??
697 (status === errorStatus || metadataStatus === undefined
698 ? getErrorStatusText(error)
699 : undefined) ??
700 ''
701 if (state && state.status !== helperStatus) {
702 // The failure replaced the response that status was meant for. Discard it
703 // so later reconciliation keeps the error status.
704 state.status = undefined
705 state.statusText = undefined
706 }
707 return { status, statusText }
709​
710/**
711 * Internal: status and status text for a serialized server-function error.
712 * Logs the error and discards a non-error helper status, like any error
713 * response Start builds.
714 */
715export function resolveErrorResponseStatus(error: unknown): {
716 status: number
717 statusText: string
718} {
719 return resolveErrorStatus(error, eventStorage.getStore())
721​
722function createErrorResponse(error: unknown, event: StartEvent): Response {
723 // Error metadata and reporting hooks can call public response helpers.
724 // Materialize them before taking the state used to build the response.
725 let headers = getErrorHeaders(error) ?? new Headers()
726 const { status, statusText } = resolveErrorStatus(error, event)
727 const state = event.responseState
728 const body = canHaveBody(event.request.method, status)
729 ? JSON.stringify({
730 status,
731 statusText,
732 unhandled: true,
733 message: 'HTTPError',
734 })
735 : null
736 if (!headers.has('content-type')) {
737 headers.set('content-type', 'application/json')
738 }
739​
740 if (state) {
741 headers = applyHeaderState(headers, state, true)
742 }
743​
744 // Build Start-owned errors with their final headers instead of creating a
745 // response that reconciliation must immediately reconstruct. A byte body
746 // keeps Fetch from restoring Content-Type after an explicit helper removal.
747 return publishResponse(
748 new Response(
749 body !== null && !headers.has('content-type')
750 ? new TextEncoder().encode(body)
751 : body,
752 { status, statusText, headers },
753 ),
754 event,
755 )
757​
758function finalizeError(error: unknown, event: StartEvent): Response {
759 if (error instanceof Response) {
760 return finalizeResponse(error, event)
761 }
762 return createErrorResponse(error, event)
764​
765export function handleStartError(error: unknown): Response {
766 const event = eventStorage.getStore()
767 if (event) {
768 return finalizeError(error, event)
769 }
770 if (error instanceof Response) {
771 return error
772 }
773 // Outside a server entry there is no invocation to recover. The thrown
774 // value is never used as a request identifier.
775 const request = new Request('http://localhost')
776 return createErrorResponse(error, {
777 request,
778 requestUrl: new URL(request.url),
779 })
781​
782/** Apply helper state to a response inside the request middleware pipeline. */
783export function reconcileResponse(
784 response: Response,
785 event: StartEvent,
786 disposeBody?: (reason: string) => void,
787): Response {
788 // Without helper writes, only a bodyless status could change the response,
789 // and the response Start last published already satisfies it. Router
790 // redirects still need destination resolution (or an RPC envelope), so they
791 // keep their identity until createStartHandler resolves them; response
792 // getters can already read the helper overlay on this snapshot.
793 if (
794 (!event.responseState &&
795 (response === event.currentResponse ||
796 canHaveBody('GET', response.status))) ||
797 isRedirect(response)
798 ) {
799 event.currentResponse = response
800 return response
801 }
802 return applyResponseState(response, event, 'GET', disposeBody)
804​
805/**
806 * Restore protocol headers that middleware changed directly on the response.
807 * Start does this once, when the response leaves the request middleware
808 * pipeline; helper writes never override them.
809 */
810export function restoreResponseProtocol(
811 response: Response,
812 event: StartEvent,
813): Response {
814 const protectedHeaders = getProtectedResponseHeaders(response)
815 if (
816 !protectedHeaders ||
817 !hasProtectedHeaderChanges(response, protectedHeaders)
818 ) {
819 return response
820 }
821 const headers = new Headers(response.headers)
822 applyProtectedHeaders(protectedHeaders, headers)
823 const restored = createReconciledResponse(
824 response.body,
825 response.status,
826 response.statusText,
827 headers,
828 )
829 transferResponseMetadata(response, restored)
830 event.currentResponse = restored
831 return restored
833​
834/**
835 * Build a Start-owned serialized reply with already normalized protocol
836 * headers. A bodyless helper status never applies to it; only a HEAD request
837 * drops its body.
838 */
839export function createFinalizedResponse(
840 body: string | Uint8Array,
841 headers: Headers,
842 protectedHeaders: ProtectedHeaders,
843 event: StartEvent,
844): Response {
845 const state = event.responseState
846 let status = 200
847 let statusText = ''
848 if (state) {
849 const helperStatus = getHelperStatus(state, true)
850 status = helperStatus ?? 200
851 statusText = getHelperStatusText(state, helperStatus) ?? ''
852 headers = applyHeaderState(headers, state, true, protectedHeaders)
853 }
854 const response = new Response(
855 canHaveBody(event.request.method, status) ? (body as BodyInit) : null,
856 { status, statusText, headers },
857 )
858 // A new response has no protection to merge with.
859 installProtectedResponseHeaders(response, protectedHeaders)
860 return publishResponse(response, event)
862​
863export function protectResponseHeaders(
864 response: Response,
865 headers: ProtectedHeaders,
866): void {
867 // Callers supply immutable protocol requirements with lowercase names.
868 // Share those requirements across responses instead of capturing each one.
869 const previous = getProtectedResponseHeaders(response)
870 if (previous === headers) {
871 return
872 }
873 if (previous) {
874 const merged = new Map(previous)
875 for (const [name, value] of headers) {
876 merged.set(name, value)
877 }
878 headers = merged
879 }
880 installProtectedResponseHeaders(response, headers)
882​
883/**
884 * Set and protect transport headers on a new response. Reuse the body stream
885 * without cloning or teeing it; callers transfer ownership to the result.
886 */
887export function setProtectedResponseHeaders(
888 response: Response,
889 headers: ProtectedHeaders,
890): Response {
891 let next: Response
892 try {
893 // Response copies its initializer's headers; change only that fresh copy.
894 next = new Response(response.body, response)
895 applyProtectedHeaders(headers, next.headers)
896 } catch (cause) {
897 throw new Error(
898 'Unable to set response header because its body has already been consumed or locked.',
899 { cause },
900 )
901 }
902 transferResponseMetadata(response, next)
903 protectResponseHeaders(next, headers)
904 return next
906​
907function decodePathname(pathname: string): string | undefined {
908 try {
909 // Return the value so bundlers preserve the potentially throwing decode.
910 return decodeURI(pathname)
911 } catch (error) {
912 if (error instanceof URIError) {
913 return undefined
914 }
915 throw error
916 }
918​
919/** A Start handler that runs in a request scope and receives its event. */
920type ScopedRequestHandler = (
921 request: Request,
922 requestOpts: any,
923 event: StartEvent,
924) => MaybePromise<Response>
925​
926function runInStartRequest(
927 request: Request,
928 requestOpts: any,
929 handler: ScopedRequestHandler,
930): MaybePromise<Response> {
931 let requestUrl: URL
932 try {
933 requestUrl = new URL(request.url)
934 } catch (error) {
935 if (error instanceof TypeError) {
936 return new Response(null, { status: 400, statusText: 'Bad Request' })
937 }
938 throw error
939 }
940 const pathname = requestUrl.pathname
941 // Validate encoded paths without changing the pathname used for routing.
942 if (pathname.includes('%') && decodePathname(pathname) === undefined) {
943 return new Response(null, { status: 400, statusText: 'Bad Request' })
944 }
945 const event: StartEvent = { request, requestUrl }
946 return eventStorage.run(event, handler, request, requestOpts, event)
948​
949/**
950 * Keep the complete server entry, including custom error handling, inside one
951 * request scope. A custom returned response is used as-is; call handleStartError
952 * in a custom catch to preserve Start's response helper state.
953 */
954export function createServerEntry<TRegister = unknown>(entry: {
955 fetch: RequestHandler<TRegister>
956}): { fetch: RequestHandler<TRegister> } {
957 return {
958 fetch: withStartRequest(async (request: Request, requestOpts: any) => {
959 try {
960 return await entry.fetch(request, requestOpts)
961 } catch (error) {
962 return handleStartError(error)
963 }
964 }),
965 }
967​
968/**
969 * Establish request scope; the response pipeline owns reconciliation. A nested
970 * handler delegating the same request participates in its scope. Independent
971 * fetch invocations and different requests get a fresh event.
972 */
973export function withStartRequest(handler: ScopedRequestHandler) {
974 return (request: Request, requestOpts: any): MaybePromise<Response> => {
975 const event = eventStorage.getStore()
976 if (event?.request === request) {
977 return handler(request, requestOpts, event)
978 }
979 return runInStartRequest(request, requestOpts, handler)
980 }
982​
983export function getStartEvent() {
984 const event = eventStorage.getStore()
985 if (!event) {
986 throw new Error(
987 `No StartEvent found in AsyncLocalStorage. Make sure you are using the function within the server runtime.`,
988 )
989 }
990 return event
992​
993/**
994 * Internal: returns the per-request parsed URL for `request`, memoized on the
995 * Start event so the framework parses each request URL only once. Falls back
996 * to parsing when called outside a Start event (e.g. in unit tests) or for a
997 * foreign request. Callers MUST NOT mutate the returned URL.
998 */
999export function getParsedRequestUrl(request: Request): URL {
1000 const event = eventStorage.getStore()
1001 if (event && event.request === request) {
1002 return event.requestUrl
1004 return new URL(request.url)
1006​
1007export function getRequest(): Request {
1008 return getStartEvent().request
1010​
1011export function getRequestHeaders(): TypedHeaders<RequestHeaderMap> {
1012 return getStartEvent().request.headers as TypedHeaders<RequestHeaderMap>
1014​
1015export function getRequestHeader(name: RequestHeaderName): string | undefined {
1016 return getRequestHeaders().get(name) ?? undefined
1018​
1019export function getRequestIP(opts?: {
1020 /**
1021 * Use the X-Forwarded-For HTTP header set by proxies.
1023 * Note: Make sure that this header can be trusted (your application running behind a CDN or reverse proxy) before enabling.
1024 */
1025 xForwardedFor?: boolean
1026}) {
1027 const request = getRequest()
1028 if (opts?.xForwardedFor) {
1029 const forwardedFor = request.headers.get('x-forwarded-for')
1030 const forwardedIp = forwardedFor?.split(',', 1)[0]?.trim()
1031 if (forwardedIp) {
1032 return forwardedIp
1035​
1036 return (
1037 (request as Request & { context?: { clientAddress?: string }; ip?: string })
1038 .context?.clientAddress ||
1039 (request as Request & { ip?: string }).ip ||
1040 undefined
1043​
1044/**
1045 * Get the request hostname.
1047 * If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
1049 * If no host header is found, it uses the request URL's host.
1050 */
1051export function getRequestHost(opts?: { xForwardedHost?: boolean }) {
1052 const headers = getRequestHeaders()
1053 if (opts?.xForwardedHost) {
1054 const forwardedHost = headers.get('x-forwarded-host')
1055 const host = forwardedHost?.split(',', 1)[0]?.trim()
1056 if (host) {
1057 return host
1060 return headers.get('host') || getStartEvent().requestUrl.host || 'localhost'
1062​
1063/**
1064 * Get the full incoming request URL.
1066 * If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
1068 * If `xForwardedProto` is `false`, it will not use the `x-forwarded-proto` header.
1069 */
1070export function getRequestUrl(opts?: {
1071 xForwardedHost?: boolean
1072 xForwardedProto?: boolean
1073}) {
1074 const event = getStartEvent()
1075 // Clone the memoized URL so callers can mutate the result freely.
1076 const url = new URL(event.requestUrl)
1077 url.protocol = getRequestProtocol(opts)
1078 if (opts?.xForwardedHost) {
1079 const host = getRequestHost(opts)
1080 if (host) {
1081 url.host = host
1082 if (!/:\d+$/.test(host)) {
1083 url.port = ''
1087 return url
1089​
1090/**
1091 * Get the request protocol.
1093 * If `x-forwarded-proto` header is set to "https", it will return "https". You can disable this behavior by setting `xForwardedProto` to `false`.
1095 * If protocol cannot be determined, it will default to "http".
1096 */
1097export function getRequestProtocol(opts?: {
1098 xForwardedProto?: boolean
1099}): 'http' | 'https' | (string & {}) {
1100 const request = getRequest()
1101 if (opts?.xForwardedProto !== false) {
1102 const forwardedProto = request.headers
1103 .get('x-forwarded-proto')
1104 ?.split(',', 1)[0]
1105 ?.trim()
1106 .toLowerCase()
1107 if (forwardedProto === 'https') {
1108 return 'https'
1110 if (forwardedProto === 'http') {
1111 return 'http'
1114 const url = getStartEvent().requestUrl
1115 return url.protocol.slice(0, -1) as 'http' | 'https' | (string & {})
1117​
1118export function setResponseHeaders(
1119 headers: TypedHeaders<ResponseHeaderMap> | ReadonlyResponseHeaders,
1120): void {
1121 if (headers instanceof Headers) {
1122 for (const [name, value] of headers) {
1123 if (name !== 'set-cookie') {
1124 setResponseHeader(name as ResponseHeaderName, value)
1127​
1128 const cookies = getSetCookieValues(headers)
1129 if (cookies.length > 0) {
1130 setResponseHeader(
1131 'set-cookie',
1132 cookies.length === 1 ? cookies[0]! : cookies,
1135 return
1137​
1138 if (!Array.isArray(headers)) {
1139 for (const [name, value] of Object.entries(
1140 headers as unknown as Record<string, string | Array<string>>,
1141 )) {
1142 setResponseHeader(name as ResponseHeaderName, value)
1144 return
1146​
1147 const groupedHeaders = new Map<
1148 string,
1149 { name: ResponseHeaderName; values: Array<string> }
1150 >()
1151 const addHeader = (name: string, value: string) => {
1152 const normalizedName = normalizeHeaderName(name)
1153 let header = groupedHeaders.get(normalizedName)
1154 if (!header) {
1155 header = { name: name as ResponseHeaderName, values: [] }
1156 groupedHeaders.set(normalizedName, header)
1158 header.values.push(value)
1160​
1161 for (const [name, value] of headers) {
1162 addHeader(name, value)
1164​
1165 for (const { name, values } of groupedHeaders.values()) {
1166 setResponseHeader(name, values.length === 1 ? values[0]! : values)
1169​
1170let SnapshotHeaders: typeof Headers | undefined
1171​
1172/**
1173 * Outside production, return the snapshot as a Headers subclass that warns when
1174 * code tries to change the outgoing response through it. Its contents and
1175 * behavior are identical to the production snapshot.
1176 */
1177function toResponseHeadersSnapshot(headers: Headers): ReadonlyResponseHeaders {
1178 if (process.env.NODE_ENV === 'production') {
1179 return headers as ReadonlyResponseHeaders
1181 SnapshotHeaders ??= class ResponseHeadersSnapshot extends Headers {
1182 override append(name: string, value: string): void {
1183 warnSnapshotMutation('append')
1184 super.append(name, value)
1186 override delete(name: string): void {
1187 warnSnapshotMutation('delete')
1188 super.delete(name)
1190 override set(name: string, value: string): void {
1191 warnSnapshotMutation('set')
1192 super.set(name, value)
1195 // The constructor fills entries without calling the overridden methods.
1196 const entries: Array<[string, string]> = []
1197 for (const [name, value] of headers) {
1198 if (name !== 'set-cookie') {
1199 entries.push([name, value])
1202 for (const cookie of getSetCookieValues(headers)) {
1203 entries.push(['set-cookie', cookie])
1205 return new SnapshotHeaders(entries) as ReadonlyResponseHeaders
1207​
1208function warnSnapshotMutation(method: string): void {
1209 console.warn(
1210 `getResponseHeaders().${method}() does not change the response: getResponseHeaders() returns a read-only snapshot. Use setResponseHeader, appendResponseHeader, removeResponseHeader, clearResponseHeaders, or setCookie instead.`,
1213​
1214/**
1215 * Read a detached snapshot of the effective response headers.
1216 * Use response header and cookie helpers to change the outgoing response.
1217 */
1218export function getResponseHeaders(): ReadonlyResponseHeaders {
1219 const event = getStartEvent()
1220 const state = event.responseState
1221 const currentResponse = event.currentResponse
1222 if (!currentResponse) {
1223 return toResponseHeadersSnapshot(
1224 state ? new Headers(state.headers) : new Headers(),
1227 const protectedHeaders = getProtectedResponseHeaders(currentResponse)
1228 let headers = currentResponse.headers
1229 if (state) {
1230 headers = applyHeaderState(
1231 headers,
1232 state,
1233 isSerializedResponse(protectedHeaders),
1234 protectedHeaders,
1235 event.responseHeaderAppends?.get(currentResponse),
1238 // Read helpers always return a detached snapshot, including when applying
1239 // helper intent did not need to copy any headers.
1240 if (headers === currentResponse.headers) {
1241 headers = new Headers(headers)
1243 if (protectedHeaders) {
1244 applyProtectedHeaders(protectedHeaders, headers)
1246 return toResponseHeadersSnapshot(headers)
1248​
1249export function getResponseHeader(
1250 name: ResponseHeaderName,
1251): string | undefined {
1252 const event = getStartEvent()
1253 const normalizedName = normalizeHeaderName(name)
1254 if (
1255 normalizedName === 'set-cookie' ||
1256 event.responseState?.headerAppends?.has(normalizedName)
1257 ) {
1258 return getResponseHeaders().get(name) ?? undefined
1260 const currentResponse = event.currentResponse
1261 const protectedHeaders = currentResponse
1262 ? getProtectedResponseHeaders(currentResponse)
1263 : undefined
1264 if (protectedHeaders?.has(normalizedName)) {
1265 return protectedHeaders.get(normalizedName) ?? undefined
1267 if (
1268 GENERATED_BODY_EXCLUDED_HEADERS.has(normalizedName) &&
1269 isSerializedResponse(protectedHeaders)
1270 ) {
1271 return currentResponse!.headers.get(name) ?? undefined
1273​
1274 const state = event.responseState
1275 if (state) {
1276 const stateValue = state.headers.get(name)
1277 if (stateValue !== null) {
1278 return stateValue
1280​
1281 if (state.clearHeaders) {
1282 return undefined
1284​
1285 if (state.removedHeaders?.has(normalizedName)) {
1286 return undefined
1289​
1290 return currentResponse?.headers.get(name) ?? undefined
1292​
1293export function setResponseHeader(
1294 name: ResponseHeaderName,
1295 value: string | Array<string>,
1296): void {
1297 const event = getStartEvent()
1298 if (Array.isArray(value)) {
1299 deleteHeaderState(event, name)
1300 for (const valueItem of value) {
1301 appendHeaderState(event, name, valueItem)
1303 } else {
1304 setHeaderState(event, name, value)
1307​
1308/**
1309 * Append a response header value without replacing existing values.
1311 * Ordinary values are appended once per returned response. Start transfers
1312 * that application state when it reconstructs a response. A new response
1313 * created by application code is fresh input: copying already-reconciled
1314 * headers into it also copies their appended values, and helper appends apply
1315 * again. Mutate the current response or pass its middleware result through
1316 * when preserving an existing response's headers.
1318 * For `set-cookie`, values must be fully serialized cookie strings; they are
1319 * merged into the outgoing cookies and deduped by cookie identity
1320 * (name + domain + path), exactly like `setCookie`. A value that cannot be
1321 * parsed is identified by its exact string. This is the primitive to
1322 * use when bridging external session/auth libraries that produce raw
1323 * `Set-Cookie` strings.
1325 * ```ts
1326 * appendResponseHeader('set-cookie', await externalLib.commitSession(session))
1327 * ```
1328 */
1329export function appendResponseHeader(
1330 name: ResponseHeaderName,
1331 value: string | Array<string>,
1332): void {
1333 const event = getStartEvent()
1334 const values = Array.isArray(value) ? value : [value]
1335 if (normalizeHeaderName(name) === 'set-cookie') {
1336 // Merge one value at a time so a batched call behaves exactly like
1337 // sequential calls (same-identity cookies dedupe, last wins).
1338 for (const valueItem of values) {
1339 // Validate before changing cookie identity or removal intent. External
1340 // libraries supply serialized strings, which can fail native validation.
1341 const headers = new Headers({ 'set-cookie': valueItem })
1342 mergeStartSetCookieValues(event, getSetCookieValues(headers))
1344 return
1346 for (const valueItem of values) {
1347 appendHeaderState(event, name, valueItem)
1350​
1351export function removeResponseHeader(name: ResponseHeaderName): void {
1352 deleteHeaderState(getStartEvent(), name)
1354​
1355export function clearResponseHeaders(
1356 headerNames?: Array<ResponseHeaderName>,
1357): void {
1358 const event = getStartEvent()
1359 if (headerNames && headerNames.length > 0) {
1360 for (const name of headerNames) {
1361 deleteHeaderState(event, name)
1363 return
1365​
1366 const state = getResponseState(event)
1367 state.clearHeaders = true
1368 state.headers = new Headers()
1369 state.headerAppends = undefined
1371​
1372export function getResponseStatus(): number {
1373 const event = getStartEvent()
1374 const currentResponse = event.currentResponse
1375 const serialized =
1376 !!currentResponse &&
1377 isSerializedResponse(getProtectedResponseHeaders(currentResponse))
1378 return (
1379 getHelperStatus(event.responseState, serialized) ??
1380 currentResponse?.status ??
1381 200
1384​
1385export function setResponseStatus(code?: number, text?: string): void {
1386 const event = getStartEvent()
1387 if (code !== undefined) {
1388 // An unusable code must not replace an earlier, returned, or error status.
1389 // Ignore the whole call, including its status text, which describes it.
1390 const status = sanitizeStatusCode(code)
1391 if (status === undefined) {
1392 if (process.env.NODE_ENV !== 'production') {
1393 console.warn(
1394 `setResponseStatus(${code}) was ignored: Fetch Response status codes must be integers from 200 to 599.`,
1397 return
1399 getResponseState(event).status = status
1401 if (text) {
1402 getResponseState(event).statusText = sanitizeStatusMessage(text)
1405​
1406/**
1407 * Parse the request to get HTTP Cookie header string and return an object of all cookie name-value pairs.
1408 * @returns Object of cookie name-value pairs
1409 * ```ts
1410 * const cookies = getCookies()
1411 * ```
1412 */
1413export function getCookies(): Record<string, string> {
1414 const cookies = parseCookie(getRequestHeaders().get('cookie') || '')
1415 const definedCookies: Record<string, string> = Object.create(null)
1416​
1417 for (const [name, value] of Object.entries(cookies)) {
1418 if (value !== undefined) {
1419 definedCookies[name] = value
1422​
1423 return definedCookies
1425​
1426/**
1427 * Get a cookie value by name.
1428 * @param name Name of the cookie to get
1429 * @returns {*} Value of the cookie (String or undefined)
1430 * ```ts
1431 * const authorization = getCookie('Authorization')
1432 * ```
1433 */
1434export function getCookie(name: string): string | undefined {
1435 return getCookies()[name]
1437​
1438/**
1439 * Set a cookie value by name.
1440 * @param name Name of the cookie to set
1441 * @param value Value of the cookie to set
1442 * @param options {CookieSerializeOptions} Options for serializing the cookie
1443 * ```ts
1444 * setCookie('Authorization', '1234567')
1445 * ```
1446 */
1447export function setCookie(
1448 name: string,
1449 value: string,
1450 options?: CookieSerializeOptions,
1451): void {
1452 const { encode, stringify, ...attrs } = options ?? {}
1453 mergeStartSetCookieValues(getStartEvent(), [
1454 serializeCookie(
1455 { name, value, path: '/', ...attrs },
1456 { encode, stringify },
1457 ),
1458 ])
1460​
1461/**
1462 * Remove a cookie by name.
1463 * @param name Name of the cookie to delete
1464 * @param serializeOptions {CookieSerializeOptions} Cookie options
1465 * ```ts
1466 * deleteCookie('SessionId')
1467 * ```
1468 */
1469export function deleteCookie(
1470 name: string,
1471 options?: CookieSerializeOptions,
1472): void {
1473 setCookie(name, '', {
1474 ...options,
1475 maxAge: 0,
1476 })
1478​
1479/**
1480 * Internal: helper status state for a serialized server-function reply.
1481 * Bodyless statuses never apply to it and are omitted with their status text.
1482 */
1483export function getSerializedResponseState(): {
1484 status: number | undefined
1485 statusText: string | undefined
1486} {
1487 const state = getStartEvent().responseState
1488 const status = getHelperStatus(state, true)
1489 return { status, statusText: getHelperStatusText(state, status) }