@kubun/plugin-p2p 0.13.1 → 0.15.0

package/lib/sync/hub-tunnel-service-listener.d.ts

@@ -0,0 +1,75 @@
+import type { ServerTransportOf } from '@enkaku/protocol';
+import type { Server } from '@enkaku/server';
+import type { Logger } from '@kubun/logger';
+import type { ServiceConfig, ServiceProtocol } from '@kubun/plugin-service-api';
+import { type MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+/**
+ * Mirrors `ServiceServerPluginAPI['serve']` (`@kubun/plugin-service-server`)
+ * without importing it, so this listener has no direct dependency on that
+ * plugin. `serve()` applies provider discovery, handler/access-rule merge,
+ * handler-authorization wrapping, and controller-DID verification that a bare
+ * `new Server` would not.
+ */
+export type ServeService = (params: {
+    transport: ServerTransportOf<ServiceProtocol>;
+    services: Record<string, ServiceConfig>;
+    requireAuth?: false;
+}) => Server<ServiceProtocol>;
+/**
+ * The injected {@link ServeService} was called before the `service-server`
+ * plugin API had resolved. Transient — the listener retries on its normal backoff.
+ */
+export declare class ServiceServeNotReadyError extends Error {
+    constructor(message: string);
+}
+/**
+ * The injected {@link ServeService} failed for a reason a retry cannot change
+ * (plugin absent, unknown/colliding service name). Terminal — the listener
+ * stops answering for this peer instead of spinning on backoff.
+ */
+export declare class ServiceServeUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type HubTunnelServiceListenerParams = {
+    /**
+     * Shared multi-subscriber device hub. Every listener on a device receives on
+     * the same topic, so the hub is fronted by a per-peer view that drops other
+     * peers' frames before they reach the cipher.
+     */
+    hub: MailboxHub;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    localDID: string;
+    peerDID: string;
+    /**
+     * Platform primitives, including the per-session id generator. Threaded in
+     * from the caller since this package runs on React Native and browser too,
+     * not just node.
+     */
+    runtime: Runtime;
+    /** Injected `plugin-service-server` `serve()` — see {@link ServeService}. */
+    serve: ServeService;
+    /** Which services to serve, forwarded verbatim to {@link serve} on every spawn. */
+    services: Record<string, ServiceConfig>;
+    idleTimeoutMs?: number;
+    logger?: Logger;
+};
+/**
+ * Answer side of the service tunnel — the same directed hub-tunnel machinery as
+ * `HubTunnelSyncListener`, on a distinct lane so a service session never
+ * collides with a sync session's topics or ratchet generation.
+ *
+ * Unlike the sync listener, this does not build a bare `Server`: it hands the
+ * spawned transport to the injected {@link ServeService} callback so
+ * provider discovery, handler wrapping, and controller-DID verification apply.
+ */
+export declare class HubTunnelServiceListener {
+    #private;
+    constructor(params: HubTunnelServiceListenerParams);
+    start(): void;
+    stop(): Promise<void>;
+}

package/lib/sync/hub-tunnel-service-listener.js

@@ -0,0 +1,289 @@
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createPeerScopedHubView } from '../hub/peer-scoped-hub-view.js';
+import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
+/**
+ * The injected {@link ServeService} was called before the `service-server`
+ * plugin API had resolved. Transient — the listener retries on its normal backoff.
+ */ export class ServiceServeNotReadyError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'ServiceServeNotReadyError';
+    }
+}
+/**
+ * The injected {@link ServeService} failed for a reason a retry cannot change
+ * (plugin absent, unknown/colliding service name). Terminal — the listener
+ * stops answering for this peer instead of spinning on backoff.
+ */ export class ServiceServeUnavailableError extends Error {
+    constructor(message, options){
+        super(message, options);
+        this.name = 'ServiceServeUnavailableError';
+    }
+}
+/**
+ * Answer side of the service tunnel — the same directed hub-tunnel machinery as
+ * `HubTunnelSyncListener`, on a distinct lane so a service session never
+ * collides with a sync session's topics or ratchet generation.
+ *
+ * Unlike the sync listener, this does not build a bare `Server`: it hands the
+ * spawned transport to the injected {@link ServeService} callback so
+ * provider discovery, handler wrapping, and controller-DID verification apply.
+ */ export class HubTunnelServiceListener {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #runtime;
+    #serve;
+    #services;
+    #idleTimeoutMs;
+    #logger;
+    #started = false;
+    #stopped = false;
+    /** Consecutive failed spawns, for the re-arm backoff. Reset by a success. */ #respawnAttempt = 0;
+    #respawnTimer;
+    #current;
+    // Single MLSEncryptor reused across spawns. Ordering across overlapping
+    // spawns (old transport's last decrypt vs. new spawn's first encrypt) is
+    // covered by the GroupHandleRegistry's per-group mutex.
+    #encryptor;
+    // Per-peer view over the device hub, built once and shared by every spawn: it
+    // holds the inbox subscription for the listener's whole life, so respawns
+    // neither re-arm nor release a topic other listeners are draining.
+    #peerHub;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#runtime = params.runtime;
+        this.#serve = params.serve;
+        this.#services = params.services;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#logger = params.logger;
+    }
+    start() {
+        if (this.#started || this.#stopped) return;
+        this.#started = true;
+        this.#encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        this.#peerHub = createPeerScopedHubView({
+            hub: this.#hub,
+            peerDID: this.#peerDID
+        });
+        this.#spawnGuarded();
+    }
+    /**
+   * Spawn, and survive a spawn that throws. `#spawn` can reject (e.g.
+   * `exportSecret` when the group handle is unavailable); left bare that would
+   * be both an unhandled rejection and a listener that never answers again,
+   * since the only other respawn trigger — the transport's `disposed` event —
+   * can't fire for a session that was never built.
+   */ #spawnGuarded() {
+        void this.#spawn().then(()=>{
+            this.#respawnAttempt = 0;
+        }).catch((error)=>{
+            // Terminal serve() failure (plugin absent, unknown/colliding service):
+            // stop rather than respawn forever. `stop()` marks `#stopped`, so the
+            // scheduled-respawn path becomes a no-op; the dialing side idles out and
+            // falls back exactly as it does for a peer that never answers.
+            if (error instanceof ServiceServeUnavailableError) {
+                this.#logger?.error('hub tunnel service listener stopping: serve() failed permanently; the service lane will not answer for this peer', {
+                    lane: 'service',
+                    groupID: this.#groupID,
+                    peerDID: this.#peerDID,
+                    error
+                });
+                void this.stop();
+                return;
+            }
+            this.#logger?.warn('hub tunnel service listener spawn failed', {
+                lane: 'service',
+                groupID: this.#groupID,
+                peerDID: this.#peerDID,
+                attempt: this.#respawnAttempt,
+                error
+            });
+            this.#scheduleRespawn();
+        });
+    }
+    #scheduleRespawn() {
+        if (this.#stopped || this.#respawnTimer != null) return;
+        // Bounded: a handle that is unavailable because the group was left never
+        // becomes available, and this must not spin on it.
+        const delay = Math.min(30_000, 250 * 2 ** Math.min(this.#respawnAttempt++, 7));
+        const timer = setTimeout(()=>{
+            this.#respawnTimer = undefined;
+            if (this.#stopped) return;
+            this.#spawnGuarded();
+        }, delay);
+        timer.unref?.();
+        this.#respawnTimer = timer;
+    }
+    async stop() {
+        if (this.#stopped) return;
+        this.#stopped = true;
+        if (this.#respawnTimer != null) {
+            clearTimeout(this.#respawnTimer);
+            this.#respawnTimer = undefined;
+        }
+        const current = this.#current;
+        this.#current = undefined;
+        if (current != null) {
+            try {
+                await current.transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await current.server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+        }
+        this.#encryptor = undefined;
+        this.#peerHub = undefined;
+    }
+    async #spawn() {
+        if (this.#stopped) return;
+        const encryptor = this.#encryptor;
+        const peerHub = this.#peerHub;
+        if (encryptor == null || peerHub == null) {
+            throw new Error('HubTunnelServiceListener: not initialized; call start() first');
+        }
+        // Epoch-bound, role-scoped topics for this spawn, on the SERVICE lane — a
+        // distinct protocol label so a service session never shares a ratchet
+        // generation with a sync session. The server listens on this device's
+        // RESPONDER topic and replies on the peer's DIALER topic — the mirror of
+        // the dialing side, and disjoint from it. Topics rotate with the MLS
+        // epoch, so each spawn re-derives them; MLS decrypt inside the registry
+        // lock remains the authoritative membership/forward-secrecy gate.
+        // Seed epoch is unread here: this port never classifies commit frames.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        const sendTopicID = tunnelTopic(secret, epoch, 'dialer', this.#peerDID, SERVICE_TUNNEL_PROTOCOL);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'responder', this.#localDID, SERVICE_TUNNEL_PROTOCOL);
+        // A stop() that landed while we awaited the handle must abort the spawn.
+        if (this.#stopped) return;
+        // No sessionID: a responder locks to whatever session dials it, so the id
+        // is not known until the first frame. `role` is what separates this
+        // listener's log lines from the dialer's on the same device at a glance.
+        const sessionLogger = this.#logger?.with({
+            role: 'listener',
+            lane: 'service',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            epoch,
+            receiveTopicID
+        });
+        sessionLogger?.debug('tunnel session opening');
+        let transportRef;
+        const transport = createEncryptedHubTunnelTransport({
+            hub: peerHub,
+            encryptor,
+            groupID: this.#groupID,
+            sessionID: {
+                auto: true
+            },
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            onSessionEnd: ()=>{
+                // Peer signaled end-of-session. Dispose the transport deterministically
+                // so the `disposed` event fires and the spawn loop re-arms for the
+                // next session arriving on the shared device drain.
+                void transportRef?.dispose().catch(()=>{
+                // ignore — best-effort
+                });
+            }
+        });
+        transportRef = transport;
+        // Hand the transport to the injected `serve()` rather than building a bare
+        // `Server` — the delta from the sync listener.
+        //
+        // `serve()` can throw synchronously (plugin API not yet resolved, or
+        // genuinely absent). By this point `transport` already exists and has
+        // already subscribed the hub, with no `disposed` handler attached yet to
+        // re-arm anything — left undisposed here, a throw would leak one
+        // orphaned, still-subscribed transport per retry. Dispose before
+        // rethrowing so every failed attempt cleans up after itself.
+        let server;
+        try {
+            server = this.#serve({
+                transport,
+                services: this.#services
+            });
+        } catch (error) {
+            await transport.dispose().catch(()=>{
+            // ignore — best-effort teardown
+            });
+            // Preserve transient/terminal classification for #spawnGuarded: a
+            // not-ready or already-terminal error rethrows as-is; any other throw is
+            // a permanent misconfiguration, wrapped terminal so the listener stops.
+            if (error instanceof ServiceServeNotReadyError || error instanceof ServiceServeUnavailableError) {
+                throw error;
+            }
+            throw new ServiceServeUnavailableError('service tunnel serve() failed permanently', {
+                cause: error
+            });
+        }
+        const session = {
+            transport,
+            server
+        };
+        this.#current = session;
+        // Defence in depth: no `await` sits between the `#stopped` check above and
+        // this assignment today, but re-checking after the assignment means a
+        // `stop()` landing in a future await window still gets torn down —
+        // whichever side runs second does the teardown.
+        if (this.#stopped) {
+            this.#current = undefined;
+            try {
+                await transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            return;
+        }
+        // `disposed` may fire more than once for a single session (disposing the
+        // server can re-enter the transport's dispose). Collapse to exactly one
+        // teardown + respawn so one session leaves exactly one successor.
+        let handled = false;
+        transport.events.on('disposed', ()=>{
+            if (handled) return;
+            handled = true;
+            sessionLogger?.debug('tunnel session closed');
+            if (this.#current === session) {
+                this.#current = undefined;
+            }
+            // Server stays around until its handlers drain; explicit cleanup here so
+            // long-running sessions don't leak server instances.
+            void server.dispose().catch(()=>{
+            // ignore
+            });
+            // Nothing re-arms the inbox here — this fires even after stop(), but the
+            // per-peer view never releases the topic, so a departing transport's
+            // teardown can't empty it. Respawn re-derives topics for the next session.
+            this.#spawnGuarded();
+        });
+    }
+}

package/lib/sync/hub-tunnel-service-provider.d.ts

@@ -0,0 +1,46 @@
+import type { ClientTransportOf } from '@enkaku/protocol';
+import type { Logger } from '@kubun/logger';
+import type { ServiceProtocol } from '@kubun/plugin-service-api';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { DeviceHub } from '../hub/hub-like.js';
+export type HubTunnelServiceProviderParams = {
+    /**
+     * Shared multi-subscriber device hub (from `createHubLike`). Each session
+     * attaches its own sink to this device-wide drain, narrowed to the peer it
+     * dialled, and filters to `receiveTopicID`; lifecycle events ride
+     * `hub.events`.
+     */
+    hub: DeviceHub;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    localDID: string;
+    peerDID: string;
+    /**
+     * Platform primitives, including the per-session id generator. Threaded in
+     * from the caller since this package runs on React Native and browser too,
+     * not just node.
+     */
+    runtime: Runtime;
+    idleTimeoutMs?: number;
+    logger?: Logger;
+};
+/**
+ * Dial side of the SERVICE tunnel — the same directed hub-tunnel machinery as
+ * {@link HubTunnelSyncProvider}, riding a distinct lane so a service session to
+ * a peer never collides with a sync session's topics or ratchet generation.
+ */
+export declare class HubTunnelServiceProvider {
+    #private;
+    constructor(params: HubTunnelServiceProviderParams);
+    /**
+     * Build a fresh client transport for one tunnel service session.
+     *
+     * Topics are group- and role-scoped, derived from the current MLS epoch
+     * secret on the service lane: outbound frames publish to the peer's
+     * responder topic, and the transport subscribes to this device's own dialer
+     * topic. Topics rotate with the epoch, so callers create a new transport per
+     * session.
+     */
+    createServiceTransport(signal?: AbortSignal): Promise<ClientTransportOf<ServiceProtocol>>;
+}

package/lib/sync/hub-tunnel-service-provider.js

@@ -0,0 +1,100 @@
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createSenderScopedHubView } from '../hub/sender-scoped-hub-view.js';
+import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
+/**
+ * Dial side of the SERVICE tunnel — the same directed hub-tunnel machinery as
+ * {@link HubTunnelSyncProvider}, riding a distinct lane so a service session to
+ * a peer never collides with a sync session's topics or ratchet generation.
+ */ export class HubTunnelServiceProvider {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #runtime;
+    #idleTimeoutMs;
+    #logger;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#runtime = params.runtime;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#logger = params.logger;
+    }
+    /**
+   * Build a fresh client transport for one tunnel service session.
+   *
+   * Topics are group- and role-scoped, derived from the current MLS epoch
+   * secret on the service lane: outbound frames publish to the peer's
+   * responder topic, and the transport subscribes to this device's own dialer
+   * topic. Topics rotate with the epoch, so callers create a new transport per
+   * session.
+   */ async createServiceTransport(signal) {
+        const sessionID = this.#runtime.getRandomID();
+        const encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        // SERVICE lane — the only substantive difference from the sync provider.
+        const sendTopicID = tunnelTopic(secret, epoch, 'responder', this.#peerDID, SERVICE_TUNNEL_PROTOCOL);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'dialer', this.#localDID, SERVICE_TUNNEL_PROTOCOL);
+        // Bound once and carried by every line this session logs — the transport's
+        // own idle timeout raises a bare `TimeoutInterruption` with none of this
+        // context.
+        const sessionLogger = this.#logger?.with({
+            role: 'dialer',
+            lane: 'service',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            sessionID,
+            epoch,
+            receiveTopicID
+        });
+        sessionLogger?.debug('tunnel session opening');
+        const transport = createEncryptedHubTunnelTransport({
+            // The peer-scoped view, never the device hub: two sessions open at once
+            // share the same inbox topic, and MLS consumes a ratchet generation per
+            // open, destroying the frame for whichever session loses the race.
+            // The idle timeout doubles as the publish bound so "no receive" and "no
+            // send" give up on the same promise rather than drifting apart.
+            hub: createSenderScopedHubView({
+                hub: this.#hub,
+                peerDID: this.#peerDID,
+                ...this.#idleTimeoutMs == null ? {} : {
+                    publishTimeoutMs: this.#idleTimeoutMs
+                }
+            }),
+            encryptor,
+            groupID: this.#groupID,
+            sessionID,
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            signal,
+            idleTimeoutMs: this.#idleTimeoutMs
+        });
+        // Close is as load-bearing as open: an unreachable peer looks like a
+        // session ending without having received anything.
+        transport.events.on('disposed', ()=>{
+            sessionLogger?.debug('tunnel session closed');
+        });
+        return transport;
+    }
+}

