Open History to see the last commit
1/**
2 * Binary frame protocol for multiplexing JSON and raw streams over HTTP.
3 *
4 * Frame format: [type:1][streamId:4][length:4][payload:length]
5 * - type: 1 byte - frame type (JSON, CHUNK, END, ERROR)
6 * - streamId: 4 bytes big-endian uint32 - stream identifier
7 * - length: 4 bytes big-endian uint32 - payload length
8 * - payload: variable length bytes
9 */
10β
11import {
12 FRAME_HEADER_SIZE,
13 FRAME_TYPE_CHUNK,
14 FRAME_TYPE_END,
15 FRAME_TYPE_ERROR,
16 FRAME_TYPE_JSON,
17 MAX_FRAME_PAYLOAD_SIZE,
18} from '@tanstack/start-client-core/client-rpc'
19β
20type FrameType =
21 | typeof FRAME_TYPE_JSON
22 | typeof FRAME_TYPE_CHUNK
23 | typeof FRAME_TYPE_END
24 | typeof FRAME_TYPE_ERROR
25β
26/** Cached TextEncoder for frame encoding */
27const textEncoder = new TextEncoder()
28β
29/** Shared empty payload for END frames - avoids allocation per call */
30const EMPTY_PAYLOAD = new Uint8Array(0)
31const MAX_ERROR_MESSAGE_CODE_UNITS = 4096
32β
33/**
34 * Encodes a single frame with header and payload.
35 */
36function encodeFrame(
37 type: FrameType,
38 streamId: number,
39 payload: Uint8Array,
40): Uint8Array {
41 if (payload.byteLength > MAX_FRAME_PAYLOAD_SIZE) {
42 throw new RangeError(
43 `Frame payload exceeds ${MAX_FRAME_PAYLOAD_SIZE} bytes`,
44 )
45 }
46 const frame = new Uint8Array(FRAME_HEADER_SIZE + payload.length)
47 // Write header bytes directly to avoid DataView allocation per frame
48 // Frame format: [type:1][streamId:4 BE][length:4 BE]
49 frame[0] = type
50 frame[1] = (streamId >>> 24) & 0xff
51 frame[2] = (streamId >>> 16) & 0xff
52 frame[3] = (streamId >>> 8) & 0xff
53 frame[4] = streamId & 0xff
54 frame[5] = (payload.length >>> 24) & 0xff
55 frame[6] = (payload.length >>> 16) & 0xff
56 frame[7] = (payload.length >>> 8) & 0xff
57 frame[8] = payload.length & 0xff
58 frame.set(payload, FRAME_HEADER_SIZE)
59 return frame
60}
61β
62/** Encodes an error message payload, truncated to a bounded length. */
63function encodeErrorPayload(error: unknown): Uint8Array {
64 const originalMessage =
65 error instanceof Error ? error.message : String(error ?? 'Unknown error')
66 const message =
67 originalMessage.length > MAX_ERROR_MESSAGE_CODE_UNITS
68 ? `${originalMessage.slice(0, MAX_ERROR_MESSAGE_CODE_UNITS)}β¦`
69 : originalMessage
70 return textEncoder.encode(message)
71}
72β
73/**
74 * Late stream registration for RawStreams discovered after serialization starts.
75 * Used when Promise<RawStream> resolves after the initial synchronous pass.
76 */
77export interface LateStreamRegistration {
78 id: number
79 stream: ReadableStream<Uint8Array>
80}
81β
82/** One serialized JSON patch and the raw streams referenced by that patch. */
83export interface MultiplexedStreamRecord {
84 json: Uint8Array
85 rawStreams: Array<LateStreamRegistration>
86}
87β
88export interface MultiplexedStreamOptions {
89 onCancel?: (reason?: unknown) => void
90 signal?: AbortSignal
91}
92β
93type CancellableReader = Pick<
94 ReadableStreamDefaultReader<unknown>,
95 'cancel' | 'releaseLock'
96>
97β
98/**
99 * Creates a multiplexed ReadableStream from serialized response records.
100 *
101 * A record's JSON frame is admitted before any raw stream referenced by that
102 * record starts. Raw streams from admitted records are pumped concurrently.
103 * The caller bounds the stream count before records reach this function.
104 */
105export function createMultiplexedStream(
106 recordStream: ReadableStream<MultiplexedStreamRecord>,
107 options: MultiplexedStreamOptions = {},
108): ReadableStream<Uint8Array> {
109 let controller: ReadableStreamDefaultController<Uint8Array>
110 let stopped: false | [unknown] = false
111 let activePumps = 0
112 let wakeDemand: (() => void) | undefined
113 let admission: Promise<void> | undefined
114 const readers = new Set<CancellableReader>()
115 const pendingRawStreams = new Set<ReadableStream<Uint8Array>>()
116 const abortOutput = () => errorOutput(options.signal?.reason)
117β
118 const wakeAdmission = () => {
119 const wake = wakeDemand
120 wakeDemand = undefined
121 wake?.()
122 }
123β
124 const cancelReader = (reader: CancellableReader, reason?: unknown) => {
125 void reader.cancel(reason).catch(() => {})
126 }
127β
128 const cancelStream = (stream: ReadableStream<unknown>, reason?: unknown) => {
129 void stream.cancel(reason).catch(() => {})
130 }
131β
132 const stop = (reason?: unknown) => {
133 if (stopped) {
134 return false
135 }
136 stopped = [reason]
137 options.signal?.removeEventListener('abort', abortOutput)
138 wakeAdmission()
139 for (const reader of readers) {
140 cancelReader(reader, reason)
141 }
142 for (const stream of pendingRawStreams) {
143 cancelStream(stream, reason)
144 }
145 pendingRawStreams.clear()
146 return true
147 }
148β
149 const errorOutput = (error: unknown) => {
150 if (!stop(error)) {
151 return
152 }
153 try {
154 controller.error(error)
155 } catch {
156 // The output was already closed by its consumer.
157 }
158 }
159β
160 const waitForDemand = async () => {
161 while (!stopped && (controller.desiredSize ?? 0) <= 0) {
162 await new Promise<void>((resolve) => {
163 wakeDemand = resolve
164 })
165 }
166 return !stopped
167 }
168β
169 // Only the pump at the head of this chain may inspect desiredSize and
170 // enqueue. Each other pump can retain at most one unencoded source chunk.
171 // The frame is encoded only once the output has demand for it.
172 const admitFrame = (
173 type: FrameType,
174 streamId: number,
175 payload: Uint8Array,
176 ): boolean | Promise<boolean> => {
177 if (stopped) {
178 return false
179 }
180 if (!admission && (controller.desiredSize ?? 0) > 0) {
181 controller.enqueue(encodeFrame(type, streamId, payload))
182 return true
183 }
184β
185 const runAdmission = async () => {
186 if (!(await waitForDemand())) {
187 return false
188 }
189 controller.enqueue(encodeFrame(type, streamId, payload))
190 return true
191 }
192 const result = admission ? admission.then(runAdmission) : runAdmission()
193 const clearAdmission = () => {
194 if (admission === tail) {
195 admission = undefined
196 }
197 }
198 const tail = result.then(clearAdmission, clearAdmission)
199 admission = tail
200 return result
201 }
202β
203 const maybeClose = () => {
204 if (activePumps !== 0 || !stop()) {
205 return
206 }
207 try {
208 controller.close()
209 } catch {
210 // The output was already closed by its consumer.
211 }
212 }
213β
214 const startPump = (pump: () => Promise<void>) => {
215 activePumps++
216 void pump().then(
217 () => {
218 activePumps--
219 maybeClose()
220 },
221 (error) => {
222 activePumps--
223 errorOutput(error)
224 },
225 )
226 }
227β
228 async function pumpRawStream(
229 streamId: number,
230 stream: ReadableStream<Uint8Array>,
231 ) {
232 const reader = stream.getReader()
233 readers.add(reader)
234 try {
235 while (!stopped) {
236 const { done, value } = await reader.read()
237 // Cancellation can run while the read is suspended.
238 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
239 if (stopped) {
240 return
241 }
242 if (done) {
243 const frameAdmission = admitFrame(
244 FRAME_TYPE_END,
245 streamId,
246 EMPTY_PAYLOAD,
247 )
248 if (frameAdmission !== true) {
249 await frameAdmission
250 }
251 return
252 }
253 if (!(value instanceof Uint8Array)) {
254 throw new TypeError('RawStream chunks must be Uint8Array')
255 }
256 // One frame per read, split only when the chunk exceeds a frame.
257 let offset = 0
258 do {
259 const chunk =
260 value.byteLength <= MAX_FRAME_PAYLOAD_SIZE
261 ? value
262 : value.subarray(offset, offset + MAX_FRAME_PAYLOAD_SIZE)
263 const frameAdmission = admitFrame(FRAME_TYPE_CHUNK, streamId, chunk)
264 if (
265 frameAdmission !== true &&
266 (frameAdmission === false || !(await frameAdmission))
267 ) {
268 return
269 }
270 offset += MAX_FRAME_PAYLOAD_SIZE
271 } while (offset < value.byteLength)
272 }
273 } catch (error) {
274 if (!stopped) {
275 // A raw-stream failure is isolated to that stream.
276 const frameAdmission = admitFrame(
277 FRAME_TYPE_ERROR,
278 streamId,
279 encodeErrorPayload(error),
280 )
281 if (frameAdmission !== true) {
282 await frameAdmission
283 }
284 }
285 } finally {
286 readers.delete(reader)
287 reader.releaseLock()
288 }
289 }
290β
291 async function pumpRecords() {
292 const reader = recordStream.getReader()
293 readers.add(reader)
294 try {
295 while (!stopped) {
296 const { done, value } = await reader.read()
297 // Cancellation can run while the read is suspended.
298 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
299 if (stopped) {
300 if (!done) {
301 for (const registration of value.rawStreams) {
302 cancelStream(registration.stream, stopped[0])
303 }
304 }
305 return
306 }
307 if (done) {
308 return
309 }
310 for (const registration of value.rawStreams) {
311 pendingRawStreams.add(registration.stream)
312 }
313 const frameAdmission = admitFrame(FRAME_TYPE_JSON, 0, value.json)
314 if (
315 frameAdmission !== true &&
316 (frameAdmission === false || !(await frameAdmission))
317 ) {
318 return
319 }
320 for (const registration of value.rawStreams) {
321 pendingRawStreams.delete(registration.stream)
322 startPump(
323 pumpRawStream.bind(undefined, registration.id, registration.stream),
324 )
325 }
326 }
327 } catch (error) {
328 if (!stopped) {
329 // JSON records describe the response graph, so losing one is fatal.
330 errorOutput(error)
331 }
332 } finally {
333 readers.delete(reader)
334 reader.releaseLock()
335 }
336 }
337β
338 return new ReadableStream<Uint8Array>({
339 start(ctrl) {
340 controller = ctrl
341 if (options.signal?.aborted) {
342 cancelStream(recordStream, options.signal.reason)
343 errorOutput(options.signal.reason)
344 return
345 }
346 options.signal?.addEventListener('abort', abortOutput, { once: true })
347 startPump(pumpRecords)
348 },
349 pull() {
350 wakeAdmission()
351 },
352 cancel(reason) {
353 if (stop(reason)) {
354 options.onCancel?.(reason)
355 }
356 },
357 })
358}