@syncular/client 0.58.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
package/README.md CHANGED
@@ -14,9 +14,9 @@ server-authoritative commands, and live query watches through the remote
14
14
  operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
15
15
  Its schema and sync transport are optional for query-only or command-only
16
16
  processes.
17
- Ordinary commits use wire version 1 until the caller supplies an acquired
18
- partition `logEpoch`. Set `logEpoch` after a restore rotation requires epoch
19
- validation.
17
+ Without a `logEpoch`, the first `prepareCommit` sends one empty pull to learn
18
+ the partition log epoch and binds every later commit to it; set `logEpoch` in
19
+ the constructor to skip that round.
20
20
 
21
21
  Applied and cached acknowledgements drain the send queue while protected local
22
22
  intent stays visible until the same row's server image arrives at that commit
@@ -315,8 +315,8 @@ stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
315
315
  During Vite development, retain the React client resource only while its
316
316
  captured generated schema version and published Syncular runtime identity both
317
317
  match. The
318
- [schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-install/#configure-vite) uses
319
- `retainViteSyncClientResource` to close the old worker before constructing a
318
+ [schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-realtime/#keep-one-owner-during-hmr) uses
319
+ `createViteSyncClientResource` to close the old worker before constructing a
320
320
  schema-bump or package-upgrade replacement; hot-reloading query code alone does
321
321
  not migrate the worker-owned database.
322
322
 
@@ -740,8 +740,8 @@ bun run build:packages && bun run verify:packages
740
740
 
741
741
  `init`, `call`, `ready`, `result`, `error`, `event` — every API method
742
742
  multiplexes over `call` (typed end-to-end from the single `WorkerApi`
743
- shape in `worker-protocol.ts`); `event` carries `sync-needed`,
744
- `change`, `conflict` and `synced`. Query-result blobs transfer (not copy) when
743
+ shape in `worker-protocol.ts`); `event` carries `progress`, `sync-needed`,
744
+ `conflict`, `synced`, `upgrading`, `presence`, `change` and `diagnostics`. Query-result blobs transfer (not copy) when
745
745
  they own their buffer.
746
746
 
747
747
  ## Package layout
package/dist/apply.d.ts CHANGED
@@ -7,7 +7,7 @@ import { type OverlayScope } from './failed-overlay.js';
7
7
  import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from '@syncular/core';
8
8
  import type { ClientDatabase } from './database.js';
9
9
  import type { EncryptionConfig } from './encryption.js';
10
- import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
10
+ import { type CompiledClientSchema, type CompiledClientTable, type JsonRowValue } from './schema.js';
11
11
  /** Lets the client wrap the physical write in its revision transaction. */
12
12
  export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
13
13
  export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
@@ -32,28 +32,33 @@ export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledCli
32
32
  */
33
33
  export declare function validateSegmentColumns(schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment): void;
34
34
  /**
35
- * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
36
- * rows whose generated local scope columns match `effective` — every key's
37
- * column value must be in the key's value list. Fails closed
38
- * (`sync.scope_revoked`) when the table has no local mapping for a key:
39
- * precision or nothing, never clear-the-table.
35
+ * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
36
+ * rule): delete rows whose generated local scope columns match `effective`
37
+ * (every key's column value must be in the key's value list) and that no
38
+ * entry of `owners` matches. `owners` holds the effective scopes of every
39
+ * other active subscription on the table that holds rows; a row one of them
40
+ * still covers is never removed. Fails closed (`sync.scope_revoked`) when
41
+ * the table has no local mapping for a key: precision or nothing, never
42
+ * clear-the-table.
40
43
  */
41
- export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap): {
44
+ export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): {
42
45
  sql: string;
43
46
  params: string[];
44
47
  } | undefined;
