@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/sync/scope-resolver.js

@@ -1 +1,41 @@
-export function computeBroadcastScopes(e){let{resolvedRule:r,senderGroupIDs:o}=e;switch(r.level){case"only_owner":return[];case"anyone":return Array.from(new Set(o));case"restricted":{let e=new Set;for(let t of o)(r.allowedGroupIDs.has(t)||r.allowedCircleParentGroupIDs.has(t)||r.allowedDIDGroupIDs.has(t))&&e.add(t);return Array.from(e)}default:{let e=r.level;throw Error(`Unknown access level: ${String(e)}`)}}}
+/**
+ * Compute the set of MLS group IDs to broadcast a document to,
+ * given its resolved access rule and the sender's group memberships.
+ *
+ * Pure, synchronous. The caller is responsible for:
+ * - Pre-resolving the access rule into a `ResolvedAccessRule` (all rule-side
+ *   lookups — circle parent groups and per-DID group memberships —
+ *   collapsed to MLS group ID sets).
+ * - Pre-filtering `senderGroupIDs` by catalog-match against the document.
+ *
+ * Per spec §3 "Sync routing" (sender side): a sender's own MLS group is a
+ * valid broadcast scope iff that group is the encryption perimeter for at
+ * least one allowed principal — either the group itself is in allowedGroups,
+ * or an allowed circle's parent group matches, or an allowed DID is a member
+ * of that group. The receiver applies the per-recipient access check on
+ * decrypt; the sender's own circle membership is irrelevant for routing.
+ */ export function computeBroadcastScopes(input) {
+    const { resolvedRule, senderGroupIDs } = input;
+    switch(resolvedRule.level){
+        case 'only_owner':
+            return [];
+        case 'anyone':
+            // Dedupe sender group IDs while preserving the input order.
+            return Array.from(new Set(senderGroupIDs));
+        case 'restricted':
+            {
+                const scopes = new Set();
+                for (const groupID of senderGroupIDs){
+                    if (resolvedRule.allowedGroupIDs.has(groupID) || resolvedRule.allowedCircleParentGroupIDs.has(groupID) || resolvedRule.allowedDIDGroupIDs.has(groupID)) {
+                        scopes.add(groupID);
+                    }
+                }
+                return Array.from(scopes);
+            }
+        default:
+            {
+                const _exhaustive = resolvedRule.level;
+                throw new Error(`Unknown access level: ${String(_exhaustive)}`);
+            }
+    }
+}

package/lib/sync/sync-client.d.ts

@@ -1,21 +1,30 @@
 import { Client } from '@enkaku/client';
 import type { ClientTransportOf } from '@enkaku/protocol';
-import type { Runtime } from '@enkaku/runtime';
-import type { SigningIdentity } from '@enkaku/token';
+import type { SigningIdentity } from '@kokuin/token';
 import type { Logger } from '@kubun/logger';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection, SyncProtocol } from '../protocol.js';
 /**
  * Provider for sync-specific transport to a peer's sync server.
  * The p2p plugin exposes this via `createSyncTransport()`.
  */
 export type SyncTransportProvider = {
-    createSyncTransport: (signal?: AbortSignal) => ClientTransportOf<SyncProtocol>;
+    createSyncTransport: (signal?: AbortSignal) => ClientTransportOf<SyncProtocol> | Promise<ClientTransportOf<SyncProtocol>>;
 };
