@tanstack/start-server-core 1.167.10 → 1.167.12

package/src/frame-protocol.ts

@@ -82,135 +82,177 @@ export function encodeErrorFrame(streamId: number, error: unknown): Uint8Array {
   return encodeFrame(FrameType.ERROR, streamId, textEncoder.encode(message))
 }
 
+/**
+ * Late stream registration for RawStreams discovered after serialization starts.
+ * Used when Promise<RawStream> resolves after the initial synchronous pass.
+ */
+export interface LateStreamRegistration {
+  id: number
+  stream: ReadableStream<Uint8Array>
+}
+
 /**
  * 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.
  *
+ * Supports late stream registration for RawStreams discovered after initial
+ * serialization (e.g., from resolved Promises).
+ *
  * @param jsonStream Stream of JSON strings (each string is one NDJSON line)
- * @param rawStreams Map of stream IDs to raw binary streams
+ * @param rawStreams Map of stream IDs to raw binary streams (known at start)
+ * @param lateStreamSource Optional stream of late registrations for streams discovered later
  */
 export function createMultiplexedStream(
   jsonStream: ReadableStream<string>,
   rawStreams: Map<number, ReadableStream<Uint8Array>>,
+  lateStreamSource?: ReadableStream<LateStreamRegistration>,
 ): 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
+  // Shared state for the multiplexed stream
+  let controller: ReadableStreamDefaultController<Uint8Array>
+  let cancelled = false
+  const readers: Array<ReadableStreamDefaultReader<any>> = []
+
+  // Helper to enqueue a frame, ignoring errors if stream is closed/cancelled
+  const enqueue = (frame: Uint8Array): boolean => {
+    if (cancelled) return false
     try {
-      controllerRef.enqueue(chunk)
+      controller.enqueue(frame)
+      return true
     } catch {
-      // Ignore enqueue after close/cancel
+      return false
     }
   }
 
