@olane/o-node 0.7.45 → 0.7.47

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

@@ -13,6 +13,10 @@ export declare class oNodeConnection extends oConnection {
     constructor(config: oNodeConnectionConfig);
     get remotePeerId(): import("@olane/o-config").PeerId;
     get remoteAddr(): import("@olane/o-config").Multiaddr;
+    /**
+     * Get the connection configuration for compatibility checking.
+     */
+    get connectionConfig(): oNodeConnectionConfig;
     supportsAddress(address: oNodeAddress): boolean;
     getOrCreateStream(): Promise<oNodeConnectionStream>;
     createStream(): Promise<oNodeConnectionStream>;

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,EAAE,UAAU,EAAU,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;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAO5D,IAAI,YAAY,qCAEf;IAED,IAAI,UAAU,wCAEb;IAED,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAMzC,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAanD,YAAY,IAAI,OAAO,CAAC,qBAAqB,CAAC;IA6BpD,IAAI,OAAO,IAAI,qBAAqB,EAAE,CAcrC;IAEK,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA6C/C,YAAY,CAAC,MAAM,EAAE,qBAAqB;IAI1C,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}
+{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAU,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;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAQ5D,IAAI,YAAY,qCAEf;IAED,IAAI,UAAU,wCAEb;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,qBAAqB,CAE5C;IAED,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAMzC,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAkBnD,YAAY,IAAI,OAAO,CAAC,qBAAqB,CAAC;IA6BpD,IAAI,OAAO,IAAI,qBAAqB,EAAE,CAcrC;IAEK,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA6C/C,YAAY,CAAC,MAAM,EAAE,qBAAqB;IAI1C,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}

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

