Open History to see the last commit
1/* eslint-disable @typescript-eslint/triple-slash-reference */
2/// <reference path="../vite-env.d.ts" />
3β
4import { getCrossReferenceHeader } from 'seroval'
5import { invariant } from '../invariant'
6import minifiedTsrBootStrapScript from './tsrScript?script-string'
7import { GLOBAL_TSR } from './constants'
8import { encodeIntoBoundedChunk } from './htmlBoundaryScanner'
9import type { RouterManagedTag } from '../manifest'
10β
11export const SSR_SERIALIZATION_SCOPE_ID = 'tsr'
12const HYDRATION_SCRIPT_BOUNDARY_TAIL = ';/*$tsr-stream-boundary*/'
13β
14const encoder = new TextEncoder()
15const SOURCE_SEPARATOR = ';'
16const MAX_INITIAL_SOURCE_CODE_UNITS = 16 * 1024
17const MAX_BACKLOG_CODE_UNITS = 16 * 1024 * 1024
18const MAX_BACKLOG_SOURCES = 4_096
19const MIN_OUTPUT_BYTES = 256
20const MAX_DIRECT_CODE_UNITS = 16 * 1024
21export const MAX_HYDRATION_OUTPUT_CHUNK_BYTES = 64 * 1024
22const MAX_DYNAMIC_RECORD_CODE_UNITS = MAX_HYDRATION_OUTPUT_CHUNK_BYTES
23β
24const STREAM_PART_ATTRIBUTE = 'data-tsr-stream-part'
25const INITIAL_CLEANUP_SOURCE = `{let s=document.currentScript,p;while((p=s.previousElementSibling)&&p.hasAttribute('${STREAM_PART_ATTRIBUTE}'))p.remove();s.remove()}`
26const INITIAL_CLEANUP_SUFFIX = SOURCE_SEPARATOR + INITIAL_CLEANUP_SOURCE
27const DYNAMIC_CLOSE_SOURCE = 'document.currentScript.remove()</script>'
28const HYDRATION_SCRIPT_BOUNDARY_SOURCE =
29 `document.currentScript.remove()` + HYDRATION_SCRIPT_BOUNDARY_TAIL
30const HYDRATION_SCRIPT_BOUNDARY_SUFFIX =
31 HYDRATION_SCRIPT_BOUNDARY_TAIL + '</script>'
32export const HYDRATION_SCRIPT_BOUNDARY_ANCHOR_INDEX =
33 HYDRATION_SCRIPT_BOUNDARY_SUFFIX.lastIndexOf('*')
34export const HYDRATION_SCRIPT_BOUNDARY_BYTES = encoder.encode(
35 HYDRATION_SCRIPT_BOUNDARY_SUFFIX,
36)
37β
38const ROUTER_PREFIX = GLOBAL_TSR + '.router='
39const PROMISE_PREFIX = GLOBAL_TSR + '.p(()=>'
40const DEFAULT_INITIAL_SOURCES = [
41 getCrossReferenceHeader(SSR_SERIALIZATION_SCOPE_ID),
42 minifiedTsrBootStrapScript,
43]
44β
45export const HydrationScriptOutputState = {
46 Waiting: 0,
47 Ready: 1,
48 Active: 2,
49 Done: 3,
50 Failed: 4,
51} as const
52β
53export type HydrationScriptOutputState =
54 (typeof HydrationScriptOutputState)[keyof typeof HydrationScriptOutputState]
55β
56/** A request-local, single-consumer stream of complete records. */
57export type HydrationScriptOutput = {
58 readonly state: HydrationScriptOutputState
59 readonly error: unknown
60 pullChunk: () => Uint8Array
61 subscribe: (onChange: () => void) => () => void
62}
63β
64type ConsumerOwnership =
65 | HydrationScriptOutput
66 | 'fast-path'
67 | 'cleaned'
68 | undefined
69β
70/** The one-time initial `<Scripts>` take: hydration tags plus the boundary. */
71export type InitialHydrationScriptTags = {
72 before: Array<RouterManagedTag>
73 boundary: RouterManagedTag
74}
75β
76function escapeAttribute(value: string) {
77 return value.replace(/[&"'<>]/g, (char) => `&#${char.charCodeAt(0)};`)
78}
79β
80function createInitialTags(
81 sources: ReadonlyArray<string>,
82 nonce: string | undefined,
83): InitialHydrationScriptTags {
84 const before: Array<RouterManagedTag> = []
85 for (const source of sources) {
86 if (!source) {
87 continue
88 }
89 const previous = before[before.length - 1]
90 if (
91 previous?.children &&
92 previous.children.length + SOURCE_SEPARATOR.length + source.length <=
93 MAX_INITIAL_SOURCE_CODE_UNITS
94 ) {
95 previous.children += SOURCE_SEPARATOR + source
96 } else {
97 before.push({
98 tag: 'script',
99 attrs: { nonce, [STREAM_PART_ATTRIBUTE]: '' },
100 children: source,
101 })
102 }
103 }
104 // Cleanup runs before route and asset scripts. If hydration code fails, its
105 // transport tags can remain because that page cannot hydrate successfully.
106 const lastHydrationTag = before[before.length - 1]
107 if (lastHydrationTag) {
108 const lastSource = lastHydrationTag.children!
109 if (
110 lastSource.length + INITIAL_CLEANUP_SUFFIX.length <=
111 MAX_INITIAL_SOURCE_CODE_UNITS
112 ) {
113 lastHydrationTag.children = lastSource + INITIAL_CLEANUP_SUFFIX
114 } else {
115 // Do not concatenate onto a large source. A renderer could flatten the
116 // result and temporarily retain a second copy of the hydration payload.
117 before.push({
118 tag: 'script',
119 attrs: { nonce, [STREAM_PART_ATTRIBUTE]: '' },
120 children: INITIAL_CLEANUP_SOURCE,
121 })
122 }
123 }
124 return {
125 before,
126 boundary: {
127 tag: 'script',
128 attrs: { nonce },
129 children: HYDRATION_SCRIPT_BOUNDARY_SOURCE,
130 } satisfies RouterManagedTag,
131 }
132}
133β
134type HydrationScripts = {
135 pushSerializedSource: (
136 data: string,
137 initial: boolean,
138 wrap: boolean,
139 ) => boolean
140 pushSource: (nextSource: string) => boolean
141 fail: (reason: unknown) => void
142 finish: () => void
143 takeInitialHydrationScriptTags: () => InitialHydrationScriptTags | undefined
144 disableHydration: () => void
145 isInitialTaken: () => boolean
146 skipInitialTake: () => void
147 liftBarrier: () => void
148 claimOutput: () => HydrationScriptOutput
149 reserveFastPath: (output?: HydrationScriptOutput) => boolean
150 startSerializationTimeout: (timeoutMs: number) => void
151 cleanup: () => void
152}
153β
154class HydrationScriptsOwner implements HydrationScriptOutput {
155 private queuedSources: Array<string | undefined> = []
156 private queuedSourceHead = 0
157 private initialTaken = false
158 private barrierLifted = false
159 private producerDone = false
160 private consumer: ConsumerOwnership
161 private listener: (() => void) | undefined
162β
163 private active: Array<string | undefined> | undefined
164 private retainedSources = 0
165 private regularCodeUnits = 0
166 private hasOversizedSource = false
167β
168 private segmentIndex = 0
169 private closingSegmentIndex = 0
170 private source = ''
171 private sourceOffset = 0
172 private outputCapacity = MIN_OUTPUT_BYTES
173β
174 private outputState: HydrationScriptOutputState =
175 HydrationScriptOutputState.Waiting
176 private outputError: unknown
177 private timeout: ReturnType<typeof setTimeout> | undefined
178 private opening: string | undefined
179β
180 constructor(
181 private readonly nonce: string | undefined,
182 initialSources?: ReadonlyArray<string>,
183 ) {
184 // ServerSsr exposes this method as a bare callback, so keep this single
185 // method bound while all other owner operations live on the prototype.
186 this.takeInitialHydrationScriptTags =
187 this.takeInitialHydrationScriptTags.bind(this)
188β
189 const seedSources = initialSources ?? DEFAULT_INITIAL_SOURCES
190 for (const seedSource of seedSources) {
191 if (!this.account(seedSource)) {
192 break
193 }
194 this.queuedSources.push(seedSource)
195 }
196 }
197β
198 get state() {
199 return this.outputState
200 }
201β
202 get error() {
203 return this.outputError
204 }
205β
206 private notify() {
207 try {
208 this.listener?.()
209 } catch (listenerError) {
210 console.error('Hydration script output listener error:', listenerError)
211 }
212 }
213β
214 private refresh(notifyChange = true) {
215 const next =
216 this.outputState === HydrationScriptOutputState.Failed
217 ? HydrationScriptOutputState.Failed
218 : this.active
219 ? HydrationScriptOutputState.Active
220 : typeof this.consumer === 'object' &&
221 this.initialTaken &&
222 this.barrierLifted &&
223 !this.queueIsEmpty()
224 ? HydrationScriptOutputState.Ready
225 : this.producerDone && this.initialTaken && this.queueIsEmpty()
226 ? HydrationScriptOutputState.Done
227 : HydrationScriptOutputState.Waiting
228 if (this.outputState !== next) {
229 this.outputState = next
230 if (notifyChange) {
231 this.notify()
232 }
233 }
234 }
235β
236 private clearTimeoutIfSet() {
237 if (this.timeout !== undefined) {
238 clearTimeout(this.timeout)
239 this.timeout = undefined
240 }
241 }
242β
243 private queueIsEmpty() {
244 return this.queuedSourceHead === this.queuedSources.length
245 }
246β
247 private clearQueue() {
248 this.queuedSources = []
249 this.queuedSourceHead = 0
250 }
251β
252 private dropBufferedOutput() {
253 this.clearQueue()
254 this.active = undefined
255 this.retainedSources = 0
256 this.regularCodeUnits = 0
257 this.hasOversizedSource = false
258 this.segmentIndex = 0
259 this.closingSegmentIndex = 0
260 this.source = ''
261 this.sourceOffset = 0
262 this.outputCapacity = MIN_OUTPUT_BYTES
263 this.opening = undefined
264 }
265β
266 fail(reason: unknown) {
267 if (
268 this.consumer === 'cleaned' ||
269 this.outputState === HydrationScriptOutputState.Failed
270 ) {
271 return
272 }
273 this.outputError = reason
274 this.clearTimeoutIfSet()
275 this.dropBufferedOutput()
276 this.outputState = HydrationScriptOutputState.Failed
277 this.notify()
278 }
279β
280 private rejectBacklog(kind: 'source-part' | 'code-unit') {
281 this.fail(new Error(`SSR hydration backlog exceeded maximum ${kind} count`))
282 return false
283 }
284β
285 private account(nextSource: string) {
286 if (this.retainedSources === MAX_BACKLOG_SOURCES) {
287 return this.rejectBacklog('source-part')
288 }
289 if (nextSource.length > MAX_BACKLOG_CODE_UNITS) {
290 if (this.hasOversizedSource) {
291 return this.rejectBacklog('code-unit')
292 }
293 this.hasOversizedSource = true
294 } else if (
295 this.regularCodeUnits + nextSource.length >
296 MAX_BACKLOG_CODE_UNITS
297 ) {
298 return this.rejectBacklog('code-unit')
299 } else {
300 this.regularCodeUnits += nextSource.length
301 }
302 this.retainedSources++
303 return true
304 }
305β
306 private releaseSource(part: string) {
307 this.retainedSources--
308 if (part.length > MAX_BACKLOG_CODE_UNITS) {
309 this.hasOversizedSource = false
310 } else {
311 this.regularCodeUnits -= part.length
312 }
313 }
314β
315 private releaseAccounting(batch: ReadonlyArray<string | undefined>) {
316 for (const part of batch) {
317 if (part !== undefined) {
318 this.releaseSource(part)
319 }
320 }
321 }
322β
323 liftBarrier() {
324 if (this.consumer !== 'cleaned' && !this.barrierLifted) {
325 this.barrierLifted = true
326 this.refresh()
327 }
328 }
329β
330 private producerCanWrite() {
331 return (
332 this.consumer !== 'cleaned' &&
333 this.outputState !== HydrationScriptOutputState.Failed &&
334 !this.producerDone
335 )
336 }
337β
338 pushSource(nextSource: string) {
339 if (!this.producerCanWrite()) {
340 return false
341 }
342 if (this.account(nextSource)) {
343 this.queuedSources.push(nextSource)
344 if (this.initialTaken) {
345 this.refresh()
346 }
347 } else {
348 return false
349 }
350 // A notification can synchronously fail or clean up this owner.
351 return this.producerCanWrite()
352 }
353β
354 private takeQueuedBatch(batchLength: number) {
355 if (
356 this.queuedSourceHead === 0 &&
357 batchLength === this.queuedSources.length
358 ) {
359 const batch = this.queuedSources
360 this.clearQueue()
361 return batch
362 }
363 const end = this.queuedSourceHead + batchLength
364 const batch = this.queuedSources.slice(this.queuedSourceHead, end)
365 for (let index = this.queuedSourceHead; index < end; index++) {
366 this.queuedSources[index] = undefined
367 }
368 this.queuedSourceHead = end
369 if (this.queueIsEmpty()) {
370 this.clearQueue()
371 } else if (
372 this.queuedSourceHead >= 1024 &&
373 this.queuedSourceHead >= this.queuedSources.length - this.queuedSourceHead
374 ) {
375 this.queuedSources = this.queuedSources.slice(this.queuedSourceHead)
376 this.queuedSourceHead = 0
377 }
378 return batch
379 }
380β
381 private release(batch: Array<string | undefined>) {
382 this.releaseAccounting(batch)
383 this.active = undefined
384 this.source = ''
385 this.sourceOffset = 0
386 this.refresh(false)
387 }
388β
389 private advanceSource() {
390 const batch = this.active!
391 if (this.segmentIndex > 0 && this.segmentIndex < this.closingSegmentIndex) {
392 const partIndex = (this.segmentIndex - 1) >> 1
393 if (this.segmentIndex % 2 === 1) {
394 const part = batch[partIndex]
395 if (part !== undefined) {
396 this.releaseSource(part)
397 batch[partIndex] = undefined
398 }
399 }
400 }
401 this.segmentIndex++
402 // Segment 0 is the opening tag. Sources and separators alternate until
403 // the closing segment. The next advance releases the complete record.
404 if (this.segmentIndex < this.closingSegmentIndex) {
405 const partIndex = (this.segmentIndex - 1) >> 1
406 this.source =
407 this.segmentIndex % 2 === 1 ? batch[partIndex]! : SOURCE_SEPARATOR
408 } else if (this.segmentIndex === this.closingSegmentIndex) {
409 this.source = DYNAMIC_CLOSE_SOURCE
410 } else {
411 this.release(batch)
412 }
413 this.sourceOffset = 0
414 }
415β
416 private pullActive() {
417 const bytes = new Uint8Array(this.outputCapacity)
418 let offset = 0
419 while (this.active) {
420 if (this.sourceOffset === this.source.length) {
421 this.advanceSource()
422 } else if (offset === bytes.length) {
423 break
424 } else {
425 const result = encodeIntoBoundedChunk(
426 this.source,
427 this.sourceOffset,
428 bytes,
429 offset,
430 )
431 if (result.read === 0) {
432 break
433 }
434 this.sourceOffset += result.read
435 offset += result.written
436 }
437 }
438 if (offset === 0) {
439 throw new Error('SSR router script record produced no output')
440 }
441 if (offset === bytes.length) {
442 return bytes
443 }
444 // A subarray view pins the whole output buffer. Copy mostly-empty tail
445 // chunks (typically the final close-tag remnant) so the large buffer can
446 // be collected immediately.
447 return offset * 2 < bytes.length
448 ? bytes.slice(0, offset)
449 : bytes.subarray(0, offset)
450 }
451β
452 private pullReady() {
453 const scriptOpening = (this.opening ??= this.nonce
454 ? `<script nonce="${escapeAttribute(this.nonce)}">`
455 : '<script>')
456 let codeUnits = scriptOpening.length + DYNAMIC_CLOSE_SOURCE.length
457 let batchLength = 0
458 for (
459 let index = this.queuedSourceHead;
460 index < this.queuedSources.length;
461 index++
462 ) {
463 const part = this.queuedSources[index]!
464 const nextCodeUnits = codeUnits + SOURCE_SEPARATOR.length + part.length
465 if (batchLength > 0 && nextCodeUnits > MAX_DYNAMIC_RECORD_CODE_UNITS) {
466 break
467 }
468 codeUnits = nextCodeUnits
469 batchLength++
470 if (codeUnits > MAX_DYNAMIC_RECORD_CODE_UNITS) {
471 // A complete JavaScript source is not safely splittable across tags.
472 break
473 }
474 }
475 const batch = this.takeQueuedBatch(batchLength)
476 if (codeUnits <= MAX_DIRECT_CODE_UNITS) {
477 const joined =
478 batch.length === 1 ? batch[0]! : batch.join(SOURCE_SEPARATOR)
479 const bytes = encoder.encode(
480 scriptOpening + joined + SOURCE_SEPARATOR + DYNAMIC_CLOSE_SOURCE,
481 )
482 this.release(batch)
483 return bytes
484 }
485 this.active = batch
486 this.segmentIndex = 0
487 this.closingSegmentIndex = (batch.length << 1) + 1
488 this.source = scriptOpening
489 this.sourceOffset = 0
490 this.outputCapacity = Math.max(
491 MIN_OUTPUT_BYTES,
492 Math.min(MAX_HYDRATION_OUTPUT_CHUNK_BYTES, codeUnits),
493 )
494 this.outputState = HydrationScriptOutputState.Active
495 return this.pullActive()
496 }
497β
498 pullChunk() {
499 if (
500 this.outputState !== HydrationScriptOutputState.Ready &&
501 this.outputState !== HydrationScriptOutputState.Active
502 ) {
503 throw new Error('Hydration script output is not ready')
504 }
505 try {
506 return this.outputState === HydrationScriptOutputState.Ready
507 ? this.pullReady()
508 : this.pullActive()
509 } catch (cause) {
510 this.fail(cause)
511 throw cause
512 }
513 }
514β
515 subscribe(onChange: () => void) {
516 if (this.consumer === 'cleaned') {
517 return () => {}
518 }
519 if (this.listener) {
520 throw new Error('SSR hydration output already has a subscriber')
521 }
522 this.listener = onChange
523 return () => {
524 if (this.listener === onChange) {
525 this.listener = undefined
526 }
527 }
528 }
529β
530 pushSerializedSource(data: string, initial: boolean, wrap: boolean) {
531 let serialized = initial ? ROUTER_PREFIX + data : data
532 if (wrap) {
533 serialized = PROMISE_PREFIX + serialized + ')'
534 }
535 return this.pushSource(serialized)
536 }
537β
538 finish() {
539 if (!this.pushSource(GLOBAL_TSR + '.e()')) {
540 return
541 }
542 this.producerDone = true
543 this.clearTimeoutIfSet()
544 this.refresh()
545 }
546β
547 takeInitialHydrationScriptTags() {
548 if (
549 this.consumer === 'cleaned' ||
550 this.outputState === HydrationScriptOutputState.Failed ||
551 this.initialTaken
552 ) {
553 return undefined
554 }
555 // No source can drain before the initial take, so the queue has no
556 // cleared prefix. Once tags are composed, the same empty array can become
557 // the dynamic queue without allocating a replacement.
558 const sources = this.queuedSources as Array<string>
559 const tags = createInitialTags(sources, this.nonce)
560 this.initialTaken = true
561 this.releaseAccounting(sources)
562 sources.length = 0
563 this.queuedSourceHead = 0
564 this.refresh()
565 return tags
566 }
567β
568 /**
569 * Opt this request out of hydration output entirely (for example a
570 * `hydrate: false` page). Drops the queued bootstrap sources, marks the
571 * producer done, and makes the fast pass-through path reservable without
572 * a rendered `<Scripts>` boundary. Must run before the initial take and
573 * before serialization produces output.
574 */
575 disableHydration() {
576 if (
577 this.consumer === 'cleaned' ||
578 this.outputState === HydrationScriptOutputState.Failed
579 ) {
580 return
581 }
582 if (this.initialTaken || this.consumer !== undefined || this.producerDone) {
583 if (process.env.NODE_ENV !== 'production') {
584 throw new Error(
585 'Invariant failed: hydration output is already committed; ' +
586 'disableHydration() must run before <Scripts> renders and ' +
587 'before serialization starts.',
588 )
589 }
590β
591 invariant()
592 }
593 this.releaseAccounting(this.queuedSources)
594 this.clearQueue()
595 this.initialTaken = true
596 this.barrierLifted = true
597 this.producerDone = true
598 this.refresh()
599 }
600β
601 // The rendered boundary can only exist after the initial take. The merger
602 // uses this to skip barrier scanning for all earlier renderer bytes.
603 isInitialTaken() {
604 return this.initialTaken
605 }
606β
607 // Application EOF without a rendered <Scripts> boundary. The initial
608 // sources become late records after the document so the response still
609 // completes instead of failing after its HTML was already delivered.
610 skipInitialTake() {
611 if (this.consumer !== 'cleaned' && !this.initialTaken) {
612 this.initialTaken = true
613 this.refresh()
614 }
615 }
616β
617 claimOutput(): HydrationScriptOutput {
618 if (this.consumer === 'cleaned') {
619 throw new Error('SSR hydration script output is already cleaned up')
620 }
621 if (this.consumer !== undefined) {
622 throw new Error('SSR hydration script output already has a consumer')
623 }
624 this.consumer = this
625 this.refresh(false)
626 return this
627 }
628β
629 reserveFastPath(output?: HydrationScriptOutput) {
630 const ownsConsumer = this.consumer === output
631 if (
632 this.outputState === HydrationScriptOutputState.Failed ||
633 !this.producerDone ||
634 !this.initialTaken ||
635 !this.queueIsEmpty() ||
636 this.active ||
637 !ownsConsumer
638 ) {
639 return false
640 }
641 this.consumer = 'fast-path'
642 return true
643 }
644β
645 // Arms the serialization deadline once the renderer finished. The
646 // lifecycle signal stays separate from this merge-transport concern.
647 startSerializationTimeout(timeoutMs: number) {
648 if (
649 this.consumer === 'cleaned' ||
650 this.outputState === HydrationScriptOutputState.Failed ||
651 this.producerDone ||
652 this.timeout !== undefined
653 ) {
654 return
655 }
656 this.timeout = setTimeout(() => {
657 this.timeout = undefined
658 if (
659 this.consumer !== 'cleaned' &&
660 this.outputState !== HydrationScriptOutputState.Failed &&
661 !this.producerDone
662 ) {
663 console.error('Serialization timeout after app render finished')
664 this.fail(new Error('Serialization timeout after app render finished'))
665 }
666 }, timeoutMs)
667 }
668β
669 cleanup() {
670 if (this.consumer === 'cleaned') {
671 return
672 }
673 this.consumer = 'cleaned'
674 this.clearTimeoutIfSet()
675 this.dropBufferedOutput()
676 this.listener = undefined
677 this.outputError = undefined
678 this.producerDone = true
679 this.outputState = HydrationScriptOutputState.Done
680 }
681}
682β
683/** Create the hydration-script owner for one server request. */
684export function createHydrationScripts(
685 nonce: string | undefined,
686 initialSources?: ReadonlyArray<string>,
687): HydrationScripts {
688 return new HydrationScriptsOwner(nonce, initialSources)
689}