@cello-protocol/client 0.0.20 → 0.0.22

package/dist/relay-stream-manager.d.ts

@@ -0,0 +1,136 @@
+/**
+ * RelayStreamManager — relay reader loop, reconnect logic, cross-check, content frame handling.
+ *
+ * Extracted from CelloClientImpl. Handles MSG-004 relay stream lifecycle:
+ * - #runRelayStreamReader: reads leaf_deliver, hash_submit_ack/error, gap_fill frames
+ * - #reconnectRelayStream: SESSION-006 exponential backoff reconnect
+ * - #handleInboundLeafDeliver: S2 decode, sequence/signature checks, cross-check pairing
+ * - #handleContentStream: content path receiver, cross-check trigger
+ * - #crossCheckDelivery / #drainReadyQueue: in-order delivery with prevRoot check
+ * - #desync: session desynchronization
+ * - #performRelayAuth: challenge-response auth
+ * - #performGapFillReconciliation: PERSIST-014 gap fill
+ * - #handleGapFillResponse
+ *
+ * State owned here (not in facade):
+ *   - #relayStreams, #relayRecvSeq, #reconnectInProgress
+ *   - #readyQueue, #pendingS2, #pendingContent
+ *   - #tamperedContentClaims, #pendingGapFillResolvers
+ *   - #directoryStreams
+ */
+import type { CelloNode } from "@cello-protocol/transport";
+import type { Stream } from "@libp2p/interface";
+import type { Structure2 } from "@cello-protocol/protocol-types";
+import type { Logger } from "@cello-protocol/interfaces";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { ClientStatePersistence } from "./client-state-persistence.js";
+import type { SessionRecord, ReceivedMessage } from "./types.js";
+import type { AgentHashQueue } from "./agent-hash-queue.js";
+declare const DEFAULT_RECONNECT_TIMEOUT_MS = 60000;
+interface Structure1Fields {
+    last_seen_seq: number;
+    timestamp: number | bigint;
+}
+interface PendingS2Entry {
+    s2: Structure2;
+    s2_cbor: Uint8Array;
+    s1_fields: Structure1Fields;
+    leaf_kind: number;
+    sequence_number: number;
+    content_hash: Uint8Array;
+    is_own_send: boolean;
+    arrived_at: number;
+    timer_handle: ReturnType<typeof setTimeout>;
+    echo_resolve?: () => void;
+}
+interface PendingContentEntry {
+    content_bytes: Uint8Array;
+    arrived_at: number;
+}
+interface ReadyEntry {
+    s2: Structure2;
+    s2_cbor: Uint8Array;
+    s1_fields: Structure1Fields;
+    leaf_kind: number;
+    content_bytes: Uint8Array;
+    is_own_send: boolean;
+    echo_resolve?: () => void;
+}
+/**
+ * Narrow interface exposing only what RelayStreamManager needs from external managers.
+ * State owned by RelayStreamManager is no longer in this interface.
+ */
+export interface RelayStreamContext {
+    readonly node: CelloNode;
+    readonly keyProvider: KeyProvider;
+    readonly logger: Logger;
+    readonly persistence: ClientStatePersistence | null;
+    readonly contentGraceMs: number;
+    readonly reconnectTimeoutMs: number;
+    readonly hashQueue: AgentHashQueue | null;
+    getMyPubkeyHex(): string | null;
+    getSession(sessionIdHex: string): SessionRecord | undefined;
+    getSessions(): Map<string, SessionRecord>;
+    getPendingAckResolver(sessionIdHex: string): ((v: {
+        ok: true;
+        sequence_number: number;
+    } | {
+        ok: false;
+        reason: string;
+    }) => void) | undefined;
+    setPendingAckResolver(sessionIdHex: string, resolve: (v: {
+        ok: true;
+        sequence_number: number;
+    } | {
+        ok: false;
+        reason: string;
+    }) => void): void;
+    deletePendingAckResolver(sessionIdHex: string): void;
+    getOwnPendingContent(sessionIdHex: string): Map<string, {
+        content_bytes: Uint8Array;
+        arrived_at: number;
+    }> | undefined;
+    getOwnEchoResolvers(sessionIdHex: string): Map<number, () => void> | undefined;
+    getOutboundQueue(sessionIdHex: string): Promise<void> | undefined;
+    enqueueReceivedMessage(sessionIdHex: string, message: ReceivedMessage): void;
+    wakeReceiveWaiters(sessionIdHex: string): void;
+    enqueueSessionSealedEvent(sessionIdHex: string, sealedRoot: Uint8Array, closeTimestamp: number): void;
+    handleSealVerified(sessionIdHex: string, frame: Record<string, unknown>): void;
+    handleSessionFrostSealed(sessionIdHex: string, frame: Record<string, unknown>): void;
+    handleSealRejectedTreeMismatch(sessionIdHex: string, frame: Record<string, unknown>): void;
+    handleSealUnilateralConfirmed(sessionIdHex: string, frame: Record<string, unknown>): void;
+    handleSealUnilateralNotification(sessionIdHex: string, frame: Record<string, unknown>): void;
+    handleDirectorySessionSealed(sessionIdHex: string, frame: Record<string, unknown>, directoryPubkey: Uint8Array): void;
+    handleDirectorySessionSealRejected(sessionIdHex: string, frame: Record<string, unknown>): void;
+    onRelayDisconnected(sessionIdHex: string, myPubkeyHex: string): void;
+}
+export type { ReadyEntry, PendingS2Entry, PendingContentEntry, Structure1Fields };
+export declare class RelayStreamManager {
+    #private;
+    constructor(ctx: RelayStreamContext);
+    getRelayStream(sessionIdHex: string): Stream | undefined;
+    setRelayStream(sessionIdHex: string, stream: Stream): void;
+    deleteRelayStream(sessionIdHex: string): void;
+    getDirectoryStream(sessionIdHex: string): Stream | undefined;
+    setDirectoryStream(sessionIdHex: string, stream: Stream): void;
+    deleteDirectoryStream(sessionIdHex: string): void;
+    /** Called by SessionManager.receiveSessionAssignment to initialize per-session relay state. */
+    initSession(sessionIdHex: string): void;
+    /** Called by facade.closeSession to tear down per-session relay state. */
+    closeSession(sessionIdHex: string): void;
+    injectLeafDeliver(sessionIdHex: string, frame: Record<string, unknown>): void;
+    injectRelayDisconnect(sessionIdHex: string): void;
+    runRelayStreamReader(sessionIdHex: string, stream: Stream, myPubkeyHex: string, iter?: AsyncIterator<Uint8Array>): void;
+    reconnectRelayStream(sessionIdHex: string, myPubkeyHex: string): Promise<void>;
+    handleContentStream(stream: Stream): Promise<void>;
+    performRelayAuth(stream: Stream, myPubkey: Uint8Array): Promise<{
+        ok: true;
+        iter: AsyncIterator<Uint8Array>;
+    } | {
+        ok: false;
+        reason: "relay_auth_failed" | "relay_auth_error";
+    }>;
+    performGapFillReconciliation(sessionIdHex: string, fromSeq: number, toSeq: number, correlationId: string): Promise<void>;
+}
+export { DEFAULT_RECONNECT_TIMEOUT_MS };
+//# sourceMappingURL=relay-stream-manager.d.ts.map

