@olane/o-node 0.7.13-alpha.0 → 0.7.13-alpha.2

package/dist/src/o-node.js

@@ -75,11 +75,11 @@ export class oNode extends oToolBase {
                         params: {
                             eventType: 'node:stopping',
                             eventData: {
-                                address: this.address.toString(),
+                                address: this.address?.toString(),
                                 reason: 'graceful_shutdown',
                                 expectedDowntime: null,
                             },
-                            source: this.address.toString(),
+                            source: this.address?.toString(),
                         },
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
@@ -94,12 +94,16 @@ export class oNode extends oToolBase {
             this.logger.debug('No leader found, skipping unregistration');
             return;
         }
+        // no need to unregister since we did not generate a peerID yet
+        if (!this.peerId) {
+            return;
+        }
         const address = new oNodeAddress(RestrictedAddresses.REGISTRY);
         // attempt to unregister from the network
         const params = {
             method: 'remove',
             params: {
-                peerId: this.peerId.toString(),
+                peerId: this.peerId?.toString(),
             },
         };
         this.use(address, params).catch((error) => {
@@ -135,6 +139,10 @@ export class oNode extends oToolBase {
             this.logger.debug('Skipping parent registration, node is leader');
             return;
         }
+        if (!this.parent) {
+            this.logger.warn('no parent, skipping registration');
+            return;
+        }
         if (!this.parent?.libp2pTransports?.length) {
             this.logger.debug('Parent has no transports, waiting for reconnection & leader ack');
             if (this.parent?.toString() === oAddress.leader().toString()) {
@@ -149,7 +157,8 @@ export class oNode extends oToolBase {
         // TODO: should we remove the transports check to make this more consistent?
         if (this.config.parent) {
             this.logger.debug('Registering node with parent...', this.config.parent?.toString());
-            await this.use(this.config.parent, {
+            // avoid transports to ensure we do not try direct connection, we need to route via the leader for proper access controls
+            await this.use(new oNodeAddress(this.config.parent.value), {
                 method: 'child_register',
                 params: {
                     address: this.address.toString(),
@@ -162,6 +171,11 @@ export class oNode extends oToolBase {
         }
     }
     async registerLeader() {
+        this.logger.info('Register leader called...');
+        if (!this.leader) {
+            this.logger.warn('No leader defined, skipping registration');
+            return;
+        }
         const address = oAddress.registry();
         const params = {
             method: 'commit',
@@ -187,6 +201,7 @@ export class oNode extends oToolBase {
         }
         this.didRegister = true;
         this.logger.debug('Registering node...');
+        await this.registerParent();
         // register with the leader global registry
         if (!this.config.leader) {
             this.logger.warn('No leaders found, skipping registration');
@@ -195,7 +210,6 @@ export class oNode extends oToolBase {
         else {
             this.logger.debug('Registering node with leader...');
         }
-        await this.registerParent();
         await this.registerLeader();
         this.logger.debug('Registration successful');
     }
@@ -290,7 +304,6 @@ export class oNode extends oToolBase {
                     if (this.config.type === NodeType.LEADER) {
                         return false;
                     }
-                    // deny everything else
                     return true;
                 },
                 // allow the user to override the default connection gater
@@ -305,9 +318,8 @@ export class oNode extends oToolBase {
             maxParallelReconnects: 10,
         };
         // handle the address encapsulation
-        if (this.config.leader &&
-            !this.address.protocol.includes(this.config.leader.protocol)) {
-            const parentAddress = this.config.parent || this.config.leader;
+        if (this.config.parent) {
+            const parentAddress = this.config.parent;
             this.address = CoreUtils.childAddress(parentAddress, this.address);
         }
         return params;
@@ -342,6 +354,7 @@ export class oNode extends oToolBase {
             defaultReadTimeoutMs: this.config.connectionTimeouts?.readTimeoutMs,
             defaultDrainTimeoutMs: this.config.connectionTimeouts?.drainTimeoutMs,
             runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
+            originAddress: this.address?.value
         });
     }
     async hookInitializeFinished() { }
@@ -358,9 +371,45 @@ export class oNode extends oToolBase {
         this.logger.info(`Connection heartbeat config: leader=${this.connectionHeartbeatManager.getConfig().checkLeader}, ` +
             `parent=${this.connectionHeartbeatManager.getConfig().checkParent}`);
     }
+    /**
+     * Validates that if a leader address is defined, it has associated transports.
+     * This is critical for non-leader nodes to be able to connect to their leader.
+     * @throws Error if leader is defined but has no transports
+     */
+    async validateLeaderTransports() {
+        // Skip validation if this node is the leader itself
+        if (this.isLeader) {
+            return;
+        }
+        // Skip validation if no leader is configured
+        const leaderAddress = this.config?.leader;
+        if (!leaderAddress) {
+            return;
+        }
+        // Check if leader has transports
+        if (!leaderAddress.transports || leaderAddress.transports.length === 0) {
+            throw new Error(`Leader address is defined (${leaderAddress.toString()}) but has no transports. ` +
+                `Non-leader nodes require leader transports for network connectivity. ` +
+                `Please provide transports in the leader address configuration.`);
+        }
+        this.logger.debug('Leader transport validation passed', {
+            leader: leaderAddress.toString(),
+            transportCount: leaderAddress.transports.length
+        });
+    }
+    /**
+     * oNode-specific validation that runs before core start() logic.
+     *
+     * This ensures that leader transport configuration errors are
+     * surfaced quickly and before any libp2p nodes or other heavy
+     * resources are created.
+     */
+    async validate() {
+        await this.validateLeaderTransports();
+    }
     async initialize() {
         this.logger.debug('Initializing node...');
-        if (this.p2pNode && this.state !== NodeState.STOPPED) {
+        if (this.state !== NodeState.STOPPED && this.state !== NodeState.STARTING) {
             throw new Error('Node is not in a valid state to be initialized');
         }
         if (!this.address.validate()) {
@@ -379,7 +428,7 @@ export class oNode extends oToolBase {
         this.router.addResolver(new oMethodResolver(this.address));
         this.router.addResolver(new oNodeResolver(this.address));
         // setup a fallback resolver for non-leader nodes
-        if (this.isLeader === false) {
+        if (this.isLeader === false && !!this.leader) {
             this.logger.debug('Adding leader resolver fallback...');
             this.router.addResolver(new oLeaderResolverFallback(this.address));
         }
@@ -421,6 +470,35 @@ export class oNode extends oToolBase {
         if (this.p2pNode) {
             await this.p2pNode.stop();
         }
+        // Reset state to allow restart
+        this.resetState();
+    }
+    /**
+     * Reset node state to allow restart after stop
+     * Called at the end of teardown()
+     */
+    resetState() {
+        // Reset registration flag
+        this.didRegister = false;
+        // Clear peer references
+        this.peerId = undefined;
+        this.p2pNode = undefined;
+        // Clear managers
+        this.connectionManager = undefined;
+        this.connectionHeartbeatManager = undefined;
+        this.reconnectionManager = undefined;
+        // Reset address to staticAddress with no transports
+        this.address = new oNodeAddress(this.staticAddress.value, []);
+        // Reset hierarchy manager
+        this.hierarchyManager = new oNodeHierarchyManager({
+            leaders: this.config.leader ? [this.config.leader] : [],
+            parents: this.config.parent ? [this.config.parent] : [],
+            children: [],
+        });
+        // Clear router (will be recreated in initialize)
+        this.router = undefined;
+        // Call parent reset
+        super.resetState();
     }
     // IHeartbeatableNode interface methods
     getLeaders() {

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,EACL,QAAQ,EACR,QAAQ,EAET,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAKrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAUhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CA2B5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EAET,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAKrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAehC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CA2B5D"}

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

@@ -11,6 +11,11 @@ import { StreamHandler } from './connection/stream-handler.js';
  */
 export class oNodeTool extends oTool(oServerNode) {
     async handleProtocol(address) {
+        const protocols = this.p2pNode.getProtocols();
+        if (protocols.find((p) => p === address.protocol)) {
+            // already handling
+            return;
+        }
         this.logger.debug('Handling protocol: ' + address.protocol);
         await this.p2pNode.handle(address.protocol, this.handleStream.bind(this), {
             maxInboundStreams: 10000,

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

@@ -1 +1 @@
-{"version":3,"file":"o-node.router.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAML,cAAc,EAGd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAM5C,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,aAAa,CAAqB;;IAO1C;;;;;;;;OAQG;cACa,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,GAAG,CAAC;IA6Bf;;;OAGG;YACW,kBAAkB;IA8DhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAWhC;;OAEG;YACW,eAAe;IAsC7B;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB3E;;;OAGG;IACH,UAAU,CAAC,qBAAqB,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;CAGtE"}
+{"version":3,"file":"o-node.router.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAML,cAAc,EAGd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAM5C,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,aAAa,CAAqB;;IAO1C;;;;;;;;OAQG;cACa,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,GAAG,CAAC;IA6Bf;;;OAGG;YACW,kBAAkB;IA8DhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAWhC;;OAEG;YACW,eAAe;IAsC7B;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;IAmC3E;;;OAGG;IACH,UAAU,CAAC,qBAAqB,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;CAGtE"}

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

@@ -141,7 +141,7 @@ export class oNodeRouter extends oToolRouter {
         }
         catch (error) {
             if (error?.name === 'UnsupportedProtocolError') {
-                throw new oError(oErrorCodes.NOT_FOUND, 'Address not found');
+                throw new oError(oErrorCodes.NOT_FOUND, 'Address not found: ' + address.value);
             }
             throw error;
         }
@@ -151,17 +151,27 @@ export class oNodeRouter extends oToolRouter {
      * First checks routing policy for external routing, then applies resolver chain.
      */
     async translate(address, node) {
-        // Check if external routing is needed
-        const externalRoute = this.routingPolicy.getExternalRoutingStrategy(address, node);
-        if (externalRoute) {
-            return externalRoute;
-        }
         // Apply resolver chain for internal routing
+        if (!node.parent && !node.leader && address.transports?.length > 0) {
+            // independent node
+            return {
+                nextHopAddress: address,
+                targetAddress: address,
+            };
+        }
         const { nextHopAddress, targetAddress, requestOverride } = await this.addressResolution.resolve({
             address,
             node,
             targetAddress: address,
         });
+        // if we defaulted back to the leader
+        if (nextHopAddress.value === oAddress.leader().value) {
+            // Check if external routing is needed for leader routing
+            const externalRoute = this.routingPolicy.getExternalRoutingStrategy(address, node);
+            if (externalRoute) {
+                return externalRoute;
+            }
+        }
         return {
             nextHopAddress,
             targetAddress: targetAddress,

package/dist/src/router/o-node.routing-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.routing-policy.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.routing-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAG1C;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD;;;;;;;;;OASG;IACH,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;IAuB1D;;;;;;;;OAQG;IACH,0BAA0B,CACxB,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,KAAK,GACV,aAAa,GAAG,IAAI;CAmBxB"}
+{"version":3,"file":"o-node.routing-policy.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.routing-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAG1C;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD;;;;;;;;;OASG;IACH,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;IA4B1D;;;;;;;;OAQG;IACH,0BAA0B,CACxB,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,KAAK,GACV,aAAa,GAAG,IAAI;CAmBxB"}

package/dist/src/router/o-node.routing-policy.js

@@ -21,6 +21,10 @@ export class oNodeRoutingPolicy extends oRoutingPolicy {
         if (node.hierarchyManager.parents.some((p) => p.equals(address))) {
             return true;
         }
+        // if we are trying to connect to a child, it's internal
+        if (node.hierarchyManager.children.some((p) => p.equals(address))) {
+            return true;
+        }
         if (nodeAddress.paths.indexOf(oAddress.leader().paths) !== -1 && // if the address has a leader
             nodeAddress.libp2pTransports?.length > 0) {
             // transports are provided, let's see if they match our known leaders

package/dist/test/connection-management.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connection-management.spec.d.ts.map

package/dist/test/connection-management.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-management.spec.d.ts","sourceRoot":"","sources":["../../test/connection-management.spec.ts"],"names":[],"mappings":""}

package/dist/test/connection-management.spec.js

@@ -0,0 +1,370 @@
+import { expect } from 'chai';
+import { TestEnvironment } from './helpers/index.js';
+import { NetworkBuilder, NetworkTopologies } from './helpers/network-builder.js';
+import { createConnectionSpy } from './helpers/connection-spy.js';
+import { oNodeAddress } from '../src/router/o-node.address.js';
+import { oNodeTransport } from '../src/index.js';
+describe('Connection Management', () => {
+    const env = new TestEnvironment();
+    let builder;
+    afterEach(async () => {
+        if (builder) {
+            await builder.cleanup();
+        }
+        await env.cleanup();
+    });
+    describe('Connection Pooling', () => {
+        it('should cache and reuse connections', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Make first request (establishes connection)
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'ping',
+                params: { message: 'first' },
+            });
+            const connectionsAfterFirst = spy.getSummary().currentConnections;
+            // Make second request (should reuse connection)
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'ping',
+                params: { message: 'second' },
+            });
+            const connectionsAfterSecond = spy.getSummary().currentConnections;
+            // Connection count should remain the same (reused)
+            expect(connectionsAfterFirst).to.equal(connectionsAfterSecond);
+            expect(connectionsAfterFirst).to.be.greaterThan(0);
+            spy.stop();
+        });
+        it('should maintain separate connections to different nodes', async () => {
+            builder = await NetworkTopologies.fiveNode();
+            const leader = builder.getNode('o://leader');
+            const parent1 = builder.getNode('o://parent1');
+            const parent2 = builder.getNode('o://parent2');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Call different nodes
+            await leader.use(parent1.address, {
+                method: 'echo',
+                params: { message: 'to parent1' },
+            });
+            await leader.use(parent2.address, {
+                method: 'echo',
+                params: { message: 'to parent2' },
+            });
+            const stats = spy.getConnectionStats();
+            // Should have connections to both parents
+            expect(stats.length).to.be.greaterThan(1);
+            spy.stop();
+        });
+        it('should handle connection pool efficiently under load', async () => {
+            builder = await NetworkTopologies.fiveNode();
+            const leader = builder.getNode('o://leader');
+            const child1 = builder.getNode('o://child1');
+            const child2 = builder.getNode('o://child2');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Make many requests to different nodes
+            const promises = [];
+            for (let i = 0; i < 50; i++) {
+                const target = i % 2 === 0 ? child1 : child2;
+                promises.push(leader.use(target.address, {
+                    method: 'echo',
+                    params: { message: `request-${i}` },
+                }));
+            }
+            await Promise.all(promises);
+            const summary = spy.getSummary();
+            // Connection count should be reasonable (not 50)
+            expect(summary.currentConnections).to.be.lessThan(10);
+            expect(summary.currentConnections).to.be.greaterThan(0);
+            spy.stop();
+        });
+    });
+    describe('Connection Status', () => {
+        it('should report correct connection status', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Establish connection
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            const stats = spy.getConnectionStats();
+            expect(stats.length).to.be.greaterThan(0);
+            const connection = stats[0];
+            expect(connection.status).to.equal('open');
+            expect(connection.peerId).to.be.a('string');
+            expect(connection.remoteAddr).to.be.a('string');
+            spy.stop();
+        });
+        it('should detect open connections', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            // Get child's peer ID
+            const childPeerId = child.address.libp2pTransports[0].toPeerId();
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Establish connection
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            // Verify connection exists
+            const hasConnection = spy.hasConnectionToPeer(childPeerId);
+            expect(hasConnection).to.be.true;
+            spy.stop();
+        });
+    });
+    describe('Connection Validation', () => {
+        it('should validate connection before transmission', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            // Valid connection should work
+            const response = await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            expect(response.result.success).to.be.true;
+        });
+        it('should handle connection to unreachable node', async () => {
+            builder = new NetworkBuilder();
+            const leader = await builder.addNode('o://leader');
+            // Create address to non-existent node
+            const fakeAddress = new oNodeAddress('o://nonexistent', [
+                new oNodeTransport('/ip4/127.0.0.1/tcp/4099'),
+            ]);
+            // Attempt to connect should fail gracefully
+            await leader.use(fakeAddress, {
+                method: 'echo',
+                params: { message: 'test' },
+            }).catch((err) => {
+                expect(err.code).to.be.equal('ECONNREFUSED');
+            });
+        });
+        it('should verify connection is open before use', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Make request
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            // Verify connection is open
+            const stats = spy.getConnectionStats();
+            expect(stats.length).to.be.greaterThan(0);
+            expect(stats[0].status).to.equal('open');
+            spy.stop();
+        });
+    });
+    describe('Connection Recovery', () => {
+        it('should handle transient connection errors', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            // Make successful request
+            const response1 = await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'before' },
+            });
+            expect(response1.result.success).to.be.true;
+            // Simulate brief disconnection by stopping and restarting child
+            await child.stop();
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            await child.start();
+            // Wait for reconnection
+            await new Promise((resolve) => setTimeout(resolve, 200));
+            // Subsequent request should eventually work
+            // Note: May need retry logic depending on implementation
+            const response2 = await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'after' },
+            });
+            // This may fail if connection not re-established
+            // Test verifies graceful error handling
+            if (response2.result.success) {
+                expect(response2.result.data.message).to.equal('after');
+            }
+            else {
+                expect(response2.result.error).to.exist;
+            }
+        });
+        it('should maintain other connections when one fails', async () => {
+            builder = await NetworkTopologies.fiveNode();
+            const leader = builder.getNode('o://leader');
+            const child1 = builder.getNode('o://child1');
+            const child2 = builder.getNode('o://child2');
+            // Establish connections to both children
+            await leader.use(child1.address, {
+                method: 'echo',
+                params: { message: 'child1' },
+            });
+            await leader.use(child2.address, {
+                method: 'echo',
+                params: { message: 'child2' },
+            });
+            // Stop child1
+            await builder.stopNode('o://child1');
+            // Connection to child2 should still work
+            const response = await leader.use(child2.address, {
+                method: 'echo',
+                params: { message: 'child2-after' },
+            });
+            expect(response.result.success).to.be.true;
+            expect(response.result.data.message).to.equal('child2-after');
+        });
+    });
+    describe('Multi-node Connection Management', () => {
+        it('should manage connections in complex topology', async () => {
+            builder = await NetworkTopologies.complex();
+            const leader = builder.getNode('o://leader');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            // Make requests to various nodes
+            for (let i = 1; i <= 3; i++) {
+                const parent = builder.getNode(`o://parent${i}`);
+                await leader.use(parent.address, {
+                    method: 'echo',
+                    params: { message: `parent${i}` },
+                });
+            }
+            const summary = spy.getSummary();
+            // Should have connections to parents
+            expect(summary.currentConnections).to.be.greaterThan(0);
+            expect(summary.currentConnections).to.be.lessThan(10);
+            spy.stop();
+        });
+    });
+    describe('Connection Metadata', () => {
+        it('should track connection creation time', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            const beforeTime = Date.now();
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            const afterTime = Date.now();
+            const stats = spy.getConnectionStats();
+            if (stats.length > 0) {
+                expect(stats[0].created).to.be.at.least(beforeTime);
+                expect(stats[0].created).to.be.at.most(afterTime);
+            }
+            spy.stop();
+        });
+        it('should track remote peer information', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            const stats = spy.getConnectionStats();
+            if (stats.length > 0) {
+                const connection = stats[0];
+                expect(connection.peerId).to.be.a('string');
+                expect(connection.peerId.length).to.be.greaterThan(0);
+                expect(connection.remoteAddr).to.be.a('string');
+                expect(connection.remoteAddr.length).to.be.greaterThan(0);
+            }
+            spy.stop();
+        });
+    });
+    describe('Connection Gating', () => {
+        it('should enforce connection gating rules', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            // Parent-child connections should be allowed
+            const response = await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            expect(response.result.success).to.be.true;
+        });
+        it('should allow connections within hierarchy', async () => {
+            builder = await NetworkTopologies.threeNode();
+            const leader = builder.getNode('o://leader');
+            const parent = builder.getNode('o://parent');
+            const child = builder.getNode('o://child');
+            // All connections in hierarchy should work
+            const response1 = await leader.use(parent.address, {
+                method: 'echo',
+                params: { message: 'leader-to-parent' },
+            });
+            const response2 = await parent.use(child.address, {
+                method: 'echo',
+                params: { message: 'parent-to-child' },
+            });
+            const response3 = await child.use(parent.address, {
+                method: 'echo',
+                params: { message: 'child-to-parent' },
+            });
+            expect(response1.result.success).to.be.true;
+            expect(response2.result.success).to.be.true;
+            expect(response3.result.success).to.be.true;
+        });
+    });
+    describe('Connection Cleanup', () => {
+        it('should clean up connections on node stop', async () => {
+            builder = await NetworkTopologies.twoNode();
+            const leader = builder.getNode('o://leader');
+            const child = builder.getNode('o://child');
+            // Establish connection
+            await leader.use(new oNodeAddress(child.address.toString(), child.address.libp2pTransports), {
+                method: 'echo',
+                params: { message: 'test' },
+            });
+            const spy = createConnectionSpy(leader);
+            spy.start();
+            const beforeConnections = spy.getSummary().currentConnections;
+            expect(beforeConnections).to.be.greaterThan(0);
+            // Stop child
+            await builder.stopNode('o://child');
+            // Wait for cleanup
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            // Note: Connection may still exist until cleanup cycle runs
+            // This test verifies stop mechanism doesn't throw errors
+            spy.stop();
+        });
+        it('should handle cleanup of multiple connections', async () => {
+            builder = await NetworkTopologies.fiveNode();
+            const leader = builder.getNode('o://leader');
+            // Establish connections
+            const child1 = builder.getNode('o://child1');
+            const child2 = builder.getNode('o://child2');
+            await leader.use(child1.address, {
+                method: 'echo',
+                params: { message: 'child1' },
+            });
+            await leader.use(child2.address, {
+                method: 'echo',
+                params: { message: 'child2' },
+            });
+            // Stop all children
+            await builder.stopNode('o://child1');
+            await builder.stopNode('o://child2');
+            // Leader should remain operational
+            const response = await leader.use(leader.address, {
+                method: 'get_info',
+                params: {},
+            });
+            expect(response.result.success).to.be.true;
+        });
+    });
+});