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

package/dist/test/helpers/test-environment.js

@@ -0,0 +1,184 @@
+/**
+ * TestEnvironment - Core test setup and lifecycle management for O-Network nodes
+ *
+ * Provides automatic cleanup, node factories, and common test utilities
+ * to eliminate boilerplate in O-Network package tests.
+ *
+ * @example
+ * ```typescript
+ * describe('MyTool', () => {
+ *   const env = new TestEnvironment();
+ *
+ *   afterEach(async () => {
+ *     await env.cleanup();
+ *   });
+ *
+ *   it('should work', async () => {
+ *     const node = await env.createNode(MyTool);
+ *     expect(node.state).to.equal(NodeState.RUNNING);
+ *   });
+ * });
+ * ```
+ */
+import { NodeState } from '@olane/o-core';
+/**
+ * Core test environment class for O-Network testing
+ *
+ * Manages node lifecycle, automatic cleanup, and provides
+ * factory methods for common test scenarios.
+ *
+ * Note: This class does not include leader-related utilities to avoid
+ * circular dependencies with @olane/o-leader. Packages that need leader
+ * functionality should implement their own test utilities.
+ */
+export class TestEnvironment {
+    constructor() {
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Create a node
+     *
+     * @param NodeClass - Node class to instantiate
+     * @param config - Node configuration
+     * @param autoStart - Whether to start node automatically (default: true)
+     * @returns Node instance
+     *
+     * @example
+     * ```typescript
+     * const node = await env.createNode(MyTool, {
+     *   address: new oNodeAddress('o://test')
+     * });
+     * ```
+     */
+    async createNode(NodeClass, config = {}, autoStart = true) {
+        const node = new NodeClass({
+            parent: null,
+            leader: null,
+            ...config,
+        });
+        this.track(node);
+        if (autoStart) {
+            await node.start();
+        }
+        return node;
+    }
+    /**
+     * Track a node for automatic cleanup
+     *
+     * @param node - Node instance to track
+     *
+     * @example
+     * ```typescript
+     * const node = new MyNode({});
+     * env.track(node);
+     * await node.start();
+     * ```
+     */
+    track(node) {
+        this.nodes.push(node);
+    }
+    /**
+     * Register a cleanup callback
+     *
+     * Useful for cleaning up external resources (databases, files, etc.)
+     *
+     * @param callback - Async cleanup function
+     *
+     * @example
+     * ```typescript
+     * const db = await createTestDB();
+     * env.onCleanup(async () => {
+     *   await db.close();
+     * });
+     * ```
+     */
+    onCleanup(callback) {
+        this.cleanupCallbacks.push(callback);
+    }
+    /**
+     * Stop all tracked nodes and execute cleanup callbacks
+     *
+     * Stops nodes in reverse order (children before parents)
+     * Call this in afterEach hooks.
+     *
+     * @example
+     * ```typescript
+     * afterEach(async () => {
+     *   await env.cleanup();
+     * });
+     * ```
+     */
+    async cleanup() {
+        // Stop nodes in reverse order (children first)
+        const nodesToStop = [...this.nodes].reverse();
+        for (const node of nodesToStop) {
+            try {
+                if (node.state === NodeState.RUNNING) {
+                    await node.stop();
+                }
+            }
+            catch (error) {
+                console.error('Error stopping node:', error);
+            }
+        }
+        // Execute cleanup callbacks
+        for (const callback of this.cleanupCallbacks) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                console.error('Error in cleanup callback:', error);
+            }
+        }
+        // Clear tracking
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Get all tracked nodes
+     *
+     * @returns Array of tracked node instances
+     */
+    getNodes() {
+        return [...this.nodes];
+    }
+    /**
+     * Get count of tracked nodes
+     *
+     * @returns Number of tracked nodes
+     */
+    getNodeCount() {
+        return this.nodes.length;
+    }
+    /**
+     * Check if all tracked nodes are stopped
+     *
+     * @returns True if all nodes are stopped
+     */
+    allNodesStopped() {
+        return this.nodes.every(node => node.state === NodeState.STOPPED);
+    }
+    /**
+     * Wait for a condition to be true
+     *
+     * @param condition - Function that returns true when condition is met
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @param intervalMs - Check interval in milliseconds (default: 100)
+     * @returns Promise that resolves when condition is met or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * await env.waitFor(() => tool.isReady, 10000);
+     * ```
+     */
+    async waitFor(condition, timeoutMs = 5000, intervalMs = 100) {
+        const startTime = Date.now();
+        while (!condition()) {
+            if (Date.now() - startTime > timeoutMs) {
+                throw new Error(`Timeout waiting for condition after ${timeoutMs}ms`);
+            }
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+}

package/dist/test/helpers/test-node.tool.d.ts

@@ -1,14 +1,45 @@
 import { oNodeTool } from '../../src/o-node.tool.js';
+import { oNodeToolConfig } from '../../src/interfaces/o-node.tool-config.js';
+import { Libp2pConfig } from '@olane/o-config';
 /**
  * Test-only extension of oNodeTool that adds streaming test methods.
  * This class should only be used in test files and is not part of the production code.
+ *
+ * Compatible with TestEnvironment for automatic cleanup and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * import { TestEnvironment } from './helpers/index.js';
+ * import { TestNodeTool } from './helpers/test-node.tool.js';
+ *
+ * const env = new TestEnvironment();
+ * const tool = new TestNodeTool({ address: new oNodeAddress('o://test') });
+ * await tool.start();
+ * // TestEnvironment will handle cleanup automatically
+ * ```
  */
 export declare class TestNodeTool extends oNodeTool {
+    constructor(config: oNodeToolConfig);
+    configure(): Promise<Libp2pConfig>;
     /**
      * Test method that emits chunks for 10 seconds at 100ms intervals.
      * Used for testing streaming functionality across hierarchical networks.
      *
+     * This method demonstrates streaming responses with AsyncGenerator,
+     * which is a common pattern for real-time data processing and long-running operations.
+     *
      * @returns AsyncGenerator that yields 100 chunks over 10 seconds
+     * @example
+     * ```typescript
+     * const response = await tool.use(tool.address, {
+     *   method: 'test_stream',
+     *   params: {}
+     * });
+     *
+     * for await (const chunk of response) {
+     *   console.log(`Received chunk ${chunk.chunk}`);
+     * }
+     * ```
      */
     _tool_test_stream(): AsyncGenerator<any>;
 }

package/dist/test/helpers/test-node.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-node.tool.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC;;;;;OAKG;IACI,iBAAiB,IAAI,cAAc,CAAC,GAAG,CAAC;CAehD"}
+{"version":3,"file":"test-node.tool.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,MAAM,EAAE,eAAe;IAO7B,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAcxC;;;;;;;;;;;;;;;;;;;OAmBG;IACI,iBAAiB,IAAI,cAAc,CAAC,GAAG,CAAC;CAiBhD"}

package/dist/test/helpers/test-node.tool.js

@@ -1,14 +1,61 @@
 import { oNodeTool } from '../../src/o-node.tool.js';
+import { oNodeAddress } from '../../src/index.js';
 /**
  * Test-only extension of oNodeTool that adds streaming test methods.
  * This class should only be used in test files and is not part of the production code.
+ *
+ * Compatible with TestEnvironment for automatic cleanup and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * import { TestEnvironment } from './helpers/index.js';
+ * import { TestNodeTool } from './helpers/test-node.tool.js';
+ *
+ * const env = new TestEnvironment();
+ * const tool = new TestNodeTool({ address: new oNodeAddress('o://test') });
+ * await tool.start();
+ * // TestEnvironment will handle cleanup automatically
+ * ```
  */
 export class TestNodeTool extends oNodeTool {
+    constructor(config) {
+        super({
+            ...config,
+            address: new oNodeAddress('o://test')
+        });
+    }
+    async configure() {
+        const config = await super.configure();
+        config.connectionGater = {
+            denyDialPeer: (peerId) => {
+                return false;
+            },
+            // who can call us?
+            denyInboundEncryptedConnection: (peerId, maConn) => {
+                return false;
+            },
+        };
+        return config;
+    }
     /**
      * Test method that emits chunks for 10 seconds at 100ms intervals.
      * Used for testing streaming functionality across hierarchical networks.
      *
+     * This method demonstrates streaming responses with AsyncGenerator,
+     * which is a common pattern for real-time data processing and long-running operations.
+     *
      * @returns AsyncGenerator that yields 100 chunks over 10 seconds
+     * @example
+     * ```typescript
+     * const response = await tool.use(tool.address, {
+     *   method: 'test_stream',
+     *   params: {}
+     * });
+     *
+     * for await (const chunk of response) {
+     *   console.log(`Received chunk ${chunk.chunk}`);
+     * }
+     * ```
      */
     async *_tool_test_stream() {
         const totalDuration = 10000; // 10 seconds
@@ -17,9 +64,11 @@ export class TestNodeTool extends oNodeTool {
         for (let i = 0; i < totalChunks; i++) {
             yield {
                 chunk: i + 1,
+                total: totalChunks,
                 timestamp: new Date().toISOString(),
                 nodeAddress: this.address.toString(),
                 message: `Chunk ${i + 1} of ${totalChunks}`,
+                progress: ((i + 1) / totalChunks) * 100,
             };
             await new Promise((resolve) => setTimeout(resolve, intervalMs));
         }

package/dist/test/leader-transport-validation.spec.d.ts

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

package/dist/test/leader-transport-validation.spec.d.ts.map

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

package/dist/test/leader-transport-validation.spec.js

@@ -0,0 +1,177 @@
+import { expect } from 'chai';
+import { TestEnvironment } from './helpers/index.js';
+import { oNodeTool } from '../src/o-node.tool.js';
+import { oNodeAddress, oNodeTransport } from '../src/index.js';
+describe('Leader Transport Validation', () => {
+    const env = new TestEnvironment();
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    describe('Node with leader configuration', () => {
+        it('should fail to start when leader has no transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', []); // Empty transports
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should fail to start when leader has undefined transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader');
+            // Explicitly set transports to undefined
+            leaderAddress.transports = undefined;
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should fail to start when leader has null transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader');
+            // Explicitly set transports to null
+            leaderAddress.transports = null;
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('Leader address is defined');
+                expect(error.message).to.include('but has no transports');
+                expect(error.message).to.include('o://leader');
+            }
+        });
+        it('should start successfully when leader has valid transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', [
+                new oNodeTransport('/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWTest123'),
+            ]);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+        it('should start successfully when leader has multiple transports', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', [
+                new oNodeTransport('/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWTest123'),
+                new oNodeTransport('/ip4/192.168.1.1/tcp/4001/p2p/12D3KooWTest123'),
+            ]);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Node without leader configuration', () => {
+        it('should start successfully when leader is null', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://standalone'),
+                leader: null,
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+        it('should start successfully when leader is undefined', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://standalone'),
+                leader: undefined, // Explicitly undefined
+                parent: null,
+            });
+            // Should not throw
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Leader node (self-referential)', () => {
+        it('should start successfully as a leader without transports validation', async () => {
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://leader'),
+                leader: null, // Leader nodes don't need a leader reference
+                parent: null,
+                type: 'LEADER', // Set as leader node
+            });
+            // Should not throw - leader nodes don't need leader transports
+            await node.start();
+            expect(node.state).to.not.equal('STOPPED');
+            await node.stop();
+        });
+    });
+    describe('Error message content', () => {
+        it('should provide helpful error message with leader address', async () => {
+            const leaderAddress = new oNodeAddress('o://my-custom-leader', []);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                expect(error.message).to.include('o://my-custom-leader');
+                expect(error.message).to.include('Non-leader nodes require leader transports');
+                expect(error.message).to.include('Please provide transports');
+            }
+        });
+    });
+    describe('Validation timing', () => {
+        it('should fail before p2pNode creation (fast fail)', async () => {
+            const leaderAddress = new oNodeAddress('o://leader', []);
+            const node = new oNodeTool({
+                address: new oNodeAddress('o://child'),
+                leader: leaderAddress,
+                parent: null,
+            });
+            const startTime = Date.now();
+            try {
+                await node.start();
+                expect.fail('Expected node.start() to throw an error');
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                // Validation should happen very quickly (< 100ms)
+                // If it takes longer, it means we're doing expensive operations before validation
+                expect(duration).to.be.lessThan(100);
+                expect(error.message).to.include('Leader address is defined');
+                // Verify p2pNode was never created
+                expect(node.p2pNode).to.be.undefined;
+            }
+        });
+    });
+});

package/dist/test/network-communication.spec.d.ts

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

package/dist/test/network-communication.spec.d.ts.map

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