@kubun/plugin-p2p 0.8.0

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

@@ -0,0 +1,68 @@
+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 { Logger } from '@kubun/logger';
+import type { 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>;
+};
+export type SyncClientParams = {
+    runtime: Runtime;
+    identity: SigningIdentity;
+    logger: Logger;
+    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+};
+export type SyncScope = {
+    modelID: string;
+    ownerDID: string;
+};
+export type MerkleSyncMessage = {
+    type: 'mutations';
+    mutationJWTs: Array<string>;
+} | {
+    type: 'complete';
+    divergentBuckets?: number;
+    totalMutations?: number;
+};
+/**
+ * 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 declare class SyncClient {
+    #private;
+    constructor(params: SyncClientParams);
+    /**
+     * Connect to a peer server using the specified endpoint.
+     * - `direct://server-id` - Use in-process direct transport via sync server
+     * - `http://...` or `https://...` - Use HTTP transport
+     */
+    connect(endpoint: string, serverID?: string): Promise<Client<SyncProtocol>>;
+    /**
+     * Negotiate sync scopes with peer.
+     */
+    negotiate(client: Client<SyncProtocol>, scopes: Array<SyncScope>, delegationTokens?: Array<string>, knownModelIDs?: Array<string>): Promise<{
+        acceptedScopes: Array<SyncScope>;
+        excludedDocumentIDs: Array<string>;
+        missingClusters?: Record<string, unknown>;
+    }>;
+    /**
+     * Perform Merkle tree-based sync with peer.
+     * Sends local tree, receives divergent mutation JWTs.
+     */
+    merkleSync(client: Client<SyncProtocol>, params: {
+        scopes: Array<SyncScope>;
+        excludedDocumentIDs: Array<string>;
+        tree: Record<string, string>;
+    }): Promise<{
+        mutationJWTs: Array<string>;
+        divergentBuckets: number;
+    }>;
+}

package/lib/sync/sync-client.js

@@ -0,0 +1 @@
+import{Client as e}from"@enkaku/client";import{ClientTransport as t}from"@enkaku/http-client-transport";import{createArraySink as r}from"@enkaku/stream";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.#s(e);if(e.startsWith("http://")||e.startsWith("https://"))return this.#i(e,t);throw Error(`Unsupported endpoint scheme: ${e}`)}#i(r,n){let s=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:s})}#s(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 s=n.createSyncTransport();return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:r,transport:s})}async negotiate(e,t,r=[],n){this.#r.debug("Negotiate: sending {scopeCount} scopes",{scopeCount:t.length});let s=await e.request("sync/negotiate",{param:{scopes:t,delegationTokens:r,knownModelIDs:n}});return this.#r.debug("Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs",{acceptedCount:s.acceptedScopes.length,excludedCount:s.excludedDocumentIDs.length}),s}async merkleSync(e,t){this.#r.debug("MerkleSync: creating stream with {buckets} local buckets",{buckets:Object.keys(t.tree).length});let[n,s]=r(),i=e.createStream("sync/merkle-sync",{param:{scopes:t.scopes,excludedDocumentIDs:t.excludedDocumentIDs,tree:t.tree}}),o=i.readable.pipeTo(n);this.#r.debug("MerkleSync: awaiting stream completion"),await Promise.all([i,o]),this.#r.debug("MerkleSync: stream completed, collecting messages");let c=await s,l=[],a=0;for(let e of c)"mutations"===e.type?l.push(...e.mutationJWTs):"complete"===e.type&&(a=e.divergentBuckets??0);return{mutationJWTs:l,divergentBuckets:a}}}

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

