@syncular/client 0.58.0 → 0.60.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 (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
package/src/database.ts CHANGED
@@ -34,6 +34,11 @@ export interface ClientDatabase {
34
34
  exec(sql: string, params?: readonly SqlValue[]): void;
35
35
  /** Execute a single statement and return its rows as objects. */
36
36
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
37
+ /**
38
+ * The raw-SQL tier behind `client.query()`: prepare `sql` through
39
+ * `prepareReadOnly`, then return the statement's rows.
40
+ */
41
+ queryReadOnly(sql: string, params?: readonly SqlValue[]): SqlRow[];
37
42
  /**
38
43
  * Run `fn` atomically. Nested calls are savepoints: an inner failure
39
44
  * rolls back only the inner scope.
package/src/devtools.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * __SYNCULAR__.clients // the live entries
8
8
  * await __SYNCULAR__.snapshot() // one plain object per client:
9
- * // outbox depth, subscriptions,
9
+ * // outbox depth, units,
10
10
  * // conflicts, syncNeeded, upgrading,
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
@@ -26,7 +26,7 @@ export interface DevtoolsRegistration {
26
26
  readonly clientId: () => string;
27
27
  readonly role: () => string;
28
28
  readonly outbox: () => Promise<number>;
29
- readonly subscriptions: () => Promise<readonly unknown[]>;
29
+ readonly units: () => Promise<readonly unknown[]>;
30
30
  readonly conflicts: () => Promise<number>;
31
31
  readonly rejections: () => Promise<number>;
32
32
  readonly syncNeeded: () => Promise<boolean>;
@@ -87,9 +87,9 @@ function registryOn(host: Record<string, unknown>): DevtoolsRegistry {
87
87
  clientId: entry.clientId(),
88
88
  role: entry.role(),
89
89
  outbox: await entry.outbox().catch(() => 'unavailable'),
90
- subscriptions: await entry
91
- .subscriptions()
92
- .then((subs) => subs.length)
90
+ units: await entry
91
+ .units()
92
+ .then((units) => units.length)
93
93
  .catch(() => 'unavailable'),
94
94
  conflicts: await entry.conflicts().catch(() => 'unavailable'),
95
95
  rejections: await entry.rejections().catch(() => 'unavailable'),
@@ -7,8 +7,7 @@
7
7
  */
8
8
  import type { SecurityLifecycle } from './client';
9
9
 
10
- export const CLIENT_DIAGNOSTICS_VERSION = 1 as const;
11
- export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
10
+ export const CLIENT_DIAGNOSTICS_VERSION = 2 as const;
12
11
  export const MAX_DIAGNOSTIC_DOMAINS = 256;
13
12
  export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
14
13
 
@@ -66,38 +65,15 @@ export interface ClientDiagnosticsHost {
66
65
  readonly realtimeRetryDelayMs?: number;
67
66
  }
68
67
 
69
- export interface ExpectedDiagnosticSubscription {
70
- /** Application-owned stable identifier. It must never contain PHI. */
71
- readonly id: string;
72
- /** Generated schema table name. */
73
- readonly table: string;
74
- }
75
-
76
- export interface ClientDiagnosticsRequest {
77
- /**
78
- * Optional bounded intent list. Missing registrations are returned as
79
- * `unregistered`, allowing a zero-row security scope to fail closed without
80
- * reading private Syncular tables. Values/scopes are intentionally absent.
81
- */
82
- readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
83
- }
84
-
85
- export type DiagnosticSubscriptionState =
86
- | 'unregistered'
87
- | 'bootstrapping'
88
- | 'complete'
89
- | 'reset'
90
- | 'revoked'
91
- | 'failed';
92
-
93
- export interface DiagnosticSubscription {
94
- readonly id: string;
95
- readonly table: string;
96
- readonly state: DiagnosticSubscriptionState;
97
- readonly complete: boolean;
98
- /** Last fully applied local commit sequence; absent when unregistered. */
99
- readonly cursor?: number;
100
- readonly reasonCode?: string;
68
+ /** §7.6: registered units per state; a unit id never enters diagnostics. */
69
+ export interface DiagnosticUnits {
70
+ readonly bootstrapping: number;
71
+ readonly complete: number;
72
+ readonly reset: number;
73
+ readonly revoked: number;
74
+ readonly failed: number;
75
+ /** Distinct stable reason codes of registered units, ascending. */
76
+ readonly reasonCodes: readonly string[];
101
77
  }
102
78
 
103
79
  export interface DiagnosticRoundCounters {
@@ -140,7 +116,8 @@ export interface DiagnosticLastChange {
140
116
  readonly recordedAtMs: number;
141
117
  /** Generated table names only; no scope keys or row ids. */
142
118
  readonly tables: readonly string[];
143
- /** Generated table names for changed window registrations/completeness. */
119
+ /** Selected variables of window bases whose registration or completeness
120
+ * changed. */
144
121
  readonly windows: readonly string[];
145
122
  readonly domainsTruncated: boolean;
146
123
  readonly statusChanged: boolean;
@@ -201,8 +178,11 @@ export interface ClientDiagnosticsSnapshot {
201
178
  readonly expiresAtMs?: number;
202
179
  readonly errorCode?: string;
203
180
  };
204
- readonly subscriptions: readonly DiagnosticSubscription[];
205
- readonly subscriptionsTruncated: boolean;
181
+ readonly units: DiagnosticUnits;
182
+ /** Units the next registration list carries; the server limit counts these (SPEC §4.1). */
183
+ readonly activeUnits: number;
184
+ /** §4.5 replica cursor; `-1` while no unit is live. */
185
+ readonly replicaCursor: number;
206
186
  readonly lastRound?: DiagnosticLastRound;
207
187
  readonly lastChange?: DiagnosticLastChange;
208
188
  readonly storage: ClientDiagnosticsStorage;
package/src/encryption.ts CHANGED
@@ -20,7 +20,7 @@ import {
20
20
  type RowColumn,
21
21
  type RowValue,
22
22
  } from '@syncular/core';
23
- import { ClientSyncError } from './errors';
23
+ import { invalidRequest } from './errors';
24
24
  import type { CompiledClientTable } from './schema';
25
25
 
26
26
  /**
@@ -73,8 +73,7 @@ export function encryptionConfigFromKeyring(
73
73
  ): EncryptionConfig {
74
74
  for (const [keyId, key] of Object.entries(keyring.keys)) {
75
75
  if (key.length !== KEY_LENGTH) {
76
- throw new ClientSyncError(
77
- 'sync.invalid_request',
76
+ throw invalidRequest(
78
77
  `encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`,
79
78
  );
80
79
  }
@@ -144,7 +143,7 @@ function declaredTypeOf(column: RowColumn): DeclaredType {
144
143
  * unencrypted (§5.11).
145
144
  */
146
145
  export async function encryptRowValues<T extends RowValue | undefined>(
147
- config: EncryptionConfig,
146
+ config: EncryptionConfig | undefined,
148
147
  table: CompiledClientTable,
149
148
  rowId: string,
150
149
  values: readonly T[],
@@ -164,6 +163,9 @@ export async function encryptRowValues<T extends RowValue | undefined>(
164
163
  }
165
164
  }
166
165
  if (!hasPresentEncrypted) return out;
166
+ if (config === undefined) {
167
+ throw new EncryptError('encrypted columns need an encryption config');
168
+ }
167
169
  // Key selection reads the presence set first, then the stored local row.
168
170
  // Absent slots densify to null for selection only; the loop below still
169
171
  // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
@@ -213,7 +215,7 @@ export async function encryptRowValues<T extends RowValue | undefined>(
213
215
  * {@link DecryptError} (`client.decrypt_failed`, §5.11).
214
216
  */
215
217
  export async function decryptRowValues(
216
- config: EncryptionConfig,
218
+ config: EncryptionConfig | undefined,
217
219
  table: CompiledClientTable,
218
220
  values: readonly RowValue[],
219
221
  ): Promise<RowValue[]> {
@@ -229,6 +231,9 @@ export async function decryptRowValues(
229
231
  `encrypted column ${column.name} decoded to a non-bytes value`,
230
232
  );
231
233
  }
234
+ if (config === undefined) {
235
+ throw new DecryptError('encrypted columns need an encryption config');
236
+ }
232
237
  out[i] = deserializeGuard(
233
238
  await decryptValue(declaredTypeOf(column), value, config.keyProvider),
234
239
  );
package/src/errors.ts CHANGED
@@ -9,7 +9,7 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
9
9
  */
10
10
  export const STORAGE_FENCED_CODE = 'client.storage_fenced';
11
11
 
12
- /** The browser cannot provide the persistent storage APIs Syncular requires. */
12
+ /** The runtime cannot provide the storage APIs Syncular requires. */
13
13
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
14
14
 
15
15
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
@@ -63,6 +63,14 @@ export function invalidRequest(
63
63
  return new ClientSyncError('sync.invalid_request', message, retryable);
64
64
  }
65
65
 
66
+ /** Shared retryable `sync.transport_failed` construction for client transports. */
67
+ export function transportFailed(
68
+ message: string,
69
+ details?: Readonly<Record<string, unknown>>,
70
+ ): ClientSyncError {
71
+ return new ClientSyncError('sync.transport_failed', message, true, details);
72
+ }
73
+
66
74
  /**
67
75
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
68
76
  * for its required coverage. `code` is the attempt's static progress error
@@ -1,6 +1,6 @@
1
1
  import { hasUniqueIndex } from './schema';
2
2
  import { OUTCOMES_TABLE } from './outcomes';
3
- import { OUTBOX_TABLE } from './outbox';
3
+ import { OUTBOX_IMAGES } from './outbox';
4
4
  export const RETAINED_ROWS = '_syncular_failed_rows';
5
5
  import { ClientSyncError } from './errors';
6
6
  import type { ClientDatabase } from './database';
@@ -37,6 +37,9 @@ export function ensureFailedOverlaySchema(db: ClientDatabase): void {
37
37
  for (const column of ['unique_conflicts TEXT', 'commit_seq INTEGER'])
38
38
  if (!columns.some((row) => row.name === column.split(' ')[0]))
39
39
  db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
40
+ db.exec(
41
+ `CREATE INDEX IF NOT EXISTS ${RETAINED_ROWS}_row ON ${RETAINED_ROWS}(tbl,id)`,
42
+ );
40
43
  }
41
44
 
42
45
  export function retainedBaseWrite(
@@ -171,17 +174,15 @@ export function uniqueConflicts(
171
174
  /** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
172
175
  export type OverlayScope = readonly string[];
173
176
 
174
- export function overlayScopePredicate(table: string, id: string): string {
175
- return `?1 IS NULL OR json_array(${table},${id}) IN(SELECT value FROM json_each(?1)) OR json_array(${table}) IN(SELECT value FROM json_each(?1))`;
176
- }
177
-
178
177
  function retainedRows(
179
178
  db: ClientDatabase,
180
179
  scope?: OverlayScope,
181
180
  acknowledged?: boolean,
182
181
  ) {
182
+ // A scope joins through the (tbl, id) index; a scan per applied commit
183
+ // would make a drained batch quadratic.
183
184
  return db.query(
184
- `SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
185
+ `SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
185
186
  [scope ? JSON.stringify(scope) : null],
186
187
  );
187
188
  }
@@ -266,7 +267,7 @@ export function failedOverlayCommits(
266
267
  (conflict) =>
267
268
  conflict.serverVersion >= 0 &&
268
269
  !db.query(
269
- `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_TABLE},json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
270
+ `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`,
270
271
  [table.name, conflict.rowId, table.name, conflict.rowId],
271
272
  ).length,
272
273
  );
package/src/http.ts CHANGED
@@ -6,7 +6,8 @@
6
6
  */
7
7
  import type { BlobTransport } from './blob';
8
8
  import { SSP2_CONTENT_TYPE } from './content-type';
9
- import { ClientSyncError } from './errors';
9
+ import { ClientSyncError, transportFailed } from './errors';
10
+ import { hexToBytes } from './schema';
10
11
  import type {
11
12
  RealtimeConnector,
12
13
  RemoteOperationTransport,
@@ -35,7 +36,7 @@ async function transfer<T>(
35
36
  : error instanceof TypeError
36
37
  ? 'network'
37
38
  : 'unknown';
38
- throw new ClientSyncError('sync.transport_failed', message, true, {
39
+ throw transportFailed(message, {
39
40
  causeKind,
40
41
  ...(httpStatus !== undefined ? { httpStatus } : {}),
41
42
  });
@@ -117,7 +118,7 @@ export function httpSyncTransport(
117
118
  options?: HttpTransportOptions,
118
119
  ): SyncTransport {
119
120
  const doFetch = options?.fetch ?? fetch;
120
- return async (request) => {
121
+ return async (request, signal) => {
121
122
  const response = await transfer('sync request failed', () =>
122
123
  doFetch(syncUrl, {
123
124
  method: 'POST',
@@ -126,6 +127,7 @@ export function httpSyncTransport(
126
127
  ...hostHeaders(options),
127
128
  },
128
129
  body: request.slice().buffer as ArrayBuffer,
130
+ ...(signal !== undefined ? { signal } : {}),
129
131
  }),
130
132
  );
131
133
  if (!response.ok) await throwHttpError(response);
@@ -171,7 +173,7 @@ function socketOperation<T>(message: string, operation: () => T): T {
171
173
  try {
172
174
  return operation();
173
175
  } catch {
174
- throw new ClientSyncError('sync.transport_failed', message, true, {
176
+ throw transportFailed(message, {
175
177
  causeKind: 'unknown',
176
178
  });
177
179
  }
@@ -208,10 +210,8 @@ export function webSocketRemoteOperationConnector(
208
210
  socket.onerror = () => {
209
211
  if (!opened) {
210
212
  reject(
211
- new ClientSyncError(
212
- 'sync.transport_failed',
213
+ transportFailed(
213
214
  'remote operation realtime socket failed to connect',
214
- true,
215
215
  ),
216
216
  );
217
217
  }
@@ -224,10 +224,8 @@ export function webSocketRemoteOperationConnector(
224
224
  socket.onclose = () => {
225
225
  if (!opened) {
226
226
  reject(
227
- new ClientSyncError(
228
- 'sync.transport_failed',
227
+ transportFailed(
229
228
  'remote operation realtime socket closed while connecting',
230
- true,
231
229
  ),
232
230
  );
233
231
  }
@@ -244,11 +242,12 @@ export function webSocketRemoteOperationConnector(
244
242
  * Resolution (which path a descriptor takes, expiry, no fall-through)
245
243
  * lives in the client core, not here.
246
244
  */
247
- async function readSegmentBody(
245
+ async function readBody(
248
246
  response: Response,
249
247
  onProgress?: (bytesReceived: number) => void,
248
+ maxBytes?: number,
250
249
  ): Promise<Uint8Array> {
251
- const chunks: Uint8Array[] = [];
250
+ const chunks: Uint8Array<ArrayBuffer>[] = [];
252
251
  let received = 0;
253
252
  let reported = 0;
254
253
  const reader = response.body?.getReader();
@@ -259,6 +258,11 @@ async function readSegmentBody(
259
258
  if (done) break;
260
259
  chunks.push(value);
261
260
  received += value.byteLength;
261
+ // The caller rejects a body longer than its declared byteLength.
262
+ if (received > (maxBytes ?? received)) {
263
+ await reader.cancel();
264
+ break;
265
+ }
262
266
  if (received - reported >= 64 * 1024) {
263
267
  onProgress?.(received);
264
268
  reported = received;
@@ -269,13 +273,7 @@ async function readSegmentBody(
269
273
  }
270
274
  }
271
275
  if (received !== reported) onProgress?.(received);
272
- const bytes = new Uint8Array(received);
273
- let offset = 0;
274
- for (const chunk of chunks) {
275
- bytes.set(chunk, offset);
276
- offset += chunk.byteLength;
277
- }
278
- return bytes;
276
+ return new Uint8Array(await new Blob(chunks).arrayBuffer());
279
277
  }
280
278
 
281
279
  export function httpSegmentDownloader(
@@ -288,29 +286,30 @@ export function httpSegmentDownloader(
288
286
  init?: RequestInit,
289
287
  onProgress?: (bytesReceived: number) => void,
290
288
  signed = false,
289
+ maxBytes?: number,
291
290
  ) => {
292
291
  const response = await transfer('segment transfer failed', () =>
293
292
  doFetch(url, init),
294
293
  );
295
294
  if (!response.ok) {
296
295
  if (!signed) await throwHttpError(response);
297
- throw new ClientSyncError(
298
- 'sync.transport_failed',
299
- 'signed segment request failed; invalidate the descriptor and re-pull',
300
- true,
301
- { causeKind: 'status', httpStatus: response.status },
302
- );
296
+ throw transportFailed('signed segment request failed', {
297
+ causeKind: 'status',
298
+ httpStatus: response.status,
299
+ });
303
300
  }
304
301
  return transfer(
305
302
  'segment transfer failed',
306
- () => readSegmentBody(response, onProgress),
303
+ () => readBody(response, onProgress, maxBytes),
307
304
  response.status,
308
305
  );
309
306
  };
310
307
  const direct = (request: {
311
308
  readonly segmentId: string;
312
309
  readonly requestedScopesJson: string;
310
+ readonly byteLength?: number;
313
311
  readonly onProgress?: (bytesReceived: number) => void;
312
+ readonly signal?: AbortSignal;
314
313
  }) =>
315
314
  download(
316
315
  `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
@@ -319,14 +318,26 @@ export function httpSegmentDownloader(
319
318
  'X-Syncular-Scopes': request.requestedScopesJson,
320
319
  ...hostHeaders(options),
321
320
  },
321
+ ...(request.signal !== undefined ? { signal: request.signal } : {}),
322
322
  },
323
323
  request.onProgress,
324
+ false,
325
+ request.byteLength,
324
326
  );
325
327
  // Deliberately headerless: the URL is the bearer grant (§5.4).
326
328
  const fetchUrl = (
327
329
  url: string,
328
330
  onProgress?: (bytesReceived: number) => void,
329
- ) => download(url, undefined, onProgress, true);
331
+ signal?: AbortSignal,
332
+ byteLength?: number,
333
+ ) =>
334
+ download(
335
+ url,
336
+ signal !== undefined ? { signal } : undefined,
337
+ onProgress,
338
+ true,
339
+ byteLength,
340
+ );
330
341
  return Object.assign(direct, { fetchUrl });
331
342
  }
332
343
 
@@ -344,7 +355,7 @@ export function httpBlobTransport(
344
355
  const blobUrl = (blobId: string) =>
345
356
  `${blobsBaseUrl}/${encodeURIComponent(blobId)}`;
346
357
  return {
347
- upload: async (blobId, bytes, mediaType) => {
358
+ upload: async (blobId, bytes, mediaType, signal) => {
348
359
  const response = await transfer('blob upload failed', () =>
349
360
  doFetch(blobUrl(blobId), {
350
361
  method: 'PUT',
@@ -353,11 +364,12 @@ export function httpBlobTransport(
353
364
  ...hostHeaders(options),
354
365
  },
355
366
  body: bytes.slice().buffer as ArrayBuffer,
367
+ ...(signal !== undefined ? { signal } : {}),
356
368
  }),
357
369
  );
358
370
  if (!response.ok) await throwHttpError(response);
359
371
  },
360
- download: async (blobId) => {
372
+ download: async (blobId, byteLength) => {
361
373
  const response = await transfer('blob download failed', () =>
362
374
  doFetch(blobUrl(blobId), {
363
375
  headers: { ...hostHeaders(options) },
@@ -375,17 +387,16 @@ export function httpBlobTransport(
375
387
  : 'sync.transport_failed',
376
388
  );
377
389
  // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
378
- // any other body is inline bytes. The body is read exactly once as bytes,
379
- // so an inline blob stored as `application/json` stays readable.
380
- const contentType = response.headers.get('content-type') ?? '';
381
- const bytes = new Uint8Array(
382
- await transfer(
383
- 'blob download body read failed',
384
- () => response.arrayBuffer(),
385
- response.status,
386
- ),
390
+ // any other body is inline bytes, capped by the declared byteLength.
391
+ const json = (response.headers.get('content-type') ?? '').includes(
392
+ 'application/json',
393
+ );
394
+ const bytes = await transfer(
395
+ 'blob body read failed',
396
+ () => readBody(response, undefined, json ? undefined : byteLength),
397
+ response.status,
387
398
  );
388
- if (contentType.includes('application/json')) {
399
+ if (json) {
389
400
  let envelope: { url?: unknown; urlExpiresAtMs?: unknown } | null = null;
390
401
  try {
391
402
  envelope = JSON.parse(new TextDecoder().decode(bytes));
@@ -405,28 +416,24 @@ export function httpBlobTransport(
405
416
  return { kind: 'bytes', bytes };
406
417
  },
407
418
  // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
408
- fetchUrl: async (url) => {
419
+ fetchUrl: async (url, byteLength) => {
409
420
  const response = await transfer('signed blob download failed', () =>
410
421
  doFetch(url),
411
422
  );
412
423
  if (!response.ok) {
413
- throw new ClientSyncError(
414
- 'sync.transport_failed',
415
- 'signed blob download failed; re-request to recover',
416
- true,
417
- { causeKind: 'status', httpStatus: response.status },
418
- );
424
+ throw transportFailed('signed blob download failed', {
425
+ causeKind: 'status',
426
+ httpStatus: response.status,
427
+ });
419
428
  }
420
- return new Uint8Array(
421
- await transfer(
422
- 'response body read failed',
423
- () => response.arrayBuffer(),
424
- response.status,
425
- ),
429
+ return transfer(
430
+ 'response body read failed',
431
+ () => readBody(response, undefined, byteLength),
432
+ response.status,
426
433
  );
427
434
  },
428
435
  // §5.9.3: presigned-upload grant.
429
- uploadGrant: async (blobId, byteLength, mediaType) => {
436
+ uploadGrant: async (blobId, byteLength, mediaType, signal) => {
430
437
  const response = await transfer('blob upload grant request failed', () =>
431
438
  doFetch(`${blobUrl(blobId)}/upload-grant`, {
432
439
  method: 'POST',
@@ -438,11 +445,12 @@ export function httpBlobTransport(
438
445
  byteLength,
439
446
  ...(mediaType !== undefined ? { mediaType } : {}),
440
447
  }),
448
+ ...(signal !== undefined ? { signal } : {}),
441
449
  }),
442
450
  );
443
451
  if (!response.ok) await throwHttpError(response);
444
452
  const body = (await transfer(
445
- 'blob upload grant body read failed',
453
+ 'blob grant read failed',
446
454
  () => response.json(),
447
455
  response.status,
448
456
  )) as {
@@ -463,37 +471,57 @@ export function httpBlobTransport(
463
471
  return { kind: 'none' };
464
472
  },
465
473
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
466
- uploadToUrl: async (url, bytes, mediaType) => {
474
+ uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
475
+ // The grant signs content-length (set by fetch from the body) and the
476
+ // checksum, the blob id's digest, so the object store rejects any other
477
+ // bytes without the client hashing the body again (§5.9.3).
478
+ const hex = /^sha256:([0-9a-f]{64})$/.exec(blobId)?.[1];
479
+ if (hex === undefined) {
480
+ throw new ClientSyncError(
481
+ 'sync.invalid_request',
482
+ 'the blob id is not a sha256 blob id (§5.9.1)',
483
+ );
484
+ }
485
+ const checksum = btoa(String.fromCharCode(...hexToBytes(hex)));
486
+ const body = bytes.slice().buffer as ArrayBuffer;
467
487
  const response = await transfer('signed blob upload failed', () =>
468
488
  doFetch(url, {
469
489
  method: 'PUT',
470
490
  headers: {
471
491
  'Content-Type': mediaType ?? 'application/octet-stream',
492
+ 'x-amz-checksum-sha256': checksum,
472
493
  },
473
- body: bytes.slice().buffer as ArrayBuffer,
494
+ body,
495
+ ...(signal !== undefined ? { signal } : {}),
474
496
  }),
475
497
  );
476
498
  if (!response.ok) {
477
- throw new ClientSyncError(
478
- 'sync.transport_failed',
479
- 'signed blob upload failed; re-request a grant or stream direct',
480
- true,
481
- { causeKind: 'status', httpStatus: response.status },
482
- );
499
+ throw transportFailed('signed blob upload failed', {
500
+ causeKind: 'status',
501
+ httpStatus: response.status,
502
+ });
483
503
  }
484
504
  },
485
505
  };
486
506
  }
487
507
 
488
- /** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
508
+ /**
509
+ * WebSocket realtime connector (§8.1): text = control, binary = deltas. The
510
+ * client's id replaces a `{clientId}` placeholder in the URL.
511
+ */
489
512
  export function webSocketRealtimeConnector(
490
513
  realtimeUrl: string,
491
514
  ): RealtimeConnector {
492
- return (handlers) =>
515
+ return (handlers, clientId) =>
493
516
  new Promise((resolve, reject) => {
494
517
  const socket = socketOperation(
495
518
  'realtime socket failed to connect',
496
- () => new WebSocket(realtimeUrl),
519
+ () =>
520
+ new WebSocket(
521
+ clientId === undefined
522
+ ? realtimeUrl
523
+ : realtimeUrl.replace('{clientId}', encodeURIComponent(clientId)),
524
+ ),
497
525
  );
498
526
  let opened = false;
499
527
  socket.binaryType = 'arraybuffer';
@@ -517,13 +545,7 @@ export function webSocketRealtimeConnector(
517
545
  };
518
546
  socket.onerror = () => {
519
547
  if (!opened) {
520
- reject(
521
- new ClientSyncError(
522
- 'sync.transport_failed',
523
- 'realtime socket failed to connect',
524
- true,
525
- ),
526
- );
548
+ reject(transportFailed('realtime socket failed to connect'));
527
549
  }
528
550
  try {
529
551
  socket.close();
@@ -533,13 +555,7 @@ export function webSocketRealtimeConnector(
533
555
  };
534
556
  socket.onclose = () => {
535
557
  if (!opened) {
536
- reject(
537
- new ClientSyncError(
538
- 'sync.transport_failed',
539
- 'realtime socket closed while connecting',
540
- true,
541
- ),
542
- );
558
+ reject(transportFailed('realtime socket closed while connecting'));
543
559
  }
544
560
  handlers.onClose?.();
545
561
  };
package/src/index.ts CHANGED
@@ -46,7 +46,7 @@ export {
46
46
  type PreviousVersionReason,
47
47
  type PreviousVersionSnapshot,
48
48
  } from './previous-version';
49
- export * from './query-guard';
49
+ export { prepareReadOnly, RawSqlError } from './query-guard';
50
50
  export * from './reactive-store';
51
51
  export * from './remote';
52
52
  export * from './realtime-supervisor';