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

package/dist/test/helpers/network-builder.js

@@ -0,0 +1,309 @@
+import { oNodeTool } from '../../src/o-node.tool.js';
+import { oNodeAddress } from '../../src/router/o-node.address.js';
+import { oAddress } from '@olane/o-core';
+/**
+ * Simple test tool for network communication testing
+ */
+export class TestTool extends oNodeTool {
+    constructor(config) {
+        super(config);
+        this.callCount = 0;
+    }
+    async configure() {
+        const config = await super.configure();
+        config.connectionGater = {
+            denyDialPeer: (peerId) => {
+                return false;
+            },
+            // who can call us?
+            denyInboundEncryptedConnection: (peerId, maConn) => {
+                return false;
+            },
+        };
+        return config;
+    }
+    // NEED TO OVERRIDE to ensure that we can test fully without a proper leader node
+    async registerParent() {
+        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()) {
+                this.parent.setTransports(this.leader?.libp2pTransports || []);
+            }
+            else {
+                this.logger.debug('Waiting for parent and reconnecting...');
+                await this.reconnectionManager?.waitForParentAndReconnect();
+            }
+        }
+        // if no parent transports, register with the parent to get them
+        // 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());
+            // avoid transports to ensure we do not try direct connection, we need to route via the leader for proper access controls
+            await this.use(this.config.parent, {
+                method: 'child_register',
+                params: {
+                    address: this.address.toString(),
+                    transports: this.transports.map((t) => t.toString()),
+                    peerId: this.peerId.toString(),
+                    _token: this.config.joinToken,
+                },
+            });
+            this.setKeepAliveTag(this.parent);
+        }
+    }
+    async _tool_echo(request) {
+        this.callCount++;
+        return {
+            message: request.params.message || 'echo',
+            nodeAddress: this.address.toString(),
+            timestamp: Date.now(),
+        };
+    }
+    async _tool_get_info(request) {
+        return {
+            address: this.address.toString(),
+            parent: this.parent?.toString(),
+            children: this.getChildren().map((c) => c.toString()),
+            callCount: this.callCount,
+        };
+    }
+    async *_tool_stream(request) {
+        const count = request.params.count || 5;
+        for (let i = 0; i < count; i++) {
+            yield {
+                chunk: i + 1,
+                total: count,
+                nodeAddress: this.address.toString(),
+                timestamp: Date.now(),
+            };
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+}
+/**
+ * Simplified network topology builder for testing node-to-node communication
+ * Focuses on peer connections and parent-child relationships without leader abstractions
+ */
+export class NetworkBuilder {
+    constructor() {
+        this.nodes = new Map();
+        this.startedNodes = new Set();
+    }
+    /**
+     * Add a node to the network
+     * If parentAddress is provided, the node will register as a child
+     */
+    async addNode(address, parentAddress, config = {}) {
+        const seed = config.seed || `node-seed-${address}-${Date.now()}`;
+        let parentNode;
+        let parentRef = null;
+        if (parentAddress) {
+            parentNode = this.nodes.get(parentAddress);
+            if (!parentNode) {
+                throw new Error(`Parent node not found: ${parentAddress}`);
+            }
+            // Wait for parent to have transports
+            // await this.waitForTransports(parentNode);
+            parentRef = new oNodeAddress(parentNode.address.toString(), parentNode.address.libp2pTransports);
+        }
+        const node = new TestTool({
+            address: new oNodeAddress(address),
+            parent: parentRef,
+            leader: null, // No leader abstraction in o-node tests
+            seed,
+            connectionHeartbeat: {
+                enabled: !config.disableHeartbeat,
+                checkChildren: parentAddress ? false : true, // Only root monitors children
+            },
+        });
+        this.nodes.set(address, node);
+        await this.startNode(address);
+        return node;
+    }
+    /**
+     * Start a specific node
+     */
+    async startNode(address) {
+        const node = this.nodes.get(address);
+        if (!node) {
+            throw new Error(`Node not found: ${address}`);
+        }
+        if (this.startedNodes.has(address)) {
+            return; // Already started
+        }
+        await node.start();
+        this.startedNodes.add(address);
+        // Wait for transports to be available
+        // await this.waitForTransports(node);
+    }
+    /**
+     * Stop a specific node
+     */
+    async stopNode(address) {
+        const node = this.nodes.get(address);
+        if (!node) {
+            throw new Error(`Node not found: ${address}`);
+        }
+        if (!this.startedNodes.has(address)) {
+            return; // Not started
+        }
+        await node.stop();
+        this.startedNodes.delete(address);
+    }
+    /**
+     * Stop all nodes in the network
+     * Stops in reverse dependency order: children first, then parents
+     */
+    async stopAll() {
+        const sortedNodes = this.getSortedNodesByDepth().reverse();
+        for (const address of sortedNodes) {
+            if (this.startedNodes.has(address)) {
+                await this.stopNode(address);
+            }
+        }
+    }
+    /**
+     * Get a node by address
+     */
+    getNode(address) {
+        return this.nodes.get(address);
+    }
+    /**
+     * Get all nodes
+     */
+    getAllNodes() {
+        return new Map(this.nodes);
+    }
+    /**
+     * Sort nodes by hierarchy depth (root nodes first)
+     */
+    getSortedNodesByDepth() {
+        const depths = new Map();
+        const addresses = Array.from(this.nodes.keys());
+        // Calculate depth for each node
+        const calculateDepth = (address) => {
+            if (depths.has(address)) {
+                return depths.get(address);
+            }
+            const node = this.nodes.get(address);
+            if (!node.parent) {
+                depths.set(address, 0);
+                return 0;
+            }
+            // Find parent address in our map
+            const parentAddress = Array.from(this.nodes.entries()).find(([_, n]) => n.address.toString() === node.parent?.toString())?.[0];
+            if (!parentAddress) {
+                depths.set(address, 0);
+                return 0;
+            }
+            const depth = calculateDepth(parentAddress) + 1;
+            depths.set(address, depth);
+            return depth;
+        };
+        addresses.forEach((addr) => calculateDepth(addr));
+        // Sort by depth (ascending)
+        return addresses.sort((a, b) => {
+            const depthA = depths.get(a) || 0;
+            const depthB = depths.get(b) || 0;
+            return depthA - depthB;
+        });
+    }
+    /**
+     * Wait for a node to have transports available
+     */
+    async waitForTransports(node, timeoutMs = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            if (node.address.libp2pTransports.length > 0) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        throw new Error(`Timeout waiting for transports on ${node.address.toString()}`);
+    }
+    /**
+     * Clean up all nodes
+     */
+    async cleanup() {
+        await this.stopAll();
+        this.nodes.clear();
+        this.startedNodes.clear();
+    }
+}
+/**
+ * Quick network topology builders for common test scenarios
+ * All topologies use simple parent-child relationships without leader abstractions
+ * Note: "leader" in address names is just a convention, not a special node type
+ */
+export class NetworkTopologies {
+    /**
+     * Create a simple two-node network (parent-child)
+     * Addresses: o://leader (root), o://child
+     */
+    static async twoNode() {
+        const builder = new NetworkBuilder();
+        await builder.addNode('o://leader');
+        await builder.addNode('o://child', 'o://leader');
+        return builder;
+    }
+    /**
+     * Create a three-node hierarchy (leader → parent → child)
+     * Addresses: o://leader (root), o://parent, o://child
+     */
+    static async threeNode() {
+        const builder = new NetworkBuilder();
+        await builder.addNode('o://leader');
+        await builder.addNode('o://parent', 'o://leader');
+        await builder.addNode('o://child', 'o://parent');
+        return builder;
+    }
+    /**
+     * Create a five-node hierarchy with two branches
+     * Structure: leader → parent1 → child1, child2
+     *                  → parent2
+     */
+    static async fiveNode() {
+        const builder = new NetworkBuilder();
+        await builder.addNode('o://leader');
+        await builder.addNode('o://parent1', 'o://leader');
+        await builder.addNode('o://parent2', 'o://leader');
+        await builder.addNode('o://child1', 'o://parent1');
+        await builder.addNode('o://child2', 'o://parent1');
+        return builder;
+    }
+    /**
+     * Create two standalone nodes (peer-to-peer)
+     */
+    static async twoStandalone() {
+        const builder = new NetworkBuilder();
+        await builder.addNode('o://node1');
+        await builder.addNode('o://node2');
+        return builder;
+    }
+    /**
+     * Create a complex hierarchy for integration testing
+     * Structure: leader → parent1 → child1, child2
+     *                  → parent2 → child3, child4
+     *                  → parent3 → child5, child6
+     */
+    static async complex() {
+        const builder = new NetworkBuilder();
+        await builder.addNode('o://leader');
+        // Add three parent nodes
+        await builder.addNode('o://parent1', 'o://leader');
+        await builder.addNode('o://parent2', 'o://leader');
+        await builder.addNode('o://parent3', 'o://leader');
+        // Add children to each parent
+        await builder.addNode('o://parent1-child1', 'o://parent1');
+        await builder.addNode('o://parent1-child2', 'o://parent1');
+        await builder.addNode('o://parent2-child1', 'o://parent2');
+        await builder.addNode('o://parent2-child2', 'o://parent2');
+        await builder.addNode('o://parent3-child1', 'o://parent3');
+        await builder.addNode('o://parent3-child2', 'o://parent3');
+        return builder;
+    }
+}

package/dist/test/helpers/simple-node-builder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SimpleNodeBuilder - Fluent API for creating single-node tests
+ *
+ * @example
+ * ```typescript
+ * const node = await new SimpleNodeBuilder(MyTool)
+ *   .withConfig({ apiKey: 'test' })
+ *   .withAddress('o://test-tool')
+ *   .build(env);
+ * ```
+ */
+import type { oNodeTool } from '../../src/o-node.tool.js';
+import type { oNodeAddress } from '../../src/router/o-node.address.js';
+import type { TestEnvironment } from './test-environment.js';
+import type { TestNodeConfig } from './test-environment.js';
+export declare class SimpleNodeBuilder<T extends oNodeTool = any> {
+    private nodeClass;
+    private config;
+    private autoStart;
+    constructor(NodeClass: new (config: any) => T);
+    /**
+     * Set node configuration
+     */
+    withConfig(config: TestNodeConfig): this;
+    /**
+     * Set node address
+     */
+    withAddress(address: oNodeAddress): this;
+    /**
+     * Set node description
+     */
+    withDescription(description: string): this;
+    /**
+     * Set leader reference
+     */
+    withLeader(leader: oNodeAddress | null): this;
+    /**
+     * Set parent reference
+     */
+    withParent(parent: oNodeAddress | null): this;
+    /**
+     * Control automatic start
+     */
+    withAutoStart(autoStart: boolean): this;
+    /**
+     * Build and create the node
+     */
+    build(env: TestEnvironment): Promise<T>;
+}
+//# sourceMappingURL=simple-node-builder.d.ts.map

package/dist/test/helpers/simple-node-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-node-builder.d.ts","sourceRoot":"","sources":["../../../test/helpers/simple-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,qBAAa,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,GAAG;IACtD,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,KAAK,CAAC;IAI7C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKxC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKxC;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK1C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAK7C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAK7C;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAKvC;;OAEG;IACG,KAAK,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC;CAG9C"}

package/dist/test/helpers/simple-node-builder.js

@@ -0,0 +1,66 @@
+/**
+ * SimpleNodeBuilder - Fluent API for creating single-node tests
+ *
+ * @example
+ * ```typescript
+ * const node = await new SimpleNodeBuilder(MyTool)
+ *   .withConfig({ apiKey: 'test' })
+ *   .withAddress('o://test-tool')
+ *   .build(env);
+ * ```
+ */
+export class SimpleNodeBuilder {
+    constructor(NodeClass) {
+        this.config = {};
+        this.autoStart = true;
+        this.nodeClass = NodeClass;
+    }
+    /**
+     * Set node configuration
+     */
+    withConfig(config) {
+        this.config = { ...this.config, ...config };
+        return this;
+    }
+    /**
+     * Set node address
+     */
+    withAddress(address) {
+        this.config.address = address;
+        return this;
+    }
+    /**
+     * Set node description
+     */
+    withDescription(description) {
+        this.config.description = description;
+        return this;
+    }
+    /**
+     * Set leader reference
+     */
+    withLeader(leader) {
+        this.config.leader = leader;
+        return this;
+    }
+    /**
+     * Set parent reference
+     */
+    withParent(parent) {
+        this.config.parent = parent;
+        return this;
+    }
+    /**
+     * Control automatic start
+     */
+    withAutoStart(autoStart) {
+        this.autoStart = autoStart;
+        return this;
+    }
+    /**
+     * Build and create the node
+     */
+    async build(env) {
+        return await env.createNode(this.nodeClass, this.config, this.autoStart);
+    }
+}

package/dist/test/helpers/test-environment.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 type { oNode } from '../../src/o-node.js';
+import type { oNodeAddress } from '../../src/router/o-node.address.js';
+/**
+ * Node configuration for test environment
+ */
+export interface TestNodeConfig {
+    address?: oNodeAddress;
+    leader?: oNodeAddress | null;
+    parent?: oNodeAddress | null;
+    description?: string;
+    [key: string]: any;
+}
+/**
+ * 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 declare class TestEnvironment {
+    private nodes;
+    private 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')
+     * });
+     * ```
+     */
+    createNode<T extends oNode>(NodeClass: new (config: any) => T, config?: TestNodeConfig, autoStart?: boolean): Promise<T>;
+    /**
+     * 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: oNode): void;
+    /**
+     * 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: () => Promise<void>): void;
+    /**
+     * 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();
+     * });
+     * ```
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get all tracked nodes
+     *
+     * @returns Array of tracked node instances
+     */
+    getNodes(): oNode[];
+    /**
+     * Get count of tracked nodes
+     *
+     * @returns Number of tracked nodes
+     */
+    getNodeCount(): number;
+    /**
+     * Check if all tracked nodes are stopped
+     *
+     * @returns True if all nodes are stopped
+     */
+    allNodesStopped(): boolean;
+    /**
+     * 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);
+     * ```
+     */
+    waitFor(condition: () => boolean, timeoutMs?: number, intervalMs?: number): Promise<void>;
+}
+//# sourceMappingURL=test-environment.d.ts.map

package/dist/test/helpers/test-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-environment.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,gBAAgB,CAAkC;IAE1D;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,CAAC,SAAS,KAAK,EAC9B,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,KAAK,CAAC,EACjC,MAAM,GAAE,cAAmB,EAC3B,SAAS,GAAE,OAAc,GACxB,OAAO,CAAC,CAAC,CAAC;IAgBb;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAIxB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI9C;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B9B;;;;OAIG;IACH,QAAQ,IAAI,KAAK,EAAE;IAInB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;;;;;;;;;OAYG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,OAAO,EACxB,SAAS,GAAE,MAAa,EACxB,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC,IAAI,CAAC;CAUjB"}