@syncular/server 0.95.0 → 0.97.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +6 -5
  2. package/dist/context.d.ts +4 -16
  3. package/dist/context.js +0 -3
  4. package/dist/d1-storage.js +1 -1
  5. package/dist/errors.d.ts +11 -0
  6. package/dist/errors.js +36 -0
  7. package/dist/frame-bytes.js +1 -0
  8. package/dist/handler.d.ts +20 -2
  9. package/dist/handler.js +199 -59
  10. package/dist/postgres-storage.d.ts +3 -2
  11. package/dist/postgres-storage.js +18 -2
  12. package/dist/pull.d.ts +2 -2
  13. package/dist/pull.js +22 -16
  14. package/dist/push.js +41 -77
  15. package/dist/realtime.d.ts +5 -11
  16. package/dist/realtime.js +10 -23
  17. package/dist/relational-rows.d.ts +23 -13
  18. package/dist/relational-rows.js +49 -30
  19. package/dist/schema-window.js +2 -2
  20. package/dist/schema.d.ts +2 -2
  21. package/dist/schema.js +2 -2
  22. package/dist/segment-download.js +11 -4
  23. package/dist/sqlite-dialect.d.ts +3 -1
  24. package/dist/sqlite-dialect.js +37 -6
  25. package/dist/storage-query.d.ts +5 -2
  26. package/dist/storage-query.js +7 -4
  27. package/dist/storage.d.ts +12 -0
  28. package/dist/validate.d.ts +21 -39
  29. package/dist/validate.js +4 -3
  30. package/package.json +2 -2
  31. package/src/context.ts +4 -23
  32. package/src/d1-storage.ts +0 -1
  33. package/src/errors.ts +46 -0
  34. package/src/frame-bytes.ts +1 -0
  35. package/src/handler.ts +257 -73
  36. package/src/postgres-storage.ts +32 -6
  37. package/src/pull.ts +50 -35
  38. package/src/push.ts +51 -129
  39. package/src/realtime.ts +10 -22
  40. package/src/relational-rows.ts +51 -30
  41. package/src/schema-window.ts +2 -2
  42. package/src/schema.ts +4 -4
  43. package/src/segment-download.ts +19 -12
  44. package/src/sqlite-dialect.ts +47 -7
  45. package/src/storage-query.ts +7 -4
  46. package/src/storage.ts +13 -0
  47. package/src/validate.ts +21 -48
@@ -94,6 +94,11 @@ CREATE TABLE IF NOT EXISTS sync_partition_registry(
94
94
  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,
95
95
  last_authenticated_at_ms BIGINT NOT NULL
96
96
  );
97
+ CREATE TABLE IF NOT EXISTS sync_table_horizons(
98
+ partition TEXT NOT NULL, tbl TEXT NOT NULL,
99
+ commit_seq BIGINT NOT NULL,
100
+ PRIMARY KEY(partition, tbl)
101
+ );
97
102
  CREATE TABLE IF NOT EXISTS sync_row_scopes(
98
103
  partition TEXT NOT NULL, tbl TEXT NOT NULL,
99
104
  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
@@ -1930,6 +1935,14 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1930
1935
  const { rows } = await this.#exec.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
1931
1936
  return rows[0] === undefined ? 0 : asNumber(rows[0].horizon_seq);
1932
1937
  }
1938
+ async getHorizons(partition) {
1939
+ const { rows } = await this.#exec.query(`SELECT coalesce((SELECT horizon_seq FROM sync_partitions WHERE partition=$1),0) AS seq,
1940
+ coalesce((SELECT jsonb_object_agg(tbl, commit_seq) FROM sync_table_horizons WHERE partition=$1),'{}')::text AS tables`, [partition]);
1941
+ return {
1942
+ seq: asNumber(rows[0]?.seq),
1943
+ tables: new Map(Object.entries(asJson(rows[0]?.tables ?? '{}'))),
1944
+ };
1945
+ }
1933
1946
  async setHorizonSeq(partition, seq) {
1934
1947
  await this.#exec.query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES ($1,$2)
1935
1948
  ON CONFLICT (partition) DO UPDATE SET horizon_seq=GREATEST(sync_partitions.horizon_seq,EXCLUDED.horizon_seq)`, [partition, seq]);
@@ -1956,8 +1969,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1956
1969
  WHERE s.partition=$1 AND s.tbl=k.tbl AND s.var=k.key
