Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

RawStream.test.ts

628 lines19.2 KB

1import { describe, expect, it, vi } from 'vitest'
2import {
3 createStream,
4 crossSerializeStream,
5 toCrossJSONAsync,
6 toCrossJSONStream,
7 fromCrossJSON,
8} from 'seroval'
9import type { SerovalNode } from 'seroval'
10import { RawStream } from '../src/ssr/serializer/RawStream'
11import {
12 RawStreamJSONDeserializePlugin,
13 RawStreamJSONPlugin,
14 createRawStreamJSONPlugin,
15} from '../src/ssr/serializer/RawStreamJSONPlugin'
16import {
17 createRawStreamDeserializePlugin,
18 createRawStreamRPCPlugin,
19} from '../src/ssr/serializer/RawStreamRPCPlugin'
20import { RawStreamSSRPlugin } from '../src/ssr/serializer/RawStreamSSRPlugin'
21import {
22 defaultSerovalDeserializerPlugins,
23 defaultSerovalPlugins,
24} from '../src/ssr/serializer/seroval-plugins'
25​
26type EncodedStream = ReturnType<typeof createStream<any>>
27type EncodedStreamListener = Parameters<EncodedStream['on']>[0]
28type RawStreamFactory = (stream: EncodedStream) => ReadableStream<Uint8Array>
29​
30function getRawStreamFactory(
31 pluginIndex: number,
32 emitted: boolean,
33): RawStreamFactory {
34 if (emitted) {
35 const plugin = RawStreamSSRPlugin.extends![pluginIndex]!
36 const source = (plugin.serialize as () => string)()
37 return new Function(`return ${source}`)() as RawStreamFactory
38 }
39​
40 return (stream) => {
41 const textNode = {} as SerovalNode
42 const streamNode = {} as SerovalNode
43 return (RawStreamJSONDeserializePlugin.deserialize as any)(
44 { text: textNode, stream: streamNode },
45 {
46 deserialize(node: SerovalNode) {
47 return node === textNode ? pluginIndex === 1 : stream
48 },
49 },
50 )
51 }
53​
54function createTrackedEncodedStream() {
55 const listeners = new Set<EncodedStreamListener>()
56 let unsubscribeCalls = 0
57 const stream: EncodedStream = {
58 __SEROVAL_STREAM__: true,
59 on(listener) {
60 listeners.add(listener)
61 let subscribed = true
62 return () => {
63 if (subscribed) {
64 subscribed = false
65 unsubscribeCalls++
66 listeners.delete(listener)
67 }
68 }
69 },
70 next(value) {
71 for (const listener of listeners) {
72 listener.next(value)
73 }
74 },
75 throw(value) {
76 for (const listener of listeners) {
77 listener.throw(value)
78 }
79 listeners.clear()
80 },
81 return(value) {
82 for (const listener of listeners) {
83 listener.return(value)
84 }
85 listeners.clear()
86 },
87 }
88 return {
89 stream,
90 get listenerCount() {
91 return listeners.size
92 },
93 get unsubscribeCalls() {
94 return unsubscribeCalls
95 },
96 }
98​
99describe('RawStream', () => {
100 describe('RawStream class', () => {
101 it('should wrap a ReadableStream<Uint8Array>', () => {
102 const stream = new ReadableStream<Uint8Array>({
103 start(controller) {
104 controller.enqueue(new Uint8Array([1, 2, 3]))
105 controller.close()
106 },
107 })
108 const rawStream = new RawStream(stream)
109 expect(rawStream.stream).toBe(stream)
110 })
111​
112 it('should be an instance of RawStream', () => {
113 const stream = new ReadableStream<Uint8Array>()
114 const rawStream = new RawStream(stream)
115 expect(rawStream instanceof RawStream).toBe(true)
116 })
117​
118 it('should default to binary hint', () => {
119 const stream = new ReadableStream<Uint8Array>()
120 const rawStream = new RawStream(stream)
121 expect(rawStream.hint).toBe('binary')
122 })
123​
124 it('should accept binary hint option', () => {
125 const stream = new ReadableStream<Uint8Array>()
126 const rawStream = new RawStream(stream, { hint: 'binary' })
127 expect(rawStream.hint).toBe('binary')
128 })
129​
130 it('should accept text hint option', () => {
131 const stream = new ReadableStream<Uint8Array>()
132 const rawStream = new RawStream(stream, { hint: 'text' })
133 expect(rawStream.hint).toBe('text')
134 })
135 })
136​
137 describe('createRawStreamRPCPlugin', () => {
138 it('should call onRawStream callback with stream id and stream', () => {
139 const collectedStreams = new Map<number, ReadableStream<Uint8Array>>()
140​
141 const plugin = createRawStreamRPCPlugin((id, stream) => {
142 collectedStreams.set(id, stream)
143 })
144​
145 const testStream = new ReadableStream<Uint8Array>({
146 start(controller) {
147 controller.enqueue(new Uint8Array([1, 2, 3]))
148 controller.close()
149 },
150 })
151​
152 const rawStream = new RawStream(testStream)
153​
154 toCrossJSONStream(rawStream, {
155 refs: new Map(),
156 plugins: [plugin],
157 onParse() {},
158 })
159​
160 expect(collectedStreams.size).toBe(1)
161 // Stream ID is assigned by our internal counter (sequential starting at 1)
162 const streamEntry = Array.from(collectedStreams.entries())[0]
163 expect(streamEntry).toBeDefined()
164 expect(streamEntry![1]).toBe(testStream)
165 })
166​
167 it('should serialize with tss/RawStream tag', () => {
168 const plugin = createRawStreamRPCPlugin(() => {})
169​
170 const testStream = new ReadableStream<Uint8Array>()
171 const rawStream = new RawStream(testStream)
172​
173 const serialized = new Array<unknown>()
174 toCrossJSONStream(rawStream, {
175 refs: new Map(),
176 plugins: [plugin],
177 onParse(value) {
178 serialized.push(value)
179 },
180 })
181​
182 // The serialized output should have the plugin tag and contain streamId
183 const jsonStr = JSON.stringify(serialized)
184 expect(jsonStr).toContain('tss/RawStream')
185 expect(jsonStr).toContain('streamId')
186 })
187​
188 it('should collect multiple streams with unique ids', () => {
189 const collectedStreams = new Map<number, ReadableStream<Uint8Array>>()
190​
191 const plugin = createRawStreamRPCPlugin((id, stream) => {
192 collectedStreams.set(id, stream)
193 })
194​
195 const stream1 = new ReadableStream<Uint8Array>()
196 const stream2 = new ReadableStream<Uint8Array>()
197​
198 const data = {
199 first: new RawStream(stream1),
200 second: new RawStream(stream2),
201 }
202​
203 toCrossJSONStream(data, {
204 refs: new Map(),
205 plugins: [plugin],
206 onParse() {},
207 })
208​
209 expect(collectedStreams.size).toBe(2)
210 const ids = Array.from(collectedStreams.keys())
211 expect(ids[0]).not.toBe(ids[1])
212 })
213 })
214​
215 describe('round-trip serialization', () => {
216 it('does not acquire the source reader when hint parsing fails', async () => {
217 const getReader = vi.fn()
218 const stream = { getReader } as unknown as ReadableStream<Uint8Array>
219 const failure = new Error('hint parse failed')
220 const parse = RawStreamJSONPlugin.parse.async! as any
221​
222 await expect(
223 parse(new RawStream(stream), {
224 parse: () => Promise.reject(failure),
225 }),
226 ).rejects.toBe(failure)
227 expect(getReader).not.toHaveBeenCalled()
228 })
229​
230 it('does not acquire the source reader when request serialization is already aborted', async () => {
231 const getReader = vi.fn()
232 const stream = { getReader } as unknown as ReadableStream<Uint8Array>
233 const controller = new AbortController()
234 const reason = new Error('request aborted')
235 controller.abort(reason)
236​
237 await expect(
238 toCrossJSONAsync(new RawStream(stream), {
239 refs: new Map(),
240 plugins: [createRawStreamJSONPlugin(controller.signal)],
241 }),
242 ).rejects.toMatchObject({ cause: reason })
243 expect(getReader).not.toHaveBeenCalled()
244 })
245​
246 it('preserves malformed UTF-8 and BOM bytes in text chunks', async () => {
247 const cancel = vi.fn()
248 const stream = new ReadableStream<Uint8Array>({
249 start(controller) {
250 controller.enqueue(Uint8Array.of(0x41, 0xe2))
251 controller.enqueue(Uint8Array.of(0x28))
252 controller.enqueue(Uint8Array.of(0xef, 0xbb, 0xbf, 0x42))
253 controller.close()
254 },
255 cancel,
256 })
257​
258 const serialized = await new Promise<Array<string>>((resolve, reject) => {
259 const sources = new Array<string>()
260 crossSerializeStream(new RawStream(stream, { hint: 'text' }), {
261 refs: new Map(),
262 plugins: [RawStreamSSRPlugin],
263 scopeId: 'raw-stream-test',
264 onSerialize(source) {
265 sources.push(source)
266 },
267 onError: reject,
268 onDone() {
269 expect(stream.locked).toBe(false)
270 resolve(sources)
271 },
272 })
273 })
274​
275 const output = serialized.join(';')
276 expect(output).toContain('QeI=')
277 expect(output).toContain('\ufeffB')
278 expect(cancel).not.toHaveBeenCalled()
279 expect(stream.locked).toBe(false)
280 })
281​
282 it('preserves a UTF-8 character split across text chunks', async () => {
283 // Each half is invalid UTF-8 by itself. Text mode must encode both as
284 // binary instead of retaining decoder state across chunk boundaries.
285 const expected = [Uint8Array.of(0xf0, 0x9f), Uint8Array.of(0x98, 0x80)]
286 const input = new ReadableStream<Uint8Array>({
287 start(controller) {
288 for (const chunk of expected) {
289 controller.enqueue(chunk)
290 }
291 controller.close()
292 },
293 })
294​
295 const serialized = await toCrossJSONAsync(
296 new RawStream(input, { hint: 'text' }),
297 {
298 refs: new Map(),
299 plugins: [RawStreamJSONPlugin],
300 },
301 )
302 const output = fromCrossJSON(serialized, {
303 refs: new Map(),
304 plugins: [RawStreamJSONDeserializePlugin],
305 }) as ReadableStream<Uint8Array>
306 const reader = output.getReader()
307​
308 await expect(reader.read()).resolves.toEqual({
309 done: false,
310 value: expected[0],
311 })
312 await expect(reader.read()).resolves.toEqual({
313 done: false,
314 value: expected[1],
315 })
316 await expect(reader.read()).resolves.toEqual({
317 done: true,
318 value: undefined,
319 })
320 })
321​
322 it.each([
323 ['default', 'binary', defaultSerovalDeserializerPlugins],
324 ['default', 'text', defaultSerovalDeserializerPlugins],
325 ['deserialize-only', 'binary', [RawStreamJSONDeserializePlugin]],
326 ['deserialize-only', 'text', [RawStreamJSONDeserializePlugin]],
327 ] as const)(
328 'preserves every %s-plugin decoded %s-hinted chunk through async JSON',
329 async (_, hint, deserializePlugins) => {
330 const expected = [
331 new Uint8Array(),
332 Uint8Array.of(0x41, 0x42),
333 Uint8Array.of(0x41, 0xe2),
334 Uint8Array.of(0xef, 0xbb, 0xbf, 0x42),
335 ]
336 const input = new ReadableStream<Uint8Array>({
337 start(controller) {
338 for (const chunk of expected) {
339 controller.enqueue(chunk)
340 }
341 controller.close()
342 },
343 })
344​
345 const serialized = await toCrossJSONAsync(
346 new RawStream(input, { hint }),
347 {
348 refs: new Map(),
349 plugins: [RawStreamJSONPlugin],
350 },
351 )
352 const output = fromCrossJSON(serialized, {
353 refs: new Map(),
354 plugins: [...deserializePlugins],
355 }) as ReadableStream<Uint8Array>
356 const reader = output.getReader()
357 const actual: Array<Uint8Array> = []
358​
359 while (true) {
360 const next = await reader.read()
361 if (next.done) {
362 break
363 }
364 actual.push(next.value)
365 }
366​
367 expect(actual.map((chunk) => Array.from(chunk))).toEqual(
368 expected.map((chunk) => Array.from(chunk)),
369 )
370 },
371 )
372​
373 it('round-trips: client default plugins write, deserializer plugins read', async () => {
374 const input = new ReadableStream<Uint8Array>({
375 start(controller) {
376 controller.enqueue(Uint8Array.of(1, 2, 3))
377 controller.close()
378 },
379 })
380 const serialized = await toCrossJSONAsync(
381 { stream: new RawStream(input), error: new Error('boom') },
382 { refs: new Map(), plugins: defaultSerovalPlugins },
383 )
384 const output = fromCrossJSON(serialized, {
385 refs: new Map(),
386 plugins: defaultSerovalDeserializerPlugins,
387 }) as { stream: ReadableStream<Uint8Array>; error: Error }
388​
389 expect(output.error).toBeInstanceOf(Error)
390 expect(output.error.message).toBe('boom')
391 const reader = output.stream.getReader()
392 await expect(reader.read()).resolves.toEqual({
393 done: false,
394 value: Uint8Array.of(1, 2, 3),
395 })
396 await expect(reader.read()).resolves.toMatchObject({ done: true })
397 })
398​
399 it('should serialize and deserialize RawStream correctly', async () => {
400 // Collect streams during serialization
401 const collectedStreams = new Map<number, ReadableStream<Uint8Array>>()
402 const rpcPlugin = createRawStreamRPCPlugin((id, stream) => {
403 collectedStreams.set(id, stream)
404 })
405​
406 const testStream = new ReadableStream<Uint8Array>({
407 start(controller) {
408 controller.enqueue(new Uint8Array([1, 2, 3]))
409 controller.close()
410 },
411 })
412​
413 const data = {
414 message: 'test',
415 rawData: new RawStream(testStream),
416 }
417​
418 // Serialize using RPC plugin
419 const refs = new Map()
420 let serialized: SerovalNode | undefined
421 toCrossJSONStream(data, {
422 refs,
423 plugins: [rpcPlugin],
424 onParse(value) {
425 serialized = value
426 },
427 })
428​
429 // Verify we collected the stream
430 expect(collectedStreams.size).toBe(1)
431 const streamId = Array.from(collectedStreams.keys())[0]!
432​
433 // Create getOrCreateStream function
434 const getOrCreateStream = (id: number) => {
435 const stream = collectedStreams.get(id)
436 if (!stream) {
437 throw new Error(`Stream ${id} not found in collected streams`)
438 }
439 return stream
440 }
441​
442 // Create deserialize plugin with function
443 const deserializePlugin =
444 createRawStreamDeserializePlugin(getOrCreateStream)
445​
446 // Deserialize
447 const deserialized = fromCrossJSON(serialized!, {
448 refs: new Map(),
449 plugins: [deserializePlugin],
450 }) as any
451​
452 expect(deserialized.message).toBe('test')
453 expect(deserialized.rawData).toBe(testStream)
454 })
455 })
456​
457 describe('SSR stream lifecycle', () => {
458 it.each(['chunk', 'eof', 'error'] as const)(
459 'ignores a late %s read result after disposal',
460 async (settlement) => {
461 let resolveRead!: (result: ReadableStreamReadResult<Uint8Array>) => void
462 let rejectRead!: (error: unknown) => void
463 const readResult = new Promise<ReadableStreamReadResult<Uint8Array>>(
464 (resolve, reject) => {
465 resolveRead = resolve
466 rejectRead = reject
467 },
468 )
469 const reader = {
470 read: vi.fn(() => readResult),
471 cancel: vi.fn(() => Promise.resolve()),
472 releaseLock: vi.fn(),
473 }
474 const readable = {
475 getReader: () => reader,
476 } as unknown as ReadableStream<Uint8Array>
477 const sources = new Array<string>()
478 const dispose = crossSerializeStream(new RawStream(readable), {
479 refs: new Map(),
480 plugins: [RawStreamSSRPlugin],
481 scopeId: 'raw-stream-disposal-test',
482 onSerialize(source) {
483 sources.push(source)
484 },
485 })
486​
487 expect(reader.read).toHaveBeenCalledTimes(1)
488 const sourceCount = sources.length
489 dispose()
490 dispose()
491 expect(reader.cancel).toHaveBeenCalledTimes(1)
492 expect(reader.releaseLock).toHaveBeenCalledTimes(1)
493​
494 if (settlement === 'error') {
495 rejectRead(new Error('late read failure'))
496 } else {
497 resolveRead(
498 settlement === 'eof'
499 ? { done: true, value: undefined }
500 : { done: false, value: Uint8Array.of(1) },
501 )
502 }
503 await Promise.resolve()
504 await Promise.resolve()
505​
506 expect(sources).toHaveLength(sourceCount)
507 expect(reader.read).toHaveBeenCalledTimes(1)
508 expect(reader.cancel).toHaveBeenCalledTimes(1)
509 expect(reader.releaseLock).toHaveBeenCalledTimes(1)
510 },
511 )
512 })
513​
514 describe.each([
515 { hint: 'binary', pluginIndex: 0, encoded: 'QQ==' },
516 { hint: 'text', pluginIndex: 1, encoded: 'tA' },
517 ] as const)('$hint browser factory', ({ pluginIndex, encoded }) => {
518 it.each([
519 ['local', false],
520 ['emitted', true],
521 ] as const)(
522 'unsubscribes the %s factory on cancellation',
523 async (_, emitted) => {
524 const factory = getRawStreamFactory(pluginIndex, emitted)
525 const encodedStream = createTrackedEncodedStream()
526 const output = factory(encodedStream.stream)
527 const reader = output.getReader()
528​
529 expect(encodedStream.listenerCount).toBe(1)
530 encodedStream.stream.next(encoded)
531 const chunk = await reader.read()
532 expect(chunk.done).toBe(false)
533 expect(Array.from(chunk.value!)).toEqual([65])
534​
535 await reader.cancel()
536 await reader.cancel()
537 expect(encodedStream.unsubscribeCalls).toBe(1)
538 expect(encodedStream.listenerCount).toBe(0)
539​
540 encodedStream.stream.next(encoded)
541 expect(encodedStream.listenerCount).toBe(0)
542 },
543 )
544​
545 it.each([
546 ['local', false],
547 ['emitted', true],
548 ] as const)(
549 'does not retain a synchronous terminal disposer in the %s factory',
550 async (_, emitted) => {
551 const unsubscribe = vi.fn()
552 const stream = {
553 __SEROVAL_STREAM__: true,
554 on(listener: EncodedStreamListener) {
555 listener.next(encoded)
556 listener.return(undefined)
557 return unsubscribe
558 },
559 next() {},
560 throw() {},
561 return() {},
562 } as EncodedStream
563 const reader = getRawStreamFactory(
564 pluginIndex,
565 emitted,
566 )(stream).getReader()
567​
568 expect(unsubscribe).toHaveBeenCalledTimes(emitted ? 0 : 1)
569 await reader.cancel()
570 expect(unsubscribe).toHaveBeenCalledTimes(emitted ? 0 : 1)
571 },
572 )
573​
574 it.each([false, true])(
575 'disposes a malformed buffered JSON stream (ended: %s)',
576 async (ended) => {
577 const stream = createStream<string | undefined>()
578 stream.next(pluginIndex === 1 ? 'b%' : '%')
579 stream.next(encoded)
580 if (ended) {
581 stream.return(undefined)
582 }
583 const on = stream.on.bind(stream)
584 const unsubscribe = vi.fn()
585 vi.spyOn(stream, 'on').mockImplementation((listener) => {
586 unsubscribe.mockImplementation(on(listener))
587 return unsubscribe
588 })
589​
590 const reader = getRawStreamFactory(
591 pluginIndex,
592 false,
593 )(stream).getReader()
594​
595 expect(unsubscribe).toHaveBeenCalledOnce()
596 await expect(reader.read()).rejects.toMatchObject({
597 name: 'InvalidCharacterError',
598 })
599 stream.next(encoded)
600 await expect(reader.cancel()).rejects.toMatchObject({
601 name: 'InvalidCharacterError',
602 })
603 expect(unsubscribe).toHaveBeenCalledOnce()
604 reader.releaseLock()
605 },
606 )
607​
608 it.each([
609 ['local', false],
610 ['emitted', true],
611 ] as const)(
612 'does not retain a live terminal disposer in the %s factory',
613 async (_, emitted) => {
614 const encodedStream = createTrackedEncodedStream()
615 const reader = getRawStreamFactory(
616 pluginIndex,
617 emitted,
618 )(encodedStream.stream).getReader()
619​
620 encodedStream.stream.next(encoded)
621 encodedStream.stream.return(undefined)
622 await reader.cancel()
623​
624 expect(encodedStream.unsubscribeCalls).toBe(0)
625 },
626 )
627 })
628})