@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/hub/hub-connection.d.ts

@@ -1,96 +0,0 @@
-import { Disposer } from '@enkaku/async';
-import { EventEmitter } from '@enkaku/event';
-import type { StoredMessage } from '@enkaku/hub-protocol';
-import type { Logger } from '@kubun/logger';
-import type { HubConnectionPool } from './connection-pool.js';
-import type { ReceivedHubMessage } from './receive-handler.js';
-export type TunnelMessageStream = AsyncIterable<StoredMessage> & {
-    return(): void;
-};
-export type TunnelMessageStreamParams = {
-    peerDID: string;
-};
-export type SubscriptionHandler = (message: ReceivedHubMessage) => Promise<{
-    ack: boolean;
-}>;
-export type ConnectionLifecycleEvent = {
-    type: 'connected';
-} | {
-    type: 'disconnected';
-    reason?: string;
-} | {
-    type: 'error';
-    error: unknown;
-} | {
-    type: 'reconnecting';
-    attempt: number;
-    delayMs: number;
-};
-type HubConnectionEvents = {
-    lifecycle: ConnectionLifecycleEvent;
-};
-export type HubConnectionParams = {
-    hubURL: string;
-    deviceID: string;
-    pool: HubConnectionPool;
-    logger?: Logger;
-    ackFlushMs?: number;
-    ackFlushMax?: number;
-    backoffBaseMs?: number;
-    backoffMaxMs?: number;
-    backoffJitter?: number;
-};
-export declare class HubConnection extends Disposer {
-    #private;
-    constructor(params: HubConnectionParams);
-    get events(): EventEmitter<HubConnectionEvents>;
-    open(): Promise<void>;
-    subscribe(groupID: string, credential: string, handler: SubscriptionHandler): Promise<void>;
-    unsubscribe(groupID: string): Promise<void>;
-    broadcast(groupID: string, encryptedPayload: string, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Send an opaque tunnel-style message to explicit recipients via
-     * `hub/send`. No `groupID` is attached at the hub level — recipients
-     * receive the message on the tunnel-routing path (see
-     * {@link tunnelMessageStream}). Used by hub-mediated document sync.
-     */
-    send(params: {
-        recipients: Array<string>;
-        payload: Uint8Array;
-        timeoutMs?: number;
-    }): Promise<{
-        sequenceID: string;
-    }>;
-    /**
-     * Run `fn` inside the same per-group mutex used by receive `#dispatch`. This
-     * lets callers (e.g. `GroupChannel.broadcast`) serialize MLS-state-mutating
-     * pipelines with incoming-message handling on the same group, avoiding races
-     * between concurrent send-encrypt and receive-decrypt against shared MLS
-     * group state.
-     *
-     * The gate-await ensures the subscription map is settled before lookup —
-     * i.e. mid-reconnect callers wait for the subscription to be (re)registered
-     * rather than throwing.
-     */
-    runInGroup<T>(groupID: string, fn: () => Promise<T>, opts?: {
-        timeoutMs?: number;
-    }): Promise<T>;
-    /**
-     * Register a per-peer tunnel inbox and return a disposable async iterable
-     * of {@link StoredMessage} values received from that peer over the tunnel
-     * (i.e. direct hub messages with no `groupID`).
-     *
-     * Used by the hub-mediated document sync server adapter (see Q3 of the
-     * hub-mediated document sync plan). The hub's receive-side dispatcher
-     * keys tunnel routing on `senderDID` because hub-level messages cannot
-     * reveal the in-frame `sessionID` (the body is encrypted). P2P pairs
-     * `peerDID` and `sessionID` at session creation, so peer-keying is
-     * sufficient. Concurrent tunnel sessions to the same peer are not
-     * supported and are the caller's responsibility to avoid.
-     */
-    tunnelMessageStream({ peerDID }: TunnelMessageStreamParams): TunnelMessageStream;
-    close(): Promise<void>;
-}
-export {};

package/lib/hub/hub-connection.js

@@ -1 +0,0 @@
-import{Disposer as e}from"@enkaku/async";import{fromB64 as t,toB64 as s}from"@enkaku/codec";import{EventEmitter as n}from"@enkaku/event";import{createMutex as i}from"../util/mutex.js";import{ReconnectingError as r}from"./errors.js";import{AckBatch as o,abortableSleep as h,computeBackoff as a}from"./group-channel.js";import{TunnelInbox as c}from"./tunnel-inbox.js";import{waitForGate as l}from"./wait-for-gate.js";let u=Symbol("disposed");export class HubConnection extends e{#e;#t;#s;#n;#i;#r;#o;#h;#a;#c=null;#l=null;#u=null;#b=null;#p=null;#d=new Map;#f=!1;#g=0;#m=null;#y=new Map;#w;constructor(e){super({dispose:async()=>{await this.#L()}}),this.#e=e.hubURL,this.#t=e.deviceID,this.#s=e.pool,this.#n=e.logger,this.#i=e.ackFlushMs??500,this.#r=e.ackFlushMax??10,this.#o=e.backoffBaseMs??1e3,this.#h=e.backoffMaxMs??6e4,this.#a=e.backoffJitter??.25,this.#w=new n}get events(){return this.#w}async #I(e){try{await this.#w.emit("lifecycle",e)}catch(t){this.#n?.warn("hub-connection lifecycle subscriber threw",{hubURL:this.#e,type:e.type,error:t})}}async open(){if(this.#f)throw Error("HubConnection already opened");try{await this.#k(),this.#f=!0,await this.#I({type:"connected"})}catch(e){if(null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release after open failure failed",{hubURL:this.#e,error:e})}this.#l=null}throw this.#c=null,e}}async #k(){if(null!=this.#l){let e=this.#l;this.#l=null,this.#c=null;try{await this.#s.release(this.#e,e)}catch(e){this.#n?.debug("hub-connection pool release before reconnect failed",{hubURL:this.#e,error:e})}}let{client:e,refID:t}=await this.#s.acquire(this.#e);this.#c=e,this.#l=t;let s=e.createChannel("hub/receive",{param:{},signal:this.signal});this.#u=s,s.catch(()=>{}),this.#b=new o({flushMs:this.#i,flushMax:this.#r,send:async e=>{await s.send({ack:e})},logger:this.#n}),this.#p=this.#R(e).catch(e=>{this.#n?.debug("hub-connection receive task tail error",{hubURL:this.#e,error:e})});let n=[...this.#d.entries()];if(n.length>0){let t=await Promise.allSettled(n.map(async([t,s])=>{await e.request("hub/group/join",{param:{groupID:t,credential:s.credential}})}));for(let e=0;e<t.length;e++){let s=t[e];if("rejected"===s.status){let t=n[e][0];this.#n?.warn("hub-connection rejoin failed",{hubURL:this.#e,groupID:t,error:s.reason})}}}}async subscribe(e,t,s){if(await l(this.#m,void 0),!this.#f||null==this.#c)throw Error("HubConnection not open");if(this.#d.has(e))throw Error(`already subscribed to group ${e}`);await this.#c.request("hub/group/join",{param:{groupID:e,credential:t}}),this.#d.set(e,{credential:t,handler:s,mutex:i()})}async unsubscribe(e){await l(this.#m,void 0);let t=this.#c;if(!this.#f||null==t)throw Error("HubConnection not open");let s=this.#d.get(e);if(null==s)throw Error(`not subscribed to group ${e}`);await s.mutex.run(async()=>{}),await t.request("hub/group/leave",{param:{groupID:e}}),this.#d.delete(e)}async broadcast(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");await this.#c.request("hub/group/send",{param:{groupID:e,payload:t}})}async send(e){if(await l(this.#m,e.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");return{sequenceID:(await this.#c.request("hub/send",{param:{recipients:e.recipients,payload:s(e.payload)}})).sequenceID}}async runInGroup(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f)throw Error("HubConnection not open");let n=this.#d.get(e);if(null==n)throw Error(`not subscribed to group ${e}`);return n.mutex.run(t)}tunnelMessageStream({peerDID:e}){if(this.#y.has(e))throw Error("tunnelMessageStream: peerDID already registered");let t=new c,s={inbox:t};this.#y.set(e,s);let n=!1;return{[Symbol.asyncIterator]:()=>t.iterator(),return:()=>{n||(n=!0,this.#y.get(e)===s&&this.#y.delete(e),t.close())}}}async #R(e){let t=this.#u;if(null==t)return;let s=t.readable.getReader(),n=null;try{for(;!this.signal.aborted;){let t=s.read(),n=e.disposed.then(()=>u),i=await Promise.race([t,n]);if("symbol"==typeof i){this.#n?.debug("hub-connection receive loop observed hub client disposal",{hubURL:this.#e});break}let{done:r,value:o}=i;if(r)break;this.#D(o),this.#g=0}}catch(e){n=e,this.#n?.warn("hub-connection receive loop error",{hubURL:this.#e,error:e})}finally{try{s.releaseLock()}catch{}}if(!this.signal.aborted){let e=n instanceof Error&&n.message?n.message:"receive loop ended";await this.#I({type:"disconnected",reason:e}),this.#U()}}#U(){this.#p=this.#M().catch(e=>{this.#n?.debug("hub-connection reconnect task tail error",{hubURL:this.#e,error:e})})}async #M(){let e=()=>{};this.#m=new Promise(t=>{e=t});try{for(;!this.signal.aborted;){let e=a(this.#g++,this.#o,this.#h,this.#a);this.#n?.debug("hub-connection reconnect scheduled",{hubURL:this.#e,delay:e,attempt:this.#g});try{await h(e,this.signal)}catch{return}await this.#I({type:"reconnecting",attempt:this.#g,delayMs:e});try{this.#b?.dispose(),this.#b=null,this.#u=null,await this.#k(),this.#g=0,await this.#I({type:"connected"});return}catch(e){this.#n?.warn("hub-connection reconnect attempt failed",{hubURL:this.#e,attempt:this.#g,error:e}),await this.#I({type:"error",error:e})}}}finally{this.#m=null,e()}}#D(e){if(null==e.groupID){let s=this.#y.get(e.senderDID);if(null!=s){let n={sequenceID:e.sequenceID,senderDID:e.senderDID,payload:t(e.payload)};s.inbox.push(n),this.#b?.add(e.sequenceID);return}this.#n?.debug("direct message received, no handler",{hubURL:this.#e,sequenceID:e.sequenceID}),this.#b?.add(e.sequenceID);return}let s=this.#d.get(e.groupID);null==s?this.#n?.debug("message for unsubscribed group",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID}):s.mutex.run(()=>s.handler(e)).then(t=>{t.ack&&this.#b?.add(e.sequenceID)}).catch(t=>{this.#n?.warn("hub-connection subscription handler error",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID,error:t})})}async close(){this.#f&&await this.dispose()}async #L(){if(!this.#f)return;let e=this.#b;if(this.#b=null,null!=e){try{await e.flush()}catch(e){this.#n?.debug("hub-connection ack flush during close failed",{hubURL:this.#e,error:e})}e.dispose()}try{this.#u?.close()}catch{}try{await this.#p}catch{}let t=[...this.#d.values()].map(e=>e.mutex.run(async()=>{}).catch(()=>{}));if(await Promise.allSettled(t),null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release during close failed",{hubURL:this.#e,error:e})}this.#l=null}for(let e of(this.#c=null,this.#u=null,this.#p=null,this.#d.clear(),this.#y.values()))e.inbox.close();this.#y.clear(),this.#f=!1}}

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

@@ -1,51 +0,0 @@
-import type { Logger } from '@kubun/logger';
-import { type BroadcastService, type ReceiveBroadcastResult } from '../groups/broadcast-service.js';
-/**
- * Shape of a message pushed by `hub/receive`. Matches `@enkaku/hub-protocol`
- * server-to-client push payload.
- */
-export type ReceivedHubMessage = {
-    sequenceID: string;
-    senderDID: string;
-    groupID?: string;
-    /** base64-encoded encrypted MLS application message */
-    payload: string;
-};
-export type HandleReceivedMessageParams = {
-    groupID: string;
-    message: ReceivedHubMessage;
-    broadcastService: BroadcastService;
-    logger?: Logger;
-};
-/**
- * Classification of a single received message's processing result. Drives both
- * the ack decision and the epoch-stale health signal (see `EpochStaleDetector`):
- * - `applied` — decrypted/applied cleanly; the device is at the current epoch.
- * - `decrypt-failed` — could not derive the key for the current epoch.
- * - `commit-out-of-order` — a Commit ahead of the local epoch (gap in stream).
- * - `apply-failed` — decrypted but failed to apply to the local DB (transient).
- * - `error` — unexpected failure.
- * - `skipped` — not for this group; no processing attempted.
- * - `control` — a rejoin control frame (request/groupinfo); processed cleanly
- *   but NOT a health indicator (must not reset epoch-stale tracking).
- */
-export type ReceiveOutcome = 'applied' | 'decrypt-failed' | 'commit-out-of-order' | 'apply-failed' | 'error' | 'skipped' | 'control';
-export type HandleReceivedMessageResult = {
-    ack: boolean;
-    outcome: ReceiveOutcome;
-    sequenceID: string;
-    /** The processed result, present on success — lets the channel route rejoin
-     *  control frames to the responder/requester. */
-    result?: ReceiveBroadcastResult;
-};
-/**
- * Apply a single hub-received message for a group.
- *
- * Returns `{ ack: true }` when the message has been processed to a state where
- * redelivery serves no purpose (applied successfully, or decrypt failed with
- * no recovery path). Returns `{ ack: false }` when the hub should redeliver
- * (transient apply failure or unexpected error). Skips with `{ ack: false }`
- * on groupID mismatch so the message stays queued for whichever recipient it
- * was intended for. The `outcome` classifies the result for health tracking.
- */
-export declare function handleReceivedMessage(params: HandleReceivedMessageParams): Promise<HandleReceivedMessageResult>;

package/lib/hub/receive-handler.js

@@ -1 +0,0 @@
-import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,CommitOutOfOrderError as o,DecryptError as a,MalformedControlError as c}from"../groups/broadcast-service.js";export async function handleReceivedMessage(i){let t,{groupID:n,message:s,broadcastService:p,logger:u}=i,d=s.sequenceID;if(s.groupID!==n)return u?.debug("hub message groupID mismatch, skipping",{groupID:n,messageGroupID:s.groupID,sequenceID:d}),{ack:!1,outcome:"skipped",sequenceID:d};let l=e(s.payload);try{t=await p.processReceived({groupID:n,encrypted:l})}catch(e){if(e instanceof c)return u?.debug("malformed control frame, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"control",sequenceID:d};if(e instanceof a)return u?.debug("decrypt failed, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"decrypt-failed",sequenceID:d};if(e instanceof o)return u?.debug("mls commit out of order, will redeliver after gap fills",{groupID:n,sequenceID:d,messageEpoch:e.messageEpoch.toString(),handleEpoch:e.handleEpoch.toString()}),{ack:!1,outcome:"commit-out-of-order",sequenceID:d};if(e instanceof r)return u?.error("broadcast apply failed, will redeliver",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"apply-failed",sequenceID:d};return u?.error("unexpected error processing hub message",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"error",sequenceID:d}}return{ack:!0,outcome:"rejoin-request"===t.kind||"rejoin-groupinfo"===t.kind?"control":"applied",sequenceID:d,result:t}}

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

@@ -1,78 +0,0 @@
-import { type GroupHandle, type MemberCredential } from '@enkaku/group';
-import type { OwnIdentity } from '@enkaku/token';
-import type { Logger } from '@kubun/logger';
-import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
-import type { RejoinResult } from '../types.js';
-export type JoinExternalResult = {
-    /** Framed MLSMessage(Commit) bytes to broadcast to existing members. */
-    commitMessage: Uint8Array;
-    /** Optimistic post-commit handle (NOT yet persisted). */
-    pendingHandle: GroupHandle;
-};
-export type RejoinManagerParams = {
-    groupID: string;
-    identity: OwnIdentity;
-    /** Read the stale handle's cached MemberCredential (reused for the rejoin). */
-    readCredential: () => Promise<MemberCredential>;
-    /** Fresh correlation id per request (incl. retries). */
-    genRequestID: () => string;
-    /** Broadcast a `rejoin-request` on the group channel. */
-    sendRequest: (requestID: string) => Promise<void>;
-    /** Broadcast the resync Commit (`mls` frame) to existing members. */
-    sendCommit: (commitBytes: Uint8Array) => Promise<void>;
-    /** Atomically swap the cached handle for the confirmed one (registry). */
-    replaceHandle: (handle: GroupHandle) => Promise<void>;
-    monitor: GroupHealthMonitor;
-    /**
-     * Test seam: defaults to `@enkaku/group` `joinGroupExternal({resync:true})`
-     * built from `identity` + `readCredential`. Override to skip real MLS.
-     */
-    joinExternal?: (groupInfo: Uint8Array) => Promise<JoinExternalResult>;
-    /** Test seam: defaults to `@enkaku/group` `inspectGroupInfo`. */
-    inspectGroupInfo?: (groupInfo: Uint8Array) => {
-        epoch: bigint;
-        treeHash: Uint8Array;
-    };
-    requestTimeoutMs?: number;
-    confirmTimeoutMs?: number;
-    /** Delay between the candidate-head probe and its re-probe (settle window). */
-    confirmSettleMs?: number;
-    maxAttempts?: number;
-    backoffMs?: (attempt: number) => number;
-    logger?: Logger;
-};
-/**
- * Drives a stale device's MLS epoch recovery for one group: per attempt,
- * request GroupInfo → `joinGroupExternal({resync:true})` → broadcast the resync
- * Commit → confirm → `replaceHandle`.
- *
- * Confirm is a tree-hash compare against the current head, because the hub never
- * echoes the sender's own Commit. Three guards keep it reliable under concurrent
- * rejoins (a resync Commit is canonical only for an instant):
- * - behind-responder filter: a probe reply below our epoch can't confirm us.
- * - chase-the-head: a reply above our epoch means we lost the race; re-join the
- *   newer GroupInfo next attempt (`{resync:true}` rebuilds the tree — no replay).
- * - settle re-probe: re-probe after a delay and require the head still ours
- *   before swapping. Shrinks (not closes) the transient-head window — a Commit
- *   landing in the gap leaves us one epoch behind, which detect→rejoin catches.
- *   A fall-behind, never a silent fork; a wrong `recovered` is unreachable.
- *
- * Retries capped; exhaustion → `recovery-failed`.
- */
-export declare class RejoinManager {
-    #private;
-    constructor(params: RejoinManagerParams);
-    get inFlight(): boolean;
-    /**
-     * Route a received `rejoin-groupinfo`: resolve the matching in-flight waiter.
-     * Unknown `requestID`s (peers' requests, stale responses) are ignored.
-     */
-    onGroupInfo(requestID: string, groupInfo: Uint8Array): void;
-    /** Run the recovery flow. Idempotent: a concurrent call returns the loser early. */
-    rejoin(): Promise<RejoinResult>;
-    /**
-     * Stop a running rejoin and release timers. Idempotent; the loop checks
-     * `#disposed` between attempts, pending waiters resolve `null`. On channel close.
-     */
-    dispose(): void;
-}

package/lib/hub/rejoin-manager.js

@@ -1 +0,0 @@
-import{inspectGroupInfo as e,joinGroupExternal as t}from"@enkaku/group";import{bytesEqual as r,sleep as i,unref as s}from"../utils.js";export class RejoinManager{#e;#t;#r;#i;#s;#o;#n;#a;#l;#u;#h;#c;#p;#m;#d=new Map;#f=!1;#g=!1;constructor(r){this.#e=r.groupID,this.#t=r.genRequestID,this.#r=r.sendRequest,this.#i=r.sendCommit,this.#s=r.replaceHandle,this.#o=r.monitor,this.#n=r.joinExternal??(async e=>{let i=await r.readCredential(),{commitMessage:s,group:o}=await t({identity:r.identity,groupInfo:e,credential:i,resync:!0});return{commitMessage:s,pendingHandle:o}}),this.#a=r.inspectGroupInfo??e,this.#l=r.requestTimeoutMs??5e3,this.#u=r.confirmTimeoutMs??5e3,this.#h=r.confirmSettleMs??300,this.#c=r.maxAttempts??8,this.#p=r.backoffMs??o,this.#m=r.logger}get inFlight(){return this.#f}onGroupInfo(e,t){let r=this.#d.get(e);null!=r&&(this.#d.delete(e),r.resolve(t))}async rejoin(){if(this.#f)return{status:"recovery-failed"};this.#f=!0,this.#o.markRecovering(this.#e);try{for(let e=0;e<this.#c&&!this.#g&&(await i(this.#p(e)),!this.#g);e++){let e=await this.#w();if("recovered"===e)return this.#o.markRecovered(this.#e),{status:"recovered"}}return this.#o.markRecoveryFailed(this.#e),{status:"recovery-failed"}}finally{this.#f=!1}}async #w(){let e,t=await this.#I(this.#l);if(null==t)return"retry";try{e=await this.#n(t)}catch(e){return this.#m?.warn("rejoin: joinGroupExternal failed",{groupID:this.#e,error:e}),"retry"}let{commitMessage:s,pendingHandle:o}=e,n=o.epoch,a=o.treeHash;try{await this.#i(s)}catch(e){return this.#m?.warn("rejoin: resync Commit send failed",{groupID:this.#e,error:e}),"retry"}let l=await this.#y(n);if(null==l||!(l.epoch===n&&r(l.treeHash,a)))return"retry";await i(this.#h);let u=await this.#y(n);return null==u?"retry":u.epoch===n&&r(u.treeHash,a)?(await this.#s(o),"recovered"):"retry"}async #y(e){let t,r=await this.#I(this.#u);if(null==r)return null;try{t=this.#a(r)}catch(e){return this.#m?.warn("rejoin: confirm GroupInfo inspect failed",{groupID:this.#e,error:e}),null}return t.epoch<e?null:t}async #I(e){let t=this.#t(),r=this.#M(t,e);try{await this.#r(t)}catch(e){return this.#D(t),this.#m?.warn("rejoin: request send failed",{groupID:this.#e,error:e}),null}return r}#M(e,t){return new Promise(r=>{let i=setTimeout(()=>{this.#d.delete(e),r(null)},t);s(i),this.#d.set(e,{resolve:e=>{clearTimeout(i),r(e)},cancel:()=>{clearTimeout(i),r(null)}})})}#D(e){this.#d.delete(e)}dispose(){for(let e of(this.#g=!0,this.#d.values()))e.cancel();this.#d.clear()}}function o(e){return Math.floor(Math.random()*Math.min(500*2**(e-1),5e3))}

package/lib/hub/rejoin-responder.d.ts

@@ -1,32 +0,0 @@
-import type { Logger } from '@kubun/logger';
-export type RejoinResponderParams = {
-    groupID: string;
-    /** Produce a fresh GroupInfo for this group (current MLS handle). */
-    exportGroupInfo: () => Promise<Uint8Array>;
-    /** Broadcast a `rejoin-groupinfo` reply to the group channel. */
-    sendGroupInfo: (requestID: string, groupInfo: Uint8Array) => Promise<void>;
-    /** Jitter delay (ms) before replying. Defaults to a random 0..250ms. */
-    nextJitterMs?: () => number;
-    /** How long a `requestID` stays suppressed after being answered. */
-    suppressTTLMs?: number;
-    logger?: Logger;
-};
-/**
- * Answers `rejoin-request`s with a fresh GroupInfo. Every member could reply, so
- * jitter (random pre-reply delay) + suppression (cancel on seeing a peer's reply
- * for the same `requestID`) collapse the storm to ~1 reply. Keyed on `requestID`
- * (fresh per attempt); suppression entries TTL out to bound memory.
- *
- * Suppression collapses only duplicates of one `requestID`, so distinct
- * `requestID`s still draw one reply each — an amplification. A per-window reply
- * cap is tracked in `docs/agents/plans/backlog/rejoin-frame-authentication.md`.
- */
-export declare class RejoinResponder {
-    #private;
-    constructor(params: RejoinResponderParams);
-    /** Handle an inbound `rejoin-request`: schedule a jittered, suppressible reply. */
-    onRejoinRequest(requestID: string): void;
-    /** Handle an observed `rejoin-groupinfo` (own or peer's): suppress this request. */
-    onRejoinGroupInfoSeen(requestID: string): void;
-    dispose(): void;
-}

package/lib/hub/rejoin-responder.js

@@ -1 +0,0 @@
-import{unref as e}from"../utils.js";export class RejoinResponder{#e;#s;#t;#r;#p;#o;#i=new Map;#n=new Map;constructor(e){this.#e=e.groupID,this.#s=e.exportGroupInfo,this.#t=e.sendGroupInfo,this.#r=e.nextJitterMs??(()=>Math.floor(250*Math.random())),this.#p=e.suppressTTLMs??5e3,this.#o=e.logger}onRejoinRequest(s){if(this.#n.has(s)||this.#i.has(s))return;let t=setTimeout(()=>{this.#i.delete(s),this.#u(s)},this.#r());e(t),this.#i.set(s,t)}onRejoinGroupInfoSeen(e){let s=this.#i.get(e);null!=s&&(clearTimeout(s),this.#i.delete(e)),this.#h(e)}dispose(){for(let e of this.#i.values())clearTimeout(e);for(let e of(this.#i.clear(),this.#n.values()))clearTimeout(e);this.#n.clear()}async #u(e){if(!this.#n.has(e)){this.#h(e);try{let s=await this.#s();await this.#t(e,s)}catch(s){this.#o?.warn("rejoin responder failed to reply",{groupID:this.#e,requestID:e,error:s})}}}#h(s){let t=this.#n.get(s);null!=t&&clearTimeout(t);let r=setTimeout(()=>{this.#n.delete(s)},this.#p);e(r),this.#n.set(s,r)}}

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

@@ -1,142 +0,0 @@
-import type { Client } from '@enkaku/client';
-import { EventEmitter } from '@enkaku/event';
-import type { HubProtocol } from '@enkaku/hub-protocol';
-import type { OwnIdentity } from '@enkaku/token';
-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 { GroupHealthMonitor } from '../groups/group-health-monitor.js';
-import type { RejoinResult } from '../types.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;
-    /** When provided, receive outcomes drive epoch-stale health detection. */
-    monitor?: GroupHealthMonitor;
-    /** Device identity — enables the rejoin flow (needs `joinGroupExternal`). */
-    identity?: OwnIdentity;
-    /** Fresh correlation ids for rejoin requests. */
-    getRandomID?: () => string;
-    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;
-    get 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>;
-    /**
-     * Run stale-device MLS epoch recovery for an active group via its channel.
-     * Throws if the group is not active; returns `recovery-failed` if the rejoin
-     * flow is unavailable (no monitor/identity wired).
-     */
-    rejoinGroup(groupID: string): Promise<RejoinResult>;
-    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 o}from"./hub-connection.js";export class HubRelayManager{#e;#t;#s;#o;#r;#i;#a;#n;#l;#c;#u;#h;#g;#p;#d;#b;#f=new Map;#m=new Map;#M=new Map;#v=new Map;#w;get relayEvents(){return this.#w}constructor(r){this.#e=r.p2pStore,this.#t=r.broadcastService,this.#s=r.deviceID,this.#r=r.logger,this.#i=r.ackFlushMs??500,this.#a=r.ackFlushMax??10,this.#n=r.backoffBaseMs??1e3,this.#l=r.backoffMaxMs??6e4,this.#c=r.backoffJitter??.25,this.#u=r.broadcastTimeoutMs,this.#h=r.monitor,this.#g=r.identity,this.#p=r.getRandomID;let i=r.p2pStore;this.#o=new t({createHubClient:r.createHubClient,logger:r.logger,onServerDIDObserved:r.onServerDIDObserved,resolvePinnedDID:async e=>{let t=await i.getHubByURL(e);return t?.server_did??null}}),this.#d=r.createGroupChannel??(e=>new s(e)),this.#b=r.createHubConnection??(e=>new o(e)),this.#w=new e}async #y(e){let t=this.#f.get(e);if(null!=t)return t;let s=this.#b({hubURL:e,deviceID:this.#s,pool:this.#o,logger:this.#r,ackFlushMs:this.#i,ackFlushMax:this.#a,backoffBaseMs:this.#n,backoffMaxMs:this.#l,backoffJitter:this.#c});try{await s.open()}catch(e){try{await s.dispose()}catch{}throw e}let o=s.events.on("lifecycle",async t=>{let s=Object.freeze([...this.#M.entries()].filter(([,t])=>t===e).map(([e])=>e));await this.#w.emit("relay",{...t,hubURL:e,groupIDs:s})});return this.#v.set(e,o),this.#f.set(e,s),s}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((t,s)=>{"rejected"===t.status&&this.#r?.error("addGroup failed during start",{groupID:e[s],error:t.reason})})}async addGroup(e){if(this.#m.has(e))return void this.#r?.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.#r?.warn("group has no hub bindings, skipping",{groupID:e}):(t.length>1&&this.#r?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t.map(e=>e.url)}),await this.#k(e,t[0].url))}async #k(e,t){let s=await this.#y(t),o=this.#d({groupID:e,deviceID:this.#s,hubConnection:s,broadcastService:this.#t,p2pStore:this.#e,logger:this.#r,monitor:this.#h,identity:this.#g,getRandomID:this.#p});await o.open(),this.#m.set(e,o),this.#M.set(e,t)}async addBinding(e,t){let s=this.#M.get(e);null!=s?s===t?this.#r?.debug("binding already active",{groupID:e,hubURL:t}):this.#r?.warn("multi-hub not yet supported, ignoring extra binding",{groupID:e,activeHubURL:s,newHubURL:t}):await this.#k(e,t)}async removeBinding(e,t){this.#M.get(e)!==t?this.#r?.debug("binding not active, ignoring removal",{groupID:e,hubURL:t}):await this.removeGroup(e)}async removeGroup(e){let t=this.#m.get(e);null!=t&&(await t.close(),this.#m.delete(e),this.#M.delete(e))}async rejoinGroup(e){let t=this.#m.get(e);if(null==t)throw Error(`Group ${e} is not active in HubRelayManager`);return await t.rejoinGroup()}async broadcast(e,t,s){let o=this.#m.get(e);if(null==o)throw Error(`Group ${e} is not active in HubRelayManager`);let r=s?.timeoutMs??this.#u;await o.broadcast(t,{timeoutMs:r})}async sendCommit(e,t,s){let o=this.#m.get(e);if(null==o)throw Error(`Group ${e} is not active in HubRelayManager`);let r=s?.timeoutMs??this.#u;await o.sendCommit(t,{timeoutMs:r})}async stop(){for(let e of this.#v.values())e();this.#v.clear();let e=[...this.#m.values()];this.#m.clear(),this.#M.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#r?.warn("GroupChannel close failed",{error:e.reason})});let t=[...this.#f.values()];this.#f.clear(),(await Promise.allSettled(t.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#r?.warn("HubConnection close failed",{error:e.reason})}),await this.#o.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)}}