1957
1970
  AND s.value=k.value AND s.commit_seq=k.commit_seq`, [partition, horizonSeq]);
1958
1971
  await client.query('DELETE FROM sync_changes WHERE partition=$1 AND commit_seq<=$2', [partition, horizonSeq]);
1959
- // §4.6: tombstones prune in the same pass as the commit log.
1960
- await client.query('DELETE FROM sync_tombstones WHERE partition=$1 AND commit_seq<=$2', [partition, horizonSeq]);
1972
+ // §4.6: tombstones and table horizons prune in the same pass as the
1973
+ // commit log.
1974
+ for (const table of ['sync_tombstones', 'sync_table_horizons']) {
1975
+ await client.query(`DELETE FROM ${table} WHERE partition=$1 AND commit_seq<=$2`, [partition, horizonSeq]);
1976
+ }
1961
1977
  return {
1962
1978
  previousHorizonSeq,
1963
1979
  horizonSeq,
package/dist/pull.d.ts CHANGED
@@ -7,7 +7,7 @@ import type { PullSegmentSummary } from './events.js';
7
7
  import { type CompiledSchema, type CompiledTable } from './schema.js';
8
8
  import { type ResolvedScopes } from './scopes.js';
9
9
  import type { SegmentRecord } from './segment-store.js';
10
- import type { StoredCommit, StoredRow } from './storage.js';
10
+ import type { PartitionHorizons, StoredCommit, StoredRow } from './storage.js';
11
11
  /** §4.2 accept bitmask. */
12
12
  export declare const ACCEPT_INLINE_ROWS: number;
13
13
  export declare const ACCEPT_EXTERNAL_ROWS: number;
@@ -99,7 +99,7 @@ export interface BootstrapPlan {
99
99
  * is awaited, so a storage that batches concurrent page reads (PostgreSQL,
100
100
  * D1) answers them in one statement per table.
101
101
  */
102
- export declare function planBootstrap(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, unit: UnitPlan, bootstrapState: string | undefined, maxSeq: number, horizonSeq: number, logEpoch: string, keptCursor?: number): BootstrapPlan;
102
+ export declare function planBootstrap(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, unit: UnitPlan, bootstrapState: string | undefined, maxSeq: number, horizon: PartitionHorizons, logEpoch: string, keptCursor?: number): BootstrapPlan;
103
103
  /**
104
104
  * The segments of one bootstrap section (§4.7): tables in bootstrap order,
105
105
  * each active pair's rows or image, up to `maxSnapshotPages` pages. Returns
package/dist/pull.js CHANGED
@@ -3,7 +3,7 @@
3
3
  */
4
4
  import { encodeRowsSegment, unitId, } from '@syncular/core';
5
5
  import { clockOf, limitsOf } from './context.js';
6
- import { syncError } from './errors.js';
6
+ import { segmentStoreFailure, syncError } from './errors.js';
7
7
  import { compileSchema, } from './schema.js';
8
8
  import { computeEffective, scopeDigest } from './scopes.js';
9
9
  import { issueSegmentUrl } from './signed-url.js';
@@ -237,7 +237,8 @@ function sqliteLaneEligible(limits, table, startRowCursor, imageLane) {
237
237
  async function findImage(ctx, schema, limits, pair, scopePin, rowCursor, probe, logEpoch) {
238
238
  if (probe.length <= limits.limitSnapshotRows)
239
239
  return undefined;
240
- const stored = await ctx.segments.find({
240
+ const stored = await ctx.segments
241
+ .find({
241
242
  partition: ctx.partition,
242
243
  logEpoch,
243
244
  table: pair.table.name,
@@ -246,7 +247,8 @@ async function findImage(ctx, schema, limits, pair, scopePin, rowCursor, probe,
246
247
  scopeDigest: await scopeDigest(pair.effective),
247
248
  asOfCommitSeq: scopePin,
248
249
  rowCursor,
249
- }, clockOf(ctx)());
250
+ }, clockOf(ctx)())
251
+ .catch(segmentStoreFailure(ctx.onError, 'sync', 'find'));
250
252
  return stored !== undefined &&
251
253
  (stored.byteLength <= limitsOf(ctx).maxImageSegmentBytes ||
252
254
  stored.rowCount === 1)
@@ -264,9 +266,9 @@ async function readTableStart(ctx, schema, limits, unit, pair, startRowCursor, i
264
266
  return { firstPage: await scan };
265
267
  }
266
268
  // §4.7: a sqlite-lane table pins at the newest commit carrying all of the
267
- // unit's values (never below the horizon, never above maxCommitSeq), so a
268
- // stored image stays the reuse key's match until this scope changes
269
- // (§5.3). The server computes the pin; a client token never supplies it.
269
+ // unit's values (never below the table's horizon, never above
270
+ // maxCommitSeq), so a stored image stays the reuse key's match until this
271
+ // scope changes (§5.3). The server computes the pin; a client token never supplies it.
270
272
  const [firstPage, latest] = await Promise.all([
271
273
  scan,
272
274
  ctx.storage.latestScopedChangeSeq(ctx.partition, {
@@ -377,11 +379,13 @@ async function* sqliteImageSegment(ctx, schema, limits, pair, scopePin, rowCurso
377
379
  throw new Error('sqliteImageBuilder consumed rows out of order');
378
380
  }
379
381
  const last = index < 0 ? beforeBatch : batch[index].rowId;
380
- return segments.put({
382
+ return segments
383
+ .put({
381
384
  ...identity,
382
385
  rowCount: image.rowCount,
383
386
  nextRowCursor: image.rowCount < yielded || !exhausted ? last : null,
384
- }, image.bytes, clockOf(ctx)());
387
+ }, image.bytes, clockOf(ctx)())
388
+ .catch(segmentStoreFailure(ctx.onError, 'sync', 'put'));
385
389
  })();
386
390
  builds.set(key, building);
387
391
  }
@@ -474,7 +478,7 @@ async function* tableSegments(ctx, schema, limits, pair, pin, startRowCursor, st
474
478
  }
475
479
  else {
476
480
  // The page's put runs while the next page is scanned; the caller keeps
477
- // `maxConcurrentSegmentPuts` in flight and emits the frames in order.
481
+ // six puts in flight and emits the frames in order.
478
482
  trace?.segments.push({
479
483
  mediaType: 'rows',
480
484
  delivery: 'ref',
@@ -495,6 +499,7 @@ async function* tableSegments(ctx, schema, limits, pair, pin, startRowCursor, st
495
499
  rowCursor,
496
500
  nextRowCursor,
497
501
  }, bytes, now)
502
+ .catch(segmentStoreFailure(ctx.onError, 'sync', 'put'))
498
503
  .then(async (record) => segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, now)));
499
504
  yield { type: 'PENDING_REF', ref };
500
505
  }
@@ -511,13 +516,14 @@ async function* tableSegments(ctx, schema, limits, pair, pin, startRowCursor, st
511
516
  * is awaited, so a storage that batches concurrent page reads (PostgreSQL,
512
517
  * D1) answers them in one statement per table.
513
518
  */
514
- export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq, horizonSeq, logEpoch, keptCursor = 0) {
519
+ export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq, horizon, logEpoch, keptCursor = 0) {
515
520
  // §4.7: resume at the token's pin unless the token is unusable, or the pin
516
- // fell behind the horizon or a restricted bootstrap's kept cursor; then
517
- // restart from a fresh pin.
521
+ // fell behind the horizon, the table horizon of a bootstrap table, or a
522
+ // restricted bootstrap's kept cursor; then restart from a fresh pin.
518
523
  const token = parseBootstrapToken(bootstrapState, unit.tables, maxSeq);
519
524
  const resume = token !== undefined &&
520
- token.asOfCommitSeq >= Math.max(horizonSeq, keptCursor)
525
+ token.asOfCommitSeq >=
526
+ Math.max(horizon.seq, keptCursor, ...unit.tables.map((table) => horizon.tables.get(table.name) ?? -1))
521
527
  ? token
522
528
  : undefined;
523
529
  const tableIndex = resume?.tableIndex ?? 0;
@@ -529,7 +535,7 @@ export function planBootstrap(ctx, schema, limits, unit, bootstrapState, maxSeq,
529
535
  const effective = unit.pairs.get(table.name);
530
536
  if (effective === undefined)
531
537
  continue;
532
- const start = readTableStart(ctx, schema, limits, unit, { table, effective }, index === tableIndex ? rowCursor : null, index === tableIndex && image, maxSeq, horizonSeq, logEpoch);
538
+ const start = readTableStart(ctx, schema, limits, unit, { table, effective }, index === tableIndex ? rowCursor : null, index === tableIndex && image, maxSeq, Math.max(horizon.seq, horizon.tables.get(table.name) ?? -1), logEpoch);
533
539
  // A section that stops early never awaits the later starts.
534
540
  start.catch(() => undefined);
535
541
  starts.set(index, start);
@@ -649,9 +655,9 @@ export async function publishSqliteImage(input) {
649
655
  accept: ACCEPT_SQLITE,
650
656
  };
651
657
  const maxSeq = await config.storage.getMaxCommitSeq(partition);
652
- const horizonSeq = await config.storage.getHorizonSeq(partition);
658
+ const horizons = await config.storage.getHorizons(partition);
653
659
  const trace = { segments: [] };
654
- const plan = planBootstrap(ctx, schema, limits, unit, undefined, maxSeq, horizonSeq, logEpoch);
660
+ const plan = planBootstrap(ctx, schema, limits, unit, undefined, maxSeq, horizons, logEpoch);
655
661
  const refs = [];
656
662
  for await (const frame of bootstrapSegments(ctx, schema, limits, plan, trace, logEpoch)) {
657
663
  if (frame.type === 'PENDING_REF')
package/dist/push.js CHANGED
@@ -92,20 +92,23 @@ async function resolveBlobPresence(blobCtx, blobIds) {
92
92
  }));
93
93
  }
94
94
  /**
95
- * §6.7: run the table's write-validation hook, if configured, on the row
96
- * that WILL persist (post scope-strip, post CRDT-merge — the values the
97
- * store receives). Returns a terminating outcome iff the validator rejects
98
- * (its `ValidationRejection` code, or `sync.constraint_violation` for a
99
- * non-`ValidationRejection` throw), else `undefined` (accept / no hook).
100
- * A no-op for tables with no validator — the `undefined` short-circuit
101
- * keeps the feature zero-cost when off.
95
+ * §6.7: run the table's row hook, if configured, on the row that will persist
96
+ * (post scope-strip, post CRDT-merge). With `present` (an accepted insert or
97
+ * update of a pushed commit or a registered command) the hook's returned
98
+ * values for server-owned columns land in `values` and are marked present, so
99
+ * their column versions advance; elsewhere (a delete, a rescope, a §6.11
100
+ * cascade) the server ignores them. Returns a terminating outcome iff the
101
+ * hook fails: a `ValidationRejection` keeps its host code, and any other
102
+ * throw, a returned column that is not server-owned, a value the column's
103
+ * type refuses or a changed scope column on an update is
104
+ * `sync.constraint_violation`.
102
105
  */
103
- async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, tx, partition, actorId, context) {
106
+ async function runValidator(validators, tx, schema, table, op, rowId, values, storedValues, opIndex, partition, actorId, context, present) {
104
107
  const validator = validators?.[table.name];
105
108
  if (validator === undefined)
106
109
  return undefined;
107
110
  try {
108
- await validator({
111
+ const output = await validator({
109
112
  op,
110
113
  table: table.name,
111
114
  rowId,
@@ -115,61 +118,26 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
115
118
  stored: storedValues !== undefined
116
119
  ? toValidateRow(table.columns, storedValues)
117
120
  : undefined,
118
- }, {
119
- actorId,
120
- partition,
121
- ...(context !== undefined ? { context } : {}),
122
- queryAuthoritative: (query) => transactionQuery(tx, query),
123
- });
124
- }
125
- catch (error) {
126
- if (error instanceof ValidationRejection) {
127
- return errorRecord(opIndex, error.code, error.message, false, error.details);
128
- }
129
- // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
130
- // the generic server-side constraint code (§10.2) — the validator's
131
- // failure never crashes the request or leaks its message as a code.
132
- return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
133
- }
134
- return undefined;
135
- }
136
- /**
137
- * §6.12: complete an accepted upsert with the table's server column hook.
138
- * The returned values land in `values` and are marked present, so their
139
- * column versions advance. A `ValidationRejection` keeps its host code; any
140
- * other failure (an undeclared key, a value the column's type refuses, a
141
- * changed scope column on an update) is `sync.constraint_violation`.
142
- */
143
- async function runServerColumns(hooks, tx, schema, table, rowId, values, storedValues, present, opIndex, partition, actorId, context) {
144
- const hook = hooks?.[table.name];
145
- if (hook === undefined)
146
- return undefined;
147
- try {
148
- const output = await hook({
149
- table: table.name,
150
- rowId,
151
- row: toValidateRow(table.columns, values),
152
- stored: storedValues !== undefined
153
- ? toValidateRow(table.columns, storedValues)
154
- : undefined,
155
121
  }, {
156
122
  actorId,
157
123
  partition,
158
124
  ...(context !== undefined ? { context } : {}),
159
125
  read: commitValidationReader(tx, schema),
160
126
  });
127
+ if (output === undefined || present === undefined || values === undefined)
128
+ return undefined;
161
129
  for (const [name, value] of Object.entries(output)) {
162
130
  const index = table.columnIndex.get(name);
163
131
  if (index === undefined ||
164
132
  !table.serverOwnedColumnIndices.includes(index)) {
165
- throw new Error('server column hook returned a column that is not server-owned');
133
+ throw new Error('write validator returned a column that is not server-owned');
166
134
  }
167
135
  // The column's own codec refuses a value of the wrong type.
168
136
  encodeRow([table.columns[index]], [value]);
169
137
  if (storedValues !== undefined &&
170
138
  table.scopePatterns.some((pattern) => pattern.columnIndex === index) &&
171
139
  value !== (storedValues[index] ?? null)) {
172
- throw new Error('server column hook changed a scope column on update');
140
+ throw new Error('write validator changed a scope column on update');
173
141
  }
174
142
  values[index] = value;
175
143
  present[index] = true;
@@ -179,7 +147,10 @@ async function runServerColumns(hooks, tx, schema, table, rowId, values, storedV
179
147
  if (error instanceof ValidationRejection) {
180
148
  return errorRecord(opIndex, error.code, error.message, false, error.details);
181
149
  }
182
- return errorRecord(opIndex, 'sync.constraint_violation', 'server column hook failed');
150
+ // §6.7: any other failure is still a rejection, mapped to the generic
151
+ // server-side constraint code (§10.2); the hook's failure never crashes
152
+ // the request or leaks its message.
153
+ return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
183
154
  }
184
155
  return undefined;
185
156
  }
@@ -225,7 +196,7 @@ async function mergeCrdtColumns(table, values, storedValues, present, opIndex, m
225
196
  }
226
197
  return { changed };
227
198
  }
228
- async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, serverColumns, partition, actorId, context,
199
+ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, actorId, context,
229
200
  /** §2.2: the partition's delete floor, raised by this commit's deletes. */
230
201
  deleteFloor) {
231
202
  const table = schema.tables.get(op.table);
@@ -293,10 +264,10 @@ deleteFloor) {
293
264
  if (!authorizeWrite(table, extracted.scopes, resolved, true)) {
294
265
  return errorRecord(opIndex, 'sync.forbidden', 'rescope denied by scope authorization of the new scopes (§3.4)');
295
266
  }
296
- const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId, context);
267
+ const deleteReject = await runValidator(validators, tx, schema, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId, context);
297
268
  if (deleteReject !== undefined)
298
269
  return deleteReject;
299
- const upsertReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId, context);
270
+ const upsertReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId, context);
300
271
  if (upsertReject !== undefined)
301
272
  return upsertReject;
302
273
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
@@ -413,7 +384,7 @@ deleteFloor) {
413
384
  // stored = the row about to be removed). Only reached for an existing
414
385
  // row — an absent-row delete is an idempotent no-op above.
415
386
  const storedValues = decodeRow(table.columns, stored.payload);
416
- const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId, context);
387
+ const deleteReject = await runValidator(validators, tx, schema, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId, context);
417
388
  if (deleteReject !== undefined)
418
389
  return deleteReject;
419
390
  await tx.deleteRow(op.table, op.rowId);
@@ -460,7 +431,7 @@ deleteFloor) {
460
431
  catch (error) {
461
432
  return errorRecord(opIndex, 'sync.invalid_request', `row payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`);
462
433
  }
463
- // §6.12: the server discards a pushed value of a server-owned column, so an
434
+ // §6.7: the server discards a pushed value of a server-owned column, so an
464
435
  // older client that still writes one stays valid.
465
436
  for (const index of table.serverOwnedColumnIndices) {
466
437
  sparse[index] = stored === undefined ? null : undefined;
@@ -538,9 +509,11 @@ deleteFloor) {
538
509
  const mergeOutcome = await mergeCrdtColumns(table, values, storedValues, present, opIndex, crdtMergers);
539
510
  if ('kind' in mergeOutcome)
540
511
  return mergeOutcome;
541
- const serverReject = await runServerColumns(serverColumns, tx, schema, table, op.rowId, values, storedValues, present, opIndex, partition, actorId, context);
542
- if (serverReject !== undefined)
543
- return serverReject;
512
+ // §6.7: validate the merged row that will persist (for a crdt column the
513
+ // MERGED value, §5.10.3) and take its server-owned values.
514
+ const updateReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId, context, present);
515
+ if (updateReject !== undefined)
516
+ return updateReject;
544
517
  const newVersion = stored.serverVersion + 1;
545
518
  const nextVersions = new Map();
546
519
  for (let i = 0; i < table.columns.length; i++) {
@@ -559,12 +532,6 @@ deleteFloor) {
559
532
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
560
533
  if (blobCheck !== undefined)
561
534
  return blobCheck;
562
- // §6.7: validate the merged row that will persist — for a crdt column
563
- // the validator sees the MERGED value (§5.10.3), the state the store
564
- // holds, not the raw pushed update.
565
- const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId, context);
566
- if (updateReject !== undefined)
567
- return updateReject;
568
535
  const columnVersions = encodeColumnVersions(nextVersions);
569
536
  const newRow = {
570
537
  rowId: op.rowId,
@@ -656,14 +623,17 @@ deleteFloor) {
656
623
  const insertMerge = await mergeCrdtColumns(table, values, undefined, present, opIndex, crdtMergers);
657
624
  if ('kind' in insertMerge)
658
625
  return insertMerge;
659
- const serverReject = await runServerColumns(serverColumns, tx, schema, table, op.rowId, values, undefined, present, opIndex, partition, actorId, context);
660
- if (serverReject !== undefined)
661
- return serverReject;
662
- // §6.12: the stored scopes and the change-scope index take the hook's
626
+ // §6.7: validate the insert row (stored = undefined, so a validator can
627
+ // distinguish create from update; crdt columns are already merged against
628
+ // the empty document) and take its server-owned values.
629
+ const insertReject = await runValidator(validators, tx, schema, table, 'upsert', op.rowId, values, undefined, opIndex, partition, actorId, context, present);
630
+ if (insertReject !== undefined)
631
+ return insertReject;
632
+ // §6.7: the stored scopes and the change-scope index take the validator's
663
633
  // values, so the row reaches a server-set scope's units in this commit.
664
634
  const scoped = storedScopesForRow(table, values);
665
635
  if ('missing' in scoped) {
666
- return errorRecord(opIndex, 'sync.constraint_violation', 'server column hook failed');
636
+ return errorRecord(opIndex, 'sync.constraint_violation', 'write validator failed');
667
637
  }
668
638
  // The stored payload is the full-row codec (§2.4); every column is
669
639
  // present on an insert.
@@ -672,12 +642,6 @@ deleteFloor) {
672
642
  const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
673
643
  if (blobCheck !== undefined)
674
644
  return blobCheck;
675
- // §6.7: validate the insert row (stored = undefined, so a validator can
676
- // distinguish create from update); crdt columns are already merged
677
- // against the empty document.
678
- const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId, context);
679
- if (insertReject !== undefined)
680
- return insertReject;
681
645
  // §2.2, §6.2: every insert starts one above the delete floor, over a
682
646
  // tombstone or not; without a column-versions blob every column sits at
683
647
  // that version.
@@ -1085,7 +1049,7 @@ async function enforceReferences(tx, schema, resolved, staged, clientOpCount, ca
1085
1049
  const syntheticIndex = clientOpCount + originByIndex.length;
1086
1050
  const storedValues = decodeRow(child.columns, childRow.payload);
1087
1051
  if (reference.onDelete === 'CASCADE') {
1088
- const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, tx, partition, actorId, context);
1052
+ const reject = await runValidator(validators, tx, schema, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, partition, actorId, context);
1089
1053
  if (reject !== undefined) {
1090
1054
  return { kind: 'terminate', record: reject.record };
1091
1055
  }
@@ -1110,7 +1074,7 @@ async function enforceReferences(tx, schema, resolved, staged, clientOpCount, ca
1110
1074
  else {
1111
1075
  const values = [...storedValues];
1112
1076
  values[reference.columnIndex] = null;
1113
- const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, tx, partition, actorId, context);
1077
+ const reject = await runValidator(validators, tx, schema, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, partition, actorId, context);
1114
1078
  if (reject !== undefined) {
1115
1079
  return { kind: 'terminate', record: reject.record };
1116
1080
  }
@@ -1468,7 +1432,7 @@ async function applyPushCommits(ctx, schema, resolved, clientId, commits, wireSc
1468
1432
  const op = operations[opIndex];
1469
1433
  if (op === undefined)
1470
1434
  continue;
1471
- const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, ctx.serverColumns, partition, ctx.actorId, ctx.context, deleteFloor);
1435
+ const outcome = await applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId, ctx.context, deleteFloor);
1472
1436
  if (outcome.kind === 'terminate') {
1473
1437
  terminated = outcome.record;
1474
1438
  break;
@@ -304,9 +304,11 @@ export declare class RealtimeHub {
304
304
  notifySubscriptions(partition: string, clientId: string): Promise<void>;
305
305
  /**
306
306
  * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
307
- * after it changes an actor's membership or connection state, so the
308
- * partition's connected sessions stop using grants the host already revoked
309
- * without waiting for the client to happen to run a round.
307
+ * after it changes an actor's grants, whether they shrank or grew. Each
308
+ * matching session re-resolves its registrations, so it stops using grants
309
+ * the host already revoked without waiting for its client to run a round,
310
+ * and then receives one `scopes` event, so its client's app runs its
311
+ * discovery and registers units it did not know.
310
312
  *
311
313
  * This differs deliberately from the round-end refresh
312
314
  * (`RealtimeSession.refreshRegistrations`), which keeps the previous
@@ -316,14 +318,6 @@ export declare class RealtimeHub {
316
318
  * on until the next round. Presence is reconciled exactly as at round end.
317
319
  */
318
320
  refreshScopes(partition: string, actorId?: string): Promise<void>;
319
- /**
320
- * Host announcement (§8.7): tell the connected sessions of `actorIds` on
321
- * the partition that their grant widened, so each client's app runs its
322
- * discovery and registers the units it did not know. Sends one `scopes`
323
- * event per session and changes no registration; a narrowed grant needs
324
- * `refreshScopes`.
325
- */
326
- announceScopes(partition: string, actorIds: readonly string[]): void;
327
321
  /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
328
322
  wake(partition: string, reason: WakeReason): void;
329
323
  /** Wake every session on every partition (fanout listener gap, §8.3). */
package/dist/realtime.js CHANGED
@@ -531,8 +531,8 @@ export class RealtimeSession {
531
531
  step = await iterator.next();
532
532
  }
533
533
  catch (error) {
534
- // The generator builds the whole response (and runs the read-verify
535
- // refusal) on its first `next()`, before any chunk is yielded.
534
+ // The first `next()` waits until the response is built (and the
535
+ // read-verify refusal ran) or its first KEEPALIVE is due (§1.6).
536
536
  // Nothing has escaped, so a failure there is delivered as the same
537
537
  // §8.4 ERROR frame HTTP returns rather than a silent close; a
538
538
  // non-catalog exception is reported and answers
@@ -1203,9 +1203,11 @@ export class RealtimeHub {
1203
1203
  }
1204
1204
  /**
1205
1205
  * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
1206
- * after it changes an actor's membership or connection state, so the
1207
- * partition's connected sessions stop using grants the host already revoked
1208
- * without waiting for the client to happen to run a round.
1206
+ * after it changes an actor's grants, whether they shrank or grew. Each
1207
+ * matching session re-resolves its registrations, so it stops using grants
1208
+ * the host already revoked without waiting for its client to run a round,
1209
+ * and then receives one `scopes` event, so its client's app runs its
1210
+ * discovery and registers units it did not know.
1209
1211
  *
1210
1212
  * This differs deliberately from the round-end refresh
1211
1213
  * (`RealtimeSession.refreshRegistrations`), which keeps the previous
@@ -1220,25 +1222,10 @@ export class RealtimeHub {
1220
1222
  continue;
1221
1223
  if (actorId !== undefined && session.actorId !== actorId)
1222
1224
  continue;
1223
- // Fail closed (see the doc above): an unreadable client record drops
1224
- // every grant on the connection. The session's generation guard keeps
1225
- // this revocation from being overwritten by a slower round-end reload.
1225
+ // The session's generation guard keeps this revocation from being
1226
+ // overwritten by a slower round-end reload.
1226
1227
  await session.refreshRegistrations(true);
1227
- }
1228
- }
1229
- /**
1230
- * Host announcement (§8.7): tell the connected sessions of `actorIds` on
1231
- * the partition that their grant widened, so each client's app runs its
1232
- * discovery and registers the units it did not know. Sends one `scopes`
1233
- * event per session and changes no registration; a narrowed grant needs
1234
- * `refreshScopes`.
1235
- */
1236
- announceScopes(partition, actorIds) {
1237
- for (const session of this.#sessions) {
1238
- if (session.partition !== partition)
1239
- continue;
1240
- if (actorIds.includes(session.actorId))
1241
- session.sendScopes();
1228
+ session.sendScopes();
1242
1229
  }
1243
1230
  }
1244
1231
  /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
@@ -210,12 +210,22 @@ export interface IndexRowPageStatement {
210
210
  export declare function indexRowPageStatement(table: CompiledTable, index: IndexSchema, values: readonly RowValue[], partition: string, afterRowId: string | null | undefined, limit: number, dialect: RelationalDialect): IndexRowPageStatement;
211
211
  /**
212
212
  * One-round-trip page scan for `scanRows`: candidates from the inverted
213
- * scope index (ordered + LIMITed at the covering `sync_row_scopes` PK —
214
- * exactly the old candidate query, so the index-first posture is unchanged)
215
- * LEFT JOINed to the row table, so a whole page arrives in ONE statement
216
- * instead of one lookup per candidate. That per-candidate lookup was the
217
- * cold-bootstrap hot path: a 100k-row snapshot on Postgres paid ~100k
218
- * network round-trips (~10 s at 0.1 ms each) before this join.
213
+ * scope index LEFT JOINed to the row table, so a whole page arrives in ONE
214
+ * statement instead of one lookup per candidate. That per-candidate lookup
215
+ * was the cold-bootstrap hot path: a 100k-row snapshot on Postgres paid
216
+ * ~100k network round-trips (~10 s at 0.1 ms each) before this join.
217
+ *
218
+ * The candidates read at most `limit` entries of the covering
219
+ * `sync_row_scopes` PK per scope value. A bare `value IN (...)` (or
220
+ * `= ANY`) predicate gives up the PK's `row_id` order whenever the planner
221
+ * cannot prove a single value, and then every entry after the cursor is read
222
+ * and sorted before the LIMIT: a cost that grows with the entries left, so a
223
+ * bootstrap is quadratic. PostgreSQL reads one ordered, LIMITed range per
224
+ * value through a LATERAL join and merges them. SQLite has no LATERAL; it
225
+ * bounds the ranges from above instead: the smallest of the values' `limit`th
226
+ * entries after the cursor. That value alone has `limit` entries up to its
227
+ * bound, so the page ends there; a value with fewer entries has no bound, and
228
+ * when no value has one the empty blob `x''` sorts after every TEXT row id.
219
229
  *
220
230
  * LEFT JOIN (not INNER): a candidate whose row vanished (index entry
221
231
  * without a row) must still reach the caller — its `row_id` advances the
@@ -223,11 +233,9 @@ export declare function indexRowPageStatement(table: CompiledTable, index: Index
223
233
  * disappearing from the page.
224
234
  *
225
235
  * Bind order:
226
- * - postgres: [partition, tbl, var, ...values, afterRowId, limit]
227
- * (the join reuses `$1` for the partition);
236
+ * - postgres: [partition, tbl, var, ...values, afterRowId, limit];
228
237
  * - sqlite: [partition, tbl, var, values as JSON array text, afterRowId,
229
- * limit, partition] (positional `?`; the partition binds again for the
230
- * join). The values expand through `json_each`, so the statement text and
238
+ * limit]. The values expand through `json_each`, so the statement text and
231
239
  * parameter count do not depend on `valueCount` and D1's 100-parameter
232
240
  * cap is unreachable through scope values.
233
241
  */
@@ -264,7 +272,7 @@ export declare function scanProbeSql(dialect: RelationalDialect): string;
264
272
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
265
273
  * page of every subscription scanning any table in a pull. `$2` is a JSON
266
274
  * array of `{i, tbl, var, vals, after, lim}` records; each record runs the
267
- * same index-first candidate subquery through a LATERAL join, so every
275
+ * same per-value candidate ranges through a LATERAL join, so every
268
276
  * subscription keeps its own keyset cursor and LIMIT. The candidate side is
269
277
  * table-agnostic (a spec names its table), so the statement joins the row
270
278
  * table once per table present in the batch through a UNION ALL branch that
@@ -346,8 +354,10 @@ export declare function changedScopePatterns(schema: CompiledSchema, storedJson:
346
354
  export declare function assertStoredScopePatterns(schema: CompiledSchema, storedJson: string | null | undefined): boolean;
347
355
  /**
348
356
  * §3.1 re-key, before the row walk: drop the re-keyed tables' row scope index
349
- * entries and tombstones, and raise every partition's horizon past the
350
- * changes logged under the previous patterns. Empty when nothing re-keys.
357
+ * entries and tombstones. The re-key takes a commit sequence number of its
358
+ * own in every partition and records it as each re-keyed table's horizon
359
+ * (§4.6), past the changes logged under the previous patterns. Empty when
360
+ * nothing re-keys.
351
361
  */
352
362
  export declare function rekeyCleanupSql(tables: readonly string[]): string[];
353
363
  /**