@tanstack/start-client-core 1.143.9 → 1.144.0

package/src/client-rpc/frame-decoder.ts

@@ -0,0 +1,389 @@
+/**
+ * Client-side frame decoder for multiplexed responses.
+ *
+ * Decodes binary frame protocol and reconstructs:
+ * - JSON stream (NDJSON lines for seroval)
+ * - Raw streams (binary data as ReadableStream<Uint8Array>)
+ */
+
+import { FRAME_HEADER_SIZE, FrameType } from '../constants'
+
+/** Cached TextDecoder for frame decoding */
+const textDecoder = new TextDecoder()
+
+/** Shared empty buffer for empty buffer case - avoids allocation */
+const EMPTY_BUFFER = new Uint8Array(0)
+
+/** Hardening limits to prevent memory/CPU DoS */
+const MAX_FRAME_PAYLOAD_SIZE = 16 * 1024 * 1024 // 16MiB
+const MAX_BUFFERED_BYTES = 32 * 1024 * 1024 // 32MiB
+const MAX_STREAMS = 1024
+const MAX_FRAMES = 100_000 // Limit total frames to prevent CPU DoS
+
+/**
+ * Result of frame decoding.
+ */
+export interface FrameDecoderResult {
+  /** Gets or creates a raw stream by ID (for use by deserialize plugin) */
+  getOrCreateStream: (id: number) => ReadableStream<Uint8Array>
+  /** Stream of JSON strings (NDJSON lines) */
+  jsonChunks: ReadableStream<string>
+}
+
+/**
+ * Creates a frame decoder that processes a multiplexed response stream.
+ *
+ * @param input The raw response body stream
+ * @returns Decoded JSON stream and stream getter function
+ */
+export function createFrameDecoder(
+  input: ReadableStream<Uint8Array>,
+): FrameDecoderResult {
+  const streamControllers = new Map<
+    number,
+    ReadableStreamDefaultController<Uint8Array>
+  >()
+  const streams = new Map<number, ReadableStream<Uint8Array>>()
+  const cancelledStreamIds = new Set<number>()
+
+  let cancelled = false as boolean
+  let inputReader: ReadableStreamReader<Uint8Array> | null = null
+  let frameCount = 0
+
+  let jsonController!: ReadableStreamDefaultController<string>
+  const jsonChunks = new ReadableStream<string>({
+    start(controller) {
+      jsonController = controller
+    },
+    cancel() {
+      cancelled = true
+      try {
+        inputReader?.cancel()
+      } catch {
+        // Ignore
+      }
+
+      streamControllers.forEach((ctrl) => {
+        try {
+          ctrl.error(new Error('Framed response cancelled'))
+        } catch {
+          // Ignore
+        }
+      })
+      streamControllers.clear()
+      streams.clear()
+      cancelledStreamIds.clear()
+    },
+  })
+
+  /**
+   * Gets or creates a stream for a given stream ID.
+   * Called by deserialize plugin when it encounters a RawStream reference.
+   */
+  function getOrCreateStream(id: number): ReadableStream<Uint8Array> {
+    const existing = streams.get(id)
+    if (existing) {
+      return existing
+    }
+
+    // If we already received an END/ERROR for this streamId, returning a fresh stream
+    // would hang consumers. Return an already-closed stream instead.
+    if (cancelledStreamIds.has(id)) {
+      return new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.close()
+        },
+      })
+    }
+
+    if (streams.size >= MAX_STREAMS) {
+      throw new Error(
+        `Too many raw streams in framed response (max ${MAX_STREAMS})`,
+      )
+    }
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(ctrl) {
+        streamControllers.set(id, ctrl)
+      },
+      cancel() {
+        cancelledStreamIds.add(id)
+        streamControllers.delete(id)
+        streams.delete(id)
+      },
+    })
+    streams.set(id, stream)
+    return stream
+  }
+
+  /**
+   * Ensures stream exists and returns its controller for enqueuing data.
+   * Used for CHUNK frames where we need to ensure stream is created.
+   */
+  function ensureController(
+    id: number,
+  ): ReadableStreamDefaultController<Uint8Array> | undefined {
+    getOrCreateStream(id)
+    return streamControllers.get(id)
+  }
+
+  // Process frames asynchronously
+  ;(async () => {
+    const reader = input.getReader()
+    inputReader = reader
+
+    const bufferList: Array<Uint8Array> = []
+    let totalLength = 0
+
+    /**
+     * Reads header bytes from buffer chunks without flattening.
+     * Returns header data or null if not enough bytes available.
+     */
+    function readHeader(): {
+      type: number
+      streamId: number
+      length: number
+    } | null {
+      if (totalLength < FRAME_HEADER_SIZE) return null
+
+      const first = bufferList[0]!
+
+      // Fast path: header fits entirely in first chunk (common case)
+      if (first.length >= FRAME_HEADER_SIZE) {
+        const type = first[0]!
+        const streamId =
+          ((first[1]! << 24) |
+            (first[2]! << 16) |
+            (first[3]! << 8) |
+            first[4]!) >>>
+          0
+        const length =
+          ((first[5]! << 24) |
+            (first[6]! << 16) |
+            (first[7]! << 8) |
+            first[8]!) >>>
+          0
+        return { type, streamId, length }
+      }
+
+      // Slow path: header spans multiple chunks - flatten header bytes only
+      const headerBytes = new Uint8Array(FRAME_HEADER_SIZE)
+      let offset = 0
+      let remaining = FRAME_HEADER_SIZE
+      for (let i = 0; i < bufferList.length && remaining > 0; i++) {
+        const chunk = bufferList[i]!
+        const toCopy = Math.min(chunk.length, remaining)
+        headerBytes.set(chunk.subarray(0, toCopy), offset)
+        offset += toCopy
+        remaining -= toCopy
+      }
+
+      const type = headerBytes[0]!
+      const streamId =
+        ((headerBytes[1]! << 24) |
+          (headerBytes[2]! << 16) |
+          (headerBytes[3]! << 8) |
+          headerBytes[4]!) >>>
+        0
+      const length =
+        ((headerBytes[5]! << 24) |
+          (headerBytes[6]! << 16) |
+          (headerBytes[7]! << 8) |
+          headerBytes[8]!) >>>
+        0
+
+      return { type, streamId, length }
+    }
+
+    /**
+     * Flattens buffer list into single Uint8Array and removes from list.
+     */
+    function extractFlattened(count: number): Uint8Array {
+      if (count === 0) return EMPTY_BUFFER
+
+      const result = new Uint8Array(count)
+      let offset = 0
+      let remaining = count
+
+      while (remaining > 0 && bufferList.length > 0) {
+        const chunk = bufferList[0]
+        if (!chunk) break
+        const toCopy = Math.min(chunk.length, remaining)
+        result.set(chunk.subarray(0, toCopy), offset)
+
+        offset += toCopy
+        remaining -= toCopy
+
+        if (toCopy === chunk.length) {
+          bufferList.shift()
+        } else {
+          bufferList[0] = chunk.subarray(toCopy)
+        }
+      }
+
+      totalLength -= count
+      return result
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      while (true) {
+        const { done, value } = await reader.read()
+        if (cancelled) break
+        if (done) break
+
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!value) continue
+
+        // Append incoming chunk to buffer list
+        if (totalLength + value.length > MAX_BUFFERED_BYTES) {
+          throw new Error(
+            `Framed response buffer exceeded ${MAX_BUFFERED_BYTES} bytes`,
+          )
+        }
+        bufferList.push(value)
+        totalLength += value.length
+
+        // Parse complete frames from buffer
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (true) {
+          const header = readHeader()
+          if (!header) break // Not enough bytes for header
+
+          const { type, streamId, length } = header
+
+          if (
+            type !== FrameType.JSON &&
+            type !== FrameType.CHUNK &&
+            type !== FrameType.END &&
+            type !== FrameType.ERROR
+          ) {
+            throw new Error(`Unknown frame type: ${type}`)
+          }
+
+          // Enforce stream id conventions: JSON uses streamId 0, raw streams use non-zero ids
+          if (type === FrameType.JSON) {
+            if (streamId !== 0) {
+              throw new Error('Invalid JSON frame streamId (expected 0)')
+            }
+          } else {
+            if (streamId === 0) {
+              throw new Error('Invalid raw frame streamId (expected non-zero)')
+            }
+          }
+
+          if (length > MAX_FRAME_PAYLOAD_SIZE) {
+            throw new Error(
+              `Frame payload too large: ${length} bytes (max ${MAX_FRAME_PAYLOAD_SIZE})`,
+            )
+          }
+
+          const frameSize = FRAME_HEADER_SIZE + length
+          if (totalLength < frameSize) break // Wait for more data
+
+          if (++frameCount > MAX_FRAMES) {
+            throw new Error(
+              `Too many frames in framed response (max ${MAX_FRAMES})`,
+            )
+          }
+
+          // Extract and consume header bytes
+          extractFlattened(FRAME_HEADER_SIZE)
+
+          // Extract payload
+          const payload = extractFlattened(length)
+
+          // Process frame by type
+          switch (type) {
+            case FrameType.JSON: {
+              try {
+                jsonController.enqueue(textDecoder.decode(payload))
+              } catch {
+                // JSON stream may be cancelled/closed
+              }
+              break
+            }
+
+            case FrameType.CHUNK: {
+              const ctrl = ensureController(streamId)
+              if (ctrl) {
+                ctrl.enqueue(payload)
+              }
+              break
+            }
+
+            case FrameType.END: {
+              const ctrl = ensureController(streamId)
+              cancelledStreamIds.add(streamId)
+              if (ctrl) {
+                try {
+                  ctrl.close()
+                } catch {
+                  // Already closed
+                }
+                streamControllers.delete(streamId)
+              }
+              break
+            }
+
+            case FrameType.ERROR: {
+              const ctrl = ensureController(streamId)
+              cancelledStreamIds.add(streamId)
+              if (ctrl) {
+                const message = textDecoder.decode(payload)
+                ctrl.error(new Error(message))
+                streamControllers.delete(streamId)
+              }
+              break
+            }
+          }
+        }
+      }
+
+      if (totalLength !== 0) {
+        throw new Error('Incomplete frame at end of framed response')
+      }
+
+      // Close JSON stream when done
+      try {
+        jsonController.close()
+      } catch {
+        // JSON stream may be cancelled/closed
+      }
+
+      // Close any remaining streams (shouldn't happen in normal operation)
+      streamControllers.forEach((ctrl) => {
+        try {
+          ctrl.close()
+        } catch {
+          // Already closed
+        }
+      })
+      streamControllers.clear()
+    } catch (error) {
+      // Error reading - propagate to all streams
+      try {
+        jsonController.error(error)
+      } catch {
+        // Already errored/closed
+      }
+      streamControllers.forEach((ctrl) => {
+        try {
+          ctrl.error(error)
+        } catch {
+          // Already errored/closed
+        }
+      })
+      streamControllers.clear()
+    } finally {
+      try {
+        reader.releaseLock()
+      } catch {
+        // Ignore
+      }
+      inputReader = null
+    }
+  })()
+
+  return { getOrCreateStream, jsonChunks }
+}

