@olane/o-node 0.7.12-alpha.21 → 0.7.12-alpha.23

package/dist/o-core/src/streaming/stream-transport.interface.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Stream status states
+ */
+export declare enum StreamStatus {
+    OPEN = "open",
+    CLOSING = "closing",
+    CLOSED = "closed",
+    RESET = "reset"
+}
+/**
+ * Transport-agnostic interface for stream operations.
+ * Implementations can use libp2p, WebSockets, HTTP/2, or any other streaming transport.
+ */
+export interface IStreamTransport {
+    /**
+     * Send data through the stream with backpressure handling
+     * @param data - The data to send (UTF-8 encoded bytes)
+     * @returns Promise that resolves when data is sent (handles backpressure internally)
+     */
+    send(data: Uint8Array): Promise<void>;
+    /**
+     * Set up a message handler for incoming data
+     * @param handler - Callback function to handle incoming messages
+     */
+    onMessage(handler: (data: Uint8Array) => void): void;
+    /**
+     * Remove the message handler
+     */
+    removeMessageHandler(): void;
+    /**
+     * Close the stream and clean up resources
+     * @returns Promise that resolves when stream is closed
+     */
+    close(): Promise<void>;
+    /**
+     * Get the current status of the stream
+     * @returns The current stream status
+     */
+    getStatus(): StreamStatus;
+    /**
+     * Check if the stream is in a usable state
+     * @returns true if stream can send/receive data
+     */
+    isOpen(): boolean;
+}
+/**
+ * Configuration options for stream transport operations
+ */
+export interface StreamTransportConfig {
+    /**
+     * Timeout in milliseconds for drain operations when handling backpressure
+     * @default 30000 (30 seconds)
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Maximum time in milliseconds to wait for the first message
+     * @default 120000 (2 minutes)
+     */
+    readTimeoutMs?: number;
+}
+//# sourceMappingURL=stream-transport.interface.d.ts.map

package/dist/o-core/src/streaming/stream-transport.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-transport.interface.d.ts","sourceRoot":"","sources":["../../../../../o-core/src/streaming/stream-transport.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,YAAY;IACtB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,KAAK,UAAU;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IAErD;;OAEG;IACH,oBAAoB,IAAI,IAAI,CAAC;IAE7B;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;OAGG;IACH,SAAS,IAAI,YAAY,CAAC;IAE1B;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/o-core/src/streaming/stream-transport.interface.js

@@ -0,0 +1,10 @@
+/**
+ * Stream status states
+ */
+export var StreamStatus;
+(function (StreamStatus) {
+    StreamStatus["OPEN"] = "open";
+    StreamStatus["CLOSING"] = "closing";
+    StreamStatus["CLOSED"] = "closed";
+    StreamStatus["RESET"] = "reset";
+})(StreamStatus || (StreamStatus = {}));

package/dist/o-core/src/utils/streaming.utils.d.ts

@@ -0,0 +1,37 @@
+import { oResponse } from '../connection/o-response.js';
+/**
+ * Type guard to check if a value is an AsyncGenerator
+ * @param value - The value to check
+ * @returns true if the value is an AsyncGenerator
+ */
+export declare function isAsyncGenerator(value: any): value is AsyncGenerator;
+/**
+ * Safely iterate through an AsyncGenerator with error handling
+ * @param generator - The AsyncGenerator to iterate
+ * @param onChunk - Callback for each chunk
+ * @param onError - Optional error handler
+ * @returns Promise that resolves when iteration is complete
+ */
+export declare function iterateAsyncGenerator<T>(generator: AsyncGenerator<T>, onChunk: (chunk: T) => Promise<void> | void, onError?: (error: unknown) => void): Promise<void>;
+/**
+ * Create an oResponse object configured for streaming
+ * @param connectionId - The connection ID
+ * @param requestMethod - The request method
+ * @param requestId - The request ID
+ * @returns An oResponse configured for streaming
+ */
+export declare function createStreamingResponse(connectionId: string, requestMethod: string, requestId: string | number): oResponse;
+/**
+ * Collect all chunks from an AsyncGenerator into an array
+ * Useful for testing or converting streaming responses to non-streaming
+ * @param generator - The AsyncGenerator to collect from
+ * @returns Promise resolving to array of all chunks
+ */
+export declare function collectStreamChunks<T>(generator: AsyncGenerator<T>): Promise<T[]>;
+/**
+ * Process incoming stream data (deserialize from bytes)
+ * @param data - The data to process
+ * @returns Parsed message object
+ */
+export declare function processStream(data: Uint8Array): any;
+//# sourceMappingURL=streaming.utils.d.ts.map

