@syncular/client 0.52.0 → 0.53.1
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 +5 -0
- package/dist/client.d.ts +3 -0
- package/dist/client.js +60 -28
- package/dist/devtools.d.ts +7 -7
- package/dist/devtools.js +7 -1
- package/dist/diagnostics.d.ts +4 -0
- package/dist/progress.d.ts +3 -0
- package/dist/worker-host.d.ts +4 -0
- package/dist/worker-host.js +5 -3
- package/package.json +5 -4
- package/src/client.ts +73 -35
- package/src/devtools.ts +23 -12
- package/src/diagnostics.ts +17 -0
- package/src/progress.ts +4 -0
- package/src/worker-host.ts +10 -4
package/README.md
CHANGED
|
@@ -393,6 +393,11 @@ and generated table names, never scopes. It lets a support screen distinguish
|
|
|
393
393
|
an absent registration from a legitimate zero-row completed bootstrap. The
|
|
394
394
|
snapshot also distinguishes reset, revocation, failure, schema floor, lease
|
|
395
395
|
stop, pending outbox, offline transport, and storage pressure/unreadability.
|
|
396
|
+
Failed progress and `lastRound` diagnostics expose an optional bounded
|
|
397
|
+
`causeKind` and HTTP status. Worker leaders and followers receive the same
|
|
398
|
+
evidence. A new progress attempt clears its failure fields; a successful round
|
|
399
|
+
replaces the failed last round. `host.connectivity` describes the latest
|
|
400
|
+
endpoint observation and does not prove the device's network state.
|
|
396
401
|
`queryFailures` retains at most 256 failed owned snapshot reads until each query
|
|
397
402
|
reads successfully. An entry contains only its stable PHI-free owner id,
|
|
398
403
|
generated table names, a stable code, an optional numeric SQLite result code,
|
package/dist/client.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
|
12
12
|
import { 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
|
+
import type { DevtoolsRegistrar } from './devtools.js';
|
|
15
16
|
import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
|
|
16
17
|
import type { EncryptionConfig } from './encryption.js';
|
|
17
18
|
import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
|
|
@@ -146,6 +147,8 @@ export interface SyncClientLimits {
|
|
|
146
147
|
readonly maxPushRequestBytes?: number;
|
|
147
148
|
}
|
|
148
149
|
export interface SyncClientConfig {
|
|
150
|
+
/** Explicit development console registry; absent means no registration. */
|
|
151
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
149
152
|
readonly transportEnabled?: boolean;
|
|
150
153
|
/** Keep rejected/conflicting local intent visible until explicit resolution. */
|
|
151
154
|
readonly retainFailedCommits?: boolean;
|
package/dist/client.js
CHANGED
|
@@ -19,7 +19,6 @@ import { EncryptError } from '@syncular/core';
|
|
|
19
19
|
import { EncodeError } from '@syncular/core';
|
|
20
20
|
import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
|
|
21
21
|
import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
|
|
22
|
-
import { registerDevtools } from './devtools.js';
|
|
23
22
|
import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
|
|
24
23
|
import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
|
|
25
24
|
import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
|
|
@@ -450,7 +449,7 @@ export class SyncClient {
|
|
|
450
449
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
451
450
|
}
|
|
452
451
|
// Console introspection is a no-op outside a dev page.
|
|
453
|
-
this.#devtoolsUnregister =
|
|
452
|
+
this.#devtoolsUnregister = this.#config.devtools?.({
|
|
454
453
|
kind: 'client',
|
|
455
454
|
ref: this,
|
|
456
455
|
clientId: () => this.#clientId,
|
|
@@ -1323,9 +1322,13 @@ export class SyncClient {
|
|
|
1323
1322
|
: this.#lastRound?.status === 'succeeded'
|
|
1324
1323
|
? 'online'
|
|
1325
1324
|
: this.#lastRound?.status === 'failed' &&
|
|
1326
|
-
|
|
1325
|
+
(this.#lastRound.causeKind === 'network' ||
|
|
1326
|
+
this.#lastRound.causeKind === 'connect')
|
|
1327
1327
|
? 'offline'
|
|
1328
|
-
: '
|
|
1328
|
+
: this.#lastRound?.status === 'failed' &&
|
|
1329
|
+
this.#lastRound.httpStatus !== undefined
|
|
1330
|
+
? 'online'
|
|
1331
|
+
: 'unknown';
|
|
1329
1332
|
const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
|
|
1330
1333
|
const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
|
|
1331
1334
|
const aExpected = expectedOrder.get(a.id);
|
|
@@ -1713,6 +1716,14 @@ export class SyncClient {
|
|
|
1713
1716
|
(!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
|
|
1714
1717
|
throw invalidRequest('maxRounds must be a positive integer');
|
|
1715
1718
|
const { clientCommitId, sequence } = outcome;
|
|
1719
|
+
const provable = (candidate) => candidate !== undefined &&
|
|
1720
|
+
candidate.sequence === sequence &&
|
|
1721
|
+
candidate.resolution === 'active' &&
|
|
1722
|
+
(candidate.status === 'conflict' || candidate.status === 'rejected') &&
|
|
1723
|
+
candidate.operations !== undefined &&
|
|
1724
|
+
candidate.retainedRows !== undefined &&
|
|
1725
|
+
candidate.operations.length === candidate.retainedRows.length &&
|
|
1726
|
+
candidate.retainedRows.length > 0;
|
|
1716
1727
|
let initial;
|
|
1717
1728
|
try {
|
|
1718
1729
|
initial = readCommitOutcome(this.#db, clientCommitId);
|
|
@@ -1720,14 +1731,7 @@ export class SyncClient {
|
|
|
1720
1731
|
catch {
|
|
1721
1732
|
return { proven: false, reason: 'snapshot_failed' };
|
|
1722
1733
|
}
|
|
1723
|
-
if (initial
|
|
1724
|
-
initial.sequence !== sequence ||
|
|
1725
|
-
initial.resolution !== 'active' ||
|
|
1726
|
-
(initial.status !== 'conflict' && initial.status !== 'rejected') ||
|
|
1727
|
-
initial.operations === undefined ||
|
|
1728
|
-
initial.retainedRows === undefined ||
|
|
1729
|
-
initial.operations.length !== initial.retainedRows.length ||
|
|
1730
|
-
initial.retainedRows.length === 0)
|
|
1734
|
+
if (!provable(initial))
|
|
1731
1735
|
return { proven: false, reason: 'outcome_unavailable' };
|
|
1732
1736
|
if (!this.#transportEnabled)
|
|
1733
1737
|
return { proven: false, reason: 'offline' };
|
|
@@ -1778,15 +1782,7 @@ export class SyncClient {
|
|
|
1778
1782
|
});
|
|
1779
1783
|
const delivery = snapshot.deliveries[0];
|
|
1780
1784
|
const current = readCommitOutcome(this.#db, clientCommitId);
|
|
1781
|
-
if (delivery?.status !== 'known' ||
|
|
1782
|
-
current === undefined ||
|
|
1783
|
-
current.sequence !== sequence ||
|
|
1784
|
-
current.resolution !== 'active' ||
|
|
1785
|
-
(current.status !== 'conflict' && current.status !== 'rejected') ||
|
|
1786
|
-
current.operations === undefined ||
|
|
1787
|
-
current.retainedRows === undefined ||
|
|
1788
|
-
current.operations.length !== current.retainedRows.length ||
|
|
1789
|
-
current.retainedRows.length === 0)
|
|
1785
|
+
if (delivery?.status !== 'known' || !provable(current))
|
|
1790
1786
|
return {
|
|
1791
1787
|
proven: false,
|
|
1792
1788
|
reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
|
|
@@ -2895,12 +2891,53 @@ export class SyncClient {
|
|
|
2895
2891
|
const error = classifySqliteFailure(caught).error;
|
|
2896
2892
|
const completedAtMs = this.#now();
|
|
2897
2893
|
const code = error.code;
|
|
2894
|
+
const details = typeof error === 'object' && error !== null && 'details' in error
|
|
2895
|
+
? error.details
|
|
2896
|
+
: undefined;
|
|
2897
|
+
const rawCause = typeof details === 'object' &&
|
|
2898
|
+
details !== null &&
|
|
2899
|
+
'causeKind' in details
|
|
2900
|
+
? details.causeKind
|
|
2901
|
+
: undefined;
|
|
2902
|
+
let causeKind;
|
|
2903
|
+
switch (rawCause) {
|
|
2904
|
+
case 'network':
|
|
2905
|
+
case 'connect':
|
|
2906
|
+
case 'tls':
|
|
2907
|
+
case 'io':
|
|
2908
|
+
case 'request':
|
|
2909
|
+
case 'protocol':
|
|
2910
|
+
case 'timeout':
|
|
2911
|
+
case 'round_deadline':
|
|
2912
|
+
case 'aborted':
|
|
2913
|
+
case 'body':
|
|
2914
|
+
case 'status':
|
|
2915
|
+
case 'redirect':
|
|
2916
|
+
case 'unknown':
|
|
2917
|
+
causeKind = rawCause;
|
|
2918
|
+
}
|
|
2919
|
+
const rawStatus = typeof details === 'object' &&
|
|
2920
|
+
details !== null &&
|
|
2921
|
+
'httpStatus' in details
|
|
2922
|
+
? details.httpStatus
|
|
2923
|
+
: undefined;
|
|
2924
|
+
const httpStatus = (causeKind === 'status' ||
|
|
2925
|
+
causeKind === 'body' ||
|
|
2926
|
+
causeKind === 'redirect') &&
|
|
2927
|
+
typeof rawStatus === 'number' &&
|
|
2928
|
+
Number.isInteger(rawStatus) &&
|
|
2929
|
+
rawStatus >= 100 &&
|
|
2930
|
+
rawStatus <= 599
|
|
2931
|
+
? rawStatus
|
|
2932
|
+
: undefined;
|
|
2898
2933
|
this.#progress.update(definedObject({
|
|
2899
2934
|
state: 'failed',
|
|
2900
2935
|
errorCode: typeof code === 'string'
|
|
2901
2936
|
? this.#diagnosticCode(code)
|
|
2902
2937
|
: 'client.unknown_failure',
|
|
2903
2938
|
retryDelayMs: this.#roundRetryDelayMs,
|
|
2939
|
+
causeKind,
|
|
2940
|
+
httpStatus,
|
|
2904
2941
|
}));
|
|
2905
2942
|
this.#lastRound = {
|
|
2906
2943
|
status: 'failed',
|
|
@@ -2910,6 +2947,8 @@ export class SyncClient {
|
|
|
2910
2947
|
errorCode: typeof code === 'string'
|
|
2911
2948
|
? this.#diagnosticCode(code)
|
|
2912
2949
|
: 'client.unknown_failure',
|
|
2950
|
+
...(causeKind !== undefined ? { causeKind } : {}),
|
|
2951
|
+
...(httpStatus !== undefined ? { httpStatus } : {}),
|
|
2913
2952
|
};
|
|
2914
2953
|
this.#emitDiagnostics();
|
|
2915
2954
|
throw error;
|
|
@@ -2937,13 +2976,6 @@ export class SyncClient {
|
|
|
2937
2976
|
deferredCommits: summary.deferredCommits ?? 0,
|
|
2938
2977
|
};
|
|
2939
2978
|
}
|
|
2940
|
-
#transportFailureCode(code) {
|
|
2941
|
-
return (code === 'transport.failed' ||
|
|
2942
|
-
code === 'transport.unavailable' ||
|
|
2943
|
-
code === 'sync.transport_failed' ||
|
|
2944
|
-
code === 'client.worker_failed' ||
|
|
2945
|
-
code === 'client.worker_restart_required');
|
|
2946
|
-
}
|
|
2947
2979
|
#diagnosticCode(code) {
|
|
2948
2980
|
return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
|
|
2949
2981
|
? code
|
package/dist/devtools.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The client-side introspection registry:
|
|
3
|
-
* `SyncClient` / `SyncClientHandle` on a page registers itself on
|
|
2
|
+
* The optional client-side introspection registry: a configured
|
|
3
|
+
* `SyncClient` / `SyncClientHandle` on a development page registers itself on
|
|
4
4
|
* `globalThis.__SYNCULAR__`, so a first integration debugs from the console
|
|
5
5
|
* instead of hand-exposing the client:
|
|
6
6
|
*
|
|
@@ -11,11 +11,9 @@
|
|
|
11
11
|
* // last invalidation
|
|
12
12
|
* __SYNCULAR__.clients[0].ref // the client itself — full API
|
|
13
13
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
* production builds skip installation; environments without `process` are
|
|
18
|
-
* treated as dev). Cost when gated off: one function call per client.
|
|
14
|
+
* The host explicitly supplies `registerDevtools` in its client config. The
|
|
15
|
+
* registry also requires a development or test environment signal and a
|
|
16
|
+
* `window`. A browser without a development signal leaves it disabled.
|
|
19
17
|
*/
|
|
20
18
|
import type { InvalidationListener } from './invalidation.js';
|
|
21
19
|
/** What a registrant supplies — plain lambdas over its own surface. */
|
|
@@ -34,6 +32,8 @@ export interface DevtoolsRegistration {
|
|
|
34
32
|
readonly upgrading: () => Promise<boolean>;
|
|
35
33
|
readonly onInvalidate: (listener: InvalidationListener) => () => void;
|
|
36
34
|
}
|
|
35
|
+
/** Explicit development registry supplied to a client or worker handle. */
|
|
36
|
+
export type DevtoolsRegistrar = (registration: DevtoolsRegistration) => () => void;
|
|
37
37
|
/** One live entry on the registry (a registration plus tracked state). */
|
|
38
38
|
export interface DevtoolsEntry extends DevtoolsRegistration {
|
|
39
39
|
/** The most recent invalidation event, timestamped (epoch ms). */
|
package/dist/devtools.js
CHANGED
|
@@ -4,7 +4,13 @@ function registryHost() {
|
|
|
4
4
|
const g = globalThis;
|
|
5
5
|
if (g.window === undefined)
|
|
6
6
|
return undefined;
|
|
7
|
-
if (
|
|
7
|
+
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
8
|
+
return undefined;
|
|
9
|
+
if (!((typeof import.meta.env !== 'undefined' &&
|
|
10
|
+
import.meta.env.DEV === true) ||
|
|
11
|
+
(typeof process !== 'undefined' &&
|
|
12
|
+
(process.env.NODE_ENV === 'development' ||
|
|
13
|
+
process.env.NODE_ENV === 'test'))))
|
|
8
14
|
return undefined;
|
|
9
15
|
return g;
|
|
10
16
|
}
|
package/dist/diagnostics.d.ts
CHANGED
|
@@ -13,6 +13,8 @@ export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
|
|
|
13
13
|
export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
|
|
14
14
|
export type ClientDiagnosticsHostRole = 'single' | 'leader' | 'follower' | 'unknown';
|
|
15
15
|
export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
|
|
16
|
+
/** Bounded transport classification shared by progress and diagnostics (§1.8). */
|
|
17
|
+
export type TransportCauseKind = 'network' | 'connect' | 'tls' | 'io' | 'request' | 'protocol' | 'timeout' | 'round_deadline' | 'aborted' | 'body' | 'status' | 'redirect' | 'unknown';
|
|
16
18
|
/**
|
|
17
19
|
* SPEC §8.8: how a client treats the realtime binding for sync rounds. The
|
|
18
20
|
* default is `optional`.
|
|
@@ -82,6 +84,8 @@ export type DiagnosticLastRound = {
|
|
|
82
84
|
readonly durationMs: number;
|
|
83
85
|
/** Stable code only; never arbitrary transport/server prose. */
|
|
84
86
|
readonly errorCode: string;
|
|
87
|
+
readonly causeKind?: TransportCauseKind;
|
|
88
|
+
readonly httpStatus?: number;
|
|
85
89
|
};
|
|
86
90
|
export interface DiagnosticLastChange {
|
|
87
91
|
/** Decimal u64 for JSON/IPC parity. */
|
package/dist/progress.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { TransportCauseKind } from './diagnostics.js';
|
|
1
2
|
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
|
|
2
3
|
export interface SyncProgress {
|
|
3
4
|
readonly attempt: number;
|
|
@@ -11,6 +12,8 @@ export interface SyncProgress {
|
|
|
11
12
|
readonly rowsProcessed: number;
|
|
12
13
|
readonly rowsTotal?: number;
|
|
13
14
|
readonly errorCode?: string;
|
|
15
|
+
readonly causeKind?: TransportCauseKind;
|
|
16
|
+
readonly httpStatus?: number;
|
|
14
17
|
/** Present on `failed` when the core scheduled a background retry. */
|
|
15
18
|
readonly retryDelayMs?: number;
|
|
16
19
|
}
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -27,6 +27,7 @@ import type { WakeReason } from '@syncular/core';
|
|
|
27
27
|
import type { BlobRef, CachedBlob } from './blob.js';
|
|
28
28
|
import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
|
|
29
29
|
import type { SqlRow, SqlValue } from './database.js';
|
|
30
|
+
import type { DevtoolsRegistrar } from './devtools.js';
|
|
30
31
|
import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
|
|
31
32
|
import type { EncryptionKeyringConfig } from './encryption.js';
|
|
32
33
|
import { ClientSyncError } from './errors.js';
|
|
@@ -65,6 +66,8 @@ export declare function isolatedReplicaNames(options: {
|
|
|
65
66
|
readonly replicaId: string;
|
|
66
67
|
}): IsolatedReplicaNames;
|
|
67
68
|
export interface SyncClientHandleConfig {
|
|
69
|
+
/** Explicit development console registry for this page's handle. */
|
|
70
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
68
71
|
/**
|
|
69
72
|
* Spawns the worker running `startSyncWorker()` (a factory so bundlers
|
|
70
73
|
* see `new Worker(new URL(...))` at the call site, and so no worker is
|
|
@@ -193,6 +196,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
193
196
|
leadershipListeners?: Set<(state: LeadershipState) => void>;
|
|
194
197
|
unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
|
|
195
198
|
leadership?: LeadershipState;
|
|
199
|
+
devtools?: DevtoolsRegistrar;
|
|
196
200
|
});
|
|
197
201
|
/**
|
|
198
202
|
* @internal — apply a leadership snapshot in place: a promotion flips the
|
package/dist/worker-host.js
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { ProgressEmitter, } from './progress.js';
|
|
2
|
-
import { registerDevtools } from './devtools.js';
|
|
3
2
|
import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
|
|
4
3
|
import { ClientSyncError } from './errors.js';
|
|
5
4
|
import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
|
|
@@ -107,7 +106,7 @@ export class SyncClientHandle {
|
|
|
107
106
|
this.#leadershipListeners = internals.leadershipListeners ?? new Set();
|
|
108
107
|
this.#unreachableListeners = internals.unreachableListeners ?? new Set();
|
|
109
108
|
// Console introspection is a no-op outside a dev page.
|
|
110
|
-
this.#devtoolsUnregister =
|
|
109
|
+
this.#devtoolsUnregister = internals.devtools?.({
|
|
111
110
|
kind: 'handle',
|
|
112
111
|
ref: this,
|
|
113
112
|
clientId: () => this.#clientId,
|
|
@@ -442,7 +441,7 @@ export class SyncClientHandle {
|
|
|
442
441
|
return;
|
|
443
442
|
this.#closed = true;
|
|
444
443
|
this.#progress.clear();
|
|
445
|
-
this.#devtoolsUnregister();
|
|
444
|
+
this.#devtoolsUnregister?.();
|
|
446
445
|
await this.#tabs?.close();
|
|
447
446
|
if (this.#core !== undefined) {
|
|
448
447
|
const core = this.#core;
|
|
@@ -660,6 +659,9 @@ export async function createSyncClientHandle(config) {
|
|
|
660
659
|
roleListeners,
|
|
661
660
|
leadershipListeners,
|
|
662
661
|
unreachableListeners,
|
|
662
|
+
...(resolvedConfig.devtools !== undefined
|
|
663
|
+
? { devtools: resolvedConfig.devtools }
|
|
664
|
+
: {}),
|
|
663
665
|
};
|
|
664
666
|
if (resolvedConfig.multiTab === false) {
|
|
665
667
|
// Single-tab contract: the leader runs its core with no channel; a losing
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.53.1",
|
|
4
4
|
"description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -97,11 +97,12 @@
|
|
|
97
97
|
},
|
|
98
98
|
"dependencies": {
|
|
99
99
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
100
|
-
"@syncular/core": "0.
|
|
100
|
+
"@syncular/core": "0.53.1"
|
|
101
101
|
},
|
|
102
102
|
"devDependencies": {
|
|
103
|
-
"@syncular/server": "0.
|
|
103
|
+
"@syncular/server": "0.53.1",
|
|
104
104
|
"playwright": "1.63.0",
|
|
105
|
-
"@electric-sql/pglite": "^0.5.4"
|
|
105
|
+
"@electric-sql/pglite": "^0.5.4",
|
|
106
|
+
"vite": "8.3.4"
|
|
106
107
|
}
|
|
107
108
|
}
|
package/src/client.ts
CHANGED
|
@@ -86,7 +86,7 @@ import {
|
|
|
86
86
|
serializeBlobRef,
|
|
87
87
|
} from './blob';
|
|
88
88
|
import type { ClientDatabase, SqlRow, SqlValue } from './database';
|
|
89
|
-
import {
|
|
89
|
+
import type { DevtoolsRegistrar } from './devtools';
|
|
90
90
|
import {
|
|
91
91
|
CLIENT_DIAGNOSTICS_VERSION,
|
|
92
92
|
ClientDiagnosticsEmitter,
|
|
@@ -104,6 +104,7 @@ import {
|
|
|
104
104
|
MAX_DIAGNOSTIC_QUERY_FAILURES,
|
|
105
105
|
type RealtimePolicy,
|
|
106
106
|
type RealtimeState,
|
|
107
|
+
type TransportCauseKind,
|
|
107
108
|
} from './diagnostics';
|
|
108
109
|
import type { EncryptionConfig } from './encryption';
|
|
109
110
|
import {
|
|
@@ -416,6 +417,8 @@ export interface SyncClientLimits {
|
|
|
416
417
|
}
|
|
417
418
|
|
|
418
419
|
export interface SyncClientConfig {
|
|
420
|
+
/** Explicit development console registry; absent means no registration. */
|
|
421
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
419
422
|
readonly transportEnabled?: boolean;
|
|
420
423
|
/** Keep rejected/conflicting local intent visible until explicit resolution. */
|
|
421
424
|
readonly retainFailedCommits?: boolean;
|
|
@@ -1251,7 +1254,7 @@ export class SyncClient {
|
|
|
1251
1254
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
1252
1255
|
}
|
|
1253
1256
|
// Console introspection is a no-op outside a dev page.
|
|
1254
|
-
this.#devtoolsUnregister =
|
|
1257
|
+
this.#devtoolsUnregister = this.#config.devtools?.({
|
|
1255
1258
|
kind: 'client',
|
|
1256
1259
|
ref: this,
|
|
1257
1260
|
clientId: () => this.#clientId,
|
|
@@ -2290,9 +2293,13 @@ export class SyncClient {
|
|
|
2290
2293
|
: this.#lastRound?.status === 'succeeded'
|
|
2291
2294
|
? 'online'
|
|
2292
2295
|
: this.#lastRound?.status === 'failed' &&
|
|
2293
|
-
|
|
2296
|
+
(this.#lastRound.causeKind === 'network' ||
|
|
2297
|
+
this.#lastRound.causeKind === 'connect')
|
|
2294
2298
|
? 'offline'
|
|
2295
|
-
: '
|
|
2299
|
+
: this.#lastRound?.status === 'failed' &&
|
|
2300
|
+
this.#lastRound.httpStatus !== undefined
|
|
2301
|
+
? 'online'
|
|
2302
|
+
: 'unknown';
|
|
2296
2303
|
const expectedOrder = new Map(
|
|
2297
2304
|
expected.map((item, index) => [item.id, index] as const),
|
|
2298
2305
|
);
|
|
@@ -2776,22 +2783,26 @@ export class SyncClient {
|
|
|
2776
2783
|
)
|
|
2777
2784
|
throw invalidRequest('maxRounds must be a positive integer');
|
|
2778
2785
|
const { clientCommitId, sequence } = outcome;
|
|
2786
|
+
const provable = (
|
|
2787
|
+
candidate: CommitOutcome | undefined,
|
|
2788
|
+
): candidate is CommitOutcome & {
|
|
2789
|
+
readonly retainedRows: readonly RetainedCommitRow[];
|
|
2790
|
+
} =>
|
|
2791
|
+
candidate !== undefined &&
|
|
2792
|
+
candidate.sequence === sequence &&
|
|
2793
|
+
candidate.resolution === 'active' &&
|
|
2794
|
+
(candidate.status === 'conflict' || candidate.status === 'rejected') &&
|
|
2795
|
+
candidate.operations !== undefined &&
|
|
2796
|
+
candidate.retainedRows !== undefined &&
|
|
2797
|
+
candidate.operations.length === candidate.retainedRows.length &&
|
|
2798
|
+
candidate.retainedRows.length > 0;
|
|
2779
2799
|
let initial: CommitOutcome | undefined;
|
|
2780
2800
|
try {
|
|
2781
2801
|
initial = readCommitOutcome(this.#db, clientCommitId);
|
|
2782
2802
|
} catch {
|
|
2783
2803
|
return { proven: false, reason: 'snapshot_failed' };
|
|
2784
2804
|
}
|
|
2785
|
-
if (
|
|
2786
|
-
initial === undefined ||
|
|
2787
|
-
initial.sequence !== sequence ||
|
|
2788
|
-
initial.resolution !== 'active' ||
|
|
2789
|
-
(initial.status !== 'conflict' && initial.status !== 'rejected') ||
|
|
2790
|
-
initial.operations === undefined ||
|
|
2791
|
-
initial.retainedRows === undefined ||
|
|
2792
|
-
initial.operations.length !== initial.retainedRows.length ||
|
|
2793
|
-
initial.retainedRows.length === 0
|
|
2794
|
-
)
|
|
2805
|
+
if (!provable(initial))
|
|
2795
2806
|
return { proven: false, reason: 'outcome_unavailable' };
|
|
2796
2807
|
if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
|
|
2797
2808
|
await this.#opChain;
|
|
@@ -2841,17 +2852,7 @@ export class SyncClient {
|
|
|
2841
2852
|
});
|
|
2842
2853
|
const delivery = snapshot.deliveries[0];
|
|
2843
2854
|
const current = readCommitOutcome(this.#db, clientCommitId);
|
|
2844
|
-
if (
|
|
2845
|
-
delivery?.status !== 'known' ||
|
|
2846
|
-
current === undefined ||
|
|
2847
|
-
current.sequence !== sequence ||
|
|
2848
|
-
current.resolution !== 'active' ||
|
|
2849
|
-
(current.status !== 'conflict' && current.status !== 'rejected') ||
|
|
2850
|
-
current.operations === undefined ||
|
|
2851
|
-
current.retainedRows === undefined ||
|
|
2852
|
-
current.operations.length !== current.retainedRows.length ||
|
|
2853
|
-
current.retainedRows.length === 0
|
|
2854
|
-
)
|
|
2855
|
+
if (delivery?.status !== 'known' || !provable(current))
|
|
2855
2856
|
return {
|
|
2856
2857
|
proven: false,
|
|
2857
2858
|
reason:
|
|
@@ -4227,6 +4228,49 @@ export class SyncClient {
|
|
|
4227
4228
|
const error = classifySqliteFailure(caught).error;
|
|
4228
4229
|
const completedAtMs = this.#now();
|
|
4229
4230
|
const code = (error as { code?: unknown }).code;
|
|
4231
|
+
const details =
|
|
4232
|
+
typeof error === 'object' && error !== null && 'details' in error
|
|
4233
|
+
? error.details
|
|
4234
|
+
: undefined;
|
|
4235
|
+
const rawCause =
|
|
4236
|
+
typeof details === 'object' &&
|
|
4237
|
+
details !== null &&
|
|
4238
|
+
'causeKind' in details
|
|
4239
|
+
? details.causeKind
|
|
4240
|
+
: undefined;
|
|
4241
|
+
let causeKind: TransportCauseKind | undefined;
|
|
4242
|
+
switch (rawCause) {
|
|
4243
|
+
case 'network':
|
|
4244
|
+
case 'connect':
|
|
4245
|
+
case 'tls':
|
|
4246
|
+
case 'io':
|
|
4247
|
+
case 'request':
|
|
4248
|
+
case 'protocol':
|
|
4249
|
+
case 'timeout':
|
|
4250
|
+
case 'round_deadline':
|
|
4251
|
+
case 'aborted':
|
|
4252
|
+
case 'body':
|
|
4253
|
+
case 'status':
|
|
4254
|
+
case 'redirect':
|
|
4255
|
+
case 'unknown':
|
|
4256
|
+
causeKind = rawCause;
|
|
4257
|
+
}
|
|
4258
|
+
const rawStatus =
|
|
4259
|
+
typeof details === 'object' &&
|
|
4260
|
+
details !== null &&
|
|
4261
|
+
'httpStatus' in details
|
|
4262
|
+
? details.httpStatus
|
|
4263
|
+
: undefined;
|
|
4264
|
+
const httpStatus =
|
|
4265
|
+
(causeKind === 'status' ||
|
|
4266
|
+
causeKind === 'body' ||
|
|
4267
|
+
causeKind === 'redirect') &&
|
|
4268
|
+
typeof rawStatus === 'number' &&
|
|
4269
|
+
Number.isInteger(rawStatus) &&
|
|
4270
|
+
rawStatus >= 100 &&
|
|
4271
|
+
rawStatus <= 599
|
|
4272
|
+
? rawStatus
|
|
4273
|
+
: undefined;
|
|
4230
4274
|
this.#progress.update(
|
|
4231
4275
|
definedObject({
|
|
4232
4276
|
state: 'failed',
|
|
@@ -4235,6 +4279,8 @@ export class SyncClient {
|
|
|
4235
4279
|
? this.#diagnosticCode(code)
|
|
4236
4280
|
: 'client.unknown_failure',
|
|
4237
4281
|
retryDelayMs: this.#roundRetryDelayMs,
|
|
4282
|
+
causeKind,
|
|
4283
|
+
httpStatus,
|
|
4238
4284
|
}),
|
|
4239
4285
|
);
|
|
4240
4286
|
this.#lastRound = {
|
|
@@ -4246,6 +4292,8 @@ export class SyncClient {
|
|
|
4246
4292
|
typeof code === 'string'
|
|
4247
4293
|
? this.#diagnosticCode(code)
|
|
4248
4294
|
: 'client.unknown_failure',
|
|
4295
|
+
...(causeKind !== undefined ? { causeKind } : {}),
|
|
4296
|
+
...(httpStatus !== undefined ? { httpStatus } : {}),
|
|
4249
4297
|
};
|
|
4250
4298
|
this.#emitDiagnostics();
|
|
4251
4299
|
throw error;
|
|
@@ -4275,16 +4323,6 @@ export class SyncClient {
|
|
|
4275
4323
|
};
|
|
4276
4324
|
}
|
|
4277
4325
|
|
|
4278
|
-
#transportFailureCode(code: string): boolean {
|
|
4279
|
-
return (
|
|
4280
|
-
code === 'transport.failed' ||
|
|
4281
|
-
code === 'transport.unavailable' ||
|
|
4282
|
-
code === 'sync.transport_failed' ||
|
|
4283
|
-
code === 'client.worker_failed' ||
|
|
4284
|
-
code === 'client.worker_restart_required'
|
|
4285
|
-
);
|
|
4286
|
-
}
|
|
4287
|
-
|
|
4288
4326
|
#diagnosticCode(code: string): string {
|
|
4289
4327
|
return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
|
|
4290
4328
|
? code
|
package/src/devtools.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The client-side introspection registry:
|
|
3
|
-
* `SyncClient` / `SyncClientHandle` on a page registers itself on
|
|
2
|
+
* The optional client-side introspection registry: a configured
|
|
3
|
+
* `SyncClient` / `SyncClientHandle` on a development page registers itself on
|
|
4
4
|
* `globalThis.__SYNCULAR__`, so a first integration debugs from the console
|
|
5
5
|
* instead of hand-exposing the client:
|
|
6
6
|
*
|
|
@@ -11,11 +11,9 @@
|
|
|
11
11
|
* // last invalidation
|
|
12
12
|
* __SYNCULAR__.clients[0].ref // the client itself — full API
|
|
13
13
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
* production builds skip installation; environments without `process` are
|
|
18
|
-
* treated as dev). Cost when gated off: one function call per client.
|
|
14
|
+
* The host explicitly supplies `registerDevtools` in its client config. The
|
|
15
|
+
* registry also requires a development or test environment signal and a
|
|
16
|
+
* `window`. A browser without a development signal leaves it disabled.
|
|
19
17
|
*/
|
|
20
18
|
import type { InvalidationEvent, InvalidationListener } from './invalidation';
|
|
21
19
|
|
|
@@ -36,6 +34,11 @@ export interface DevtoolsRegistration {
|
|
|
36
34
|
readonly onInvalidate: (listener: InvalidationListener) => () => void;
|
|
37
35
|
}
|
|
38
36
|
|
|
37
|
+
/** Explicit development registry supplied to a client or worker handle. */
|
|
38
|
+
export type DevtoolsRegistrar = (
|
|
39
|
+
registration: DevtoolsRegistration,
|
|
40
|
+
) => () => void;
|
|
41
|
+
|
|
39
42
|
/** One live entry on the registry (a registration plus tracked state). */
|
|
40
43
|
export interface DevtoolsEntry extends DevtoolsRegistration {
|
|
41
44
|
/** The most recent invalidation event, timestamped (epoch ms). */
|
|
@@ -55,12 +58,20 @@ const KEY = '__SYNCULAR__';
|
|
|
55
58
|
|
|
56
59
|
/** The page global to install on, or undefined when gated off. */
|
|
57
60
|
function registryHost(): Record<string, unknown> | undefined {
|
|
58
|
-
const g = globalThis as Record<string, unknown> & {
|
|
59
|
-
window?: unknown;
|
|
60
|
-
process?: { env?: { NODE_ENV?: string } };
|
|
61
|
-
};
|
|
61
|
+
const g = globalThis as Record<string, unknown> & { window?: unknown };
|
|
62
62
|
if (g.window === undefined) return undefined;
|
|
63
|
-
if (
|
|
63
|
+
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
64
|
+
return undefined;
|
|
65
|
+
if (
|
|
66
|
+
!(
|
|
67
|
+
(typeof import.meta.env !== 'undefined' &&
|
|
68
|
+
(import.meta.env.DEV as boolean | string | undefined) === true) ||
|
|
69
|
+
(typeof process !== 'undefined' &&
|
|
70
|
+
(process.env.NODE_ENV === 'development' ||
|
|
71
|
+
process.env.NODE_ENV === 'test'))
|
|
72
|
+
)
|
|
73
|
+
)
|
|
74
|
+
return undefined;
|
|
64
75
|
return g;
|
|
65
76
|
}
|
|
66
77
|
|
package/src/diagnostics.ts
CHANGED
|
@@ -23,6 +23,21 @@ export type ClientDiagnosticsHostRole =
|
|
|
23
23
|
| 'follower'
|
|
24
24
|
| 'unknown';
|
|
25
25
|
export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
|
|
26
|
+
/** Bounded transport classification shared by progress and diagnostics (§1.8). */
|
|
27
|
+
export type TransportCauseKind =
|
|
28
|
+
| 'network'
|
|
29
|
+
| 'connect'
|
|
30
|
+
| 'tls'
|
|
31
|
+
| 'io'
|
|
32
|
+
| 'request'
|
|
33
|
+
| 'protocol'
|
|
34
|
+
| 'timeout'
|
|
35
|
+
| 'round_deadline'
|
|
36
|
+
| 'aborted'
|
|
37
|
+
| 'body'
|
|
38
|
+
| 'status'
|
|
39
|
+
| 'redirect'
|
|
40
|
+
| 'unknown';
|
|
26
41
|
/**
|
|
27
42
|
* SPEC §8.8: how a client treats the realtime binding for sync rounds. The
|
|
28
43
|
* default is `optional`.
|
|
@@ -115,6 +130,8 @@ export type DiagnosticLastRound =
|
|
|
115
130
|
readonly durationMs: number;
|
|
116
131
|
/** Stable code only; never arbitrary transport/server prose. */
|
|
117
132
|
readonly errorCode: string;
|
|
133
|
+
readonly causeKind?: TransportCauseKind;
|
|
134
|
+
readonly httpStatus?: number;
|
|
118
135
|
};
|
|
119
136
|
|
|
120
137
|
export interface DiagnosticLastChange {
|
package/src/progress.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { TransportCauseKind } from './diagnostics';
|
|
2
|
+
|
|
1
3
|
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
|
|
2
4
|
export interface SyncProgress {
|
|
3
5
|
readonly attempt: number;
|
|
@@ -11,6 +13,8 @@ export interface SyncProgress {
|
|
|
11
13
|
readonly rowsProcessed: number;
|
|
12
14
|
readonly rowsTotal?: number;
|
|
13
15
|
readonly errorCode?: string;
|
|
16
|
+
readonly causeKind?: TransportCauseKind;
|
|
17
|
+
readonly httpStatus?: number;
|
|
14
18
|
/** Present on `failed` when the core scheduled a background retry. */
|
|
15
19
|
readonly retryDelayMs?: number;
|
|
16
20
|
}
|
package/src/worker-host.ts
CHANGED
|
@@ -49,7 +49,7 @@ import type {
|
|
|
49
49
|
WindowState,
|
|
50
50
|
} from './client';
|
|
51
51
|
import type { SqlRow, SqlValue } from './database';
|
|
52
|
-
import {
|
|
52
|
+
import type { DevtoolsRegistrar } from './devtools';
|
|
53
53
|
import {
|
|
54
54
|
ClientDiagnosticsEmitter,
|
|
55
55
|
type ClientDiagnosticsListener,
|
|
@@ -178,6 +178,8 @@ export function isolatedReplicaNames(options: {
|
|
|
178
178
|
}
|
|
179
179
|
|
|
180
180
|
export interface SyncClientHandleConfig {
|
|
181
|
+
/** Explicit development console registry for this page's handle. */
|
|
182
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
181
183
|
/**
|
|
182
184
|
* Spawns the worker running `startSyncWorker()` (a factory so bundlers
|
|
183
185
|
* see `new Worker(new URL(...))` at the call site, and so no worker is
|
|
@@ -337,7 +339,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
337
339
|
readonly #roleListeners: Set<(role: HandleRole) => void>;
|
|
338
340
|
readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
|
|
339
341
|
readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
|
|
340
|
-
readonly #devtoolsUnregister: () => void;
|
|
342
|
+
readonly #devtoolsUnregister: (() => void) | undefined;
|
|
341
343
|
#closed = false;
|
|
342
344
|
|
|
343
345
|
/** @internal — use {@link createSyncClientHandle}. */
|
|
@@ -355,6 +357,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
355
357
|
leadershipListeners?: Set<(state: LeadershipState) => void>;
|
|
356
358
|
unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
|
|
357
359
|
leadership?: LeadershipState;
|
|
360
|
+
devtools?: DevtoolsRegistrar;
|
|
358
361
|
}) {
|
|
359
362
|
this.#role = internals.role;
|
|
360
363
|
this.#clientId = internals.clientId;
|
|
@@ -380,7 +383,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
380
383
|
this.#leadershipListeners = internals.leadershipListeners ?? new Set();
|
|
381
384
|
this.#unreachableListeners = internals.unreachableListeners ?? new Set();
|
|
382
385
|
// Console introspection is a no-op outside a dev page.
|
|
383
|
-
this.#devtoolsUnregister =
|
|
386
|
+
this.#devtoolsUnregister = internals.devtools?.({
|
|
384
387
|
kind: 'handle',
|
|
385
388
|
ref: this,
|
|
386
389
|
clientId: () => this.#clientId,
|
|
@@ -832,7 +835,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
832
835
|
if (this.#closed) return;
|
|
833
836
|
this.#closed = true;
|
|
834
837
|
this.#progress.clear();
|
|
835
|
-
this.#devtoolsUnregister();
|
|
838
|
+
this.#devtoolsUnregister?.();
|
|
836
839
|
await this.#tabs?.close();
|
|
837
840
|
if (this.#core !== undefined) {
|
|
838
841
|
const core = this.#core;
|
|
@@ -1076,6 +1079,9 @@ export async function createSyncClientHandle(
|
|
|
1076
1079
|
roleListeners,
|
|
1077
1080
|
leadershipListeners,
|
|
1078
1081
|
unreachableListeners,
|
|
1082
|
+
...(resolvedConfig.devtools !== undefined
|
|
1083
|
+
? { devtools: resolvedConfig.devtools }
|
|
1084
|
+
: {}),
|
|
1079
1085
|
};
|
|
1080
1086
|
|
|
1081
1087
|
if (resolvedConfig.multiTab === false) {
|