45
- export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap): void;
48
+ /** {@link localScopePredicate} over decoded row values (retained rows). */
49
+ export declare function ownsLocalRow(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], values: Readonly<Record<string, JsonRowValue>>): boolean;
50
+ export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): void;
46
51
  /**
47
52
  * §4.8 window eviction: delete rows matching a departing unit's effective
48
- * scopes (same local-scope-column rule and fail-closed clause as
49
- * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
53
+ * scopes (same local-scope-column rule, owner exclusion and fail-closed
54
+ * clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
50
55
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
51
56
  * whether unpinned work remains and whether any scoped rows remain. Each
52
57
  * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
53
58
  * evicted rows' `server_version` with them (E2 — no residual version
54
59
  * cache), which is automatic since the version column is per-row.
55
60
  */
56
- export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): {
61
+ export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], pinnedRowIds: ReadonlySet<string>): {
57
62
  remaining: boolean;
58
63
  deferred: boolean;
59
64
  };
@@ -75,6 +80,8 @@ export interface SqliteSegmentDescriptor {
75
80
  export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
76
81
  readonly clearFirst: boolean;
77
82
  readonly effective: ScopeMap;
83
+ /** Effective scopes of the other row-holding subscriptions (§5.6). */
84
+ readonly owners: readonly ScopeMap[];
78
85
  readonly transaction?: ApplyTransaction;
79
86
  readonly onProgress?: (rowsProcessed: number) => void;
80
87
  readonly isCurrent?: () => boolean;
@@ -90,6 +97,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
90
97
  export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
91
98
  readonly clearFirst: boolean;
92
99
  readonly effective: ScopeMap;
100
+ /** Effective scopes of the other row-holding subscriptions (§5.6). */
101
+ readonly owners: readonly ScopeMap[];
93
102
  readonly transaction?: ApplyTransaction;
94
103
  readonly onProgress?: (rowsProcessed: number) => void;
95
104
  readonly isCurrent?: () => boolean;
package/dist/apply.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { hasUniqueIndex } from './schema.js';
2
- import { OUTBOX_TABLE, OUTBOX_IMAGES, countOutbox } from './outbox.js';
2
+ import { OUTBOX_IMAGES, countOutbox } from './outbox.js';
3
3
  import { RETAINED_ROWS } from './failed-overlay.js';
4
4
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
5
5
  /**
@@ -66,7 +66,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
66
66
  throw invalidRequest('upsert change without row payload');
67
67
  }
68
68
  let values = decodeRow(table.columns, change.row);
69
- if (encryption !== undefined && table.hasEncryptedColumns) {
69
+ if (table.hasEncryptedColumns) {
70
70
  const { decryptRowValues } = await import('./encryption.js');
71
71
  values = await decryptRowValues(encryption, table, values);
72
72
  }
@@ -78,13 +78,18 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
78
78
  });
79
79
  }
80
80
  transaction(() => {
81
- const scope = resolved.map((change, index) => JSON.stringify(hasUniqueIndex(change.table)
82
- ? [change.table.name]
83
- : [change.table.name, frame.changes[index].rowId]));
81
+ // Exact keys name the rows this frame rebases; unique-key peers widen the
82
+ // replay to the table.
83
+ const scope = resolved.flatMap((change, index) => [
84
+ ...(hasUniqueIndex(change.table)
85
+ ? [JSON.stringify([change.table.name])]
86
+ : []),
87
+ JSON.stringify([change.table.name, frame.changes[index].rowId]),
88
+ ]);
84
89
  restoreFailedBases(db, schema, scope);
85
90
  for (const [index, change] of resolved.entries()) {
86
91
  const rowId = frame.changes[index].rowId;
87
- db.exec(`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')=?)`, [frame.commitSeq, change.table.name, rowId]);
92
+ db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
88
93
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
89
94
  if (change.op === 'delete') {
90
95
  deleteLocalRow(db, change.table, change.rowId);
@@ -127,13 +132,16 @@ export function validateSegmentColumns(schema, table, segment) {
127
132
  }
128
133
  }
129
134
  /**
130
- * Scope-matched local delete (§3.3 purge / §5.6 first-page rule): delete
131
- * rows whose generated local scope columns match `effective` — every key's
132
- * column value must be in the key's value list. Fails closed
133
- * (`sync.scope_revoked`) when the table has no local mapping for a key:
134
- * precision or nothing, never clear-the-table.
135
+ * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
136
+ * rule): delete rows whose generated local scope columns match `effective`
137
+ * (every key's column value must be in the key's value list) and that no
138
+ * entry of `owners` matches. `owners` holds the effective scopes of every
139
+ * other active subscription on the table that holds rows; a row one of them
140
+ * still covers is never removed. Fails closed (`sync.scope_revoked`) when
141
+ * the table has no local mapping for a key: precision or nothing, never
142
+ * clear-the-table.
135
143
  */
136
- export function localScopePredicate(table, effective) {
144
+ export function localScopePredicate(table, effective, owners) {
137
145
  const entries = Object.entries(effective);
138
146
  if (!entries.length || entries.some(([, values]) => !values.length))
139
147
  return;
@@ -147,25 +155,37 @@ export function localScopePredicate(table, effective) {
147
155
  return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
148
156
  })
149
157
  .join(' AND ');
150
- return { sql, params };
158
+ const kept = owners.flatMap((owner) => {
159
+ const scope = localScopePredicate(table, owner, []);
160
+ if (scope === undefined)
161
+ return [];
162
+ params.push(...scope.params);
163
+ return [` AND NOT (${scope.sql})`];
164
+ });
165
+ return { sql: sql + kept.join(''), params };
166
+ }
167
+ /** {@link localScopePredicate} over decoded row values (retained rows). */
168
+ export function ownsLocalRow(table, effective, owners, values) {
169
+ return (matchesLocalScopes(table, effective, values) &&
170
+ !owners.some((owner) => matchesLocalScopes(table, owner, values)));
151
171
  }
152
172
  function scopedRows(db, table, scope) {
153
173
  return scope
154
174
  ? db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`, scope.params)
155
175
  : [];
156
176
  }
157
- function bootstrapScope(db, table, effective) {
158
- const rows = scopedRows(db, table, localScopePredicate(table, effective));
177
+ function bootstrapScope(db, table, effective, owners) {
178
+ const rows = scopedRows(db, table, localScopePredicate(table, effective, owners));
159
179
  rows.push(...db
160
180
  .query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
161
181
  table.name,
162
182
  ])
163
183
  .filter((row) => [row.base, row.intent].some((json) => json !== null &&
164
- matchesLocalScopes(table, effective, JSON.parse(json)))));
184
+ ownsLocalRow(table, effective, owners, JSON.parse(json)))));
165
185
  return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
166
186
  }
167
- export function deleteScopedRows(db, table, effective) {
168
- const scope = localScopePredicate(table, effective);
187
+ export function deleteScopedRows(db, table, effective, owners) {
188
+ const scope = localScopePredicate(table, effective, owners);
169
189
  if (!scope)
170
190
  return;
171
191
  const { sql, params } = scope;
@@ -176,16 +196,16 @@ export function deleteScopedRows(db, table, effective) {
176
196
  }
177
197
  /**
178
198
  * §4.8 window eviction: delete rows matching a departing unit's effective
179
- * scopes (same local-scope-column rule and fail-closed clause as
180
- * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
199
+ * scopes (same local-scope-column rule, owner exclusion and fail-closed
200
+ * clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
181
201
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
182
202
  * whether unpinned work remains and whether any scoped rows remain. Each
183
203
  * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
184
204
  * evicted rows' `server_version` with them (E2 — no residual version
185
205
  * cache), which is automatic since the version column is per-row.
186
206
  */
187
- export function evictScopedRows(db, table, effective, pinnedRowIds) {
188
- const scope = localScopePredicate(table, effective);
207
+ export function evictScopedRows(db, table, effective, owners, pinnedRowIds) {
208
+ const scope = localScopePredicate(table, effective, owners);
189
209
  if (!scope)
190
210
  return { remaining: false, deferred: false };
191
211
  const { sql, params } = scope;
@@ -200,7 +220,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
200
220
  for (const row of db.query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`, [table.name])) {
201
221
  if (!pinnedRowIds.has(row.id) &&
202
222
  [row.intent, row.base].some((json) => json !== null &&
203
- matchesLocalScopes(table, effective, JSON.parse(json))))
223
+ ownsLocalRow(table, effective, owners, JSON.parse(json))))
204
224
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`, [table.name, row.id]);
205
225
  }
206
226
  db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`, params);
@@ -229,6 +249,10 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
229
249
  if (descriptor.table !== table.name) {
230
250
  imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
231
251
  }
252
+ // §5.11: an image bypasses the decrypt seam, so a server cannot serve one
253
+ // for a table with encrypted columns.
254
+ if (table.hasEncryptedColumns)
255
+ imageInvalid('table has encrypted columns');
232
256
  return withImage(bytes, IMAGE_ALIAS, async () => {
233
257
  // 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
234
258
  // SQLite database or lacks the metadata table fails right here.
@@ -314,17 +338,16 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
314
338
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
315
339
  const scope = !replay
316
340
  ? []
317
- : hasUniqueIndex(table)
318
- ? [JSON.stringify([table.name])]
319
- : [
320
- ...(after === undefined && options.clearFirst
321
- ? bootstrapScope(db, table, options.effective)
322
- : []),
323
- ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
324
- ];
341
+ : [
342
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
343
+ ...(after === undefined && options.clearFirst
344
+ ? bootstrapScope(db, table, options.effective, options.owners)
345
+ : []),
346
+ ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
347
+ ];
325
348
  const protectedRows = restoreFailedBases(db, schema, scope);
326
349
  if (after === undefined && options.clearFirst)
327
- deleteScopedRows(db, table, options.effective);
350
+ deleteScopedRows(db, table, options.effective, options.owners);
328
351
  db.exec(`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}`, params);
329
352
  applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
330
353
  if (protectedRows)
@@ -368,7 +391,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
368
391
  // aborts before any write in this block.
369
392
  const rows = [];
370
393
  for (const row of block) {
371
- const values = encryption !== undefined && table.hasEncryptedColumns
394
+ const values = table.hasEncryptedColumns
372
395
  ? await (async () => {
373
396
  const { decryptRowValues } = await import('./encryption.js');
374
397
  return decryptRowValues(encryption, table, row.values);
@@ -383,20 +406,19 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
383
406
  if (!clearThisBlock && rows.length === 0)
384
407
  continue;
385
408
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
386
- const scope = hasUniqueIndex(table)
387
- ? [JSON.stringify([table.name])]
388
- : [
389
- ...(clearThisBlock
390
- ? bootstrapScope(db, table, options.effective)
391
- : []),
392
- ...rows.map((row) => JSON.stringify([
393
- table.name,
394
- String(row.values[table.primaryKeyIndex]),
395
- ])),
396
- ];
409
+ const scope = [
410
+ ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
411
+ ...(clearThisBlock
412
+ ? bootstrapScope(db, table, options.effective, options.owners)
413
+ : []),
414
+ ...rows.map((row) => JSON.stringify([
415
+ table.name,
416
+ String(row.values[table.primaryKeyIndex]),
417
+ ])),
418
+ ];
397
419
  const protectedRows = restoreFailedBases(db, schema, scope);
398
420
  if (clearThisBlock) {
399
- deleteScopedRows(db, table, options.effective);
421
+ deleteScopedRows(db, table, options.effective, options.owners);
400
422
  }
401
423
  for (const row of rows) {
402
424
  upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
package/dist/blob.d.ts CHANGED
@@ -39,35 +39,43 @@ export type BlobUploadGrant = {
39
39
  } | {
40
40
  readonly kind: 'none';
41
41
  };
42
- /** The transport seam for blob upload/download (§5.9.3/§5.9.5). */
42
+ /**
43
+ * The transport seam for blob upload/download (§5.9.3/§5.9.5). The upload
44
+ * calls receive the round's `signal`, which aborts when the `syncUntilIdle`
45
+ * deadline elapses (§7.7).
46
+ */
43
47
  export interface BlobTransport {
44
48
  /** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
45
- upload(blobId: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
49
+ upload(blobId: string, bytes: Uint8Array, mediaType?: string, signal?: AbortSignal): Promise<void>;
46
50
  /**
47
51
  * `GET <mount>/blobs/{blobId}` — re-authorized (§5.9.5). Returns inline
48
52
  * bytes, or a presigned `url` the client core fetches via `fetchUrl`.
53
+ * `byteLength` is the BlobRef's declared size when the caller passed one;
54
+ * reading inline bytes stops once the body exceeds it.
49
55
  */
50
- download(blobId: string): Promise<BlobDownloadResponse>;
56
+ download(blobId: string, byteLength?: number): Promise<BlobDownloadResponse>;
51
57
  /**
52
58
  * §5.9.5 presigned-download fetch: a bare GET of the signed `url`. Present
53
59
  * iff the transport can consume URLs. MUST attach NO host authentication —
54
60
  * the URL is the entire grant (§5.4). Only called when `download` returned
55
- * a `url` arm.
61
+ * a `url` arm. Reading stops once the body exceeds `byteLength`.
56
62
  */
57
- fetchUrl?(url: string): Promise<Uint8Array>;
63
+ fetchUrl?(url: string, byteLength?: number): Promise<Uint8Array>;
58
64
  /**
59
65
  * §5.9.3 presigned-upload grant: `POST /blobs/{blobId}/upload-grant` with
60
66
  * the declared size. Present iff the transport supports the grant flow;
61
67
  * absent ⇒ the client always streams through `upload`. A `url` grant is
62
68
  * PUT via `uploadToUrl`.
63
69
  */
64
- uploadGrant?(blobId: string, byteLength: number, mediaType?: string): Promise<BlobUploadGrant>;
70
+ uploadGrant?(blobId: string, byteLength: number, mediaType?: string, signal?: AbortSignal): Promise<BlobUploadGrant>;
65
71
  /**
66
72
  * §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
67
- * authentication — the presigned URL is the entire grant (§5.4). Only
68
- * called when `uploadGrant` returned a `url` arm.
73
+ * authentication — the presigned URL is the entire grant (§5.4) — and MUST
74
+ * send `x-amz-checksum-sha256` (base64 of the body's SHA-256), which the
75
+ * grant signs beside `content-length`. Only called when `uploadGrant`
76
+ * returned a `url` arm.
69
77
  */
70
- uploadToUrl?(url: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
78
+ uploadToUrl?(url: string, bytes: Uint8Array, mediaType?: string, signal?: AbortSignal): Promise<void>;
71
79
  }
72
80
  export interface CachedBlob {
73
81
  readonly blobId: string;
package/dist/blob.js CHANGED
@@ -71,7 +71,7 @@ export function enforceBlobCacheCap(db, schema, maxBytes) {
71
71
  if (total <= maxBytes)
72
72
  return [];
73
73
  // Oldest eligible body first, with blob ID as a stable tie.
74
- const candidates = db.query(`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`);
74
+ const candidates = db.query(`SELECT blob_id,byte_length ${unreferencedBlobsSql(schema)}ORDER BY created_at_ms ASC,blob_id ASC`);
75
75
  const evicted = [];
76
76
  db.transaction(() => {
77
77
  for (const row of candidates) {
@@ -126,7 +126,8 @@ export function schemaHasBlobs(schema) {
126
126
  }
127
127
  return false;
128
128
  }
129
- function visibleBlobIdsSql(schema) {
129
+ /** The cached bodies no upload, pending commit, or visible row references. */
130
+ function unreferencedBlobsSql(schema) {
130
131
  const selects = [];
131
132
  for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
132
133
  for (const column of columns) {
@@ -134,11 +135,9 @@ function visibleBlobIdsSql(schema) {
134
135
  selects.push(`SELECT json_extract(${identifier},'$.blobId')AS blob_id FROM ${quoteIdent(tableName)} WHERE typeof(${identifier})='text' AND json_valid(${identifier})AND json_type(${identifier},'$.blobId')='text'`);
135
136
  }
136
137
  }
137
- return selects.length === 0
138
- ? 'SELECT NULL AS blob_id WHERE 0'
139
- : selects.join(' UNION ');
138
+ 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 ')})`;
140
139
  }
141
140
  export function deleteUnreferencedCachedBlobs(db, schema) {
142
- db.exec(`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)})`);
141
+ db.exec(`DELETE ${unreferencedBlobsSql(schema)}`);
143
142
  }
144
143
  export { parseBlobRef, serializeBlobRef };
@@ -16,6 +16,7 @@ export declare class BunClientDatabase implements ClientDatabase {
16
16
  constructor(path?: string);
17
17
  exec(sql: string, params?: readonly SqlValue[]): void;
18
18
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
19
+ queryReadOnly(sql: string, params?: readonly SqlValue[]): SqlRow[];
19
20
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
20
21
  openSibling(name: string): SiblingDatabase;
21
22
  siblingExists(name: string): boolean;
@@ -8,6 +8,7 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
8
8
  import { tmpdir } from 'node:os';
9
9
  import { join } from 'node:path';
10
10
  import { assertImageAlias, runTransaction, } from './database.js';
11
+ import { prepareReadOnly, refuseRawSql } from './query-guard.js';
11
12
  function coerceParams(params) {
12
13
  return params.map((value) => {
13
14
  if (typeof value === 'boolean')
@@ -45,6 +46,33 @@ export class BunClientDatabase {
45
46
  query(sql, params = []) {
46
47
  return this.db.query(sql).all(...coerceParams(params));
47
48
  }
49
+ queryReadOnly(sql, params = []) {
50
+ const statement = prepareReadOnly(sql, () => {
51
+ const prepared = this.db.query(sql);
52
+ // bun:sqlite exposes no `sqlite3_sql`, so the first statement ends at
53
+ // the first `;` outside literals, identifiers and comments.
54
+ return [
55
+ prepared,
56
+ /^(?:'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[^;])*/.exec(sql)[0],
57
+ prepared.columnNames.length > 0,
58
+ ];
59
+ });
60
+ // bun:sqlite exposes `sqlite3_stmt_readonly` only from Bun 1.4.4, so
61
+ // SQLite refuses a write when the statement runs: under `query_only` a
62
+ // write transaction fails before it changes anything.
63
+ this.db.run('PRAGMA query_only = ON');
64
+ try {
65
+ return statement.all(...coerceParams(params));
66
+ }
67
+ catch (error) {
68
+ if (error.code === 'SQLITE_READONLY')
69
+ refuseRawSql();
70
+ throw error;
71
+ }
72
+ finally {
73
+ this.db.run('PRAGMA query_only = OFF');
74
+ }
75
+ }
48
76
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
49
77
  openSibling(name) {
50
78
  const siblingPath = this.#path === ':memory:' ? ':memory:' : `${this.#path}.${name}`;
package/dist/client.d.ts CHANGED
@@ -9,7 +9,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
9
9
  * ownership behind `LeaderLock`. One combined push+pull request per
10
10
  * `sync()` round (§7.2); local reads go straight to the database.
11
11
  */
12
- import { type ScopeMap, type WakeReason } from '@syncular/core';
12
+ import { type PresenceErrorCode, type ScopeMap, type WakeReason } from '@syncular/core';
13
13
  import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
14
14
  import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
15
15
  import type { DevtoolsRegistrar } from './devtools.js';
@@ -176,6 +176,15 @@ export interface SyncClientConfig {
176
176
  * `required` without a `realtime` connector is refused at construction.
177
177
  */
178
178
  readonly realtimePolicy?: RealtimePolicy;
179
+ /**
180
+ * SPEC §8.5: the server's heartbeat interval in ms, default 30,000. The
181
+ * socket's first `heartbeat` event arms a watchdog; once armed, twice the
182
+ * interval without an inbound frame loses the socket with
183
+ * `transport.timeout` (`causeKind` `heartbeat`).
184
+ */
185
+ readonly realtimeHeartbeatMs?: number;
186
+ /** Timer seam for the heartbeat watchdog; defaults to `setTimeout`. */
187
+ readonly schedule?: (callback: () => void, delayMs: number) => () => void;
179
188
  /** Stable per-device id (§1.5); defaults to a persisted random UUID. */
180
189
  readonly clientId?: string;
181
190
  readonly leaderLock?: LeaderLock;
@@ -197,9 +206,11 @@ export interface SyncClientConfig {
197
206
  /**
198
207
  * §8.6 presence: a scope-mate's presence on a key this client holds
199
208
  * changed (join/update/leave). Fired after the local presence map is
200
- * updated — the app's cue to re-render who's-online.
209
+ * updated — the app's cue to re-render who's-online. `error` is set when
210
+ * the server refused this client's own publish on `scopeKey` (§8.6.2);
211
+ * the map is unchanged then.
201
212
  */
202
- readonly onPresence?: (scopeKey: string) => void;
213
+ readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
203
214
  /**
204
215
  * §5.11 client-side encryption. Supplies the key material (`keyProvider`)
205
216
  * and key selection (`keyIdFor`) for columns the generated schema marks
@@ -433,8 +444,8 @@ export declare class SyncClient {
433
444
  /** The underlying database: raw SQL is the local query API. */
434
445
  get database(): ClientDatabase;
435
446
  /**
436
- * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only
437
- * statement only — writes must go through `mutate()` so they hit the
447
+ * The raw-SQL read tier. Guarded (query-guard.ts): a single statement
448
+ * SQLite reports read-only — writes must go through `mutate()` so they hit the
438
449
  * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
439
450
  * result, so a `SELECT *` row is safe to feed back into `mutate()`
440
451
  * values; alias explicitly (`_sync_version AS v`) to read one. Engine
@@ -534,7 +545,11 @@ export declare class SyncClient {
534
545
  * Accepts a raw `blob_ref` column string or a bare `blobId`.
535
546
  */
536
547
  fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
537
- /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
548
+ /**
549
+ * Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. It
550
+ * runs on the round's operation chain because a refused upload drops
551
+ * outbox commits a round may have captured.
552
+ */
538
553
  flushBlobUploads(): Promise<void>;
539
554
  conflicts(): readonly ConflictRecord[];
540
555
  rejections(): readonly RejectionRecord[];
@@ -565,12 +580,14 @@ export declare class SyncClient {
565
580
  /** Every scope key this client currently has presence state for. */
566
581
  presenceKeys(): string[];
567
582
  /**
568
- * §8.6: subscribe to presence changes (join/update/leave on any held key).
569
- * The subscribable twin of the `onPresence` config callback — React's
570
- * `usePresence` targets this so many components can watch one client.
583
+ * §8.6: subscribe to presence changes (join/update/leave on any held key)
584
+ * and to the server's refusal of this client's own publish (`error`,
585
+ * §8.6.2). The subscribable twin of the `onPresence` config callback —
586
+ * React's `usePresence` targets this so many components can watch one
587
+ * client.
571
588
  * Returns an unsubscribe function.
572
589
  */
573
- onPresence(listener: (scopeKey: string) => void): () => void;
590
+ onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
574
591
  /**
575
592
  * §8.6.2 publish (or clear, `doc: null`) this client's presence document
576
593
  * for `scopeKey`. Requires a live socket; the document is ephemeral and