Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
fe1e3c6
fix(zero-react): release views whose render never commits
typedrat Nov 6, 2026
cab9677
feat(zero-react): hand query results from server render to hydration
typedrat Nov 6, 2026
d27b082
feat(zero-react): make server-rendered pages complete for crawlers
typedrat Nov 6, 2026
102d8eb
feat(zero-react): let a user's own writes end the seed hold
typedrat Nov 6, 2026
1593cfe
feat(zero-react): fail a server render when the connection is lost
typedrat Nov 6, 2026
30cc168
docs(zero-react): note that snapshots need matching context on both s…
typedrat Nov 6, 2026
78c612c
feat(zero-react): choose what live queries render when disconnected
typedrat Nov 6, 2026
b8fc38c
feat(zero-cache): place connections with the same affinity key together
typedrat Nov 6, 2026
536309f
feat(zero-cache): measure whether hydrations could be copied between …
typedrat Nov 6, 2026
6990ff0
test(zero-cache): check that pipeline rows do not depend on history
typedrat Nov 6, 2026
c978867
feat(zero-cache): copy hydrations from other client groups on the worker
typedrat Nov 6, 2026
57bdbfc
feat(zero-cache): copy hydrations of queries with scalar subqueries
typedrat Nov 7, 2026
96cc131
feat(zero-react): warn when a query hydrates without a server snapshot
typedrat Nov 9, 2026
411ff9d
perf(zero-cache): copy operator state in bulk
typedrat Nov 9, 2026
1133f4b
feat(zero-cache): copy hydrations of queries with aggregates
typedrat Nov 9, 2026
fc3731c
feat(zero-cache): key donors by the row keys of the tables a query reads
typedrat Nov 9, 2026
b5abbad
feat(zero-cache): wait briefly for a donor that is about to be ready
typedrat Nov 9, 2026
13cb7f5
feat(zero-cache): wait for a hydration of the same query in progress
typedrat Nov 9, 2026
d98dede
feat(zero-cache): keep a key's overflow on workers that already have it
typedrat Nov 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions packages/zero-cache/src/config/zero-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -683,6 +683,22 @@ export const zeroOptions = {
],
},

hydrationClone: {
type: v.literalUnion('off', 'shadow', 'on').optional(() => 'off'),
desc: [
`Whether a client group can take a query's hydration from another group on`,
`its sync worker that already has that query live at the same version.`,
``,
`{bold shadow} still hydrates, and compares the result with what could have`,
`been copied. {bold on} copies when it can. The outcomes are reported in the`,
`{bold sync.hydration-clone} metric.`,
``,
`Both read the operator state of the pipelines involved, holding up the worker`,
`for large queries.`,
],
hidden: true,
},

