@olane/o-node 0.7.12-alpha.9 → 0.7.13-alpha.0

package/dist/src/connection/interfaces/o-node-connection-manager.config.d.ts

@@ -2,5 +2,6 @@ import { oConnectionManagerConfig } from '@olane/o-core';
 import { Libp2p } from '@olane/o-config';
 export interface oNodeConnectionManagerConfig extends oConnectionManagerConfig {
     p2pNode: Libp2p;
+    runOnLimitedConnection?: boolean;
 }
 //# sourceMappingURL=o-node-connection-manager.config.d.ts.map

package/dist/src/connection/interfaces/o-node-connection-manager.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection-manager.config.d.ts","sourceRoot":"","sources":["../../../../src/connection/interfaces/o-node-connection-manager.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"o-node-connection-manager.config.d.ts","sourceRoot":"","sources":["../../../../src/connection/interfaces/o-node-connection-manager.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC"}

package/dist/src/connection/interfaces/o-node-connection.config.d.ts

@@ -2,5 +2,6 @@ import { Connection } from '@olane/o-config';
 import { oConnectionConfig } from '@olane/o-core';
 export interface oNodeConnectionConfig extends oConnectionConfig {
     p2pConnection: Connection;
+    runOnLimitedConnection?: boolean;
 }
 //# sourceMappingURL=o-node-connection.config.d.ts.map

