@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/state.ts CHANGED
@@ -1,119 +1,238 @@
1
1
  export const META_TABLE = '_syncular_meta';
2
2
  import { PENDING_EVICTIONS } from './window';
3
3
  import { WINDOWS_TABLE } from './window';
4
- export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
4
+ export const UNITS_TABLE = '_syncular_units';
5
5
  /**
6
- * Durable client sync state: per-subscription cursor, bootstrap resume
7
- * token (round-tripped opaquely, §4.7), and the last-echoed effective
8
- * scopes the §3.3 purge contract is keyed on — persisted per subscription
9
- * exactly for that purpose.
6
+ * Durable unit state (SPEC.md §4.1): per unit its scope map, status, live
7
+ * membership, catch-up cursor and opaque resume token (§4.7), the tables its
8
+ * current bootstrap seeded (§5.6) and the last echo (§4.4) the §3.3 purge
9
+ * contract is keyed on. The replica cursor, the echo digest and the
10
+ * registration digest the server holds live in meta.
10
11
  */
11
- import type { ScopeMap } from '@syncular/core';
12
+ import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
12
13
  import { ClientSyncError } from './errors';
13
- import type { CompiledClientSchema } from './schema';
14
+ import type { CompiledClientSchema, CompiledClientTable } from './schema';
14
15
  import type { ClientDatabase } from './database';
15
16
  import type { LocalRevision } from './invalidation';
16
17
 
17
18
  export const LOCAL_REVISION_KEY = 'localRevision';
19
+ /** §4.5 replica cursor; absent means `-1`. */
20
+ export const REPLICA_CURSOR_KEY = 'replicaCursor';
21
+ /** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
22
+ export const ECHO_DIGEST_KEY = 'echoDigest';
23
+ /** Hex of the registration digest of the list the server stores (§4.1). */
24
+ export const REGISTERED_DIGEST_KEY = 'registrationDigest';
18
25
  const MAX_U64 = 18_446_744_073_709_551_615n;
19
26
 
20
- export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
27
+ export type UnitStatus = 'active' | 'revoked' | 'failed';
21
28
 
22
- export interface SubscriptionRecord {
29
+ export interface UnitRecord {
30
+ /** §4.1: derived from the scope map. */
23
31
  readonly id: string;
24
- readonly table: string;
25
- /** Requested scopes (§3.2), chosen by the app. */
26
- readonly scopes: ScopeMap;
27
- /** Host-opaque JSON params, preserved verbatim. */
28
- readonly params?: string;
29
- /** Last fully-applied commitSeq; -1 = never synced (§4.3). */
30
- readonly cursor: number;
32
+ readonly scopes: UnitScopes;
33
+ /** An explicit `subscribe` holds the unit; window bases hold it through
34
+ * the window registry (§4.1 references). */
35
+ readonly explicit: boolean;
36
+ readonly status: UnitStatus;
37
+ /** §10 code when not active, or `sync.cursor_expired` after a reset. */
38
+ readonly reasonCode?: string | undefined;
39
+ /** Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
40
+ * post-bootstrap cursor `P`. */
41
+ readonly cursor?: number | undefined;
31
42
  /** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
32
- readonly bootstrapState?: string;
33
- /** Last effective scopes echoed while active (§3.3 purge key). */
34
- readonly effectiveScopes?: ScopeMap;
35
- readonly status: SubscriptionStatus;
36
- /** §10 code when not active (`sync.scope_revoked`, …). */
37
- readonly reasonCode?: string;
43
+ readonly bootstrapState?: string | undefined;
44
+ /** Tables that received a segment in the current bootstrap (§5.6). */
45
+ readonly seeded: readonly string[];
46
+ /** The echo persisted at the last `SUB_END` (§4.4). */
47
+ readonly echo?: readonly FencedRecord[] | undefined;
38
48
  }
39
49
 
40
- function rowToRecord(row: Record<string, unknown>): SubscriptionRecord {
41
- return {
42
- id: row.id as string,
43
- table: row.tbl as string,
44
- scopes: JSON.parse(row.requested_scopes as string) as ScopeMap,
45
- ...(row.params !== null ? { params: row.params as string } : {}),
46
- cursor: row.cursor as number,
47
- ...(row.bootstrap_state !== null
48
- ? { bootstrapState: row.bootstrap_state as string }
49
- : {}),
50
- ...(row.effective_scopes !== null
51
- ? {
52
- effectiveScopes: JSON.parse(
53
- row.effective_scopes as string,
54
- ) as ScopeMap,
55
- }
56
- : {}),
57
- status: row.status as SubscriptionStatus,
58
- ...(row.reason_code !== null
59
- ? { reasonCode: row.reason_code as string }
60
- : {}),
50
+ /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
51
+ export function bootstrapping(unit: UnitRecord): boolean {
52
+ return (
53
+ unit.cursor !== undefined &&
54
+ (unit.cursor < 0 || unit.bootstrapState !== undefined)
55
+ );
56
+ }
57
+
58
+ /** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
59
+ export function owning(unit: UnitRecord): boolean {
60
+ return (
61
+ unit.status === 'active' && unit.echo !== undefined && !bootstrapping(unit)
62
+ );
63
+ }
64
+
65
+ /** §4.1: the unit covers every table declaring all of its variables. */
66
+ export function covers(
67
+ table: CompiledClientTable,
68
+ scopes: UnitScopes,
69
+ ): boolean {
70
+ return Object.keys(scopes).every((variable) =>
71
+ table.scopeColumnByVariable.has(variable),
72
+ );
73
+ }
74
+
75
+ /**
76
+ * §4.4: the effective scopes of the (unit, table) pair under `echo`: the
77
+ * scope map as one-element lists plus the fenced lists. Undefined when the
78
+ * fence revoked the pair.
79
+ */
80
+ export function pairScopes(
81
+ scopes: UnitScopes,
82
+ table: string,
83
+ echo: readonly FencedRecord[] | undefined,
84
+ ): ScopeMap | undefined {
85
+ const fenced = echo?.find((record) => record.table === table);
86
+ if (fenced?.status === 'revoked') return undefined;
87
+ const effective: ScopeMap = { ...fenced?.scopes };
88
+ for (const [variable, value] of Object.entries(scopes))
89
+ effective[variable] = [value];
90
+ return effective;
91
+ }
92
+
93
+ /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
94
+ * A bootstrapping unit owns the tables its current bootstrap seeded. */
95
+ export function unitOwners(
96
+ units: readonly UnitRecord[],
97
+ table: CompiledClientTable,
98
+ exceptId: string,
99
+ ): ScopeMap[] {
100
+ return units.flatMap((unit) => {
101
+ const scopes =
102
+ unit.id !== exceptId &&
103
+ (owning(unit) ||
104
+ (unit.status === 'active' &&
105
+ unit.echo !== undefined &&
106
+ unit.seeded.includes(table.name))) &&
107
+ covers(table, unit.scopes)
108
+ ? pairScopes(unit.scopes, table.name, unit.echo)
109
+ : undefined;
110
+ return scopes === undefined ? [] : [scopes];
111
+ });
112
+ }
113
+
114
+ /** A unit row; every persisted field must have its stored type and shape,
115
+ * otherwise the row is `sync.local_corrupt` (§7.5). */
116
+ function rowToRecord(row: Record<string, unknown>): UnitRecord {
117
+ const corrupt = () =>
118
+ new ClientSyncError(
119
+ 'sync.local_corrupt',
120
+ 'persisted unit state is invalid',
121
+ );
122
+ const json = (raw: unknown): unknown => {
123
+ if (typeof raw !== 'string') throw corrupt();
124
+ try {
125
+ return JSON.parse(raw);
126
+ } catch {
127
+ throw corrupt();
128
+ }
129
+ };
130
+ const isMap = (value: unknown): value is Record<string, unknown> =>
131
+ typeof value === 'object' && value !== null && !Array.isArray(value);
132
+ const isStrings = (value: unknown): value is string[] =>
133
+ Array.isArray(value) && value.every((item) => typeof item === 'string');
134
+ const optionalText = (value: unknown) => {
135
+ if (value !== null && typeof value !== 'string') throw corrupt();
136
+ return value ?? undefined;
61
137
  };
138
+ const scopes = json(row.scopes);
139
+ const seeded = json(row.seeded);
140
+ const echo = row.echo === null ? undefined : json(row.echo);
141
+ const { id, status, cursor } = row;
142
+ if (
143
+ typeof id !== 'string' ||
144
+ !isMap(scopes) ||
145
+ !Object.values(scopes).every((value) => typeof value === 'string') ||
146
+ (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
147
+ (cursor !== null && !Number.isInteger(cursor)) ||
148
+ !isStrings(seeded) ||
149
+ (echo !== undefined &&
150
+ !(
151
+ Array.isArray(echo) &&
152
+ echo.every(
153
+ (record) =>
154
+ isMap(record) &&
155
+ typeof record.table === 'string' &&
156
+ (record.status === 'active' || record.status === 'revoked') &&
157
+ isMap(record.scopes) &&
158
+ Object.values(record.scopes).every(isStrings),
159
+ )
160
+ ))
161
+ )
162
+ throw corrupt();
163
+ const record: { -readonly [K in keyof UnitRecord]: UnitRecord[K] } = {
164
+ id,
165
+ scopes: scopes as UnitScopes,
166
+ explicit: row.explicit === 1,
167
+ status,
168
+ seeded,
169
+ };
170
+ const reasonCode = optionalText(row.reason_code);
171
+ if (reasonCode !== undefined) record.reasonCode = reasonCode;
172
+ if (typeof cursor === 'number') record.cursor = cursor;
173
+ const bootstrapState = optionalText(row.bootstrap_state);
174
+ if (bootstrapState !== undefined) record.bootstrapState = bootstrapState;
175
+ if (echo !== undefined) record.echo = echo as FencedRecord[];
176
+ return record;
62
177
  }
63
178
 
64
- export function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[] {
179
+ /** Every unit in registration order (§4.1). */
180
+ export function loadUnits(db: ClientDatabase): UnitRecord[] {
65
181
  return db
66
- .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
182
+ .query(`SELECT * FROM ${UNITS_TABLE} ORDER BY rowid ASC`)
67
183
  .map(rowToRecord);
68
184
  }
69
185
 
70
- export function getSubscription(
186
+ export function getUnit(
71
187
  db: ClientDatabase,
72
188
  id: string,
73
- ): SubscriptionRecord | undefined {
74
- const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [
75
- id,
76
- ])[0];
189
+ ): UnitRecord | undefined {
190
+ const row = db.query(`SELECT * FROM ${UNITS_TABLE} WHERE id=?`, [id])[0];
77
191
  return row === undefined ? undefined : rowToRecord(row);
78
192
  }
79
193
 
80
- export function saveSubscription(
81
- db: ClientDatabase,
82
- record: SubscriptionRecord,
83
- ): void {
194
+ /** Insert or update in place: an update keeps the registration order. */
195
+ export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
84
196
  db.exec(
85
- `INSERT OR REPLACE INTO ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`,
197
+ `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo`,
86
198
  [
87
199
  record.id,
88
- record.table,
89
200
  JSON.stringify(record.scopes),
90
- record.params ?? null,
91
- record.cursor,
92
- record.bootstrapState ?? null,
93
- record.effectiveScopes === undefined
94
- ? null
95
- : JSON.stringify(record.effectiveScopes),
201
+ record.explicit ? 1 : 0,
96
202
  record.status,
97
203
  record.reasonCode ?? null,
204
+ record.cursor ?? null,
205
+ record.bootstrapState ?? null,
206
+ JSON.stringify(record.seeded),
207
+ record.echo === undefined ? null : JSON.stringify(record.echo),
98
208
  ],
99
209
  );
100
210
  }
101
211
 
102
- export function deleteSubscription(db: ClientDatabase, id: string): void {
103
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
212
+ export function deleteUnit(db: ClientDatabase, id: string): void {
213
+ db.exec(`DELETE FROM ${UNITS_TABLE} WHERE id=?`, [id]);
104
214
  }
105
215
 
106
216
  /**
107
- * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
108
- * requested scopes, params — the app's declared intent) but discard all
109
- * synced state (cursor → -1, no resume token, no effective-scope map,
110
- * status → active), so the next round fresh-bootstraps exactly the
111
- * subscriptions the app still wants. Caller owns the transaction.
217
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
218
+ * registrations (the app's declared intent) and discard every synced state,
219
+ * so the next round sends the list and fresh-bootstraps every unit. Caller
220
+ * owns the transaction.
112
221
  */
113
- export function resetSubscriptionsForBump(db: ClientDatabase): void {
222
+ export function resetUnits(db: ClientDatabase): void {
114
223
  db.exec(
115
- `UPDATE ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`,
224
+ `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`,
116
225
  );
226
+ db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
227
+ REPLICA_CURSOR_KEY,
228
+ ECHO_DIGEST_KEY,
229
+ REGISTERED_DIGEST_KEY,
230
+ ]);
231
+ }
232
+
233
+ /** §4.5: the replica cursor, `-1` while no unit is live. */
234
+ export function replicaCursor(db: ClientDatabase): number {
235
+ return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
117
236
  }
118
237
 
119
238
  type ScopeDeclarations = Record<
@@ -121,8 +240,8 @@ type ScopeDeclarations = Record<
121
240
  Record<string, readonly [string, string]>
122
241
  >;
123
242
 
124
- /** Persist declarations separately from the previous-version row descriptor. */
125
- export function saveSubscriptionScopeSchema(
243
+ /** §7.4.3 declaration evidence, persisted beside the schema marker. */
244
+ export function saveUnitScopeSchema(
126
245
  db: ClientDatabase,
127
246
  schema: CompiledClientSchema,
128
247
  ): void {
@@ -138,76 +257,78 @@ export function saveSubscriptionScopeSchema(
138
257
  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
139
258
  }
140
259
 
141
- /** Drop incompatible registrations and their windows; never translate scopes. */
142
- export function pruneUnknownSubscriptions(
260
+ /**
261
+ * Drop units that cover no table of the running schema, with their window
262
+ * registry rows and pending evictions; never translate scopes. At a bump
263
+ * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
264
+ * every table it covered before.
265
+ */
266
+ export function pruneUnknownUnits(
143
267
  db: ClientDatabase,
144
- subscriptions: readonly SubscriptionRecord[],
145
268
  schema: CompiledClientSchema,
146
269
  bump = false,
147
- ): SubscriptionRecord[] {
270
+ ): void {
148
271
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
149
272
  const previous =
150
273
  stored === undefined
151
274
  ? undefined
152
275
  : (JSON.parse(stored) as ScopeDeclarations);
153
- const compatible = (
154
- record: Pick<SubscriptionRecord, 'table' | 'scopes'>,
155
- ): boolean => {
156
- const table = schema.tables.get(record.table);
157
- if (table === undefined) return false;
158
- const variables = Object.keys(record.scopes);
159
- if (
160
- !variables.every((variable) => table.scopeColumnByVariable.has(variable))
161
- )
276
+ // A table keeps the variables' meaning when each has the same prefix and
277
+ // column as before. An old binary stored no declaration evidence; matching
278
+ // names cannot prove unchanged meaning, so the app registers again.
279
+ const unchanged = (name: string, variables: readonly string[]): boolean => {
280
+ const old = previous?.[name];
281
+ const table = schema.tables.get(name);
282
+ return (
283
+ old !== undefined &&
284
+ table !== undefined &&
285
+ variables.every(
286
+ (variable) =>
287
+ old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
288
+ old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
289
+ )
290
+ );
291
+ };
292
+ const compatible = (scopes: UnitScopes): boolean => {
293
+ const variables = Object.keys(scopes);
294
+ if (![...schema.tables.values()].some((table) => covers(table, scopes)))
162
295
  return false;
163
296
  if (!bump) return true;
164
- // An old binary stored no declaration evidence. Re-registration is required
165
- // at a bump: matching names cannot prove unchanged column/prefix meaning.
166
- const old = previous?.[record.table];
167
- if (old === undefined) return false;
168
- const compared =
169
- variables.length === 0
170
- ? [
171
- ...new Set([
172
- ...Object.keys(old),
173
- ...table.scopeColumnByVariable.keys(),
174
- ]),
175
- ]
176
- : variables;
177
- return compared.every(
178
- (variable) =>
179
- old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
180
- old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
297
+ if (previous === undefined) return false;
298
+ return Object.entries(previous).every(
299
+ ([name, old]) =>
300
+ !variables.every((variable) => old[variable] !== undefined) ||
301
+ unchanged(name, variables),
181
302
  );
182
303
  };
183
- const retained = subscriptions.filter(compatible);
184
- const staleIds = new Set(
185
- subscriptions
186
- .filter((record) => !compatible(record))
187
- .map((record) => record.id),
304
+ const stale = new Set(
305
+ loadUnits(db)
306
+ .filter((unit) => !compatible(unit.scopes))
307
+ .map((unit) => unit.id),
188
308
  );
189
- // Shrinking a pinned window already removed its registration. Its deferred
190
- // eviction still carries the old scope declaration and needs the same fence.
309
+ // A shrunk window's deferred eviction outlives its unit row and keeps its
310
+ // per-table scopes. A table the schema no longer has cannot be evicted, and
311
+ // at a bump a table whose scope declarations changed must not be evicted by
312
+ // the outdated rule.
191
313
  for (const row of db.query(
192
- `SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
314
+ `SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
193
315
  )) {
316
+ const table = String(row.tbl);
194
317
  if (
195
- !compatible({
196
- table: String(row.tbl),
197
- scopes: JSON.parse(String(row.effective_scopes)) as ScopeMap,
198
- })
318
+ !schema.tables.has(table) ||
319
+ (bump &&
320
+ !unchanged(
321
+ table,
322
+ Object.keys(JSON.parse(String(row.effective_scopes)) as ScopeMap),
323
+ ))
199
324
  )
200
- staleIds.add(String(row.sub_id));
325
+ stale.add(String(row.unit_id));
326
+ }
327
+ for (const id of stale) {
328
+ db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
329
+ db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
330
+ deleteUnit(db, id);
201
331
  }
202
- if (staleIds.size === 0) return retained;
203
- db.transaction(() => {
204
- for (const id of staleIds) {
205
- db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
206
- db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
207
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
208
- }
209
- });
210
- return retained;
211
332
  }
212
333
 
213
334
  export function getMeta(db: ClientDatabase, key: string): string | undefined {
@@ -45,6 +45,8 @@ export function installSyncScheduler(
45
45
  let backgroundReady = false;
46
46
  let backgroundDue = Number.POSITIVE_INFINITY;
47
47
  let cancelBackground: (() => void) | undefined;
48
+ // §7.7 backoff for drives that end without a client retry intent.
49
+ let retryDelayMs = 250;
48
50
 
49
51
  const report = (error: unknown): void => {
50
52
  if (options.onError !== undefined) {
@@ -88,6 +90,7 @@ export function installSyncScheduler(
88
90
  void client
89
91
  .syncUntilIdle(options.maxRounds)
90
92
  .then((result) => {
93
+ retryDelayMs = 250;
91
94
  if (
92
95
  result !== null &&
93
96
  typeof result === 'object' &&
@@ -98,7 +101,34 @@ export function installSyncScheduler(
98
101
  }
99
102
  })
100
103
  .catch((error: unknown) => {
101
- if (!stopped) report(error);
104
+ if (stopped) return;
105
+ report(error);
106
+ // §7.8: a retryable drive rejection owes another drive. A retryable
107
+ // round failure already handed this loop its background intent; the
108
+ // drive deadline did not. An unreachable endpoint waits for the
109
+ // host's connectivity resume (§1.8).
110
+ const details =
111
+ error instanceof Error && 'details' in error
112
+ ? error.details
113
+ : undefined;
114
+ const causeKind =
115
+ typeof details === 'object' &&
116
+ details !== null &&
117
+ 'causeKind' in details
118
+ ? details.causeKind
119
+ : undefined;
120
+ if (
121
+ error instanceof Error &&
122
+ 'retryable' in error &&
123
+ error.retryable === true &&
124
+ causeKind !== 'network' &&
125
+ causeKind !== 'connect' &&
126
+ cancelBackground === undefined &&
127
+ !immediatePending
128
+ ) {
129
+ consume({ kind: 'background', delayMs: retryDelayMs });
130
+ retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
131
+ }
102
132
  })
103
133
  .finally(() => {
104
134
  running = false;
package/src/transport.ts CHANGED
@@ -5,8 +5,15 @@
5
5
  * loopback doctrine; HTTP/WebSocket bindings live in `./http`.
6
6
  */
7
7
 
8
- /** One combined push+pull round trip: SSP2 request bytes → response bytes. */
9
- export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
8
+ /**
9
+ * One combined push+pull round trip: SSP2 request bytes → response bytes.
10
+ * `signal` aborts when the `syncUntilIdle` deadline elapses (§7.8); a
11
+ * transport that honors it releases the round instead of holding it open.
12
+ */
13
+ export type SyncTransport = (
14
+ request: Uint8Array,
15
+ signal?: AbortSignal,
16
+ ) => Promise<Uint8Array>;
10
17
 
11
18
  /** One registered authoritative query or command request. */
12
19
  export type RemoteOperationTransport = (
@@ -32,7 +39,14 @@ export interface SegmentFetchRequest {
32
39
  readonly table: string;
33
40
  /** Canonical JSON (§11.2) of the requested scope map (§5.5 header). */
34
41
  readonly requestedScopesJson: string;
42
+ /**
43
+ * The descriptor's `byteLength` (§5.4): the downloader stops reading once
44
+ * the body exceeds it, and the client core rejects the result.
45
+ */
46
+ readonly byteLength?: number;
35
47
  readonly onProgress?: (bytesReceived: number) => void;
48
+ /** Aborts with the round when the `syncUntilIdle` deadline elapses (§7.8). */
49
+ readonly signal?: AbortSignal;
36
50
  }
37
51
 
38
52
  /**
@@ -48,6 +62,9 @@ export interface SegmentDownloader {
48
62
  readonly fetchUrl?: (
49
63
  url: string,
50
64
  onProgress?: (bytesReceived: number) => void,
65
+ signal?: AbortSignal,
66
+ /** The descriptor's `byteLength`; reading stops once the body exceeds it. */
67
+ byteLength?: number,
51
68
  ) => Promise<Uint8Array>;
52
69
  }
53
70
 
@@ -72,4 +89,6 @@ export interface RealtimeSocket {
72
89
 
73
90
  export type RealtimeConnector = (
74
91
  handlers: RealtimeHandlers,
92
+ /** The client's id; the client passes it on every connect. */
93
+ clientId?: string,
75
94
  ) => Promise<RealtimeSocket> | RealtimeSocket;