@olane/o-node 0.7.54 → 0.7.56

package/dist/src/connection/o-node-stream.manager.js

@@ -1,633 +0,0 @@
-import { EventEmitter } from 'events';
-import { oObject, oError, oErrorCodes, oRequest, oResponse, CoreUtils, ResponseBuilder, } from '@olane/o-core';
-import { oNodeStream } from './o-node-stream.js';
-import { StreamManagerEvent, } from './stream-manager.events.js';
-import { isStreamInitMessage, } from './interfaces/stream-init-message.js';
-import { lpStream } from '@olane/o-config';
-import JSON5 from 'json5';
-/**
- * oNodeStreamManager handles the lifecycle and tracking of streams for a single connection.
- * Features:
- * - Tracks all streams by ID
- * - Creates new streams on demand
- * - Manages stream lifecycle (cleanup after use)
- * - Provides events for monitoring
- * - No reuse at base layer (extensible in subclasses)
- */
-export class oNodeStreamManager extends oObject {
-    constructor(config) {
-        super();
-        this.config = config;
-        this.streams = new Map();
-        this.eventEmitter = new EventEmitter();
-        this.isInitialized = false;
-        this.activeStreamHandlers = new Map();
-        this.p2pConnection = config.p2pConnection;
-    }
-    /**
-     * Initialize the stream manager
-     */
-    async initialize() {
-        if (this.isInitialized) {
-            this.logger.debug('Stream manager already initialized');
-            return;
-        }
-        try {
-            // Stream manager is now initialized and ready to handle streams
-            this.isInitialized = true;
-            this.emit(StreamManagerEvent.ManagerInitialized, {});
-            this.logger.info('Stream manager initialized', {
-                remotePeer: this.p2pConnection.remotePeer.toString(),
-            });
-        }
-        catch (error) {
-            this.logger.error('Failed to initialize stream manager:', error);
-            throw new oError(oErrorCodes.INTERNAL_ERROR, `Failed to initialize stream manager: ${error.message}`);
-        }
-    }
-    /**
-     * Gets or creates a stream for the connection
-     * Always creates a new stream (no reuse at base layer)
-     *
-     * For limited connections (where caller has identified a reader stream):
-     * - If callerReaderStream exists, wrap and return it for sending requests
-     * - Otherwise, create new stream as normal
-     *
-     * @param protocol - The protocol string for the stream
-     * @param remoteAddress - The remote address for the stream
-     * @param config - Stream handler configuration
-     * @returns Wrapped stream
-     */
-    async getOrCreateStream(protocol, remoteAddress, config = {}) {
-        this.logger.debug('Getting or creating stream', this.callerReaderStream?.protocol, 'and status', this.callerReaderStream?.status);
-        // If we have a caller's reader stream (from limited connection), use it for sending requests
-        if (this.callerReaderStream && this.callerReaderStream.status === 'open') {
-            this.logger.debug('Using caller reader stream for limited connection', {
-                streamId: this.callerReaderStream.id,
-            });
-            // Wrap the reader stream for use (if not already wrapped)
-            const existingWrapped = Array.from(this.streams.values()).find((s) => s.p2pStream.id === this.callerReaderStream.id);
-            if (existingWrapped) {
-                return existingWrapped;
-            }
-            // Wrap the reader stream
-            const wrappedStream = new oNodeStream(this.callerReaderStream, {
-                direction: 'inbound', // It's inbound to us, we write to it
-                reusePolicy: 'reuse',
-                remoteAddress: remoteAddress,
-                streamType: 'request-response',
-            });
-            this.streams.set(this.callerReaderStream.id, wrappedStream);
-            return wrappedStream;
-        }
-        // Always create new stream (no reuse at base layer)
-        return await this.createStream(protocol, remoteAddress, config);
-    }
-    /**
-     * Creates a new stream from the connection
-     *
-     * @param protocol - The protocol string for the stream
-     * @param remoteAddress - The remote address for the stream
-     * @param config - Stream handler configuration
-     * @returns Wrapped stream
-     */
-    async createStream(protocol, remoteAddress, config = {}) {
-        this.logger.debug('Creating new stream', {
-            protocol,
-            currentStreamCount: this.streams.size,
-        });
-        // Create stream from libp2p connection
-        const stream = await this.p2pConnection.newStream(protocol, {
-            signal: config.signal,
-            maxOutboundStreams: config.maxOutboundStreams ?? 1000,
-            runOnLimitedConnection: config.runOnLimitedConnection ?? true,
-        });
-        // Wrap in oNodeStream with metadata
-        const wrappedStream = new oNodeStream(stream, {
-            direction: 'outbound',
-            reusePolicy: 'none', // Always none at base layer
-            remoteAddress: remoteAddress,
-            streamType: 'request-response',
-        });
-        // Track the stream
-        this.streams.set(stream.id, wrappedStream);
-        this.logger.debug('Stream created', {
-            streamId: stream.id,
-            protocol,
-            totalStreams: this.streams.size,
-        });
-        return wrappedStream;
-    }
-    /**
-     * Releases and cleans up a stream
-     *
-     * @param streamId - The ID of the stream to release
-     */
-    async releaseStream(streamId) {
-        const wrappedStream = this.streams.get(streamId);
-        if (!wrappedStream) {
-            this.logger.debug('Stream not found for release', { streamId });
-            return;
-        }
-        this.logger.debug('Releasing stream', { streamId });
-        // Remove from tracking
-        this.streams.delete(streamId);
-        // Close the stream if still open
-        if (wrappedStream.p2pStream.status === 'open') {
-            try {
-                await wrappedStream.p2pStream.close();
-            }
-            catch (error) {
-                this.logger.debug('Error closing stream during release', {
-                    streamId,
-                    error: error.message,
-                });
-            }
-        }
-        this.logger.debug('Stream released', {
-            streamId,
-            remainingStreams: this.streams.size,
-        });
-    }
-    /**
-     * Gets all tracked streams
-     *
-     * @returns Array of wrapped streams
-     */
-    getAllStreams() {
-        return Array.from(this.streams.values());
-    }
-    /**
-     * Gets a stream by its ID
-     * Checks persistent caller streams (reader/writer) and tracked streams
-     *
-     * @param streamId - The ID of the stream to retrieve
-     * @returns The libp2p Stream or undefined if not found
-     */
-    getStreamById(streamId) {
-        // Check caller writer stream
-        if (this.callerWriterStream?.id === streamId) {
-            return this.callerWriterStream;
-        }
-        // Check caller reader stream
-        if (this.callerReaderStream?.id === streamId) {
-            return this.callerReaderStream;
-        }
-        // Check tracked streams
-        const wrappedStream = this.streams.get(streamId);
-        return wrappedStream?.p2pStream;
-    }
-    /**
-     * Emits an async event and waits for the first listener to return a result
-     * This enables event-based request handling with async responses
-     */
-    async emitAsync(event, data) {
-        const listeners = this.eventEmitter.listeners(event);
-        if (listeners.length === 0) {
-            throw new oError(oErrorCodes.INTERNAL_ERROR, `No listener registered for event: ${event}`);
-        }
-        // Call the first listener and await its response
-        const listener = listeners[0];
-        return await listener(data);
-    }
-    /**
-     * Detects if a decoded message is a request
-     * Requests have a 'method' field and no 'result' field
-     */
-    isRequest(message) {
-        return typeof message?.method === 'string' && message.result === undefined;
-    }
-    /**
-     * Detects if a decoded message is a response
-     * Responses have a 'result' field and no 'method' field
-     */
-    isResponse(message) {
-        return message?.result !== undefined && message.method === undefined;
-    }
-    /**
-     * Detects if a decoded message is a stream initialization message
-     * Uses the imported type guard from stream-init-message.ts
-     */
-    isStreamInit(message) {
-        return isStreamInitMessage(message);
-    }
-    /**
-     * Handles a stream initialization message
-     * Stores reference to caller's reader stream for bidirectional communication
-     * Sends acknowledgment back to confirm stream registration
-     *
-     * @param message - The decoded stream init message
-     * @param stream - The stream that sent the message
-     */
-    async handleStreamInitMessage(message, stream) {
-        try {
-            if (message.role === 'reader') {
-                this.callerReaderStream = stream;
-                this.logger.info('Identified caller reader stream', {
-                    streamId: stream.id,
-                    connectionId: message.connectionId,
-                });
-                this.emit(StreamManagerEvent.StreamIdentified, {
-                    streamId: stream.id,
-                    role: message.role,
-                    connectionId: message.connectionId,
-                });
-            }
-            else if (message.role === 'writer') {
-                this.callerWriterStream = stream;
-                this.logger.info('Identified caller writer stream', {
-                    streamId: stream.id,
-                    connectionId: message.connectionId,
-                });
-                this.emit(StreamManagerEvent.StreamIdentified, {
-                    streamId: stream.id,
-                    role: message.role,
-                    connectionId: message.connectionId,
-                });
-            }
-            // Send acknowledgment back to caller
-            const ackMessage = {
-                type: 'stream-init-ack',
-                status: 'success',
-                streamId: stream.id,
-                role: message.role,
-                timestamp: Date.now(),
-            };
-            const ackBytes = new TextEncoder().encode(JSON.stringify(ackMessage));
-            await this.sendLengthPrefixed(stream, ackBytes, {});
-            this.logger.debug('Sent stream-init-ack', {
-                streamId: stream.id,
-                role: message.role,
-            });
-        }
-        catch (error) {
-            this.logger.error('Failed to process stream-init message', error);
-            // Try to send error acknowledgment
-            try {
-                const errorAck = {
-                    type: 'stream-init-ack',
-                    status: 'error',
-                    streamId: stream.id,
-                    role: message.role,
-                    error: error.message,
-                    timestamp: Date.now(),
-                };
-                const errorAckBytes = new TextEncoder().encode(JSON.stringify(errorAck));
-                await this.sendLengthPrefixed(stream, errorAckBytes, {});
-            }
-            catch (ackError) {
-                this.logger.error('Failed to send error acknowledgment', ackError);
-            }
-            throw error;
-        }
-    }
-    /**
-     * Extracts and parses JSON from various formats including:
-     * - Already parsed objects
-     * - Plain JSON
-     * - Markdown code blocks (```json ... ``` or ``` ... ```)
-     * - Mixed content with explanatory text
-     * - JSON5 format (trailing commas, comments, unquoted keys, etc.)
-     *
-     * @param decoded - The decoded string that may contain JSON, or an already parsed object
-     * @returns Parsed JSON object
-     * @throws Error if JSON parsing fails even with JSON5 fallback
-     */
-    extractAndParseJSON(decoded) {
-        // If already an object (not a string), return it directly
-        if (typeof decoded !== 'string') {
-            return decoded;
-        }
-        let jsonString = decoded.trim();
-        // Attempt standard JSON.parse first
-        try {
-            return JSON.parse(jsonString);
-        }
-        catch (jsonError) {
-            this.logger.debug('Standard JSON parse failed, trying JSON5', {
-                error: jsonError.message,
-                position: jsonError.message.match(/position (\d+)/)?.[1],
-                preview: jsonString,
-            });
-            // Fallback to JSON5 for more relaxed parsing
-            try {
-                return JSON5.parse(jsonString);
-            }
-            catch (json5Error) {
-                // Enhanced error with context
-                this.logger.error('JSON5 parse also failed', {
-                    originalError: jsonError.message,
-                    json5Error: json5Error.message,
-                    preview: jsonString.substring(0, 200),
-                    length: jsonString.length,
-                });
-                throw new Error(`Failed to parse JSON: ${jsonError.message}\nJSON5 also failed: ${json5Error.message}\nPreview: ${jsonString.substring(0, 200)}${jsonString.length > 200 ? '...' : ''}`);
-            }
-        }
-    }
-    /**
-     * Sends data through a stream using length-prefixed encoding (libp2p v3 best practice)
-     * Each message is automatically prefixed with a varint indicating the message length
-     * This ensures proper message boundaries and eliminates concatenation issues
-     *
-     * @param stream - The stream to send data through
-     * @param data - The data to send
-     * @param config - Configuration for timeout and other options
-     */
-    async sendLengthPrefixed(stream, data, config = {}) {
-        const lp = lpStream(stream);
-        await lp.write(data, { signal: config.signal });
-    }
-    /**
-     * Tracks an active stream handler
-     */
-    trackStreamHandler(stream, abortController) {
-        this.activeStreamHandlers.set(stream.id, { stream, abortController });
-    }
-    /**
-     * Untracks a stream handler
-     */
-    untrackStreamHandler(streamId) {
-        this.activeStreamHandlers.delete(streamId);
-    }
-    /**
-     * Handles an incoming stream on the server side using length-prefixed protocol
-     * Uses async read loops instead of event listeners (libp2p v3 best practice)
-     * Processes complete messages with proper boundaries
-     *
-     * @param stream - The incoming stream
-     * @param connection - The connection the stream belongs to
-     */
-    async handleIncomingStream(stream, connection) {
-        const lp = lpStream(stream);
-        const abortController = new AbortController();
-        this.trackStreamHandler(stream, abortController);
-        try {
-            while (stream.status === 'open' && !abortController.signal.aborted) {
-                // Read complete length-prefixed message
-                const messageBytes = await lp.read();
-                const decoded = new TextDecoder().decode(messageBytes.subarray());
-                // Parse JSON (handles markdown blocks, mixed content, and JSON5)
-                const message = this.extractAndParseJSON(decoded);
-                if (this.isStreamInit(message)) {
-                    await this.handleStreamInitMessage(message, stream);
-                    // Continue reading for subsequent messages on this stream
-                }
-                else if (this.isRequest(message)) {
-                    await this.handleRequestMessage(message, stream, connection);
-                }
-                else if (this.isResponse(message)) {
-                    this.logger.warn('Received response message on server-side stream, ignoring', message);
-                }
-                else {
-                    this.logger.warn('Received unknown message type', message);
-                }
-            }
-        }
-        catch (error) {
-            // Stream closed or error occurred
-            if (stream.status === 'open') {
-                this.logger.error('Error in length-prefixed stream handler:', error);
-                this.emit(StreamManagerEvent.StreamError, {
-                    streamId: stream.id,
-                    error,
-                    context: 'incoming',
-                });
-            }
-        }
-        finally {
-            this.untrackStreamHandler(stream.id);
-        }
-    }
-    /**
-     * Determines which stream to use for sending the response
-     * Checks for _streamId in request params and routes accordingly
-     *
-     * @param request - The incoming request
-     * @param defaultStream - The stream the request came on (fallback)
-     * @returns The stream to use for the response
-     */
-    getResponseStream(request, defaultStream) {
-        const streamId = request.params._streamId;
-        // If no explicit response stream specified, use the request stream (backward compatibility)
-        if (!streamId) {
-            return defaultStream;
-        }
-        // Check if the response stream is the identified caller writer stream
-        if (this.callerWriterStream && this.callerWriterStream.id === streamId) {
-            this.logger.debug('Routing response to caller writer stream', {
-                requestId: request.id,
-                streamId,
-            });
-            return this.callerWriterStream;
-        }
-        if (this.callerReaderStream && this.callerReaderStream.id === streamId) {
-            this.logger.debug('Routing response to caller reader stream', {
-                requestId: request.id,
-                streamId,
-            });
-            return this.callerReaderStream;
-        }
-        // If specified stream not found, warn and fall back to request stream
-        this.logger.warn('Specified response stream not found, using request stream', {
-            requestId: request.id,
-            streamId,
-        });
-        return defaultStream;
-    }
-    /**
-     * Handles a request message by emitting an event and sending response
-     *
-     * @param message - The decoded request message
-     * @param stream - The stream to send the response on
-     * @param connection - The connection the stream belongs to
-     */
-    async handleRequestMessage(message, stream, connection) {
-        const request = new oRequest(message);
-        const responseBuilder = ResponseBuilder.create();
-        // Determine which stream to use for the response
-        const responseStream = this.getResponseStream(request, stream);
-        try {
-            // Emit InboundRequest event and wait for handler to process
-            const result = await this.emitAsync(StreamManagerEvent.InboundRequest, {
-                request,
-                stream,
-                connection,
-            });
-            const response = await responseBuilder.build(request, result, null);
-            await CoreUtils.sendResponse(response, responseStream);
-            this.logger.debug(`Successfully processed request: method=${request.method}, id=${request.id}`);
-        }
-        catch (error) {
-            this.logger.error(`Error processing request: method=${request.method}, id=${request.id}`, error);
-            const errorResponse = await responseBuilder.buildError(request, error);
-            await CoreUtils.sendResponse(errorResponse, responseStream);
-            this.emit(StreamManagerEvent.StreamError, {
-                streamId: stream.id,
-                error: error instanceof Error ? error : new Error(String(error)),
-                context: 'incoming',
-            });
-        }
-    }
-    /**
-     * Handles an outgoing stream on the client side using length-prefixed protocol
-     * Uses async read loops to process responses with proper message boundaries
-     *
-     * @param stream - The outgoing stream
-     * @param emitter - Event emitter for chunk events
-     * @param config - Configuration including abort signal
-     * @param requestId - Optional request ID to filter responses (for stream reuse scenarios)
-     * @returns Promise that resolves with the final response
-     */
-    async handleOutgoingStream(stream, emitter, config = {}, requestId) {
-        const lp = lpStream(stream);
-        const abortController = new AbortController();
-        this.trackStreamHandler(stream, abortController);
-        // Combine external signal with our internal abort controller
-        const combinedSignal = config.signal
-            ? AbortSignal.any([config.signal, abortController.signal])
-            : abortController.signal;
-        try {
-            while (stream.status === 'open' && !combinedSignal.aborted) {
-                this.logger.debug('Waiting for response...');
-                // Read complete length-prefixed message
-                const messageBytes = await lp.read({ signal: combinedSignal });
-                const decoded = new TextDecoder().decode(messageBytes.subarray());
-                // Parse JSON (handles markdown blocks, mixed content, and JSON5)
-                const message = this.extractAndParseJSON(decoded);
-                if (this.isResponse(message)) {
-                    const response = new oResponse({
-                        ...message.result,
-                        id: message.id,
-                    });
-                    // Filter by request ID if provided
-                    if (requestId !== undefined && response.id !== requestId) {
-                        this.logger.debug(`Ignoring response for different request (expected: ${requestId}, received: ${response.id})`);
-                        continue;
-                    }
-                    // Emit chunk for streaming responses
-                    emitter.emit('chunk', response);
-                    // Check if this is the last chunk
-                    if (response.result._last || !response.result._isStreaming) {
-                        return response;
-                    }
-                }
-                else if (this.isRequest(message)) {
-                    // Process incoming router requests via event emission
-                    const hasListeners = this.eventEmitter.listenerCount(StreamManagerEvent.InboundRequest) >
-                        0;
-                    if (hasListeners) {
-                        this.logger.debug('Received router request on client-side stream, processing...', message);
-                        // Use handleRequestMessage which emits the InboundRequest event
-                        await this.handleRequestMessage(message, stream, this.p2pConnection);
-                    }
-                    else {
-                        this.logger.warn('Received request message on client-side stream, ignoring (no handler)', message);
-                    }
-                }
-                else {
-                    this.logger.warn('Received unknown message type', message);
-                }
-            }
-            throw new oError(oErrorCodes.TIMEOUT, 'Stream closed before response received');
-        }
-        catch (error) {
-            this.emit(StreamManagerEvent.StreamError, {
-                streamId: stream.id,
-                error: error instanceof Error ? error : new Error(String(error)),
-                context: 'outgoing',
-            });
-            if (combinedSignal.aborted) {
-                throw new oError(oErrorCodes.TIMEOUT, 'Request aborted');
-            }
-            throw error;
-        }
-        finally {
-            this.untrackStreamHandler(stream.id);
-        }
-    }
-    /**
-     * Forwards a request to the next hop and relays response chunks back
-     * This implements the middleware/proxy pattern for intermediate nodes
-     *
-     * @param request - The router request to forward
-     * @param incomingStream - The stream to send responses back on
-     * @param dialFn - Function to dial the next hop connection
-     */
-    async forwardRequest(request, incomingStream, dialFn) {
-        try {
-            // Connect to next hop
-            const nextHopConnection = await dialFn(request.params.address);
-            // Set up chunk relay - forward responses from next hop back to incoming stream
-            nextHopConnection.onChunk(async (response) => {
-                try {
-                    await CoreUtils.sendResponse(response, incomingStream);
-                }
-                catch (error) {
-                    this.logger.error('Error forwarding chunk:', error);
-                }
-            });
-            // Transmit the request to next hop
-            await nextHopConnection.transmit(request);
-        }
-        catch (error) {
-            this.logger.error('Error forwarding request:', error);
-            // Send error response back on incoming stream using ResponseBuilder
-            const responseBuilder = ResponseBuilder.create();
-            const errorResponse = await responseBuilder.buildError(request, error);
-            await CoreUtils.sendResponse(errorResponse, incomingStream);
-        }
-    }
-    /**
-     * Close the stream manager and cleanup resources
-     */
-    async close() {
-        this.logger.info('Closing stream manager', {
-            activeStreams: this.streams.size,
-            activeHandlers: this.activeStreamHandlers.size,
-        });
-        // Abort all active stream handlers
-        for (const [streamId, { abortController },] of this.activeStreamHandlers.entries()) {
-            abortController.abort();
-        }
-        this.activeStreamHandlers.clear();
-        // Close all tracked streams
-        const closePromises = Array.from(this.streams.values()).map(async (wrappedStream) => {
-            try {
-                if (wrappedStream.p2pStream.status === 'open') {
-                    await wrappedStream.p2pStream.close();
-                }
-            }
-            catch (error) {
-                this.logger.debug('Error closing stream during manager close', {
-                    streamId: wrappedStream.p2pStream.id,
-                    error: error.message,
-                });
-            }
-        });
-        await Promise.all(closePromises);
-        // Clear tracking
-        this.streams.clear();
-        this.isInitialized = false;
-        this.emit(StreamManagerEvent.ManagerClosed, undefined);
-        this.logger.info('Stream manager closed');
-    }
-    /**
-     * Add event listener
-     */
-    on(event, listener) {
-        this.eventEmitter.on(event, listener);
-    }
-    /**
-     * Remove event listener
-     */
-    off(event, listener) {
-        this.eventEmitter.off(event, listener);
-    }
-    /**
-     * Emit event
-     */
-    emit(event, data) {
-        this.eventEmitter.emit(event, data);
-    }
-}