@syncular/client 0.57.0 → 0.59.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 (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
@@ -1,6 +1,30 @@
1
1
  import { ProgressEmitter, } from './progress.js';
2
+ /**
3
+ * Main-thread side of the worker mode and the
4
+ * multi-tab topology.
5
+ *
6
+ * `createSyncClientHandle` acquires the Web Locks leader lock and, when it
7
+ * wins, spawns the worker running the WHOLE core — so exactly one core runs
8
+ * per origin (the lock IS the invariant: a worker is NEVER spawned without
9
+ * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
10
+ * async proxy over the `worker-protocol` RPC.
11
+ *
12
+ * Multi-tab is the DEFAULT. The follower path is
13
+ * conformance-covered): a tab that LOSES the election becomes a FOLLOWER
14
+ * (`role === 'follower'`) that proxies every call to the leader tab over a
15
+ * BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
16
+ * lock releases; the followers contest, the winner PROMOTES in place —
17
+ * spawns the worker over the persisted OPFS database and re-announces — and
18
+ * the handle's `role` flips to `'leader'` with `onRoleChange` firing. The
19
+ * same handle object is kept across the transition so React bindings hold a
20
+ * stable reference.
21
+ *
22
+ * With `multiTab: false`, the loser is an `isLeader === false` handle whose
23
+ * calls reject with `client.not_leader` (the single-tab contract).
24
+ */
25
+ import { serializeBlobRef, } from '@syncular/core';
2
26
  import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
3
- import { ClientSyncError } from './errors.js';
27
+ import { ClientSyncError, invalidRequest } from './errors.js';
4
28
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
5
29
  import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
6
30
  import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
@@ -18,7 +42,7 @@ export function workerStartupError(message) {
18
42
  /** Derive the complete ownership tuple for an independently owned replica. */
19
43
  export function isolatedReplicaNames(options) {
20
44
  if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
21
- throw new ClientSyncError('sync.invalid_request', 'an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
45
+ throw invalidRequest('an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
22
46
  }
23
47
  const suffix = `--replica-${options.replicaId}`;
24
48
  const databaseName = `${options.databaseName}${suffix}`;
@@ -131,6 +155,11 @@ export class SyncClientHandle {
131
155
  this.#clientId = state.clientId;
132
156
  if (state.state === 'follower')
133
157
  this.#clientId = state.leaderClientId;
158
+ // A new leader starts a fresh core that no tab has pulled from yet.
159
+ if (this.#diagnostics.observed &&
160
+ (state.state === 'leader' || state.state === 'follower')) {
161
+ this.#pullDiagnostics();
162
+ }
134
163
  for (const listener of this.#leadershipListeners) {
135
164
  try {
136
165
  listener(state);
@@ -160,7 +189,7 @@ export class SyncClientHandle {
160
189
  else if (event.kind === 'presence') {
161
190
  for (const listener of this.#presence) {
162
191
  try {
163
- listener(event.scopeKey);
192
+ listener(event.scopeKey, event.error);
164
193
  }
165
194
  catch {
166
195
  /* a UI listener must never break event dispatch */
@@ -200,7 +229,17 @@ export class SyncClientHandle {
200
229
  return this.#changes.on(listener);
201
230
  }
202
231
  onDiagnostics(listener) {
203
- return this.#diagnostics.on(listener);
232
+ const off = this.#diagnostics.on(listener);
233
+ this.#pullDiagnostics();
234
+ return off;
235
+ }
236
+ /**
237
+ * The worker pushes diagnostics only after a consumer pulled once. A handle
238
+ * that cannot reach a core has nothing to observe, so a failed pull is
239
+ * dropped.
240
+ */
241
+ #pullDiagnostics() {
242
+ void this.diagnosticsSnapshot().catch(() => undefined);
204
243
  }
205
244
  /**
206
245
  * §8.6: subscribe to presence changes — the identical surface as
@@ -402,6 +441,10 @@ export class SyncClientHandle {
402
441
  uploadBlob(bytes, options) {
403
442
  return this.#call('uploadBlob', [bytes, options]);
404
443
  }
444
+ /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
445
+ blobRefString(ref) {
446
+ return serializeBlobRef(ref);
447
+ }
405
448
  fetchBlob(blobIdOrRef) {
406
449
  return this.#call('fetchBlob', [blobIdOrRef]);
407
450
  }
@@ -461,7 +504,15 @@ export class SyncClientHandle {
461
504
  */
462
505
  async function startWorkerCore(options) {
463
506
  const { config, initConfig, lease } = options;
464
- const worker = config.worker();
507
+ let worker;
508
+ try {
509
+ worker = config.worker();
510
+ }
511
+ catch (error) {
512
+ // No worker exists to terminate; the lease is the only thing held.
513
+ await lease.release();
514
+ throw error;
515
+ }
465
516
  const pending = new Map();
466
517
  const nextId = { value: 1 };
467
518
  let terminated = false;
@@ -546,6 +597,9 @@ async function startWorkerCore(options) {
546
597
  config: initConfig,
547
598
  });
548
599
  });
600
+ // A config callback is a consumer from the first round.
601
+ if (config.onDiagnostics !== undefined)
602
+ await invoke('diagnosticsSnapshot', []);
549
603
  return {
550
604
  clientId: initResult.clientId,
551
605
  invoke,
@@ -596,6 +650,9 @@ function buildInitConfig(config, headers = config.headers) {
596
650
  ...(config.realtimePolicy !== undefined
597
651
  ? { realtimePolicy: config.realtimePolicy }
598
652
  : {}),
653
+ ...(config.realtimeHeartbeatMs !== undefined
654
+ ? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
655
+ : {}),
599
656
  ...(config.previousVersionContext !== undefined
600
657
  ? { previousVersionContext: config.previousVersionContext }
601
658
  : {}),
@@ -614,7 +671,7 @@ function fireConfigCallbacks(config, event) {
614
671
  config.onUpgrading?.(event.upgrading);
615
672
  }
616
673
  else if (event.kind === 'presence') {
617
- config.onPresence?.(event.scopeKey);
674
+ config.onPresence?.(event.scopeKey, event.error);
618
675
  }
619
676
  else if (event.kind === 'synced') {
620
677
  config.onSynced?.({
@@ -783,7 +840,7 @@ function resolveReplicaConfig(config) {
783
840
  if (config.replica?.mode !== 'isolated')
784
841
  return config;
785
842
  if (config.database.mode !== 'persistent') {
786
- throw new ClientSyncError('sync.invalid_request', 'isolated browser replicas require a named persistent database');
843
+ throw invalidRequest('isolated browser replicas require a named persistent database');
787
844
  }
788
845
  const names = isolatedReplicaNames({
789
846
  databaseName: config.database.name,
@@ -1,4 +1,4 @@
1
- import { ClientSyncError } from './errors.js';
1
+ import { ClientSyncError, invalidRequest } from './errors.js';
2
2
  import { LOCAL_AUTHORITY_UNCONFIGURED_CODE } from './worker-protocol.js';
3
3
  /** §12 behavior loaded by the authority-enabled worker entry. */
4
4
  export const createWorkerLocalAuthority = (context) => {
@@ -58,7 +58,7 @@ export const createWorkerLocalAuthority = (context) => {
58
58
  if (active())
59
59
  return local.downloadSegment(request);
60
60
  if (segments === undefined) {
61
- throw new ClientSyncError('sync.invalid_request', 'no segment endpoint configured');
61
+ throw invalidRequest('no segment endpoint configured');
62
62
  }
63
63
  return segments(request);
64
64
  },
@@ -17,7 +17,7 @@ import type { SyncProgress } from './progress.js';
17
17
  * so the UI thread never has to react to keep data flowing. Events are
18
18
  * still forwarded to the handle for visibility.
19
19
  */
20
- import type { WakeReason } from '@syncular/core';
20
+ import type { PresenceErrorCode, WakeReason } from '@syncular/core';
21
21
  import type { BlobRef, CachedBlob } from './blob.js';
22
22
  import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
23
23
  import type { SqlRow, SqlValue } from './database.js';
@@ -107,6 +107,8 @@ export interface WorkerInitConfig {
107
107
  * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
108
108
  */
109
109
  readonly realtimePolicy?: RealtimePolicy;
110
+ /** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
111
+ readonly realtimeHeartbeatMs?: number;
110
112
  /**
111
113
  * RFC 0005 previous-version context, forwarded verbatim into the worker's
112
114
  * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -231,9 +233,11 @@ export type SyncWorkerEvent = {
231
233
  readonly kind: 'upgrading';
232
234
  readonly upgrading: boolean;
233
235
  } | {
234
- /** §8.6: presence on a scope key changed inside the worker. */
236
+ /** §8.6: presence on a scope key changed, or the server refused this
237
+ * client's publish on it (`error`, §8.6.2). */
235
238
  readonly kind: 'presence';
236
239
  readonly scopeKey: string;
240
+ readonly error?: PresenceErrorCode | undefined;
237
241
  } | {
238
242
  /** Exact revisioned core transaction; Sets and bigint clone directly. */
239
243
  readonly kind: 'change';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.57.0",
3
+ "version": "0.59.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -89,6 +89,14 @@
89
89
  "types": "./dist/authority.d.ts",
90
90
  "default": "./dist/authority.js"
91
91
  }
92
+ },
93
+ "./native-bridge": {
94
+ "bun": "./src/native-bridge.ts",
95
+ "browser": "./dist/native-bridge.js",
96
+ "import": {
97
+ "types": "./dist/native-bridge.d.ts",
98
+ "default": "./dist/native-bridge.js"
99
+ }
92
100
  }
93
101
  },
94
102
  "files": [
@@ -105,11 +113,11 @@
105
113
  },
106
114
  "dependencies": {
107
115
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
108
- "@syncular/core": "0.57.0"
116
+ "@syncular/core": "0.59.0"
109
117
  },
110
118
  "devDependencies": {
111
119
  "@electric-sql/pglite": "^0.5.4",
112
- "@syncular/server": "0.57.0",
120
+ "@syncular/server": "0.59.0",
113
121
  "playwright": "1.63.0",
114
122
  "vite": "8.3.4"
115
123
  }
package/src/apply.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { hasUniqueIndex } from './schema';
2
- import { OUTBOX_TABLE, OUTBOX_IMAGES, countOutbox } from './outbox';
2
+ import { OUTBOX_IMAGES, countOutbox } from './outbox';
3
3
  import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
4
4
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
5
5
  /**
@@ -132,7 +132,7 @@ export async function applyCommitFrame(
132
132
  throw invalidRequest('upsert change without row payload');
133
133
  }
134
134
  let values = decodeRow(table.columns, change.row);
135
- if (encryption !== undefined && table.hasEncryptedColumns) {
135
+ if (table.hasEncryptedColumns) {
136
136
  const { decryptRowValues } = await import('./encryption');
137
137
  values = await decryptRowValues(encryption, table, values);
138
138
  }
@@ -144,18 +144,19 @@ export async function applyCommitFrame(
144
144
  });
145
145
  }
146
146
  transaction(() => {
147
- const scope = resolved.map((change, index) =>
148
- JSON.stringify(
149
- hasUniqueIndex(change.table)
150
- ? [change.table.name]
151
- : [change.table.name, frame.changes[index]!.rowId],
152
- ),
153
- );
147
+ // Exact keys name the rows this frame rebases; unique-key peers widen the
148
+ // replay to the table.
149
+ const scope = resolved.flatMap((change, index) => [
150
+ ...(hasUniqueIndex(change.table)
151
+ ? [JSON.stringify([change.table.name])]
152
+ : []),
153
+ JSON.stringify([change.table.name, frame.changes[index]!.rowId]),
154
+ ]);
154
155
  restoreFailedBases(db, schema, scope);
155
156
  for (const [index, change] of resolved.entries()) {
156
157
  const rowId = frame.changes[index]!.rowId;
157
158
  db.exec(
158
- `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM ${OUTBOX_TABLE},json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)`,
159
+ `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
159
160
  [frame.commitSeq, change.table.name, rowId],
160
161
  );
161
162
  db.exec(
@@ -212,15 +213,19 @@ export function validateSegmentColumns(
212
213
  }
213
214
 
214
215
  /**
215
- * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
216
- * rows whose generated local scope columns match `effective` — every key's
217
- * column value must be in the key's value list. Fails closed
218
- * (`sync.scope_revoked`) when the table has no local mapping for a key:
219
- * precision or nothing, never clear-the-table.
216
+ * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
217
+ * rule): delete rows whose generated local scope columns match `effective`
218
+ * (every key's column value must be in the key's value list) and that no
219
+ * entry of `owners` matches. `owners` holds the effective scopes of every
220
+ * other active subscription on the table that holds rows; a row one of them
221
+ * still covers is never removed. Fails closed (`sync.scope_revoked`) when
222
+ * the table has no local mapping for a key: precision or nothing, never
223
+ * clear-the-table.
220
224
  */
221
225
  export function localScopePredicate(
222
226
  table: CompiledClientTable,
223
227
  effective: ScopeMap,
228
+ owners: readonly ScopeMap[],
224
229
  ): { sql: string; params: string[] } | undefined {
225
230
  const entries = Object.entries(effective);
226
231
  if (!entries.length || entries.some(([, values]) => !values.length)) return;
@@ -237,7 +242,26 @@ export function localScopePredicate(
237
242
  return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
238
243
  })
239
244
  .join(' AND ');
240
- return { sql, params };
245
+ const kept = owners.flatMap((owner) => {
246
+ const scope = localScopePredicate(table, owner, []);
247
+ if (scope === undefined) return [];
248
+ params.push(...scope.params);
249
+ return [` AND NOT (${scope.sql})`];
250
+ });
251
+ return { sql: sql + kept.join(''), params };
252
+ }
253
+
254
+ /** {@link localScopePredicate} over decoded row values (retained rows). */
255
+ export function ownsLocalRow(
256
+ table: CompiledClientTable,
257
+ effective: ScopeMap,
258
+ owners: readonly ScopeMap[],
259
+ values: Readonly<Record<string, JsonRowValue>>,
260
+ ): boolean {
261
+ return (
262
+ matchesLocalScopes(table, effective, values) &&
263
+ !owners.some((owner) => matchesLocalScopes(table, owner, values))
264
+ );
241
265
  }
242
266
 
243
267
  function scopedRows(
@@ -257,8 +281,13 @@ function bootstrapScope(
257
281
  db: ClientDatabase,
258
282
  table: CompiledClientTable,
259
283
  effective: ScopeMap,
284
+ owners: readonly ScopeMap[],
260
285
  ): string[] {
261
- const rows = scopedRows(db, table, localScopePredicate(table, effective));
286
+ const rows = scopedRows(
287
+ db,
288
+ table,
289
+ localScopePredicate(table, effective, owners),
290
+ );
262
291
  rows.push(
263
292
  ...db
264
293
  .query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
@@ -268,7 +297,7 @@ function bootstrapScope(
268
297
  [row.base, row.intent].some(
269
298
  (json) =>
270
299
  json !== null &&
271
- matchesLocalScopes(table, effective, JSON.parse(json as string)),
300
+ ownsLocalRow(table, effective, owners, JSON.parse(json as string)),
272
301
  ),
273
302
  ),
274
303
  );
@@ -279,8 +308,9 @@ export function deleteScopedRows(
279
308
  db: ClientDatabase,
280
309
  table: CompiledClientTable,
281
310
  effective: ScopeMap,
311
+ owners: readonly ScopeMap[],
282
312
  ): void {
283
- const scope = localScopePredicate(table, effective);
313
+ const scope = localScopePredicate(table, effective, owners);
284
314
  if (!scope) return;
285
315
  const { sql, params } = scope;
286
316
  for (const row of scopedRows(db, table, scope)) {
@@ -291,8 +321,8 @@ export function deleteScopedRows(
291
321
 
292
322
  /**
293
323
  * §4.8 window eviction: delete rows matching a departing unit's effective
294
- * scopes (same local-scope-column rule and fail-closed clause as
295
- * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
324
+ * scopes (same local-scope-column rule, owner exclusion and fail-closed
325
+ * clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
296
326
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
297
327
  * whether unpinned work remains and whether any scoped rows remain. Each
298
328
  * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
@@ -303,9 +333,10 @@ export function evictScopedRows(
303
333
  db: ClientDatabase,
304
334
  table: CompiledClientTable,
305
335
  effective: ScopeMap,
336
+ owners: readonly ScopeMap[],
306
337
  pinnedRowIds: ReadonlySet<string>,
307
338
  ): { remaining: boolean; deferred: boolean } {
308
- const scope = localScopePredicate(table, effective);
339
+ const scope = localScopePredicate(table, effective, owners);
309
340
  if (!scope) return { remaining: false, deferred: false };
310
341
  const { sql, params } = scope;
311
342
  const pk = quoteIdent(table.primaryKey);
@@ -325,9 +356,10 @@ export function evictScopedRows(
325
356
  [row.intent, row.base].some(
326
357
  (json) =>
327
358
  json !== null &&
328
- matchesLocalScopes(
359
+ ownsLocalRow(
329
360
  table,
330
361
  effective,
362
+ owners,
331
363
  JSON.parse(json as string) as Record<string, JsonRowValue>,
332
364
  ),
333
365
  )
@@ -386,6 +418,8 @@ export async function applySqliteSegment(
386
418
  options: {
387
419
  readonly clearFirst: boolean;
388
420
  readonly effective: ScopeMap;
421
+ /** Effective scopes of the other row-holding subscriptions (§5.6). */
422
+ readonly owners: readonly ScopeMap[];
389
423
  readonly transaction?: ApplyTransaction;
390
424
  readonly onProgress?: (rowsProcessed: number) => void;
391
425
  readonly isCurrent?: () => boolean;
@@ -400,6 +434,9 @@ export async function applySqliteSegment(
400
434
  if (descriptor.table !== table.name) {
401
435
  imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
402
436
  }
437
+ // §5.11: an image bypasses the decrypt seam, so a server cannot serve one
438
+ // for a table with encrypted columns.
439
+ if (table.hasEncryptedColumns) imageInvalid('table has encrypted columns');
403
440
  return withImage(bytes, IMAGE_ALIAS, async () => {
404
441
  // 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
405
442
  // SQLite database or lacks the metadata table fails right here.
@@ -499,19 +536,18 @@ export async function applySqliteSegment(
499
536
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
500
537
  const scope = !replay
501
538
  ? []
502
- : hasUniqueIndex(table)
503
- ? [JSON.stringify([table.name])]
504
- : [
505
- ...(after === undefined && options.clearFirst
506
- ? bootstrapScope(db, table, options.effective)
507
- : []),
508
- ...rows.map((row) =>
509
- JSON.stringify([table.name, String(row[table.primaryKey])]),
510
- ),
511
- ];
539
+ : [
540
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
541
+ ...(after === undefined && options.clearFirst
542
+ ? bootstrapScope(db, table, options.effective, options.owners)
543
+ : []),
544
+ ...rows.map((row) =>
545
+ JSON.stringify([table.name, String(row[table.primaryKey])]),
546
+ ),
547
+ ];
512
548
  const protectedRows = restoreFailedBases(db, schema, scope);
513
549
  if (after === undefined && options.clearFirst)
514
- deleteScopedRows(db, table, options.effective);
550
+ deleteScopedRows(db, table, options.effective, options.owners);
515
551
  db.exec(
516
552
  `INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${predicates.join(' AND ') || 'true'} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`,
517
553
  params,
@@ -561,6 +597,8 @@ export async function applyRowsSegment(
561
597
  options: {
562
598
  readonly clearFirst: boolean;
563
599
  readonly effective: ScopeMap;
600
+ /** Effective scopes of the other row-holding subscriptions (§5.6). */
601
+ readonly owners: readonly ScopeMap[];
564
602
  readonly transaction?: ApplyTransaction;
565
603
  readonly onProgress?: (rowsProcessed: number) => void;
566
604
  readonly isCurrent?: () => boolean;
@@ -579,13 +617,12 @@ export async function applyRowsSegment(
579
617
  // aborts before any write in this block.
580
618
  const rows: { values: readonly RowValue[]; serverVersion: number }[] = [];
581
619
  for (const row of block) {
582
- const values =
583
- encryption !== undefined && table.hasEncryptedColumns
584
- ? await (async () => {
585
- const { decryptRowValues } = await import('./encryption');
586
- return decryptRowValues(encryption, table, row.values);
587
- })()
588
- : row.values;
620
+ const values = table.hasEncryptedColumns
621
+ ? await (async () => {
622
+ const { decryptRowValues } = await import('./encryption');
623
+ return decryptRowValues(encryption, table, row.values);
624
+ })()
625
+ : row.values;
589
626
  rows.push({ values, serverVersion: row.serverVersion });
590
627
  }
591
628
  if (options.isCurrent?.() === false) break;
@@ -593,22 +630,21 @@ export async function applyRowsSegment(
593
630
  first = false;
594
631
  if (!clearThisBlock && rows.length === 0) continue;
595
632
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
596
- const scope: OverlayScope = hasUniqueIndex(table)
597
- ? [JSON.stringify([table.name])]
598
- : [
599
- ...(clearThisBlock
600
- ? bootstrapScope(db, table, options.effective)
601
- : []),
602
- ...rows.map((row) =>
603
- JSON.stringify([
604
- table.name,
605
- String(row.values[table.primaryKeyIndex]),
606
- ]),
607
- ),
608
- ];
633
+ const scope: OverlayScope = [
634
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
635
+ ...(clearThisBlock
636
+ ? bootstrapScope(db, table, options.effective, options.owners)
637
+ : []),
638
+ ...rows.map((row) =>
639
+ JSON.stringify([
640
+ table.name,
641
+ String(row.values[table.primaryKeyIndex]),
642
+ ]),
643
+ ),
644
+ ];
609
645
  const protectedRows = restoreFailedBases(db, schema, scope);
610
646
  if (clearThisBlock) {
611
- deleteScopedRows(db, table, options.effective);
647
+ deleteScopedRows(db, table, options.effective, options.owners);
612
648
  }
613
649
  for (const row of rows) {
614
650
  upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
package/src/blob.ts CHANGED
@@ -42,22 +42,33 @@ export type BlobUploadGrant =
42
42
  | { readonly kind: 'present' }
43
43
  | { readonly kind: 'none' };
44
44
 
45
- /** The transport seam for blob upload/download (§5.9.3/§5.9.5). */
45
+ /**
46
+ * The transport seam for blob upload/download (§5.9.3/§5.9.5). The upload
47
+ * calls receive the round's `signal`, which aborts when the `syncUntilIdle`
48
+ * deadline elapses (§7.7).
49
+ */
46
50
  export interface BlobTransport {
47
51
  /** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
48
- upload(blobId: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
52
+ upload(
53
+ blobId: string,
54
+ bytes: Uint8Array,
55
+ mediaType?: string,
56
+ signal?: AbortSignal,
57
+ ): Promise<void>;
49
58
  /**
50
59
  * `GET <mount>/blobs/{blobId}` — re-authorized (§5.9.5). Returns inline
51
60
  * bytes, or a presigned `url` the client core fetches via `fetchUrl`.
61
+ * `byteLength` is the BlobRef's declared size when the caller passed one;
62
+ * reading inline bytes stops once the body exceeds it.
52
63
  */
53
- download(blobId: string): Promise<BlobDownloadResponse>;
64
+ download(blobId: string, byteLength?: number): Promise<BlobDownloadResponse>;
54
65
  /**
55
66
  * §5.9.5 presigned-download fetch: a bare GET of the signed `url`. Present
56
67
  * iff the transport can consume URLs. MUST attach NO host authentication —
57
68
  * the URL is the entire grant (§5.4). Only called when `download` returned
58
- * a `url` arm.
69
+ * a `url` arm. Reading stops once the body exceeds `byteLength`.
59
70
  */
60
- fetchUrl?(url: string): Promise<Uint8Array>;
71
+ fetchUrl?(url: string, byteLength?: number): Promise<Uint8Array>;
61
72
  /**
62
73
  * §5.9.3 presigned-upload grant: `POST /blobs/{blobId}/upload-grant` with
63
74
  * the declared size. Present iff the transport supports the grant flow;
@@ -68,16 +79,20 @@ export interface BlobTransport {
68
79
  blobId: string,
69
80
  byteLength: number,
70
81
  mediaType?: string,
82
+ signal?: AbortSignal,
71
83
  ): Promise<BlobUploadGrant>;
72
84
  /**
73
85
  * §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
74
- * authentication — the presigned URL is the entire grant (§5.4). Only
75
- * called when `uploadGrant` returned a `url` arm.
86
+ * authentication — the presigned URL is the entire grant (§5.4) — and MUST
87
+ * send `x-amz-checksum-sha256` (base64 of the body's SHA-256), which the
88
+ * grant signs beside `content-length`. Only called when `uploadGrant`
89
+ * returned a `url` arm.
76
90
  */
77
91
  uploadToUrl?(
78
92
  url: string,
79
93
  bytes: Uint8Array,
80
94
  mediaType?: string,
95
+ signal?: AbortSignal,
81
96
  ): Promise<void>;
82
97
  }
83
98
 
@@ -188,7 +203,7 @@ export function enforceBlobCacheCap(
188
203
  if (total <= maxBytes) return [];
189
204
  // Oldest eligible body first, with blob ID as a stable tie.
190
205
  const candidates = db.query(
191
- `SELECT blob_id,byte_length FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})ORDER BY created_at_ms ASC,blob_id ASC`,
206
+ `SELECT blob_id,byte_length ${unreferencedBlobsSql(schema)}ORDER BY created_at_ms ASC,blob_id ASC`,
192
207
  );
193
208
  const evicted: string[] = [];
194
209
  db.transaction(() => {
@@ -266,7 +281,8 @@ export function schemaHasBlobs(schema: CompiledClientSchema): boolean {
266
281
  return false;
267
282
  }
268
283
 
269
- function visibleBlobIdsSql(schema: CompiledClientSchema): string {
284
+ /** The cached bodies no upload, pending commit, or visible row references. */
285
+ function unreferencedBlobsSql(schema: CompiledClientSchema): string {
270
286
  const selects: string[] = [];
271
287
  for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
272
288
  for (const column of columns) {
@@ -276,18 +292,14 @@ function visibleBlobIdsSql(schema: CompiledClientSchema): string {
276
292
  );
277
293
  }
278
294
  }
279
- return selects.length === 0
280
- ? 'SELECT NULL AS blob_id WHERE 0'
281
- : selects.join(' UNION ');
295
+ return `FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${selects.length === 0 ? 'SELECT NULL AS blob_id WHERE 0' : selects.join(' UNION ')})`;
282
296
  }
283
297
 
284
298
  export function deleteUnreferencedCachedBlobs(
285
299
  db: ClientDatabase,
286
300
  schema: CompiledClientSchema,
287
301
  ): void {
288
- db.exec(
289
- `DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`,
290
- );
302
+ db.exec(`DELETE ${unreferencedBlobsSql(schema)}`);
291
303
  }
292
304
 
293
305
  export type { BlobRef };
@@ -15,6 +15,7 @@ import {
15
15
  type SqlRow,
16
16
  type SqlValue,
17
17
  } from './database';
18
+ import { prepareReadOnly, refuseRawSql } from './query-guard';
18
19
 
19
20
  declare module 'bun:sqlite' {
20
21
  interface Database {
@@ -64,6 +65,34 @@ export class BunClientDatabase implements ClientDatabase {
64
65
  return this.db.query(sql).all(...coerceParams(params)) as SqlRow[];
65
66
  }
66
67
 
68
+ queryReadOnly(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
69
+ const statement = prepareReadOnly(sql, () => {
70
+ const prepared = this.db.query(sql);
71
+ // bun:sqlite exposes no `sqlite3_sql`, so the first statement ends at
72
+ // the first `;` outside literals, identifiers and comments.
73
+ return [
74
+ prepared,
75
+ /^(?:'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[^;])*/.exec(
76
+ sql,
77
+ )![0],
78
+ prepared.columnNames.length > 0,
79
+ ] as const;
80
+ });
81
+ // bun:sqlite exposes `sqlite3_stmt_readonly` only from Bun 1.4.4, so
82
+ // SQLite refuses a write when the statement runs: under `query_only` a
83
+ // write transaction fails before it changes anything.
84
+ this.db.run('PRAGMA query_only = ON');
85
+ try {
86
+ return statement.all(...coerceParams(params)) as SqlRow[];
87
+ } catch (error) {
88
+ if ((error as { code?: unknown }).code === 'SQLITE_READONLY')
89
+ refuseRawSql();
90
+ throw error;
91
+ } finally {
92
+ this.db.run('PRAGMA query_only = OFF');
93
+ }
94
+ }
95
+
67
96
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
68
97
  openSibling(name: string): SiblingDatabase {
69
98
  const siblingPath =