Open History to see the last commit
1import { invariant, isNotFound, isRedirect } from '@tanstack/router-core'
2import {
3 createRawStreamRPCPlugin,
4 defaultSerovalDeserializerPlugins as routerDefaultSerovalPlugins,
5} from '@tanstack/router-core/ssr/server'
6import {
7 TSS_CONTENT_TYPE_FRAMED_VERSIONED,
8 TSS_FORMDATA_CONTEXT,
9 X_TSS_RAW_RESPONSE,
10 X_TSS_SERIALIZED,
11 getSerovalPlugins,
12} from '@tanstack/start-client-core'
13import {
14 MAX_FRAMED_STREAMS,
15 MAX_FRAME_PAYLOAD_SIZE,
16} from '@tanstack/start-client-core/client-rpc'
17import { fromJSON, toCrossJSONAsync, toCrossJSONStream } from 'seroval'
18import {
19 createFinalizedResponse,
20 getErrorHeaders,
21 getParsedRequestUrl,
22 getSerializedResponseState,
23 protectResponseHeaders,
24 resolveErrorResponseStatus,
25 setProtectedResponseHeaders,
26} from './internal-request-response'
27import { getServerFnById } from './getServerFnById'
28import { createMultiplexedStream } from './frame-protocol'
29import type {
30 LateStreamRegistration,
31 MultiplexedStreamOptions,
32 MultiplexedStreamRecord,
33} from './frame-protocol'
34import type { Plugin as SerovalPlugin } from 'seroval'
35import type { StartEvent } from './internal-request-response'
36β
37// Serialized replies are decoded by the client from their body. With a
38// helper-selected 3xx status, a Location would let fetch follow it first.
39const SERIALIZED_JSON_HEADERS: ReadonlyMap<string, string | null> = new Map([
40 ['content-type', 'application/json'],
41 [X_TSS_SERIALIZED, 'true'],
42 [X_TSS_RAW_RESPONSE, null],
43 ['location', null],
44])
45// A shared template the Response constructor copies. Never mutate it.
46const SERIALIZED_JSON_HEADER_INIT = new Headers({
47 'content-type': 'application/json',
48 [X_TSS_SERIALIZED]: 'true',
49})
50β
51/** Completed bytes own no stream until the request pipeline accepts them. */
52export class DeferredResponse {
53 constructor(private readonly body: Uint8Array) {}
54β
55 createResponse(event: StartEvent): Response {
56 return createFinalizedResponse(
57 this.body,
58 SERIALIZED_JSON_HEADER_INIT,
59 SERIALIZED_JSON_HEADERS,
60 event,
61 )
62 }
63}
64β
65const SERIALIZED_FRAMED_HEADERS: ReadonlyMap<string, string | null> = new Map([
66 ['content-type', TSS_CONTENT_TYPE_FRAMED_VERSIONED],
67 [X_TSS_SERIALIZED, 'true'],
68 [X_TSS_RAW_RESPONSE, null],
69 ['location', null],
70])
71const NOT_FOUND_HEADERS: ReadonlyMap<string, string | null> = new Map([
72 ['content-type', 'application/json'],
73 [X_TSS_SERIALIZED, null],
74 [X_TSS_RAW_RESPONSE, null],
75 ['location', null],
76])
77const RAW_RESPONSE_HEADERS: ReadonlyMap<string, string | null> = new Map([
78 [X_TSS_RAW_RESPONSE, 'true'],
79])
80// A Response the server function threw. The client rethrows it.
81const THROWN_RESPONSE_HEADERS: ReadonlyMap<string, string | null> = new Map([
82 [X_TSS_RAW_RESPONSE, 'thrown'],
83])
84β
85// Maximum payload size for GET requests (1MB)
86const MAX_PAYLOAD_SIZE = 1_000_000
87const MAX_PENDING_SERIALIZATION_RECORDS = 1024
88const MAX_PENDING_SERIALIZATION_BYTES = 32 * 1024 * 1024
89const textEncoder = new TextEncoder()
90β
91function encodeSerializationRecord(value: unknown) {
92 return textEncoder.encode(JSON.stringify(value))
93}
94β
95function exceedsPendingSerializationLimit(
96 record: Uint8Array,
97 recordCount: number,
98 pendingBytes: number,
99) {
100 return (
101 recordCount >= MAX_PENDING_SERIALIZATION_RECORDS ||
102 pendingBytes + record.byteLength > MAX_PENDING_SERIALIZATION_BYTES
103 )
104}
105β
106function runSerializationCleanup(dispose: () => void) {
107 try {
108 dispose()
109 } catch {}
110}
111β
112function cancelRawStream(stream: ReadableStream<Uint8Array>, reason?: unknown) {
113 void stream.cancel(reason).catch(() => {})
114}
115β
116/**
117 * Marks a Response thrown during a server-function request so the client
118 * rejects the call with it. Redirects keep their own protocol.
119 */
120export function toThrownServerFnResponse(response: Response): Response {
121 return isRedirect(response)
122 ? response
123 : setProtectedResponseHeaders(response, THROWN_RESPONSE_HEADERS)
124}
125β
126/**
127 * Builds the reply for a server-function request that failed outside the
128 * function, such as in request middleware. Like a failed call, it carries
129 * only the thrown value under an `error` key, so the client rethrows it.
130 */
131export async function createServerFnErrorResponse(
132 error: unknown,
133 serovalPlugins?: Array<SerovalPlugin<any, any>>,
134) {
135 if (isNotFound(error)) {
136 return isNotFoundResponse(error)
137 }
138β
139 // Header getters and reporting hooks can write helpers before the status
140 // is resolved. Error statuses are always body-bearing, as the client needs.
141 const headers = getErrorHeaders(error) ?? new Headers()
142 const { status, statusText } = resolveErrorResponseStatus(error)
143 headers.set('Content-Type', 'application/json')
144 headers.set(X_TSS_SERIALIZED, 'true')
145 headers.delete(X_TSS_RAW_RESPONSE)
146 headers.delete('location')
147β
148 const plugins =
149 serovalPlugins ?? getSerovalPlugins(routerDefaultSerovalPlugins)
150 let serializedError: string
151 try {
152 serializedError = JSON.stringify(
153 await toCrossJSONAsync({ error }, { refs: new Map(), plugins }),
154 )
155 } catch (serializationError) {
156 // Like a result that cannot be serialized, the call rejects with the
157 // serialization error instead of the value it could not send.
158 serializedError = JSON.stringify(
159 await toCrossJSONAsync(
160 { error: serializationError },
161 { refs: new Map(), plugins },
162 ),
163 )
164 }
165 const errorResponse = new Response(serializedError, {
166 status,
167 statusText,
168 headers,
169 })
170 protectResponseHeaders(errorResponse, SERIALIZED_JSON_HEADERS)
171 return errorResponse
172}
173β
174// The action merges the client context with the trusted server context
175// (__executeServer), so the client context is passed through unmerged.
176export const handleServerAction = async ({
177 request,
178 serverFnId,
179}: {
180 request: Request
181 serverFnId: string
182}) => {
183 const methodUpper = request.method.toUpperCase()
184 const action = await getServerFnById(serverFnId, { origin: 'client' })
185β
186 // Early method check: reject mismatched HTTP methods before parsing
187 // the request payload (FormData, JSON, query string, etc.)
188 if (action.method && methodUpper !== action.method) {
189 return new Response(
190 `expected ${action.method} method. Got ${methodUpper}`,
191 {
192 status: 405,
193 headers: {
194 Allow: action.method,
195 },
196 },
197 )
198 }
199β
200 const headers = request.headers
201 const isServerFn = headers.get('x-tsr-serverfn') === 'true'
202 let serovalPlugins: Array<SerovalPlugin<any, any>> | undefined
203 const getRequestSerovalPlugins = () => {
204 return (serovalPlugins ??= getSerovalPlugins(routerDefaultSerovalPlugins))
205 }
206 const contentType = headers.get('content-type')
207β
208 try {
209 let res: any
210 if (
211 contentType &&
212 (contentType.includes('multipart/form-data') ||
213 contentType.includes('application/x-www-form-urlencoded'))
214 ) {
215 // We don't support GET requests with FormData payloads... that seems impossible
216 if (methodUpper === 'GET') {
217 if (process.env.NODE_ENV !== 'production') {
218 throw new Error(
219 'Invariant failed: GET requests with FormData payloads are not supported',
220 )
221 }
222β
223 invariant()
224 }
225 const formData = await request.formData()
226 const serializedContext = formData.get(TSS_FORMDATA_CONTEXT)
227 formData.delete(TSS_FORMDATA_CONTEXT)
228β
229 const params: { context?: unknown; data: FormData; method: string } = {
230 data: formData,
231 method: methodUpper,
232 }
233 if (typeof serializedContext === 'string') {
234 try {
235 const parsedContext = JSON.parse(serializedContext)
236 const deserializedContext = fromJSON(parsedContext, {
237 plugins: getRequestSerovalPlugins(),
238 })
239 if (typeof deserializedContext === 'object' && deserializedContext) {
240 params.context = deserializedContext
241 }
242 } catch (e) {
243 // Log warning for debugging but don't expose to client
244 if (process.env.NODE_ENV === 'development') {
245 console.warn('Failed to parse FormData context:', e)
246 }
247 }
248 }
249β
250 res = await action(params)
251 } else {
252 let json: any
253 if (methodUpper === 'GET') {
254 // Get payload directly from searchParams
255 const payloadParam =
256 getParsedRequestUrl(request).searchParams.get('payload')
257 // Reject oversized payloads to prevent DoS
258 if (payloadParam && payloadParam.length > MAX_PAYLOAD_SIZE) {
259 throw new Error('Payload too large')
260 }
261 json = payloadParam ? JSON.parse(payloadParam) : undefined
262 } else if (contentType?.includes('application/json')) {
263 json = await request.json()
264 }
265 const payload: any =
266 json === undefined
267 ? undefined
268 : fromJSON(json, { plugins: getRequestSerovalPlugins() })
269 // Pass only the fields a client sends, so a crafted `error` or
270 // `result` key cannot decide the outcome of the call.
271 res = await action({
272 data: payload?.data,
273 context: payload?.context,
274 method: methodUpper,
275 })
276 }
277β
278 const failed = 'error' in res
279 const unwrapped = failed ? res.error : res.result
280β
281 if (
282 !isServerFn &&
283 (unwrapped instanceof Response ||
284 unwrapped === null ||
285 typeof unwrapped !== 'object')
286 ) {
287 return unwrapped
288 }
289β
290 if (unwrapped instanceof Response) {
291 if (failed) {
292 return toThrownServerFnResponse(unwrapped)
293 }
294 if (isRedirect(unwrapped)) {
295 return unwrapped
296 }
297 return setProtectedResponseHeaders(unwrapped, RAW_RESPONSE_HEADERS)
298 }
299β
300 return serializeResult(res, request, getRequestSerovalPlugins())
301 } catch (error: any) {
302 if (error instanceof Response) {
303 return error
304 }
305β
306 // Currently this server-side context has no idea how to
307 // build final URLs, so we need to defer that to the client.
308 // The client will check for __redirect and __notFound keys,
309 // and if they exist, it will handle them appropriately.
310β
311 return createServerFnErrorResponse(error, serovalPlugins)
312 }
313}
314β
315/**
316 * Serializes a server-function result. A result that Seroval completes
317 * synchronously without RawStreams becomes plain JSON; everything else is a
318 * framed response whose records and raw streams are multiplexed in order.
319 */
320function serializeResult(
321 res: unknown,
322 request: Request,
323 plugins: Array<SerovalPlugin<any, any>>,
324): Response | DeferredResponse {
325 const initialRecords: Array<Uint8Array> = []
326 let initialBytes = 0
327 const pendingRawStreams: Array<LateStreamRegistration> = []
328β
329 // Seroval replays synchronously discovered work before returning. Collect
330 // that first pass so a complete result can skip framing entirely.
331 let done = false as boolean
332 let initialParsed = false
333 let serializationFailure: [unknown] | undefined
334 let disposeSerialization: (() => void) | undefined
335 let onParse = (value: any, initial: boolean) => {
336 if (serializationFailure) {
337 return
338 }
339 initialParsed ||= initial
340 const record = encodeSerializationRecord(value)
341 if (
342 exceedsPendingSerializationLimit(
343 record,
344 initialRecords.length,
345 initialBytes,
346 )
347 ) {
348 serializationFailure = [
349 new Error(
350 'Server function serialization exceeded its pending output limit',
351 ),
352 ]
353 return
354 }
355 initialRecords.push(record)
356 initialBytes += record.byteLength
357 }
358 let onDone = () => {
359 if (initialParsed) {
360 done = true
361 }
362 }
363 let onError = (error: any) => {
364 serializationFailure ??= [error]
365 }
366 const rawStreamPlugin = createRawStreamRPCPlugin(
367 (id: number, stream: ReadableStream<Uint8Array>) => {
368 if (serializationFailure) {
369 cancelRawStream(stream, serializationFailure[0])
370 return
371 }
372 if (id > MAX_FRAMED_STREAMS) {
373 const error = new Error(
374 `Too many raw streams in framed response (max ${MAX_FRAMED_STREAMS})`,
375 )
376 cancelRawStream(stream, error)
377 onError(error)
378 return
379 }
380 pendingRawStreams.push({ id, stream })
381 },
382 )
383β
384 const dispose = toCrossJSONStream(res, {
385 refs: new Map(),
386 plugins: [rawStreamPlugin, ...plugins],
387 onParse(value, initial) {
388 onParse(value, initial)
389 },
390 onDone() {
391 onDone()
392 },
393 onError: (error) => {
394 onError(error)
395 },
396 })
397 if (serializationFailure) {
398 runSerializationCleanup(dispose)
399 for (const registration of pendingRawStreams) {
400 cancelRawStream(registration.stream, serializationFailure[0])
401 }
402 throw serializationFailure[0]
403 }
404 if (!done) {
405 disposeSerialization = dispose
406 }
407β
408 if (done && pendingRawStreams.length === 0 && initialRecords.length === 1) {
409 return new DeferredResponse(initialRecords[0]!)
410 }
411β
412 if (done && initialRecords.length === 1) {
413 const json = initialRecords[0]!
414 if (json.byteLength > MAX_FRAME_PAYLOAD_SIZE) {
415 const error = new Error(
416 'Server function serialization exceeded its pending output limit',
417 )
418 for (const registration of pendingRawStreams) {
419 cancelRawStream(registration.stream, error)
420 }
421 throw error
422 }
423β
424 // Serialization is complete, so this one bounded record needs no writer
425 // or pending-serialization lifecycle. The mux still controls raw demand.
426 const rawStreams = pendingRawStreams.splice(0)
427 initialRecords.length = 0
428 return createFramedResponse(
429 new ReadableStream<MultiplexedStreamRecord>({
430 start(controller) {
431 controller.enqueue({ json, rawStreams })
432 controller.close()
433 },
434 cancel(reason) {
435 for (const registration of rawStreams) {
436 cancelRawStream(registration.stream, reason)
437 }
438 },
439 }),
440 { signal: request.signal },
441 )
442 }
443β
444 // Couple every JSON patch to the RawStreams it introduces. The mux admits
445 // each JSON reference before it starts that stream's chunks.
446 const { readable, writable } = new TransformStream<MultiplexedStreamRecord>()
447 const writer = writable.getWriter()
448 const recordAbortController = new AbortController()
449 let pendingBytes = 0
450 const pendingRecords = new Set<MultiplexedStreamRecord>()
451β
452 const abortRecordStream = (error: unknown) => {
453 if (serializationFailure) {
454 return
455 }
456 serializationFailure = [error]
457 const disposeCurrentSerialization = disposeSerialization
458 disposeSerialization = undefined
459 for (const registration of pendingRawStreams.splice(0)) {
460 cancelRawStream(registration.stream, error)
461 }
462 for (const record of pendingRecords) {
463 for (const registration of record.rawStreams) {
464 cancelRawStream(registration.stream, error)
465 }
466 }
467 pendingRecords.clear()
468 recordAbortController.abort(error)
469 void writer.abort(error).catch(() => {})
470 if (disposeCurrentSerialization) {
471 runSerializationCleanup(disposeCurrentSerialization)
472 }
473 }
474β
475 const writeRecord = (
476 json: Uint8Array,
477 rawStreams: Array<LateStreamRegistration>,
478 ) => {
479 if (serializationFailure) {
480 for (const registration of rawStreams) {
481 cancelRawStream(registration.stream, serializationFailure[0])
482 }
483 return false
484 }
485β
486 if (
487 json.byteLength > MAX_FRAME_PAYLOAD_SIZE ||
488 exceedsPendingSerializationLimit(json, pendingRecords.size, pendingBytes)
489 ) {
490 const error = new Error(
491 'Server function serialization exceeded its pending output limit',
492 )
493 for (const registration of rawStreams) {
494 cancelRawStream(registration.stream, error)
495 }
496 onError(error)
497 return false
498 }
499β
500 pendingBytes += json.byteLength
501 const record = { json, rawStreams }
502 pendingRecords.add(record)
503 void writer.write(record).then(
504 () => {
505 pendingRecords.delete(record)
506 pendingBytes -= json.byteLength
507 },
508 (error) => {
509 const stillOwned = pendingRecords.delete(record)
510 pendingBytes -= json.byteLength
511 if (stillOwned) {
512 for (const registration of rawStreams) {
513 cancelRawStream(registration.stream, error)
514 }
515 }
516 },
517 )
518 return true
519 }
520β
521 onParse = (value) => {
522 if (serializationFailure) {
523 return
524 }
525 writeRecord(encodeSerializationRecord(value), pendingRawStreams.splice(0))
526 }
527 onDone = () => {
528 if (serializationFailure) {
529 return
530 }
531 disposeSerialization = undefined
532 void writer.close().catch(() => {})
533 }
534 onError = (error) => {
535 abortRecordStream(error)
536 }
537β
538 // Seroval buffers nested patches during its initial traversal. Their
539 // RawStream callbacks may precede the root callback, so start every
540 // synchronously discovered stream only after all initial records.
541 const initialRawStreams = pendingRawStreams.splice(0)
542 for (let index = 0; index < initialRecords.length; index++) {
543 const isLast = index === initialRecords.length - 1
544 if (!writeRecord(initialRecords[index]!, isLast ? initialRawStreams : [])) {
545 // `writeRecord` recorded the failure. Nothing was handed to the client
546 // yet, so fail the whole call.
547 if (!isLast) {
548 for (const registration of initialRawStreams) {
549 cancelRawStream(registration.stream, serializationFailure![0])
550 }
551 }
552 initialRecords.length = 0
553 throw serializationFailure![0]
554 }
555 }
556 initialRecords.length = 0
557 if (done) {
558 onDone()
559 }
560β
561 void writer.closed.catch((error) => {
562 abortRecordStream(error)
563 })
564β
565 return createFramedResponse(readable, {
566 signal: AbortSignal.any([recordAbortController.signal, request.signal]),
567 onCancel: abortRecordStream,
568 })
569}
570β
571function createFramedResponse(
572 records: ReadableStream<MultiplexedStreamRecord>,
573 options: MultiplexedStreamOptions,
574) {
575 const multiplexedStream = createMultiplexedStream(records, options)
576 // Completed JSON reads helper state later, when the pipeline accepts it.
577 const { status, statusText } = getSerializedResponseState()
578 try {
579 const response = new Response(multiplexedStream, {
580 status,
581 statusText,
582 headers: {
583 'Content-Type': TSS_CONTENT_TYPE_FRAMED_VERSIONED,
584 [X_TSS_SERIALIZED]: 'true',
585 },
586 })
587 protectResponseHeaders(response, SERIALIZED_FRAMED_HEADERS)
588 return response
589 } catch (error) {
590 cancelRawStream(multiplexedStream, error)
591 throw error
592 }
593}
594β
595function isNotFoundResponse(error: any) {
596 const { headers, ...rest } = error
597 let responseHeaders: HeadersInit
598 if (headers) {
599 // Snapshot caller headers before serialization can run user callbacks.
600 const copiedHeaders = new Headers(headers)
601 copiedHeaders.set('Content-Type', 'application/json')
602 copiedHeaders.delete(X_TSS_SERIALIZED)
603 copiedHeaders.delete(X_TSS_RAW_RESPONSE)
604 copiedHeaders.delete('location')
605 responseHeaders = copiedHeaders
606 } else {
607 responseHeaders = { 'Content-Type': 'application/json' }
608 }
609β
610 const response = new Response(JSON.stringify(rest), {
611 status: 404,
612 headers: responseHeaders,
613 })
614 protectResponseHeaders(response, NOT_FOUND_HEADERS)
615 return response
616}