agentic-qe 2.7.4 → 2.8.0

package/dist/edge/p2p/nat/HolePuncher.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Hole Puncher for @ruvector/edge P2P
+ *
+ * Implements UDP hole punching techniques for NAT traversal including
+ * simultaneous open, port prediction, and fallback escalation.
+ *
+ * @module edge/p2p/nat/HolePuncher
+ * @version 1.0.0
+ */
+import { PeerId, ICECandidate } from '../webrtc/types';
+import { HolePunchResult, HolePuncherConfig, PortPrediction, EscalationLevel, EscalationState, EscalationConfig, NATClassification, NATEventType, NATEventHandler, TURNConfig } from './types';
+/**
+ * Hole punch coordination message
+ */
+interface CoordinationMessage {
+    /** Message type */
+    type: 'ready' | 'punch' | 'ack' | 'failed';
+    /** Source peer ID */
+    from: PeerId;
+    /** Target peer ID */
+    to: PeerId;
+    /** Local endpoint information */
+    endpoint?: {
+        address: string;
+        port: number;
+    };
+    /** Predicted ports for symmetric NAT */
+    predictedPorts?: number[];
+    /** Attempt number */
+    attempt: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Hole Puncher - Implements NAT hole punching techniques
+ *
+ * @example
+ * ```typescript
+ * const holePuncher = new HolePuncher({
+ *   maxAttempts: 10,
+ *   enablePortPrediction: true,
+ *   enableSimultaneousOpen: true,
+ * });
+ *
+ * // Set up coordination channel
+ * holePuncher.setCoordinationChannel({
+ *   send: (msg) => signalingChannel.send(msg),
+ *   onMessage: (handler) => signalingChannel.on('message', handler),
+ * });
+ *
+ * // Attempt hole punch
+ * const result = await holePuncher.punch(remotePeerId, {
+ *   localCandidates: [...],
+ *   remoteCandidates: [...],
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Direct connection established!');
+ * }
+ * ```
+ */
+export declare class HolePuncher {
+    private readonly config;
+    private readonly escalationConfig;
+    private escalationState;
+    private eventHandlers;
+    private coordinationChannel;
+    private localPeerId;
+    private currentPunch;
+    /**
+     * Create a new Hole Puncher
+     *
+     * @param config - Hole puncher configuration
+     * @param escalationConfig - Escalation configuration
+     */
+    constructor(config?: Partial<HolePuncherConfig>, escalationConfig?: Partial<EscalationConfig>);
+    /**
+     * Set local peer ID
+     *
+     * @param peerId - Local peer identifier
+     */
+    setLocalPeerId(peerId: PeerId): void;
+    /**
+     * Set coordination channel for peer signaling
+     *
+     * @param channel - Coordination channel interface
+     */
+    setCoordinationChannel(channel: {
+        send: (msg: CoordinationMessage) => void;
+        onMessage: (handler: (msg: CoordinationMessage) => void) => () => void;
+    }): void;
+    /**
+     * Attempt hole punch to remote peer
+     *
+     * @param remotePeerId - Remote peer to punch to
+     * @param options - Punch options with candidates
+     * @returns Promise resolving to punch result
+     */
+    punch(remotePeerId: PeerId, options: {
+        localCandidates: ICECandidate[];
+        remoteCandidates: ICECandidate[];
+        localNatType?: NATClassification;
+        remoteNatType?: NATClassification;
+    }): Promise<HolePunchResult>;
+    /**
+     * Cancel ongoing hole punch attempt
+     */
+    cancel(): void;
+    /**
+     * Get fallback to TURN relay
+     *
+     * @param turnServers - Available TURN servers
+     * @returns Recommended escalation action
+     */
+    getFallbackAction(turnServers: TURNConfig[]): {
+        action: 'continue' | 'escalate' | 'abort';
+        level: EscalationLevel;
+        turnServer?: TURNConfig;
+    };
+    /**
+     * Escalate to next level
+     */
+    escalate(): void;
+    /**
+     * Get current escalation state
+     */
+    getEscalationState(): EscalationState | null;
+    /**
+     * Predict ports for symmetric NAT
+     *
+     * @param observedPorts - Previously observed port mappings
+     * @returns Port prediction result
+     */
+    predictPorts(observedPorts: number[]): PortPrediction;
+    /**
+     * Register event handler
+     *
+     * @param type - Event type to handle
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    on<T>(type: NATEventType, handler: NATEventHandler<T>): () => void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HolePuncherConfig;
+    private resetEscalation;
+    private getNextEscalationLevel;
+    private selectTurnServer;
+    private executePunchSequence;
+    private simultaneousPunch;
+    private predictedPunch;
+    private extractEndpoints;
+    private createFailedResult;
+    private delay;
+    private emitEvent;
+}
+export default HolePuncher;
+//# sourceMappingURL=HolePuncher.d.ts.map

package/dist/edge/p2p/nat/HolePuncher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HolePuncher.d.ts","sourceRoot":"","sources":["../../../../src/edge/p2p/nat/HolePuncher.ts"],"names":[],"mappings":"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"}