@syncular/client 0.65.0 → 0.65.2
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 +9 -5
- package/dist/realtime-supervisor.d.ts +47 -13
- package/dist/realtime-supervisor.js +377 -294
- package/package.json +3 -3
- package/src/realtime-supervisor.ts +404 -317
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
|
|
|
@@ -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;
|