deferIvmWrites: {
type: v.boolean().optional(() => true),
desc: [
Expand Down
1 change: 1 addition & 0 deletions packages/zero-cache/src/server/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,7 @@ export default async function runWorker(
syncers,
mutator,
changeStreamer,
config.hydrationClone !== 'off',
),
);
} catch (err) {
Expand Down
178 changes: 178 additions & 0 deletions packages/zero-cache/src/server/syncer-assigner.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
import {describe, expect, test} from 'vitest';
import {SyncerAssigner} from './syncer-assigner.ts';

function fill(assigner: SyncerAssigner, prefix: string, count: number) {
for (let i = 0; i < count; i++) {
assigner.assign(`${prefix}${i}`);
}
}

describe('SyncerAssigner affinity', () => {
test('sends groups with the same key to the same worker', () => {
const assigner = new SyncerAssigner('task', 8);
const {worker} = assigner.assign('server', 'alice');
expect(assigner.assign('browser', 'alice').worker).toBe(worker);
expect(assigner.assign('phone', 'alice').worker).toBe(worker);
});

test('still balances groups without a key or with other keys', () => {
const assigner = new SyncerAssigner('task', 2);
const a = assigner.assign('a', 'alice').worker;
const b = assigner.assign('b', 'bob').worker;
const c = assigner.assign('c').worker;
expect(b).not.toBe(a);
expect(
[assigner.getWorkerLoad(0), assigner.getWorkerLoad(1)].sort(),
).toEqual([1, 2]);
expect(c === a || c === b).toBe(true);
});

test('ignores affinity once the worker is too far above the least loaded', () => {
const assigner = new SyncerAssigner('task', 2);
const {worker} = assigner.assign('first', 'popular');
const other = 1 - worker;

const placed: number[] = [];
for (let i = 0; i < 20; i++) {
placed.push(assigner.assign(`g${i}`, 'popular').worker);
}
expect(placed).toContain(other);
expect(
Math.abs(assigner.getWorkerLoad(0) - assigner.getWorkerLoad(1)),
).toBeLessThanOrEqual(5);
});

test('allows proportionally more skew on busy workers', () => {
const assigner = new SyncerAssigner('task', 2);
fill(assigner, 'background', 200);
expect(assigner.getWorkerLoad(0)).toBe(100);

const {worker} = assigner.assign('first', 'popular');
let stayed = 0;
for (let i = 0; i < 10; i++) {
if (assigner.assign(`g${i}`, 'popular').worker === worker) {
stayed++;
}
}
expect(stayed).toBe(10);
});

test('a reconnecting group keeps its worker whatever its key', () => {
const assigner = new SyncerAssigner('task', 4);
const {worker} = assigner.assign('group', 'alice');
assigner.assign('other', 'bob');
expect(assigner.assign('group', 'bob').worker).toBe(worker);
expect(assigner.assign('group').worker).toBe(worker);
});

test('forgets a key once its last group on that worker is released', () => {
const assigner = new SyncerAssigner('task', 2);
const {worker} = assigner.assign('server', 'alice');
assigner.assign('browser', 'alice');
assigner.release('server', worker);
fill(assigner, 'load', 1);

// The browser group still anchors the key.
expect(assigner.assign('phone', 'alice').worker).toBe(worker);

assigner.release('browser', worker);
assigner.release('phone', worker);
fill(assigner, 'more', 4);
const least =
assigner.getWorkerLoad(0) <= assigner.getWorkerLoad(1) ? 0 : 1;
expect(assigner.assign('new', 'alice').worker).toBe(least);
});

test('releasing an overflow group does not release the anchor', () => {
const assigner = new SyncerAssigner('task', 2);
const {worker} = assigner.assign('first', 'popular');
const onAnchor: string[] = [];
const overflow: string[] = [];
for (let i = 0; overflow.length === 0 && i < 50; i++) {
const placed = assigner.assign(`g${i}`, 'popular').worker;
(placed === worker ? onAnchor : overflow).push(`g${i}`);
}
expect(overflow).toHaveLength(1);

for (const group of onAnchor) {
assigner.release(group, worker);
}
assigner.release(overflow[0], 1 - worker);

// Only 'first' still holds the anchor, and the other worker is emptier.
expect(assigner.getWorkerLoad(worker)).toBe(1);
expect(assigner.getWorkerLoad(1 - worker)).toBe(0);
expect(assigner.assign('after', 'popular').worker).toBe(worker);
});

/** Places groups for `key` until one lands off `worker`, and returns where. */
function overflow(assigner: SyncerAssigner, key: string, worker: number) {
for (let i = 0; i < 50; i++) {
const placed = assigner.assign(`${key}-${i}`, key).worker;
if (placed !== worker) {
return placed;
}
}
throw new Error('never overflowed');
}

test('sends overflow to a worker that already has the key', () => {
const assigner = new SyncerAssigner('task', 3);
const {worker} = assigner.assign('first', 'popular');
const second = overflow(assigner, 'popular', worker);
// A worker that has none of the key is emptier, but has nothing to share.
expect(assigner.assign('next', 'popular').worker).toBe(second);
});

test('prefers the least loaded of the workers that have the key', () => {
const assigner = new SyncerAssigner('task', 3);
const {worker} = assigner.assign('first', 'popular');
const second = overflow(assigner, 'popular', worker);
const third = 3 - worker - second;
assigner.assign('other', 'other');
expect(assigner.getWorkerLoad(third)).toBe(1);
// Both workers with the key are within the skew, and the second is emptier.
expect(assigner.assign('next', 'popular').worker).toBe(second);
});

test('spreads a key over as few workers as the skew allows', () => {
const assigner = new SyncerAssigner('task', 4);
const workers = new Set<number>();
for (let i = 0; i < 17; i++) {
workers.add(assigner.assign(`g${i}`, 'popular').worker);
}
expect(workers.size).toBe(4);
const loads = [0, 1, 2, 3].map(w => assigner.getWorkerLoad(w));
// Each worker the key reaches fills to the skew before the next is used.
expect(loads.toSorted((a, b) => b - a)).toEqual([5, 5, 5, 2]);
});

test('forgets a worker for a key once its last group there is released', () => {
const assigner = new SyncerAssigner('task', 3);
const {worker} = assigner.assign('first', 'popular');
const second = overflow(assigner, 'popular', worker);
const overflowed = `popular-${assigner.getWorkerLoad(worker) - 1}`;
assigner.release(overflowed, second);
expect(assigner.getWorkerLoad(second)).toBe(0);
// The two empty workers are tied, so either may be picked: only the
// anchor's worker is ruled out.
expect(assigner.assign('next', 'popular').worker).not.toBe(worker);
});

test('destroy forgets every key', () => {
const assigner = new SyncerAssigner('task', 2);
const {worker} = assigner.assign('a', 'alice');
assigner.destroy();

// A load only the other worker can relieve shows the key no longer applies.
const other = 1 - worker;
const placed = assigner.assign('b').worker;
if (placed === worker) {
expect(assigner.assign('c', 'alice').worker).toBe(other);
} else {
assigner.assign('c');
expect(assigner.getWorkerLoad(other)).toBeGreaterThan(0);
expect(assigner.assign('d', 'alice').worker).toBe(worker);
}
});
});
64 changes: 60 additions & 4 deletions packages/zero-cache/src/server/syncer-assigner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,25 @@ import {h32} from '../../../shared/src/hash.ts';
export type Assignment = {
readonly worker: number;
readonly generation: number;
/** The affinity key whose groups this one shares its worker with, if any. */
readonly affinityKey?: string | undefined;
};

/**
* How many more groups than the least loaded worker a worker can hold and still
* take a group for affinity. It grows with load so that it stays small next to
* what a worker is already doing.
*/
function maxAffinitySkew(minLoad: number): number {
return Math.max(4, Math.ceil(minLoad / 4));
}

export class SyncerAssigner {
readonly #taskID: string;
readonly #numWorkers: number;
readonly #assignments = new Map<string, Assignment>();
/** For each affinity key, the workers with groups for it, and how many. */
readonly #keyWorkers = new Map<string, Map<number, number>>();
readonly #workerLoads: number[];
#nextGeneration = 0;

Expand All @@ -18,15 +31,23 @@ export class SyncerAssigner {
this.#workerLoads = new Array<number>(numWorkers).fill(0);
}

assign(clientGroupID: string): Assignment {
/**
* Places a client group on a worker. Groups with the same `affinityKey` share
* a worker where load allows, because only groups on one worker can reuse each
* other's work. Affinity never overrides balance by more than
* {@link maxAffinitySkew}. Past that, a group goes to the least loaded of the
* other workers that have the key, and only when none can take it to a new
* one, so that the key spreads over as few workers as possible.
*/
assign(clientGroupID: string, affinityKey?: string): Assignment {
if (this.#numWorkers <= 0) {
return {worker: 0, generation: 0};
}

const generation = ++this.#nextGeneration;
const existing = this.#assignments.get(clientGroupID);
if (existing !== undefined) {
const updated: Assignment = {worker: existing.worker, generation};
const updated: Assignment = {...existing, generation};
this.#assignments.set(clientGroupID, updated);
return updated;
}
Expand All @@ -45,13 +66,35 @@ export class SyncerAssigner {
}
}

const chosen =
const leastLoaded =
tied.length === 1
? tied[0]
: tied[h32(this.#taskID + '/' + clientGroupID) % tied.length];

let chosen = leastLoaded;
if (affinityKey !== undefined) {
let workers = this.#keyWorkers.get(affinityKey);
const maxLoad = minLoad + maxAffinitySkew(minLoad);
let best: number | undefined;
for (const worker of workers?.keys() ?? []) {
const load = this.#workerLoads[worker];
if (
load <= maxLoad &&
(best === undefined || load < this.#workerLoads[best])
) {
best = worker;
}
}
chosen = best ?? leastLoaded;
if (!workers) {
workers = new Map();
this.#keyWorkers.set(affinityKey, workers);
}
workers.set(chosen, (workers.get(chosen) ?? 0) + 1);
}

this.#workerLoads[chosen]++;
const assignment: Assignment = {worker: chosen, generation};
const assignment: Assignment = {worker: chosen, generation, affinityKey};
this.#assignments.set(clientGroupID, assignment);
return assignment;
}
Expand All @@ -70,6 +113,18 @@ export class SyncerAssigner {
}
this.#decrementLoad(workerIndex);
this.#assignments.delete(clientGroupID);
if (existing.affinityKey !== undefined) {
const workers = this.#keyWorkers.get(existing.affinityKey);
const groups = (workers?.get(workerIndex) ?? 0) - 1;
if (groups > 0) {
workers?.set(workerIndex, groups);
} else {
workers?.delete(workerIndex);
if (workers?.size === 0) {
this.#keyWorkers.delete(existing.affinityKey);
}
}
}
}

getWorkerLoad(workerIndex: number): number {
Expand All @@ -88,6 +143,7 @@ export class SyncerAssigner {

destroy(): void {
this.#assignments.clear();
this.#keyWorkers.clear();
this.#workerLoads.fill(0);
}
}
9 changes: 9 additions & 0 deletions packages/zero-cache/src/server/syncer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ import {
} from '../services/view-syncer/connection-context-manager.ts';
import {DeferredWritesBudget} from '../services/view-syncer/deferred-writes-budget.ts';
import type {DrainCoordinator} from '../services/view-syncer/drain-coordinator.ts';
import {PipelineDonors} from '../services/view-syncer/pipeline-donors.ts';
import {PipelineDriver} from '../services/view-syncer/pipeline-driver.ts';
import {QueryStats} from '../services/view-syncer/query-stats.ts';
import {SnapshotRowCache} from '../services/view-syncer/snapshot-row-cache.ts';
Expand Down Expand Up @@ -264,6 +265,13 @@ export default async function runWorker(
}).addCallback(o => o.observe(batchPacer.multiplier));
}

// Shared by all of the view-syncers on this worker, because pipelines can only
// be taken from other client groups in the same process.
const donors =
config.hydrationClone === 'off'
? undefined
: new PipelineDonors({lc, copy: config.hydrationClone === 'on'});

// Shared by all of the view-syncers on this worker, so that the work done
// for each query shape is logged once per worker per interval.
const queryStats =
Expand Down Expand Up @@ -342,6 +350,7 @@ export default async function runWorker(
config,
deferredWritesBudget,
queryStats,
donors,
),
sub,
drainCoordinator,
Expand Down
10 changes: 8 additions & 2 deletions packages/zero-cache/src/server/worker-dispatcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ export class WorkerDispatcher implements Service {
syncers: Worker[],
mutator: Worker | undefined,
changeStreamer: Worker | undefined,
// Groups only reuse each other's work when hydrations can be copied.
// Otherwise placing them together costs balance and gains nothing.
placeByAffinity = false,
) {
this.#lc = lc;

Expand Down Expand Up @@ -100,10 +103,13 @@ export class WorkerDispatcher implements Service {
const handleSync = (req: IncomingMessageSubset) => {
assert(syncers.length, 'Received a sync request with no sync workers.');
const params = connectParams(req);
const {clientGroupID, protocolVersion} = params;
const {clientGroupID, protocolVersion, affinityKey} = params;
maxProtocolVersion = Math.max(maxProtocolVersion, protocolVersion);

const {worker: syncer, generation} = assigner.assign(clientGroupID);
const {worker: syncer, generation} = assigner.assign(
clientGroupID,
placeByAffinity ? affinityKey : undefined,
);
workerDispatchesCounter.add(1, {worker: String(syncer)});

lc.debug?.(
Expand Down
5 changes: 5 additions & 0 deletions packages/zero-cache/src/services/view-syncer/cvr-store.ts
Original file line number Diff line number Diff line change
Expand Up @@ -582,6 +582,11 @@ export class CVRStore {
return this.#rowCache.getRowRecords();
}

/** The row records, for a caller that can't wait for them to be loaded. */
loadedRowRecords(): ReadonlyMap<RowID, RowRecord> | undefined {
return this.#rowCache.loadedRowRecords();
}

putRowRecord(row: RowRecord): void {
this.#pendingRowRecordUpdates.set(row.id, row);
}
Expand Down
Loading