-  const safeError = (err: unknown) => {
-    if (cancelled || !controllerRef) return
+  // Helper to error the output stream (for fatal errors like JSON stream failure)
+  const errorOutput = (error: unknown): void => {
+    if (cancelled) return
+    cancelled = true
     try {
-      controllerRef.error(err)
+      controller.error(error)
     } catch {
-      // Ignore
+      // Already errored
+    }
+    // Cancel all readers to stop other pumps
+    for (const reader of readers) {
+      reader.cancel().catch(() => {})
     }
   }
 
-  const safeClose = () => {
-    if (cancelled || !controllerRef) return
+  // Pumps a raw stream, sending CHUNK frames and END/ERROR on completion
+  async function pumpRawStream(
+    streamId: number,
+    stream: ReadableStream<Uint8Array>,
+  ): Promise<void> {
+    const reader = stream.getReader()
+    readers.push(reader)
     try {
-      controllerRef.close()
-    } catch {
-      // Ignore
+      while (!cancelled) {
+        const { done, value } = await reader.read()
+        if (done) {
+          enqueue(encodeEndFrame(streamId))
+          return
+        }
+        if (!enqueue(encodeChunkFrame(streamId, value))) return
+      }
+    } catch (error) {
+      // Raw stream error - send ERROR frame, don't fail entire response
+      enqueue(encodeErrorFrame(streamId, error))
+    } finally {
+      reader.releaseLock()
     }
   }
 
-  const checkComplete = () => {
-    activePumps--
-    if (activePumps === 0) {
-      safeClose()
+  // Pumps the JSON stream, sending JSON frames
+  // JSON stream errors are fatal - they error the entire output
+  async function pumpJSON(): Promise<void> {
+    const reader = jsonStream.getReader()
+    readers.push(reader)
+    try {
+      while (!cancelled) {
+        const { done, value } = await reader.read()
+        if (done) return
+        if (!enqueue(encodeJSONFrame(value))) return
+      }
+    } catch (error) {
+      // JSON stream error is fatal - error the entire output
+      errorOutput(error)
+      throw error // Re-throw to signal failure to Promise.all
+    } finally {
+      reader.releaseLock()
     }
   }
 
+  // Pumps late stream registrations, spawning raw stream pumps as they arrive
+  async function pumpLateStreams(): Promise<Array<Promise<void>>> {
+    if (!lateStreamSource) return []
+
+    const lateStreamPumps: Array<Promise<void>> = []
+    const reader = lateStreamSource.getReader()
+    readers.push(reader)
+    try {
+      while (!cancelled) {
+        const { done, value } = await reader.read()
+        if (done) break
+        // Start pumping this late stream and track it
+        lateStreamPumps.push(pumpRawStream(value.id, value.stream))
+      }
+    } finally {
+      reader.releaseLock()
+    }
+    return lateStreamPumps
+  }
+
   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()
-        }
+    async start(ctrl) {
+      controller = ctrl
+
+      // Collect all pump promises
+      const pumps: Array<Promise<void | Array<Promise<void>>>> = [pumpJSON()]
+
+      for (const [streamId, stream] of rawStreams) {
+        pumps.push(pumpRawStream(streamId, stream))
       }
 
-      // 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()
-        }
+      // Add late stream pump (returns array of spawned pump promises)
+      if (lateStreamSource) {
+        pumps.push(pumpLateStreams())
       }
 
-      // Start all pumps concurrently
-      pumpJSON()
-      for (const [streamId, stream] of rawStreams) {
-        pumpRawStream(streamId, stream)
+      try {
+        // Wait for initial pumps to complete
+        const results = await Promise.all(pumps)
+
+        // Wait for any late stream pumps that were spawned
+        const latePumps = results.find(Array.isArray) as
+          | Array<Promise<void>>
+          | undefined
+        if (latePumps && latePumps.length > 0) {
+          await Promise.all(latePumps)
+        }
+
+        // All pumps done - close the output stream
+        if (!cancelled) {
+          try {
+            controller.close()
+          } catch {
+            // Already closed
+          }
+        }
+      } catch {
+        // Error already handled by errorOutput in pumpJSON
+        // or was a raw stream error (non-fatal, already sent ERROR frame)
       }
     },
 
     cancel() {
       cancelled = true
-      controllerRef = null
-      // Proactively cancel all underlying readers to stop work quickly.
-      for (const cancelReader of cancelReaders) {
-        cancelReader()
+      // Cancel all readers to stop pumps quickly
+      for (const reader of readers) {
+        reader.cancel().catch(() => {})
       }
-      cancelReaders.length = 0
+      readers.length = 0
     },
   })
 }

package/src/serializer/ServerFunctionSerializationAdapter.ts

@@ -17,7 +17,7 @@ export const ServerFunctionSerializationAdapter = createSerializationAdapter({
       // When a function ID is received through serialization (e.g., as a parameter
       // to another server function), it originates from the client and must be
       // validated the same way as direct HTTP calls to server functions.
-      const serverFn = await getServerFnById(functionId, { fromClient: true })
+      const serverFn = await getServerFnById(functionId, { origin: 'client' })
       const result = await serverFn(opts ?? {}, signal)
       return result.result
     }

package/src/server-functions-handler.ts

@@ -18,14 +18,12 @@ import {
   TSS_CONTENT_TYPE_FRAMED_VERSIONED,
   createMultiplexedStream,
 } from './frame-protocol'
+import type { LateStreamRegistration } from './frame-protocol'
 import type { Plugin as SerovalPlugin } from 'seroval'
 
 // 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',
@@ -48,7 +46,7 @@ export const handleServerAction = async ({
   const methodUpper = method.toUpperCase()
   const url = new URL(request.url)
 
-  const action = await getServerFnById(serverFnId, { fromClient: true })
+  const action = await getServerFnById(serverFnId, { origin: 'client' })
 
   // Early method check: reject mismatched HTTP methods before parsing
   // the request payload (FormData, JSON, query string, etc.)
@@ -186,11 +184,40 @@ export const handleServerAction = async ({
 
         const alsResponse = getResponse()
         if (res !== undefined) {
-          // Collect raw streams encountered during serialization
+          // Collect raw streams encountered during initial synchronous serialization
           const rawStreams = new Map<number, ReadableStream<Uint8Array>>()
+
+          // Track whether we're still in the initial synchronous phase
+          // After initial phase, new RawStreams go to lateStreamWriter
+          let initialPhase = true
+
+          // Late stream registration for RawStreams discovered after initial pass
+          // (e.g., from resolved Promises)
+          let lateStreamWriter:
+            | WritableStreamDefaultWriter<LateStreamRegistration>
+            | undefined
+          let lateStreamReadable:
+            | ReadableStream<LateStreamRegistration>
+            | undefined = undefined
+          const pendingLateStreams: Array<LateStreamRegistration> = []
+
           const rawStreamPlugin = createRawStreamRPCPlugin(
             (id: number, stream: ReadableStream<Uint8Array>) => {
-              rawStreams.set(id, stream)
+              if (initialPhase) {
+                rawStreams.set(id, stream)
+                return
+              }
+
+              if (lateStreamWriter) {
+                // Late stream - write to the late stream channel
+                lateStreamWriter.write({ id, stream }).catch(() => {
+                  // Ignore write errors - stream may be closed
+                })
+                return
+              }
+
+              // Discovered after initial phase but before writer exists.
+              pendingLateStreams.push({ id, stream })
             },
           )
 
@@ -228,6 +255,13 @@ export const handleServerAction = async ({
             },
           })
 
+          // End of initial synchronous phase - any new RawStreams are "late"
+          initialPhase = false
+
+          // If any RawStreams are discovered after this point but before the
+          // late-stream writer exists, we buffer them and flush once the writer
+          // is ready. This avoids an occasional missed-stream race.
+
           // If no raw streams and done synchronously, return simple JSON
           if (done && rawStreams.size === 0) {
             return new Response(
@@ -243,71 +277,87 @@ export const handleServerAction = async ({
             )
           }
 
-          // 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': TSS_CONTENT_TYPE_FRAMED_VERSIONED,
-                [X_TSS_SERIALIZED]: 'true',
-              },
+          // Not done synchronously or has raw streams - use framed protocol
+          // This supports late RawStreams from resolved Promises
+          const { readable, writable } =
+            new TransformStream<LateStreamRegistration>()
+          lateStreamReadable = readable
+          lateStreamWriter = writable.getWriter()
+
+          // Flush any late streams that were discovered in the small window
+          // between end of initial serialization and writer setup.
+          for (const registration of pendingLateStreams) {
+            lateStreamWriter.write(registration).catch(() => {
+              // Ignore write errors - stream may be closed
             })
           }
+          pendingLateStreams.length = 0
 
-          // No raw streams but not done yet - use standard NDJSON streaming
-          const stream = new ReadableStream({
+          // Create a stream of JSON chunks
+          const jsonStream = new ReadableStream<string>({
             start(controller) {
-              callbacks.onParse = (value) =>
-                controller.enqueue(
-                  textEncoder.encode(JSON.stringify(value) + '\n'),
-                )
+              callbacks.onParse = (value) => {
+                controller.enqueue(JSON.stringify(value) + '\n')
+              }
               callbacks.onDone = () => {
                 try {
                   controller.close()
-                } catch (error) {
-                  controller.error(error)
+                } catch {
+                  // Already closed
                 }
+                // Close late stream writer when JSON serialization is done
+                // Any RawStreams not yet discovered won't be sent
+                lateStreamWriter
+                  ?.close()
+                  .catch(() => {
+                    // Ignore close errors
+                  })
+                  .finally(() => {
+                    lateStreamWriter = undefined
+                  })
+              }
+
+              callbacks.onError = (error) => {
+                controller.error(error)
+                lateStreamWriter
+                  ?.abort(error)
+                  .catch(() => {
+                    // Ignore abort errors
+                  })
+                  .finally(() => {
+                    lateStreamWriter = undefined
+                  })
               }
-              callbacks.onError = (error) => controller.error(error)
-              // stream initial body
+
+              // Emit initial body if we have one
               if (nonStreamingBody !== undefined) {
                 callbacks.onParse(nonStreamingBody)
               }
+              // If serialization already completed synchronously, close now
+              // This handles the case where onDone was called during toCrossJSONStream
+              // before we overwrote callbacks.onDone
+              if (done) {
+                callbacks.onDone()
+              }
+            },
+            cancel() {
+              lateStreamWriter?.abort().catch(() => {})
+              lateStreamWriter = undefined
             },
           })
-          return new Response(stream, {
+
+          // Create multiplexed stream with JSON, initial raw streams, and late streams
+          const multiplexedStream = createMultiplexedStream(
+            jsonStream,
+            rawStreams,
+            lateStreamReadable,
+          )
+
+          return new Response(multiplexedStream, {
             status: alsResponse.status,
             statusText: alsResponse.statusText,
             headers: {
-              'Content-Type': 'application/x-ndjson',
+              'Content-Type': TSS_CONTENT_TYPE_FRAMED_VERSIONED,
               [X_TSS_SERIALIZED]: 'true',
             },
           })

package/src/tanstack-start.d.ts

@@ -11,12 +11,14 @@ declare module 'tanstack-start-route-tree:v' {
 }
 
 declare module '#tanstack-start-server-fn-resolver' {
+  export type ServerFnLookupAccess = { origin: 'client' } | { origin: 'server' }
+
   export type ServerFn = ((...args: Array<any>) => Promise<any>) & {
     method?: 'GET' | 'POST'
   }
   export function getServerFnById(
     id: string,
-    opts?: { fromClient?: boolean },
+    access: ServerFnLookupAccess,
   ): Promise<ServerFn>
 }
 

package/src/transformAssetUrls.ts

@@ -445,16 +445,15 @@ export async function transformManifestAssets(
     }),
   )
 
-  const rootRoute = manifest.routes[rootRouteId]
-  if (rootRoute) {
-    rootRoute.assets = rootRoute.assets || []
-    rootRoute.assets.push(
-      buildClientEntryScriptTag(
-        transformedClientEntry.href,
-        source.injectedHeadScripts,
-      ),
-    )
-  }
+  const rootRoute = (manifest.routes[rootRouteId] =
+    manifest.routes[rootRouteId] || {})
+  rootRoute.assets = rootRoute.assets || []
+  rootRoute.assets.push(
+    buildClientEntryScriptTag(
+      transformedClientEntry.href,
+      source.injectedHeadScripts,
+    ),
+  )
 
   return manifest
 }
@@ -476,14 +475,10 @@ export function buildManifestWithClientEntry(
   const baseRootRoute = source.manifest.routes[rootRouteId]
   const routes = {
     ...source.manifest.routes,
-    ...(baseRootRoute
-      ? {
-          [rootRouteId]: {
-            ...baseRootRoute,
-            assets: [...(baseRootRoute.assets || []), scriptTag],
-          },
-        }
-      : {}),
+    [rootRouteId]: {
+      ...baseRootRoute,
+      assets: [...(baseRootRoute?.assets || []), scriptTag],
+    },
   }
 
   return { routes }

package/src/virtual-modules.ts

@@ -2,4 +2,5 @@ export const VIRTUAL_MODULES = {
   startManifest: 'tanstack-start-manifest:v',
   injectedHeadScripts: 'tanstack-start-injected-head-scripts:v',
   serverFnResolver: '#tanstack-start-server-fn-resolver',
+  pluginAdapters: '#tanstack-start-plugin-adapters',
 } as const