@@ -0,0 +1,61 @@
+import type { Runtime } from '@enkaku/runtime';
+import { type Identity, type SigningIdentity } from '@enkaku/token';
+import type { KubunDB } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import { type PeerConfig, type PeerConfigWithID } from './peer-registry.js';
+import { type SyncScope, type SyncTransportProvider } from './sync-client.js';
+export type SyncSessionInfo = {
+    peerID: string;
+    startTime: number;
+    documentsAttempted: number;
+    documentsCompleted: number;
+};
+export type SyncStatus = {
+    activeSessions: Array<SyncSessionInfo>;
+    lastSyncByPeer: Record<string, number>;
+};
+export type SyncEvent = {
+    type: 'started' | 'completed' | 'error' | 'document:complete' | 'document:failed' | 'document:skipped';
+    peerID: string;
+    documentID?: string;
+    timestamp: number;
+    error?: string;
+    reason?: string;
+};
+export type SyncManagerParams = {
+    db: KubunDB;
+    deployClusters?: (clusters: Record<string, unknown>) => Promise<void>;
+    runtime: Runtime;
+    identity: Identity;
+    logger: Logger;
+    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+};
+export type MerkleSyncOptions = {
+    knownModelIDs?: Array<string>;
+};
+export declare class SyncManager {
+    #private;
+    constructor(params: SyncManagerParams);
+    /**
+     * Configure the signing identity used for sync operations.
+     */
+    setIdentity(identity: SigningIdentity): void;
+    /**
+     * Configure the server resolver for direct transport connections.
+     */
+    setServerResolver(resolver: (serverID: string) => SyncTransportProvider | undefined): void;
+    addPeer(config: PeerConfig): Promise<void>;
+    removePeer(peerDID: string): Promise<void>;
+    updatePeerConfig(peerDID: string, updates: Partial<PeerConfig>): Promise<void>;
+    listPeers(): Promise<Array<PeerConfigWithID>>;
+    getPeer(peerDID: string): Promise<PeerConfigWithID | undefined>;
+    merkleSyncWithPeer(peerDID: string, scopes: Array<SyncScope>, delegationTokens?: Array<string>, options?: MerkleSyncOptions): Promise<{
+        sessionID: string;
+        divergentBuckets: number;
+        messagesReceived: number;
+        missingClusters?: Record<string, unknown>;
+    }>;
+    getStatus(peerDID?: string): SyncStatus;
+    onSyncEvent(callback: (event: SyncEvent) => void): () => void;
+    dispose(): Promise<void>;
+}

package/lib/sync/sync-manager.js

