@syncular/server 0.82.3 → 0.84.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.
@@ -44,8 +44,8 @@ var _a;
44
44
  import { decodeRow } from '@syncular/core';
45
45
  import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, assertStoredScopePatterns, changedScopePatterns, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, rekeyCleanupSql, rekeyedScopes, rekeyRowScopesSql, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanProbeSql, scanRowPageSql, schemaDdl, serverIndexDdl, SQLITE_TABLE_INDEXES_SQL, sqliteIndexSignatures, selectRowSql, selectRowsSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, } from './relational-rows.js';
46
46
  import { matchesEffective } from './scopes.js';
47
- import { asUint8Array, deserializePushResult, placeholders, SqliteFamilyStorage, SqliteFamilyTransaction, sqliteDdlStatements, SQLITE_UPGRADE_PROBE, sqliteUpgradeDdl, toStoredRow, toTombstone, } from './sqlite-dialect.js';
48
- import { commitDeleteFloor } from './storage.js';
47
+ import { deserializePushResult, placeholders, SqliteFamilyStorage, SqliteFamilyTransaction, sqliteDdlStatements, SQLITE_UPGRADE_PROBE, sqliteUpgradeDdl, } from './sqlite-dialect.js';
48
+ import { asUint8Array, commitDeleteFloor, toStoredRow, toTombstone, } from './storage.js';
49
49
  import { isD1ConstraintError, StorageConstraintError, StorageQueryError, } from './storage-errors.js';
50
50
  import { chooseScanVariable, resolveIndexRowScan } from './storage-query.js';
51
51
  /** The rows of one `db.batch` result entry (`{ results }` per statement). */
@@ -1,6 +1,6 @@
1
1
  import { validateCommitPruneQuery } from './prune.js';
2
2
  import { StorageQueryError } from './storage-errors.js';
3
- import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS, commitDeleteFloor, rowsLiveAfterDelete, serveGateRefusal, } from './storage.js';
3
+ import { asJson, CLIENT_RECORD_COLUMNS, pushResultFromJson, pushResultToJson, toClientRecord, toStoredChange, toStoredReaction, toStoredRow, toTombstone, PARTITION_TOUCH_INTERVAL_MS, commitDeleteFloor, rowsLiveAfterDelete, serveGateRefusal, } from './storage.js';
4
4
  import { serveNotReadyError } from './readiness.js';
5
5
  /**
6
6
  * Postgres server storage: the production database path.
@@ -39,7 +39,7 @@ import { serveNotReadyError } from './readiness.js';
39
39
  * would leave gaps on rollback, which the pull-window arithmetic in §4.5
40
40
  * does not tolerate). Cross-partition pushes never contend.
41
41
  */
42
- import { decodeRow, } from '@syncular/core';
42
+ import { decodeRow } from '@syncular/core';
43
43
  import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
44
44
  import { syncError } from './errors.js';
45
45
  import { asBytes, asNumber, } from './pg-executor.js';