package/src/client-rpc/serverFnFetcher.ts

@@ -1,12 +1,20 @@
-import { encode, isNotFound, parseRedirect } from '@tanstack/router-core'
+import {
+  createRawStreamDeserializePlugin,
+  encode,
+  isNotFound,
+  parseRedirect,
+} from '@tanstack/router-core'
 import { fromCrossJSON, toJSONAsync } from 'seroval'
 import invariant from 'tiny-invariant'
 import { getDefaultSerovalPlugins } from '../getDefaultSerovalPlugins'
 import {
+  TSS_CONTENT_TYPE_FRAMED,
   TSS_FORMDATA_CONTEXT,
   X_TSS_RAW_RESPONSE,
   X_TSS_SERIALIZED,
+  validateFramedProtocolVersion,
 } from '../constants'
+import { createFrameDecoder } from './frame-decoder'
 import type { FunctionMiddlewareClientFnOptions } from '../createMiddleware'
 import type { Plugin as SerovalPlugin } from 'seroval'
 
@@ -25,6 +33,15 @@ function hasOwnProperties(obj: object): boolean {
   }
   return false
 }
+// caller =>
+//   serverFnFetcher =>
+//     client =>
+//       server =>
+//         fn =>
+//       seroval =>
+//     client middleware =>
+//   serverFnFetcher =>
+// caller
 
 export async function serverFnFetcher(
   url: string,
@@ -43,10 +60,13 @@ export async function serverFnFetcher(
 
   // Arrange the headers
   const headers = first.headers ? new Headers(first.headers) : new Headers()
-  headers.set('x-tsr-redirect', 'manual')
+  headers.set('x-tsr-serverFn', 'true')
 
   if (type === 'payload') {
-    headers.set('accept', 'application/x-ndjson, application/json')
+    headers.set(
+      'accept',
+      `${TSS_CONTENT_TYPE_FRAMED}, application/x-ndjson, application/json`,
+    )
   }
 
   // If the method is GET, we need to move the payload to the query string
@@ -146,7 +166,7 @@ async function getFetchBody(
 async function getResponse(fn: () => Promise<Response>) {
   let response: Response
   try {
-    response = await fn()
+    response = await fn() // client => server => fn => server => client
   } catch (error) {
     if (error instanceof Response) {
       response = error
@@ -159,23 +179,45 @@ async function getResponse(fn: () => Promise<Response>) {
   if (response.headers.get(X_TSS_RAW_RESPONSE) === 'true') {
     return response
   }
+
   const contentType = response.headers.get('content-type')
   invariant(contentType, 'expected content-type header to be set')
   const serializedByStart = !!response.headers.get(X_TSS_SERIALIZED)
-  // If the response is not ok, throw an error
-  if (!response.ok) {
-    if (serializedByStart && contentType.includes('application/json')) {
-      const jsonPayload = await response.json()
-      const result = fromCrossJSON(jsonPayload, { plugins: serovalPlugins! })
-      throw result
-    }
-
-    throw new Error(await response.text())
-  }
 
+  // If the response is serialized by the start server, we need to process it
+  // differently than a normal response.
   if (serializedByStart) {
     let result
-    if (contentType.includes('application/x-ndjson')) {
+
+    // If it's a framed response (contains RawStream), use frame decoder
+    if (contentType.includes(TSS_CONTENT_TYPE_FRAMED)) {
+      // Validate protocol version compatibility
+      validateFramedProtocolVersion(contentType)
+
+      if (!response.body) {
+        throw new Error('No response body for framed response')
+      }
+
+      const { getOrCreateStream, jsonChunks } = createFrameDecoder(
+        response.body,
+      )
+
+      // Create deserialize plugin that wires up the raw streams
+      const rawStreamPlugin =
+        createRawStreamDeserializePlugin(getOrCreateStream)
+      const plugins = [rawStreamPlugin, ...(serovalPlugins || [])]
+
+      const refs = new Map()
+      result = await processFramedResponse({
+        jsonStream: jsonChunks,
+        onMessage: (msg: any) => fromCrossJSON(msg, { refs, plugins }),
+        onError(msg, error) {
+          console.error(msg, error)
+        },
+      })
+    }
+    // If it's a stream from the start serializer, process it as such
+    else if (contentType.includes('application/x-ndjson')) {
       const refs = new Map()
       result = await processServerFnResponse({
         response,
@@ -187,17 +229,22 @@ async function getResponse(fn: () => Promise<Response>) {
         },
       })
     }
-    if (contentType.includes('application/json')) {
+    // If it's a JSON response, it can be simpler
+    else if (contentType.includes('application/json')) {
       const jsonPayload = await response.json()
       result = fromCrossJSON(jsonPayload, { plugins: serovalPlugins! })
     }
+
     invariant(result, 'expected result to be resolved')
     if (result instanceof Error) {
       throw result
     }
+
     return result
   }
 
+  // If it wasn't processed by the start serializer, check
+  // if it's JSON
   if (contentType.includes('application/json')) {
     const jsonPayload = await response.json()
     const redirect = parseRedirect(jsonPayload)
@@ -210,6 +257,12 @@ async function getResponse(fn: () => Promise<Response>) {
     return jsonPayload
   }
 
+  // Otherwise, if it's not OK, throw the content
+  if (!response.ok) {
+    throw new Error(await response.text())
+  }
+
+  // Or return the response itself
   return response
 }
 
@@ -296,3 +349,50 @@ async function processServerFnResponse({
 
   return onMessage(firstObject)
 }
+
+/**
+ * Processes a framed response where each JSON chunk is a complete JSON string
+ * (already decoded by frame decoder).
+ */
+async function processFramedResponse({
+  jsonStream,
+  onMessage,
+  onError,
+}: {
+  jsonStream: ReadableStream<string>
+  onMessage: (msg: any) => any
+  onError?: (msg: string, error?: any) => void
+}) {
+  const reader = jsonStream.getReader()
+
+  // Read first JSON frame - this is the main result
+  const { value: firstValue, done: firstDone } = await reader.read()
+  if (firstDone || !firstValue) {
+    throw new Error('Stream ended before first object')
+  }
+
+  // Each frame is a complete JSON string
+  const firstObject = JSON.parse(firstValue)
+
+  // Process remaining frames asynchronously (for streaming refs like RawStream)
+  ;(async () => {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+        if (value) {
+          try {
+            onMessage(JSON.parse(value))
+          } catch (e) {
+            onError?.(`Invalid JSON: ${value}`, e)
+          }
+        }
+      }
+    } catch (err) {
+      onError?.('Stream processing error:', err)
+    }
+  })()
+
+  return onMessage(firstObject)
+}

package/src/constants.ts

@@ -6,4 +6,64 @@ export const TSS_SERVER_FUNCTION_FACTORY = Symbol.for(
 
 export const X_TSS_SERIALIZED = 'x-tss-serialized'
 export const X_TSS_RAW_RESPONSE = 'x-tss-raw'
+export const X_TSS_CONTEXT = 'x-tss-context'
+
+/** Content-Type for multiplexed framed responses (RawStream support) */
+export const TSS_CONTENT_TYPE_FRAMED = 'application/x-tss-framed'
+
+/**
+ * Frame types for binary multiplexing protocol.
+ */
+export const FrameType = {
+  /** Seroval JSON chunk (NDJSON line) */
+  JSON: 0,
+  /** Raw stream data chunk */
+  CHUNK: 1,
+  /** Raw stream end (EOF) */
+  END: 2,
+  /** Raw stream error */
+  ERROR: 3,
+} as const
+
+export type FrameType = (typeof FrameType)[keyof typeof FrameType]
+
+/** Header size in bytes: type(1) + streamId(4) + length(4) */
+export const FRAME_HEADER_SIZE = 9
+
+/** Current protocol version for framed responses */
+export const TSS_FRAMED_PROTOCOL_VERSION = 1
+
+/** Full Content-Type header value with version parameter */
+export const TSS_CONTENT_TYPE_FRAMED_VERSIONED = `${TSS_CONTENT_TYPE_FRAMED}; v=${TSS_FRAMED_PROTOCOL_VERSION}`
+
+/**
+ * Parses the version parameter from a framed Content-Type header.
+ * Returns undefined if no version parameter is present.
+ */
+const FRAMED_VERSION_REGEX = /;\s*v=(\d+)/
+export function parseFramedProtocolVersion(
+  contentType: string,
+): number | undefined {
+  // Match "v=<number>" in the content-type parameters
+  const match = contentType.match(FRAMED_VERSION_REGEX)
+  return match ? parseInt(match[1]!, 10) : undefined
+}
+
+/**
+ * Validates that the server's protocol version is compatible with this client.
+ * Throws an error if versions are incompatible.
+ */
+export function validateFramedProtocolVersion(contentType: string): void {
+  const serverVersion = parseFramedProtocolVersion(contentType)
+  if (serverVersion === undefined) {
+    // No version specified - assume compatible (backwards compat)
+    return
+  }
+  if (serverVersion !== TSS_FRAMED_PROTOCOL_VERSION) {
+    throw new Error(
+      `Incompatible framed protocol version: server=${serverVersion}, client=${TSS_FRAMED_PROTOCOL_VERSION}. ` +
+        `Please ensure client and server are using compatible versions.`,
+    )
+  }
+}
 export {}