package/dist/o-core/src/utils/streaming.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.utils.d.ts","sourceRoot":"","sources":["../../../../../o-core/src/utils/streaming.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,cAAc,CAMpE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,SAAS,CAQX;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,GAAG,CAGnD"}

package/dist/o-core/src/utils/streaming.utils.js

@@ -0,0 +1,71 @@
+import { oResponse } from '../connection/o-response.js';
+/**
+ * Type guard to check if a value is an AsyncGenerator
+ * @param value - The value to check
+ * @returns true if the value is an AsyncGenerator
+ */
+export function isAsyncGenerator(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        typeof value[Symbol.asyncIterator] === 'function');
+}
+/**
+ * Safely iterate through an AsyncGenerator with error handling
+ * @param generator - The AsyncGenerator to iterate
+ * @param onChunk - Callback for each chunk
+ * @param onError - Optional error handler
+ * @returns Promise that resolves when iteration is complete
+ */
+export async function iterateAsyncGenerator(generator, onChunk, onError) {
+    try {
+        for await (const chunk of generator) {
+            await onChunk(chunk);
+        }
+    }
+    catch (error) {
+        if (onError) {
+            onError(error);
+        }
+        else {
+            throw error;
+        }
+    }
+}
+/**
+ * Create an oResponse object configured for streaming
+ * @param connectionId - The connection ID
+ * @param requestMethod - The request method
+ * @param requestId - The request ID
+ * @returns An oResponse configured for streaming
+ */
+export function createStreamingResponse(connectionId, requestMethod, requestId) {
+    const response = new oResponse({
+        id: requestId,
+        _connectionId: connectionId,
+        _requestMethod: requestMethod,
+    });
+    response.isStreaming = true;
+    return response;
+}
+/**
+ * Collect all chunks from an AsyncGenerator into an array
+ * Useful for testing or converting streaming responses to non-streaming
+ * @param generator - The AsyncGenerator to collect from
+ * @returns Promise resolving to array of all chunks
+ */
+export async function collectStreamChunks(generator) {
+    const chunks = [];
+    for await (const chunk of generator) {
+        chunks.push(chunk);
+    }
+    return chunks;
+}
+/**
+ * Process incoming stream data (deserialize from bytes)
+ * @param data - The data to process
+ * @returns Parsed message object
+ */
+export function processStream(data) {
+    const text = new TextDecoder().decode(data);
+    return JSON.parse(text);
+}

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

@@ -0,0 +1,5 @@
+export * from './o-node-connection.js';
+export * from './o-node-connection.manager.js';
+export * from './interfaces/o-node-connection.config.js';
+export * from './interfaces/o-node-connection-manager.config.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/connection/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,cAAc,kDAAkD,CAAC"}

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

