@syncular/client 0.65.1 → 0.66.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.
- package/README.md +15 -7
- package/dist/apply.d.ts +4 -4
- package/dist/apply.js +55 -66
- package/dist/client.js +29 -9
- package/dist/progress.d.ts +4 -0
- package/dist/realtime-supervisor.d.ts +47 -13
- package/dist/realtime-supervisor.js +374 -277
- package/dist/wasm-database.js +9 -20
- package/package.json +3 -3
- package/src/apply.ts +77 -77
- package/src/client.ts +24 -3
- package/src/progress.ts +4 -0
- package/src/realtime-supervisor.ts +408 -303
- package/src/wasm-database.ts +11 -25
package/README.md
CHANGED
|
@@ -150,17 +150,21 @@ installRealtimeSupervisor(handle, {
|
|
|
150
150
|
});
|
|
151
151
|
```
|
|
152
152
|
|
|
153
|
-
It owns one connection attempt, retries initial failure and later
|
|
154
|
-
with bounded exponential jitter, suspends while
|
|
155
|
-
|
|
156
|
-
`
|
|
153
|
+
It owns one connection attempt at a time, retries initial failure and later
|
|
154
|
+
socket loss with bounded exponential jitter, suspends while
|
|
155
|
+
offline/background/protected without resetting that backoff, runs
|
|
156
|
+
`syncUntilIdle()` before reporting `connected`, and settles its attempt and
|
|
157
|
+
disconnect before `close()` closes the client. A failed disconnect, an
|
|
158
|
+
unreadable first diagnostics read, or a throwing timer cancel latches phase
|
|
159
|
+
`unsupported` with a `failureCode`, and `close()` rejects with a
|
|
160
|
+
`RealtimeSupervisorError` of that code.
|
|
157
161
|
|
|
158
162
|
Multi-tab handles share ONE leader socket across every tab, so pass
|
|
159
163
|
`sharedTransport: true` (the templates do): backgrounding this tab then
|
|
160
164
|
leaves the shared socket alone — a sibling tab may still be visible — while
|
|
161
165
|
offline and protection continue to suspend. Each client accepts exactly one
|
|
162
166
|
supervisor for its lifetime; a second `installRealtimeSupervisor` call
|
|
163
|
-
throws. `realtimeSupervisorSnapshot()` and
|
|
167
|
+
throws `realtime.supervisor_already_installed`. `realtimeSupervisorSnapshot()` and
|
|
164
168
|
`subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
|
|
165
169
|
library delay for UI/diagnostics—never raw transport prose or identities.
|
|
166
170
|
|
|
@@ -844,8 +848,12 @@ through the core, without intermediate download updates.
|
|
|
844
848
|
|
|
845
849
|
Import reports every 1,024 rows and its final count. `rowsProcessed` includes work
|
|
846
850
|
inside the current transaction; a failed import can roll those rows back. SQLite
|
|
847
|
-
images commit in
|
|
848
|
-
|
|
851
|
+
images commit in transactions of 1,024 rows, then twice as many per transaction
|
|
852
|
+
up to 65,536, and yield after each commit. Earlier committed transactions
|
|
853
|
+
survive a later interruption. A SQLite image payload also reports
|
|
854
|
+
`importWriteMs` (time before COMMIT: row statements with index maintenance)
|
|
855
|
+
and `importCommitMs` (COMMIT and revision publication), each summed over the
|
|
856
|
+
payload's transactions. `complete` follows checkpoint persistence
|
|
849
857
|
and optimistic-state reconciliation for the round. More bootstrap pages can
|
|
850
858
|
remain; use window coverage to determine whether a query is complete.
|
|
851
859
|
Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
|
package/dist/apply.d.ts
CHANGED
|
@@ -71,10 +71,10 @@ export interface SqliteSegmentDescriptor {
|
|
|
71
71
|
readonly scopeDigest: string;
|
|
72
72
|
}
|
|
73
73
|
/**
|
|
74
|
-
* Apply a §5.3 sqlite image in committed
|
|
75
|
-
* the in-file metadata against the descriptor, validate the
|
|
76
|
-
* column names/order against the generated schema, run the
|
|
77
|
-
* first-page clear when fresh, then bulk-copy
|
|
74
|
+
* Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
|
|
75
|
+
* rows: validate the in-file metadata against the descriptor, validate the
|
|
76
|
+
* data table's column names/order against the generated schema, run the
|
|
77
|
+
* §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
|
|
78
78
|
* primary-key upsert — `_syncular_version` lands in
|
|
79
79
|
* `_sync_version` exactly like a rows segment's per-row `serverVersion`.
|
|
80
80
|
*/
|
package/dist/apply.js
CHANGED
|
@@ -125,29 +125,15 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
|
|
|
125
125
|
* fatal (`sync.schema_mismatch`): the descriptor validates, never infers.
|
|
126
126
|
*/
|
|
127
127
|
export function validateSegmentColumns(schema, table, segment) {
|
|
128
|
-
const
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
if (segment.columns.length !== table.columns.length) {
|
|
138
|
-
mismatch(`column count ${segment.columns.length}`);
|
|
139
|
-
}
|
|
140
|
-
for (let i = 0; i < table.columns.length; i++) {
|
|
141
|
-
const expected = table.columns[i];
|
|
142
|
-
const actual = segment.columns[i];
|
|
143
|
-
if (expected === undefined || actual === undefined)
|
|
144
|
-
continue;
|
|
145
|
-
if (expected.name !== actual.name ||
|
|
146
|
-
expected.type !== actual.type ||
|
|
147
|
-
expected.nullable !== actual.nullable) {
|
|
148
|
-
mismatch(`column ${i} (${actual.name})`);
|
|
149
|
-
}
|
|
150
|
-
}
|
|
128
|
+
const column = segment.columns.length !== table.columns.length
|
|
129
|
+
? 'count'
|
|
130
|
+
: table.columns.findIndex((expected, i) => expected.name !== segment.columns[i]?.name ||
|
|
131
|
+
expected.type !== segment.columns[i]?.type ||
|
|
132
|
+
expected.nullable !== segment.columns[i]?.nullable);
|
|
133
|
+
if (segment.table !== table.name ||
|
|
134
|
+
segment.schemaVersion !== schema.version ||
|
|
135
|
+
column !== -1)
|
|
136
|
+
throw new ClientSyncError('sync.schema_mismatch', 'rows segment columns do not match the generated schema (§5.2)', false, column === -1 ? { table: table.name } : { table: table.name, column });
|
|
151
137
|
}
|
|
152
138
|
/**
|
|
153
139
|
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
@@ -252,10 +238,10 @@ function imageInvalid(detail) {
|
|
|
252
238
|
throw invalidRequest(`sqlite segment rejected: ${detail} (§5.3)`);
|
|
253
239
|
}
|
|
254
240
|
/**
|
|
255
|
-
* Apply a §5.3 sqlite image in committed
|
|
256
|
-
* the in-file metadata against the descriptor, validate the
|
|
257
|
-
* column names/order against the generated schema, run the
|
|
258
|
-
* first-page clear when fresh, then bulk-copy
|
|
241
|
+
* Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
|
|
242
|
+
* rows: validate the in-file metadata against the descriptor, validate the
|
|
243
|
+
* data table's column names/order against the generated schema, run the
|
|
244
|
+
* §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
|
|
259
245
|
* primary-key upsert — `_syncular_version` lands in
|
|
260
246
|
* `_sync_version` exactly like a rows segment's per-row `serverVersion`.
|
|
261
247
|
*/
|
|
@@ -285,23 +271,13 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
285
271
|
if (meta.length !== 1 || record === undefined) {
|
|
286
272
|
imageInvalid('_syncular_segment must contain exactly one row');
|
|
287
273
|
}
|
|
288
|
-
if (record.format !== 1
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
imageInvalid(
|
|
295
|
-
}
|
|
296
|
-
if (Number(record.pin) !== descriptor.asOfCommitSeq) {
|
|
297
|
-
imageInvalid(`asOfCommitSeq ${String(record.pin)}`);
|
|
298
|
-
}
|
|
299
|
-
if (record.sd !== descriptor.scopeDigest) {
|
|
300
|
-
imageInvalid('scopeDigest mismatch');
|
|
301
|
-
}
|
|
302
|
-
if (Number(record.rc) !== descriptor.rowCount) {
|
|
303
|
-
imageInvalid(`rowCount ${String(record.rc)}`);
|
|
304
|
-
}
|
|
274
|
+
if (record.format !== 1 ||
|
|
275
|
+
record.tbl !== table.name ||
|
|
276
|
+
Number(record.sv) !== schema.version ||
|
|
277
|
+
Number(record.pin) !== descriptor.asOfCommitSeq ||
|
|
278
|
+
record.sd !== descriptor.scopeDigest ||
|
|
279
|
+
Number(record.rc) !== descriptor.rowCount)
|
|
280
|
+
imageInvalid('_syncular_segment does not match the descriptor');
|
|
305
281
|
// 2. Column names and order vs the generated schema (§5.3 rule 3 —
|
|
306
282
|
// sync.schema_mismatch, the §5.2 rule specialized).
|
|
307
283
|
const info = db.query(`PRAGMA ${IMAGE_ALIAS}.table_info(${quoteIdent(table.name)})`);
|
|
@@ -312,7 +288,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
312
288
|
const actual = info.map((row) => String(row.name));
|
|
313
289
|
if (actual.length !== expected.length ||
|
|
314
290
|
expected.some((name, index) => actual[index] !== name)) {
|
|
315
|
-
throw new ClientSyncError('sync.schema_mismatch',
|
|
291
|
+
throw new ClientSyncError('sync.schema_mismatch', 'sqlite segment columns do not match the generated schema (§5.3)', false, { table: table.name });
|
|
316
292
|
}
|
|
317
293
|
const primaryKeys = info.filter((column) => Number(column.pk) > 0);
|
|
318
294
|
if (primaryKeys.length !== 1 || primaryKeys[0]?.name !== table.primaryKey)
|
|
@@ -329,50 +305,62 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
329
305
|
.map((name) => `${name}=excluded.${name}`)
|
|
330
306
|
.join(', ');
|
|
331
307
|
const version = quoteIdent(SYNC_VERSION_COLUMN);
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
const boundary = db.query(`SELECT ${primaryKey} AS
|
|
308
|
+
// A statement copies the 1,024 rows after `from`; NULL keys cannot hide
|
|
309
|
+
// between statements.
|
|
310
|
+
const range = (from) => {
|
|
311
|
+
const params = from === undefined ? [] : [from];
|
|
312
|
+
const predicates = from === undefined ? [] : [`${primaryKey}>?`];
|
|
313
|
+
const boundary = db.query(`SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, params)[0]?.b;
|
|
338
314
|
if (boundary === null)
|
|
339
315
|
imageInvalid('image primary key must not be null');
|
|
340
|
-
const predicates = [];
|
|
341
|
-
const params = [];
|
|
342
|
-
if (after !== undefined) {
|
|
343
|
-
predicates.push(`${primaryKey} > ?`);
|
|
344
|
-
params.push(after);
|
|
345
|
-
}
|
|
346
316
|
if (boundary !== undefined) {
|
|
347
|
-
predicates.push(`${primaryKey}
|
|
317
|
+
predicates.push(`${primaryKey}<=?`);
|
|
348
318
|
params.push(boundary);
|
|
349
319
|
}
|
|
320
|
+
return [boundary, predicates.join(' AND ') || 'true', params];
|
|
321
|
+
};
|
|
322
|
+
let [boundary, where, params] = range();
|
|
323
|
+
let applied = 0;
|
|
324
|
+
// §5.3: a transaction holds one statement at first and doubles after each
|
|
325
|
+
// commit up to 64; a replaying transaction holds one.
|
|
326
|
+
for (let statements = 1;; statements = Math.min(statements * 2, 64)) {
|
|
327
|
+
if (options.isCurrent?.() === false)
|
|
328
|
+
return applied;
|
|
329
|
+
const first = applied === 0;
|
|
350
330
|
const replay = countOutbox(db) ||
|
|
351
331
|
db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [
|
|
352
332
|
table.name,
|
|
353
333
|
]).length;
|
|
354
334
|
const rows = replay
|
|
355
|
-
? db.query(`SELECT * FROM ${source} WHERE ${
|
|
335
|
+
? db.query(`SELECT * FROM ${source} WHERE ${where}`, params)
|
|
356
336
|
: [];
|
|
357
337
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
358
338
|
const scope = !replay
|
|
359
339
|
? []
|
|
360
340
|
: [
|
|
361
341
|
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
362
|
-
...(
|
|
342
|
+
...(first && options.clearFirst
|
|
363
343
|
? bootstrapScope(db, table, options.effective, options.owners)
|
|
364
344
|
: []),
|
|
365
345
|
...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
|
|
366
346
|
];
|
|
367
347
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
368
|
-
if (
|
|
348
|
+
if (first && options.clearFirst)
|
|
369
349
|
deleteScopedRows(db, table, options.effective, options.owners);
|
|
370
350
|
const kept = new Set();
|
|
371
351
|
const skipped = new Set();
|
|
372
352
|
const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
353
|
+
for (let statement = 1;; statement++) {
|
|
354
|
+
db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${where} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates} WHERE excluded.${version}>${quoteIdent(table.name)}.${version}`, params);
|
|
355
|
+
applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
|
|
356
|
+
options.onProgress?.(applied);
|
|
357
|
+
if (replay ||
|
|
358
|
+
statement === statements ||
|
|
359
|
+
boundary === undefined ||
|
|
360
|
+
applied === count)
|
|
361
|
+
break;
|
|
362
|
+
[boundary, where, params] = range(boundary);
|
|
363
|
+
}
|
|
376
364
|
if (protectedRows)
|
|
377
365
|
for (const row of landing) {
|
|
378
366
|
retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
|
|
@@ -382,14 +370,15 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
382
370
|
}
|
|
383
371
|
return rebaseScope(scope, kept, skipped);
|
|
384
372
|
});
|
|
385
|
-
options.onProgress?.(applied);
|
|
386
373
|
await yieldToHost();
|
|
387
374
|
if (boundary === undefined || applied === count)
|
|
388
375
|
break;
|
|
389
|
-
|
|
376
|
+
[boundary, where, params] = range(boundary);
|
|
390
377
|
}
|
|
391
378
|
if (applied !== count)
|
|
392
379
|
imageInvalid('image applied row count does not match descriptor');
|
|
380
|
+
// A file replica's WAL keeps its high-water size until truncated.
|
|
381
|
+
db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
|
|
393
382
|
return applied;
|
|
394
383
|
});
|
|
395
384
|
}
|
package/dist/client.js
CHANGED
|
@@ -3915,6 +3915,8 @@ export class SyncClient {
|
|
|
3915
3915
|
bytesTotal: frame.byteLength,
|
|
3916
3916
|
rowsProcessed: 0,
|
|
3917
3917
|
rowsTotal: frame.rowCount,
|
|
3918
|
+
importWriteMs: undefined,
|
|
3919
|
+
importCommitMs: undefined,
|
|
3918
3920
|
});
|
|
3919
3921
|
prefetch();
|
|
3920
3922
|
const pending = prefetched.get(frame);
|
|
@@ -3947,11 +3949,13 @@ export class SyncClient {
|
|
|
3947
3949
|
bytesTotal: bytes.byteLength,
|
|
3948
3950
|
rowsProcessed: 0,
|
|
3949
3951
|
rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
|
|
3952
|
+
importWriteMs: undefined,
|
|
3953
|
+
importCommitMs: undefined,
|
|
3950
3954
|
});
|
|
3951
3955
|
await this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
|
|
3952
3956
|
const options = this.#segmentApplyOptions(table, clearFirst, effective, owners, image !== undefined
|
|
3953
3957
|
? image.rowCount > 0
|
|
3954
|
-
: segment.blocks.some((block) => block.length > 0), resetEpoch);
|
|
3958
|
+
: segment.blocks.some((block) => block.length > 0), resetEpoch, image !== undefined);
|
|
3955
3959
|
return image !== undefined
|
|
3956
3960
|
? applySqliteSegment(this.#db, this.#schema, table, bytes, image, options)
|
|
3957
3961
|
: applyRowsSegment(this.#db, this.#schema, table, segment, options, this.#encryption);
|
|
@@ -4355,21 +4359,37 @@ export class SyncClient {
|
|
|
4355
4359
|
this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
|
|
4356
4360
|
}
|
|
4357
4361
|
/** Shared transaction, reset fence and progress for both segment formats. */
|
|
4358
|
-
#segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch) {
|
|
4362
|
+
#segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch, image) {
|
|
4363
|
+
let writeMs = 0;
|
|
4364
|
+
let commitMs = 0;
|
|
4359
4365
|
return {
|
|
4360
4366
|
clearFirst,
|
|
4361
4367
|
effective,
|
|
4362
4368
|
owners,
|
|
4363
4369
|
isCurrent: () => this.#localResetEpoch === resetEpoch,
|
|
4364
4370
|
onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
|
|
4365
|
-
transaction: (fn) =>
|
|
4366
|
-
|
|
4367
|
-
|
|
4368
|
-
|
|
4369
|
-
|
|
4370
|
-
|
|
4371
|
+
transaction: (fn) => {
|
|
4372
|
+
const started = performance.now();
|
|
4373
|
+
let written = started;
|
|
4374
|
+
const result = this.#applyBatch((batch) => {
|
|
4375
|
+
if (hasRows ||
|
|
4376
|
+
(clearFirst && this.#scopedRowsExist(table, effective, owners)))
|
|
4377
|
+
batch.table(table.name);
|
|
4378
|
+
const result = fn();
|
|
4379
|
+
this.#replayOutbox(result, false);
|
|
4380
|
+
written = performance.now();
|
|
4381
|
+
return result;
|
|
4382
|
+
});
|
|
4383
|
+
// §7.7: image payloads report their import cost.
|
|
4384
|
+
writeMs += written - started;
|
|
4385
|
+
commitMs += performance.now() - written;
|
|
4386
|
+
if (image)
|
|
4387
|
+
this.#progress.update({
|
|
4388
|
+
importWriteMs: Math.round(writeMs),
|
|
4389
|
+
importCommitMs: Math.round(commitMs),
|
|
4390
|
+
});
|
|
4371
4391
|
return result;
|
|
4372
|
-
}
|
|
4392
|
+
},
|
|
4373
4393
|
};
|
|
4374
4394
|
}
|
|
4375
4395
|
/**
|
package/dist/progress.d.ts
CHANGED
|
@@ -11,6 +11,10 @@ export interface SyncProgress {
|
|
|
11
11
|
readonly bytesTotal?: number;
|
|
12
12
|
readonly rowsProcessed: number;
|
|
13
13
|
readonly rowsTotal?: number;
|
|
14
|
+
/** Time in this payload's import transactions before COMMIT, in ms. */
|
|
15
|
+
readonly importWriteMs?: number | undefined;
|
|
16
|
+
/** Time committing them and publishing their changes, in ms. */
|
|
17
|
+
readonly importCommitMs?: number | undefined;
|
|
14
18
|
readonly errorCode?: string;
|
|
15
19
|
readonly causeKind?: TransportCauseKind;
|
|
16
20
|
readonly httpStatus?: number;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { SecurityLifecycle } from './client.js';
|
|
2
2
|
import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
|
|
3
|
+
import { ClientSyncError } from './errors.js';
|
|
3
4
|
type CancelTimer = () => void;
|
|
4
5
|
export interface RealtimeSupervisorClient {
|
|
5
6
|
connectRealtime(): Promise<void>;
|
|
@@ -23,13 +24,18 @@ export interface RealtimeSupervisorSnapshot {
|
|
|
23
24
|
readonly attempt: number;
|
|
24
25
|
/** Bounded host-policy delay, never server or transport prose. */
|
|
25
26
|
readonly retryDelayMs?: number;
|
|
27
|
+
/** The latched failure of phase `unsupported` (or `stopped`). */
|
|
28
|
+
readonly failureCode?: RealtimeSupervisorFailureCode;
|
|
26
29
|
}
|
|
30
|
+
/** SPEC §10.3: client-local supervisor failures, never on the wire. */
|
|
31
|
+
export type RealtimeSupervisorFailureCode = 'realtime.diagnostics_unavailable' | 'realtime.disconnect_failed' | 'realtime.cleanup_failed';
|
|
27
32
|
export interface RealtimeSupervisorOptions {
|
|
28
33
|
/**
|
|
29
34
|
* Host online/offline evidence, the only connectivity the supervisor
|
|
30
35
|
* trusts: a failed round does not suspend it. Unknown remains connectable
|
|
31
|
-
* and observable. Each `online` report drives `syncUntilIdle
|
|
32
|
-
* failed round left behind resumes without
|
|
36
|
+
* and observable. Each `online` report drives `syncUntilIdle` while no
|
|
37
|
+
* socket is connected, so work a failed round left behind resumes without
|
|
38
|
+
* realtime.
|
|
33
39
|
*/
|
|
34
40
|
readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
|
|
35
41
|
/** Browser/native foreground evidence. Background suspends a tab-owned
|
|
@@ -73,12 +79,33 @@ export declare function browserConnectivitySignal(options?: BrowserConnectivityS
|
|
|
73
79
|
/** Browser/Tauri-webview visibility evidence without importing DOM types. */
|
|
74
80
|
export declare function documentLifecycleSignal(options?: DocumentLifecycleSignalOptions): RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
|
|
75
81
|
/**
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
|
|
81
|
-
|
|
82
|
+
* SPEC §8.4: a supervisor failure. `code` is the latest latched failure, or
|
|
83
|
+
* `realtime.cleanup_failed` when only a cancel threw. Every failure of the
|
|
84
|
+
* lifetime is also named in its own field. Cause codes are Syncular codes or
|
|
85
|
+
* `unknown`; no message or original error is retained.
|
|
86
|
+
*/
|
|
87
|
+
export declare class RealtimeSupervisorError extends ClientSyncError {
|
|
88
|
+
readonly name = "RealtimeSupervisorError";
|
|
89
|
+
readonly code: RealtimeSupervisorFailureCode;
|
|
90
|
+
readonly cleanupFailureCode?: 'realtime.cleanup_failed';
|
|
91
|
+
readonly diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
|
|
92
|
+
/** The code the client's `disconnectRealtime` rejected with. */
|
|
93
|
+
readonly disconnectCauseCode?: string;
|
|
94
|
+
/** Set by the installed `close()` when the client close failed as well. */
|
|
95
|
+
readonly stopFailureCode?: RealtimeSupervisorFailureCode;
|
|
96
|
+
readonly closeFailureCode?: string;
|
|
97
|
+
constructor(code: RealtimeSupervisorFailureCode, fields?: Omit<Partial<RealtimeSupervisorError>, 'code'>);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Supported host policy for Syncular's explicit realtime transport (§8.4). It
|
|
101
|
+
* owns one attempt at a time: a connect, then an explicit catch-up round
|
|
102
|
+
* before it claims connected. A successor never starts before the previous
|
|
103
|
+
* attempt and its disconnect settle. Transient loss retries with bounded
|
|
104
|
+
* exponential jitter, and the backoff survives offline, background and
|
|
105
|
+
* protected suspensions. While no socket is connected, each failed connect,
|
|
106
|
+
* each host `online` report and each foreground return drives one HTTP round
|
|
107
|
+
* (§1.8). A disconnect, diagnostics or cleanup failure latches phase
|
|
108
|
+
* `unsupported` with its `failureCode`, and `stop()` rejects with it.
|
|
82
109
|
*/
|
|
83
110
|
export declare class RealtimeSupervisor {
|
|
84
111
|
#private;
|
|
@@ -86,13 +113,20 @@ export declare class RealtimeSupervisor {
|
|
|
86
113
|
snapshot(): RealtimeSupervisorSnapshot;
|
|
87
114
|
subscribe(listener: () => void): () => void;
|
|
88
115
|
start(): void;
|
|
89
|
-
|
|
116
|
+
/**
|
|
117
|
+
* Cancel the timer and every subscription, release the socket, and settle
|
|
118
|
+
* once the in-flight attempt, its disconnect and any driven round have
|
|
119
|
+
* settled. Rejects with a {@link RealtimeSupervisorError} when a failure
|
|
120
|
+
* latched during the lifetime or a cancel threw; every caller shares it.
|
|
121
|
+
*/
|
|
122
|
+
stop(): Promise<void>;
|
|
90
123
|
}
|
|
91
124
|
/**
|
|
92
|
-
* Install one supervisor and make client disposal
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
125
|
+
* Install one supervisor and make client disposal stop it before close.
|
|
126
|
+
* Repeated and reentrant `close()` calls share one operation. A client accepts
|
|
127
|
+
* exactly one supervisor for its lifetime; installing a second throws
|
|
128
|
+
* `realtime.supervisor_already_installed`, because silently keeping the first
|
|
129
|
+
* would discard the second call's options.
|
|
96
130
|
*/
|
|
97
131
|
export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
|
|
98
132
|
export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;
|