@olane/o-client-limited 0.7.50 → 0.7.52

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

@@ -1,10 +1,32 @@
 import { oNodeConnection } from '@olane/o-node';
 import type { oNodeConnectionConfig } from '@olane/o-node';
+import { oLimitedStreamManager } from './o-limited.stream-manager.js';
 /**
- * oLimitedConnection extends oNodeConnection with stream reuse enabled
+ * oLimitedConnection extends oNodeConnection with stream reuse for limited connections.
+ *
  * This is optimized for limited connections where creating new streams is expensive
+ * (mobile clients, browsers, resource-constrained environments).
+ *
+ * Stream Architecture:
+ * - 1 dedicated reader stream for receiving requests from receiver
+ * - Reuses outbound streams for multiple request-response cycles
+ *
+ * Features:
+ * - Automatic reader stream creation and maintenance
+ * - Single retry on reader failure
+ * - Stream reuse for outbound requests
+ * - Event emission for monitoring (reader-started, reader-failed, reader-recovered)
+ *
+ * Default Behavior:
+ * - Uses 'reuse' stream policy by default
+ * - Automatically initializes dedicated reader on connection start
  */
 export declare class oLimitedConnection extends oNodeConnection {
+    streamManager: oLimitedStreamManager;
     constructor(config: oNodeConnectionConfig);
+    /**
+     * Override close to cleanup stream manager properly
+     */
+    close(): Promise<void>;
 }
 //# sourceMappingURL=o-limited-connection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"o-limited-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-limited-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;gBACzC,MAAM,EAAE,qBAAqB;CAQ1C"}