+/**
+ * What a route carries beyond the peer DID. `tunnel://` names the group whose
+ * MLS epoch keys the session's inbox topics; `direct://` names nothing, so a
+ * resolver serving only in-process peers can ignore the second argument.
+ */
+export type SyncRoute = {
+    groupID: string;
+};
+export type SyncServerResolver = (serverID: string, route?: SyncRoute) => SyncTransportProvider | undefined;
 export type SyncClientParams = {
     runtime: Runtime;
     identity: SigningIdentity;
     logger: Logger;
-    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    serverResolver?: SyncServerResolver;
 };
 export type SyncScope = {
     modelID: string;
@@ -34,6 +43,7 @@ export declare class SyncClient {
     /**
      * Connect to a peer server using the specified endpoint.
      * - `direct://server-id` - Use in-process direct transport via sync server
+     * - `tunnel://group-id/peer-did` - Use a hub tunnel through the named group
      * - `http://...` or `https://...` - Use HTTP transport
      */
     connect(endpoint: string, serverID?: string): Promise<Client<SyncProtocol>>;

package/lib/sync/sync-client.js

@@ -1 +1,254 @@
-import{Client as e}from"@enkaku/client";import{ClientTransport as t}from"@enkaku/http-client-transport";import{findDivergentBuckets as r,getTimeBuckets as n,SYNC_BATCH_SIZE as i}from"./merkle-tree.js";export class SyncClient{#e;#t;#r;#n;constructor(e){this.#e=e.runtime,this.#t=e.identity,this.#r=e.logger,this.#n=e.serverResolver}async connect(e,t){if(e.startsWith("direct://"))return this.#i(e);if(e.startsWith("http://")||e.startsWith("https://"))return this.#s(e,t);throw Error(`Unsupported endpoint scheme: ${e}`)}#s(r,n){if(null==n||""===n)throw Error("HTTP sync transport requires a serverID (peer DID) to authenticate; without it the server rejects all requests");let i=new t({url:r,fetch:this.#e.fetch});return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:n,transport:i})}#i(t){let r=t.replace("direct://","");if(!this.#n)throw Error("Server resolver not configured for direct transport");let n=this.#n(r);if(!n)throw Error(`Server not found: ${r}`);let i=n.createSyncTransport();return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:r,transport:i})}async negotiate(e,t,r=[],n,i){this.#r.debug("Negotiate: sending {scopeCount} scopes",{scopeCount:t.length});let s=await e.request("sync/negotiate",{param:{scopes:t,delegationTokens:r,knownModelIDs:n,direction:i}});return this.#r.debug("Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs",{acceptedCount:s.acceptedScopes.length,excludedCount:s.excludedDocumentIDs.length}),s}async merkleSync(e,t){let{scopes:s,excludedDocumentIDs:o,localTree:c,direction:l,localEntries:a,delegationTokens:u}=t;this.#r.debug("MerkleSync: creating channel with {buckets} local buckets",{buckets:Object.keys(c.buckets).length});let h=e.createChannel("sync/merkle-sync",{param:{scopes:s,excludedDocumentIDs:o,tree:c.buckets,direction:l,...null!=u&&{delegationTokens:u}}}),d=h.readable.getReader(),g=await d.read();if(g.done)throw Error("MerkleSync: channel closed before receiving remote tree");let p=g.value;if("tree"!==p.type)throw Error(`MerkleSync: expected 'tree' message, got '${p.type}'`);let m=r(c,{root:p.tree?.root??"",buckets:p.tree??{}}),y=m.length;this.#r.debug("MerkleSync: found {count} divergent buckets",{count:y});let f=0,k=async()=>{if("push"===l||"both"===l){let e=new Set(m),t=a.filter(t=>{let{minute:r}=n(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=i){let r=t.slice(e,e+i);await h.send({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),f+=r.length}}await h.send({type:"complete"})},v=async()=>{let e=[];for(;;){let{done:t,value:r}=await d.read();if(t)break;if("mutations"===r.type&&null!=r.mutationJWTs)e.push(...r.mutationJWTs);else if("complete"===r.type)break}return d.releaseLock(),e},[,w]=await Promise.all([k(),v()]),b=await h;if(null!=b&&!b.success)throw Error("MerkleSync: responder reported failure");return this.#r.debug("MerkleSync: completed with {received} received, {sent} sent",{received:w.length,sent:f}),{mutationJWTs:w,divergentBuckets:y,mutationsSent:f}}}
+import { Client } from '@enkaku/client';
+import { ClientTransport as HTTPClientTransport } from '@enkaku/http-fetch';
+import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-tree.js';
+/**
+ * Client for connecting to peer servers for sync operations.
+ * Supports both direct (in-process) and HTTP transports.
+ *
+ * Uses a raw Enkaku `Client<SyncProtocol>` for sync connections rather than
+ * `KubunClient`, since only sync procedures (negotiate, merkle-sync) are needed.
+ */ export class SyncClient {
+    #runtime;
+    #identity;
+    #logger;
+    #serverResolver;
+    /**
+   * The context each session's lines carry, keyed by the client `connect` built
+   * for it.
+   *
+   * Held here rather than passed through `negotiate` / `merkleSync` because the
+   * peer a session is talking to is fixed when it is dialled and is not a
+   * parameter of either call. Without it these logs report bucket and mutation
+   * counts with nothing naming the peer, which is what makes two devices' logs
+   * impossible to join except by grepping DIDs out of unrelated lines.
+   *
+   * The transport's own `sessionID` is not here: it is minted inside the tunnel
+   * provider, which logs it against the same (group, peer, epoch).
+   */ #sessionLoggers = new WeakMap();
+    constructor(params){
+        this.#runtime = params.runtime;
+        this.#identity = params.identity;
+        this.#logger = params.logger;
+        this.#serverResolver = params.serverResolver;
+    }
+    /**
+   * Connect to a peer server using the specified endpoint.
+   * - `direct://server-id` - Use in-process direct transport via sync server
+   * - `tunnel://group-id/peer-did` - Use a hub tunnel through the named group
+   * - `http://...` or `https://...` - Use HTTP transport
+   */ async connect(endpoint, serverID) {
+        if (endpoint.startsWith('direct://')) {
+            return this.#connectDirect(endpoint);
+        }
+        if (endpoint.startsWith('tunnel://')) {
+            return this.#connectTunnel(endpoint);
+        }
+        if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+            return this.#connectHTTP(endpoint, serverID);
+        }
+        throw new Error(`Unsupported endpoint scheme: ${endpoint}`);
+    }
+    /** The session's own logger, or the client-wide one for a session built elsewhere. */ #loggerFor(client) {
+        return this.#sessionLoggers.get(client) ?? this.#logger;
+    }
+    #trackSession(client, context) {
+        this.#sessionLoggers.set(client, this.#logger.getChild('sync-client').with(context));
+        return client;
+    }
+    #connectHTTP(endpoint, serverID) {
+        if (serverID == null || serverID === '') {
+            throw new Error('HTTP sync transport requires a serverID (peer DID) to authenticate; without it the server rejects all requests');
+        }
+        const transport = new HTTPClientTransport({
+            url: endpoint,
+            fetch: this.#runtime.fetch
+        });
+        return this.#trackSession(new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        }), {
+            peerDID: serverID,
+            scheme: 'http'
+        });
+    }
+    async #connectDirect(endpoint) {
+        return await this.#connectResolved(endpoint.replace('direct://', ''), 'direct');
+    }
+    /**
+   * `tunnel://<groupID>/<peerDID>` — a session relayed by the group's hub, with
+   * no server listening on either device. The audience comes from the route
+   * itself rather than from `connect`'s `serverID` argument: the route names the
+   * device whose inbox the frames are addressed to, so the two cannot disagree.
+   */ async #connectTunnel(endpoint) {
+        const route = endpoint.slice('tunnel://'.length);
+        const separator = route.indexOf('/');
+        const groupID = separator === -1 ? '' : route.slice(0, separator);
+        const peerDID = separator === -1 ? '' : route.slice(separator + 1);
+        if (groupID === '' || peerDID === '') {
+            throw new Error(`Invalid tunnel endpoint: ${endpoint} — expected tunnel://<groupID>/<peerDID>`);
+        }
+        return await this.#connectResolved(peerDID, 'tunnel', {
+            groupID
+        });
+    }
+    async #connectResolved(serverID, scheme, route) {
+        if (!this.#serverResolver) {
+            throw new Error(`Server resolver not configured for ${scheme} transport`);
+        }
+        const provider = this.#serverResolver(serverID, route);
+        if (!provider) {
+            throw new Error(`Server not found: ${serverID}`);
+        }
+        // Get a sync-specific transport from the peer's p2p plugin. The provider may
+        // build the transport asynchronously (e.g. the hub-tunnel provider derives
+        // its epoch-bound inbox topics from the live MLS handle), so await it; an
+        // in-process provider returning a transport synchronously is unaffected.
+        const transport = await provider.createSyncTransport();
+        return this.#trackSession(new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        }), {
+            peerDID: serverID,
+            scheme,
+            ...route == null ? {} : {
+                groupID: route.groupID
+            }
+        });
+    }
+    /**
+   * Negotiate sync scopes with peer.
+   */ async negotiate(client, scopes, delegationTokens = [], knownModelIDs, direction) {
+        const logger = this.#loggerFor(client);
+        logger.debug('Negotiate: sending {scopeCount} scopes', {
+            scopeCount: scopes.length
+        });
+        const result = await client.request('sync/negotiate', {
+            param: {
+                scopes,
+                delegationTokens,
+                knownModelIDs,
+                direction
+            }
+        });
+        logger.debug('Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs', {
+            acceptedCount: result.acceptedScopes.length,
+            excludedCount: result.excludedDocumentIDs.length
+        });
+        return result;
+    }
+    /**
+   * Perform Merkle tree-based sync with peer using bidirectional channel.
+   * Sends local tree and divergent mutations, receives remote mutations.
+   */ async merkleSync(client, params) {
+        const { scopes, excludedDocumentIDs, localTree, direction, localEntries, delegationTokens } = params;
+        const logger = this.#loggerFor(client);
+        logger.debug('MerkleSync: creating channel with {buckets} local buckets', {
+            buckets: Object.keys(localTree.buckets).length
+        });
+        const channelCall = client.createChannel('sync/merkle-sync', {
+            param: {
+                scopes,
+                excludedDocumentIDs,
+                tree: localTree.buckets,
+                direction,
+                ...delegationTokens != null && {
+                    delegationTokens
+                }
+            }
+        });
+        // Marked handled the moment it exists, because the call is awaited LAST —
+        // after the send/receive pair below. A transport that aborts rejects all
+        // three, `Promise.all` throws first, and this one's rejection then reaches
+        // nobody: on React Native that is an error overlay with no message, which
+        // is exactly how a starved tunnel session presented during device QA. The
+        // await at the end still sees the rejection; this only stops it counting as
+        // unhandled in the window before that.
+        void channelCall.catch(()=>{});
+        // Step 1: Read the responder's tree from the first message
+        const reader = channelCall.readable.getReader();
+        const firstRead = await reader.read();
+        if (firstRead.done) {
+            throw new Error('MerkleSync: channel closed before receiving remote tree');
+        }
+        const firstMessage = firstRead.value;
+        if (firstMessage.type !== 'tree') {
+            throw new Error(`MerkleSync: expected 'tree' message, got '${firstMessage.type}'`);
+        }
+        // Step 2: Compute divergent buckets
+        const remoteTree = {
+            root: firstMessage.tree?.root ?? '',
+            buckets: firstMessage.tree ?? {}
+        };
+        const divergentBuckets = findDivergentBuckets(localTree, remoteTree);
+        const divergentBucketCount = divergentBuckets.length;
+        logger.debug('MerkleSync: found {count} divergent buckets', {
+            count: divergentBucketCount
+        });
+        // Step 3: Concurrent send and receive
+        let mutationsSent = 0;
+        // Send task: send divergent mutations to responder
+        const sendTask = async ()=>{
+            if (direction === 'push' || direction === 'both') {
+                // Filter local entries to those in divergent buckets
+                const divergentSet = new Set(divergentBuckets);
+                const entriesToSend = localEntries.filter((entry)=>{
+                    const { minute } = getTimeBuckets(entry.hlc);
+                    return divergentSet.has(minute);
+                });
+                // Send in batches
+                for(let i = 0; i < entriesToSend.length; i += SYNC_BATCH_SIZE){
+                    const batch = entriesToSend.slice(i, i + SYNC_BATCH_SIZE);
+                    await channelCall.send({
+                        type: 'mutations',
+                        mutationJWTs: batch.map((e)=>e.mutation_jwt)
+                    });
+                    mutationsSent += batch.length;
+                }
+            }
+            // Signal completion
+            await channelCall.send({
+                type: 'complete'
+            });
+        };
+        // Receive task: collect mutations from responder
+        const receiveTask = async ()=>{
+            const collectedJWTs = [];
+            while(true){
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (value.type === 'mutations' && value.mutationJWTs != null) {
+                    collectedJWTs.push(...value.mutationJWTs);
+                } else if (value.type === 'complete') {
+                    break;
+                }
+            }
+            reader.releaseLock();
+            return collectedJWTs;
+        };
+        const [, mutationJWTs] = await Promise.all([
+            sendTask(),
+            receiveTask()
+        ]);
+        // Wait for the handler to finish processing (applying pushed mutations)
+        // before returning — prevents transport teardown racing with mutation application
+        const handlerResult = await channelCall;
+        if (handlerResult != null && !handlerResult.success) {
+            throw new Error('MerkleSync: responder reported failure');
+        }
+        logger.debug('MerkleSync: completed with {received} received, {sent} sent', {
+            received: mutationJWTs.length,
+            sent: mutationsSent
+        });
+        return {
+            mutationJWTs,
+            divergentBuckets: divergentBucketCount,
+            mutationsSent
+        };
+    }
+}