@@ -8,6 +8,7 @@ export class oNodeConnection extends oConnection {
         this.p2pConnection = config.p2pConnection;
         this.streamHandler = new StreamHandler(this.logger);
         this.reusePolicy = config.reusePolicy ?? 'none';
+        console.log('oNodeConnection constructor', this.reusePolicy);
     }
     get remotePeerId() {
         return this.p2pConnection.remotePeer;
@@ -15,16 +16,27 @@ export class oNodeConnection extends oConnection {
     get remoteAddr() {
         return this.p2pConnection.remoteAddr;
     }
+    /**
+     * Get the connection configuration for compatibility checking.
+     */
+    get connectionConfig() {
+        return this.config;
+    }
     supportsAddress(address) {
         return address.libp2pTransports.some((transport) => {
             return transport.toString() === this.remoteAddr.toString();
         });
     }
     async getOrCreateStream() {
-        if (this.reusePolicy === 'reuse' && this.streams.length > 0) {
-            this.logger.debug('Returning reuse stream: ', this.streams[0].p2pStream.protocol);
+        console.log('getOrCreateStream', this.reusePolicy);
+        if (this.reusePolicy === 'reuse') {
+            this.logger.debug('Reusing stream...');
             // search for streams that allow re-use
-            return this.streams[0];
+            if (this.streams.length > 0) {
+                this.logger.debug('Returning reuse stream: ', this.streams[0].p2pStream.protocol);
+                // search for streams that allow re-use
+                return this.streams[0];
+            }
         }
         return this.createStream();
     }

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

@@ -9,6 +9,8 @@ export declare class oNodeConnectionManager extends oConnectionManager {
     private defaultDrainTimeoutMs?;
     private connectionsByAddress;
     private pendingDialsByAddress;
+    /** Cache of oNodeConnection instances keyed by p2p connection ID */
+    private nodeConnectionByConnectionId;
     constructor(config: oNodeConnectionManagerConfig);
     /**
      * Set up listeners to maintain connection cache state
@@ -36,6 +38,17 @@ export declare class oNodeConnectionManager extends oConnectionManager {
      * @returns The best connection or null if none are suitable
      */
     private selectBestConnection;
+    /**
+     * Get a cached oNodeConnection for the given p2p connection if it exists and is valid.
+     * @param p2pConnection - The p2p connection to look up
+     * @returns A valid oNodeConnection or null if none found
+     */
+    private getCachedNodeConnection;
+    /**
+     * Cache an oNodeConnection by its p2p connection ID for potential reuse.
+     * @param conn - The oNodeConnection to cache
+     */
+    private cacheNodeConnection;
     getOrCreateConnection(nextHopAddress: oAddress, address: oAddress): Promise<Connection>;
     private performDial;
     answer(config: oConnectionConfig & {
@@ -43,7 +56,7 @@ export declare class oNodeConnectionManager extends oConnectionManager {
         reuse?: boolean;
     }): Promise<oNodeConnection>;
     /**
-     * Connect to a given address, reusing libp2p connections when possible
+     * Connect to a given address, reusing oNodeConnection and libp2p connections when possible
      * @param config - Connection configuration
      * @returns The connection object
      */
@@ -68,6 +81,7 @@ export declare class oNodeConnectionManager extends oConnectionManager {
         cachedAddresses: number;
         totalCachedConnections: number;
         pendingDials: number;
+        cachedNodeConnections: number;
         connectionsByPeer: Array<{
             peerId: string;
             status: string;
@@ -79,5 +93,10 @@ export declare class oNodeConnectionManager extends oConnectionManager {
      * @returns Number of connections removed
      */
     cleanupStaleConnections(): number;
+    /**
+     * Clean up all stale oNodeConnections from cache
+     * @returns Number of oNodeConnections removed
+     */
+    cleanupStaleNodeConnections(): number;
 }
 //# 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,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;IAQhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IAPzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CACjB;gBAES,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IASrB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IA6DtB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YA+ER,WAAW;IAwBnB,MAAM,CACV,MAAM,EAAE,iBAAiB,GAAG;QAAE,aAAa,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACzE,OAAO,CAAC,eAAe,CAAC;IAwC3B;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IA8CpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA0D/D;;;OAGG;IACH,aAAa,IAAI;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,KAAK,CAAC;YACvB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;KACJ;IAyBD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;CAuBlC"}
+{"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;IAUhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IATzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CAA+C;IAC5E,oEAAoE;IACpE,OAAO,CAAC,4BAA4B,CACxB;gBAES,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IASrB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IA8D5B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAIrB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YAgFR,WAAW;IAwBnB,MAAM,CACV,MAAM,EAAE,iBAAiB,GAAG;QAAE,aAAa,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACzE,OAAO,CAAC,eAAe,CAAC;IA2C3B;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6ClE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAiDpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA6D/D;;;OAGG;IACH,aAAa,IAAI;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,YAAY,EAAE,MAAM,CAAC;QACrB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,iBAAiB,EAAE,KAAK,CAAC;YACvB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;KACJ;IA6BD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;IA6BjC;;;OAGG;IACH,2BAA2B,IAAI,MAAM;CAgBtC"}

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

@@ -6,6 +6,8 @@ export class oNodeConnectionManager extends oConnectionManager {
         this.config = config;
         this.connectionsByAddress = new Map();
         this.pendingDialsByAddress = new Map();
+        /** Cache of oNodeConnection instances keyed by p2p connection ID */
+        this.nodeConnectionByConnectionId = new Map();
         this.p2pNode = config.p2pNode;
         this.defaultReadTimeoutMs = config.defaultReadTimeoutMs;
         this.defaultDrainTimeoutMs = config.defaultDrainTimeoutMs;
@@ -22,19 +24,31 @@ export class oNodeConnectionManager extends oConnectionManager {
             if (!connection) {
                 return;
             }
-            for (const [addressKey, cachedConnections,] of this.connectionsByAddress.entries()) {
-                const index = cachedConnections.indexOf(connection);
-                if (index !== -1) {
-                    this.logger.debug('Connection closed, removing from cache for address:', addressKey);
-                    cachedConnections.splice(index, 1);
-                    // Remove the address key entirely if no connections remain
-                    if (cachedConnections.length === 0) {
-                        this.connectionsByAddress.delete(addressKey);
-                    }
-                    else {
-                        this.connectionsByAddress.set(addressKey, cachedConnections);
-                    }
-                }
+            // Clean up libp2p connection cache
+            // for (const [
+            //   addressKey,
+            //   cachedConnections,
+            // ] of this.connectionsByAddress.entries()) {
+            //   const index = cachedConnections.indexOf(connection);
+            //   if (index !== -1) {
+            //     this.logger.debug(
+            //       'Connection closed, removing from cache for address:',
+            //       addressKey,
+            //     );
+            //     cachedConnections.splice(index, 1);
+            //     // Remove the address key entirely if no connections remain
+            //     if (cachedConnections.length === 0) {
+            //       this.connectionsByAddress.delete(addressKey);
+            //     } else {
+            //       this.connectionsByAddress.set(addressKey, cachedConnections);
+            //     }
+            //   }
+            // }
+            // Clean up oNodeConnection cache by connection ID
+            const connectionId = connection.id;
+            if (this.nodeConnectionByConnectionId.has(connectionId)) {
+                this.logger.debug('Connection closed, removing oNodeConnection for connection ID:', connectionId);
+                this.nodeConnectionByConnectionId.delete(connectionId);
             }
         });
     }
@@ -105,8 +119,7 @@ export class oNodeConnectionManager extends oConnectionManager {
         // Priority 2: Based on reuse context
         if (reuseContext) {
             // Prefer inbound connections
-            const inbound = openConnections.find((c) => c.direction === 'inbound' ||
-                !c.direction);
+            const inbound = openConnections.find((c) => c.direction === 'inbound' || !c.direction);
             if (inbound) {
                 this.logger.debug('Selected inbound connection (reuse context)');
                 return inbound;
@@ -121,9 +134,32 @@ export class oNodeConnectionManager extends oConnectionManager {
             }
         }
         // Priority 3: Return first open connection
-        this.logger.debug('Selected first available open connection');
+        this.logger.debug('Selected first available open connection', connectionsWithStreams);
         return openConnections[0];
     }
+    /**
+     * Get a cached oNodeConnection for the given p2p connection if it exists and is valid.
+     * @param p2pConnection - The p2p connection to look up
+     * @returns A valid oNodeConnection or null if none found
+     */
+    getCachedNodeConnection(p2pConnection) {
+        const cached = this.nodeConnectionByConnectionId.get(p2pConnection.id);
+        if (cached && cached.p2pConnection?.status === 'open') {
+            return cached;
+        }
+        // Clean up stale entry if connection is no longer open
+        if (cached) {
+            this.nodeConnectionByConnectionId.delete(p2pConnection.id);
+        }
+        return null;
+    }
+    /**
+     * Cache an oNodeConnection by its p2p connection ID for potential reuse.
+     * @param conn - The oNodeConnection to cache
+     */
+    cacheNodeConnection(conn) {
+        this.nodeConnectionByConnectionId.set(conn.p2pConnection.id, conn);
+    }
     async getOrCreateConnection(nextHopAddress, address) {
         if (!nextHopAddress) {
             throw new Error('Invalid address passed');
@@ -137,7 +173,7 @@ export class oNodeConnectionManager extends oConnectionManager {
         const cachedConnections = this.connectionsByAddress.get(addressKey) || [];
         const bestConnection = this.selectBestConnection(cachedConnections, false);
         if (bestConnection) {
-            this.logger.debug('Reusing cached connection for address:', nextHopAddress?.value);
+            this.logger.debug('Reusing cached connection for address:', nextHopAddress?.value, bestConnection.id);
             return bestConnection;
         }
         // Clean up stale connections if they exist but are not open
@@ -210,6 +246,8 @@ export class oNodeConnectionManager extends oConnectionManager {
             requestHandler: config.requestHandler ?? undefined,
             reusePolicy: reuse ? 'reuse' : 'none',
         });
+        // Cache the new connection by its p2p connection ID
+        this.cacheNodeConnection(connection);
         const addressKey = this.getAddressKey(nextHopAddress);
         if (addressKey) {
             const connections = this.connectionsByAddress.get(addressKey) || [];
@@ -225,13 +263,21 @@ export class oNodeConnectionManager extends oConnectionManager {
         return connection;
     }
     /**
-     * Connect to a given address, reusing libp2p connections when possible
+     * Connect to a given address, reusing oNodeConnection and libp2p connections when possible
      * @param config - Connection configuration
      * @returns The connection object
      */
     async connect(config) {
         const { address, nextHopAddress, callerAddress, readTimeoutMs, drainTimeoutMs, } = config;
+        // First get or create the underlying p2p connection
         const p2pConnection = await this.getOrCreateConnection(nextHopAddress, address);
+        // Check for existing valid oNodeConnection for this p2p connection
+        const existingConnection = this.getCachedNodeConnection(p2pConnection);
+        if (existingConnection) {
+            this.logger.debug('Reusing cached oNodeConnection for connection ID:', p2pConnection.id);
+            return existingConnection;
+        }
+        // No valid cached connection, create new one
         const connection = new oNodeConnection({
             nextHopAddress: nextHopAddress,
             address: address,
@@ -244,6 +290,8 @@ export class oNodeConnectionManager extends oConnectionManager {
             runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
             requestHandler: config.requestHandler ?? undefined,
         });
+        // Cache the new connection by its p2p connection ID
+        this.cacheNodeConnection(connection);
         return connection;
     }
     /**
@@ -342,7 +390,7 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     getCacheStats() {
         const allConnections = [];
-        for (const [addressKey, connections] of this.connectionsByAddress.entries()) {
+        for (const [addressKey, connections,] of this.connectionsByAddress.entries()) {
             for (const conn of connections) {
                 allConnections.push({
                     peerId: conn.remotePeer?.toString() ?? 'unknown',
@@ -355,6 +403,7 @@ export class oNodeConnectionManager extends oConnectionManager {
             cachedAddresses: this.connectionsByAddress.size,
             totalCachedConnections: allConnections.length,
             pendingDials: this.pendingDialsByAddress.size,
+            cachedNodeConnections: this.nodeConnectionByConnectionId.size,
             connectionsByPeer: allConnections,
         };
     }
@@ -364,7 +413,7 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     cleanupStaleConnections() {
         let removed = 0;
-        for (const [addressKey, connections] of this.connectionsByAddress.entries()) {
+        for (const [addressKey, connections,] of this.connectionsByAddress.entries()) {
             const openConnections = connections.filter((conn) => conn.status === 'open');
             const staleCount = connections.length - openConnections.length;
             if (staleCount > 0) {
@@ -384,4 +433,21 @@ export class oNodeConnectionManager extends oConnectionManager {
         }
         return removed;
     }
+    /**
+     * Clean up all stale oNodeConnections from cache
+     * @returns Number of oNodeConnections removed
+     */
+    cleanupStaleNodeConnections() {
+        let removed = 0;
+        for (const [connectionId, conn,] of this.nodeConnectionByConnectionId.entries()) {
+            if (conn.p2pConnection?.status !== 'open') {
+                this.nodeConnectionByConnectionId.delete(connectionId);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            this.logger.debug(`Cleaned up ${removed} stale oNodeConnections`);
+        }
+        return removed;
+    }
 }

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

@@ -11,6 +11,7 @@ import { oToolBase } from '@olane/o-tool';
 import { oConnectionHeartbeatManager } from './managers/o-connection-heartbeat.manager.js';
 import { oNodeConnectionConfig } from './connection/index.js';
 import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LockManager } from './utils/lock-manager.js';
 export declare class oNode extends oToolBase {
     peerId: PeerId;
     p2pNode: Libp2p;
@@ -23,6 +24,7 @@ export declare class oNode extends oToolBase {
     protected didRegister: boolean;
     protected hooksStartFinished: any[];
     protected hooksInitFinished: any[];
+    protected lockManager: LockManager;
     constructor(config: oNodeConfig);
     get leader(): oNodeAddress | null;
     get networkConfig(): Libp2pConfig;

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

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

package/dist/src/o-node.js

@@ -11,12 +11,14 @@ import { oMethodResolver, oToolBase } from '@olane/o-tool';
 import { oLeaderResolverFallback } from './router/index.js';
 import { oNodeNotificationManager } from './o-node.notification-manager.js';
 import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LockManager } from './utils/lock-manager.js';
 export class oNode extends oToolBase {
     constructor(config) {
         super(config);
         this.didRegister = false;
         this.hooksStartFinished = [];
         this.hooksInitFinished = [];
+        this.lockManager = new LockManager();
         this.config = config;
     }
     get leader() {
@@ -522,6 +524,8 @@ export class oNode extends oToolBase {
     resetState() {
         // Reset registration flag
         this.didRegister = false;
+        // Clear all locks
+        this.lockManager.clearAll();
         // Clear peer references
         this.peerId = undefined;
         this.p2pNode = undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAMrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,mBAAmB,CAAC,OAAO,EAAE,QAAQ;IAgBrC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAoBhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAwCV,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAgC5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAMrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,mBAAmB,CAAC,OAAO,EAAE,QAAQ;IAsBrC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAoBhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAyCV,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAiC5D"}

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

@@ -13,6 +13,7 @@ import { ConnectionUtils } from './utils/connection.utils.js';
 export class oNodeTool extends oTool(oServerNode) {
     async handleProtocolReuse(address) {
         const reuseProtocol = address.protocol + '/reuse';
+        this.logger.debug('Handling protocol reuse: ' + reuseProtocol);
         const protocols = this.p2pNode.getProtocols();
         if (protocols.find((p) => p === reuseProtocol)) {
             // already handling
@@ -21,10 +22,11 @@ export class oNodeTool extends oTool(oServerNode) {
         const maxOutboundsStreams = process.env.MAX_OUTBOUND_STREAMS
             ? parseInt(process.env.MAX_OUTBOUND_STREAMS)
             : 1000;
-        await this.p2pNode.handle(reuseProtocol, this.handleStream.bind(this), {
+        await this.p2pNode.handle(reuseProtocol, this.handleStreamReuse.bind(this), {
             maxInboundStreams: 10000,
             maxOutboundStreams: maxOutboundsStreams,
         });
+        this.logger.debug('Handled protocol reuse: ' + reuseProtocol);
     }
     async handleProtocol(address) {
         const protocols = this.p2pNode.getProtocols();
@@ -72,6 +74,7 @@ export class oNodeTool extends oTool(oServerNode) {
             callerAddress: this.address,
             p2pConnection: connection,
             reuse,
+            // requestHandler: this.execute.bind(this), TODO: do we need this?
         });
         // Use StreamHandler for consistent stream handling
         // This follows libp2p v3 best practices for length-prefixed streaming
@@ -108,6 +111,7 @@ export class oNodeTool extends oTool(oServerNode) {
             }));
         }
         // create downward direction connection
+        this.logger.debug('Pinging child to confirm access');
         await this.useChild(childAddress, {
             method: 'ping',
             params: {},

package/dist/src/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './stream.utils.js';
 export * from './network.utils.js';
 export * from './connection.utils.js';
+export * from './lock-manager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/src/utils/index.js

@@ -1,3 +1,4 @@
 export * from './stream.utils.js';
 export * from './network.utils.js';
 export * from './connection.utils.js';
+export * from './lock-manager.js';

package/dist/src/utils/lock-manager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Promise-based lock manager for handling concurrent access to critical sections
+ * Supports named locks for fine-grained concurrency control
+ */
+export declare class LockManager {
+    private locks;
+    private lockStates;
+    private resolvers;
+    /**
+     * Acquire a named lock, waiting if necessary
+     * @param lockName - Unique identifier for the lock
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws Error if timeout is reached
+     */
+    acquire(lockName: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Release a named lock
+     * @param lockName - Unique identifier for the lock to release
+     */
+    release(lockName: string): void;
+    /**
+     * Execute a function with automatic lock acquisition/release
+     * @param lockName - Unique identifier for the lock
+     * @param fn - Async function to execute while holding the lock
+     * @param timeoutMs - Optional timeout for lock acquisition
+     * @returns The result of the function execution
+     */
+    withLock<T>(lockName: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+    /**
+     * Check if a lock is currently held
+     * @param lockName - Unique identifier for the lock
+     * @returns true if the lock is currently held
+     */
+    isLocked(lockName: string): boolean;
+    /**
+     * Clear all locks (for teardown/reset)
+     * Resolves any pending waiters
+     */
+    clearAll(): void;
+    /**
+     * Get statistics about current lock states (useful for debugging)
+     * @returns Object containing lock statistics
+     */
+    getStats(): {
+        totalLocks: number;
+        activeLocks: number;
+        lockNames: string[];
+    };
+}
+//# sourceMappingURL=lock-manager.d.ts.map

package/dist/src/utils/lock-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-manager.d.ts","sourceRoot":"","sources":["../../../src/utils/lock-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,SAAS,CAAsC;IAEvD;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAS/B;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EACd,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IASb;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAInC;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAUhB;;;OAGG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB;CAWF"}

package/dist/src/utils/lock-manager.js

@@ -0,0 +1,101 @@
+/**
+ * Promise-based lock manager for handling concurrent access to critical sections
+ * Supports named locks for fine-grained concurrency control
+ */
+export class LockManager {
+    constructor() {
+        this.locks = new Map();
+        this.lockStates = new Map();
+        this.resolvers = new Map();
+    }
+    /**
+     * Acquire a named lock, waiting if necessary
+     * @param lockName - Unique identifier for the lock
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws Error if timeout is reached
+     */
+    async acquire(lockName, timeoutMs) {
+        // Wait for any existing lock to be released
+        while (this.lockStates.get(lockName)) {
+            const currentLock = this.locks.get(lockName);
+            if (currentLock) {
+                if (timeoutMs) {
+                    await Promise.race([
+                        currentLock,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Lock timeout: ${lockName}`)), timeoutMs)),
+                    ]);
+                }
+                else {
+                    await currentLock;
+                }
+            }
+        }
+        // Acquire the lock
+        this.lockStates.set(lockName, true);
+        const lockPromise = new Promise((resolve) => {
+            this.resolvers.set(lockName, resolve);
+        });
+        this.locks.set(lockName, lockPromise);
+    }
+    /**
+     * Release a named lock
+     * @param lockName - Unique identifier for the lock to release
+     */
+    release(lockName) {
+        const resolver = this.resolvers.get(lockName);
+        if (resolver) {
+            resolver();
+            this.resolvers.delete(lockName);
+        }
+        this.lockStates.set(lockName, false);
+    }
+    /**
+     * Execute a function with automatic lock acquisition/release
+     * @param lockName - Unique identifier for the lock
+     * @param fn - Async function to execute while holding the lock
+     * @param timeoutMs - Optional timeout for lock acquisition
+     * @returns The result of the function execution
+     */
+    async withLock(lockName, fn, timeoutMs) {
+        await this.acquire(lockName, timeoutMs);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(lockName);
+        }
+    }
+    /**
+     * Check if a lock is currently held
+     * @param lockName - Unique identifier for the lock
+     * @returns true if the lock is currently held
+     */
+    isLocked(lockName) {
+        return this.lockStates.get(lockName) ?? false;
+    }
+    /**
+     * Clear all locks (for teardown/reset)
+     * Resolves any pending waiters
+     */
+    clearAll() {
+        // Resolve any pending waiters
+        for (const lockName of this.lockStates.keys()) {
+            this.release(lockName);
+        }
+        this.locks.clear();
+        this.lockStates.clear();
+        this.resolvers.clear();
+    }
+    /**
+     * Get statistics about current lock states (useful for debugging)
+     * @returns Object containing lock statistics
+     */
+    getStats() {
+        const activeLocks = Array.from(this.lockStates.entries()).filter(([_, isLocked]) => isLocked);
+        return {
+            totalLocks: this.lockStates.size,
+            activeLocks: activeLocks.length,
+            lockNames: activeLocks.map(([name]) => name),
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.45",
+  "version": "0.7.47",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -40,7 +40,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.29.0",
-    "@olane/o-test": "0.7.45",
+    "@olane/o-test": "0.7.47",
     "@tsconfig/node20": "^20.1.6",
     "@types/jest": "^30.0.0",
     "@types/json5": "^2.2.0",
@@ -60,13 +60,13 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.45",
-    "@olane/o-core": "0.7.45",
-    "@olane/o-protocol": "0.7.45",
-    "@olane/o-tool": "0.7.45",
+    "@olane/o-config": "0.7.47",
+    "@olane/o-core": "0.7.47",
+    "@olane/o-protocol": "0.7.47",
+    "@olane/o-tool": "0.7.47",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
     "json5": "^2.2.3"
   },
-  "gitHead": "d336869dfa3105b453d2249ae388870088b17343"
+  "gitHead": "2730d1ccdfb58549ebd253ded9479156086cc066"
 }