+{"version":3,"file":"o-limited-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-limited-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EACL,qBAAqB,EAEtB,MAAM,+BAA+B,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IAC7C,aAAa,EAAE,qBAAqB,CAAC;gBAEjC,MAAM,EAAE,qBAAqB;IAmCzC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

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

@@ -1,15 +1,60 @@
 import { oNodeConnection } from '@olane/o-node';
+import { oLimitedStreamManager, } from './o-limited.stream-manager.js';
+import { StreamManagerEvent } from '@olane/o-node';
 /**
- * oLimitedConnection extends oNodeConnection with stream reuse enabled
+ * oLimitedConnection extends oNodeConnection with stream reuse for limited connections.
+ *
  * This is optimized for limited connections where creating new streams is expensive
+ * (mobile clients, browsers, resource-constrained environments).
+ *
+ * Stream Architecture:
+ * - 1 dedicated reader stream for receiving requests from receiver
+ * - Reuses outbound streams for multiple request-response cycles
+ *
+ * Features:
+ * - Automatic reader stream creation and maintenance
+ * - Single retry on reader failure
+ * - Stream reuse for outbound requests
+ * - Event emission for monitoring (reader-started, reader-failed, reader-recovered)
+ *
+ * Default Behavior:
+ * - Uses 'reuse' stream policy by default
+ * - Automatically initializes dedicated reader on connection start
  */
 export class oLimitedConnection extends oNodeConnection {
     constructor(config) {
         const reusePolicy = config.reusePolicy ?? 'reuse';
         super({
             ...config,
-            reusePolicy: reusePolicy,
+            reusePolicy,
         });
-        this.reusePolicy = reusePolicy;
+        // Replace the base streamManager with our limited version
+        const protocol = this.nextHopAddress.protocol +
+            (reusePolicy === 'reuse' ? '/reuse' : '');
+        const limitedConfig = {
+            p2pConnection: this.p2pConnection,
+            protocol,
+            remoteAddress: this.nextHopAddress,
+            requestHandler: config.requestHandler,
+        };
+        this.streamManager = new oLimitedStreamManager(limitedConfig);
+        // Set up event listeners for monitoring
+        this.streamManager.on(StreamManagerEvent.ReaderStarted, (data) => {
+            this.logger.info('Reader stream started', data);
+        });
+        this.streamManager.on(StreamManagerEvent.ReaderFailed, (data) => {
+            this.logger.warn('Reader stream failed', data);
+        });
+        this.streamManager.on(StreamManagerEvent.ReaderRecovered, (data) => {
+            this.logger.info('Reader stream recovered', data);
+        });
+    }
+    /**
+     * Override close to cleanup stream manager properly
+     */
+    async close() {
+        this.logger.debug('Closing limited connection');
+        await this.streamManager.close();
+        await super.close();
     }
 }

package/dist/src/connection/o-limited.stream-manager.d.ts

@@ -0,0 +1,79 @@
+import type { Stream } from '@libp2p/interface';
+import { oNodeStreamManager, oNodeStream, StreamManagerConfig } from '@olane/o-node';
+import type { StreamHandlerConfig } from '@olane/o-node';
+/**
+ * Extended configuration for limited stream manager
+ */
+export interface oLimitedStreamManagerConfig extends StreamManagerConfig {
+    /**
+     * Protocol string for creating streams
+     */
+    protocol: string;
+    /**
+     * Remote address for the connection
+     */
+    remoteAddress: any;
+    /**
+     * Optional request handler for bidirectional communication
+     */
+    requestHandler?: (request: any, stream: Stream) => Promise<any>;
+}
+/**
+ * Limited Stream Manager handles stream lifecycle for limited connections
+ * Features:
+ * - Maintains dedicated reader stream for receiving requests from receiver
+ * - Reuses outbound streams (no close after use)
+ * - Single retry on reader failure
+ * - No health checks (error handling on use)
+ */
+export declare class oLimitedStreamManager extends oNodeStreamManager {
+    private readerStream?;
+    private isReaderLoopActive;
+    private readerLoopAbortController?;
+    private outboundStream?;
+    private limitedConfig;
+    private closing;
+    constructor(config: oLimitedStreamManagerConfig);
+    /**
+     * Initialize the limited stream manager
+     * Creates dedicated reader stream and starts background read loop
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates and initializes the dedicated reader stream
+     */
+    private createReaderStream;
+    /**
+     * Sends stream initialization message to identify this as a reader stream
+     */
+    private sendStreamInitMessage;
+    /**
+     * Starts the background reader loop
+     * Continuously listens for incoming requests on the reader stream
+     */
+    private startReaderLoop;
+    /**
+     * Background reader loop implementation
+     */
+    private runReaderLoop;
+    /**
+     * Attempts to recover the reader stream (single retry)
+     */
+    private recoverReaderStream;
+    /**
+     * Override getOrCreateStream to reuse outbound streams
+     * Does not create new stream for every request
+     * Auto-initializes on first use
+     */
+    getOrCreateStream(protocol: string, remoteAddress: any, config?: StreamHandlerConfig): Promise<oNodeStream>;
+    /**
+     * Override releaseStream to NOT close the stream
+     * Keep streams open for reuse
+     */
+    releaseStream(streamId: string): Promise<void>;
+    /**
+     * Close the stream manager and cleanup all resources
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=o-limited.stream-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"o-limited.stream-manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-limited.stream-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EACL,kBAAkB,EAElB,WAAW,EACX,mBAAmB,EAGpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,aAAa,EAAE,GAAG,CAAC;IAEnB;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACjE;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,kBAAkB;IAC3D,OAAO,CAAC,YAAY,CAAC,CAAc;IACnC,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,yBAAyB,CAAC,CAAkB;IACpD,OAAO,CAAC,cAAc,CAAC,CAAc;IACrC,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,OAAO,CAAkB;gBAErB,MAAM,EAAE,2BAA2B;IAK/C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAqDjC;;OAEG;YACW,kBAAkB;IA4BhC;;OAEG;YACW,qBAAqB;IAiBnC;;;OAGG;YACW,eAAe;IAe7B;;OAEG;YACW,aAAa;IAwB3B;;OAEG;YACW,mBAAmB;IAgCjC;;;;OAIG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,GAAG,EAClB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,WAAW,CAAC;IA6BvB;;;OAGG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAqC7B"}

package/dist/src/connection/o-limited.stream-manager.js

@@ -0,0 +1,234 @@
+import { oError, oErrorCodes } from '@olane/o-core';
+import { oNodeStreamManager, StreamManagerEvent, } from '@olane/o-node';
+/**
+ * Limited Stream Manager handles stream lifecycle for limited connections
+ * Features:
+ * - Maintains dedicated reader stream for receiving requests from receiver
+ * - Reuses outbound streams (no close after use)
+ * - Single retry on reader failure
+ * - No health checks (error handling on use)
+ */
+export class oLimitedStreamManager extends oNodeStreamManager {
+    constructor(config) {
+        super(config);
+        this.isReaderLoopActive = false;
+        this.closing = false;
+        this.limitedConfig = config;
+    }
+    /**
+     * Initialize the limited stream manager
+     * Creates dedicated reader stream and starts background read loop
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        await super.initialize();
+        // Register InboundRequest listener if requestHandler provided
+        // This enables bidirectional communication - receiver can send requests to caller via reader stream
+        if (this.limitedConfig.requestHandler) {
+            this.eventEmitter.on(StreamManagerEvent.InboundRequest, async (data) => {
+                try {
+                    const result = await this.limitedConfig.requestHandler(data.request, data.stream);
+                    return result;
+                }
+                catch (error) {
+                    this.logger.error('Error in requestHandler for inbound request:', data.request.toString(), error);
+                    throw error; // StreamManager will handle error response
+                }
+            });
+            this.logger.debug('Registered InboundRequest handler for limited connection');
+        }
+        try {
+            // Create dedicated reader stream
+            await this.createReaderStream();
+            this.isInitialized = true;
+            this.logger.info('Limited stream manager initialized', {
+                remotePeer: this.limitedConfig.p2pConnection.remotePeer.toString(),
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to initialize limited stream manager:', error);
+            throw new oError(oErrorCodes.INTERNAL_ERROR, `Failed to initialize limited stream manager: ${error.message}`);
+        }
+    }
+    /**
+     * Creates and initializes the dedicated reader stream
+     */
+    async createReaderStream() {
+        try {
+            // Create reader stream using parent's createStream method
+            this.readerStream = await this.createStream(this.limitedConfig.protocol, this.limitedConfig.remoteAddress, {});
+            // Send self-identification message
+            await this.sendStreamInitMessage(this.readerStream.p2pStream);
+            // Start background reader loop
+            await this.startReaderLoop();
+            this.eventEmitter.emit(StreamManagerEvent.ReaderStarted, {
+                streamId: this.readerStream.p2pStream.id,
+            });
+            this.logger.info('Reader stream created and started', {
+                streamId: this.readerStream.p2pStream.id,
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to create reader stream:', error);
+            throw error;
+        }
+    }
+    /**
+     * Sends stream initialization message to identify this as a reader stream
+     */
+    async sendStreamInitMessage(stream) {
+        const initMessage = {
+            type: 'stream-init',
+            role: 'reader',
+            timestamp: Date.now(),
+            connectionId: this.limitedConfig.p2pConnection.id,
+        };
+        const messageBytes = new TextEncoder().encode(JSON.stringify(initMessage));
+        await this.sendLengthPrefixed(stream, messageBytes, {});
+        this.logger.debug('Sent stream-init message', {
+            streamId: stream.id,
+            role: 'reader',
+        });
+    }
+    /**
+     * Starts the background reader loop
+     * Continuously listens for incoming requests on the reader stream
+     */
+    async startReaderLoop() {
+        if (!this.readerStream || this.isReaderLoopActive) {
+            return;
+        }
+        this.isReaderLoopActive = true;
+        this.readerLoopAbortController = new AbortController();
+        // Start background task (don't await)
+        this.runReaderLoop().catch((error) => {
+            this.logger.error('Reader loop failed:', error);
+            this.isReaderLoopActive = false;
+        });
+    }
+    /**
+     * Background reader loop implementation
+     */
+    async runReaderLoop() {
+        if (!this.readerStream) {
+            return;
+        }
+        const stream = this.readerStream.p2pStream;
+        try {
+            // Continuous read loop using parent's handleIncomingStream
+            // This will process all incoming requests on the reader stream
+            await this.handleIncomingStream(stream, this.limitedConfig.p2pConnection);
+        }
+        catch (error) {
+            if (!this.closing) {
+                this.logger.error('Reader loop error, attempting recovery:', error);
+                await this.recoverReaderStream();
+            }
+        }
+        finally {
+            this.isReaderLoopActive = false;
+        }
+    }
+    /**
+     * Attempts to recover the reader stream (single retry)
+     */
+    async recoverReaderStream() {
+        try {
+            this.logger.info('Attempting to recover reader stream...');
+            // Close old stream if it exists
+            if (this.readerStream) {
+                try {
+                    await this.readerStream.p2pStream.close();
+                }
+                catch (e) {
+                    // Ignore close errors
+                }
+                this.readerStream = undefined;
+            }
+            // Try to recreate
+            await this.createReaderStream();
+            this.eventEmitter.emit(StreamManagerEvent.ReaderRecovered, {
+                failureCount: 1,
+            });
+            this.logger.info('Reader stream recovered successfully');
+        }
+        catch (error) {
+            this.logger.error('Reader stream recovery failed:', error);
+            this.eventEmitter.emit(StreamManagerEvent.ReaderFailed, {
+                error: error.message,
+                failureCount: 1,
+            });
+        }
+    }
+    /**
+     * Override getOrCreateStream to reuse outbound streams
+     * Does not create new stream for every request
+     * Auto-initializes on first use
+     */
+    async getOrCreateStream(protocol, remoteAddress, config = {}) {
+        // Auto-initialize on first use
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        // Check if we have an existing outbound stream that's still valid
+        if (this.outboundStream &&
+            this.outboundStream.p2pStream.status === 'open' &&
+            this.outboundStream.p2pStream.writeStatus === 'writable') {
+            this.logger.debug('Reusing existing outbound stream', {
+                streamId: this.outboundStream.p2pStream.id,
+            });
+            return this.outboundStream;
+        }
+        // Create new outbound stream if none exists or current is invalid
+        this.logger.debug('Creating new outbound stream (no valid stream to reuse)');
+        this.outboundStream = await this.createStream(protocol, remoteAddress, config);
+        return this.outboundStream;
+    }
+    /**
+     * Override releaseStream to NOT close the stream
+     * Keep streams open for reuse
+     */
+    async releaseStream(streamId) {
+        // Don't close the stream - just log that we're keeping it open
+        this.logger.debug('Keeping stream open for reuse', { streamId });
+        // Do NOT call super.releaseStream() as that would close the stream
+    }
+    /**
+     * Close the stream manager and cleanup all resources
+     */
+    async close() {
+        if (this.closing) {
+            return;
+        }
+        this.closing = true;
+        this.logger.info('Closing limited stream manager');
+        // Stop reader loop
+        if (this.readerLoopAbortController) {
+            this.readerLoopAbortController.abort();
+        }
+        this.isReaderLoopActive = false;
+        // Close reader stream
+        if (this.readerStream) {
+            try {
+                await this.readerStream.p2pStream.close();
+            }
+            catch (error) {
+                this.logger.warn('Error closing reader stream:', error);
+            }
+            this.readerStream = undefined;
+        }
+        // Close outbound stream
+        if (this.outboundStream) {
+            try {
+                await this.outboundStream.p2pStream.close();
+            }
+            catch (error) {
+                this.logger.warn('Error closing outbound stream:', error);
+            }
+            this.outboundStream = undefined;
+        }
+        this.eventEmitter.emit(StreamManagerEvent.ManagerClosed, undefined);
+    }
+}

package/dist/src/o-limited.tool.d.ts

@@ -1,15 +1,8 @@
 import { oNodeConnection, oNodeConnectionConfig, oNodeTool } from '@olane/o-node';
 import { oNodeConfig } from '@olane/o-node';
 export declare class oLimitedTool extends oNodeTool {
-    protected backgroundReaders: Map<string, boolean>;
     constructor(config: oNodeConfig);
     connect(config: oNodeConnectionConfig): Promise<oNodeConnection>;
-    /**
-     * Start a background reader on the stream to handle incoming requests.
-     * Uses handleIncomingStream which runs a persistent while loop,
-     * allowing the stream to receive multiple messages over its lifetime.
-     */
-    private startBackgroundReader;
     initConnectionManager(): Promise<void>;
 }
 //# sourceMappingURL=o-limited.tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"o-limited.tool.d.ts","sourceRoot":"","sources":["../../src/o-limited.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAI5C,qBAAa,YAAa,SAAQ,SAAS;IACzC,SAAS,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAa;gBAElD,MAAM,EAAE,WAAW;IAUzB,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA2BtE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA8CvB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7C"}
+{"version":3,"file":"o-limited.tool.d.ts","sourceRoot":"","sources":["../../src/o-limited.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,MAAM,EAAE,WAAW;IAUzB,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkBhE,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7C"}

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

@@ -9,7 +9,6 @@ export class oLimitedTool extends oNodeTool {
                 listeners: config.network?.listeners || [], // default to no listeners
             },
         });
-        this.backgroundReaders = new Map();
     }
     async connect(config) {
         this.handleProtocol(config.nextHopAddress).catch((error) => {
@@ -17,51 +16,14 @@ export class oLimitedTool extends oNodeTool {
         });
         // Inject requestHandler to enable bidirectional stream processing
         // This allows incoming router requests to be processed through the tool's execute method
+        // The StreamPoolManager (in oLimitedConnection) will use this handler for the dedicated reader
         const configWithHandler = {
             ...config,
             requestHandler: this.execute.bind(this),
         };
         const connection = await super.connect(configWithHandler);
-        // Hook postTransmit to start background reader for reuse streams
-        const originalPostTransmit = connection.postTransmit.bind(connection);
-        connection.postTransmit = async (stream) => {
-            // Start background reader for bidirectional communication on reuse streams
-            if (connection.reusePolicy === 'reuse') {
-                this.startBackgroundReader(stream, connection);
-            }
-            await originalPostTransmit(stream);
-        };
         return connection;
     }
-    /**
-     * Start a background reader on the stream to handle incoming requests.
-     * Uses handleIncomingStream which runs a persistent while loop,
-     * allowing the stream to receive multiple messages over its lifetime.
-     */
-    startBackgroundReader(stream, connection) {
-        const streamId = stream.p2pStream?.id || stream.id;
-        // Don't start duplicate readers for the same stream
-        if (this.backgroundReaders.get(streamId)) {
-            this.logger.debug('Background reader already running for stream:', streamId);
-            return;
-        }
-        this.backgroundReaders.set(streamId, true);
-        this.logger.debug('Starting background reader for stream:', streamId);
-        // Get the raw p2p stream
-        const p2pStream = stream.p2pStream || stream;
-        // Use the connection's streamHandler to handle incoming requests
-        const streamHandler = connection.streamHandler;
-        // Start the persistent read loop in the background
-        streamHandler
-            .handleIncomingStream(p2pStream, connection.p2pConnection, async (request, s) => {
-            this.logger.debug('Background reader received request:', request.method);
-            return this.execute(request, s);
-        })
-            .catch((error) => {
-            this.logger.debug('Background reader exited:', error?.message || 'stream closed');
-            this.backgroundReaders.delete(streamId);
-        });
-    }
     async initConnectionManager() {
         this.connectionManager = new oLimitedConnectionManager({
             p2pNode: this.p2pNode,

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

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

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

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