@tanstack/start-server-core 1.143.9 → 1.144.0

package/src/frame-protocol.ts

@@ -0,0 +1,216 @@
+/**
+ * Binary frame protocol for multiplexing JSON and raw streams over HTTP.
+ *
+ * Frame format: [type:1][streamId:4][length:4][payload:length]
+ * - type: 1 byte - frame type (JSON, CHUNK, END, ERROR)
+ * - streamId: 4 bytes big-endian uint32 - stream identifier
+ * - length: 4 bytes big-endian uint32 - payload length
+ * - payload: variable length bytes
+ */
+
+// Re-export constants from shared location
+import { FRAME_HEADER_SIZE, FrameType } from '@tanstack/start-client-core'
+
+export {
+  FRAME_HEADER_SIZE,
+  FrameType,
+  TSS_CONTENT_TYPE_FRAMED,
+  TSS_CONTENT_TYPE_FRAMED_VERSIONED,
+  TSS_FRAMED_PROTOCOL_VERSION,
+} from '@tanstack/start-client-core'
+
+/** Cached TextEncoder for frame encoding */
+const textEncoder = new TextEncoder()
+
+/** Shared empty payload for END frames - avoids allocation per call */
+const EMPTY_PAYLOAD = new Uint8Array(0)
+
+/**
+ * Encodes a single frame with header and payload.
+ */
+export function encodeFrame(
+  type: FrameType,
+  streamId: number,
+  payload: Uint8Array,
+): Uint8Array {
+  const frame = new Uint8Array(FRAME_HEADER_SIZE + payload.length)
+  // Write header bytes directly to avoid DataView allocation per frame
+  // Frame format: [type:1][streamId:4 BE][length:4 BE]
+  frame[0] = type
+  frame[1] = (streamId >>> 24) & 0xff
+  frame[2] = (streamId >>> 16) & 0xff
+  frame[3] = (streamId >>> 8) & 0xff
+  frame[4] = streamId & 0xff
+  frame[5] = (payload.length >>> 24) & 0xff
+  frame[6] = (payload.length >>> 16) & 0xff
+  frame[7] = (payload.length >>> 8) & 0xff
+  frame[8] = payload.length & 0xff
+  frame.set(payload, FRAME_HEADER_SIZE)
+  return frame
+}
+
+/**
+ * Encodes a JSON frame (type 0, streamId 0).
+ */
+export function encodeJSONFrame(json: string): Uint8Array {
+  return encodeFrame(FrameType.JSON, 0, textEncoder.encode(json))
+}
+
+/**
+ * Encodes a raw stream chunk frame.
+ */
+export function encodeChunkFrame(
+  streamId: number,
+  chunk: Uint8Array,
+): Uint8Array {
+  return encodeFrame(FrameType.CHUNK, streamId, chunk)
+}
+
+/**
+ * Encodes a raw stream end frame.
+ */
+export function encodeEndFrame(streamId: number): Uint8Array {
+  return encodeFrame(FrameType.END, streamId, EMPTY_PAYLOAD)
+}
+
+/**
+ * Encodes a raw stream error frame.
+ */
+export function encodeErrorFrame(streamId: number, error: unknown): Uint8Array {
+  const message =
+    error instanceof Error ? error.message : String(error ?? 'Unknown error')
+  return encodeFrame(FrameType.ERROR, streamId, textEncoder.encode(message))
+}
+
+/**
+ * Creates a multiplexed ReadableStream from JSON stream and raw streams.
+ *
+ * The JSON stream emits NDJSON lines (from seroval's toCrossJSONStream).
+ * Raw streams are pumped concurrently, interleaved with JSON frames.
+ *
+ * @param jsonStream Stream of JSON strings (each string is one NDJSON line)
+ * @param rawStreams Map of stream IDs to raw binary streams
+ */
+export function createMultiplexedStream(
+  jsonStream: ReadableStream<string>,
+  rawStreams: Map<number, ReadableStream<Uint8Array>>,
+): ReadableStream<Uint8Array> {
+  // Track active pumps for completion
+  let activePumps = 1 + rawStreams.size // 1 for JSON + raw streams
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null
+  let cancelled = false as boolean
+  const cancelReaders: Array<() => void> = []
+
+  const safeEnqueue = (chunk: Uint8Array) => {
+    if (cancelled || !controllerRef) return
+    try {
+      controllerRef.enqueue(chunk)
+    } catch {
+      // Ignore enqueue after close/cancel
+    }
+  }
+
+  const safeError = (err: unknown) => {
+    if (cancelled || !controllerRef) return
+    try {
+      controllerRef.error(err)
+    } catch {
+      // Ignore
+    }
+  }
+
+  const safeClose = () => {
+    if (cancelled || !controllerRef) return
+    try {
+      controllerRef.close()
+    } catch {
+      // Ignore
+    }
+  }
+
+  const checkComplete = () => {
+    activePumps--
+    if (activePumps === 0) {
+      safeClose()
+    }
+  }
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllerRef = controller
+      cancelReaders.length = 0
+
+      // Pump JSON stream (streamId 0)
+      const pumpJSON = async () => {
+        const reader = jsonStream.getReader()
+        cancelReaders.push(() => {
+          // Catch async rejection - reader may already be released
+          reader.cancel().catch(() => {})
+        })
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          while (true) {
+            const { done, value } = await reader.read()
+            // Check cancelled after await - flag may have changed while waiting
+            if (cancelled) break
+            if (done) break
+            safeEnqueue(encodeJSONFrame(value))
+          }
+        } catch (error) {
+          // JSON stream error - fatal, error the whole response
+          safeError(error)
+        } finally {
+          reader.releaseLock()
+          checkComplete()
+        }
+      }
+
+      // Pump a single raw stream with its streamId
+      const pumpRawStream = async (
+        streamId: number,
+        stream: ReadableStream<Uint8Array>,
+      ) => {
+        const reader = stream.getReader()
+        cancelReaders.push(() => {
+          // Catch async rejection - reader may already be released
+          reader.cancel().catch(() => {})
+        })
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          while (true) {
+            const { done, value } = await reader.read()
+            // Check cancelled after await - flag may have changed while waiting
+            if (cancelled) break
+            if (done) {
+              safeEnqueue(encodeEndFrame(streamId))
+              break
+            }
+            safeEnqueue(encodeChunkFrame(streamId, value))
+          }
+        } catch (error) {
+          // Stream error - send ERROR frame (non-fatal, other streams continue)
+          safeEnqueue(encodeErrorFrame(streamId, error))
+        } finally {
+          reader.releaseLock()
+          checkComplete()
+        }
+      }
+
+      // Start all pumps concurrently
+      pumpJSON()
+      for (const [streamId, stream] of rawStreams) {
+        pumpRawStream(streamId, stream)
+      }
+    },
+
+    cancel() {
+      cancelled = true
+      controllerRef = null
+      // Proactively cancel all underlying readers to stop work quickly.
+      for (const cancelReader of cancelReaders) {
+        cancelReader()
+      }
+      cancelReaders.length = 0
+    },
+  })
+}