@@ -0,0 +1,4 @@
+export * from './o-node-connection.js';
+export * from './o-node-connection.manager.js';
+export * from './interfaces/o-node-connection.config.js';
+export * from './interfaces/o-node-connection-manager.config.js';

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,20 @@
+import { Connection, Stream } from '@olane/o-config';
+import { oConnection, oRequest, oResponse } from '@olane/o-core';
+import { oNodeConnectionConfig } from './interfaces/o-node-connection.config.js';
+export declare class oNodeConnection extends oConnection {
+    protected readonly config: oNodeConnectionConfig;
+    p2pConnection: Connection;
+    constructor(config: oNodeConnectionConfig);
+    read(source: Stream): Promise<any>;
+    validate(): void;
+    transmit(request: oRequest): Promise<oResponse>;
+    /**
+     * Transmit a request and receive streaming chunks via callback
+     * @param request The request to send
+     * @param onChunk Callback function called for each chunk received
+     * @returns Promise that resolves when stream is complete
+     */
+    transmitStreaming(request: oRequest, onChunk: (chunk: any, sequence: number, isLast: boolean) => void): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=o-node-connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAIV,MAAM,EAEP,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAIjF,qBAAa,eAAgB,SAAQ,WAAW;IAGlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAFrD,aAAa,EAAE,UAAU,CAAC;gBAEF,MAAM,EAAE,qBAAqB;IAKtD,IAAI,CAAC,MAAM,EAAE,MAAM;IAWzB,QAAQ;IAOF,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IAmDrD;;;;;OAKG;IACG,iBAAiB,CACrB,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAC/D,OAAO,CAAC,IAAI,CAAC;IA+FV,KAAK;CAKZ"}

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

@@ -0,0 +1,146 @@
+import { Uint8ArrayList, byteStream, } from '@olane/o-config';
+import { oConnection, oError, oErrorCodes, oResponse, } from '@olane/o-core';
+import { Libp2pStreamTransport } from '../streaming/libp2p-stream-transport.js';
+import { ProtocolBuilder } from '../../../o-core/src/streaming/protocol-builder.js';
+export class oNodeConnection extends oConnection {
+    constructor(config) {
+        super(config);
+        this.config = config;
+        this.p2pConnection = config.p2pConnection;
+    }
+    async read(source) {
+        const bytes = byteStream(source);
+        const output = await bytes.read({
+            signal: AbortSignal.timeout(this.config.readTimeoutMs ?? 120000), // Default: 2 min timeout
+        });
+        const outputObj = output instanceof Uint8ArrayList ? output.subarray() : output;
+        const jsonStr = new TextDecoder().decode(outputObj);
+        return JSON.parse(jsonStr);
+    }
+    validate() {
+        if (this.config.p2pConnection.status !== 'open') {
+            throw new Error('Connection is not valid');
+        }
+        // do nothing
+    }
+    async transmit(request) {
+        try {
+            const stream = await this.p2pConnection.newStream(this.nextHopAddress.protocol, {
+                maxOutboundStreams: Infinity,
+                runOnLimitedConnection: true, // TODO: should this be configurable?
+            });
+            if (!stream || (stream.status !== 'open' && stream.status !== 'reset')) {
+                throw new oError(oErrorCodes.FAILED_TO_DIAL_TARGET, 'Failed to dial target');
+            }
+            if (stream.status === 'reset') {
+                throw new oError(oErrorCodes.CONNECTION_LIMIT_REACHED, 'Connection limit reached');
+            }
+            // Send the data with backpressure handling (libp2p v3 best practice)
+            const data = new TextEncoder().encode(request.toString());
+            const sent = stream.send(data);
+            // If send() returns false, wait for the stream to drain before continuing
+            if (!sent) {
+                this.logger.debug('Stream buffer full, waiting for drain...');
+                await stream.onDrain({
+                    signal: AbortSignal.timeout(this.config.drainTimeoutMs ?? 30000),
+                }); // Default: 30 second timeout
+            }
+            const res = await this.read(stream);
+            await stream.close();
+            // process the response
+            const response = new oResponse({
+                ...res.result,
+            });
+            return response;
+        }
+        catch (error) {
+            if (error?.name === 'UnsupportedProtocolError') {
+                throw new oError(oErrorCodes.NOT_FOUND, 'Address not found');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Transmit a request and receive streaming chunks via callback
+     * @param request The request to send
+     * @param onChunk Callback function called for each chunk received
+     * @returns Promise that resolves when stream is complete
+     */
+    async transmitStreaming(request, onChunk) {
+        try {
+            const stream = await this.p2pConnection.newStream(this.nextHopAddress.protocol, {
+                maxOutboundStreams: Infinity,
+                runOnLimitedConnection: true,
+            });
+            if (!stream || (stream.status !== 'open' && stream.status !== 'reset')) {
+                throw new oError(oErrorCodes.FAILED_TO_DIAL_TARGET, 'Failed to dial target');
+            }
+            if (stream.status === 'reset') {
+                throw new oError(oErrorCodes.CONNECTION_LIMIT_REACHED, 'Connection limit reached');
+            }
+            // Create transport abstraction
+            const transport = new Libp2pStreamTransport(stream, {
+                drainTimeoutMs: this.config.drainTimeoutMs ?? 30000,
+                readTimeoutMs: this.config.readTimeoutMs ?? 120000,
+            });
+            // Send the request using the transport
+            const data = new TextEncoder().encode(request.toString());
+            await transport.send(data);
+            // Set up to receive multiple chunks
+            return new Promise((resolve, reject) => {
+                // Set up timeout for receiving first chunk
+                const timeout = setTimeout(async () => {
+                    transport.removeMessageHandler();
+                    await transport.close();
+                    reject(new oError(oErrorCodes.TIMEOUT, 'Timeout waiting for streaming response'));
+                }, this.config.readTimeoutMs ?? 120000);
+                let timeoutCleared = false;
+                const messageHandler = async (data) => {
+                    // Clear timeout on first message
+                    if (!timeoutCleared) {
+                        clearTimeout(timeout);
+                        timeoutCleared = true;
+                    }
+                    try {
+                        const response = ProtocolBuilder.decodeMessage(data);
+                        // Try to parse as streaming chunk
+                        const chunk = ProtocolBuilder.parseStreamChunk(response);
+                        if (chunk) {
+                            // Streaming response
+                            onChunk(chunk.data, chunk.sequence, chunk.isLast);
+                            if (chunk.isLast) {
+                                transport.removeMessageHandler();
+                                await transport.close();
+                                resolve();
+                            }
+                        }
+                        else {
+                            // Non-streaming response (fallback for compatibility)
+                            onChunk(response.result, 1, true);
+                            transport.removeMessageHandler();
+                            await transport.close();
+                            resolve();
+                        }
+                    }
+                    catch (error) {
+                        transport.removeMessageHandler();
+                        await transport.close();
+                        reject(error);
+                    }
+                };
+                transport.onMessage(messageHandler);
+            });
+        }
+        catch (error) {
+            if (error?.name === 'UnsupportedProtocolError') {
+                throw new oError(oErrorCodes.NOT_FOUND, 'Address not found');
+            }
+            throw error;
+        }
+    }
+    async close() {
+        this.logger.debug('Closing connection');
+        await this.p2pConnection.close();
+        this.logger.debug('Connection closed');
+    }
+}

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

@@ -0,0 +1,19 @@
+import { oAddress, oConnectionConfig, oConnectionManager } from '@olane/o-core';
+import { oConnection } from '@olane/o-core';
+import { oNodeConnectionManagerConfig } from './interfaces/o-node-connection-manager.config.js';
+import { oNodeConnection } from './o-node-connection.js';
+export declare class oNodeConnectionManager extends oConnectionManager {
+    private p2pNode;
+    private defaultReadTimeoutMs?;
+    private defaultDrainTimeoutMs?;
+    constructor(config: oNodeConnectionManagerConfig);
+    /**
+     * Connect to a given address with exponential backoff retry
+     * @param address - The address to connect to
+     * @returns The connection object
+     */
+    connect(config: oConnectionConfig): Promise<oNodeConnection>;
+    isCached(address: oAddress): boolean;
+    getCachedConnection(address: oAddress): oConnection | null;
+}
+//# sourceMappingURL=o-node-connection.manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;gBAE3B,MAAM,EAAE,4BAA4B;IAOhD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6FlE,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAIpC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI;CAe3D"}

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

@@ -0,0 +1,92 @@
+import { oConnectionManager } from '@olane/o-core';
+import { oNodeConnection } from './o-node-connection.js';
+export class oNodeConnectionManager extends oConnectionManager {
+    constructor(config) {
+        super(config);
+        this.p2pNode = config.p2pNode;
+        this.defaultReadTimeoutMs = config.defaultReadTimeoutMs;
+        this.defaultDrainTimeoutMs = config.defaultDrainTimeoutMs;
+    }
+    /**
+     * Connect to a given address with exponential backoff retry
+     * @param address - The address to connect to
+     * @returns The connection object
+     */
+    async connect(config) {
+        const { address, nextHopAddress, callerAddress, readTimeoutMs, drainTimeoutMs, } = config;
+        // check if we already have a connection to this address
+        // TODO: how can we enable caching of connections & connection lifecycles
+        if (this.isCached(nextHopAddress)) {
+            const cachedConnection = this.getCachedConnection(nextHopAddress);
+            if (cachedConnection &&
+                cachedConnection.p2pConnection.status === 'open') {
+                this.logger.debug('Using cached connection for address: ' + address.toString());
+                return cachedConnection;
+            }
+            else {
+                // cached item is not valid, remove it
+                this.cache.delete(nextHopAddress.toString());
+            }
+        }
+        // Retry configuration for handling transient connection failures
+        const MAX_RETRIES = 3;
+        const BASE_DELAY_MS = 1000; // Start with 1 second
+        const MAX_DELAY_MS = 10000; // Cap at 10 seconds
+        // first time setup connection with retry logic
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                if (attempt > 0) {
+                    // Calculate exponential backoff delay: 1s, 2s, 4s, 8s (capped at MAX_DELAY_MS)
+                    const delay = Math.min(BASE_DELAY_MS * Math.pow(2, attempt - 1), MAX_DELAY_MS);
+                    this.logger.debug(`Retry attempt ${attempt}/${MAX_RETRIES} for ${nextHopAddress.toString()} after ${delay}ms delay`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                const p2pConnection = await this.p2pNode.dial(nextHopAddress.libp2pTransports.map((ma) => ma.toMultiaddr()));
+                const connection = new oNodeConnection({
+                    nextHopAddress: nextHopAddress,
+                    address: address,
+                    p2pConnection: p2pConnection,
+                    callerAddress: callerAddress,
+                    readTimeoutMs: readTimeoutMs ?? this.defaultReadTimeoutMs,
+                    drainTimeoutMs: drainTimeoutMs ?? this.defaultDrainTimeoutMs,
+                });
+                if (attempt > 0) {
+                    this.logger.info(`Successfully connected to ${nextHopAddress.toString()} on retry attempt ${attempt}`);
+                }
+                // this.cache.set(nextHopAddress.toString(), connection);
+                return connection;
+            }
+            catch (error) {
+                lastError = error;
+                this.logger.warn(`[${callerAddress?.toString() || 'unknown'}] Connection attempt ${attempt + 1}/${MAX_RETRIES + 1} failed for ${nextHopAddress.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+                // Don't retry on the last attempt
+                if (attempt === MAX_RETRIES) {
+                    break;
+                }
+            }
+        }
+        // All retries exhausted
+        this.logger.error(`[${callerAddress?.toString() || 'unknown'}] Failed to connect after ${MAX_RETRIES + 1} attempts to address! Next hop: ${nextHopAddress} With Address: ${address.toString()}`, lastError);
+        throw lastError;
+    }
+    isCached(address) {
+        return this.cache.has(address.toString());
+    }
+    getCachedConnection(address) {
+        const key = address.toString();
+        try {
+            const connection = this.cache.get(key);
+            if (!connection) {
+                throw new Error('Connection not found in cache');
+            }
+            connection.validate();
+            return connection;
+        }
+        catch (error) {
+            this.cache.delete(key);
+            this.logger.error('Error getting cached connection:', error);
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,10 @@
+export * from './o-node.js';
+export * from './utils/network.utils.js';
+export * from './o-node.hierarchy-manager.js';
+export * from './interfaces/o-node.config.js';
+export * from './connection/index.js';
+export * from './o-node.tool.js';
+export * from './nodes/index.js';
+export * from './interfaces/o-node.tool-config.js';
+export * from './router/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC"}

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

@@ -0,0 +1,9 @@
+export * from './o-node.js';
+export * from './utils/network.utils.js';
+export * from './o-node.hierarchy-manager.js';
+export * from './interfaces/o-node.config.js';
+export * from './connection/index.js';
+export * from './o-node.tool.js';
+export * from './nodes/index.js';
+export * from './interfaces/o-node.tool-config.js';
+export * from './router/index.js';

package/dist/o-node/src/interfaces/i-heartbeatable-node.d.ts

@@ -0,0 +1,49 @@
+import { oNotificationManager } from '@olane/o-core';
+import { Libp2p } from '@olane/o-config';
+import { oNodeAddress } from '../router/o-node.address.js';
+/**
+ * Interface for nodes that support connection heartbeat monitoring.
+ * This interface defines the contract that oConnectionHeartbeatManager needs
+ * to access live hierarchy state without holding stale references.
+ */
+export interface IHeartbeatableNode {
+    /**
+     * The node's current address
+     */
+    address: oNodeAddress;
+    /**
+     * The notification manager for emitting heartbeat events
+     */
+    notificationManager: oNotificationManager;
+    /**
+     * The underlying libp2p node for ping operations
+     */
+    p2pNode: Libp2p;
+    /**
+     * The current parent address (with live transport updates)
+     * @returns Parent address or null if no parent
+     */
+    parent: oNodeAddress | null;
+    /**
+     * Get the current list of leader addresses
+     * @returns Array of leader addresses (empty if this node is the leader)
+     */
+    getLeaders(): oNodeAddress[];
+    /**
+     * Get the current list of parent addresses
+     * @returns Array of parent addresses
+     */
+    getParents(): oNodeAddress[];
+    /**
+     * Get the current list of child addresses
+     * @returns Array of child addresses
+     */
+    getChildren(): oNodeAddress[];
+    /**
+     * Remove a child from the hierarchy
+     * @param childAddress The address of the child to remove
+     */
+    removeChild(childAddress: oNodeAddress): void;
+    use(param1: any, param2: any): Promise<any>;
+}
+//# sourceMappingURL=i-heartbeatable-node.d.ts.map

package/dist/o-node/src/interfaces/i-heartbeatable-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-heartbeatable-node.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/i-heartbeatable-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,mBAAmB,EAAE,oBAAoB,CAAC;IAE1C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B;;;OAGG;IACH,UAAU,IAAI,YAAY,EAAE,CAAC;IAE7B;;;OAGG;IACH,UAAU,IAAI,YAAY,EAAE,CAAC;IAE7B;;;OAGG;IACH,WAAW,IAAI,YAAY,EAAE,CAAC;IAE9B;;;OAGG;IACH,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAE9C,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7C"}

package/dist/o-node/src/interfaces/i-heartbeatable-node.js

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

package/dist/o-node/src/interfaces/i-reconnectable-node.d.ts

@@ -0,0 +1,46 @@
+import { oAddress, NodeState, oNotificationManager } from '@olane/o-core';
+import { oNodeAddress } from '../router/o-node.address.js';
+import { oNodeConfig } from './o-node.config.js';
+/**
+ * Interface for nodes that support reconnection management.
+ * This interface defines the contract that oReconnectionManager needs
+ * to perform reconnection operations without creating a circular dependency.
+ */
+export interface IReconnectableNode {
+    /**
+     * The node's configuration
+     */
+    config: oNodeConfig;
+    /**
+     * The node's current address
+     */
+    address: oNodeAddress;
+    /**
+     * The node's current state
+     */
+    state: NodeState;
+    /**
+     * The notification manager for subscribing to events
+     */
+    notificationManager: oNotificationManager;
+    /**
+     * Register with the parent node
+     */
+    registerParent(): Promise<void>;
+    /**
+     * Register with the leader's global registry
+     */
+    register(): Promise<void>;
+    useSelf(request?: any): Promise<any>;
+    /**
+     * Execute a method on another node
+     */
+    use(address: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }): Promise<any>;
+}
+//# sourceMappingURL=i-reconnectable-node.d.ts.map