Repository navigation
docs: live demo will silently stop updating when the SSE wire change merges #548
Description
Activity
Fixed before the stack merged — recording it here since this is the original issue and it had no resolution note.
docs/package.jsonnow depends on"@wavehouse/sdk": "^0.1.1"from the registry instead ofworkspace:*(commit8277bf6e, shipped in #554). The caret takes0.1.xpatches and stops short of0.2.0, so merging a wire change can no longer push an unreleased SDK onto the landing page; moving the site onto the new wire is now a deliberate bump lined up with tagging the SDK release.tests/e2e/sdkdeliberately keepsworkspace:*.Verified rather than assumed at the time:
docs/node_modules/@wavehouse/sdkresolves to.pnpm/@wavehouse+sdk@0.1.1, whiletests/e2e/sdkstill symlinksclients/ts.make build-docsclean, so the published API still satisfiesLiveDemo.astro— only the wire changed in that stack, not the SDK surface.- The published 0.1.1 build carries none of the v2 schema-frame handling and still reads
msg.data, which is what the deployed backend sends; the built docs bundle no longer contains theno-schemaguard.
Two things that came out of it and are still live:
- Depending on our own package from the registry newly subjected it to
minimumReleaseAge(7 days), and the exclude list named only@wave-rf/*— the plugin scope.@wavehouse/*is now exempt too, otherwise a freshly tagged SDK would have been uninstallable by the docs site for a week after every release. - Dependabot would have undone the pin: the npm group is
patterns: ["*"], so once0.2.0publishes it would have proposed^0.1.1→^0.2.0in a routine Mondaydeps:PR.@wavehouse/sdkis now in thatignorelist (4c27c547), and the release runbook says so.
The general version of this — that any SDK consumer upgrading ahead of their server hits the same silent stall, with no
errorcallback — is not fixed by pinning our own site. That is #577.(I filed #568 during the stack without searching first; it duplicates this. Closing that one and keeping this as canonical.)
What
Merging the pre-chtypes stack will silently break the homepage live demo, because the docs site bundles the SDK from this repo while the demo streams from a separately deployed server.
docs/package.json:24—"@wavehouse/sdk": "workspace:*", so a docs build ships whatever SDK is in the tree.docs/src/components/LiveDemo.astrostreams fromhttps://iefrrvavd5akvphk7pq3.wavehouse.app.Probed that backend directly:
No
event: schemaframe at connect — so it is still running the pre-stack server. The newSubscribeSchemaFramesends one before the first row.Why it breaks silently
This is exactly the skew the stack's own new warning describes (
docs/src/content/docs/sdk/streaming.md, "Upgrade the SDK and the server together"). A new SDK against an old server never receives a schema frame, so_columnsstays unset and_dispatchdrops every row with aconsole.warnand noerrorcallback.liveQuery()makes it worse to notice: its backfill goes over REST and is unaffected, so the panel renders its initial snapshot, reports statuslive, and then simply never updates. Nothing turns red.Options
"@wavehouse/sdk": "0.1.x"instead ofworkspace:*) until the backend catches up, then unpin. Also removes the general coupling where any unreleased SDK change can affect the marketing site.LiveDemo.astro— surface "no data" when a stream reportslivebut delivers nothing for N seconds, so this class fails visibly rather than silently.(2) is the smallest change and fixes the class, not just this instance; (3) is worth doing regardless.
Scope
Not a defect in the stack's code — it is a deployment-ordering consequence of the SSE wire change, and the stack documents the hazard for users. Found by the docs reviewer while reviewing the stack tip, which noticed the site was advertising a warning it was itself about to trip over.