package/lib/sync/sync-manager.d.ts

@@ -1,12 +1,12 @@
-import type { Runtime } from '@enkaku/runtime';
-import { type Identity, type SigningIdentity } from '@enkaku/token';
+import { type Identity, type SigningIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection } from '../protocol.js';
 import type { StoreUnreadableMode } from '../types.js';
 import { type PeerConfig, type PeerConfigWithID, PeerRegistry } from './peer-registry.js';
-import { type SyncScope, type SyncTransportProvider } from './sync-client.js';
+import { type SyncScope, type SyncServerResolver } from './sync-client.js';
 export type SyncSessionInfo = {
     peerID: string;
     startTime: number;
@@ -31,7 +31,7 @@ export type SyncManagerParams = {
     runtime: Runtime;
     identity: Identity;
     logger: Logger;
-    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    serverResolver?: SyncServerResolver;
     /**
      * Receive-side storage mode forwarded to `applySyncMutations`.
      * Defaults to `'persist'` when omitted.
@@ -47,6 +47,15 @@ export type MerkleSyncParams = {
     delegationTokens?: Array<string>;
     knownModelIDs?: Array<string>;
     direction?: SyncDirection;
+    /**
+     * Where to reach the peer, when the caller already resolved it. Omitted, the
+     * persisted registry answers and a peer with no row is an error.
+     *
+     * A route, and only a route: what a session serves is decided per document
+     * downstream, so supplying one reaches a peer the registry never heard of and
+     * grants it nothing.
+     */
+    endpoint?: string;
 };
 export declare class SyncManager {
     #private;
@@ -57,9 +66,11 @@ export declare class SyncManager {
      */
     setIdentity(identity: SigningIdentity): void;
     /**
-     * Configure the server resolver for direct transport connections.
+     * Configure the resolver for the transports built locally rather than dialled:
+     * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose
+     * group id arrives as the resolver's `route`).
      */
-    setServerResolver(resolver: (serverID: string) => SyncTransportProvider | undefined): void;
+    setServerResolver(resolver: SyncServerResolver): void;
     addPeer(params: {
         config: PeerConfig;
         stores: StoreProvider;
@@ -92,5 +103,12 @@ export declare class SyncManager {
         stores: StoreProvider;
     }): SyncStatus;
     onSyncEvent(callback: (event: SyncEvent) => void): () => void;
+    /**
+     * Async-iterable view of the sync event stream, for bridging into a GraphQL
+     * subscription. An optional `filter` narrows to a single peer. Closing the
+     * generator (its `return()`, e.g. a subscriber disconnecting) unsubscribes the
+     * underlying listener, so no listener leaks past the consumer.
+     */
+    subscribeEvents(filter?: (event: SyncEvent) => boolean): AsyncGenerator<SyncEvent, void, void>;
     dispose(): Promise<void>;
 }