@syncular/client 0.1.3 → 0.2.0

package/dist/worker-host.js

@@ -0,0 +1,536 @@
+import { ClientSyncError } from './errors.js';
+import { InvalidationEmitter } from './invalidation.js';
+import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
+import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
+import { NOT_LEADER_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
+function defaultLeaderLock() {
+    const nav = globalThis.navigator;
+    return nav?.locks !== undefined
+        ? webLocksLeaderLock(nav.locks)
+        : singleOwnerLock();
+}
+/**
+ * The main-thread proxy: the same logical API as `SyncClient`, every method a
+ * promise. `role` is `'leader'` (owns the worker) or `'follower'` (proxies to
+ * the leader over the channel). Constructed via {@link createSyncClientHandle}.
+ */
+export class SyncClientHandle {
+    /** True only for a leader handle. Kept for the pre-multiTab contract. */
+    get isLeader() {
+        return this.#role === 'leader';
+    }
+    get role() {
+        return this.#role;
+    }
+    /** Resolved client id — the leader's; shared by all tabs on this origin. */
+    get clientId() {
+        return this.#clientId;
+    }
+    #role;
+    #clientId;
+    #core;
+    #follower;
+    #invalidation;
+    #presence;
+    #roleListeners;
+    #closed = false;
+    /** @internal — use {@link createSyncClientHandle}. */
+    constructor(internals) {
+        this.#role = internals.role;
+        this.#clientId = internals.clientId;
+        this.#core = internals.core;
+        this.#follower = internals.follower;
+        this.#invalidation = internals.invalidation;
+        this.#presence = internals.presence;
+        this.#roleListeners = internals.roleListeners ?? new Set();
+    }
+    /** @internal — swap this handle from follower to leader (promotion). */
+    __becomeLeader(core) {
+        this.#follower?.close();
+        this.#follower = undefined;
+        this.#core = core;
+        this.#clientId = core.clientId;
+        this.#role = 'leader';
+        for (const listener of this.#roleListeners) {
+            try {
+                listener('leader');
+            }
+            catch {
+                /* a UI listener must never break promotion */
+            }
+        }
+    }
+    /** @internal — dispatch a worker/relayed event to handle-local listeners. */
+    __dispatchEvent(event) {
+        if (event.kind === 'presence') {
+            for (const listener of this.#presence) {
+                try {
+                    listener(event.scopeKey);
+                }
+                catch {
+                    /* a UI listener must never break event dispatch */
+                }
+            }
+        }
+        else if (event.kind === 'invalidate') {
+            this.#invalidation.emit(event.event);
+        }
+    }
+    /**
+     * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
+     * surface as `SyncClient.onInvalidate`, so React bindings target one
+     * interface across direct, worker-leader, and follower modes. Returns an
+     * unsubscribe function.
+     */
+    onInvalidate(listener) {
+        return this.#invalidation.on(listener);
+    }
+    /**
+     * §8.6: subscribe to presence changes — the identical surface as
+     * `SyncClient.onPresence`. Returns an unsubscribe function.
+     */
+    onPresence(listener) {
+        this.#presence.add(listener);
+        return () => {
+            this.#presence.delete(listener);
+        };
+    }
+    /** Subscribe to role transitions (follower → leader on promotion). */
+    onRoleChange(listener) {
+        this.#roleListeners.add(listener);
+        return () => {
+            this.#roleListeners.delete(listener);
+        };
+    }
+    #call(method, args) {
+        if (this.#closed) {
+            return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
+        }
+        if (this.#role === 'follower') {
+            if (this.#follower === undefined) {
+                return Promise.reject(new ClientSyncError(NOT_LEADER_CODE, 'this tab is not the leader — another tab owns the syncular ' +
+                    'core for this origin (enable multiTab for follower proxying)'));
+            }
+            return this.#follower.call(method, args);
+        }
+        if (this.#core === undefined) {
+            return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
+        }
+        return this.#core.invoke(method, args);
+    }
+    subscribe(input) {
+        return this.#call('subscribe', [input]);
+    }
+    unsubscribe(id) {
+        return this.#call('unsubscribe', [id]);
+    }
+    setWindow(base, units) {
+        return this.#call('setWindow', [base, units]);
+    }
+    windowState(base) {
+        return this.#call('windowState', [base]);
+    }
+    mutate(mutations) {
+        return this.#call('mutate', [mutations]);
+    }
+    sync() {
+        return this.#call('sync', []);
+    }
+    syncUntilIdle(maxRounds) {
+        return this.#call('syncUntilIdle', [maxRounds]);
+    }
+    query(sql, params) {
+        return this.#call('query', [sql, params]);
+    }
+    conflicts() {
+        return this.#call('conflicts', []);
+    }
+    rejections() {
+        return this.#call('rejections', []);
+    }
+    schemaFloor() {
+        return this.#call('schemaFloor', []);
+    }
+    leaseState() {
+        return this.#call('leaseState', []);
+    }
+    /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
+    upgrading() {
+        return this.#call('upgrading', []);
+    }
+    syncNeeded() {
+        return this.#call('syncNeeded', []);
+    }
+    pendingCommits() {
+        return this.#call('pendingCommits', []);
+    }
+    subscriptions() {
+        return this.#call('subscriptions', []);
+    }
+    subscription(id) {
+        return this.#call('subscription', [id]);
+    }
+    connectRealtime() {
+        return this.#call('connectRealtime', []);
+    }
+    disconnectRealtime() {
+        return this.#call('disconnectRealtime', []);
+    }
+    /** §8.6: publish/clear a scope-keyed presence document. */
+    setPresence(scopeKey, doc) {
+        return this.#call('setPresence', [scopeKey, doc]);
+    }
+    /** §8.6: the peers currently present on a scope key. */
+    presence(scopeKey) {
+        return this.#call('presence', [scopeKey]);
+    }
+    uploadBlob(bytes, options) {
+        return this.#call('uploadBlob', [bytes, options]);
+    }
+    fetchBlob(blobIdOrRef) {
+        return this.#call('fetchBlob', [blobIdOrRef]);
+    }
+    /** Sever/restore transport + realtime inside the worker (demos). */
+    setOffline(offline) {
+        return this.#call('setOffline', [offline]);
+    }
+    /** Close the core (leader) or unbind the link (follower), release leadership. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        if (this.#follower !== undefined) {
+            this.#follower.close();
+            this.#follower = undefined;
+        }
+        if (this.#core !== undefined) {
+            const core = this.#core;
+            this.#core = undefined;
+            await core.close(true);
+        }
+    }
+}
+/**
+ * Spawn the worker, run the init handshake, and return a running leader core.
+ * `dispatchEvent` receives every worker event; `bridge` (when supplied) is
+ * the follower relay whose lifetime is tied to this core.
+ */
+async function startWorkerCore(options) {
+    const { config, initConfig, lease } = options;
+    const worker = config.worker();
+    const pending = new Map();
+    const nextId = { value: 1 };
+    const invoke = (method, args) => {
+        const id = nextId.value++;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+            worker.postMessage({
+                t: 'call',
+                id,
+                method,
+                args,
+            });
+        });
+    };
+    let bridge;
+    const ready = new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            const message = event.data;
+            switch (message.t) {
+                case 'ready':
+                    resolve();
+                    break;
+                case 'result': {
+                    const entry = pending.get(message.id);
+                    pending.delete(message.id);
+                    entry?.resolve(message.value);
+                    break;
+                }
+                case 'error': {
+                    const entry = pending.get(message.id);
+                    pending.delete(message.id);
+                    entry?.reject(new ClientSyncError(message.error.code, message.error.message, message.error.retryable));
+                    break;
+                }
+                case 'event':
+                    options.dispatchEvent(message.event);
+                    bridge?.broadcastEvent(message.event);
+                    break;
+            }
+        };
+        const onError = (event) => {
+            const error = new ClientSyncError(WORKER_FAILED_CODE, `the sync worker failed: ${event.message ?? 'unknown error'}`);
+            reject(error);
+            for (const entry of pending.values())
+                entry.reject(error);
+            pending.clear();
+        };
+        worker.addEventListener('message', onMessage);
+        worker.addEventListener('error', onError);
+    });
+    try {
+        await ready;
+        const initResult = await new Promise((resolve, reject) => {
+            const id = nextId.value++;
+            pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+            });
+            worker.postMessage({
+                t: 'init',
+                id,
+                config: initConfig,
+            });
+        });
+        if (options.makeBridge !== undefined) {
+            bridge = options.makeBridge(initResult.clientId, invoke);
+        }
+        return {
+            clientId: initResult.clientId,
+            invoke,
+            bridge,
+            lease,
+            close: async (terminate) => {
+                bridge?.close();
+                try {
+                    await invoke('close', []);
+                }
+                catch {
+                    // Closing a wedged worker still terminates it below.
+                }
+                if (terminate)
+                    worker.terminate();
+                const closedError = new ClientSyncError(WORKER_FAILED_CODE, 'the handle was closed');
+                for (const entry of pending.values())
+                    entry.reject(closedError);
+                pending.clear();
+                await lease.release();
+            },
+        };
+    }
+    catch (error) {
+        worker.terminate();
+        await lease.release();
+        throw error;
+    }
+}
+function buildInitConfig(config) {
+    return {
+        schema: config.schema,
+        database: config.database,
+        endpoints: config.endpoints,
+        ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
+        ...(config.limits !== undefined ? { limits: config.limits } : {}),
+        ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
+        ...(config.wakeJitterMs !== undefined
+            ? { wakeJitterMs: config.wakeJitterMs }
+            : {}),
+    };
+}
+/** Route a worker event to the config-level callbacks (leader visibility). */
+function fireConfigCallbacks(config, event) {
+    if (event.kind === 'sync-needed') {
+        config.onSyncNeeded?.(event.reason);
+    }
+    else if (event.kind === 'conflict') {
+        config.onConflict?.(event.conflict);
+    }
+    else if (event.kind === 'upgrading') {
+        config.onUpgrading?.(event.upgrading);
+    }
+    else if (event.kind === 'presence') {
+        config.onPresence?.(event.scopeKey);
+    }
+    else if (event.kind === 'synced') {
+        config.onSynced?.({
+            ...(event.summary !== undefined ? { summary: event.summary } : {}),
+            ...(event.error !== undefined ? { error: event.error } : {}),
+        });
+    }
+}
+/**
+ * Acquire leadership, spawn the worker, initialize the core inside it.
+ *
+ * With `multiTab` off: a losing tab resolves to a dead not-leader handle.
+ * With `multiTab` on: a losing tab becomes a FOLLOWER proxying to the leader,
+ * and promotes itself if the leader later closes.
+ */
+export async function createSyncClientHandle(config) {
+    const lock = config.leaderLock ?? defaultLeaderLock();
+    const lockName = config.lockName ?? 'syncular-leader';
+    const invalidation = new InvalidationEmitter();
+    const presence = new Set();
+    const roleListeners = new Set();
+    if (config.onRoleChange !== undefined)
+        roleListeners.add(config.onRoleChange);
+    // Leadership BEFORE the worker exists: one core per origin, and a losing
+    // tab never boots a database it must not own.
+    const lease = lock.tryAcquire !== undefined
+        ? await lock.tryAcquire(lockName)
+        : await lock.acquire(lockName);
+    // ---- Won the election: leader. ----
+    if (lease !== undefined) {
+        // Epoch derivation for a fresh boot: epoch 0. A promoter (below) reads
+        // the highest epoch it has seen and adds one, so leaders monotonically
+        // increase it across handovers.
+        return await bootLeader(config, lockName, lease, {
+            epoch: 0,
+            invalidation,
+            presence,
+            roleListeners,
+        });
+    }
+    // ---- Lost the election. ----
+    if (config.multiTab !== true) {
+        // Legacy single-tab contract: a dead not-leader handle.
+        return new SyncClientHandle({
+            role: 'follower',
+            clientId: '',
+            invalidation,
+            presence,
+            roleListeners,
+        });
+    }
+    // ---- Follower: proxy to the leader; contest + promote on its close. ----
+    return await bootFollower(config, lockName, lock, {
+        invalidation,
+        presence,
+        roleListeners,
+    });
+}
+/** Boot (or promote to) a leader: spawn the worker, wire the bridge. */
+async function bootLeader(config, lockName, lease, parts) {
+    const handleRef = {
+        handle: undefined,
+    };
+    const dispatchEvent = (event) => {
+        fireConfigCallbacks(config, event);
+        handleRef.handle?.__dispatchEvent(event);
+    };
+    const makeBridge = config.multiTab === true
+        ? (clientId, invoke) => {
+            const factory = config.channelFactory ?? broadcastChannelFactory();
+            const channel = factory(multiTabChannelName(lockName));
+            return new LeaderBridge({
+                channel,
+                epoch: parts.epoch ?? 0,
+                clientId,
+                invoke,
+            });
+        }
+        : undefined;
+    const core = await startWorkerCore({
+        config,
+        initConfig: buildInitConfig(config),
+        lease,
+        dispatchEvent,
+        ...(makeBridge !== undefined ? { makeBridge } : {}),
+    });
+    const handle = new SyncClientHandle({
+        role: 'leader',
+        clientId: core.clientId,
+        core,
+        invalidation: parts.invalidation,
+        presence: parts.presence,
+        roleListeners: parts.roleListeners,
+    });
+    handleRef.handle = handle;
+    return handle;
+}
+/**
+ * Boot a follower: open the channel, bind to the leader, and race the lock in
+ * the background so this tab promotes itself the instant the leader closes.
+ */
+async function bootFollower(config, lockName, lock, parts) {
+    const factory = config.channelFactory ?? broadcastChannelFactory();
+    const channel = factory(multiTabChannelName(lockName));
+    const handleRef = {
+        handle: undefined,
+    };
+    const follower = new FollowerLink({
+        channel,
+        fromId: newTabId(),
+        onEvent: (event) => handleRef.handle?.__dispatchEvent(event),
+        onLeaderChange: (clientId) => {
+            // Learn the leader's shared client id (best-effort; the handle exposes
+            // it after binding). Nothing else to do — calls already flush.
+            void clientId;
+        },
+        ...(config.followerCallTimeoutMs !== undefined
+            ? { callTimeoutMs: config.followerCallTimeoutMs }
+            : {}),
+    });
+    // A follower waits (blocking) on the exclusive lock: it resolves ONLY when
+    // the current leader releases it (tab close). Winning it triggers promotion.
+    // We do NOT hold this promise — it settles asynchronously.
+    void lock.acquire(lockName).then(async (lease) => {
+        const handle = handleRef.handle;
+        if (handle === undefined) {
+            // Handle was never assembled (shouldn't happen); drop the lease.
+            await lease.release();
+            return;
+        }
+        // The follower saw the departing leader's epoch; the new leader must
+        // strictly exceed it so stale replies/events are discarded everywhere.
+        const nextEpoch = follower.maxEpochSeen + 1;
+        // Unbind the link so any late leader traffic is ignored, then promote.
+        follower.unbind();
+        try {
+            const core = await startWorkerCore({
+                config,
+                initConfig: buildInitConfig(config),
+                lease,
+                dispatchEvent: (event) => {
+                    fireConfigCallbacks(config, event);
+                    handle.__dispatchEvent(event);
+                },
+                ...(config.multiTab === true
+                    ? {
+                        makeBridge: (clientId, invoke) => {
+                            const promoteChannel = factory(multiTabChannelName(lockName));
+                            return new LeaderBridge({
+                                channel: promoteChannel,
+                                epoch: nextEpoch,
+                                clientId,
+                                invoke,
+                            });
+                        },
+                    }
+                    : {}),
+            });
+            handle.__becomeLeader(core);
+        }
+        catch {
+            // Promotion failed to spawn a worker — release so the next tab tries.
+            await lease.release();
+        }
+    });
+    const handle = new SyncClientHandle({
+        role: 'follower',
+        // The follower learns the leader's shared client id once bound; expose it
+        // lazily via `clientId` is not possible on a getter over the link, so we
+        // leave '' until promotion (the shared id is the leader's — hooks that
+        // need it read it after a round). Followers rarely need clientId directly.
+        clientId: '',
+        follower,
+        invalidation: parts.invalidation,
+        presence: parts.presence,
+        roleListeners: parts.roleListeners,
+    });
+    handleRef.handle = handle;
+    // Do not hand back a follower until its link has bound to the leader (the
+    // hello→announce round trip completed). Before binding, epoch is -1 and any
+    // event the leader fans out is dropped, so a caller that subscribes and then
+    // relies on push invalidation would silently miss events emitted in the
+    // binding window — a real multi-tab race, not just a test flake. Binding is
+    // fast (the leader answers every hello with an announce); on the off chance
+    // it times out we still return the handle (queued calls flush and events
+    // resume on the next announce) rather than failing handle construction.
+    try {
+        await follower.waitUntilBound();
+    }
+    catch {
+        /* bind timed out — return the (degraded but functional) handle anyway */
+    }
+    return handle;
+}