package/dist/relay-stream-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-stream-manager.d.ts","sourceRoot":"","sources":["../src/relay-stream-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,QAAA,MAAM,4BAA4B,QAAS,CAAC;AAgC5C,UAAU,gBAAgB;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,UAAU,cAAc;IACtB,EAAE,EAAE,UAAU,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,UAAU,mBAAmB;IAC3B,aAAa,EAAE,UAAU,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,UAAU,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,UAAU,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC5D,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC9I,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/I,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;IACvH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAC/E,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IAElE,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7E,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtG,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrF,8BAA8B,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3F,6BAA6B,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1F,gCAAgC,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7F,4BAA4B,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IACtH,kCAAkC,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE/F,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,CAAC;AAElF,qBAAa,kBAAkB;;gBAgCjB,GAAG,EAAE,kBAAkB;IAMnC,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxD,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1D,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAI7C,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI9D,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAIjD,+FAA+F;IAC/F,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAQvC,0EAA0E;IAC1E,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IA2BxC,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAM7E,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAajD,oBAAoB,CAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B,IAAI;IAqED,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0E9E,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6GlD,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,CAAA;KAAE,CAAC;IAmUrH,4BAA4B,CAChC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;CAqIjB;AAED,OAAO,EAAE,4BAA4B,EAAE,CAAC"}