package/lib/sync/service-tunnel-listeners.d.ts

@@ -0,0 +1,35 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { ServiceConfig } from '@kubun/plugin-service-api';
+import type { MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import { type ServeService } from './hub-tunnel-service-listener.js';
+import type { TunnelListeners } from './tunnel-listeners.js';
+export type ServiceTunnelListenersParams = {
+    stores: StoreProvider;
+    registry: GroupHandleRegistry;
+    identity: OwnIdentity;
+    localDID: string;
+    runtime: Runtime;
+    /** Injected `plugin-service-server` `serve()` — see {@link ServeService}. */
+    serve: ServeService;
+    /** Which services to serve, forwarded verbatim to `serve` on every spawn. */
+    services: Record<string, ServiceConfig>;
+    /** The group's device-wide drain, or `undefined` when no hub is bound. */
+    tunnelHub: (groupID: string) => MailboxHub | undefined;
+    logger?: Logger;
+    idleTimeoutMs?: number;
+};
+/**
+ * The answering half of the service tunnel — one `HubTunnelServiceListener` per
+ * co-member per group, so a device dialing on the service lane finds something
+ * draining the mailbox and handing the session to the injected `serve()`.
+ *
+ * Structurally identical to {@link createTunnelListeners} (the sync lane's
+ * answering half): same groupID→peerDID map, same epoch/hub-change teardown,
+ * same per-group serialized reconciles — only the listener class and what's
+ * threaded into it differ, so the two lanes never share an instance or ratchet.
+ */
+export declare function createServiceTunnelListeners(params: ServiceTunnelListenersParams): TunnelListeners;