Repository navigation
Conversation
typedrat
force-pushed
the
typedrat/ssr
branch
2 times, most recently
from
November 9, 2026 04:36
43264f1 to
d2fd85d
Compare
useQuery materializes its view during render but only learned React was done with it from an unsubscribe. A render that never subscribes (one React discards, or any server render) therefore held its query forever. Give a view with no subscribers a lease, renewed on each render, that destroys it when it lapses. A view a suspended render is waiting on outlives the lease, since destroying it would strand that render on a promise nothing settles. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
useSyncExternalStore needs the snapshot the server rendered, and useQuery had no way to provide it, so hydrating a server-rendered page failed and showed empty lists until the client caught up. QuerySnapshotProvider collects rendered results by query hash on the server and seeds them on the client. Passing the server snapshot alone is not enough: React re-reads the client snapshot straight after hydrating, and that view is still empty. A seeded view therefore keeps showing its seed until the server confirms the query or the connection is lost. 'cached' does not end the hold, because rows from local storage can be older than what the server just rendered. Optimistic writes made during the hold stay hidden until it ends. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
A server render is all a crawler sees, but useQuery did not wait on the server at all and useSuspenseQuery defaulted to accepting partial rows, so a crawler could index an empty or partial page with nothing to indicate it. While collecting, every query now suspends until the server confirms it. Losing the connection also replaced the seed with whatever the local view held. For a client that never connected, such as a crawler that runs JS but has no WebSocket, that view is empty, which blanked the page. The seed now only gives way to rows the client actually has. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
A hydrated view held back all local results until the server confirmed the query, so with a slow or stuck connection a user's edit appeared to do nothing. A client with 'cached' rows has a whole result to show, so its write now ends the hold. A client without them keeps the seed until the server confirms: its local store may hold little more than the write itself, and showing that would replace the page. For the same reason, losing the connection now only gives way to 'cached' rows, not to any rows at all. Adds Zero.hasPendingMutations. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
A collecting render waits for the server, and that wait had no end once the connection could not answer. An expired token reached needs-auth within milliseconds, but the render stayed suspended until the caller gave up on it. Rejecting at once lets the server respond with an error or fall back to client rendering straight away. A reconnect attempt does not fail the render, and a query that is already live still renders from what it holds. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
A long-lived server instance keeps its views when it loses the connection, so a server render could keep showing rows marked complete after zero-cache went away or the user's token was rejected. Those rows may be old, and may include ones the user can no longer see. QuerySnapshotCollector now takes whenDisconnected. 'fail', the default, waits through a reconnect and fails the render once the connection is lost. 'serve' renders what the view holds, for data that is safe to show after access to it has been revoked. It is per render, so an app can choose it by route. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
A server-side render and the browser it renders for are separate client groups, and were placed with no regard for each other, so two connections that want the same queries usually landed in different sync workers. Only connections in one worker can reuse each other's work. Connections now carry an affinityKey, which defaults to the userID and can be set with a new ZeroOptions.affinityKey, for logged-out clients for example. The key is sent on the URL so a load balancer can route on it, and SyncerAssigner prefers the worker already serving a key unless that worker is too far above the least loaded one. The key only affects placement, so it is not validated. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
…groups Every client group hydrates a query from scratch, even when another group on the worker already has the same pipeline live. Before copying that state, we need to know it would be sound: a donor can reach a version by advancing, which need not leave the same state as hydrating. With enableCloneShadow, off by default, each hydration is compared with a donor that has the same (clientSchemaKey, transformationHash) at the same version, by row set and operator state, and the outcome goes to the sync.clone-shadow metric. Hydration itself is unchanged. Entries only the donor holds are reported on their own: advancing leaves Cap state behind for rows the pipeline has touched, which a hydration would not create, and a copy takes after the donor. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
Client groups can be served by pipelines with any history, and hydration state may later be copied between them, so a long-lived pipeline has to deliver what a fresh hydration would. This drives seeded random writes through one and compares it with a fresh hydration at every version. The child rows of an EXISTS are the exception. Cap keeps a few as proof that the parent qualifies, and which ones depends on arrival order, so they are checked for validity instead. ZERO_TEST_HISTORY_SEEDS and ZERO_TEST_HISTORY_STEPS raise the volume. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
Each client group hydrates a query from scratch, even when another group on the worker has the same query live, and for a query that reads much more than it returns that is nearly all of its time to sync. With hydrationClone set to on, a new pipeline takes its operator state and join indexes from a donor with the same (clientSchemaKey, transformationHash) at the same version, and streams the donor's rows as a hydration would, so the view syncer and CVR treat it like any other. It falls back to hydrating when there is no such donor, or for queries with aggregates or scalar subqueries. The rows come from the donor's CVR row records, which its view-syncer already holds with a reference count per query. They are only used while the donor's lock is free, when its CVR has caught up with its pipelines, and only if they account for the pipeline's row-set signature. State and rows come from one pipeline because a hydration can pick different proof rows for an EXISTS, and those rows and the Cap state tracking them have to agree. This saves little for a query that returns most of what it reads, since those rows still have to be read one by one and written to the new group's CVR. Replaces enableCloneShadow with hydrationClone: off, shadow or on, and moves the parent index getter out of test-only naming so each join can report its index. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
Scalar subqueries were left out of copying because their pipelines fetch while being built, to resolve the value. They can be copied like the rest: their operator state and rows are already part of what a donor provides, so what remained was reporting their join indexes and replacing what the fetch wrote. The transformation hash is of the query before scalars are resolved, so a donor now also has to match the resolved query. That guards every copy, since a wrong copy is silent and hydrating is always correct. Queries with aggregates still hydrate. Part of https://bugs.rocicorp.dev/p/zero/issue/3491.
React only reports that the HTML didn't match. The warning names the query and says whether the server rendered it with other args, with the same args (so the context differs), or not at all. Snapshots now carry a named query's name and args for this. Hydrating with no snapshots at all warns once.
Copying went through the Storage interface, which sorts every key on a scan and sizes every value on a set. DatabaseStorage now copies an operator in one step: in memory it shares the values, which are never mutated, and in SQLite it copies the rows without parsing them. 100,000 entries took 28-34 ms in memory and 205-225 ms in SQLite, and now take 6-9 ms and 47-49 ms. The copy still blocks the worker, which at that rate is shorter than yielding would be worth.
Aggregate state is already in operator storage, except GroupBy's flag for whether it has been fetched, which moves there. A copy takes the donor's synthetic aggregate rows, which aren't in the replica, and stamps them again so that this driver's later stamps of them are higher. Their tables are named after the query ID, so the donor must have the same one.
The client schema only changes a pipeline through the primary keys its rows are keyed by: the columns come from the replica. Keying donors by the whole schema kept clients apart that differ only in tables the query never reads, as two app versions usually do during a deploy. The tables include those behind scalar subqueries, whose rows are synced too.
A donor that is advancing, or whose CVR rows are being loaded or written, is usually ready within a few turns of the worker. The hydration yields until it is, for at most half of what the donor's hydration took and never more than 250 ms, then hydrates. A copy passes on the time of the hydration it replaced. Donors are now matched against the query before anything waits for them. A wait that ends without a copy only adds to the hydration, so the time spent waiting is logged and counted in sync.hydration-clone-wait-ms, separately for waits that copied and waits that didn't.
Groups that connect together, such as several browsers for one user, all found no donor and hydrated the same query side by side, sharing the worker. A hydration now offers itself while it runs, and a group that starts the same query at the same version waits for it and copies it. It started first and would share the worker, so waiting takes no longer than hydrating would. Only a hydration that has stopped waiting offers itself, so none waits for itself or in a cycle. A hydration that stops making progress for 5 s, as one whose view-syncer stopped without ending it would, is no longer waited for, and destroying a driver stops offering its hydration.
Past the affinity skew, a group went to the least loaded worker, whether or not it had any of the key's groups, so each overflow could land somewhere new with nothing to copy from. It now goes to the least loaded worker that has the key and can take it, and only to a new one when none can. With hydrationClone off nothing can be copied, so affinity keys are ignored and groups are placed for balance alone.
typedrat
force-pushed
the
typedrat/ssr
branch
from
November 17, 2026 01:08
34bb34c to
d98dede
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
SSR for Zero, for issue 3491. I'm not at Rocicorp and can't run your private zero-cache tests, so none of this has run against them. It's a draft to show the approach working, and I don't expect it to merge as is.
The demo is synapdeck/zero-ssr-demo. It builds Zero from this branch, then
pnpm bench --verifyruns Postgres, zero-cache and Chromium and compareshydrationCloneoff and on.Client, in the first 8 commits:
useQueryleaking a query when a render never commits. This affects browsers today and stands alone.QuerySnapshotCollectorandQuerySnapshotProvider: the server render waits for queries to be complete and serializes them, and hydration seedsuseQueryfrom them, so there's no empty flash.zero-cache, in the last 11:
affinityKey, which puts a user's connections on one sync worker, and which a load balancer can hash on. When a key outgrows a worker, its overflow stays on workers that already have it. It's ignored whenhydrationCloneis off.hydrationClone, hidden andoffby default.oncopies a hydration from another group on the same worker, insidePipelineDriver.addQuery, when the query and the row keys of the tables it reads match at the same version. Anything that doesn't match hydrates normally.shadowhydrates and compares the result with what it could have copied.On 500,000 issues with 4 sync workers, a query that reads ~100,000 rows to return 5 hydrated in 760 ms → 7 ms, and the browser was live in 885 ms → 108 ms. A count that reads as many rows went from 741 ms to 9 ms. With 16 browsers for one user opening at once, 13 of 16 copied and all were live in about 1.1 s instead of 3.5–4.8 s. Queries that return what they read don't get faster.
Tests: zero-client 784, zero-react 160, the new zero-cache tests 419 and zqlite 15, including a fuzz test (
pipeline-history.test.ts) comparing long-lived and copied pipelines with fresh ones, aggregates included. The demo also compares clones with donors and fresh groups against real CVR data, with writes running: 225 copies, 0 differences across 75,195cvr.rowsentries.Known gaps: multiple nodes are untested beyond routing on
affinityKeywith Envoy, and a group a version behind or ahead of every donor hydrates normally.