@syncular/client 0.53.1 → 0.55.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 +10 -0
- package/dist/client.js +30 -23
- package/dist/invalidation.d.ts +8 -0
- package/dist/invalidation.js +7 -0
- package/dist/worker-core.d.ts +77 -0
- package/dist/worker-core.js +505 -0
- package/dist/worker-entry.d.ts +3 -55
- package/dist/worker-entry.js +4 -553
- package/dist/worker-local-authority.d.ts +3 -0
- package/dist/worker-local-authority.js +70 -0
- package/dist/worker-protocol.d.ts +2 -0
- package/dist/worker-protocol.js +2 -0
- package/dist/worker-remote.d.ts +5 -0
- package/dist/worker-remote.js +5 -0
- package/package.json +12 -4
- package/src/client.ts +42 -21
- package/src/invalidation.ts +19 -0
- package/src/worker-core.ts +713 -0
- package/src/worker-entry.ts +5 -743
- package/src/worker-local-authority.ts +106 -0
- package/src/worker-protocol.ts +3 -0
- package/src/worker-remote.ts +14 -0
package/README.md
CHANGED
|
@@ -48,6 +48,15 @@ import { startSyncWorker } from '@syncular/client/worker';
|
|
|
48
48
|
startSyncWorker();
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
+
Use `@syncular/client/worker/remote` for a worker that only connects to a
|
|
52
|
+
remote authority. It omits the local-authority lifecycle from the worker
|
|
53
|
+
bundle while preserving the normal client and multi-tab APIs. It refuses an
|
|
54
|
+
initialization with `localAuthority: true` before opening storage using
|
|
55
|
+
`client.local_authority_unconfigured`. The shared handle still declares its
|
|
56
|
+
local-authority methods; those calls fail with
|
|
57
|
+
`client.worker_method_unavailable` on a remote-only worker. Use
|
|
58
|
+
`@syncular/client/worker` to run a local authority.
|
|
59
|
+
|
|
51
60
|
```ts
|
|
52
61
|
// main thread
|
|
53
62
|
import { createSyncClientHandle } from '@syncular/client';
|
|
@@ -741,6 +750,7 @@ they own their buffer.
|
|
|
741
750
|
|---|---|
|
|
742
751
|
| `.` | protocol core, transports, handle + RPC protocol (browser-safe, no SQLite) |
|
|
743
752
|
| `./worker` | `startSyncWorker` — worker-side bootstrap (pulls sqlite-wasm) |
|
|
753
|
+
| `./worker/remote` | remote-only worker bootstrap without the local-authority lifecycle |
|
|
744
754
|
| `./wasm` | sqlite-wasm bindings: `openPersistentWasmDatabase`, `openWasmDatabase` |
|
|
745
755
|
| `./sqlite` | Runtime-selected SQLite: `openSqliteDatabase` on Node or Bun |
|
|
746
756
|
| `./bun` | Explicit `bun:sqlite` binding: `openBunDatabase` |
|
package/dist/client.js
CHANGED
|
@@ -173,13 +173,10 @@ export class SyncClient {
|
|
|
173
173
|
#needsPull = false;
|
|
174
174
|
#progress = new ProgressEmitter();
|
|
175
175
|
#progressAttempt = 0;
|
|
176
|
-
#syncing = false;
|
|
177
176
|
/**
|
|
178
177
|
* True from the synchronous entry of `sync()` until its serialized round
|
|
179
178
|
* settles — the "one loop owns the database" guard that rejects a
|
|
180
|
-
* concurrent `sync()` before the op chain would queue it.
|
|
181
|
-
* `#syncing`, which is true only while `#runSync`'s body actually runs
|
|
182
|
-
* (the fast-bail the delta path reads).
|
|
179
|
+
* concurrent `sync()` before the op chain would queue it.
|
|
183
180
|
*/
|
|
184
181
|
#syncOutstanding = false;
|
|
185
182
|
/**
|
|
@@ -2999,10 +2996,7 @@ export class SyncClient {
|
|
|
2999
2996
|
schemaFloor: this.#schemaFloor,
|
|
3000
2997
|
};
|
|
3001
2998
|
}
|
|
3002
|
-
|
|
3003
|
-
// Cleared before the round, not after: a wake-up (or a delta dropped
|
|
3004
|
-
// because this pull is mid-flight) that lands during the round must
|
|
3005
|
-
// survive it — the reference server keeps no replay buffer (§8.2).
|
|
2999
|
+
// A wake-up that lands during the round must survive it (§8.4).
|
|
3006
3000
|
this.#setSyncNeeded(false);
|
|
3007
3001
|
try {
|
|
3008
3002
|
await this.#drainPendingEvictions();
|
|
@@ -3180,9 +3174,6 @@ export class SyncClient {
|
|
|
3180
3174
|
}
|
|
3181
3175
|
throw error;
|
|
3182
3176
|
}
|
|
3183
|
-
finally {
|
|
3184
|
-
this.#syncing = false;
|
|
3185
|
-
}
|
|
3186
3177
|
}
|
|
3187
3178
|
/**
|
|
3188
3179
|
* Pull repeatedly until quiescent: no commits delivered, no bootstrap
|
|
@@ -3654,19 +3645,24 @@ export class SyncClient {
|
|
|
3654
3645
|
async #handleRealtimeBinary(bytes) {
|
|
3655
3646
|
if (!this.#transportEnabled)
|
|
3656
3647
|
return;
|
|
3657
|
-
|
|
3658
|
-
|
|
3659
|
-
|
|
3660
|
-
// worth it. (An optimization; the op chain below is the correctness
|
|
3661
|
-
// mechanism — it also excludes a delta from racing a `setWindow` or a
|
|
3662
|
-
// sync round that started between this check and the apply.)
|
|
3663
|
-
this.#setSyncNeeded(true);
|
|
3664
|
-
return;
|
|
3665
|
-
}
|
|
3648
|
+
const resetEpoch = this.#localResetEpoch;
|
|
3649
|
+
const securityEpoch = this.#securityEpoch;
|
|
3650
|
+
const transportEpoch = this.#transportEpoch;
|
|
3666
3651
|
// Serialize the apply on the operation chain: a delta must never
|
|
3667
3652
|
// interleave its transactions or share the `#batch` accumulator with a
|
|
3668
3653
|
// pull round or a `setWindow` at an await point (§8.2).
|
|
3669
3654
|
await this.#serialize(async () => {
|
|
3655
|
+
if (!this.#started ||
|
|
3656
|
+
!this.#transportEnabled ||
|
|
3657
|
+
this.#securityLifecycle !== 'active' ||
|
|
3658
|
+
securityEpoch !== this.#securityEpoch ||
|
|
3659
|
+
transportEpoch !== this.#transportEpoch)
|
|
3660
|
+
return;
|
|
3661
|
+
if (resetEpoch !== this.#localResetEpoch) {
|
|
3662
|
+
this.#setSyncNeeded(true);
|
|
3663
|
+
this.#emitSyncNeeded('catchup-required');
|
|
3664
|
+
return;
|
|
3665
|
+
}
|
|
3670
3666
|
try {
|
|
3671
3667
|
const message = decodeMessage(bytes);
|
|
3672
3668
|
if (message.msgKind !== 'response')
|
|
@@ -3942,7 +3938,9 @@ export class SyncClient {
|
|
|
3942
3938
|
break;
|
|
3943
3939
|
}
|
|
3944
3940
|
case 'COMMIT':
|
|
3945
|
-
if (section !== undefined &&
|
|
3941
|
+
if (section !== undefined &&
|
|
3942
|
+
!section.skip &&
|
|
3943
|
+
section.sub !== undefined) {
|
|
3946
3944
|
const changes = frame.changes.filter((change) => {
|
|
3947
3945
|
if (change.op !== 'delete')
|
|
3948
3946
|
return true;
|
|
@@ -3951,7 +3949,7 @@ export class SyncClient {
|
|
|
3951
3949
|
!coalescedDeletes.has(deleteKey(frame.commitSeq, table, change.rowId)));
|
|
3952
3950
|
});
|
|
3953
3951
|
if (changes.length > 0) {
|
|
3954
|
-
await this.#applyCommit({ ...frame, changes }, summary);
|
|
3952
|
+
await this.#applyCommit({ ...frame, changes }, summary, section.sub.id, mode);
|
|
3955
3953
|
}
|
|
3956
3954
|
}
|
|
3957
3955
|
break;
|
|
@@ -4261,11 +4259,20 @@ export class SyncClient {
|
|
|
4261
4259
|
});
|
|
4262
4260
|
return names;
|
|
4263
4261
|
}
|
|
4264
|
-
async #applyCommit(frame, summary) {
|
|
4262
|
+
async #applyCommit(frame, summary, subscriptionId, source) {
|
|
4265
4263
|
await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
|
|
4266
4264
|
this.#recordCommitChanges(batch, frame);
|
|
4267
4265
|
const result = fn();
|
|
4268
4266
|
this.#replayOutbox(result, false);
|
|
4267
|
+
for (const table of new Set(frame.changes.map((change) => frame.tables[change.tableIndex]))) {
|
|
4268
|
+
if (table !== undefined)
|
|
4269
|
+
batch.appliedCommit({
|
|
4270
|
+
subscriptionId,
|
|
4271
|
+
table,
|
|
4272
|
+
commitSeq: frame.commitSeq,
|
|
4273
|
+
source,
|
|
4274
|
+
});
|
|
4275
|
+
}
|
|
4269
4276
|
return result;
|
|
4270
4277
|
}));
|
|
4271
4278
|
summary.commitsApplied += 1;
|
package/dist/invalidation.d.ts
CHANGED
|
@@ -44,6 +44,13 @@ export interface ClientChangeBatch {
|
|
|
44
44
|
readonly conflictsChanged: boolean;
|
|
45
45
|
readonly rejectionsChanged: boolean;
|
|
46
46
|
readonly outcomesChanged: boolean;
|
|
47
|
+
/** Server COMMIT frames applied by this transaction, when present. */
|
|
48
|
+
readonly appliedCommits?: readonly {
|
|
49
|
+
readonly subscriptionId: string;
|
|
50
|
+
readonly table: string;
|
|
51
|
+
readonly commitSeq: number;
|
|
52
|
+
readonly source: 'delta' | 'pull';
|
|
53
|
+
}[];
|
|
47
54
|
}
|
|
48
55
|
export type ClientChangeListener = (batch: ClientChangeBatch) => void;
|
|
49
56
|
/** Network work created by a core command (SPEC §7.5). */
|
|
@@ -69,6 +76,7 @@ export declare const NO_COMMAND_EFFECTS: CommandEffects;
|
|
|
69
76
|
*/
|
|
70
77
|
export declare class ChangeAccumulator {
|
|
71
78
|
#private;
|
|
79
|
+
appliedCommit(entry: NonNullable<ClientChangeBatch['appliedCommits']>[number]): void;
|
|
72
80
|
/** Mark a whole table dirty, discarding any weaker scope-only facts. */
|
|
73
81
|
table(name: string): void;
|
|
74
82
|
/** Associate a precise `prefix:value` key with its table. */
|
package/dist/invalidation.js
CHANGED
|
@@ -12,6 +12,10 @@ export class ChangeAccumulator {
|
|
|
12
12
|
#conflicts = false;
|
|
13
13
|
#rejections = false;
|
|
14
14
|
#outcomes = false;
|
|
15
|
+
#appliedCommits = [];
|
|
16
|
+
appliedCommit(entry) {
|
|
17
|
+
this.#appliedCommits.push(entry);
|
|
18
|
+
}
|
|
15
19
|
/** Mark a whole table dirty, discarding any weaker scope-only facts. */
|
|
16
20
|
table(name) {
|
|
17
21
|
this.#tables.set(name, { tableWide: true, scopeKeys: undefined });
|
|
@@ -113,6 +117,9 @@ export class ChangeAccumulator {
|
|
|
113
117
|
conflictsChanged: this.#conflicts,
|
|
114
118
|
rejectionsChanged: this.#rejections,
|
|
115
119
|
outcomesChanged: this.#outcomes,
|
|
120
|
+
...(this.#appliedCommits.length > 0
|
|
121
|
+
? { appliedCommits: this.#appliedCommits }
|
|
122
|
+
: {}),
|
|
116
123
|
};
|
|
117
124
|
}
|
|
118
125
|
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Worker-side bootstrap: constructs the WHOLE
|
|
3
|
+
* client core — SyncClient + transports + realtime + SQLite — inside the
|
|
4
|
+
* worker and serves the `worker-protocol` RPC over postMessage.
|
|
5
|
+
*
|
|
6
|
+
* Browsers get the defaults: opfs-sahpool persistence and the fetch/WS
|
|
7
|
+
* transports from `./http`, wired from `WorkerInitConfig.endpoints`.
|
|
8
|
+
* Tests inject a database factory (bun:sqlite) through `overrides` — the
|
|
9
|
+
* same bootstrap, the same RPC, a different SQLite.
|
|
10
|
+
*
|
|
11
|
+
* The §8.4 host loop lives HERE: wake-ups (hello/`sync` events, delta
|
|
12
|
+
* drops) coalesce into one intent-driven `syncUntilIdle` round in the worker;
|
|
13
|
+
* RPC-driven and auto-driven sync rounds serialize on one queue because
|
|
14
|
+
* the core owns exactly one loop.
|
|
15
|
+
*/
|
|
16
|
+
import type { defineAuthorityReads } from './authority.js';
|
|
17
|
+
import { SyncClient } from './client.js';
|
|
18
|
+
import type { ClientDatabase } from './database.js';
|
|
19
|
+
import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
|
|
20
|
+
import type { ClientSchema } from './schema.js';
|
|
21
|
+
import { type LocalAuthorityState, type WorkerApi, type WorkerInitConfig } from './worker-protocol.js';
|
|
22
|
+
export interface SyncWorkerOverrides {
|
|
23
|
+
/** Explicit authority reader factory. Required when init declares authorityReads. */
|
|
24
|
+
readonly createAuthorityReads?: typeof defineAuthorityReads;
|
|
25
|
+
/** Database factory indirection: tests inject bun:sqlite here. */
|
|
26
|
+
readonly openDatabase?: (config: WorkerInitConfig) => Promise<ClientDatabase> | ClientDatabase;
|
|
27
|
+
/** Retry deadline indirection for deterministic worker-host tests. */
|
|
28
|
+
readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
|
|
29
|
+
readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
|
|
30
|
+
readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Custom realtime connector, e.g. one that mints a fresh ticket per
|
|
33
|
+
* connection attempt. `headers` reads the current host auth set.
|
|
34
|
+
*/
|
|
35
|
+
readonly createRealtime?: (config: WorkerInitConfig, clientId: string, headers: () => Readonly<Record<string, string>>) => RealtimeConnector | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* SPEC §12 local authority, required by init's `localAuthority: true`:
|
|
38
|
+
* `(database, schema) => openLocalAuthority({ database:
|
|
39
|
+
* clientSqliteDatabase(database), schema })` from `@syncular/server`. Only
|
|
40
|
+
* a worker entry that passes it bundles the server code.
|
|
41
|
+
*/
|
|
42
|
+
readonly openLocalAuthority?: (database: ClientDatabase, schema: ClientSchema) => Promise<WorkerLocalAuthority>;
|
|
43
|
+
}
|
|
44
|
+
/** The `LocalAuthority` surface of `@syncular/server` the worker drives (§12). */
|
|
45
|
+
export interface WorkerLocalAuthority {
|
|
46
|
+
readonly state: LocalAuthorityState;
|
|
47
|
+
readonly sync: SyncTransport;
|
|
48
|
+
readonly downloadSegment: SegmentDownloader;
|
|
49
|
+
readonly attach: (transport: SyncTransport) => Promise<void>;
|
|
50
|
+
readonly abandonAttach: (transport?: SyncTransport) => Promise<void>;
|
|
51
|
+
}
|
|
52
|
+
type LocalAuthorityMethod = 'localAuthorityState' | 'attachLocalAuthority' | 'abandonLocalAuthorityAttach';
|
|
53
|
+
/** @internal Optional §12 behavior supplied by the authority-enabled entry. */
|
|
54
|
+
interface WorkerLocalAuthorityExtension {
|
|
55
|
+
readonly methods: Pick<WorkerApi, LocalAuthorityMethod>;
|
|
56
|
+
open(config: WorkerInitConfig, database: ClientDatabase, remote: SyncTransport, segments: SegmentDownloader | undefined): Promise<{
|
|
57
|
+
readonly transport: SyncTransport;
|
|
58
|
+
readonly segments: SegmentDownloader | undefined;
|
|
59
|
+
}>;
|
|
60
|
+
active(): boolean;
|
|
61
|
+
close(): void;
|
|
62
|
+
}
|
|
63
|
+
/** @internal Dependencies shared with the worker's single sync loop. */
|
|
64
|
+
export type WorkerLocalAuthorityFactory = (context: {
|
|
65
|
+
readonly overrides: SyncWorkerOverrides;
|
|
66
|
+
readonly requireClient: () => SyncClient;
|
|
67
|
+
readonly serializedSync: <T>(run: () => Promise<T>) => Promise<T>;
|
|
68
|
+
readonly isOffline: () => boolean;
|
|
69
|
+
readonly wake: () => void;
|
|
70
|
+
}) => WorkerLocalAuthorityExtension;
|
|
71
|
+
/**
|
|
72
|
+
* Register the RPC server on the current worker scope. Call this once
|
|
73
|
+
* from a worker entry script; the main-thread handle drives everything
|
|
74
|
+
* else through `init`/`call` messages.
|
|
75
|
+
*/
|
|
76
|
+
export declare function startSyncWorkerCore(overrides: SyncWorkerOverrides, createLocalAuthority?: WorkerLocalAuthorityFactory): void;
|
|
77
|
+
export {};
|