package/src/server-functions-handler.ts

@@ -1,59 +1,62 @@
-import { isNotFound } from '@tanstack/router-core'
+import {
+  createRawStreamRPCPlugin,
+  isNotFound,
+  isRedirect,
+} from '@tanstack/router-core'
 import invariant from 'tiny-invariant'
 import {
   TSS_FORMDATA_CONTEXT,
   X_TSS_RAW_RESPONSE,
   X_TSS_SERIALIZED,
   getDefaultSerovalPlugins,
+  safeObjectMerge,
 } from '@tanstack/start-client-core'
 import { fromJSON, toCrossJSONAsync, toCrossJSONStream } from 'seroval'
 import { getResponse } from './request-response'
 import { getServerFnById } from './getServerFnById'
+import {
+  TSS_CONTENT_TYPE_FRAMED_VERSIONED,
+  createMultiplexedStream,
+} from './frame-protocol'
 import type { Plugin as SerovalPlugin } from 'seroval'
 
-let regex: RegExp | undefined = undefined
-
 // Cache serovalPlugins at module level to avoid repeated calls
 let serovalPlugins: Array<SerovalPlugin<any, any>> | undefined = undefined
 
+// Cache TextEncoder for NDJSON serialization
+const textEncoder = new TextEncoder()
+
 // Known FormData 'Content-Type' header values - module-level constant
 const FORM_DATA_CONTENT_TYPES = [
   'multipart/form-data',
   'application/x-www-form-urlencoded',
 ]
 
