agentic-qe 1.1.0 → 1.3.0

package/dist/transport/QUICTransport.d.ts

@@ -0,0 +1,340 @@
+/**
+ * QUICTransport - High-performance QUIC transport layer for distributed QE fleet coordination
+ *
+ * Provides 50-70% latency reduction vs TCP through:
+ * - 0-RTT connection establishment
+ * - Multiplexed bidirectional streams
+ * - Built-in congestion control
+ * - Automatic TCP fallback for compatibility
+ *
+ * @module transport/QUICTransport
+ * @version 1.0.0
+ * @since 2025-10-20
+ */
+import { EventEmitter } from 'events';
+/**
+ * QUIC transport configuration options
+ */
+export interface QUICConfig {
+    /** Server hostname or IP address */
+    host: string;
+    /** Server port number */
+    port: number;
+    /** Path to TLS certificate file (optional, generates self-signed if not provided) */
+    certPath?: string;
+    /** Path to TLS private key file (optional, generates key if not provided) */
+    keyPath?: string;
+    /** Enable 0-RTT for faster reconnects (default: true) */
+    enable0RTT?: boolean;
+    /** Enable TCP fallback if QUIC fails (default: true) */
+    enableTCPFallback?: boolean;
+    /** Connection timeout in milliseconds (default: 5000) */
+    connectionTimeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Enable keep-alive packets (default: true) */
+    keepAlive?: boolean;
+    /** Keep-alive interval in milliseconds (default: 30000) */
+    keepAliveInterval?: number;
+    /** Maximum concurrent streams (default: 100) */
+    maxConcurrentStreams?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Transport mode - QUIC or TCP fallback
+ */
+export declare enum TransportMode {
+    QUIC = "QUIC",
+    TCP = "TCP",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Connection state
+ */
+export declare enum ConnectionState {
+    DISCONNECTED = "DISCONNECTED",
+    CONNECTING = "CONNECTING",
+    CONNECTED = "CONNECTED",
+    RECONNECTING = "RECONNECTING",
+    FAILED = "FAILED"
+}
+/**
+ * Performance metrics
+ */
+export interface TransportMetrics {
+    mode: TransportMode;
+    state: ConnectionState;
+    messagessent: number;
+    messagesReceived: number;
+    bytesTransferred: number;
+    averageLatency: number;
+    connectionUptime: number;
+    activeStreams: number;
+    failedAttempts: number;
+    lastError?: string;
+}
+/**
+ * QUICTransport - Production-ready QUIC/TCP transport layer
+ *
+ * Features:
+ * - QUIC protocol with 0-RTT support
+ * - Automatic TCP fallback
+ * - Channel-based message routing
+ * - Bidirectional streaming
+ * - Connection pooling and multiplexing
+ * - Comprehensive error handling
+ * - Performance monitoring
+ *
+ * @example
+ * ```typescript
+ * const transport = new QUICTransport();
+ * await transport.initialize({
+ *   host: 'fleet.example.com',
+ *   port: 4433,
+ *   enable0RTT: true
+ * });
+ *
+ * await transport.receive('coordination', (data) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * await transport.send('coordination', { action: 'sync', agentId: 'qe-01' });
+ * ```
+ */
+export declare class QUICTransport extends EventEmitter {
+    private config;
+    private mode;
+    private state;
+    private quicSocket;
+    private tcpSocket;
+    private tlsCert;
+    private tlsKey;
+    private channelCallbacks;
+    private streams;
+    private metrics;
+    private latencySamples;
+    private connectionStartTime;
+    private keepAliveTimer;
+    private retryCount;
+    private isReconnecting;
+    constructor();
+    /**
+     * Get default configuration with sensible defaults
+     * @private
+     */
+    private getDefaultConfig;
+    /**
+     * Initialize QUIC transport with configuration
+     *
+     * Attempts QUIC connection first, falls back to TCP if:
+     * - QUIC not supported by network
+     * - Connection fails after retries
+     * - UDP blocked by firewall
+     *
+     * @param config - Transport configuration options
+     * @throws {Error} If both QUIC and TCP connections fail
+     *
+     * @example
+     * ```typescript
+     * await transport.initialize({
+     *   host: 'fleet.example.com',
+     *   port: 4433,
+     *   certPath: '/path/to/cert.pem',
+     *   keyPath: '/path/to/key.pem',
+     *   enable0RTT: true
+     * });
+     * ```
+     */
+    initialize(config: QUICConfig): Promise<void>;
+    /**
+     * Load TLS credentials from files or generate self-signed
+     * @private
+     */
+    private loadTLSCredentials;
+    /**
+     * Generate self-signed certificate for development
+     * @private
+     */
+    private generateSelfSignedCert;
+    /**
+     * Establish QUIC connection over UDP
+     * @private
+     */
+    private connectQUIC;
+    /**
+     * Send QUIC handshake packet with 0-RTT support
+     * @private
+     */
+    private sendQUICHandshake;
+    /**
+     * Handle incoming QUIC message
+     * @private
+     */
+    private handleQUICMessage;
+    /**
+     * Establish TCP fallback connection
+     * @private
+     */
+    private connectTCP;
+    /**
+     * Handle incoming TCP message
+     * @private
+     */
+    private handleTCPMessage;
+    /**
+     * Route message to channel callbacks
+     * @private
+     */
+    private routeMessage;
+    /**
+     * Send message on specified channel
+     *
+     * Automatically routes message through active transport (QUIC or TCP).
+     * Includes retry logic and error handling.
+     *
+     * @param channel - Channel name for routing
+     * @param data - Message data (any JSON-serializable object)
+     * @throws {Error} If transport not connected or send fails
+     *
+     * @example
+     * ```typescript
+     * await transport.send('coordination', {
+     *   action: 'sync',
+     *   agentId: 'qe-01',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    send(channel: string, data: any): Promise<void>;
+    /**
+     * Send message via QUIC
+     * @private
+     */
+    private sendQUICMessage;
+    /**
+     * Send message via TCP
+     * @private
+     */
+    private sendTCPMessage;
+    /**
+     * Register callback for channel messages
+     *
+     * Supports multiple callbacks per channel for pub/sub pattern.
+     *
+     * @param channel - Channel name to subscribe to
+     * @param callback - Function to call when message received
+     *
+     * @example
+     * ```typescript
+     * await transport.receive('coordination', (data) => {
+     *   console.log('Coordination event:', data);
+     * });
+     *
+     * await transport.receive('metrics', (data) => {
+     *   console.log('Performance metrics:', data);
+     * });
+     * ```
+     */
+    receive(channel: string, callback: (data: any) => void): Promise<void>;
+    /**
+     * Unregister callback from channel
+     *
+     * @param channel - Channel name
+     * @param callback - Callback function to remove
+     */
+    unsubscribe(channel: string, callback: (data: any) => void): void;
+    /**
+     * Close transport connection gracefully
+     *
+     * Cleanup includes:
+     * - Closing active sockets
+     * - Clearing subscriptions
+     * - Stopping keep-alive timer
+     * - Emitting disconnect event
+     *
+     * @example
+     * ```typescript
+     * await transport.close();
+     * console.log('Transport closed successfully');
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Check if transport is connected
+     *
+     * @returns true if connected via QUIC or TCP, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Get current transport mode
+     *
+     * @returns Current transport mode (QUIC, TCP, or UNKNOWN)
+     */
+    getMode(): TransportMode;
+    /**
+     * Get connection state
+     *
+     * @returns Current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Get performance metrics
+     *
+     * Includes:
+     * - Messages sent/received
+     * - Average latency
+     * - Connection uptime
+     * - Active streams
+     * - Failed attempts
+     *
+     * @returns Current transport metrics
+     */
+    getMetrics(): TransportMetrics;
+    /**
+     * Handle disconnection and attempt reconnect
+     * @private
+     */
+    private handleDisconnect;
+    /**
+     * Start keep-alive timer
+     * @private
+     */
+    private startKeepAlive;
+    /**
+     * Generate unique message ID
+     * @private
+     */
+    private generateMessageId;
+    /**
+     * Generate stream ID from channel
+     * @private
+     */
+    private generateStreamId;
+    /**
+     * Debug logging
+     * @private
+     */
+    private log;
+}
+/**
+ * Create and initialize QUIC transport
+ *
+ * Convenience factory function for quick setup.
+ *
+ * @param config - Transport configuration
+ * @returns Initialized QUICTransport instance
+ *
+ * @example
+ * ```typescript
+ * const transport = await createQUICTransport({
+ *   host: 'fleet.example.com',
+ *   port: 4433,
+ *   enable0RTT: true
+ * });
+ * ```
+ */
+export declare function createQUICTransport(config: QUICConfig): Promise<QUICTransport>;
+//# sourceMappingURL=QUICTransport.d.ts.map

package/dist/transport/QUICTransport.d.ts.map

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