@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/sync/tunnel-listeners.js

@@ -0,0 +1,175 @@
+import { normalizeDID } from '@kokuin/token';
+import { getP2PStore } from '@kubun/store-p2p';
+import { HubTunnelSyncListener } from './hub-tunnel-sync-listener.js';
+/**
+ * The answering half of the tunnel: one listener per co-member per group, so a
+ * device that dials `tunnel://<groupID>/<ourDID>` finds something draining the
+ * mailbox.
+ *
+ * Without this a route resolves, opens, publishes its first frame and idles out:
+ * "nobody is home" and "nobody is listening" are the same silence to the dialer.
+ *
+ * ONE PER PEER, not one per group: every listener on a device receives on the
+ * same inbox topic, and two sharing a raw drain destroy each other's frames.
+ * `HubTunnelSyncListener` fronts the hub with a per-peer view for exactly this,
+ * so peers are separated here rather than multiplexed inside a session.
+ *
+ * Gated on this device having declared a profile — the same invariant presence
+ * runs on. A device that never opted in is in nobody's projection, so nothing
+ * can dial it and a listener would hold a subscription open for a session that
+ * cannot arrive.
+ */ export function createTunnelListeners(params) {
+    const selfDID = normalizeDID(params.localDID);
+    const { logger } = params;
+    // groupID → peerDID → its listener.
+    const listeners = new Map();
+    // Which drain each group's listeners were built on. A listener holds its hub
+    // for life, so a group that switches hubs needs new ones — and the peer set
+    // alone cannot show that, since the same members are still wanted.
+    const attachedHubs = new Map();
+    // And which epoch they derived their topics at. A live listener's subscription
+    // is pinned to the epoch its spawn ran at, and only a disposed transport
+    // re-derives — so a group whose epoch moved keeps draining a topic nobody
+    // publishes to any more, while every dialer idles out against the silence. The
+    // peer set cannot show this either: the same members are still wanted.
+    const attachedEpochs = new Map();
+    // Reconciles of one group run in sequence: an epoch burst fires several, and
+    // two interleaved passes over the same map would each start a listener the
+    // other has not recorded yet.
+    const queues = new Map();
+    let disposed = false;
+    const stopGroup = async (groupID)=>{
+        attachedHubs.delete(groupID);
+        attachedEpochs.delete(groupID);
+        const group = listeners.get(groupID);
+        if (group == null) {
+            return;
+        }
+        listeners.delete(groupID);
+        await Promise.allSettled([
+            ...group.values()
+        ].map((listener)=>listener.stop()));
+    };
+    const runReconcile = async (groupID)=>{
+        if (disposed) {
+            return;
+        }
+        const store = await getP2PStore(params.stores);
+        const profile = await store.getLocalPeerProfile(selfDID);
+        if (profile == null) {
+            await stopGroup(groupID);
+            return;
+        }
+        const hub = params.tunnelHub(groupID);
+        if (hub == null) {
+            // No hub bound: there is no mailbox to drain. A binding arriving later
+            // reconciles again.
+            await stopGroup(groupID);
+            return;
+        }
+        const epoch = params.registry.groupEpoch(groupID);
+        if (attachedHubs.get(groupID) !== hub || attachedEpochs.get(groupID) !== epoch) {
+            await stopGroup(groupID);
+        }
+        attachedHubs.set(groupID, hub);
+        attachedEpochs.set(groupID, epoch);
+        const members = await store.listGroupMembers(groupID);
+        const wanted = new Set(members.map((member)=>normalizeDID(member.member_did)).filter((did)=>did !== selfDID));
+        let group = listeners.get(groupID);
+        if (group == null) {
+            group = new Map();
+            listeners.set(groupID, group);
+        }
+        for (const [peerDID, listener] of group){
+            if (!wanted.has(peerDID)) {
+                group.delete(peerDID);
+                try {
+                    await listener.stop();
+                } catch (error) {
+                    logger?.warn('tunnel listener stop failed', {
+                        groupID,
+                        peerDID,
+                        error
+                    });
+                }
+            }
+        }
+        // Every await above is a point where the group could have been left or the
+        // whole thing disposed. A pass that continued past one would repopulate
+        // `listeners` with fresh, STARTED listeners for a group this device is no
+        // longer in, and they would drain that group's inbox topic indefinitely —
+        // nothing later removes what `removeGroup` already walked past.
+        if (disposed || listeners.get(groupID) !== group) {
+            return;
+        }
+        for (const peerDID of wanted){
+            if (group.has(peerDID)) {
+                continue;
+            }
+            const listener = new HubTunnelSyncListener({
+                hub,
+                registry: params.registry,
+                groupID,
+                localDID: selfDID,
+                peerDID,
+                identity: params.identity,
+                syncHandlers: params.syncHandlers,
+                runtime: params.runtime,
+                ...params.idleTimeoutMs != null ? {
+                    idleTimeoutMs: params.idleTimeoutMs
+                } : {},
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+            group.set(peerDID, listener);
+            listener.start();
+        }
+    };
+    const reconcile = (groupID)=>{
+        const queued = (queues.get(groupID) ?? Promise.resolve()).then(()=>runReconcile(groupID), ()=>runReconcile(groupID));
+        // Never let one group's failure reject a caller that only asked for a
+        // reconcile — the next signal retries, and a throw here would surface on
+        // whichever unrelated lane happened to trigger it.
+        const settled = queued.catch((error)=>{
+            logger?.warn('tunnel listener reconcile failed', {
+                groupID,
+                error
+            });
+        });
+        queues.set(groupID, settled);
+        return settled;
+    };
+    return {
+        reconcile,
+        reconcileAll: async (groupIDs)=>{
+            await Promise.all(groupIDs.map((groupID)=>reconcile(groupID)));
+        },
+        removeGroup: async (groupID)=>{
+            // Await the in-flight reconcile BEFORE tearing down. Dropping the queue
+            // entry does not stop the pass already running: it would finish after the
+            // stop and leave started listeners behind for a group the device has
+            // left. `runReconcile` also re-checks, so this is the pair.
+            const queued = queues.get(groupID);
+            queues.delete(groupID);
+            if (queued != null) {
+                await queued.catch(()=>{
+                // A failed reconcile is already logged; the teardown proceeds.
+                });
+            }
+            await stopGroup(groupID);
+        },
+        dispose: async ()=>{
+            disposed = true;
+            const inFlight = [
+                ...queues.values()
+            ];
+            queues.clear();
+            await Promise.allSettled(inFlight);
+            const groupIDs = [
+                ...listeners.keys()
+            ];
+            await Promise.allSettled(groupIDs.map((groupID)=>stopGroup(groupID)));
+        }
+    };
+}

package/lib/sync/tunnel-observability.d.ts

@@ -0,0 +1,25 @@
+import type { Logger } from '@kubun/logger';
+import type { ObservabilityEventListener } from '@kumiai/hub-tunnel';
+/**
+ * Which side of a tunnel session a transport is. Carried on every line a
+ * session logs, because the two are indistinguishable otherwise: both receive
+ * on this device's inbox topic for the epoch, and a drop only means something
+ * once you know whether the reader was answering a peer or dialling one.
+ */
+export type TunnelSessionRole = 'dialer' | 'listener';
+/**
+ * Turn a tunnel transport's observability events into log lines, and pass them
+ * on to a listener the caller supplied.
+ *
+ * Until this existed the transports' `onEvent` port had no producer anywhere in
+ * the repo — declared, forwarded to the transport, and set by nobody. Every
+ * destroyed frame was therefore silent, in tests and on devices alike: a
+ * starved session showed up as an idle timeout half a minute later with nothing
+ * saying why. That is the entire reason a two-device sync failure had to be
+ * diagnosed by reading code rather than by reading a log.
+ *
+ * `logger` is expected to carry the session's context already (`groupID`,
+ * `peerDID`, `role`, `epoch`, topics), so a line needs no arguments beyond what
+ * the event itself adds.
+ */
+export declare function createTunnelEventLogger(logger: Logger, delegate?: ObservabilityEventListener): ObservabilityEventListener;

package/lib/sync/tunnel-observability.js

@@ -0,0 +1,63 @@
+/**
+ * Drops a healthy lane never produces, so each one is a frame that reached this
+ * device and was thrown away.
+ *
+ * - `decrypt` — the ciphertext did not open. On a lane whose key is right, that
+ *   means something else opened it first: MLS consumes a ratchet generation per
+ *   open, so a second reader of the same frame is handed a key that is gone.
+ * - `session-mismatch` — it opened, and belonged to a session this reader is not
+ *   serving. The frame is destroyed for the session it WAS for, which is now
+ *   waiting out its idle timeout with nothing raised.
+ * - `group-mismatch` — a frame for another group arrived on this topic, which
+ *   the envelope catches before the cipher. Same-key misroute, never routine.
+ *
+ * Everything else is routine: `dedup` is the hub redelivering, `topic-mismatch`
+ * is the shared device drain doing its job, `envelope-decode` is a foreign
+ * publisher on the topic.
+ */ const UNEXPECTED_REASONS = new Set([
+    'decrypt',
+    'session-mismatch',
+    'group-mismatch'
+]);
+/**
+ * Turn a tunnel transport's observability events into log lines, and pass them
+ * on to a listener the caller supplied.
+ *
+ * Until this existed the transports' `onEvent` port had no producer anywhere in
+ * the repo — declared, forwarded to the transport, and set by nobody. Every
+ * destroyed frame was therefore silent, in tests and on devices alike: a
+ * starved session showed up as an idle timeout half a minute later with nothing
+ * saying why. That is the entire reason a two-device sync failure had to be
+ * diagnosed by reading code rather than by reading a log.
+ *
+ * `logger` is expected to carry the session's context already (`groupID`,
+ * `peerDID`, `role`, `epoch`, topics), so a line needs no arguments beyond what
+ * the event itself adds.
+ */ export function createTunnelEventLogger(logger, delegate) {
+    return (event)=>{
+        switch(event.type){
+            case 'decrypt-failed':
+                logger.warn('tunnel frame failed to decrypt', {
+                    error: event.error
+                });
+                break;
+            case 'envelope-decode-failed':
+                logger.debug('tunnel envelope failed to decode', {
+                    error: event.error
+                });
+                break;
+            case 'frame-dropped':
+                if (UNEXPECTED_REASONS.has(event.reason)) {
+                    logger.warn('tunnel frame dropped', {
+                        reason: event.reason
+                    });
+                } else {
+                    logger.debug('tunnel frame dropped', {
+                        reason: event.reason
+                    });
+                }
+                break;
+        }
+        delegate?.(event);
+    };
+}

package/lib/sync/tunnel-topics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which side of a directed session a topic belongs to. A `dialer` topic carries
+ * the responses flowing back to whoever opened the session; a `responder` topic
+ * carries the requests arriving at whoever answers.
+ */
+export type TunnelRole = 'dialer' | 'responder';
+/**
+ * The topic on which `ownerDID` receives the frames addressed to it in `role`.
+ *
+ * Both sides derive both topics from the same (secret, epoch), so a dialer knows
+ * where to write and a responder knows where to answer without negotiating
+ * anything. Topics rotate with the MLS epoch exactly as the inbox ones did.
+ *
+ * Scoped by role and owner but NOT by session: a device holds one drain per
+ * (role, peer) and separates concurrent sessions to different peers by sender.
+ * Two sessions in the same role to the SAME peer at once would still contend —
+ * nothing in the sync client opens those, and a session id in the scope would
+ * cost a round trip to agree on before either side could subscribe.
+ */
+export declare function tunnelTopic(secret: Uint8Array, epoch: number, role: TunnelRole, ownerDID: string): string;

package/lib/sync/tunnel-topics.js

@@ -0,0 +1,28 @@
+import { protocolTopic } from '@kumiai/rpc';
+/**
+ * The lane every directed sync tunnel rides, owned by this package.
+ *
+ * Deliberately not `inboxTopic`: that derives ONE topic per member, so a device
+ * dialing a peer and answering that same peer both read and both write the two
+ * members' inboxes. The two roles then share a topic, and sender scope cannot
+ * separate them — a peer's reply and that peer's own dial request are equally
+ * "from the peer". Whichever of the two opens a frame first consumes its MLS
+ * ratchet generation and DESTROYS it for the other, which waits out its idle
+ * timeout instead. `inboxTopic` is also `@kumiai/rpc`'s reserved lane, and a
+ * host protocol has no business publishing into it.
+ */ const SYNC_TUNNEL_PROTOCOL = 'kubun/sync-tunnel/v1';
+/**
+ * The topic on which `ownerDID` receives the frames addressed to it in `role`.
+ *
+ * Both sides derive both topics from the same (secret, epoch), so a dialer knows
+ * where to write and a responder knows where to answer without negotiating
+ * anything. Topics rotate with the MLS epoch exactly as the inbox ones did.
+ *
+ * Scoped by role and owner but NOT by session: a device holds one drain per
+ * (role, peer) and separates concurrent sessions to different peers by sender.
+ * Two sessions in the same role to the SAME peer at once would still contend —
+ * nothing in the sync client opens those, and a session id in the scope would
+ * cost a round trip to agree on before either side could subscribe.
+ */ export function tunnelTopic(secret, epoch, role, ownerDID) {
+    return protocolTopic(secret, epoch, SYNC_TUNNEL_PROTOCOL, `${role}:${ownerDID}`);
+}