@@ -0,0 +1 @@
+import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{applySyncMutations as s}from"./merkle-apply.js";import{buildMerkleTree as r}from"./merkle-tree.js";import{PeerRegistry as i}from"./peer-registry.js";import{SyncClient as n}from"./sync-client.js";export class SyncManager{#e;#t;#s;#r;#i;#n=new e;#o=new Map;#l=new Map;#a;#c;constructor(e){this.#e=e.db,this.#t=e.deployClusters,this.#s=e.runtime,this.#a=e.identity,this.#r=e.logger,this.#i=new i({db:e.db,runtime:e.runtime}),this.#c=e.serverResolver}setIdentity(e){this.#a=e}setServerResolver(e){this.#c=e}async addPeer(e){await this.#i.addPeer(e),this.#r.info("Peer added",{peerDID:e.peerDID})}async removePeer(e){await this.#i.removePeer(e),this.#r.info("Peer removed",{peerDID:e})}async updatePeerConfig(e,t){await this.#i.updatePeer(e,t),this.#r.info("Peer updated",{peerDID:e})}async listPeers(){return this.#i.listPeers()}async getPeer(e){return this.#i.getPeer(e)}async merkleSyncWithPeer(e,i,o=[],l){let a;this.#r.info("Starting Merkle sync with peer",{peerDID:e,scopes:i});let c=await this.#i.getPeer(e);if(!c)throw Error(`Peer ${e} not found`);let g=`merkle-sync-${e}-${Date.now()}`,m={peerID:e,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#o.set(g,m),this.#g({type:"started",peerID:e,timestamp:Date.now()});try{let p=this.#a;if(!t(p))throw Error("Signing identity required for Merkle sync");let d=new n({runtime:this.#s,identity:p,logger:this.#r,serverResolver:this.#c});a=await d.connect(c.endpoint,e),this.#r.info("Negotiating sync scopes",{scopes:i});let{acceptedScopes:y,excludedDocumentIDs:h,missingClusters:u}=await d.negotiate(a,i,o,l?.knownModelIDs);if(0===y.length)return this.#r.info("No scopes accepted by peer"),this.#l.set(e,Date.now()),this.#g({type:"completed",peerID:e,timestamp:Date.now()}),this.#o.delete(g),{sessionID:g,divergentBuckets:0,messagesReceived:0,missingClusters:u};null!=u&&Object.keys(u).length>0&&(null!=this.#t?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(u).length}),await this.#t(u)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(u).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:y});let v=await this.#e.getDocumentIDsForScope(y,h),f=await this.#e.getMutationLogForDocuments(v),w=r(f);this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(w.buckets).length});let k=await d.merkleSync(a,{scopes:y,excludedDocumentIDs:h,tree:w.buckets});return k.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:k.mutationJWTs.length}),m.documentsCompleted=(await s({db:this.#e,mutationJWTs:k.mutationJWTs})).applied),this.#l.set(e,Date.now()),this.#g({type:"completed",peerID:e,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:k.divergentBuckets,mutationsReceived:k.mutationJWTs.length}),{sessionID:g,divergentBuckets:k.divergentBuckets,messagesReceived:k.mutationJWTs.length,missingClusters:u}}catch(t){throw this.#r.error("Merkle sync failed",{peerDID:e,error:t}),this.#g({type:"error",peerID:e,timestamp:Date.now(),error:t instanceof Error?t.message:String(t)}),t}finally{if(null!=a)try{a.abort("SyncComplete"),await a.dispose()}catch{}this.#o.delete(g)}}getStatus(e){let t=Array.from(this.#o.values()).filter(t=>!e||t.peerID===e).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),s={};for(let[t,r]of this.#l.entries())e&&t!==e||(s[t]=r);return{activeSessions:t,lastSyncByPeer:s}}onSyncEvent(e){return this.#n.on("sync",e)}#g(e){this.#n.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#o.clear(),this.#l.clear()}}

package/lib/types.d.ts

@@ -0,0 +1,148 @@
+import type { ClientTransportOf } from '@enkaku/protocol';
+import type { SyncProtocol } from './protocol.js';
+import type { PeerConfig, PeerConfigWithID } from './sync/peer-registry.js';
+import type { SyncScope } from './sync/sync-client.js';
+import type { SyncEvent, SyncStatus } from './sync/sync-manager.js';
+export type SpaceData = {
+    id: string;
+    name: string;
+    description: string;
+    createdBy: string;
+    createdAt: string;
+};
+export type SpaceMemberData = {
+    spaceID: string;
+    memberDID: string;
+    role: string;
+    createdAt: string;
+};
+export type CircleData = {
+    id: string;
+    spaceID: string;
+    name: string;
+    description: string;
+    createdAt: string;
+};
+export type CircleMemberData = {
+    circleID: string;
+    memberDID: string;
+    role: string;
+    createdAt: string;
+};
+export type CatalogData = {
+    id: string;
+    ownerDID: string;
+    name: string;
+    description: string;
+    filterCriteria: string;
+    createdAt: string;
+};
+export type InviteToSpaceData = {
+    invitePayload: string;
+    spaceID: string;
+    spaceName: string;
+};
+export type JoinSpaceData = {
+    space: SpaceData | null;
+};
+export type LeaveSpaceData = {
+    spaceID: string;
+};
+export type RemoveSpaceMemberData = {
+    spaceID: string;
+};
+export type DeleteCatalogData = {
+    deletedID: string;
+};
+export type DeleteCircleData = {
+    deletedID: string;
+};
+export type RemoveCircleMemberData = {
+    circleID: string;
+    memberDID: string;
+};
+export type UpdateSpaceInput = {
+    spaceID: string;
+    name?: string;
+    description?: string;
+};
+export type UpdateCircleInput = {
+    circleID: string;
+    name?: string;
+    description?: string;
+    catalogIDs?: Array<string>;
+};
+export type SpaceRequestContext = {
+    spaceCreateSpace: (input: {
+        name: string;
+        description?: string;
+    }) => Promise<SpaceData>;
+    spaceGetSpaces: () => Promise<Array<SpaceData>>;
+    spaceGetSpace: (id: string) => Promise<SpaceData | null>;
+    spaceAddSpaceMember: (spaceID: string, memberDID: string, role: string) => Promise<SpaceMemberData>;
+    spaceGetSpaceMembers: (spaceID: string) => Promise<Array<SpaceMemberData>>;
+    spaceCreateCircle: (params: {
+        spaceID: string;
+        name: string;
+        description?: string;
+    }) => Promise<CircleData>;
+    spaceGetCircles: (spaceID: string) => Promise<Array<CircleData>>;
+    spaceAddCircleMember: (circleID: string, memberDID: string, role: string) => Promise<CircleMemberData>;
+    spaceCreateCatalog: (params: {
+        name: string;
+        description?: string;
+        filterCriteria: string;
+    }) => Promise<CatalogData>;
+    spaceGetCatalogs: (ownerDID?: string) => Promise<Array<CatalogData>>;
+    spaceInviteToSpace: (spaceID: string, joinRequest: string) => Promise<InviteToSpaceData>;
+    spaceJoinSpace: (invitePayload: string, joinRequestPayload: string) => Promise<JoinSpaceData>;
+    spaceLeaveSpace: (spaceID: string) => Promise<LeaveSpaceData>;
+    spaceRemoveSpaceMember: (spaceID: string, memberDID: string) => Promise<RemoveSpaceMemberData>;
+    spaceUpdateSpace: (input: UpdateSpaceInput) => Promise<SpaceData>;
+    spaceUpdateCircle: (input: UpdateCircleInput) => Promise<CircleData>;
+    spaceUpdateCatalog: (params: {
+        catalogID: string;
+        name?: string;
+        filterCriteria?: string;
+    }) => Promise<CatalogData>;
+    spaceDeleteCatalog: (catalogID: string) => Promise<DeleteCatalogData>;
+    spaceDeleteCircle: (circleID: string) => Promise<DeleteCircleData>;
+    spaceRemoveCircleMember: (circleID: string, memberDID: string) => Promise<RemoveCircleMemberData>;
+};
+export type SyncRequestContext = {
+    syncAddPeer: (config: PeerConfig) => Promise<void>;
+    syncRemovePeer: (peerDID: string) => Promise<void>;
+    syncListPeers: () => Promise<Array<PeerConfigWithID>>;
+    syncGetStatus: (peerDID?: string) => SyncStatus;
+};
+export type P2PJoinRequestContext = {
+    p2pPrepareJoinRequest: () => Promise<{
+        joinRequest: string;
+    }>;
+    p2pCompleteJoin: (invitePayload: string) => Promise<{
+        space: SpaceData | null;
+    }>;
+};
+export type SyncSessionResult = {
+    sessionID: string;
+    divergentBuckets: number;
+    messagesReceived: number;
+    missingClusters?: Record<string, unknown>;
+};
+export type SyncPluginAPI = {
+    /** Resolves when the HTTP sync transport is registered (only present when http option is enabled). */
+    syncReady?: Promise<void>;
+    addPeer(config: PeerConfig): Promise<void>;
+    removePeer(peerDID: string): Promise<void>;
+    listPeers(): Promise<Array<PeerConfigWithID>>;
+    syncWithPeer(params: {
+        peerDID: string;
+        scopes: Array<SyncScope>;
+        delegationTokens?: Array<string>;
+        knownModelIDs?: Array<string>;
+    }): Promise<SyncSessionResult>;
+    getStatus(peerDID?: string): SyncStatus;
+    onSyncEvent(callback: (event: SyncEvent) => void): () => void;
+    /** Create a sync-specific transport for direct in-process connections. */
+    createSyncTransport(signal?: AbortSignal): ClientTransportOf<SyncProtocol>;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export{};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@kubun/plugin-p2p",
+  "version": "0.8.0",
+  "license": "see LICENSE.md",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@enkaku/async": "^0.14.0",
+    "@enkaku/capability": "^0.14.0",
+    "@enkaku/client": "^0.14.3",
+    "@enkaku/codec": "^0.14.0",
+    "@enkaku/event": "^0.14.1",
+    "@enkaku/generator": "^0.14.0",
+    "@enkaku/group": "^0.14.6",
+    "@enkaku/http-client-transport": "^0.14.3",
+    "@enkaku/http-server-transport": "^0.14.2",
+    "@enkaku/protocol": "^0.14.0",
+    "@enkaku/runtime": "^0.14.0",
+    "@enkaku/schema": "^0.14.0",
+    "@enkaku/server": "^0.14.3",
+    "@enkaku/stream": "^0.14.1",
+    "@enkaku/token": "0.14.1",
+    "@enkaku/transport": "0.14.0",
+    "@noble/hashes": "^2.2.0",
+    "graphql": "^16.13.2",
+    "kysely": "^0.28.16",
+    "@kubun/client": "^0.8.0",
+    "@kubun/graphql": "^0.8.0",
+    "@kubun/hlc": "^0.8.0",
+    "@kubun/db-adapter": "^0.8.0",
+    "@kubun/db": "^0.8.0",
+    "@kubun/engine": "^0.8.0",
+    "@kubun/logger": "^0.8.0",
+    "@kubun/id": "^0.8.0",
+    "@kubun/mutation": "^0.8.0",
+    "@kubun/protocol": "^0.8.0"
+  },
+  "devDependencies": {
+    "get-port": "^7.2.0",
+    "@kubun/db-better-sqlite": "^0.8.0",
+    "@kubun/plugin-connector": "^0.8.0",
+    "@kubun/plugin-http": "^0.8.0",
+    "@kubun/plugin-rpc": "^0.8.0",
+    "@kubun/test-utils": "^0.8.0"
+  },
+  "scripts": {
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}