@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/sync/broadcast-queue.js

@@ -1 +1,183 @@
-export const DEFAULT_BROADCAST_BATCH_CONFIG={enabled:!0,windowMs:500,maxCount:20,maxBytes:65536};export function createBroadcastQueue(e){let{config:t,scheduleBroadcast:r,logger:n}=e,l=new Map,o=!1;function u(e){let t=l.get(e);if(null==t||0===t.entries.length)return;null!=t.timer&&(clearTimeout(t.timer),t.timer=null);let o=t.entries,u=t.senderPeerDID;l.delete(e);try{r(e,{type:"mutation:apply",entries:o,senderPeerDID:u})}catch(t){n?.warn("broadcast-queue flush failed",{targetGroupID:e,entryCount:o.length,error:String(t)})}}return{enqueue:function(e,i,a){if(o)return void n?.warn("broadcast-queue enqueue after dispose, dropping entry",{targetGroupID:e,docID:i.docID});if(!t.enabled){try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue pass-through scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let s=JSON.stringify(i).length;if(s>=t.maxBytes){let t=l.get(e);null!=t&&t.entries.length>0&&u(e);try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue oversize-entry scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let d=l.get(e);if(null!=d&&d.senderPeerDID!==a&&(u(e),d=void 0),null!=d&&d.bytes+s>t.maxBytes&&(u(e),d=void 0),null==d){l.set(e,{entries:[i],bytes:s,senderPeerDID:a,timer:null});let r=l.get(e);return null!=r&&r.entries.length>=t.maxCount?void u(e):void!function(e){let r=l.get(e);if(null==r||null!=r.timer)return;let n=setTimeout(()=>{u(e)},t.windowMs),o=n.unref;"function"==typeof o&&o.call(n),r.timer=n}(e)}d.entries.push(i),d.bytes+=s,d.entries.length>=t.maxCount&&u(e)},dispose:function(){if(!o)for(let e of(o=!0,Array.from(l.keys())))u(e)}}}
+export const DEFAULT_BROADCAST_BATCH_CONFIG = {
+    enabled: true,
+    windowMs: 500,
+    maxCount: 20,
+    maxBytes: 64 * 1024
+};
+/**
+ * Build a per-target-group batch queue around a `scheduleBroadcast` hook.
+ *
+ * The `mutation:apply` broadcast variant carries `entries: Array<...>` —
+ * a queue flush emits ONE broadcast with the accumulated entries, not one
+ * broadcast per entry.
+ *
+ * Each enqueued entry's wire size is approximated via `JSON.stringify(entry).length`.
+ * The accumulated byte budget tracks per-batch payload size only — message
+ * envelope (`type`, `senderPeerDID`) overhead is intentionally ignored to keep
+ * accounting cheap and predictable.
+ *
+ * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
+ * entry in each batch. If a later enqueue arrives with a different sender
+ * (defensive — in practice senderPeerDID is constant per peer), the prior
+ * batch is flushed and a fresh batch starts. This preserves the invariant
+ * that every flushed `mutation:apply` message carries a single coherent
+ * `senderPeerDID`.
+ */ export function createBroadcastQueue(params) {
+    const { config, scheduleBroadcast, logger } = params;
+    const queues = new Map();
+    let disposed = false;
+    function clearTimer(state) {
+        if (state.timer != null) {
+            clearTimeout(state.timer);
+            state.timer = null;
+        }
+    }
+    function flush(targetGroupID) {
+        const state = queues.get(targetGroupID);
+        if (state == null || state.entries.length === 0) {
+            return;
+        }
+        clearTimer(state);
+        const entries = state.entries;
+        const senderPeerDID = state.senderPeerDID;
+        queues.delete(targetGroupID);
+        try {
+            scheduleBroadcast(targetGroupID, {
+                type: 'mutation:apply',
+                entries,
+                senderPeerDID
+            });
+        } catch (error) {
+            logger?.warn('broadcast-queue flush failed', {
+                targetGroupID,
+                entryCount: entries.length,
+                error: String(error)
+            });
+        }
+    }
+    function startTimer(targetGroupID) {
+        const state = queues.get(targetGroupID);
+        if (state == null || state.timer != null) {
+            return;
+        }
+        const timer = setTimeout(()=>{
+            flush(targetGroupID);
+        }, config.windowMs);
+        // Don't hold the process open just for a pending broadcast batch.
+        // Node returns a Timeout object with `unref()`; browsers return a number.
+        const maybeUnref = timer.unref;
+        if (typeof maybeUnref === 'function') {
+            maybeUnref.call(timer);
+        }
+        state.timer = timer;
+    }
+    function appendToFreshBatch(targetGroupID, entry, entryBytes, senderPeerDID) {
+        const state = {
+            entries: [
+                entry
+            ],
+            bytes: entryBytes,
+            senderPeerDID,
+            timer: null
+        };
+        queues.set(targetGroupID, state);
+    }
+    function enqueue(targetGroupID, entry, senderPeerDID) {
+        if (disposed) {
+            logger?.warn('broadcast-queue enqueue after dispose, dropping entry', {
+                targetGroupID,
+                docID: entry.docID
+            });
+            return;
+        }
+        // Pass-through mode: emit each entry as its own single-entry broadcast.
+        if (!config.enabled) {
+            try {
+                scheduleBroadcast(targetGroupID, {
+                    type: 'mutation:apply',
+                    entries: [
+                        entry
+                    ],
+                    senderPeerDID
+                });
+            } catch (error) {
+                logger?.warn('broadcast-queue pass-through scheduleBroadcast failed', {
+                    targetGroupID,
+                    docID: entry.docID,
+                    error: String(error)
+                });
+            }
+            return;
+        }
+        const entryBytes = JSON.stringify(entry).length;
+        // Oversize lone entry: skip the queue and ship as its own batch immediately.
+        // If a batch is already queued for this group, flush it first to preserve
+        // ordering (older entries ship before this lone giant).
+        if (entryBytes >= config.maxBytes) {
+            const existing = queues.get(targetGroupID);
+            if (existing != null && existing.entries.length > 0) {
+                flush(targetGroupID);
+            }
+            try {
+                scheduleBroadcast(targetGroupID, {
+                    type: 'mutation:apply',
+                    entries: [
+                        entry
+                    ],
+                    senderPeerDID
+                });
+            } catch (error) {
+                logger?.warn('broadcast-queue oversize-entry scheduleBroadcast failed', {
+                    targetGroupID,
+                    docID: entry.docID,
+                    error: String(error)
+                });
+            }
+            return;
+        }
+        let state = queues.get(targetGroupID);
+        // Sender mismatch: flush prior batch, start fresh.
+        if (state != null && state.senderPeerDID !== senderPeerDID) {
+            flush(targetGroupID);
+            state = undefined;
+        }
+        // Byte threshold: would adding this entry overflow? Flush first, start new batch.
+        if (state != null && state.bytes + entryBytes > config.maxBytes) {
+            flush(targetGroupID);
+            state = undefined;
+        }
+        if (state == null) {
+            appendToFreshBatch(targetGroupID, entry, entryBytes, senderPeerDID);
+            // Start the window timer for this new batch — only if we won't flush
+            // synchronously below for count reasons.
+            const fresh = queues.get(targetGroupID);
+            if (fresh != null && fresh.entries.length >= config.maxCount) {
+                flush(targetGroupID);
+                return;
+            }
+            startTimer(targetGroupID);
+            return;
+        }
+        state.entries.push(entry);
+        state.bytes += entryBytes;
+        // Count threshold: flush synchronously without waiting for the timer.
+        if (state.entries.length >= config.maxCount) {
+            flush(targetGroupID);
+        }
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        // Snapshot keys — flush mutates the map.
+        const targets = Array.from(queues.keys());
+        for (const targetGroupID of targets){
+            flush(targetGroupID);
+        }
+    }
+    return {
+        enqueue,
+        dispose
+    };
+}

package/lib/sync/broadcast-sender.js

@@ -1 +1,179 @@
-import{catalogMatchesDoc as e,resolveAccessRule as r}from"@kubun/engine";import{DocumentID as t}from"@kubun/id";import{getGraphStore as o}from"@kubun/store-graph";import{getP2PStore as l}from"@kubun/store-p2p";import{computeBroadcastScopes as a}from"./scope-resolver.js";export const DEFAULT_PUSH_SYNC_CONFIG={enabled:!1};let n={read:"only_owner",write:"only_owner"};export function wireBroadcastSender(e){let r=e.defaultAccessLevel??n;return e.eventBus.on("engine:mutation:authored",async t=>{try{await i(t,{...e,defaultAccessLevel:r})}catch(r){e.logger?.warn("broadcast-sender handler failed",{documentID:t.documentID,error:String(r)})}})}async function i(n,i){let s=await o(i.db),d=await l(i.db),u=await s.getDocument(t.fromString(n.documentID));if(null==u)return;let f=await r(u,u.model,u.owner,"read",{getUserModelAccessDefault:(e,r,t)=>s.getUserModelAccessDefault(e,r,t),isMemberOfAnyCircle:(e,r)=>d.isMemberOfAnyCircle(e,r),isMemberOfAnyGroup:(e,r)=>d.isMemberOfAnyGroup(e,r),getModelInterfaces:e=>s.getModelInterfaces(e)},i.defaultAccessLevel);if("only_owner"===f.level)return;let c=await d.getCirclesForMember(i.selfDID),m=new Set;for(let e of c)for(let r of e.catalog_ids??[])m.add(r);let w=m.size>0?await s.getCatalogs(Array.from(m)):new Map,g=[];for(let e of c)for(let r of e.catalog_ids??[]){let t=w.get(r);null!=t&&g.push({groupID:e.group_id,criteria:t.filter_criteria})}let D=await Promise.all(g.map(async r=>({groupID:r.groupID,matched:await e(r.criteria,u,d)}))),p=new Set;for(let e of D)e.matched&&p.add(e.groupID);let I=Array.from(p);if(0===I.length)return;let b=new Set(f.allowedGroups??[]),v=new Set;if(null!=f.allowedCircles&&f.allowedCircles.length>0)for(let e of(await d.getCircles(f.allowedCircles)).values())null!=e.group_id&&v.add(e.group_id);let y=new Set;if(null!=f.allowedDIDs&&f.allowedDIDs.length>0)for(let e of(await d.getGroupsForMembers(f.allowedDIDs)).values())for(let r of e)y.add(r.id);let _=a({resolvedRule:{level:f.level,allowedGroupIDs:b,allowedCircleParentGroupIDs:v,allowedDIDGroupIDs:y},senderGroupIDs:I});if(0!==_.length)for(let e of _){if(!await d.recordBroadcast({docID:n.documentID,version:n.version,mlsGroupID:e}))continue;let r={mutationJWT:n.mutationJWT,docID:n.documentID,version:n.version,modelID:n.modelID};i.queue.enqueue(e,r,i.selfDID)}}
+import { catalogMatchesDoc, resolveAccessRule } from '@kubun/engine';
+import { DocumentID } from '@kubun/id';
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { computeBroadcastScopes } from './scope-resolver.js';
+/**
+ * Default push-sync config. Disabled by default — push-sync is opt-in even
+ * when a hub is configured. Apps that want immediate broadcast on local
+ * authoring must explicitly set `pushSync: { enabled: true }`.
+ */ export const DEFAULT_PUSH_SYNC_CONFIG = {
+    enabled: false
+};
+/**
+ * Default rule used by the broadcast sender when the engine is not carrying
+ * an explicit server-side default access level. Kept conservative (only the
+ * owner receives) so undeclared models never accidentally fan out.
+ */ const DEFAULT_ACCESS_LEVEL = {
+    read: 'only_owner',
+    write: 'only_owner'
+};
+/**
+ * Subscribe to `engine:mutation:authored` and, for each locally-authored
+ * mutation, compute the set of MLS group scopes to broadcast to (via the
+ * pure `computeBroadcastScopes`) and fire per-scope
+ * `mutation:apply` broadcasts through the provided `scheduleBroadcast` hook.
+ *
+ * The subscriber swallows errors — a failure here must not propagate into the
+ * engine's event loop and stall other listeners. Errors are logged via the
+ * optional logger.
+ *
+ * Returns an unsubscribe function — the caller is responsible for invoking it
+ * on plugin dispose.
+ */ export function wireBroadcastSender(params) {
+    const defaultAccessLevel = params.defaultAccessLevel ?? DEFAULT_ACCESS_LEVEL;
+    return params.eventBus.on('engine:mutation:authored', async (event)=>{
+        try {
+            await handleAuthoredMutation(event, {
+                ...params,
+                defaultAccessLevel
+            });
+        } catch (error) {
+            params.logger?.warn('broadcast-sender handler failed', {
+                documentID: event.documentID,
+                error: String(error)
+            });
+        }
+    });
+}
+async function handleAuthoredMutation(event, params) {
+    const graphStore = await getGraphStore(params.db);
+    const p2pStore = await getP2PStore(params.db);
+    // 1. Fetch document. If it no longer exists (unexpected, since the apply
+    // just completed) there is nothing to route — drop silently.
+    const doc = await graphStore.getDocument(DocumentID.fromString(event.documentID));
+    if (doc == null) {
+        return;
+    }
+    // 2. Resolve the effective read rule — broadcast scope follows read access.
+    const rule = await resolveAccessRule(doc, doc.model, doc.owner, 'read', {
+        getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>graphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+        isMemberOfAnyCircle: (viewerDID, circleIDs)=>p2pStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+        isMemberOfAnyGroup: (viewerDID, groupIDs)=>p2pStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+        getModelInterfaces: (modelID)=>graphStore.getModelInterfaces(modelID)
+    }, params.defaultAccessLevel);
+    // Short-circuit only_owner — scope resolver would also drop this, but we
+    // can avoid all the catalog lookups.
+    if (rule.level === 'only_owner') {
+        return;
+    }
+    // 3. Enumerate sender's circles and catalog-match per circle. A sender's MLS
+    // group is a candidate broadcast scope iff at least one of the sender's
+    // circles within that group covers this document.
+    //
+    // Pre-fetch every catalog referenced across senderCircles in ONE batched
+    // query — replaces an O(circles × catalogs) sequential `getCatalog` loop.
+    // catalogMatchesDoc reads are then run in parallel since they have no
+    // inter-iteration ordering.
+    const senderCircles = await p2pStore.getCirclesForMember(params.selfDID);
+    const catalogIDSet = new Set();
+    for (const circle of senderCircles){
+        for (const catalogID of circle.catalog_ids ?? []){
+            catalogIDSet.add(catalogID);
+        }
+    }
+    const catalogsByID = catalogIDSet.size > 0 ? await graphStore.getCatalogs(Array.from(catalogIDSet)) : new Map();
+    const matchInputs = [];
+    for (const circle of senderCircles){
+        for (const catalogID of circle.catalog_ids ?? []){
+            const catalog = catalogsByID.get(catalogID);
+            if (catalog == null) continue;
+            matchInputs.push({
+                groupID: circle.group_id,
+                criteria: catalog.filter_criteria
+            });
+        }
+    }
+    const matchResults = await Promise.all(matchInputs.map(async (input)=>({
+            groupID: input.groupID,
+            matched: await catalogMatchesDoc(input.criteria, doc, p2pStore)
+        })));
+    const matchedGroupIDs = new Set();
+    for (const r of matchResults){
+        if (r.matched) matchedGroupIDs.add(r.groupID);
+    }
+    const senderGroupIDs = Array.from(matchedGroupIDs);
+    if (senderGroupIDs.length === 0) {
+        return;
+    }
+    // 4. Build the ResolvedAccessRule expected by computeBroadcastScopes.
+    const allowedGroupIDs = new Set(rule.allowedGroups ?? []);
+    // Single batched query for allowedCircles → parent group IDs. Replaces a
+    // per-circle `getCircle` loop.
+    const allowedCircleParentGroupIDs = new Set();
+    if (rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+        const circlesByID = await p2pStore.getCircles(rule.allowedCircles);
+        for (const circle of circlesByID.values()){
+            if (circle.group_id != null) {
+                allowedCircleParentGroupIDs.add(circle.group_id);
+            }
+        }
+    }
+    // Single batched query for allowedDIDs → groups. Replaces a per-DID
+    // `getGroupsForMember` loop.
+    const allowedDIDGroupIDs = new Set();
+    if (rule.allowedDIDs != null && rule.allowedDIDs.length > 0) {
+        const groupsByDID = await p2pStore.getGroupsForMembers(rule.allowedDIDs);
+        for (const groups of groupsByDID.values()){
+            for (const g of groups){
+                allowedDIDGroupIDs.add(g.id);
+            }
+        }
+    }
+    const resolvedRule = {
+        level: rule.level,
+        allowedGroupIDs,
+        allowedCircleParentGroupIDs,
+        allowedDIDGroupIDs
+    };
+    // 5. Resolve final broadcast scopes.
+    const scopes = computeBroadcastScopes({
+        resolvedRule,
+        senderGroupIDs
+    });
+    if (scopes.length === 0) {
+        return;
+    }
+    // 6. Per scope — broadcast_log dedup (returns false if already recorded)
+    // then enqueue into the per-target-group batch queue. Dedup MUST run before
+    // enqueue so duplicate entries never enter the queue.
+    //
+    // Record-before-send: a recorded entry whose queue.enqueue throws will
+    // not be retried. This is at-most-once delivery by design; missing
+    // broadcasts are recovered via merkle-pull, not by replaying the
+    // authored event.
+    //
+    // This loop stays SEQUENTIAL (no Promise.all). `recordBroadcast` ordering
+    // matters for the at-most-once invariant, and the queue's per-group state
+    // machines have not been audited for concurrent enqueue safety. The earlier
+    // catalog-match/getCircles/getGroupsForMembers calls were parallelized
+    // because they are pure DB reads with no inter-iteration ordering — this
+    // path performs side-effecting writes and external dispatch.
+    for (const groupID of scopes){
+        const recorded = await p2pStore.recordBroadcast({
+            docID: event.documentID,
+            version: event.version,
+            mlsGroupID: groupID
+        });
+        if (!recorded) {
+            continue;
+        }
+        const entry = {
+            mutationJWT: event.mutationJWT,
+            docID: event.documentID,
+            version: event.version,
+            modelID: event.modelID
+        };
+        params.queue.enqueue(groupID, entry, params.selfDID);
+    }
+}

package/lib/sync/catalog-scope.js

@@ -1 +1,68 @@
-import{getGraphStore as e}from"@kubun/store-graph";import{getP2PStore as r}from"@kubun/store-p2p";export async function resolveCatalogSyncScopes(l,t,o){let[a,i]=await Promise.all([e(l),r(l)]),s=new Set,f=new Set,n=!1;for(let e of t){let r=await a.resolveCatalogScope(e);if(null!=r.models)for(let e of r.models)s.add(e);if(null!=r.owners)for(let e of(n=!0,r.owners))f.add(e);let l=await a.getCatalog(e);if(null!=l){let e=l.filter_criteria;if(null!=e.circles&&e.circles.length>0)for(let r of(n=!0,e.circles))for(let e of(await i.listCircleMembers(r)))f.add(e.member_did)}}let d=Array.from(s),m=n?Array.from(f):void 0,u=new Set(o??[]),c=new Set,w=new Set;return await Promise.all(d.map(async e=>{let r=await a.getClusterForModel(e);null!=r&&(c.add(r),u.has(e)||w.add(r))})),{modelIDs:d,owners:m,requiredClusterIDs:Array.from(c),missingClusterIDs:Array.from(w)}}
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * Resolve catalog criteria to sync-compatible scopes.
+ *
+ * Takes catalog IDs, resolves their criteria, and returns:
+ * - modelIDs: union of all model filters from all catalogs
+ * - owners: union of all owner filters (explicit + circle members)
+ * - requiredClusterIDs: cluster IDs for all required models
+ * - missingClusterIDs: cluster IDs for models not in knownModelIDs
+ */ export async function resolveCatalogSyncScopes(db, catalogIDs, knownModelIDs) {
+    const [graphStore, p2pStore] = await Promise.all([
+        getGraphStore(db),
+        getP2PStore(db)
+    ]);
+    const allModelIDs = new Set();
+    const allOwners = new Set();
+    let hasOwnerFilter = false;
+    for (const catalogID of catalogIDs){
+        const scope = await graphStore.resolveCatalogScope(catalogID);
+        if (scope.models != null) {
+            for (const m of scope.models){
+                allModelIDs.add(m);
+            }
+        }
+        if (scope.owners != null) {
+            hasOwnerFilter = true;
+            for (const o of scope.owners){
+                allOwners.add(o);
+            }
+        }
+        // Resolve circle-based owners via p2p store
+        const catalog = await graphStore.getCatalog(catalogID);
+        if (catalog != null) {
+            const criteria = catalog.filter_criteria;
+            if (criteria.circles != null && criteria.circles.length > 0) {
+                hasOwnerFilter = true;
+                for (const circleID of criteria.circles){
+                    const members = await p2pStore.listCircleMembers(circleID);
+                    for (const member of members){
+                        allOwners.add(member.member_did);
+                    }
+                }
+            }
+        }
+    }
+    const modelIDs = Array.from(allModelIDs);
+    const owners = hasOwnerFilter ? Array.from(allOwners) : undefined;
+    // Resolve clusters for all models in a single pass
+    const knownSet = new Set(knownModelIDs ?? []);
+    const requiredClusterIDs = new Set();
+    const missingClusterIDs = new Set();
+    await Promise.all(modelIDs.map(async (modelID)=>{
+        const clusterID = await graphStore.getClusterForModel(modelID);
+        if (clusterID != null) {
+            requiredClusterIDs.add(clusterID);
+            if (!knownSet.has(modelID)) {
+                missingClusterIDs.add(clusterID);
+            }
+        }
+    }));
+    return {
+        modelIDs,
+        owners,
+        requiredClusterIDs: Array.from(requiredClusterIDs),
+        missingClusterIDs: Array.from(missingClusterIDs)
+    };
+}

package/lib/sync/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown by the sync handlers when a request is denied before any store
+ * read — for example a forged subject, an unauthorized scope, or a
+ * disallowed direction. Tagged with the protocol-level error code `KB08`
+ * so server-side logging and tests can assert the reason.
+ */
+export declare class SyncAccessDeniedError extends Error {
+    #private;
+    constructor(reason: string, message?: string);
+    get code(): 'KB08';
+    get reason(): string;
+}

package/lib/sync/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Thrown by the sync handlers when a request is denied before any store
+ * read — for example a forged subject, an unauthorized scope, or a
+ * disallowed direction. Tagged with the protocol-level error code `KB08`
+ * so server-side logging and tests can assert the reason.
+ */ export class SyncAccessDeniedError extends Error {
+    #reason;
+    constructor(reason, message){
+        super(message ?? `Sync access denied: ${reason}`);
+        this.name = 'SyncAccessDeniedError';
+        this.#reason = reason;
+    }
+    get code() {
+        return 'KB08';
+    }
+    get reason() {
+        return this.#reason;
+    }
+}