@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/hub/hub-like.js

@@ -0,0 +1,535 @@
+import { fromB64, toB64 } from '@sozai/codec';
+import { EventEmitter } from '@sozai/event';
+import { AckBatch, abortableSleep, computeBackoff } from './ack-backoff.js';
+const DEFAULT_ACK_FLUSH_MS = 500;
+const DEFAULT_ACK_FLUSH_MAX = 10;
+const DEFAULT_BACKOFF_BASE_MS = 1000;
+const DEFAULT_BACKOFF_MAX_MS = 60000;
+const DEFAULT_BACKOFF_JITTER = 0.25;
+const DISPOSED_SENTINEL = Symbol('disposed');
+/**
+ * One independent receive subscriber. The underlying single hub/receive drain
+ * fans every decoded message to every active sink; each sink buffers in its own
+ * queue and parks a single waiter when drained. Sinks are long-lived across
+ * reconnects — only the draining channel is swapped, never the sinks.
+ *
+ * A sink does NOT filter by topic: topic demux is the mux's job. A message for a
+ * topic the sink's mux has no listener for is simply never pulled/acked here.
+ */ class ReceiveSink {
+    #queue = [];
+    #waiter = null;
+    #stopped = false;
+    push(message) {
+        if (this.#stopped) {
+            return;
+        }
+        const waiter = this.#waiter;
+        if (waiter != null) {
+            this.#waiter = null;
+            waiter({
+                value: message,
+                done: false
+            });
+            return;
+        }
+        this.#queue.push(message);
+    }
+    next() {
+        if (this.#queue.length > 0) {
+            const value = this.#queue.shift();
+            return Promise.resolve({
+                value,
+                done: false
+            });
+        }
+        if (this.#stopped) {
+            return Promise.resolve({
+                value: undefined,
+                done: true
+            });
+        }
+        return new Promise((resolve)=>{
+            this.#waiter = resolve;
+        });
+    }
+    // Ends this sink only. Resolves a parked waiter as done and drops any buffer;
+    // the shared drain + connection keep running for the remaining sinks.
+    stop() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#queue = [];
+        const waiter = this.#waiter;
+        if (waiter != null) {
+            this.#waiter = null;
+            waiter({
+                value: undefined,
+                done: true
+            });
+        }
+    }
+}
+/**
+ * A single reconnecting `HubLike` over one `Client<HubProtocol>`, one per
+ * (deviceDID, hubURL). It does NOT demultiplex topics or hold per-group
+ * mutexes — group-rpc's `createHubMux` already fans the single `hub.receive`
+ * drain across topics and refcounts subscribe/unsubscribe on top of this view.
+ *
+ * Connection is established lazily on the first `publish` / `subscribe` /
+ * `receive`. A mux calls `receive(localDID)` once at construction and
+ * `subscribe(localDID, topicID)` as topics are retained, so the first of those
+ * brings the client + `hub/receive` channel up.
+ *
+ * `receive()` may be called more than once: one device runs one GroupPeer per
+ * group plus directed sync transports, and the hub delivers each message to a
+ * DID exactly once, so there must be exactly one underlying `hub/receive` drain
+ * per device DID, demultiplexed client-side by topic. Each `receive()` returns
+ * its own independent subscription (sink); the single drain fans every decoded
+ * message to every active sink. Sinks are long-lived across reconnects while
+ * only the underlying channel is swapped, so every iterable keeps yielding
+ * through transport drops. Acks are deduped so the hub is acked at most once per
+ * sequenceID regardless of how many sinks ack it.
+ */ class HubLikeAdapter {
+    #createClient;
+    #localDID;
+    #logger;
+    #ackFlushMs;
+    #ackFlushMax;
+    #backoffBaseMs;
+    #backoffMaxMs;
+    #backoffJitter;
+    #client = null;
+    #channel = null;
+    #ackBatch = null;
+    #receiveTask = null;
+    #controller = new AbortController();
+    #activeTopics = new Set();
+    #reconnectAttempt = 0;
+    // Non-null while a reconnect is in flight. publish/subscribe/unsubscribe wait
+    // on it so they bind to the fresh client rather than racing the swap.
+    #reconnectGate = null;
+    #opened = false;
+    #openPromise = null;
+    #disposed = false;
+    #events = new EventEmitter();
+    // Fan-out receive: one underlying hub/receive drain feeds N independent
+    // subscriber sinks (group-peer muxes + sync transports share one device DID
+    // drain). Each sink owns its queue + waiter; sinks survive reconnects, only
+    // the draining channel is replaced.
+    #sinks = new Set();
+    // Ack dedupe: ack the hub at most once per sequenceID across all sinks. Holds
+    // sequenceIDs fed to the current AckBatch but not yet flushed; pruned when the
+    // batch flushes (see the send wrapper in #openInner) and cleared whenever the
+    // AckBatch is reset on reconnect/dispose so redelivered messages can re-ack.
+    // Bounded by the in-flight (unflushed) ack count.
+    #ackedPending = new Set();
+    constructor(params){
+        this.#createClient = params.createClient;
+        this.#localDID = params.localDID;
+        this.#logger = params.logger;
+        this.#ackFlushMs = params.ackFlushMs ?? DEFAULT_ACK_FLUSH_MS;
+        this.#ackFlushMax = params.ackFlushMax ?? DEFAULT_ACK_FLUSH_MAX;
+        this.#backoffBaseMs = params.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+        this.#backoffMaxMs = params.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS;
+        this.#backoffJitter = params.backoffJitter ?? DEFAULT_BACKOFF_JITTER;
+    }
+    // --- lifecycle events ---
+    events = {
+        subscribe: (listener)=>{
+            return this.#events.on('lifecycle', listener);
+        }
+    };
+    // Subscriber rejections must never break the state machine: emit awaits all
+    // listeners and swallows (logs) any that throw, mirroring the older
+    // hub-connection lifecycle dispatch.
+    async #emit(event) {
+        try {
+            await this.#events.emit('lifecycle', event);
+        } catch (error) {
+            this.#logger?.warn('hub-like lifecycle subscriber threw', {
+                type: event.type,
+                error
+            });
+        }
+    }
+    // --- connection setup ---
+    #ensureOpen() {
+        if (this.#opened) {
+            return Promise.resolve();
+        }
+        if (this.#openPromise != null) {
+            return this.#openPromise;
+        }
+        const promise = this.#openInner().then(async ()=>{
+            this.#opened = true;
+            await this.#emit({
+                type: 'connected'
+            });
+        }).catch((error)=>{
+            // Allow a later call to retry the first connect.
+            this.#openPromise = null;
+            throw error;
+        });
+        this.#openPromise = promise;
+        return promise;
+    }
+    async #openInner() {
+        // On the reconnect path dispose the prior client so its transport is freed
+        // before a fresh one is acquired. dispose is idempotent.
+        const previous = this.#client;
+        this.#client = null;
+        if (previous != null) {
+            try {
+                await previous.dispose();
+            } catch (error) {
+                this.#logger?.debug('hub-like previous client dispose failed', {
+                    error
+                });
+            }
+        }
+        const client = await this.#createClient();
+        this.#client = client;
+        const channel = client.createChannel('hub/receive', {
+            param: {},
+            signal: this.#controller.signal
+        });
+        this.#channel = channel;
+        // The channel call is a promise; swallow its rejection so an aborted /
+        // dropped channel never surfaces as an unhandled rejection.
+        void channel.catch(()=>{});
+        // A fresh AckBatch means the prior batch's pending acks (if any) were
+        // dropped without flushing; clear the dedupe set so the hub's redelivered
+        // messages can be acked again on this connection.
+        this.#ackedPending.clear();
+        this.#ackBatch = new AckBatch({
+            flushMs: this.#ackFlushMs,
+            flushMax: this.#ackFlushMax,
+            send: async (ids)=>{
+                try {
+                    await channel.send({
+                        ack: ids
+                    });
+                } finally{
+                    // Forget flushed sequenceIDs so the dedupe set stays bounded; a future
+                    // redelivery (after reconnect) is then free to ack again.
+                    for (const id of ids){
+                        this.#ackedPending.delete(id);
+                    }
+                }
+            },
+            logger: this.#logger
+        });
+        this.#receiveTask = this.#runReceiveLoop(client, channel).catch((error)=>{
+            this.#logger?.debug('hub-like receive task tail error', {
+                error
+            });
+        });
+        // Re-issue hub/subscribe for every active topic. Empty on the first open;
+        // on reconnect it re-registers the device's topics with the fresh client.
+        const topics = [
+            ...this.#activeTopics
+        ];
+        if (topics.length > 0) {
+            const results = await Promise.allSettled(topics.map((topicID)=>client.request('hub/subscribe', {
+                    param: {
+                        topicID
+                    }
+                })));
+            for(let i = 0; i < results.length; i++){
+                const result = results[i];
+                if (result.status === 'rejected') {
+                    // Keep the topic registered: the next reconnect retries it.
+                    this.#logger?.warn('hub-like re-subscribe failed', {
+                        topicID: topics[i],
+                        error: result.reason
+                    });
+                }
+            }
+        }
+    }
+    async #runReceiveLoop(client, channel) {
+        const reader = channel.readable.getReader();
+        let caughtError = null;
+        try {
+            while(!this.#controller.signal.aborted){
+                const readPromise = reader.read();
+                const disposedPromise = client.disposed.then(()=>DISPOSED_SENTINEL);
+                const raceResult = await Promise.race([
+                    readPromise,
+                    disposedPromise
+                ]);
+                if (typeof raceResult === 'symbol') {
+                    break;
+                }
+                const { done, value } = raceResult;
+                if (done) {
+                    break;
+                }
+                this.#pushMessage({
+                    sequenceID: value.sequenceID,
+                    senderDID: value.senderDID,
+                    topicID: value.topicID,
+                    payload: fromB64(value.payload)
+                });
+                // A successful read indicates a healthy connection.
+                this.#reconnectAttempt = 0;
+            }
+        } catch (error) {
+            caughtError = error;
+            this.#logger?.warn('hub-like receive loop error', {
+                error
+            });
+        } finally{
+            try {
+                reader.releaseLock();
+            } catch  {
+            // ignore
+            }
+        }
+        if (!this.#controller.signal.aborted && !this.#disposed) {
+            const reason = caughtError instanceof Error && caughtError.message ? caughtError.message : 'receive loop ended';
+            this.#logger?.debug('hub-like receive loop ended, scheduling reconnect', {
+                reason
+            });
+            // Order is load-bearing: subscribers observe `disconnected` before the
+            // reconnect loop's first `reconnecting`. `#emit` awaits subscribers, then
+            // `#scheduleReconnect` runs the loop whose first action is a backoff
+            // sleep, so there is no observable interleaving.
+            await this.#emit({
+                type: 'disconnected'
+            });
+            this.#scheduleReconnect();
+        }
+    }
+    #scheduleReconnect() {
+        this.#receiveTask = this.#reconnectLoop().catch((error)=>{
+            this.#logger?.debug('hub-like reconnect task tail error', {
+                error
+            });
+        });
+    }
+    async #reconnectLoop() {
+        let resolveGate = ()=>{};
+        this.#reconnectGate = new Promise((resolve)=>{
+            resolveGate = resolve;
+        });
+        try {
+            while(!this.#controller.signal.aborted && !this.#disposed){
+                const delay = computeBackoff(this.#reconnectAttempt++, this.#backoffBaseMs, this.#backoffMaxMs, this.#backoffJitter);
+                try {
+                    await abortableSleep(delay, this.#controller.signal);
+                } catch  {
+                    return;
+                }
+                if (this.#disposed) {
+                    return;
+                }
+                await this.#emit({
+                    type: 'reconnecting'
+                });
+                try {
+                    this.#ackBatch?.dispose();
+                    this.#ackBatch = null;
+                    this.#channel = null;
+                    await this.#openInner();
+                    this.#reconnectAttempt = 0;
+                    // Emit before resolving the gate so awaiters observe `connected`
+                    // before their queued publish/subscribe resumes.
+                    await this.#emit({
+                        type: 'connected'
+                    });
+                    return;
+                } catch (error) {
+                    this.#logger?.warn('hub-like reconnect attempt failed', {
+                        attempt: this.#reconnectAttempt,
+                        error
+                    });
+                }
+            }
+        } finally{
+            this.#reconnectGate = null;
+            resolveGate();
+        }
+    }
+    async #ready() {
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        await this.#ensureOpen();
+        // Wait out any in-flight reconnect so the operation binds to the fresh
+        // client. A new reconnect may begin after this resolves; loop until clear.
+        while(this.#reconnectGate != null){
+            await this.#reconnectGate;
+        }
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        const client = this.#client;
+        if (client == null) {
+            throw new Error('hub-like adapter not connected');
+        }
+        return client;
+    }
+    // --- HubLike surface ---
+    publish = async ({ senderDID, topicID, payload })=>{
+        if (senderDID !== this.#localDID) {
+            // The hub derives the sender from the signed `iss`; a mismatch here means
+            // a caller stamped the wrong DID. The publish still uses this device's
+            // identity, so surface it as a warning rather than a hard failure.
+            this.#logger?.warn('hub-like publish senderDID does not match localDID', {
+                senderDID,
+                localDID: this.#localDID
+            });
+        }
+        const client = await this.#ready();
+        const result = await client.request('hub/publish', {
+            param: {
+                topicID,
+                payload: toB64(payload)
+            }
+        });
+        return {
+            sequenceID: result.sequenceID
+        };
+    };
+    subscribe = async (_subscriberDID, topicID)=>{
+        const client = await this.#ready();
+        this.#activeTopics.add(topicID);
+        await client.request('hub/subscribe', {
+            param: {
+                topicID
+            }
+        });
+    };
+    unsubscribe = async (_subscriberDID, topicID)=>{
+        const client = await this.#ready();
+        this.#activeTopics.delete(topicID);
+        await client.request('hub/unsubscribe', {
+            param: {
+                topicID
+            }
+        });
+    };
+    receive = (_subscriberDID)=>{
+        if (this.#disposed) {
+            throw new Error('hub-like adapter disposed');
+        }
+        const sink = new ReceiveSink();
+        this.#sinks.add(sink);
+        // The first receive() brings the connection up so the drain has a channel to
+        // read from; later calls are idempotent. A late subscriber registers its
+        // sink before this resolves, so no in-flight message is lost to it. Failures
+        // surface through lifecycle events + retry.
+        void this.#ensureOpen().catch((error)=>{
+            this.#logger?.warn('hub-like open on receive failed', {
+                error
+            });
+        });
+        // Removing one sink ends only that subscription; the shared drain,
+        // connection and AckBatch persist while any other sink remains. Full
+        // teardown happens only via the adapter's dispose().
+        const removeSink = ()=>{
+            if (this.#sinks.delete(sink)) {
+                sink.stop();
+            }
+        };
+        const iterator = {
+            next: ()=>sink.next(),
+            return: ()=>{
+                removeSink();
+                return Promise.resolve({
+                    value: undefined,
+                    done: true
+                });
+            }
+        };
+        return {
+            [Symbol.asyncIterator]: ()=>iterator,
+            return: ()=>{
+                removeSink();
+            },
+            ack: (sequenceID)=>{
+                // Dedupe across all sinks: the first ack for a sequenceID feeds the
+                // shared AckBatch; repeats (same or another sink) are no-ops until the
+                // batch flushes and prunes it. If no batch is live (mid-reconnect), skip
+                // recording so a post-reconnect re-ack still reaches the hub.
+                if (this.#ackedPending.has(sequenceID)) {
+                    return;
+                }
+                const ackBatch = this.#ackBatch;
+                if (ackBatch == null) {
+                    return;
+                }
+                this.#ackedPending.add(sequenceID);
+                ackBatch.add(sequenceID);
+            }
+        };
+    };
+    // Fan the decoded message out to every active sink. Sinks whose mux has no
+    // listener for the topic simply never pull/ack it; that is expected and the
+    // hub redelivers such messages on reconnect.
+    #pushMessage(message) {
+        if (this.#disposed) {
+            return;
+        }
+        for (const sink of this.#sinks){
+            sink.push(message);
+        }
+    }
+    // --- disposal ---
+    dispose = async ()=>{
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#controller.abort();
+        // End every subscription: stop each sink (resolving parked waiters as done)
+        // and drop them. New receive() calls are rejected once disposed.
+        for (const sink of this.#sinks){
+            sink.stop();
+        }
+        this.#sinks.clear();
+        const ackBatch = this.#ackBatch;
+        this.#ackBatch = null;
+        if (ackBatch != null) {
+            try {
+                await ackBatch.flush();
+            } catch (error) {
+                this.#logger?.debug('hub-like ack flush during dispose failed', {
+                    error
+                });
+            }
+            ackBatch.dispose();
+        }
+        // Close the channel before awaiting the receive task so the reader unblocks.
+        try {
+            this.#channel?.close();
+        } catch  {
+        // ignore
+        }
+        try {
+            await this.#receiveTask;
+        } catch  {
+        // ignore
+        }
+        const client = this.#client;
+        this.#client = null;
+        if (client != null) {
+            try {
+                await client.dispose();
+            } catch (error) {
+                this.#logger?.debug('hub-like client dispose failed', {
+                    error
+                });
+            }
+        }
+        this.#channel = null;
+        this.#receiveTask = null;
+        this.#activeTopics.clear();
+        this.#ackedPending.clear();
+    };
+}
+export function createHubLike(params) {
+    return new HubLikeAdapter(params);
+}

package/lib/hub/manager.d.ts

@@ -65,16 +65,17 @@ export type UpsertHubParams = {
     serverDID?: string | null;
 };
 export declare class HubServerDIDConflictError extends Error {
-    readonly hubID: string;
-    readonly url: string;
-    readonly existingServerDID: string;
-    readonly providedServerDID: string;
+    #private;
     constructor(params: {
         hubID: string;
         url: string;
         existingServerDID: string;
         providedServerDID: string;
     });
+    get hubID(): string;
+    get url(): string;
+    get existingServerDID(): string;
+    get providedServerDID(): string;
 }
 export declare function createHub(params: CreateHubParams): Promise<Hub>;
 /**