package/dist/src/connection/interfaces/o-node-connection.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.config.d.ts","sourceRoot":"","sources":["../../../../src/connection/interfaces/o-node-connection.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,aAAa,EAAE,UAAU,CAAC;CAC3B"}
+{"version":3,"file":"o-node-connection.config.d.ts","sourceRoot":"","sources":["../../../../src/connection/interfaces/o-node-connection.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,aAAa,EAAE,UAAU,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC"}

package/dist/src/connection/o-node-connection.d.ts

@@ -1,13 +1,18 @@
 import { Connection, Stream } from '@olane/o-config';
 import { oConnection, oRequest, oResponse } from '@olane/o-core';
 import { oNodeConnectionConfig } from './interfaces/o-node-connection.config.js';
+import { StreamHandler } from './stream-handler.js';
 export declare class oNodeConnection extends oConnection {
     protected readonly config: oNodeConnectionConfig;
     p2pConnection: Connection;
+    protected streamHandler: StreamHandler;
     constructor(config: oNodeConnectionConfig);
-    read(source: Stream): Promise<any>;
-    validate(): void;
+    setupConnectionListeners(): void;
+    validate(stream?: Stream): void;
+    getOrCreateStream(): Promise<Stream>;
     transmit(request: oRequest): Promise<oResponse>;
+    postTransmit(stream: Stream): Promise<void>;
+    abort(error: Error): Promise<void>;
     close(): Promise<void>;
 }
 //# sourceMappingURL=o-node-connection.d.ts.map

package/dist/src/connection/o-node-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAIV,MAAM,EAEP,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,qBAAa,eAAgB,SAAQ,WAAW;IAGlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAFrD,aAAa,EAAE,UAAU,CAAC;gBAEF,MAAM,EAAE,qBAAqB;IAKtD,IAAI,CAAC,MAAM,EAAE,MAAM;IAWzB,QAAQ;IAOF,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IAiD/C,KAAK;CAKZ"}
+{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,qBAAa,eAAgB,SAAQ,WAAW;IAIlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAHrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;gBAER,MAAM,EAAE,qBAAqB;IAO5D,wBAAwB;IAYxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAmBlB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA0C/C,YAAY,CAAC,MAAM,EAAE,MAAM;IAQ3B,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}

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

@@ -1,52 +1,65 @@
-import { Uint8ArrayList, byteStream, } from '@olane/o-config';
-import { oConnection, oError, oErrorCodes, oResponse, } from '@olane/o-core';
+import { oConnection, oError, oErrorCodes, } from '@olane/o-core';
+import { StreamHandler } from './stream-handler.js';
 export class oNodeConnection extends oConnection {
     constructor(config) {
         super(config);
         this.config = config;
         this.p2pConnection = config.p2pConnection;
+        this.streamHandler = new StreamHandler(this.logger);
+        this.setupConnectionListeners();
     }
-    async read(source) {
-        const bytes = byteStream(source);
-        const output = await bytes.read({
-            signal: AbortSignal.timeout(120000), // 2 min timeout
+    setupConnectionListeners() {
+        this.logger.debug('Setting up connection listeners for address: ' +
+            this.nextHopAddress.toString());
+        this.p2pConnection?.addEventListener('close', () => {
+            this.logger.debug('Connection closed for address: ' + this.nextHopAddress.toString());
         });
-        const outputObj = output instanceof Uint8ArrayList ? output.subarray() : output;
-        const jsonStr = new TextDecoder().decode(outputObj);
-        return JSON.parse(jsonStr);
     }
-    validate() {
+    validate(stream) {
         if (this.config.p2pConnection.status !== 'open') {
             throw new Error('Connection is not valid');
         }
         // do nothing
+        if (!stream || (stream.status !== 'open' && stream.status !== 'reset')) {
+            throw new oError(oErrorCodes.FAILED_TO_DIAL_TARGET, 'Failed to dial target');
+        }
+        if (stream.status === 'reset') {
+            throw new oError(oErrorCodes.CONNECTION_LIMIT_REACHED, 'Connection limit reached');
+        }
+    }
+    async getOrCreateStream() {
+        const streamConfig = {
+            signal: this.abortSignal,
+            maxOutboundStreams: process.env.MAX_OUTBOUND_STREAMS
+                ? parseInt(process.env.MAX_OUTBOUND_STREAMS)
+                : 1000,
+            runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
+            reusePolicy: 'none', // Default policy, can be overridden in subclasses
+            drainTimeoutMs: this.config.drainTimeoutMs,
+        };
+        return this.streamHandler.getOrCreateStream(this.p2pConnection, this.nextHopAddress.protocol, streamConfig);
     }
     async transmit(request) {
         try {
-            const stream = await this.p2pConnection.newStream(this.nextHopAddress.protocol, {
-                maxOutboundStreams: Infinity,
-                runOnLimitedConnection: true, // TODO: should this be configurable?
-            });
-            if (!stream || (stream.status !== 'open' && stream.status !== 'reset')) {
-                throw new oError(oErrorCodes.FAILED_TO_DIAL_TARGET, 'Failed to dial target');
-            }
-            if (stream.status === 'reset') {
-                throw new oError(oErrorCodes.CONNECTION_LIMIT_REACHED, 'Connection limit reached');
+            if (this.config.runOnLimitedConnection) {
+                this.logger.debug('Running on limited connection...');
             }
-            // Send the data with backpressure handling (libp2p v3 best practice)
+            const stream = await this.getOrCreateStream();
+            this.validate(stream);
+            const streamConfig = {
+                signal: this.abortSignal,
+                drainTimeoutMs: this.config.drainTimeoutMs,
+                reusePolicy: 'none', // Default policy
+            };
+            // Send the request with backpressure handling
             const data = new TextEncoder().encode(request.toString());
-            const sent = stream.send(data);
-            // If send() returns false, wait for the stream to drain before continuing
-            if (!sent) {
-                this.logger.debug('Stream buffer full, waiting for drain...');
-                await stream.onDrain({ signal: AbortSignal.timeout(30000) }); // 30 second timeout
-            }
-            const res = await this.read(stream);
-            await stream.close();
-            // process the response
-            const response = new oResponse({
-                ...res.result,
-            });
+            await this.streamHandler.send(stream, data, streamConfig);
+            // Handle response using StreamHandler
+            // Pass request handler if configured to enable bidirectional stream processing
+            // Pass request ID to enable proper response correlation on shared streams
+            const response = await this.streamHandler.handleOutgoingStream(stream, this.emitter, streamConfig, this.config.requestHandler, request.id);
+            // Handle cleanup of the stream
+            await this.postTransmit(stream);
             return response;
         }
         catch (error) {
@@ -56,6 +69,17 @@ export class oNodeConnection extends oConnection {
             throw error;
         }
     }
+    async postTransmit(stream) {
+        const streamConfig = {
+            reusePolicy: 'none', // Default policy, can be overridden in subclasses
+        };
+        await this.streamHandler.close(stream, streamConfig);
+    }
+    async abort(error) {
+        this.logger.debug('Aborting connection');
+        await this.p2pConnection.abort(error);
+        this.logger.debug('Connection aborted');
+    }
     async close() {
         this.logger.debug('Closing connection');
         await this.p2pConnection.close();

package/dist/src/connection/o-node-connection.manager.d.ts

@@ -1,17 +1,32 @@
 import { oAddress, oConnectionConfig, oConnectionManager } from '@olane/o-core';
-import { oConnection } from '@olane/o-core';
+import { Libp2p, Connection } from '@olane/o-config';
 import { oNodeConnectionManagerConfig } from './interfaces/o-node-connection-manager.config.js';
 import { oNodeConnection } from './o-node-connection.js';
 export declare class oNodeConnectionManager extends oConnectionManager {
-    private p2pNode;
+    readonly config: oNodeConnectionManagerConfig;
+    protected p2pNode: Libp2p;
+    private defaultReadTimeoutMs?;
+    private defaultDrainTimeoutMs?;
+    private connections;
     constructor(config: oNodeConnectionManagerConfig);
+    getOrCreateConnection(nextHopAddress: oAddress, address: oAddress): Promise<Connection>;
     /**
-     * Connect to a given address with exponential backoff retry
-     * @param address - The address to connect to
+     * Connect to a given address, reusing libp2p connections when possible
+     * @param config - Connection configuration
      * @returns The connection object
      */
     connect(config: oConnectionConfig): Promise<oNodeConnection>;
+    /**
+     * Check if libp2p has an active connection to the target peer
+     * @param address - The address to check
+     * @returns true if an active connection exists
+     */
     isCached(address: oAddress): boolean;
-    getCachedConnection(address: oAddress): oConnection | null;
+    /**
+     * Get an existing libp2p connection to the target peer
+     * @param address - The address to get a connection for
+     * @returns The libp2p Connection object or null if not found
+     */
+    getCachedLibp2pConnection(address: oAddress): Connection | null;
 }
 //# sourceMappingURL=o-node-connection.manager.d.ts.map

package/dist/src/connection/o-node-connection.manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC5D,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,4BAA4B;IAKhD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqFlE,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAIpC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI;CAe3D"}
+{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAMhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IALzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,WAAW,CAAsC;gBAEpC,MAAM,EAAE,4BAA4B;IAOnD,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;IAoCtB;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IA4BpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;CAmChE"}

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

@@ -3,86 +3,116 @@ import { oNodeConnection } from './o-node-connection.js';
 export class oNodeConnectionManager extends oConnectionManager {
     constructor(config) {
         super(config);
+        this.config = config;
+        this.connections = new Map();
         this.p2pNode = config.p2pNode;
+        this.defaultReadTimeoutMs = config.defaultReadTimeoutMs;
+        this.defaultDrainTimeoutMs = config.defaultDrainTimeoutMs;
+    }
+    async getOrCreateConnection(nextHopAddress, address) {
+        // Check if libp2p already has an active connection to this peer
+        const existingConnection = this.getCachedLibp2pConnection(nextHopAddress);
+        let p2pConnection;
+        if (existingConnection && existingConnection.status === 'open') {
+            this.logger.debug('Reusing existing libp2p connection for address: ' +
+                nextHopAddress.toString());
+            p2pConnection = existingConnection;
+        }
+        else {
+            // No existing connection or connection is closed, dial a new one
+            this.logger.debug('Dialing new connection for address: ' + address.toString());
+            p2pConnection = await this.p2pNode.dial(nextHopAddress.libp2pTransports.map((ma) => ma.toMultiaddr()));
+        }
+        if (nextHopAddress.libp2pTransports.length) {
+            const peerIdString = nextHopAddress.libp2pTransports[0].toPeerId();
+            if (peerIdString) {
+                this.connections.set(peerIdString, p2pConnection);
+            }
+        }
+        return p2pConnection;
     }
     /**
-     * Connect to a given address with exponential backoff retry
-     * @param address - The address to connect to
+     * Connect to a given address, reusing libp2p connections when possible
+     * @param config - Connection configuration
      * @returns The connection object
      */
     async connect(config) {
-        const { address, nextHopAddress, callerAddress } = config;
-        // check if we already have a connection to this address
-        // TODO: how can we enable caching of connections & connection lifecycles
-        if (this.isCached(nextHopAddress)) {
-            const cachedConnection = this.getCachedConnection(nextHopAddress);
-            if (cachedConnection &&
-                cachedConnection.p2pConnection.status === 'open') {
-                this.logger.debug('Using cached connection for address: ' + address.toString());
-                return cachedConnection;
+        const { address, nextHopAddress, callerAddress, readTimeoutMs, drainTimeoutMs, } = config;
+        const p2pConnection = await this.getOrCreateConnection(nextHopAddress, address);
+        const connection = new oNodeConnection({
+            nextHopAddress: nextHopAddress,
+            address: address,
+            p2pConnection: p2pConnection,
+            callerAddress: callerAddress,
+            readTimeoutMs: readTimeoutMs ?? this.defaultReadTimeoutMs,
+            drainTimeoutMs: drainTimeoutMs ?? this.defaultDrainTimeoutMs,
+            isStream: config.isStream ?? false,
+            abortSignal: config.abortSignal,
+            runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
+            requestHandler: config.requestHandler ?? undefined,
+        });
+        return connection;
+    }
+    /**
+     * Check if libp2p has an active connection to the target peer
+     * @param address - The address to check
+     * @returns true if an active connection exists
+     */
+    isCached(address) {
+        try {
+            const nodeAddress = address;
+            if (!nodeAddress.libp2pTransports ||
+                nodeAddress.libp2pTransports.length === 0) {
+                return false;
             }
-            else {
-                // cached item is not valid, remove it
-                this.cache.delete(nextHopAddress.toString());
+            // Extract peer ID from the first transport
+            const peerIdString = nodeAddress.libp2pTransports[0].toPeerId();
+            if (!peerIdString) {
+                return false;
             }
+            this.logger.debug('Peer ID string:', peerIdString);
+            // the following works since the peer id param is not really required: https://github.com/libp2p/js-libp2p/blob/0bbf5021b53938b2bffcffca6c13c479a95c2a60/packages/libp2p/src/connection-manager/index.ts#L508
+            const connections = this.p2pNode.getConnections(peerIdString); // ignore since converting to a proper peer id breaks the browser implementation
+            // Check if we have at least one open connection
+            return connections.some((conn) => conn.status === 'open');
         }
-        // Retry configuration for handling transient connection failures
-        const MAX_RETRIES = 3;
-        const BASE_DELAY_MS = 1000; // Start with 1 second
-        const MAX_DELAY_MS = 10000; // Cap at 10 seconds
-        // first time setup connection with retry logic
-        let lastError;
-        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            try {
-                if (attempt > 0) {
-                    // Calculate exponential backoff delay: 1s, 2s, 4s, 8s (capped at MAX_DELAY_MS)
-                    const delay = Math.min(BASE_DELAY_MS * Math.pow(2, attempt - 1), MAX_DELAY_MS);
-                    this.logger.debug(`Retry attempt ${attempt}/${MAX_RETRIES} for ${nextHopAddress.toString()} after ${delay}ms delay`);
-                    await new Promise((resolve) => setTimeout(resolve, delay));
-                }
-                const p2pConnection = await this.p2pNode.dial(nextHopAddress.libp2pTransports.map((ma) => ma.toMultiaddr()));
-                const connection = new oNodeConnection({
-                    nextHopAddress: nextHopAddress,
-                    address: address,
-                    p2pConnection: p2pConnection,
-                    callerAddress: callerAddress,
-                });
-                if (attempt > 0) {
-                    this.logger.info(`Successfully connected to ${nextHopAddress.toString()} on retry attempt ${attempt}`);
-                }
-                // this.cache.set(nextHopAddress.toString(), connection);
-                return connection;
-            }
-            catch (error) {
-                lastError = error;
-                this.logger.warn(`[${callerAddress?.toString() || 'unknown'}] Connection attempt ${attempt + 1}/${MAX_RETRIES + 1} failed for ${nextHopAddress.toString()}: ${error instanceof Error ? error.message : String(error)}`);
-                // Don't retry on the last attempt
-                if (attempt === MAX_RETRIES) {
-                    break;
-                }
-            }
+        catch (error) {
+            this.logger.debug('Error checking cached connection:', error);
+            return false;
         }
-        // All retries exhausted
-        this.logger.error(`[${callerAddress?.toString() || 'unknown'}] Failed to connect after ${MAX_RETRIES + 1} attempts to address! Next hop: ${nextHopAddress} With Address: ${address.toString()}`, lastError);
-        throw lastError;
     }
-    isCached(address) {
-        return this.cache.has(address.toString());
-    }
-    getCachedConnection(address) {
-        const key = address.toString();
+    /**
+     * Get an existing libp2p connection to the target peer
+     * @param address - The address to get a connection for
+     * @returns The libp2p Connection object or null if not found
+     */
+    getCachedLibp2pConnection(address) {
         try {
-            const connection = this.cache.get(key);
-            if (!connection) {
-                throw new Error('Connection not found in cache');
+            const nodeAddress = address;
+            if (!nodeAddress.libp2pTransports.length) {
+                return null;
+            }
+            const peerIdString = nodeAddress.libp2pTransports[0].toPeerId();
+            if (!peerIdString) {
+                return null;
+            }
+            const connections = this.p2pNode.getConnections(); // ignore since converting to a proper peer id breaks the browser implementation
+            const filteredConnections = connections.filter((conn) => conn.remotePeer?.toString() === peerIdString);
+            // Return the first open connection, or null if none exist
+            const openConnection = filteredConnections.find((conn) => conn.status === 'open');
+            if (openConnection) {
+                return openConnection;
+            }
+            const connection = this.connections.get(peerIdString);
+            if (connection?.status === 'open') {
+                return connection;
             }
-            connection.validate();
-            return connection;
+            // Return the first open connection, or null if none exist
+            return connection ?? null;
         }
         catch (error) {
-            this.cache.delete(key);
-            this.logger.error('Error getting cached connection:', error);
+            this.logger.debug('Error getting cached connection:', error);
+            return null;
         }
-        return null;
     }
 }

package/dist/src/connection/o-stream.request.d.ts

@@ -0,0 +1,11 @@
+import { Request, RequestId } from '@olane/o-protocol';
+import { oRequest } from '@olane/o-core';
+import { Stream } from '@olane/o-config';
+export declare class oStreamRequest extends oRequest {
+    stream: Stream;
+    constructor(config: Request & {
+        id: RequestId;
+        stream: Stream;
+    });
+}
+//# sourceMappingURL=o-stream.request.d.ts.map

package/dist/src/connection/o-stream.request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-stream.request.d.ts","sourceRoot":"","sources":["../../../src/connection/o-stream.request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,MAAM,EAAE,MAAM,CAAC;gBACH,MAAM,EAAE,OAAO,GAAG;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAIhE"}

package/dist/src/connection/o-stream.request.js

@@ -0,0 +1,7 @@
+import { oRequest } from '@olane/o-core';
+export class oStreamRequest extends oRequest {
+    constructor(config) {
+        super(config);
+        this.stream = config.stream;
+    }
+}

package/dist/src/connection/stream-handler.config.d.ts

@@ -0,0 +1,46 @@
+/// <reference types="node" />
+import type { Stream } from '@libp2p/interface';
+/**
+ * Stream reuse policy determines how streams are managed across multiple requests
+ */
+export type StreamReusePolicy = 'none' | 'reuse' | 'pool';
+/**
+ * Configuration for StreamHandler behavior
+ */
+export interface StreamHandlerConfig {
+    /**
+     * Stream reuse policy:
+     * - 'none': Create new stream for each request (default)
+     * - 'reuse': Reuse existing open streams
+     * - 'pool': (Future) Maintain a pool of streams
+     */
+    reusePolicy?: StreamReusePolicy;
+    /**
+     * Timeout in milliseconds to wait for stream drain when buffer is full
+     * @default 30000 (30 seconds)
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Whether this connection can run on limited connections
+     * @default false
+     */
+    runOnLimitedConnection?: boolean;
+    /**
+     * Maximum number of outbound streams
+     * @default 1000
+     */
+    maxOutboundStreams?: number;
+    /**
+     * AbortSignal for cancellation
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Context for stream lifecycle operations
+ */
+export interface StreamContext {
+    stream: Stream;
+    protocol: string;
+    config: StreamHandlerConfig;
+}
+//# sourceMappingURL=stream-handler.config.d.ts.map

package/dist/src/connection/stream-handler.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-handler.config.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.config.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;CAC7B"}

package/dist/src/connection/stream-handler.config.js

@@ -0,0 +1 @@
+export {};

package/dist/src/connection/stream-handler.d.ts

@@ -0,0 +1,98 @@
+/// <reference types="node" />
+import type { Connection, Stream } from '@libp2p/interface';
+import { EventEmitter } from 'events';
+import { oRequest, oResponse, Logger } from '@olane/o-core';
+import type { oRouterRequest } from '@olane/o-core';
+import type { oConnection } from '@olane/o-core';
+import type { RunResult } from '@olane/o-tool';
+import type { StreamHandlerConfig } from './stream-handler.config.js';
+/**
+ * StreamHandler centralizes all stream-related functionality including:
+ * - Message type detection (request vs response)
+ * - Stream lifecycle management (create, reuse, close)
+ * - Backpressure handling
+ * - Request/response handling
+ * - Stream routing for middleware nodes
+ */
+export declare class StreamHandler {
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Detects if a decoded message is a request
+     * Requests have a 'method' field and no 'result' field
+     */
+    isRequest(message: any): boolean;
+    /**
+     * Detects if a decoded message is a response
+     * Responses have a 'result' field and no 'method' field
+     */
+    isResponse(message: any): boolean;
+    /**
+     * Decodes a stream message event into a JSON object
+     */
+    decodeMessage(event: any): Promise<any>;
+    /**
+     * Gets an existing open stream or creates a new one based on reuse policy
+     *
+     * @param connection - The libp2p connection
+     * @param protocol - The protocol to use for the stream
+     * @param config - Stream handler configuration
+     */
+    getOrCreateStream(connection: Connection, protocol: string, config?: StreamHandlerConfig): Promise<Stream>;
+    /**
+     * Sends data through a stream with backpressure handling
+     *
+     * @param stream - The stream to send data through
+     * @param data - The data to send
+     * @param config - Configuration for timeout and other options
+     */
+    send(stream: Stream, data: Uint8Array, config?: StreamHandlerConfig): Promise<void>;
+    /**
+     * Closes a stream safely with error handling
+     *
+     * @param stream - The stream to close
+     * @param config - Configuration including reuse policy
+     */
+    close(stream: Stream, config?: StreamHandlerConfig): Promise<void>;
+    /**
+     * Handles an incoming stream on the server side
+     * Attaches message listener immediately (libp2p v3 best practice)
+     * Routes requests or executes tools based on the message
+     *
+     * @param stream - The incoming stream
+     * @param connection - The connection the stream belongs to
+     * @param toolExecutor - Function to execute tools for requests
+     */
+    handleIncomingStream(stream: Stream, connection: Connection, toolExecutor: (request: oRequest, stream: Stream) => Promise<RunResult>): Promise<void>;
+    /**
+     * Handles a request message by executing the tool and sending response
+     *
+     * @param message - The decoded request message
+     * @param stream - The stream to send the response on
+     * @param toolExecutor - Function to execute the tool
+     */
+    private handleRequestMessage;
+    /**
+     * Handles an outgoing stream on the client side
+     * Listens for response messages and emits them via the event emitter
+     * If requestHandler is provided, also processes incoming router requests
+     *
+     * @param stream - The outgoing stream
+     * @param emitter - Event emitter for chunk events
+     * @param config - Configuration including abort signal
+     * @param requestHandler - Optional handler for processing router requests received on this stream
+     * @param requestId - Optional request ID to filter responses (for stream reuse scenarios)
+     * @returns Promise that resolves with the final response
+     */
+    handleOutgoingStream(stream: Stream, emitter: EventEmitter, config?: StreamHandlerConfig, requestHandler?: (request: oRequest, stream: Stream) => Promise<RunResult>, requestId?: string | number): Promise<oResponse>;
+    /**
+     * 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
+     */
+    forwardRequest(request: oRouterRequest, incomingStream: Stream, dialFn: (address: string) => Promise<oConnection>): Promise<void>;
+}
+//# sourceMappingURL=stream-handler.d.ts.map

package/dist/src/connection/stream-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-handler.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACL,QAAQ,EACR,SAAS,EAIT,MAAM,EAEP,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,CAAC,EAAE,MAAM;IAI3B;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAIhC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAIjC;;OAEG;IACG,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAI7C;;;;;;OAMG;IACG,iBAAiB,CACrB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,MAAM,CAAC;IAsClB;;;;;;OAMG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;OAKG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5E;;;;;;;;OAQG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,GACtE,OAAO,CAAC,IAAI,CAAC;IAuChB;;;;;;OAMG;YACW,oBAAoB;IA4BlC;;;;;;;;;;;OAWG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,mBAAwB,EAChC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,EAC1E,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAC1B,OAAO,CAAC,SAAS,CAAC;IA+GrB;;;;;;;OAOG;IACG,cAAc,CAClB,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC;CAyBjB"}