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

transformStreamBackpressure.perf.test.ts

264 lines8.2 KB

1// On-demand backpressure test for transformReadableStreamWithRouter.
2//
3// NOT run in CI by default. To execute:
4// RUN_BACKPRESSURE_PERF=1 pnpm --filter @tanstack/router-core test:unit -- transformStreamBackpressure
5//
6// Validates fix for TanStack/router#7402
7// without a backpressure gate the read loop in
8// transformReadableStreamWithRouter calls controller.enqueue unconditionally,
9// allowing controller.[[queue]] to accumulate Uint8Array chunks (external
10// memory) when the consumer drains slower than the producer.
11import { describe, expect, it } from 'vitest'
12import {
13 HYDRATION_SCRIPT_BOUNDARY_BYTES,
14 HydrationScriptOutputState,
15} from '../src/ssr/hydrationScripts'
16import { transformReadableStreamWithRouter } from '../src/ssr/transformStreamWithRouter'
17import type { HydrationScriptOutput } from '../src/ssr/hydrationScripts'
18​
19const enabled = process.env.RUN_BACKPRESSURE_PERF === '1'
20const requiresGc = typeof (globalThis as any).gc === 'function'
21const SCRIPT_BARRIER_HTML = `<script>document.currentScript.remove()${new TextDecoder().decode(HYDRATION_SCRIPT_BOUNDARY_BYTES).slice(0, -'</script>'.length)}</script>`
22​
23function createFastProducer(
24 chunkCount: number,
25 chunkBytes: number,
26 opts: { freshChunks?: boolean } = {},
27) {
28 let pulls = 0
29 let produced = 0
30 const reusable = opts.freshChunks
31 ? null
32 : new Uint8Array(chunkBytes).fill(0x61)
33 const stream = new ReadableStream<Uint8Array>({
34 pull(controller) {
35 pulls++
36 if (produced >= chunkCount) {
37 controller.close()
38 return
39 }
40 produced++
41 // Fresh allocation for external-memory tests: reusing one Uint8Array
42 // means the upstream queue never actually retains additional native
43 // memory even if our transform held arbitrarily many references.
44 controller.enqueue(
45 opts.freshChunks ? new Uint8Array(chunkBytes).fill(0x61) : reusable!,
46 )
47 },
48 })
49 return {
50 stream,
51 getPulls: () => pulls,
52 getProduced: () => produced,
53 }
55​
56function makeRouter() {
57 const output: HydrationScriptOutput = {
58 state: HydrationScriptOutputState.Done,
59 error: undefined,
60 pullChunk() {
61 throw new Error('Finished hydration output cannot be pulled')
62 },
63 subscribe() {
64 return () => {}
65 },
66 }
67 return {
68 serverSsr: {
69 hydrationScripts: {
70 reserveFastPath: () => true,
71 claimOutput: () => output,
72 liftBarrier: () => {},
73 isInitialTaken: () => true,
74 startSerializationTimeout: () => {},
75 },
76 setRenderFinished: () => {},
77 onCleanup: () => {},
78 cleanup: () => {},
79 },
80 } as any
82​
83// Main-path router fake: serialization NOT finished synchronously, so the
84// transform runs the full scanner + script merger path. Exposes hooks to
85// emit router script batches and signal serialization finished.
86function makeMainPathRouter(): {
87 router: any
88 finishSerialization: () => void
89} {
90 let state: HydrationScriptOutput['state'] = HydrationScriptOutputState.Waiting
91 let listener: (() => void) | undefined
92 const output: HydrationScriptOutput = {
93 get state() {
94 return state
95 },
96 error: undefined,
97 pullChunk() {
98 throw new Error('No hydration output is ready')
99 },
100 subscribe(onChange) {
101 listener = onChange
102 return () => {
103 if (listener === onChange) {
104 listener = undefined
105 }
106 }
107 },
108 }
109 const router: any = {
110 serverSsr: {
111 hydrationScripts: {
112 reserveFastPath: () => false,
113 claimOutput: () => output,
114 liftBarrier: () => {},
115 isInitialTaken: () => true,
116 startSerializationTimeout: () => {},
117 },
118 setRenderFinished: () => {},
119 onCleanup: () => {},
120 cleanup: () => {},
121 },
122 }
123 return {
124 router,
125 finishSerialization: () => {
126 state = HydrationScriptOutputState.Done
127 listener?.()
128 },
129 }
131​
132describe.runIf(enabled)(
133 'transformReadableStreamWithRouter backpressure',
134 () => {
135 it('does not run producer arbitrarily ahead of slow consumer', async () => {
136 const CHUNKS = 200
137 const CHUNK_BYTES = 8 * 1024 // 8KB per chunk
138 const producer = createFastProducer(CHUNKS, CHUNK_BYTES)
139 const router = makeRouter()
140​
141 const out = transformReadableStreamWithRouter(router, producer.stream)
142​
143 const reader = out.getReader()
144 let consumed = 0
145 let maxLead = 0
146 for (;;) {
147 // Throttled consumer: ~5ms per chunk.
148 await new Promise((r) => setTimeout(r, 5))
149 const { done } = await reader.read()
150 if (done) {
151 break
152 }
153 consumed++
154 const lead = producer.getProduced() - consumed
155 if (lead > maxLead) {
156 maxLead = lead
157 }
158 }
159​
160 // Producer should never be more than a small constant number of chunks
161 // ahead of the consumer. ReadableStream default HWM is 1 for byte
162 // streams; allow generous slack for scheduling jitter.
163 expect(maxLead).toBeLessThanOrEqual(8)
164 expect(consumed).toBe(CHUNKS)
165 })
166​
167 it('bounded external memory under sustained load', async () => {
168 expect(requiresGc, 'Run with node --expose-gc').toBe(true)
169 const CHUNKS = 1000
170 const CHUNK_BYTES = 16 * 1024
171 const producer = createFastProducer(CHUNKS, CHUNK_BYTES, {
172 freshChunks: true,
173 })
174 const router = makeRouter()
175​
176 const out = transformReadableStreamWithRouter(router, producer.stream)
177 const reader = out.getReader()
178​
179 ;(globalThis as any).gc()
180 ;(globalThis as any).gc()
181 let consumed = 0
182 let peakExternal = 0
183 const baseline = process.memoryUsage().external
184 for (;;) {
185 await new Promise((r) => setTimeout(r, 2))
186 const { done } = await reader.read()
187 if (done) {
188 break
189 }
190 consumed++
191 if (consumed % 50 === 0) {
192 ;(globalThis as any).gc()
193 const ext = process.memoryUsage().external - baseline
194 if (ext > peakExternal) {
195 peakExternal = ext
196 }
197 }
198 }
199​
200 // Without backpressure, peak external memory scales w/ CHUNKS*CHUNK_BYTES
201 // (~16MB). With backpressure, only a few chunks worth.
202 expect(peakExternal).toBeLessThan(2 * 1024 * 1024) // 2MB ceiling
203 expect(consumed).toBe(CHUNKS)
204 })
205​
206 it('main path: scanner+inject path also honors backpressure', async () => {
207 // Same shape as fast-path test but with a router that forces the
208 // scanner+inject code path. Producer emits valid HTML fragments
209 // (ending at closing tags) so the scanner can release them.
210 const CHUNKS = 200
211 const CHUNK_BYTES = 8 * 1024
212 const filler = 'a'.repeat(CHUNK_BYTES - '<p></p>'.length)
213 const chunkStr = `<p>${filler}</p>`
214 const encoded = new TextEncoder().encode(chunkStr)
215 const firstFiller = 'a'.repeat(
216 CHUNK_BYTES - '<p></p>'.length - SCRIPT_BARRIER_HTML.length,
217 )
218 const firstEncoded = new TextEncoder().encode(
219 `<p>${firstFiller}${SCRIPT_BARRIER_HTML}</p>`,
220 )
221​
222 let produced = 0
223 const stream = new ReadableStream<Uint8Array>({
224 pull(controller) {
225 if (produced >= CHUNKS) {
226 controller.close()
227 return
228 }
229 produced++
230 controller.enqueue(produced === 1 ? firstEncoded : encoded)
231 },
232 })
233​
234 const { router, finishSerialization } = makeMainPathRouter()
235 const out = transformReadableStreamWithRouter(router, stream)
236 // Mark serialization finished immediately so tryFinish() proceeds once
237 // upstream closes.
238 finishSerialization()
239​
240 const reader = out.getReader()
241 let consumed = 0
242 let bytes = 0
243 let maxLead = 0
244 for (;;) {
245 await new Promise((r) => setTimeout(r, 5))
246 const { done, value } = await reader.read()
247 if (done) {
248 break
249 }
250 consumed++
251 bytes += value.byteLength
252 const lead = produced - consumed
253 if (lead > maxLead) {
254 maxLead = lead
255 }
256 }
257​
258 expect(maxLead).toBeLessThanOrEqual(8)
259 // The merger splits the first renderer record at the router boundary.
260 expect(consumed).toBe(CHUNKS + 1)
261 expect(bytes).toBe(CHUNKS * encoded.byteLength)
262 })
263 },