@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/hub/relay-manager.d.ts

@@ -1,127 +0,0 @@
-import type { Client } from '@enkaku/client';
-import { EventEmitter } from '@enkaku/event';
-import type { HubProtocol } from '@enkaku/hub-protocol';
-import type { Logger } from '@kubun/logger';
-import type { P2PStoreAPI } from '@kubun/store-p2p';
-import type { GroupBroadcastMessage } from '../groups/broadcast.js';
-import type { BroadcastService } from '../groups/broadcast-service.js';
-import { type OnServerDIDObserved } from './connection-pool.js';
-import type { ServerDIDMismatchObserver, ServerDIDObserver } from './did-observing-transport.js';
-import { GroupChannel, type GroupChannelParams } from './group-channel.js';
-import { HubConnection, type HubConnectionParams } from './hub-connection.js';
-export type CreateHubClientOptions = {
-    /**
-     * Per-call observer fired once when the first signed response arrives. Set
-     * by `HubConnectionPool` so the pool can route the observed server DID
-     * through its `onServerDIDObserved` handler with the hub URL bound. Factories
-     * that don't honour this opt simply skip TOFU capture for pool-spawned
-     * clients.
-     */
-    onServerDID?: ServerDIDObserver;
-    /**
-     * Pinned `server_did` resolved by the pool from the local hub row at spawn
-     * time. When set, the underlying `DIDObservingTransport` enforces it: a
-     * non-matching first response raises `HubServerDIDMismatchError` and no
-     * message is delivered to the inner Client (hard-fail path). When unset,
-     * the wrapper falls back to TOFU capture via `onServerDID`.
-     */
-    expectedServerDID?: string;
-    /**
-     * Side-channel notifier fired when a pinned-DID mismatch is detected. Lets
-     * the pool log + evict on top of the typed error that propagates through
-     * the read loop.
-     */
-    onMismatch?: ServerDIDMismatchObserver;
-};
-export type CreateHubClient = (hubURL: string, opts?: CreateHubClientOptions) => Promise<Client<HubProtocol>>;
-export type CreateGroupChannel = (params: GroupChannelParams) => GroupChannel;
-export type CreateHubConnection = (params: HubConnectionParams) => HubConnection;
-export type RelayEvent = {
-    type: 'connected';
-    hubURL: string;
-    groupIDs: Array<string>;
-} | {
-    type: 'disconnected';
-    hubURL: string;
-    groupIDs: Array<string>;
-    reason?: string;
-} | {
-    type: 'error';
-    hubURL: string;
-    groupIDs: Array<string>;
-    error: unknown;
-} | {
-    type: 'reconnecting';
-    hubURL: string;
-    groupIDs: Array<string>;
-    attempt: number;
-    delayMs: number;
-};
-type RelayManagerEvents = {
-    relay: RelayEvent;
-};
-export type HubRelayManagerParams = {
-    p2pStore: P2PStoreAPI;
-    broadcastService: BroadcastService;
-    deviceID: string;
-    createHubClient: CreateHubClient;
-    logger?: Logger;
-    ackFlushMs?: number;
-    ackFlushMax?: number;
-    backoffBaseMs?: number;
-    backoffMaxMs?: number;
-    backoffJitter?: number;
-    broadcastTimeoutMs?: number;
-    createGroupChannel?: CreateGroupChannel;
-    createHubConnection?: CreateHubConnection;
-    /**
-     * Forwarded to the underlying `HubConnectionPool`. Fired with the observed
-     * `serverDID` after the first signed response from a freshly-spawned client.
-     * Used by the hub manager to apply the TOFU capture conflict matrix (the
-     * `null → DID-A` upgrade). Errors are caught and logged by the pool;
-     * pinned-mismatch enforcement is a separate path inside the wrapper.
-     */
-    onServerDIDObserved?: OnServerDIDObserved;
-};
-export declare class HubRelayManager {
-    #private;
-    readonly relayEvents: EventEmitter<RelayManagerEvents>;
-    constructor(params: HubRelayManagerParams);
-    /**
-     * Open channels for each group in parallel. Per-group failures are logged
-     * and swallowed: this method never rejects, so a single bad group does not
-     * block the others from starting. Callers who need per-group readiness
-     * signals must check `addGroup` / `broadcast` results individually.
-     */
-    start(groupIDs: Array<string>): Promise<void>;
-    addGroup(groupID: string): Promise<void>;
-    /**
-     * Post-join binding-add hook. Single-hub regime — when the group already
-     * has an active channel:
-     *   - same hubURL → debug log, no-op (idempotent re-bind);
-     *   - different hubURL → warn, no-op (extra binding deferred until
-     *     multi-hub support lands).
-     * When the group has no active channel yet (e.g. binding was created
-     * before relay setup ran), open one for the supplied hub.
-     */
-    addBinding(groupID: string, hubURL: string): Promise<void>;
-    /**
-     * Post-join binding-remove hook. No-op when the unbound hub is not the
-     * group's active hub (single-hub regime: unbinding a non-active hub leaves
-     * the channel intact). When it matches, behaves like `removeGroup`.
-     */
-    removeBinding(groupID: string, hubURL: string): Promise<void>;
-    removeGroup(groupID: string): Promise<void>;
-    broadcast(groupID: string, message: GroupBroadcastMessage, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Fan out a pre-produced MLS handshake Commit to a group's existing members
-     * via its active channel. Mirrors {@link broadcast}.
-     */
-    sendCommit(groupID: string, commitBytes: Uint8Array, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-    stop(): Promise<void>;
-}
-export {};

package/lib/hub/relay-manager.js

@@ -1 +0,0 @@
-import{EventEmitter as e}from"@enkaku/event";import{HubConnectionPool as t}from"./connection-pool.js";import{GroupChannel as s}from"./group-channel.js";import{HubConnection as r}from"./hub-connection.js";export class HubRelayManager{#e;#t;#s;#r;#o;#a;#i;#n;#l;#c;#u;#h;#p;#g=new Map;#d=new Map;#b=new Map;#f=new Map;relayEvents;constructor(o){this.#e=o.p2pStore,this.#t=o.broadcastService,this.#s=o.deviceID,this.#o=o.logger,this.#a=o.ackFlushMs??500,this.#i=o.ackFlushMax??10,this.#n=o.backoffBaseMs??1e3,this.#l=o.backoffMaxMs??6e4,this.#c=o.backoffJitter??.25,this.#u=o.broadcastTimeoutMs;let a=o.p2pStore;this.#r=new t({createHubClient:o.createHubClient,logger:o.logger,onServerDIDObserved:o.onServerDIDObserved,resolvePinnedDID:async e=>{let t=await a.getHubByURL(e);return t?.server_did??null}}),this.#h=o.createGroupChannel??(e=>new s(e)),this.#p=o.createHubConnection??(e=>new r(e)),this.relayEvents=new e}async #M(e){let t=this.#g.get(e);if(null!=t)return t;let s=this.#p({hubURL:e,deviceID:this.#s,pool:this.#r,logger:this.#o,ackFlushMs:this.#a,ackFlushMax:this.#i,backoffBaseMs:this.#n,backoffMaxMs:this.#l,backoffJitter:this.#c});try{await s.open()}catch(e){try{await s.dispose()}catch{}throw e}let r=s.events.on("lifecycle",async t=>{let s=Object.freeze([...this.#b.entries()].filter(([,t])=>t===e).map(([e])=>e));await this.relayEvents.emit("relay",{...t,hubURL:e,groupIDs:s})});return this.#f.set(e,r),this.#g.set(e,s),s}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((t,s)=>{"rejected"===t.status&&this.#o?.error("addGroup failed during start",{groupID:e[s],error:t.reason})})}async addGroup(e){if(this.#d.has(e))return void this.#o?.debug("group already added",{groupID:e});if(null==await this.#e.getGroup(e))throw Error(`Group ${e} not found`);let t=await this.#e.listHubsByGroupID(e);0===t.length?this.#o?.warn("group has no hub bindings, skipping",{groupID:e}):(t.length>1&&this.#o?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t.map(e=>e.url)}),await this.#m(e,t[0].url))}async #m(e,t){let s=await this.#M(t),r=this.#h({groupID:e,deviceID:this.#s,hubConnection:s,broadcastService:this.#t,p2pStore:this.#e,logger:this.#o});await r.open(),this.#d.set(e,r),this.#b.set(e,t)}async addBinding(e,t){let s=this.#b.get(e);null!=s?s===t?this.#o?.debug("binding already active",{groupID:e,hubURL:t}):this.#o?.warn("multi-hub not yet supported, ignoring extra binding",{groupID:e,activeHubURL:s,newHubURL:t}):await this.#m(e,t)}async removeBinding(e,t){this.#b.get(e)!==t?this.#o?.debug("binding not active, ignoring removal",{groupID:e,hubURL:t}):await this.removeGroup(e)}async removeGroup(e){let t=this.#d.get(e);null!=t&&(await t.close(),this.#d.delete(e),this.#b.delete(e))}async broadcast(e,t,s){let r=this.#d.get(e);if(null==r)throw Error(`Group ${e} is not active in HubRelayManager`);let o=s?.timeoutMs??this.#u;await r.broadcast(t,{timeoutMs:o})}async sendCommit(e,t,s){let r=this.#d.get(e);if(null==r)throw Error(`Group ${e} is not active in HubRelayManager`);let o=s?.timeoutMs??this.#u;await r.sendCommit(t,{timeoutMs:o})}async stop(){for(let e of this.#f.values())e();this.#f.clear();let e=[...this.#d.values()];this.#d.clear(),this.#b.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("GroupChannel close failed",{error:e.reason})});let t=[...this.#g.values()];this.#g.clear(),(await Promise.allSettled(t.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("HubConnection close failed",{error:e.reason})}),await this.#r.disposeAll()}}

package/lib/hub/send-handler.d.ts

@@ -1,40 +0,0 @@
-import type { Logger } from '@kubun/logger';
-import type { GroupBroadcastMessage } from '../groups/broadcast.js';
-import type { BroadcastService } from '../groups/broadcast-service.js';
-export type HandleSendBroadcastParams = {
-    groupID: string;
-    message: GroupBroadcastMessage;
-    broadcastService: BroadcastService;
-    /**
-     * Wire-send callback. Receives the groupID and the base64-encoded encrypted
-     * MLS application message, and is expected to fan it out via the underlying
-     * hub transport (e.g. `HubConnection.broadcast`). Decoupling from the hub
-     * client lets callers serialize the send through a per-group mutex shared
-     * with the receive path.
-     */
-    send: (groupID: string, payloadB64: string) => Promise<void>;
-    logger?: Logger;
-};
-/**
- * Encrypt + send a broadcast for a group. MLS state persistence is handled
- * by the registry inside `BroadcastService.prepareSend`. Wedge protection
- * (failed send → no advance of persisted state) is preserved because send
- * runs INSIDE the registry's per-group lock and a throw skips persist.
- */
-export declare function handleSendBroadcast(params: HandleSendBroadcastParams): Promise<void>;
-export type HandleSendCommitParams = {
-    groupID: string;
-    /** Framed MLSMessage(Commit) bytes from the committer's `GroupManager` call. */
-    commitBytes: Uint8Array;
-    broadcastService: BroadcastService;
-    /** Same wire-send callback as {@link HandleSendBroadcastParams.send}. */
-    send: (groupID: string, payloadB64: string) => Promise<void>;
-    logger?: Logger;
-};
-/**
- * Fan out a pre-produced MLS handshake Commit to a group's existing members.
- * Unlike {@link handleSendBroadcast} this does not encrypt — the Commit is
- * already a self-protected `PrivateMessage`; `prepareSendCommit` just tags it
- * `mls` on the wire.
- */
-export declare function handleSendCommit(params: HandleSendCommitParams): Promise<void>;

package/lib/hub/send-handler.js

@@ -1 +0,0 @@
-import{toB64 as r}from"@enkaku/codec";export async function handleSendBroadcast(e){let{groupID:o,message:t,broadcastService:a,send:n,logger:d}=e;try{await a.prepareSend({groupID:o,message:t,send:e=>n(o,r(e))})}catch(r){throw d?.error("hub/group/send failed",{groupID:o,error:r}),r}}export async function handleSendCommit(e){let{groupID:o,commitBytes:t,broadcastService:a,send:n,logger:d}=e;try{await a.prepareSendCommit({groupID:o,commitBytes:t,send:e=>n(o,r(e))})}catch(r){throw d?.error("hub/group/send (mls commit) failed",{groupID:o,error:r}),r}}

package/lib/hub/tunnel-inbox.d.ts

@@ -1,20 +0,0 @@
-import type { StoredMessage } from '@enkaku/hub-protocol';
-/**
- * FIFO queue used by `HubConnection.tunnelMessageStream` to deliver synthetic /
- * forwarded `StoredMessage` values to tunnel transports. Callers `push` messages;
- * each consumer drains via an `AsyncIterator` returned from
- * {@link TunnelInbox.iterator}. Disposal is idempotent: once `close` runs,
- * subsequent pushes are dropped and pending iteration resolves to `done`.
- *
- * Multiple sequential iterators are supported (one consumer at a time, but
- * iterators may be created and returned across the inbox's lifetime). Each
- * iterator tracks its own pending waiter so `iterator.return()` drains only
- * that iterator's waiter — leaving queued messages and other consumers'
- * waiters intact for future iterators.
- */
-export declare class TunnelInbox {
-    #private;
-    push(message: StoredMessage): void;
-    close(): void;
-    iterator(onReturn?: () => void): AsyncIterator<StoredMessage>;
-}

package/lib/hub/tunnel-inbox.js

@@ -1 +0,0 @@
-export class TunnelInbox{#e=[];#s=[];#t=!1;push(e){if(this.#t)return;let s=this.#s.shift();null!=s?s.resolve({value:e,done:!1}):this.#e.push(e)}close(){if(!this.#t)for(this.#t=!0;this.#s.length>0;){let e=this.#s.shift();e?.resolve({value:void 0,done:!0})}}iterator(e){let s=!1,t=new Set,i=()=>{if(!s){for(let e of(s=!0,t)){let s=this.#s.indexOf(e);s>=0&&this.#s.splice(s,1),e.resolve({value:void 0,done:!0})}t.clear(),e?.()}};return{next:()=>{let e;return s?Promise.resolve({value:void 0,done:!0}):this.#e.length>0?Promise.resolve({value:this.#e.shift(),done:!1}):this.#t?(i(),Promise.resolve({value:void 0,done:!0})):new Promise(s=>{e={resolve:s},t.add(e),this.#s.push(e)}).then(s=>(null!=e&&t.delete(e),!0===s.done&&i(),s))},return:()=>(i(),Promise.resolve({value:void 0,done:!0}))}}}

package/lib/hub/wait-for-gate.d.ts

@@ -1,14 +0,0 @@
-/**
- * Wait for a reconnect gate (or similar boolean-style gate) to clear, with an
- * optional timeout. If `gate` is null the call returns immediately without
- * allocating any timer or signal — this is the hot path while the connection
- * is healthy. If `timeoutMs` is undefined we simply await the gate without
- * arming a timer (callers with no timeout can also omit `onTimeout` to skip
- * the closure allocation). Both set: race the gate against
- * `AbortSignal.timeout`; the first to settle wins.
- *
- * `onTimeout` is invoked lazily — only when the timeout actually fires — so
- * callers can capture mutable state (e.g. current reconnect attempt) at the
- * moment of failure rather than at call time.
- */
-export declare function waitForGate(gate: Promise<void> | null, timeoutMs: number | undefined, onTimeout?: () => Error): Promise<void>;

package/lib/hub/wait-for-gate.js

@@ -1 +0,0 @@
-export async function waitForGate(e,t,r){if(null==e)return;if(null==t)return void await e;if(null==r)throw Error("waitForGate: onTimeout required when timeoutMs is set");let i=AbortSignal.timeout(t),n=null,o=new Promise((e,t)=>{i.aborted?t(r()):(n=()=>{t(r())},i.addEventListener("abort",n,{once:!0}))});try{await Promise.race([e,o])}finally{null!=n&&i.removeEventListener("abort",n)}}