+// Maximum payload size for GET requests (1MB)
+const MAX_PAYLOAD_SIZE = 1_000_000
+
 export const handleServerAction = async ({
   request,
   context,
+  serverFnId,
 }: {
   request: Request
   context: any
+  serverFnId: string
 }) => {
   const controller = new AbortController()
   const signal = controller.signal
   const abort = () => controller.abort()
   request.signal.addEventListener('abort', abort)
 
-  if (regex === undefined) {
-    regex = new RegExp(`${process.env.TSS_SERVER_FN_BASE}([^/?#]+)`)
-  }
-
   const method = request.method
   const methodLower = method.toLowerCase()
-  const url = new URL(request.url, 'http://localhost:3000')
-  // extract the serverFnId from the url as host/_serverFn/:serverFnId
-  // Define a regex to match the path and extract the :thing part
-
-  // Execute the regex
-  const match = url.pathname.match(regex)
-  const serverFnId = match ? match[1] : null
-
-  if (typeof serverFnId !== 'string') {
-    throw new Error('Invalid server action param for serverFnId: ' + serverFnId)
-  }
+  const url = new URL(request.url)
 
   const action = await getServerFnById(serverFnId, { fromClient: true })
 
+  const isServerFn = request.headers.get('x-tsr-serverFn') === 'true'
+
   // Initialize serovalPlugins lazily (cached at module level)
   if (!serovalPlugins) {
     serovalPlugins = getDefaultSerovalPlugins()
@@ -68,7 +71,7 @@ export const handleServerAction = async ({
 
   const response = await (async () => {
     try {
-      const result = await (async () => {
+      let res = await (async () => {
         // FormData
         if (
           FORM_DATA_CONTENT_TYPES.some(
@@ -98,9 +101,17 @@ export const handleServerAction = async ({
                 typeof deserializedContext === 'object' &&
                 deserializedContext
               ) {
-                params.context = { ...context, ...deserializedContext }
+                params.context = safeObjectMerge(
+                  context,
+                  deserializedContext as Record<string, unknown>,
+                )
+              }
+            } catch (e) {
+              // Log warning for debugging but don't expose to client
+              if (process.env.NODE_ENV === 'development') {
+                console.warn('Failed to parse FormData context:', e)
               }
-            } catch {}
+            }
           }
 
           return await action(params, signal)
@@ -110,11 +121,15 @@ export const handleServerAction = async ({
         if (methodLower === 'get') {
           // Get payload directly from searchParams
           const payloadParam = url.searchParams.get('payload')
+          // Reject oversized payloads to prevent DoS
+          if (payloadParam && payloadParam.length > MAX_PAYLOAD_SIZE) {
+            throw new Error('Payload too large')
+          }
           // If there's a payload, we should try to parse it
           const payload: any = payloadParam
             ? parsePayload(JSON.parse(payloadParam))
             : {}
-          payload.context = { ...context, ...payload.context }
+          payload.context = safeObjectMerge(context, payload.context)
           // Send it through!
           return await action(payload, signal)
         }
@@ -129,103 +144,167 @@ export const handleServerAction = async ({
         }
 
         const payload = jsonPayload ? parsePayload(jsonPayload) : {}
-        payload.context = { ...payload.context, ...context }
+        payload.context = safeObjectMerge(payload.context, context)
         return await action(payload, signal)
       })()
 
-      // Any time we get a Response back, we should just
-      // return it immediately.
-      if (result.result instanceof Response) {
-        result.result.headers.set(X_TSS_RAW_RESPONSE, 'true')
-        return result.result
+      const unwrapped = res.result || res.error
+
+      if (isNotFound(res)) {
+        res = isNotFoundResponse(res)
       }
 
-      if (isNotFound(result)) {
-        return isNotFoundResponse(result)
+      if (!isServerFn) {
+        return unwrapped
       }
 
-      const response = getResponse()
-      let nonStreamingBody: any = undefined
-
-      if (result !== undefined) {
-        // first run without the stream in case `result` does not need streaming
-        let done = false as boolean
-        const callbacks: {
-          onParse: (value: any) => void
-          onDone: () => void
-          onError: (error: any) => void
-        } = {
-          onParse: (value) => {
-            nonStreamingBody = value
-          },
-          onDone: () => {
-            done = true
-          },
-          onError: (error) => {
-            throw error
-          },
+      if (unwrapped instanceof Response) {
+        if (isRedirect(unwrapped)) {
+          return unwrapped
         }
-        toCrossJSONStream(result, {
-          refs: new Map(),
-          plugins: serovalPlugins,
-          onParse(value) {
-            callbacks.onParse(value)
-          },
-          onDone() {
-            callbacks.onDone()
-          },
-          onError: (error) => {
-            callbacks.onError(error)
-          },
-        })
-        if (done) {
-          return new Response(
-            nonStreamingBody ? JSON.stringify(nonStreamingBody) : undefined,
-            {
-              status: response.status,
-              statusText: response.statusText,
+        unwrapped.headers.set(X_TSS_RAW_RESPONSE, 'true')
+        return unwrapped
+      }
+
+      return serializeResult(res)
+
+      function serializeResult(res: unknown): Response {
+        let nonStreamingBody: any = undefined
+
+        const alsResponse = getResponse()
+        if (res !== undefined) {
+          // Collect raw streams encountered during serialization
+          const rawStreams = new Map<number, ReadableStream<Uint8Array>>()
+          const rawStreamPlugin = createRawStreamRPCPlugin(
+            (id: number, stream: ReadableStream<Uint8Array>) => {
+              rawStreams.set(id, stream)
+            },
+          )
+
+          // Build plugins with RawStreamRPCPlugin first (before default SSR plugin)
+          const plugins = [rawStreamPlugin, ...(serovalPlugins || [])]
+
+          // first run without the stream in case `result` does not need streaming
+          let done = false as boolean
+          const callbacks: {
+            onParse: (value: any) => void
+            onDone: () => void
+            onError: (error: any) => void
+          } = {
+            onParse: (value) => {
+              nonStreamingBody = value
+            },
+            onDone: () => {
+              done = true
+            },
+            onError: (error) => {
+              throw error
+            },
+          }
+          toCrossJSONStream(res, {
+            refs: new Map(),
+            plugins,
+            onParse(value) {
+              callbacks.onParse(value)
+            },
+            onDone() {
+              callbacks.onDone()
+            },
+            onError: (error) => {
+              callbacks.onError(error)
+            },
+          })
+
+          // If no raw streams and done synchronously, return simple JSON
+          if (done && rawStreams.size === 0) {
+            return new Response(
+              nonStreamingBody ? JSON.stringify(nonStreamingBody) : undefined,
+              {
+                status: alsResponse.status,
+                statusText: alsResponse.statusText,
+                headers: {
+                  'Content-Type': 'application/json',
+                  [X_TSS_SERIALIZED]: 'true',
+                },
+              },
+            )
+          }
+
+          // If we have raw streams, use framed protocol
+          if (rawStreams.size > 0) {
+            // Create a stream of JSON chunks (NDJSON style)
+            const jsonStream = new ReadableStream<string>({
+              start(controller) {
+                callbacks.onParse = (value) => {
+                  controller.enqueue(JSON.stringify(value) + '\n')
+                }
+                callbacks.onDone = () => {
+                  try {
+                    controller.close()
+                  } catch {
+                    // Already closed
+                  }
+                }
+                callbacks.onError = (error) => controller.error(error)
+                // Emit initial body if we have one
+                if (nonStreamingBody !== undefined) {
+                  callbacks.onParse(nonStreamingBody)
+                }
+              },
+            })
+
+            // Create multiplexed stream with JSON and raw streams
+            const multiplexedStream = createMultiplexedStream(
+              jsonStream,
+              rawStreams,
+            )
+
+            return new Response(multiplexedStream, {
+              status: alsResponse.status,
+              statusText: alsResponse.statusText,
               headers: {
-                'Content-Type': 'application/json',
+                'Content-Type': TSS_CONTENT_TYPE_FRAMED_VERSIONED,
                 [X_TSS_SERIALIZED]: 'true',
               },
+            })
+          }
+
+          // No raw streams but not done yet - use standard NDJSON streaming
+          const stream = new ReadableStream({
+            start(controller) {
+              callbacks.onParse = (value) =>
+                controller.enqueue(
+                  textEncoder.encode(JSON.stringify(value) + '\n'),
+                )
+              callbacks.onDone = () => {
+                try {
+                  controller.close()
+                } catch (error) {
+                  controller.error(error)
+                }
+              }
+              callbacks.onError = (error) => controller.error(error)
+              // stream initial body
+              if (nonStreamingBody !== undefined) {
+                callbacks.onParse(nonStreamingBody)
+              }
             },
-          )
+          })
+          return new Response(stream, {
+            status: alsResponse.status,
+            statusText: alsResponse.statusText,
+            headers: {
+              'Content-Type': 'application/x-ndjson',
+              [X_TSS_SERIALIZED]: 'true',
+            },
+          })
         }
 
-        // not done yet, we need to stream
-        const encoder = new TextEncoder()
-        const stream = new ReadableStream({
-          start(controller) {
-            callbacks.onParse = (value) =>
-              controller.enqueue(encoder.encode(JSON.stringify(value) + '\n'))
-            callbacks.onDone = () => {
-              try {
-                controller.close()
-              } catch (error) {
-                controller.error(error)
-              }
-            }
-            callbacks.onError = (error) => controller.error(error)
-            // stream the initial body
-            if (nonStreamingBody !== undefined) {
-              callbacks.onParse(nonStreamingBody)
-            }
-          },
-        })
-        return new Response(stream, {
-          status: response.status,
-          statusText: response.statusText,
-          headers: {
-            'Content-Type': 'application/x-ndjson',
-            [X_TSS_SERIALIZED]: 'true',
-          },
+        return new Response(undefined, {
+          status: alsResponse.status,
+          statusText: alsResponse.statusText,
         })
       }
-
-      return new Response(undefined, {
-        status: response.status,
-        statusText: response.statusText,
-      })
     } catch (error: any) {
       if (error instanceof Response) {
         return error