@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 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. Distinct from
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
- this.#syncing = true;
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
- if (this.#syncing) {
3658
- // Fast path: a pull is mid-flight; let it win and recover the gap
3659
- // itself — re-pulling is idempotent, interleaved application is not
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 && !section.skip) {
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;
@@ -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. */
@@ -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 {};