@@ -462,9 +462,6 @@ async function hasSourceChangesAboveOn(client, partition, tables, seq) {
462
462
  function toBase64(bytes) {
463
463
  return Buffer.from(bytes).toString('base64');
464
464
  }
465
- function fromBase64(text) {
466
- return new Uint8Array(Buffer.from(text, 'base64'));
467
- }
468
465
  function toStoredCheckpoint(record) {
469
466
  return {
470
467
  partition: record.partition,
@@ -477,188 +474,6 @@ function toStoredCheckpoint(record) {
477
474
  updatedAtMs: asNumber(record.updated_at_ms),
478
475
  };
479
476
  }
480
- function toStoredReaction(record) {
481
- return {
482
- idempotencyKey: record.idempotency_key,
483
- type: record.type,
484
- version: asNumber(record.version),
485
- payload: asJson(record.payload),
486
- sourceClientId: record.source_client_id,
487
- sourceClientCommitId: record.source_client_commit_id,
488
- sourceCommitSeq: asNumber(record.source_commit_seq),
489
- createdAtMs: asNumber(record.created_at_ms),
490
- maxAttempts: asNumber(record.max_attempts),
491
- status: record.status,
492
- attempts: asNumber(record.attempts),
493
- availableAtMs: asNumber(record.available_at_ms),
494
- ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
495
- ...(record.lease_expires_at_ms !== null
496
- ? { leaseExpiresAtMs: asNumber(record.lease_expires_at_ms) }
497
- : {}),
498
- ...(record.completed_at_ms !== null
499
- ? { completedAtMs: asNumber(record.completed_at_ms) }
500
- : {}),
501
- ...(record.last_failure !== null
502
- ? { lastFailure: asJson(record.last_failure) }
503
- : {}),
504
- };
505
- }
506
- /**
507
- * Serialize a push result to a JSON-able object (stored in a JSONB column).
508
- * `serverRow` bytes are base64-encoded — JSONB cannot hold raw bytes.
509
- */
510
- function serializePushResult(result) {
511
- return {
512
- status: result.status,
513
- ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
514
- ...(result.recordedAtMs !== undefined
515
- ? { recordedAtMs: result.recordedAtMs }
516
- : {}),
517
- ...(result.cacheIdentity !== undefined
518
- ? { cacheIdentity: result.cacheIdentity }
519
- : {}),
520
- ...(result.conflictAuthorization !== undefined
521
- ? { conflictAuthorization: result.conflictAuthorization }
522
- : {}),
523
- results: result.results.map((record) => {
524
- if (record.status === 'conflict') {
525
- return {
526
- opIndex: record.opIndex,
527
- status: record.status,
528
- code: record.code,
529
- message: record.message,
530
- serverVersion: record.serverVersion,
531
- serverRow: toBase64(record.serverRow),
532
- conflictColumns: toBase64(record.conflictColumns),
533
- };
534
- }
535
- if (record.status === 'error') {
536
- return {
537
- opIndex: record.opIndex,
538
- status: record.status,
539
- code: record.code,
540
- message: record.message,
541
- retryable: record.retryable,
542
- ...(record.details !== undefined ? { details: record.details } : {}),
543
- };
544
- }
545
- return { opIndex: record.opIndex, status: record.status };
546
- }),
547
- };
548
- }
549
- function deserializePushResult(value) {
550
- const parsed = value;
551
- const results = parsed.results.map((record) => {
552
- if (record.status === 'conflict') {
553
- return {
554
- opIndex: record.opIndex,
555
- status: 'conflict',
556
- code: record.code ?? '',
557
- message: record.message ?? '',
558
- serverVersion: record.serverVersion ?? 0,
559
- serverRow: fromBase64(record.serverRow ?? ''),
560
- conflictColumns: fromBase64(record.conflictColumns ?? ''),
561
- };
562
- }
563
- if (record.status === 'error') {
564
- return {
565
- opIndex: record.opIndex,
566
- status: 'error',
567
- code: record.code ?? '',
568
- message: record.message ?? '',
569
- retryable: record.retryable ?? false,
570
- ...(record.details !== undefined ? { details: record.details } : {}),
571
- };
572
- }
573
- return { opIndex: record.opIndex, status: 'applied' };
574
- });
575
- return {
576
- status: parsed.status,
577
- ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
578
- ...(parsed.recordedAtMs !== undefined
579
- ? { recordedAtMs: parsed.recordedAtMs }
580
- : {}),
581
- ...(parsed.cacheIdentity !== undefined
582
- ? { cacheIdentity: parsed.cacheIdentity }
583
- : {}),
584
- ...(parsed.conflictAuthorization !== undefined
585
- ? { conflictAuthorization: parsed.conflictAuthorization }
586
- : {}),
587
- results,
588
- };
589
- }
590
- /**
591
- * Some drivers return a JSONB column already parsed (pglite, node-postgres);
592
- * accept a string too for defensiveness.
593
- */
594
- function asJson(value) {
595
- if (typeof value === 'string')
596
- return JSON.parse(value);
597
- return value;
598
- }
599
- function toStoredRow(record) {
600
- return {
601
- rowId: record.row_id,
602
- serverVersion: asNumber(record.server_version),
603
- scopes: asJson(record.scopes),
604
- payload: asBytes(record.payload),
605
- ...(record.column_versions === null || record.column_versions === undefined
606
- ? {}
607
- : { columnVersions: asBytes(record.column_versions) }),
608
- };
609
- }
610
- function toTombstone(seq, version, scopes) {
611
- if (seq === null || seq === undefined)
612
- return null;
613
- return {
614
- commitSeq: asNumber(seq),
615
- ...(version === null || version === undefined
616
- ? {}
617
- : { serverVersion: asNumber(version) }),
618
- ...(scopes === null || scopes === undefined
619
- ? {}
620
- : { scopes: asJson(scopes) }),
621
- };
622
- }
623
- const CLIENT_RECORD_COLUMNS = 'client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures';
624
- function toClientRecord(record) {
625
- return {
626
- clientId: record.client_id,
627
- actorId: record.actor_id,
628
- wireVersion: asNumber(record.wire_version),
629
- cursor: asNumber(record.cursor),
630
- updatedAtMs: asNumber(record.updated_at_ms),
631
- ...(record.schema_version === null
632
- ? {}
633
- : { schemaVersion: asNumber(record.schema_version) }),
634
- ...(record.units === null || record.registration_digest === null
635
- ? {}
636
- : {
637
- registration: {
638
- units: asJson(record.units),
639
- digest: asBytes(record.registration_digest),
640
- },
641
- }),
642
- catchingUp: asJson(record.catching_up),
643
- ...clientRoundState(record.last_round_at_ms === null
644
- ? null
645
- : asNumber(record.last_round_at_ms), record.last_error_code, asNumber(record.consecutive_failures)),
646
- };
647
- }
648
- function toStoredChange(record) {
649
- return {
650
- table: record.tbl,
651
- rowId: record.row_id,
652
- op: asNumber(record.op) === 1 ? 'upsert' : 'delete',
653
- ...(record.row_version !== null && record.row_version !== undefined
654
- ? { rowVersion: asNumber(record.row_version) }
655
- : {}),
656
- scopes: asJson(record.scopes),
657
- ...(record.payload !== null && record.payload !== undefined
658
- ? { payload: asBytes(record.payload) }
659
- : {}),
660
- };
661
- }
662
477
  /**
663
478
  * Migration rewrite: keyset-paged walk of a row table inside the migration
664
479
  * transaction. When `oldLayout` is
@@ -948,7 +763,7 @@ function toPersistedPushResult(value) {
948
763
  if (value === null || value === undefined)
949
764
  return undefined;
950
765
  try {
951
- return deserializePushResult(asJson(value));
766
+ return pushResultFromJson(asJson(value));
952
767
  }
953
768
  catch {
954
769
  throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
@@ -1244,7 +1059,13 @@ class PostgresTransaction {
1244
1059
  this.#prefetchedRows.set(key, record.row_id === null || record.row_id === undefined
1245
1060
  ? null
1246
1061
  : toStoredRow({ ...record, row_id: record.row_id }));
1247
- this.#prefetchedTombstones.set(key, toTombstone(record.tombstone_seq, record.tombstone_version, record.tombstone_scopes));
1062
+ this.#prefetchedTombstones.set(key, record.tombstone_seq === null || record.tombstone_seq === undefined
1063
+ ? null
1064
+ : toTombstone({
1065
+ commit_seq: record.tombstone_seq,
1066
+ server_version: record.tombstone_version,
1067
+ scopes: record.tombstone_scopes,
1068
+ }));
1248
1069
  }
1249
1070
  }
1250
1071
  async getTombstone(table, rowId) {
@@ -1254,8 +1075,9 @@ class PostgresTransaction {
1254
1075
  return prefetched ?? undefined;
1255
1076
  const { rows } = await this.#readOf([table]).query('SELECT commit_seq, server_version, scopes FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
1256
1077
  const row = rows[0];
1257
- return (toTombstone(row?.commit_seq, row?.server_version, row?.scopes) ??
1258
- undefined);
1078
+ return row === undefined || row.commit_seq === null
1079
+ ? undefined
1080
+ : toTombstone(row);
1259
1081
  }
1260
1082
  async clearTombstone(table, rowId) {
1261
1083
  this.#assertOpen();
@@ -1420,7 +1242,7 @@ class PostgresTransaction {
1420
1242
  this.#pushResults.push({
1421
1243
  client_id: clientId,
1422
1244
  client_commit_id: clientCommitId,
1423
- result: serializePushResult(result),
1245
+ result: pushResultToJson(result),
1424
1246
  outbox_id: sequence?.outboxId ?? null,
1425
1247
  client_seq: sequence?.clientSeq ?? null,
1426
1248
  });
@@ -1816,7 +1638,10 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1816
1638
  ? undefined
1817
1639
  : asNumber(marker.schema_version);
1818
1640
  if (stored !== undefined && stored > schema.version) {
1819
- throw new Error(`stored schema version ${stored} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
1641
+ throw new StorageQueryError('sync.storage.schema_changed', {
1642
+ storedVersion: String(stored),
1643
+ configuredVersion: String(schema.version),
1644
+ });
1820
1645
  }
1821
1646
  if (stored !== undefined && stored === schema.version) {
1822
1647
  const storedLayouts = typeof marker.layouts === 'string' ? marker.layouts : undefined;
@@ -1880,7 +1705,10 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1880
1705
  ? undefined
1881
1706
  : asNumber(lockedMarker[0].schema_version);
1882
1707
  if (lockedVersion !== undefined && lockedVersion > schema.version) {
1883
- throw new Error(`stored schema version ${lockedVersion} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
1708
+ throw new StorageQueryError('sync.storage.schema_changed', {
1709
+ storedVersion: String(lockedVersion),
1710
+ configuredVersion: String(schema.version),
1711
+ });
1884
1712
  }
1885
1713
  if (lockedVersion === schema.version)
1886
1714
  return;
@@ -2776,7 +2604,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2776
2604
  try {
2777
2605
  return {
2778
2606
  clientId: row.client_id,
2779
- result: deserializePushResult(asJson(row.result)),
2607
+ result: pushResultFromJson(asJson(row.result)),
2780
2608
  };
2781
2609
  }
2782
2610
  catch {
@@ -18,7 +18,7 @@ import type { UnitScopes } from '@syncular/core';
18
18
  import { type BoundAuthoritativeQuery } from './authoritative-query.js';
19
19
  import type { CompiledTable } from './schema.js';
20
20
  import type { SqliteValue } from './sqlite-driver.js';
21
- import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredChange, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
21
+ import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
22
22
  /**
23
23
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
24
24
  * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
@@ -77,16 +77,11 @@ export interface SqliteChangeRecord {
77
77
  scopes: string;
78
78
  payload: Uint8Array | null;
79
79
  }
80
- /** Native SQLite returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
81
- export declare function asUint8Array(value: unknown): Uint8Array;
82
- export declare function toStoredRow(record: SqliteRowRecord): StoredRow;
83
80
  export interface SqliteTombstoneRecord {
84
81
  commit_seq: number;
85
82
  server_version: number | null;
86
83
  scopes: string | null;
87
84
  }
88
- export declare function toTombstone(record: SqliteTombstoneRecord): Tombstone;
89
- export declare function toStoredChange(record: SqliteChangeRecord): StoredChange;
90
85
  /** One statement of an atomic unit: its SQL text and bound parameters. */
91
86
  export interface SqliteStatementSpec {
92
87
  readonly sql: string;
@@ -4,7 +4,7 @@ import { validateCommitPruneQuery } from './prune.js';
4
4
  import { StorageQueryError } from './storage-errors.js';
5
5
  import { deleteRowSql, deleteSqliteRowScopesSql, indexRowPageStatement, quoteIdent, scanProbeSql, scanRowPageSql, rowsReferencingBlobSql, selectRowSql, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, upsertSql, upsertValues, } from './relational-rows.js';
6
6
  import { matchesEffective } from './scopes.js';
7
- import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS, rowsLiveAfterDelete, } from './storage.js';
7
+ import { CLIENT_RECORD_COLUMNS, PARTITION_TOUCH_INTERVAL_MS, pushResultFromJson, pushResultToJson, rowsLiveAfterDelete, toClientRecord, toStoredChange, toStoredReaction, toStoredRow, toTombstone, } from './storage.js';
8
8
  import { chooseScanVariable, readLiveWindowPages, resolveIndexRowScan, } from './storage-query.js';
9
9
  /**
10
10
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
@@ -233,202 +233,19 @@ export function placeholders(count) {
233
233
  return new Array(count).fill('?').join(',');
234
234
  }
235
235
  // -- value (de)serialization, shared by both SQLite storages ----------------
236
- /** Runtime-neutral base64 (no `Buffer` — Workers-safe) for push results. */
237
- function bytesToBase64(bytes) {
238
- let binary = '';
239
- for (const byte of bytes)
240
- binary += String.fromCharCode(byte);
241
- return btoa(binary);
242
- }
243
- function base64ToBytes(text) {
244
- const binary = atob(text);
245
- const bytes = new Uint8Array(binary.length);
246
- for (let i = 0; i < binary.length; i++)
247
- bytes[i] = binary.charCodeAt(i);
248
- return bytes;
249
- }
250
236
  /** Serialize a push result to the JSON `TEXT` stored in `sync_push_results`. */
251
237
  export function serializePushResult(result) {
252
- return JSON.stringify({
253
- status: result.status,
254
- ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
255
- ...(result.recordedAtMs !== undefined
256
- ? { recordedAtMs: result.recordedAtMs }
257
- : {}),
258
- ...(result.cacheIdentity !== undefined
259
- ? { cacheIdentity: result.cacheIdentity }
260
- : {}),
261
- ...(result.conflictAuthorization !== undefined
262
- ? { conflictAuthorization: result.conflictAuthorization }
263
- : {}),
264
- results: result.results.map((record) => {
265
- if (record.status === 'conflict') {
266
- return {
267
- opIndex: record.opIndex,
268
- status: record.status,
269
- code: record.code,
270
- message: record.message,
271
- serverVersion: record.serverVersion,
272
- serverRow: bytesToBase64(record.serverRow),
273
- conflictColumns: bytesToBase64(record.conflictColumns),
274
- };
275
- }
276
- if (record.status === 'error') {
277
- return {
278
- opIndex: record.opIndex,
279
- status: record.status,
280
- code: record.code,
281
- message: record.message,
282
- retryable: record.retryable,
283
- ...(record.details !== undefined ? { details: record.details } : {}),
284
- };
285
- }
286
- return { opIndex: record.opIndex, status: record.status };
287
- }),
288
- });
238
+ return JSON.stringify(pushResultToJson(result));
289
239
  }
290
240
  /** Parse a stored push result; an unreadable record is a §6.3 cache miss. */
291
241
  export function deserializePushResult(text) {
292
242
  try {
293
- const parsed = JSON.parse(text);
294
- const results = parsed.results.map((record) => {
295
- if (record.status === 'conflict') {
296
- return {
297
- opIndex: record.opIndex,
298
- status: 'conflict',
299
- code: record.code ?? '',
300
- message: record.message ?? '',
301
- serverVersion: record.serverVersion ?? 0,
302
- serverRow: base64ToBytes(record.serverRow ?? ''),
303
- conflictColumns: base64ToBytes(record.conflictColumns ?? ''),
304
- };
305
- }
306
- if (record.status === 'error') {
307
- return {
308
- opIndex: record.opIndex,
309
- status: 'error',
310
- code: record.code ?? '',
311
- message: record.message ?? '',
312
- retryable: record.retryable ?? false,
313
- ...(record.details !== undefined ? { details: record.details } : {}),
314
- };
315
- }
316
- return { opIndex: record.opIndex, status: 'applied' };
317
- });
318
- return {
319
- status: parsed.status,
320
- ...(parsed.commitSeq !== undefined
321
- ? { commitSeq: parsed.commitSeq }
322
- : {}),
323
- ...(parsed.recordedAtMs !== undefined
324
- ? { recordedAtMs: parsed.recordedAtMs }
325
- : {}),
326
- ...(parsed.cacheIdentity !== undefined
327
- ? { cacheIdentity: parsed.cacheIdentity }
328
- : {}),
329
- ...(parsed.conflictAuthorization !== undefined
330
- ? { conflictAuthorization: parsed.conflictAuthorization }
331
- : {}),
332
- results,
333
- };
243
+ return pushResultFromJson(JSON.parse(text));
334
244
  }
335
245
  catch {
336
246
  throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
337
247
  }
338
248
  }
339
- /** Native SQLite returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
340
- export function asUint8Array(value) {
341
- if (value instanceof Uint8Array)
342
- return value;
343
- if (value instanceof ArrayBuffer)
344
- return new Uint8Array(value);
345
- if (Array.isArray(value))
346
- return new Uint8Array(value);
347
- throw new Error(`expected a BLOB column, got ${typeof value}`);
348
- }
349
- export function toStoredRow(record) {
350
- return {
351
- rowId: record.row_id,
352
- serverVersion: record.server_version,
353
- scopes: JSON.parse(record.scopes),
354
- payload: asUint8Array(record.payload),
355
- ...(record.column_versions !== null
356
- ? { columnVersions: asUint8Array(record.column_versions) }
357
- : {}),
358
- };
359
- }
360
- export function toTombstone(record) {
361
- return {
362
- commitSeq: record.commit_seq,
363
- ...(record.server_version !== null
364
- ? { serverVersion: record.server_version }
365
- : {}),
366
- ...(record.scopes !== null
367
- ? { scopes: JSON.parse(record.scopes) }
368
- : {}),
369
- };
370
- }
371
- export function toStoredChange(record) {
372
- return {
373
- table: record.tbl,
374
- rowId: record.row_id,
375
- op: record.op === 1 ? 'upsert' : 'delete',
376
- ...(record.row_version !== null ? { rowVersion: record.row_version } : {}),
377
- scopes: JSON.parse(record.scopes),
378
- ...(record.payload !== null
379
- ? { payload: asUint8Array(record.payload) }
380
- : {}),
381
- };
382
- }
383
- function toStoredReaction(record) {
384
- return {
385
- idempotencyKey: record.idempotency_key,
386
- type: record.type,
387
- version: record.version,
388
- payload: JSON.parse(record.payload),
389
- sourceClientId: record.source_client_id,
390
- sourceClientCommitId: record.source_client_commit_id,
391
- sourceCommitSeq: record.source_commit_seq,
392
- createdAtMs: record.created_at_ms,
393
- maxAttempts: record.max_attempts,
394
- status: record.status,
395
- attempts: record.attempts,
396
- availableAtMs: record.available_at_ms,
397
- ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
398
- ...(record.lease_expires_at_ms !== null
399
- ? { leaseExpiresAtMs: record.lease_expires_at_ms }
400
- : {}),
401
- ...(record.completed_at_ms !== null
402
- ? { completedAtMs: record.completed_at_ms }
403
- : {}),
404
- ...(record.last_failure !== null
405
- ? { lastFailure: JSON.parse(record.last_failure) }
406
- : {}),
407
- };
408
- }
409
- const CLIENT_RECORD_COLUMNS = 'client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures';
410
- function toClientRecord(record) {
411
- return {
412
- clientId: record.client_id,
413
- actorId: record.actor_id,
414
- wireVersion: record.wire_version,
415
- cursor: record.cursor,
416
- updatedAtMs: record.updated_at_ms,
417
- ...(record.schema_version !== null
418
- ? { schemaVersion: record.schema_version }
419
- : {}),
420
- ...(record.units !== null && record.registration_digest !== null
421
- ? {
422
- registration: {
423
- units: JSON.parse(record.units),
424
- digest: asUint8Array(record.registration_digest),
425
- },
426
- }
427
- : {}),
428
- catchingUp: JSON.parse(record.catching_up),
429
- ...clientRoundState(record.last_round_at_ms, record.last_error_code, record.consecutive_failures),
430
- };
431
- }
432
249
  function toPartitionRegistryEntry(row) {
433
250
  return {
434
251
  partition: row.partition,
@@ -328,7 +328,10 @@ END`);
328
328
  .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
329
329
  .get();
330
330
  if (marker !== null && marker.schema_version > schema.version) {
331
- throw new Error(`stored schema version ${marker.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
331
+ throw new StorageQueryError('sync.storage.schema_changed', {
332
+ storedVersion: String(marker.schema_version),
333
+ configuredVersion: String(schema.version),
334
+ });
332
335
  }
333
336
  if (marker !== null && marker.schema_version === schema.version) {
334
337
  assertStoredLayouts(schema, marker.layouts);
@@ -407,7 +410,10 @@ END`);
407
410
  .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
408
411
  .get();
409
412
  if (locked !== null && locked.schema_version > schema.version) {
410
- throw new Error(`stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
413
+ throw new StorageQueryError('sync.storage.schema_changed', {
414
+ storedVersion: String(locked.schema_version),
415
+ configuredVersion: String(schema.version),
416
+ });
411
417
  }
412
418
  if (locked !== null && locked.schema_version === schema.version) {
413
419
  this.db.exec('COMMIT');
package/dist/storage.d.ts CHANGED
@@ -369,6 +369,77 @@ export interface ClientRecordWriteOptions {
369
369
  }
370
370
  /** The round-state fields of a stored `sync_clients` row. */
371
371
  export declare function clientRoundState(lastRoundAtMs: number | null, lastErrorCode: string | null, consecutiveFailures: number): Pick<ClientRecord, 'lastRoundAtMs' | 'lastErrorCode' | 'consecutiveFailures'>;
372
+ /**
373
+ * Some drivers return a JSON column already parsed (pglite, node-postgres);
374
+ * SQLite returns the `TEXT`.
375
+ */
376
+ export declare function asJson<T>(value: unknown): T;
377
+ /** Native SQLite and Postgres return `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
378
+ export declare function asUint8Array(value: unknown): Uint8Array;
379
+ /**
380
+ * Convert a push result to the JSON-able object both SQL backends store.
381
+ * `serverRow` bytes are base64-encoded: JSON cannot hold raw bytes.
382
+ */
383
+ export declare function pushResultToJson(result: StoredPushResult): unknown;
384
+ export declare function pushResultFromJson(value: unknown): StoredPushResult;
385
+ /** Row shapes the SQL backends' `SELECT`s return; values are driver-typed. */
386
+ export interface StoredRowRecord {
387
+ row_id: string;
388
+ server_version: unknown;
389
+ scopes: unknown;
390
+ payload: unknown;
391
+ column_versions: unknown;
392
+ }
393
+ export interface StoredChangeRecord {
394
+ tbl: string;
395
+ row_id: string;
396
+ op: unknown;
397
+ row_version: unknown;
398
+ scopes: unknown;
399
+ payload: unknown;
400
+ }
401
+ export interface StoredReactionRecord {
402
+ idempotency_key: string;
403
+ type: string;
404
+ version: unknown;
405
+ payload: unknown;
406
+ source_client_id: string;
407
+ source_client_commit_id: string;
408
+ source_commit_seq: unknown;
409
+ created_at_ms: unknown;
410
+ available_at_ms: unknown;
411
+ status: StoredReaction['status'];
412
+ attempts: unknown;
413
+ max_attempts: unknown;
414
+ lease_owner: string | null;
415
+ lease_expires_at_ms: unknown | null;
416
+ completed_at_ms: unknown | null;
417
+ last_failure: unknown | null;
418
+ }
419
+ export interface ClientRowRecord {
420
+ client_id: string;
421
+ actor_id: string;
422
+ wire_version: unknown;
423
+ cursor: unknown;
424
+ updated_at_ms: unknown;
425
+ schema_version: unknown;
426
+ units: unknown;
427
+ registration_digest: unknown;
428
+ catching_up: unknown;
429
+ last_round_at_ms: unknown;
430
+ last_error_code: string | null;
431
+ consecutive_failures: unknown;
432
+ }
433
+ export declare function toStoredRow(record: StoredRowRecord): StoredRow;
434
+ export declare function toTombstone(record: {
435
+ commit_seq: unknown;
436
+ server_version: unknown;
437
+ scopes: unknown;
438
+ }): Tombstone;
439
+ export declare function toStoredChange(record: StoredChangeRecord): StoredChange;
440
+ export declare function toStoredReaction(record: StoredReactionRecord): StoredReaction;
441
+ export declare const CLIENT_RECORD_COLUMNS = "client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures";
442
+ export declare function toClientRecord(record: ClientRowRecord): ClientRecord;
372
443
  /** One unit of the §4.5 scan set. */
373
444
  export interface LiveScanUnit {
374
445
  /** The unit's scope map; its first variable (keys sorted) is its index key. */