Skip to content

feat: server rendering with hydration, and copying hydrations between client groups - #6742

Draft
typedrat wants to merge 19 commits into
rocicorp:mainfrom
synapdeck:typedrat/ssr
Draft

typedrat wants to merge 19 commits into
rocicorp:mainfrom
synapdeck:typedrat/ssr

Conversation

@typedrat

@typedrat typedrat commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

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 --verify runs Postgres, zero-cache and Chromium and compares hydrationClone off and on.

Client, in the first 8 commits:

  • A fix for useQuery leaking a query when a render never commits. This affects browsers today and stands alone.
  • QuerySnapshotCollector and QuerySnapshotProvider: the server render waits for queries to be complete and serializes them, and hydration seeds useQuery from them, so there's no empty flash.
  • Warnings when a query hydrates without a server snapshot, naming the query and whether the server rendered it with other args, the same args (so the context differs), or not at all.

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 when hydrationClone is off.
  • hydrationClone, hidden and off by default. on copies a hydration from another group on the same worker, inside PipelineDriver.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. shadow hydrates and compares the result with what it could have copied.
  • Queries with scalar subqueries and aggregates are copied too.
  • A hydration waits for a donor that is about to be ready: one hydrating the same query (no limit while it makes progress, since it started first), or one advancing or writing its CVR rows (at most half its hydration time, capped at 250 ms).
  • Operator state is copied in bulk: about 6 ms per 100,000 entries in memory.

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,195 cvr.rows entries.

Known gaps: multiple nodes are untested beyond routing on affinityKey with Envoy, and a group a version behind or ahead of every donor hydrates normally.

@typedrat
typedrat force-pushed the typedrat/ssr branch 2 times, most recently from 43264f1 to d2fd85d Compare November 9, 2026 04:36
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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant