@advwebrec/grainloading 0.5.1 → 0.5.2

package/README.md

@@ -13,17 +13,81 @@ New TypeScript consumers should use `YuriRTCClient` and `YuriRTCConfig`.
 `LoaderClient` and `LoaderConfig` remain compatibility aliases for existing
 integrations.
 
-The loader implements YuriRTC wire protocol v3. It keeps one interactive
-channel open, opens three asset channels only while needed, uses 128 KiB frames,
-streams Fetch request bodies through transferable streams, and bounds both
-directions with consumption-driven credits. A loader that changes the wire
-version must be published only after a compatible content node is deployed.
+The loader implements YuriRTC wire protocol v3. It negotiates the interactive
+lane first, then establishes all four lanes before the initial application
+waterfall. Lanes 1-3 retire after 15 seconds without asset work and reopen on
+demand. The transport uses 128 KiB frames, streams Fetch request bodies through
+transferable streams, and bounds both directions with consumption-driven
+credits. A loader that changes the wire version must be published only after a
+compatible content node is deployed.
+
+Lane 0 carries navigations, API/mutation traffic, and carried WebSockets. Lane
+1 is reserved for small render-critical scripts, styles, fonts, and documents.
+Normal and incremental assets use lanes 2 and 3 with one active start per lane
+and FIFO admission, so a large game payload cannot occupy every ordered stream
+ahead of bootstrap files. The lanes share one ICE/DTLS/SCTP association and
+congestion window; they separate scheduling and SCTP stream ordering rather
+than creating four network connections.
 
 When a restarted worker discovers several controlled tabs, the first completed
 attachment becomes the carrier and later responders remain live standbys. Wake
 discovery never crosses into pages still controlled by a predecessor worker, so
 an in-place upgrade cannot cancel that older worker's valid transfers.
 
+Without an unexpired session preference, the loader connects ordinary ICE and
+forced TCP in parallel. Once both are ready, each receives the same private,
+incompressible 1 MiB probe. TCP is selected only when it is at least 15 percent
+faster; if only one route connects, that route is used. An older node that does
+not return the exact probe marker safely leaves ordinary ICE selected. The
+result is remembered for ten minutes and cleared after a network change.
+
+On a selected UDP route, the page aggregates response bytes across concurrent
+GETs after the first body frame arrives. If at least 8 MiB over at least four
+seconds remains below 15 Mbit/s, it warms one TCP-only connection without
+detaching UDP. Once TCP is ready, new requests use it while existing HTTP
+requests and carried WebSockets drain on their original route; the predecessor
+is retired only after that drain. A failed warm-up leaves the working UDP route
+untouched. The thresholds can be tuned, or the behavior disabled, without
+changing the wire:
+
+```ts
+transport: {
+  adaptiveTcp: {
+    enabled: true,
+    minBytes: 8 * 1024 * 1024,
+    minSampleMs: 4_000,
+    maxGoodputMbps: 15
+  }
+}
+```
+
+Candidate filtering uses standard SDP and `RTCIceCandidateInit` data and does
+not patch browser APIs, so the baseline and forced-route paths remain usable in
+Chrome, Firefox, and Safari. Browsers that cannot report a selected pair keep
+ordinary ICE behavior and simply skip the optional goodput recommendation.
+
+A self-contained carrier may set `recovery.clientUrls` to durable module URLs.
+The loader persists those ahead of its own `import.meta.url` and the two npm CDN
+fallbacks, allowing service-worker-injected documents to recover from a
+same-origin `client.js` even when the first client was imported from a temporary
+inline Blob.
+
+For eligible complete static GET responses, a capable browser sends
+`x-yurirtc-accept-wire-encoding: gzip`; the node marks compressed transport
+bytes with `x-yurirtc-wire-encoding: gzip`. These are private YuriRTC hop
+headers, not HTTP `Accept-Encoding` or `Content-Encoding`, and the loader strips
+them after decompression. Browsers without `DecompressionStream("gzip")` omit
+the capability. Range, API, SSE, already-compressed media, and `no-transform`
+responses remain unencoded.
+
+The service worker also gives unknown static paths conservative, bounded cache
+reuse instead of assuming EDUrocks-specific names. It sends `If-None-Match`
+and `If-Modified-Since` for stored validator-backed responses, combines a 304
+with the stored body, and can use that body as an offline fallback. It never
+admits authenticated, ranged/partial, event-stream, `no-store`, `private`, or
+`Vary: *` responses; a 404, 410, or newly non-storable answer invalidates an
+older fallback.
+
 The font in `dist/assets/rot13.woff` is derived from Google Sans and is licensed
 under the SIL Open Font License 1.1; its license text is shipped beside it as
 `dist/assets/OFL.txt`.