@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/group-peer-manager.d.ts

@@ -0,0 +1,301 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import type { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { GraphStoreAPI } from '@kubun/store-graph';
+import { type GroupPeer, type LaneResult, type PendingCommit } from '@kumiai/rpc';
+import type { Runtime } from '@sozai/runtime';
+import type { CreateHubClient } from '../hub/http-client.js';
+import { type DeviceHub, type ReconnectingDeviceHub } from '../hub/hub-like.js';
+import type { SyncProtocol } from '../protocol.js';
+import type { ForwardingConfig } from '../sync/forwarder.js';
+import type { LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult, StoreUnreadableMode } from '../types.js';
+import type { GroupBroadcastMessage } from './broadcast.js';
+import { type SettleLostControlRequestDeps } from './commit-adoption.js';
+import type { P2PEventEmitter } from './events.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+import { type GroupProtocols } from './group-protocols.js';
+import { type PeerPresence } from './peer-presence.js';
+/**
+ * Rebuild a fresh `ledger` commit carrying the given signed tokens, to re-drive
+ * a lost one under its original request id.
+ *
+ * A narrow capability, NOT the whole group manager: the lane may only ask for
+ * exactly this — a build closure over surviving ledger tokens — so it stays a
+ * consumer of the ledger write path, never its owner. Wired from
+ * `GroupManager.buildEnactLedgerCommit`. `requestID` is absent when the lost
+ * commit journalled none: the tokens are still the work and are re-driven, but
+ * the rebuilt commit settles nothing rather than settling a fabricated id.
+ */
+export type BuildLedgerRedrive = (groupID: string, tokens: Array<string>, requestID?: string) => () => Promise<PendingCommit>;
+export type GroupPeerManagerParams = {
+    /**
+     * Spawns a fresh `Client<HubProtocol>` for a hub URL. The manager wraps each
+     * URL's client in one reconnecting {@link createHubLike} (a single device
+     * receive drain), lazily on first peer creation for that hub.
+     */
+    createHubClient: CreateHubClient;
+    /**
+     * Rebuilds a lost `ledger` commit's surviving tokens into a fresh commit under
+     * the original request id, for the seam to re-drive once. Narrow by design —
+     * see {@link BuildLedgerRedrive}.
+     */
+    buildLedgerRedrive: BuildLedgerRedrive;
+    /** Single canonical access point for the device's MLS `GroupHandle` instances. */
+    registry: GroupHandleRegistry;
+    /**
+     * Store coordinator. Resolves the device's p2p store for the apply path,
+     * group↔hub binding reads, and the hub-DID cache; also passed to
+     * `createGroupMLS` for the receive-side commit transaction.
+     */
+    stores: StoreProvider;
+    graphStore: GraphStoreAPI;
+    /**
+     * Engine graph internals — threaded into the apply path so a `sync/mutationApply`
+     * frame routes peer-authored mutations through `applyVerifiedMutation` with
+     * `origin: 'peer'`.
+     */
+    graph: GraphInternals;
+    /** Device-wide monotonic clock shared with the engine and MLS receive path. */
+    hlc: HLC;
+    /** Authenticated DID of this device (normalized). */
+    localDID: string;
+    /**
+     * The device's own signing identity, forwarded to each peer's `GroupMLS` for
+     * the recovery members alone — the only lane work that must sign without a
+     * request behind it to take a key from.
+     */
+    identity: OwnIdentity;
+    emitter: P2PEventEmitter;
+    /**
+     * Host runtime; forwarded to each peer when set, which sources its fresh
+     * group-rpc correlation ids from it.
+     */
+    runtime?: Runtime;
+    logger?: Logger;
+    /** Receive-side storage mode. Forwarded to the apply path. Defaults to `'persist'`. */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
+    /**
+     * Per-peer N+1 re-broadcast config for the apply path. Omitted or `false`
+     * skips the pipeline.
+     */
+    forwarding?: ForwardingConfig;
+    /**
+     * Hub hook a forward re-broadcasts through. The apply path gates on this AND
+     * `forwarding`, so supplying one alone leaves forwarding off.
+     */
+    scheduleBroadcast?: (groupID: string, message: GroupBroadcastMessage) => void | Promise<void>;
+    /**
+     * Reconnect-backoff overrides for every hub adapter this manager spawns. Only
+     * a test harness sets this — production runs on the adapter's defaults. Each
+     * field is forwarded verbatim to {@link createHubLike}.
+     */
+    hubReconnectBackoff?: {
+        baseMs?: number;
+        maxMs?: number;
+        jitter?: number;
+    };
+    /**
+     * Sync procedures served to a co-member that dials in over a hub tunnel. The
+     * same handlers the direct and HTTP transports serve — a tunnel is a route,
+     * so it must not reach a different implementation.
+     *
+     * Omitted, the device answers no tunnel session: a caller that has not built
+     * handlers has no sync surface to expose.
+     */
+    syncHandlers?: ProcedureHandlers<SyncProtocol>;
+    /** @see TunnelListenersParams.idleTimeoutMs */
+    tunnelIdleTimeoutMs?: number;
+};
+/**
+ * Coordinates the per-(group, hub) `GroupPeer`s for one device — full multi-hub.
+ *
+ * The manager owns one reconnecting `HubLike` per hub URL (created lazily on
+ * first use, shared across every group bound to that hub via the multi-subscriber
+ * adapter) and one `GroupPeer` per (group, hub) pair. A peer exists iff the group
+ * is joined AND bound to that hub. Lifecycle mirrors the old `HubRelayManager`,
+ * but per (group, hub) instead of single-hub: the wiring phase drives `addGroup`
+ * / `removeGroup` / `addBinding` / `removeBinding` from the emitter and holds the
+ * unsubscribes. The manager does not subscribe to the emitter itself.
+ */
+export type GroupPeerManager = {
+    /** Bring up peers for each already-bound hub of each joined group. */
+    start: (groupIDs: Array<string>) => Promise<void>;
+    /** Mark a group joined and create a peer for each of its hub bindings. */
+    addGroup: (groupID: string) => Promise<void>;
+    /** Unmark a group and dispose all its peers (GC-ing now-idle hubs). */
+    removeGroup: (groupID: string) => Promise<void>;
+    /** Create the (group, hub) peer if the group is joined and none exists yet. */
+    addBinding: (groupID: string, hubURL: string) => Promise<void>;
+    /** Dispose the (group, hub) peer if present, GC-ing the hub if now idle. */
+    removeBinding: (groupID: string, hubURL: string) => Promise<void>;
+    /**
+     * Re-derive the group's tunnel listeners from its current roster.
+     *
+     * Driven by the membership projection rather than only by the epoch, because
+     * the epoch advances INSIDE the transaction that writes the new member: a
+     * reconcile scheduled there can read the roster as it was and stand up no
+     * listener for the device just admitted.
+     */
+    reconcileTunnelListeners: (groupID: string) => Promise<void>;
+    /** Fan a broadcast message out across every hub-peer of a group. */
+    broadcast: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /**
+     * This device's presence on the peer lane: what it advertises, and who it asks.
+     * The manager owns it because every internal trigger fires from here — a hub
+     * connect, an epoch rotation, a pruned app window — and because a gather needs
+     * the group's live peers.
+     */
+    presence: PeerPresence;
+    /**
+     * The peer for the group's canonical commit hub — the single hub a group
+     * commits through. Resolves the designated commit hub; falls back to the live
+     * peer whose hub URL sorts first for a legacy group with no designation (and
+     * warns), then to the group's loopback peer when it has no hub-backed peer at
+     * all. `undefined` only when the group has no lane whatsoever.
+     */
+    selectCommitPeer: (groupID: string) => Promise<GroupPeer<GroupProtocols> | undefined>;
+    /**
+     * Drive a commit through the group's canonical commit hub: build against the
+     * live handle, publish to that hub's commit log, adopt only on acceptance.
+     * Throws when the group has no live commit peer.
+     */
+    commit: (groupID: string, build: () => Promise<PendingCommit>) => Promise<LaneResult>;
+    /**
+     * Deep recovery: rejoin a peer the group left behind, via `GroupPeer.recover()`
+     * on the group's canonical commit hub. The peer requests a member's sealed
+     * GroupInfo over the non-rotating rendezvous topic, publishes the external
+     * commit under a head compare-and-set, and bootstraps the ledger — reissuing
+     * any tokens the authenticated ledger lacked. Reports `recovered` once the
+     * rejoin landed, or `recovery-failed` (without throwing) when no live responder
+     * answers or the group has no lane.
+     */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
+    /**
+     * Gather the group's control ledger from its current members and adopt it
+     * locally. Sends a `control/ledgerCatchup` request on every live hub-peer of
+     * the group; each responder returns its WHOLE ledger in enactment order, and
+     * the first list that reproduces this device's authenticated head is installed
+     * — a responder that withholds or reorders entries is dropped, not merged. A
+     * drifted joiner thus backfills what its invite snapshot missed, or gets
+     * nothing. Returns what landed; a no-op summary when the group has no live
+     * peer or every responder was refused.
+     */
+    requestLedgerCatchup: (groupID: string, options?: LedgerCatchupOptions) => Promise<LedgerCatchupSummary>;
+    /**
+     * Ask co-members to restate their own model access-defaults, and apply what is
+     * newer than what this device holds. Returns how many rules landed.
+     */
+    requestPolicyCatchup: (groupID: string) => Promise<number>;
+    /** The peer for one (group, hub), or `undefined` (used by tests). */
+    peer: (groupID: string, hubURL: string) => GroupPeer<GroupProtocols> | undefined;
+    /**
+     * The shared reconnecting `HubLike` for a hub URL, creating it on first use.
+     * Lets a caller obtain the device-wide drain to pass into a directed sync
+     * transport (provider/listener) sharing the same hub connection.
+     */
+    getHubLike: (hubURL: string) => ReconnectingDeviceHub;
+    /**
+     * The device-wide drain a directed session to this group should ride, or
+     * `undefined` when the group has no live hub binding — which is what a caller
+     * building a tunnel needs to know before it builds one.
+     *
+     * The group's first binding. A second hub is a second route to the same
+     * mailbox, not a different peer, so choosing between them is a preference
+     * nothing here holds.
+     */
+    tunnelHub: (groupID: string) => DeviceHub | undefined;
+    /**
+     * Try every hub this device holds now, rather than when each one's backoff
+     * says so, and answer with whether any of them is connected afterwards.
+     */
+    retryHubs: () => Promise<boolean>;
+    /** Dispose every peer and hub, then clear all maps. */
+    stop: () => Promise<void>;
+    /** Alias for {@link stop}. */
+    dispose: () => Promise<void>;
+};
+/**
+ * Send-side union → procedure mapping — the inverse of `buildGroupHandlers`.
+ *
+ * Translates a {@link GroupBroadcastMessage} into the matching group-rpc
+ * `dispatch` on a peer's control/sync protocol surface. Variants with no carried
+ * procedure (catalog control) are logged and no-op'd, matching the receive side.
+ */
+export declare function dispatchMessage(peer: GroupPeer<GroupProtocols>, message: GroupBroadcastMessage, logger?: Logger): Promise<void>;
+/**
+ * Run one lane operation, retrying only while the peer's runtimes are mid-rebuild.
+ *
+ * Safe to retry because the throw happens BEFORE anything is sealed or published:
+ * `surfaceFor` is what fails, so a retry cannot duplicate a frame. Every other
+ * failure — a refused publish, an unrouted message type — propagates on the first
+ * attempt, which is what keeps this from papering over a real fault.
+ */
+export declare function throughRotation<T>(op: () => Promise<T>, label: string, logger?: Logger): Promise<T>;
+/**
+ * Everything the seam needs to act on a lost commit: the settle deps it shares
+ * with {@link settleLostControlRequest}, plus what a lost `ledger` re-drive
+ * takes — the group whose ledger is read for the never-re-append filter, the
+ * registry that read runs through, and the narrow builder that rebuilds a
+ * surviving-token commit.
+ */
+export type CommitThroughPeerDeps = SettleLostControlRequestDeps & {
+    groupID: string;
+    /** Reads the group's current ledger tokens for the never-re-append filter. */
+    registry: Pick<GroupHandleRegistry, 'readHandle'>;
+    buildLedgerRedrive: BuildLedgerRedrive;
+};
+/**
+ * Publish a commit through the peer and act on what the lane hands back.
+ *
+ * A `LaneResult` can carry both a `lost` and a `reenact`; handle each
+ * independently. A lost `ledger` is re-issuable from its tokens, an `invite` or
+ * `remove` is not, so those settle `lost` here.
+ *
+ * The housekeeping is CONTAINED — never let it throw. By the time it runs THIS
+ * commit has landed and its request is settled, while `lost` and `reenact` name
+ * other work; an escaping throw would have the producer's per-request catch
+ * settle the terminal request `rejected`, writing a failure over a success and
+ * nulling the artifact for a member who really was added. That covers
+ * `RecoveryRequiredError` too: reaching {@link commitWithRecovery} would re-run
+ * the ORIGINAL `build` after its commit landed, publishing a second copy outside
+ * the never-re-append filter.
+ */
+export declare function commitThroughPeer(peer: Pick<GroupPeer<GroupProtocols>, 'commit'>, build: () => Promise<PendingCommit>, deps: CommitThroughPeerDeps): Promise<LaneResult>;
+export type CommitWithRecoveryParams = {
+    peer: Pick<GroupPeer<GroupProtocols>, 'commit' | 'recover'>;
+    build: () => Promise<PendingCommit>;
+    deps: CommitThroughPeerDeps;
+    /** Repair an incomplete ledger, the cheaper of the two remedies. */
+    gatherLedger: () => Promise<unknown>;
+};
+/**
+ * Publish a commit and, on the lane's stranded/incomplete-ledger gate, self-heal.
+ *
+ * The gate conflates an incomplete ledger — repaired by a plain ledger GATHER —
+ * with a true strand, repaired only by a full rejoin via `recover()`, so the
+ * cheaper remedy runs first: gather + retry once, then `recover()` + retry once,
+ * then propagate. Each remedy runs AT MOST ONCE (≤3 commit attempts): upstream
+ * forbids a tight retry loop, and `recover()` already bounds itself with its own
+ * deadline loop. When `recover()` cannot advance, rethrow the ORIGINAL gate error
+ * so the caller settles against the real cause. The retry carries the original
+ * `requestID`, so a healed commit settles `committed` through its own
+ * `onAccepted` rather than surfacing as a failure.
+ */
+export declare function commitWithRecovery(params: CommitWithRecoveryParams): Promise<LaneResult>;
+/**
+ * Rejoin the group through `GroupPeer.recover()` and map its outcome to a
+ * {@link RejoinResult}. `recover()` publishes the external commit under a head
+ * compare-and-set and bootstraps the ledger; it bounds itself, so it is never
+ * wrapped in a loop. Any `reenact` tokens it hands back — held here but absent
+ * from the authenticated ledger after the rejoin — are re-issued through the
+ * same {@link reissueLedgerTokens} filter every lane outcome uses. `advanced`
+ * maps to `recovered`; a peer that could not advance (no live responder) maps to
+ * `recovery-failed` without throwing.
+ */
+export declare function recoverThroughPeer(peer: Pick<GroupPeer<GroupProtocols>, 'commit' | 'recover'>, deps: CommitThroughPeerDeps): Promise<RejoinResult>;
+export declare function createGroupPeerManager(params: GroupPeerManagerParams): GroupPeerManager;