@olane/o-node 0.7.6 → 0.7.8

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

@@ -1 +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;AAEjF,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;IAuC/C,KAAK;CAKZ"}
+{"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;AAEjF,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;IAyC/C,KAAK;CAKZ"}

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

@@ -25,6 +25,7 @@ export class oNodeConnection extends oConnection {
         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');
@@ -35,6 +36,7 @@ export class oNodeConnection extends oConnection {
             // Send the data
             await stream.send(new TextEncoder().encode(request.toString()));
             const res = await this.read(stream);
+            await stream.close();
             // process the response
             const response = new oResponse({
                 ...res.result,

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

@@ -1 +1 @@
-{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAKL,QAAQ,EAET,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAGnF,OAAO,EAAmB,SAAS,EAAE,MAAM,eAAe,CAAC;AAI3D,qBAAa,KAAM,SAAQ,SAAS;IAC3B,MAAM,EAAG,MAAM,CAAC;IAChB,OAAO,EAAG,MAAM,CAAC;IACjB,OAAO,EAAG,YAAY,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,iBAAiB,EAAG,sBAAsB,CAAC;IAC3C,gBAAgB,EAAG,qBAAqB,CAAC;IAChD,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;gBAE3B,MAAM,EAAE,WAAW;IAK/B,IAAI,MAAM,IAAI,YAAY,GAAG,IAAI,CAEhC;IAED,IAAI,aAAa,IAAI,YAAY,CAKhC;IAED,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAOhC;IAED,mBAAmB,IAAI,GAAG,EAAE;IAItB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC,IAAI,aAAa,IAAI,YAAY,CAEhC;IAED,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAEvC;IAED,IAAI,UAAU,IAAI,cAAc,EAAE,CAIjC;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC/B,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAG1D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;cA0FxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvC,OAAO,CACX,cAAc,EAAE,YAAY,EAC5B,aAAa,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC;IA0BrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAOhC"}
+{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAKL,QAAQ,EAET,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAGnF,OAAO,EAAmB,SAAS,EAAE,MAAM,eAAe,CAAC;AAI3D,qBAAa,KAAM,SAAQ,SAAS;IAC3B,MAAM,EAAG,MAAM,CAAC;IAChB,OAAO,EAAG,MAAM,CAAC;IACjB,OAAO,EAAG,YAAY,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,iBAAiB,EAAG,sBAAsB,CAAC;IAC3C,gBAAgB,EAAG,qBAAqB,CAAC;IAChD,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;gBAE3B,MAAM,EAAE,WAAW;IAK/B,IAAI,MAAM,IAAI,YAAY,GAAG,IAAI,CAEhC;IAED,IAAI,aAAa,IAAI,YAAY,CAKhC;IAED,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAOhC;IAED,mBAAmB,IAAI,GAAG,EAAE;IAItB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC,IAAI,aAAa,IAAI,YAAY,CAEhC;IAED,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAEvC;IAED,IAAI,UAAU,IAAI,cAAc,EAAE,CAIjC;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC/B,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAG1D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;cA0FxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvC,OAAO,CACX,cAAc,EAAE,YAAY,EAC5B,aAAa,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC;IA0BrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAOhC"}

package/dist/src/o-node.js

@@ -80,6 +80,7 @@ export class oNode extends oToolBase {
             return;
         }
         // 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.config.parent.transports.length === 0) {
             this.logger.debug('Registering node with parent...', this.config.parent);
             const parentRegistration = await this.use(this.config.parent, {

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

@@ -3,10 +3,43 @@ import { oRouterRequest, RouteResponse } from '@olane/o-core';
 import type { oNode } from '../o-node.js';
 import { oToolRouter } from '@olane/o-tool';
 export declare class oNodeRouter extends oToolRouter {
+    private routingPolicy;
     constructor();
+    /**
+     * Forwards a request to the specified address via libp2p transport.
+     * Handles self-routing (local execution) and destination detection.
+     *
+     * @param address The next hop address to forward to
+     * @param request The router request to forward
+     * @param node The current node context
+     * @returns The response from the forwarded request
+     */
     protected forward(address: oNodeAddress, request: oRouterRequest, node: oNode): Promise<any>;
-    private handleExternalAddress;
+    /**
+     * Executes a request locally when routing to self.
+     */
+    private executeSelfRouting;
+    /**
+     * Checks if the next hop is the final destination address.
+     */
+    private isDestinationAddress;
+    /**
+     * Unwraps the routing envelope when we've reached the destination.
+     */
+    private unwrapDestinationRequest;
+    /**
+     * Dials a remote node and transmits the request via libp2p.
+     */
+    private dialAndTransmit;
+    /**
+     * Translates an address to determine the next hop and target addresses.
+     * First checks routing policy for external routing, then applies resolver chain.
+     */
     translate(address: oNodeAddress, node: oNode): Promise<RouteResponse>;
+    /**
+     * Determines if an address is internal to this node's hierarchy.
+     * Delegates to the routing policy for the decision.
+     */
     isInternal(addressWithTransports: oNodeAddress, node: oNode): boolean;
 }
 //# sourceMappingURL=o-node.router.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"o-node.router.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAML,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,qBAAa,WAAY,SAAQ,WAAW;;cAK1B,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,GAAG,CAAC;IA0Ef,OAAO,CAAC,qBAAqB;IAsBvB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;IAqB3E,UAAU,CAAC,qBAAqB,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;CAetE"}
+{"version":3,"file":"o-node.router.d.ts","sourceRoot":"","sources":["../../../src/router/o-node.router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAML,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAK5C,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,aAAa,CAAqB;;IAO1C;;;;;;;;OAQG;cACa,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,GAAG,CAAC;IA0Bf;;OAEG;YACW,kBAAkB;IAgBhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;OAEG;YACW,eAAe;IA2B7B;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB3E;;;OAGG;IACH,UAAU,CAAC,qBAAqB,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO;CAGtE"}

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

@@ -1,62 +1,89 @@
-import { oNodeAddress } from './o-node.address.js';
-import { CoreUtils, oAddress, oError, oErrorCodes, oRequest, } from '@olane/o-core';
+import { oAddress, oError, oErrorCodes, oRequest, } from '@olane/o-core';
 import { oToolRouter } from '@olane/o-tool';
 import { oNodeConnection } from '../connection/o-node-connection.js';
+import { oNodeRoutingPolicy } from './o-node.routing-policy.js';
 export class oNodeRouter extends oToolRouter {
     constructor() {
         super();
+        this.routingPolicy = new oNodeRoutingPolicy();
     }
+    /**
+     * Forwards a request to the specified address via libp2p transport.
+     * Handles self-routing (local execution) and destination detection.
+     *
+     * @param address The next hop address to forward to
+     * @param request The router request to forward
+     * @param node The current node context
+     * @returns The response from the forwarded request
+     */
     async forward(address, request, node) {
         if (!request.stream) {
             throw new oError(oErrorCodes.INVALID_REQUEST, 'Stream is required');
         }
-        const stream = request.stream;
         let nextHopRequest = new oRequest({
             method: request.method,
             params: request.params,
             id: request.id,
         });
-        // are we dialing self?
-        if (node.address.toString() === address.toString()) {
-            const { payload } = request.params;
-            const params = payload.params;
-            nextHopRequest = new oRequest({
-                method: payload.method,
-                params: {
-                    ...params,
-                },
-                id: request.id,
-            });
-            const result = await node.execute(nextHopRequest);
-            const response = CoreUtils.buildResponse(nextHopRequest, result, result?.error);
-            // add the request method to the response
-            return response;
+        // Handle self-routing: execute locally instead of dialing
+        if (this.routingPolicy.isSelfAddress(address, node)) {
+            return this.executeSelfRouting(request, node);
         }
-        // next hop is the destination address
-        if (address
-            ?.toStaticAddress()
-            .equals(new oAddress(request?.params?.address).toStaticAddress())) {
-            // reached destination, so change from route to actual request
-            const { payload } = request.params;
-            const params = payload.params;
-            nextHopRequest = new oRequest({
-                method: payload.method,
-                params: {
-                    ...params,
-                },
-                id: request.id,
-            });
+        // Check if we've reached the final destination
+        const isDestination = this.isDestinationAddress(address, request);
+        if (isDestination) {
+            nextHopRequest = this.unwrapDestinationRequest(request);
         }
-        // dial the target
+        // Dial and transmit to remote node
+        return this.dialAndTransmit(address, nextHopRequest, node);
+    }
+    /**
+     * Executes a request locally when routing to self.
+     */
+    async executeSelfRouting(request, node) {
+        const { payload } = request.params;
+        const params = payload.params;
+        const localRequest = new oRequest({
+            method: payload.method,
+            params: { ...params },
+            id: request.id,
+        });
+        const result = await node.execute(localRequest);
+        return result;
+    }
+    /**
+     * Checks if the next hop is the final destination address.
+     */
+    isDestinationAddress(address, request) {
+        return address
+            ?.toStaticAddress()
+            .equals(new oAddress(request?.params?.address).toStaticAddress());
+    }
+    /**
+     * Unwraps the routing envelope when we've reached the destination.
+     */
+    unwrapDestinationRequest(request) {
+        const { payload } = request.params;
+        const params = payload.params;
+        return new oRequest({
+            method: payload.method,
+            params: { ...params },
+            id: request.id,
+        });
+    }
+    /**
+     * Dials a remote node and transmits the request via libp2p.
+     */
+    async dialAndTransmit(address, request, node) {
         try {
-            const connection = await node?.p2pNode.dial(address.libp2pTransports.map((t) => t.toMultiaddr()));
+            const connection = await node.p2pNode.dial(address.libp2pTransports.map((t) => t.toMultiaddr()));
             const nodeConnection = new oNodeConnection({
                 p2pConnection: connection,
                 nextHopAddress: address,
                 address: node.address,
                 callerAddress: node.address,
             });
-            const response = await nodeConnection.transmit(nextHopRequest);
+            const response = await nodeConnection.transmit(request);
             return response.result.data;
         }
         catch (error) {
@@ -66,26 +93,17 @@ export class oNodeRouter extends oToolRouter {
             throw error;
         }
     }
-    handleExternalAddress(address, node) {
-        // determine if this is external
-        const isInternal = this.isInternal(address, node);
-        if (!isInternal) {
-            // external address, so we need to route
-            this.logger.debug('Address is external, routing...', address);
-            // route to leader of external OS
-            return {
-                nextHopAddress: new oNodeAddress(oAddress.leader().toString(), address.libp2pTransports),
-                targetAddress: address,
-            };
-        }
-        return null;
-    }
+    /**
+     * Translates an address to determine the next hop and target addresses.
+     * First checks routing policy for external routing, then applies resolver chain.
+     */
     async translate(address, node) {
-        const externalRoute = this.handleExternalAddress(address, node);
+        // Check if external routing is needed
+        const externalRoute = this.routingPolicy.getExternalRoutingStrategy(address, node);
         if (externalRoute) {
-            this.logger.debug('External route found', externalRoute);
             return externalRoute;
         }
+        // Apply resolver chain for internal routing
         const { nextHopAddress, targetAddress, requestOverride } = await this.addressResolution.resolve({
             address,
             node,
@@ -97,14 +115,11 @@ export class oNodeRouter extends oToolRouter {
             requestOverride,
         };
     }
+    /**
+     * Determines if an address is internal to this node's hierarchy.
+     * Delegates to the routing policy for the decision.
+     */
     isInternal(addressWithTransports, node) {
-        if (addressWithTransports.paths.indexOf(oAddress.leader().paths) !== -1 && // if the address has a leader
-            addressWithTransports.libp2pTransports?.length > 0) {
-            // transports are provided, let's see if they match our known leaders
-            const isLeaderRef = addressWithTransports.toString() === oAddress.leader().toString();
-            const isOurLeaderRef = node.hierarchyManager.leaders.some((l) => l.equals(addressWithTransports));
-            return isLeaderRef || isOurLeaderRef;
-        }
-        return true;
+        return this.routingPolicy.isInternalAddress(addressWithTransports, node);
     }
 }

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

@@ -0,0 +1,30 @@
+import { oAddress, oRoutingPolicy, RouteResponse } from '@olane/o-core';
+import type { oNode } from '../o-node.js';
+/**
+ * Routing policy implementation for oNode that handles internal/external routing decisions
+ * and leader-based routing strategies.
+ */
+export declare class oNodeRoutingPolicy extends oRoutingPolicy {
+    /**
+     * Determines if an address is internal to the current node's hierarchy.
+     * An address is considered internal if:
+     * 1. It doesn't have leader references, OR
+     * 2. Its leader references match our known leaders
+     *
+     * @param address The address to check
+     * @param node The current node context
+     * @returns True if the address is internal to this hierarchy
+     */
+    isInternalAddress(address: oAddress, node: oNode): boolean;
+    /**
+     * Determines the routing strategy for external addresses.
+     * External addresses are routed to the leader of the external OS using
+     * the address's libp2p transports.
+     *
+     * @param address The address to evaluate
+     * @param node The current node context
+     * @returns RouteResponse if external routing is needed, null if internal
+     */
+    getExternalRoutingStrategy(address: oAddress, node: oNode): RouteResponse | null;
+}
+//# sourceMappingURL=o-node.routing-policy.d.ts.map

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

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

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

@@ -0,0 +1,52 @@
+import { oAddress, oRoutingPolicy } from '@olane/o-core';
+import { oNodeAddress } from './o-node.address.js';
+/**
+ * Routing policy implementation for oNode that handles internal/external routing decisions
+ * and leader-based routing strategies.
+ */
+export class oNodeRoutingPolicy extends oRoutingPolicy {
+    /**
+     * Determines if an address is internal to the current node's hierarchy.
+     * An address is considered internal if:
+     * 1. It doesn't have leader references, OR
+     * 2. Its leader references match our known leaders
+     *
+     * @param address The address to check
+     * @param node The current node context
+     * @returns True if the address is internal to this hierarchy
+     */
+    isInternalAddress(address, node) {
+        const nodeAddress = address;
+        if (nodeAddress.paths.indexOf(oAddress.leader().paths) !== -1 && // if the address has a leader
+            nodeAddress.libp2pTransports?.length > 0) {
+            // transports are provided, let's see if they match our known leaders
+            const isLeaderRef = nodeAddress.toString() === oAddress.leader().toString();
+            const isOurLeaderRef = node.hierarchyManager.leaders.some((l) => l.equals(nodeAddress));
+            return isLeaderRef || isOurLeaderRef;
+        }
+        return true;
+    }
+    /**
+     * Determines the routing strategy for external addresses.
+     * External addresses are routed to the leader of the external OS using
+     * the address's libp2p transports.
+     *
+     * @param address The address to evaluate
+     * @param node The current node context
+     * @returns RouteResponse if external routing is needed, null if internal
+     */
+    getExternalRoutingStrategy(address, node) {
+        const nodeAddress = address;
+        const isInternal = this.isInternalAddress(address, node);
+        if (!isInternal) {
+            // external address, so we need to route
+            this.logger.debug('Address is external, routing...', nodeAddress.toString(), nodeAddress.libp2pTransports.map((t) => t.toString()));
+            // route to leader of external OS
+            return {
+                nextHopAddress: new oNodeAddress(oAddress.leader().toString(), nodeAddress.libp2pTransports),
+                targetAddress: nodeAddress,
+            };
+        }
+        return null;
+    }
+}

package/dist/src/router/resolvers/o-node.search-resolver.d.ts

@@ -1,8 +1,170 @@
-import { oAddress, oAddressResolver, oTransport, ResolveRequest, RouteResponse } from '@olane/o-core';
+import { oAddress, oAddressResolver, oCore, oTransport, ResolveRequest, RouteResponse } from '@olane/o-core';
+import { oNodeTransport } from '../o-node.transport.js';
+/**
+ * Address resolver that searches a registry to find transports for addresses.
+ *
+ * This resolver queries a registry service to find the transport information
+ * for addresses that don't already have transports configured. It's designed
+ * to be extensible through subclassing via protected template methods.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const resolver = new oSearchResolver(nodeAddress);
+ * router.addResolver(resolver);
+ * ```
+ *
+ * @example Creating a custom search resolver
+ * ```typescript
+ * class CustomSearchResolver extends oSearchResolver {
+ *   // Search a different registry
+ *   protected getRegistryAddress(): oAddress {
+ *     return new oAddress('o://my-custom-registry');
+ *   }
+ *
+ *   // Use round-robin selection instead of first result
+ *   private currentIndex = 0;
+ *   protected selectResult(results: any[]): any | null {
+ *     if (results.length === 0) return null;
+ *     const result = results[this.currentIndex % results.length];
+ *     this.currentIndex++;
+ *     return result;
+ *   }
+ *
+ *   // Add custom filtering logic
+ *   protected filterSearchResults(results: any[], node: oCore): any[] {
+ *     return super.filterSearchResults(results, node).filter(
+ *       result => result.status === 'active'
+ *     );
+ *   }
+ *
+ *   // Implement custom routing logic with transport setup
+ *   protected determineNextHop(
+ *     node: oCore,
+ *     resolvedTargetAddress: oAddress,
+ *     searchResult: any
+ *   ): oAddress {
+ *     // Always route directly to target, bypassing hierarchy
+ *     const targetTransports = this.mapTransports(searchResult);
+ *     resolvedTargetAddress.setTransports(targetTransports);
+ *     return resolvedTargetAddress;
+ *   }
+ * }
+ * ```
+ *
+ * ## Extension Points
+ *
+ * The following protected methods can be overridden to customize behavior:
+ *
+ * - `getRegistryAddress()` - Change which registry to search
+ * - `getSearchMethod()` - Change the registry method to call
+ * - `buildSearchParams()` - Customize search parameters
+ * - `filterSearchResults()` - Add custom filtering logic
+ * - `selectResult()` - Implement custom result selection (e.g., load balancing)
+ * - `mapTransports()` - Customize how transports are mapped from results
+ * - `determineNextHop()` - Implement custom routing logic to determine the next hop address
+ * - `resolveNextHopTransports()` - Customize transport resolution for the next hop
+ */
 export declare class oSearchResolver extends oAddressResolver {
     protected readonly address: oAddress;
     constructor(address: oAddress);
     get customTransports(): oTransport[];
+    /**
+     * Returns the address of the registry to search.
+     * Override this method to search a different registry.
+     * @returns The registry address to query
+     */
+    protected getRegistryAddress(): oAddress;
+    /**
+     * Returns the method name to call on the registry.
+     * Override this method to use a different search method.
+     * @returns The method name to call
+     */
+    protected getSearchMethod(): string;
+    /**
+     * Builds the search parameters for the registry query.
+     * Override this method to customize search parameters.
+     * @param address - The address being resolved
+     * @returns Parameters to pass to the registry search method
+     */
+    protected buildSearchParams(address: oAddress): any;
+    /**
+     * Filters the search results from the registry.
+     * Override this method to apply custom filtering logic.
+     * @param results - Raw results from the registry
+     * @param node - The current node context
+     * @returns Filtered array of results
+     */
+    protected filterSearchResults(results: any[], node: oCore): any[];
+    /**
+     * Selects which result to use from the filtered results.
+     * Override this method to implement custom selection logic (e.g., load balancing).
+     * @param results - Filtered search results
+     * @returns The selected result, or null if no suitable result
+     */
+    protected selectResult(results: any[]): any | null;
+    /**
+     * Maps the transport data from the search result to oNodeTransport instances.
+     * Override this method to customize transport mapping.
+     * @param result - The selected search result
+     * @returns Array of oNodeTransport instances
+     */
+    protected mapTransports(result: any): oNodeTransport[];
+    /**
+     * Resolves the transports for the next hop address.
+     * This handles the logic of determining which transports to use based on
+     * whether the next hop is the leader, a known child, or a new target.
+     *
+     * Override this method to customize transport resolution logic.
+     *
+     * @param nextHop - The next hop address
+     * @param targetTransports - The transports from the registry search result
+     * @param node - The current node context
+     * @returns Array of transports to use for the next hop
+     */
+    protected resolveNextHopTransports(nextHop: oAddress, targetTransports: oNodeTransport[], node: oCore): oNodeTransport[];
+    /**
+     * Determines the next hop address for routing to the target and sets up its transports.
+     *
+     * This method implements the complete routing logic including:
+     * 1. Determining the next address in the path (using `oAddress.next()`)
+     * 2. Mapping transports from the search result
+     * 3. Resolving and setting transports on the next hop address
+     * 4. Setting transports on the target address
+     *
+     * The default implementation:
+     * - Uses `oAddress.next()` for standard hierarchy-based routing
+     * - Maps transports from the registry search result
+     * - Resolves next hop transports based on leader/hierarchy
+     * - Configures both next hop and target with appropriate transports
+     *
+     * Override this method to implement custom routing logic, such as:
+     * - Direct peer-to-peer routing
+     * - Custom hierarchy traversal
+     * - Alternative transport selection strategies
+     * - Bypass leader for certain routes
+     *
+     * @param node - The current node context
+     * @param resolvedTargetAddress - The resolved target address to route to
+     * @param searchResult - The raw search result from the registry containing transport data
+     * @returns The next hop address with transports configured
+     *
+     * @example Custom direct routing
+     * ```typescript
+     * class DirectSearchResolver extends oSearchResolver {
+     *   protected determineNextHop(
+     *     node: oCore,
+     *     resolvedTargetAddress: oAddress,
+     *     searchResult: any
+     *   ): oAddress {
+     *     // Always route directly to the target, bypassing hierarchy
+     *     const targetTransports = this.mapTransports(searchResult);
+     *     resolvedTargetAddress.setTransports(targetTransports);
+     *     return resolvedTargetAddress;
+     *   }
+     * }
+     * ```
+     */
+    protected determineNextHop(node: oCore, resolvedTargetAddress: oAddress, searchResult: any): oAddress;
     resolve(request: ResolveRequest): Promise<RouteResponse>;
 }
 //# sourceMappingURL=o-node.search-resolver.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"o-node.search-resolver.d.ts","sourceRoot":"","sources":["../../../../src/router/resolvers/o-node.search-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,gBAAgB,EAEhB,UAAU,EACV,cAAc,EAEd,aAAa,EAEd,MAAM,eAAe,CAAC;AAGvB,qBAAa,eAAgB,SAAQ,gBAAgB;IACvC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ;gBAAjB,OAAO,EAAE,QAAQ;IAIhD,IAAI,gBAAgB,IAAI,UAAU,EAAE,CAEnC;IAEK,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAiE/D"}
+{"version":3,"file":"o-node.search-resolver.d.ts","sourceRoot":"","sources":["../../../../src/router/resolvers/o-node.search-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,KAAK,EAEL,UAAU,EACV,cAAc,EAEd,aAAa,EAEd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;IACvC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ;gBAAjB,OAAO,EAAE,QAAQ;IAIhD,IAAI,gBAAgB,IAAI,UAAU,EAAE,CAEnC;IAED;;;;OAIG;IACH,SAAS,CAAC,kBAAkB,IAAI,QAAQ;IAIxC;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,MAAM;IAInC;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,GAAG,GAAG;IAOnD;;;;;;OAMG;IACH,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,GAAG,EAAE;IASjE;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI;IAIlD;;;;;OAKG;IACH,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,GAAG,cAAc,EAAE;IAOtD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,wBAAwB,CAChC,OAAO,EAAE,QAAQ,EACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,IAAI,EAAE,KAAK,GACV,cAAc,EAAE;IAgBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,SAAS,CAAC,gBAAgB,CACxB,IAAI,EAAE,KAAK,EACX,qBAAqB,EAAE,QAAQ,EAC/B,YAAY,EAAE,GAAG,GAChB,QAAQ;IAeL,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CA6D/D"}

package/dist/src/router/resolvers/o-node.search-resolver.js

@@ -1,5 +1,69 @@
 import { oAddress, oAddressResolver, oCustomTransport, RestrictedAddresses, } from '@olane/o-core';
 import { oNodeTransport } from '../o-node.transport.js';
+/**
+ * Address resolver that searches a registry to find transports for addresses.
+ *
+ * This resolver queries a registry service to find the transport information
+ * for addresses that don't already have transports configured. It's designed
+ * to be extensible through subclassing via protected template methods.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const resolver = new oSearchResolver(nodeAddress);
+ * router.addResolver(resolver);
+ * ```
+ *
+ * @example Creating a custom search resolver
+ * ```typescript
+ * class CustomSearchResolver extends oSearchResolver {
+ *   // Search a different registry
+ *   protected getRegistryAddress(): oAddress {
+ *     return new oAddress('o://my-custom-registry');
+ *   }
+ *
+ *   // Use round-robin selection instead of first result
+ *   private currentIndex = 0;
+ *   protected selectResult(results: any[]): any | null {
+ *     if (results.length === 0) return null;
+ *     const result = results[this.currentIndex % results.length];
+ *     this.currentIndex++;
+ *     return result;
+ *   }
+ *
+ *   // Add custom filtering logic
+ *   protected filterSearchResults(results: any[], node: oCore): any[] {
+ *     return super.filterSearchResults(results, node).filter(
+ *       result => result.status === 'active'
+ *     );
+ *   }
+ *
+ *   // Implement custom routing logic with transport setup
+ *   protected determineNextHop(
+ *     node: oCore,
+ *     resolvedTargetAddress: oAddress,
+ *     searchResult: any
+ *   ): oAddress {
+ *     // Always route directly to target, bypassing hierarchy
+ *     const targetTransports = this.mapTransports(searchResult);
+ *     resolvedTargetAddress.setTransports(targetTransports);
+ *     return resolvedTargetAddress;
+ *   }
+ * }
+ * ```
+ *
+ * ## Extension Points
+ *
+ * The following protected methods can be overridden to customize behavior:
+ *
+ * - `getRegistryAddress()` - Change which registry to search
+ * - `getSearchMethod()` - Change the registry method to call
+ * - `buildSearchParams()` - Customize search parameters
+ * - `filterSearchResults()` - Add custom filtering logic
+ * - `selectResult()` - Implement custom result selection (e.g., load balancing)
+ * - `mapTransports()` - Customize how transports are mapped from results
+ * - `determineNextHop()` - Implement custom routing logic to determine the next hop address
+ * - `resolveNextHopTransports()` - Customize transport resolution for the next hop
+ */
 export class oSearchResolver extends oAddressResolver {
     constructor(address) {
         super(address);
@@ -8,8 +72,144 @@ export class oSearchResolver extends oAddressResolver {
     get customTransports() {
         return [new oCustomTransport('/search')];
     }
+    /**
+     * Returns the address of the registry to search.
+     * Override this method to search a different registry.
+     * @returns The registry address to query
+     */
+    getRegistryAddress() {
+        return new oAddress(RestrictedAddresses.REGISTRY);
+    }
+    /**
+     * Returns the method name to call on the registry.
+     * Override this method to use a different search method.
+     * @returns The method name to call
+     */
+    getSearchMethod() {
+        return 'search';
+    }
+    /**
+     * Builds the search parameters for the registry query.
+     * Override this method to customize search parameters.
+     * @param address - The address being resolved
+     * @returns Parameters to pass to the registry search method
+     */
+    buildSearchParams(address) {
+        return {
+            staticAddress: address.toRootAddress().toString(),
+            address: address.toString(),
+        };
+    }
+    /**
+     * Filters the search results from the registry.
+     * Override this method to apply custom filtering logic.
+     * @param results - Raw results from the registry
+     * @param node - The current node context
+     * @returns Filtered array of results
+     */
+    filterSearchResults(results, node) {
+        return results.filter(
+        // filter out the items that may cause infinite looping
+        (result) => result.staticAddress !== RestrictedAddresses.REGISTRY &&
+            result.address !== node.address);
+    }
+    /**
+     * Selects which result to use from the filtered results.
+     * Override this method to implement custom selection logic (e.g., load balancing).
+     * @param results - Filtered search results
+     * @returns The selected result, or null if no suitable result
+     */
+    selectResult(results) {
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Maps the transport data from the search result to oNodeTransport instances.
+     * Override this method to customize transport mapping.
+     * @param result - The selected search result
+     * @returns Array of oNodeTransport instances
+     */
+    mapTransports(result) {
+        return result.transports.map((t) => new oNodeTransport(t.value));
+    }
+    /**
+     * Resolves the transports for the next hop address.
+     * This handles the logic of determining which transports to use based on
+     * whether the next hop is the leader, a known child, or a new target.
+     *
+     * Override this method to customize transport resolution logic.
+     *
+     * @param nextHop - The next hop address
+     * @param targetTransports - The transports from the registry search result
+     * @param node - The current node context
+     * @returns Array of transports to use for the next hop
+     */
+    resolveNextHopTransports(nextHop, targetTransports, node) {
+        // If next hop is the leader, use leader transports
+        if (nextHop.value === RestrictedAddresses.LEADER) {
+            return (node.leader?.transports || []);
+        }
+        // Check if next hop is a known child in the hierarchy
+        const childAddress = node?.hierarchyManager.getChild(nextHop);
+        if (childAddress?.transports) {
+            return childAddress.transports;
+        }
+        // Fall back to target transports from registry
+        return targetTransports;
+    }
+    /**
+     * Determines the next hop address for routing to the target and sets up its transports.
+     *
+     * This method implements the complete routing logic including:
+     * 1. Determining the next address in the path (using `oAddress.next()`)
+     * 2. Mapping transports from the search result
+     * 3. Resolving and setting transports on the next hop address
+     * 4. Setting transports on the target address
+     *
+     * The default implementation:
+     * - Uses `oAddress.next()` for standard hierarchy-based routing
+     * - Maps transports from the registry search result
+     * - Resolves next hop transports based on leader/hierarchy
+     * - Configures both next hop and target with appropriate transports
+     *
+     * Override this method to implement custom routing logic, such as:
+     * - Direct peer-to-peer routing
+     * - Custom hierarchy traversal
+     * - Alternative transport selection strategies
+     * - Bypass leader for certain routes
+     *
+     * @param node - The current node context
+     * @param resolvedTargetAddress - The resolved target address to route to
+     * @param searchResult - The raw search result from the registry containing transport data
+     * @returns The next hop address with transports configured
+     *
+     * @example Custom direct routing
+     * ```typescript
+     * class DirectSearchResolver extends oSearchResolver {
+     *   protected determineNextHop(
+     *     node: oCore,
+     *     resolvedTargetAddress: oAddress,
+     *     searchResult: any
+     *   ): oAddress {
+     *     // Always route directly to the target, bypassing hierarchy
+     *     const targetTransports = this.mapTransports(searchResult);
+     *     resolvedTargetAddress.setTransports(targetTransports);
+     *     return resolvedTargetAddress;
+     *   }
+     * }
+     * ```
+     */
+    determineNextHop(node, resolvedTargetAddress, searchResult) {
+        // Determine next hop using standard hierarchy logic
+        const nextHopAddress = oAddress.next(node.address, resolvedTargetAddress);
+        // Map transports from search result
+        const targetTransports = this.mapTransports(searchResult);
+        // Set transports on the next hop based on routing logic
+        nextHopAddress.setTransports(this.resolveNextHopTransports(nextHopAddress, targetTransports, node));
+        return nextHopAddress;
+    }
     async resolve(request) {
         const { address, node, request: resolveRequest, targetAddress } = request;
+        // Early return: if address already has transports, no search needed
         if (address.transports.length > 0) {
             return {
                 nextHopAddress: address,
@@ -17,43 +217,36 @@ export class oSearchResolver extends oAddressResolver {
                 requestOverride: resolveRequest,
             };
         }
-        // search the leader registry for the address
-        const extraParams = address
-            .toString()
-            .replace(address.toRootAddress().toString(), '');
-        const params = {
-            staticAddress: address.toRootAddress().toString(),
-            address: address.toString(),
-        };
-        const registrySearchResults = await node.use(new oAddress(RestrictedAddresses.REGISTRY), {
-            method: 'search',
-            params: params,
+        // Perform registry search
+        const searchParams = this.buildSearchParams(address);
+        const registryAddress = this.getRegistryAddress();
+        const searchResponse = await node.use(registryAddress, {
+            method: this.getSearchMethod(),
+            params: searchParams,
         });
-        // if there are results, return the first one
-        const registrySearchResultsArray = registrySearchResults.result.data.filter(
-        // filter out the items that may cause infinite looping
-        (result) => result.staticAddress !== RestrictedAddresses.REGISTRY &&
-            result.address !== node.address);
-        if (registrySearchResultsArray.length > 0) {
-            const registrySearchResult = registrySearchResultsArray[0];
-            // we know the final destination, so let's return it + the next hop
-            const targetAddress = new oAddress(registrySearchResult.address + extraParams);
-            const nextHopAddress = oAddress.next(node.address, targetAddress);
-            const targetTransports = registrySearchResult.transports.map((t) => new oNodeTransport(t.value));
-            const childAddress = node?.hierarchyManager.getChild(nextHopAddress);
-            nextHopAddress.setTransports(nextHopAddress.value === RestrictedAddresses.LEADER
-                ? node.leader?.transports
-                : childAddress?.transports || targetTransports);
-            targetAddress.setTransports(targetTransports);
+        // Filter and select result
+        const filteredResults = this.filterSearchResults(searchResponse.result.data, node);
+        const selectedResult = this.selectResult(filteredResults);
+        // Early return: if no result found, return original address
+        if (!selectedResult) {
             return {
-                nextHopAddress: nextHopAddress,
+                nextHopAddress: address,
                 targetAddress: targetAddress,
                 requestOverride: resolveRequest,
             };
         }
+        // Build route from search result
+        const extraParams = address
+            .toString()
+            .replace(address.toRootAddress().toString(), '');
+        const resolvedTargetAddress = new oAddress(selectedResult.address + extraParams);
+        // Set transports on the target address
+        resolvedTargetAddress.setTransports(this.mapTransports(selectedResult));
+        // Determine next hop and configure transports
+        const nextHopAddress = this.determineNextHop(node, resolvedTargetAddress, selectedResult);
         return {
-            nextHopAddress: address,
-            targetAddress: targetAddress,
+            nextHopAddress: nextHopAddress,
+            targetAddress: resolvedTargetAddress,
             requestOverride: resolveRequest,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -56,10 +56,10 @@
     "typescript": "5.4.5"
   },
   "peerDependencies": {
-    "@olane/o-config": "^0.7.5",
-    "@olane/o-core": "^0.7.5",
-    "@olane/o-protocol": "^0.7.5",
-    "@olane/o-tool": "^0.7.5"
+    "@olane/o-config": "^0.7.7",
+    "@olane/o-core": "^0.7.7",
+    "@olane/o-protocol": "^0.7.7",
+    "@olane/o-tool": "^0.7.7"
   },
   "dependencies": {
     "debug": "^4.4.1",