Skip to content

Agent Mesh

sdk/js: ask the held routers for the directory, floodsub for events

Antonio Ojea3f6417ea75c6
diff --git a/sdk/js/package-lock.json b/sdk/js/package-lock.json
index abfb65f0..519ab307 100644
--- a/sdk/js/package-lock.json
+++ b/sdk/js/package-lock.json
@@ -18,7 +18,6 @@
"@libp2p/gossipsub": "^17.1.2",
"@libp2p/identify": "^4.1.14",
"@libp2p/interface": "^3.3.0",
- "@libp2p/kad-dht": "^16.4.5",
"@libp2p/peer-id": "^6.0.15",
"@libp2p/ping": "^3.1.13",
"@libp2p/tcp": "^11.0.28",
@@ -855,54 +854,6 @@
"uint8arrays": "^6.0.0"
}
},
- "node_modules/@libp2p/kad-dht": {
- "version": "16.4.5",
- "resolved": "https://registry.npmjs.org/@libp2p/kad-dht/-/kad-dht-16.4.5.tgz",
- "integrity": "sha512-Pxmk3pIfe5Ih1xr+CY1uzw8AXRY+2VI6p3iebM4ljueu+dovEPIahW8tq4F2iNHIQftuc9Svncw4JikwrU7I1w==",
- "license": "Apache-2.0 OR MIT",
- "dependencies": {
- "@libp2p/crypto": "^5.1.23",
- "@libp2p/interface": "^3.3.0",
- "@libp2p/interface-internal": "^3.1.13",
- "@libp2p/peer-collections": "^7.0.28",
- "@libp2p/peer-id": "^6.0.15",
- "@libp2p/ping": "^3.1.13",
- "@libp2p/record": "^4.0.15",
- "@libp2p/utils": "^7.4.1",
- "@multiformats/multiaddr": "^13.0.3",
- "@multiformats/multiaddr-matcher": "^3.0.2",
- "any-signal": "^4.1.1",
- "interface-datastore": "^10.0.1",
- "it-all": "^3.0.9",
- "it-drain": "^3.0.10",
- "it-length": "^3.0.9",
- "it-map": "^3.1.4",
- "it-merge": "^3.0.12",
- "it-parallel": "^3.0.13",
- "it-pipe": "^3.0.1",
- "it-pushable": "^3.2.3",
- "it-take": "^3.0.9",
- "main-event": "^1.0.1",
- "multiformats": "^14.0.0",
- "p-defer": "^4.0.1",
- "p-event": "^7.0.0",
- "progress-events": "^1.0.1",
- "protons-runtime": "^7.0.0",
- "race-signal": "^2.0.0",
- "uint8-varint": "^3.0.0",
- "uint8arraylist": "^3.0.2",
- "uint8arrays": "^6.1.1"
- }
- },
- "node_modules/@libp2p/kad-dht/node_modules/uint8arraylist": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/uint8arraylist/-/uint8arraylist-3.0.2.tgz",
- "integrity": "sha512-LDVoq9BQaGJzGDUovEnoX6rpKCvnY/Jbtws4ikwnBzjRbq5qBAFpBZevUEbSmMM87aO0Sp+wOZy2ZXf5yODmXQ==",
- "license": "Apache-2.0 OR MIT",
- "dependencies": {
- "uint8arrays": "^6.0.0"
- }
- },
"node_modules/@libp2p/logger": {
"version": "6.2.13",
"resolved": "https://registry.npmjs.org/@libp2p/logger/-/logger-6.2.13.tgz",
@@ -1042,26 +993,6 @@
"uint8arrays": "^6.0.0"
}
},
- "node_modules/@libp2p/record": {
- "version": "4.0.15",
- "resolved": "https://registry.npmjs.org/@libp2p/record/-/record-4.0.15.tgz",
- "integrity": "sha512-EaHFtQAlZuM9vCpd+0KnZhTVgV26Uzje7DkyUseGNKTy+Wit9Q94C/+wDThpZuRHnK1FH/CvPxJ4kLj7AoQ1WA==",
- "license": "Apache-2.0 OR MIT",
- "dependencies": {
- "protons-runtime": "^7.0.0",
- "uint8arraylist": "^3.0.2",
- "uint8arrays": "^6.1.1"
- }
- },
- "node_modules/@libp2p/record/node_modules/uint8arraylist": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/uint8arraylist/-/uint8arraylist-3.0.2.tgz",
- "integrity": "sha512-LDVoq9BQaGJzGDUovEnoX6rpKCvnY/Jbtws4ikwnBzjRbq5qBAFpBZevUEbSmMM87aO0Sp+wOZy2ZXf5yODmXQ==",
- "license": "Apache-2.0 OR MIT",
- "dependencies": {
- "uint8arrays": "^6.0.0"
- }
- },
"node_modules/@libp2p/tcp": {
"version": "11.0.28",
"resolved": "https://registry.npmjs.org/@libp2p/tcp/-/tcp-11.0.28.tgz",
@@ -2806,12 +2737,6 @@
"it-peekable": "^3.0.0"
}
},
- "node_modules/it-length": {
- "version": "3.0.11",
- "resolved": "https://registry.npmjs.org/it-length/-/it-length-3.0.11.tgz",
- "integrity": "sha512-j0uukHdr3zoLm4dcozDoyv5khQrOI8dfXMSSEqaxorfOtleh1KwRVbdnTmzj6HVkHgTM1jcx+bhAcnTkbpHl+g==",
- "license": "Apache-2.0 OR MIT"
- },
"node_modules/it-length-prefixed": {
"version": "11.0.1",
"resolved": "https://registry.npmjs.org/it-length-prefixed/-/it-length-prefixed-11.0.1.tgz",
diff --git a/sdk/js/package.json b/sdk/js/package.json
index d6b8dfa8..e96b941f 100644
--- a/sdk/js/package.json
+++ b/sdk/js/package.json
@@ -50,7 +50,6 @@
"@libp2p/gossipsub": "^17.1.2",
"@libp2p/identify": "^4.1.14",
"@libp2p/interface": "^3.3.0",
- "@libp2p/kad-dht": "^16.4.5",
"@libp2p/peer-id": "^6.0.15",
"@libp2p/ping": "^3.1.13",
"@libp2p/tcp": "^11.0.28",
diff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.ts
index 9a3669d0..466afec3 100644
--- a/sdk/js/src/discovery.ts
+++ b/sdk/js/src/discovery.ts
@@ -12,23 +12,32 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Service discovery as agentmesh-node does it (internal/node/service.go): a
-// provider record in the mesh DHT under a CID derived from the service key.
+// The mesh's directory as a member uses it, as agentmesh-node does
+// (internal/node/directory_client.go): the member keeps no DHT and asks the
+// routers it holds over /mesh/directory/1.0.0, one DirectoryRequest per
+// stream, one DirectoryResponse back. A request goes to one held router and
+// to the next when it fails. The routers run the lookup across their own
+// DHT. A key is the sha256 multihash of "mesh:service:<type>[:<name>]" for
+// a service and of "mesh:peer:<peer_id>" for a member.
-import { CID } from "multiformats/cid";
-import * as raw from "multiformats/codecs/raw";
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import type { Connection } from "@libp2p/interface";
+import { lpStream } from "@libp2p/utils";
import { sha256 } from "multiformats/hashes/sha2";
+import {
+ DirectoryRequestSchema,
+ DirectoryResponseSchema,
+ type DirectoryRequest,
+ type DirectoryResponse,
+ type PeerRecord,
+} from "./gen/agentmesh_pb.ts";
-/** The DHT protocol, go-libp2p-kad-dht with dht.ProtocolPrefix("/mesh"). */
-export const DHT_PROTOCOL = "/mesh/kad/1.0.0";
+/** api.DirectoryProtocolID. */
+export const DIRECTORY_PROTOCOL = "/mesh/directory/1.0.0";
-/**
- * How many routers hold each record and answer each lookup when the control
- * plane publishes no directory parameters on /info: api.DefaultDHTReplication.
- * A member reads the mesh's value from /info (AgentMesh.dhtReplication) and
- * runs its DHT client on it (createMeshHost), as agentmesh-node does.
- */
-export const DEFAULT_DHT_REPLICATION = 3;
+const REQUEST_TIMEOUT_MS = 10_000;
+const MAX_DIRECTORY_MESSAGE_BYTES = 64 * 1024;
+export const DEFAULT_LIMIT = 20;
export type ServiceType = "mcp" | "inference" | "a2a" | "egress";
@@ -36,14 +45,23 @@ export function isServiceType(value: unknown): value is ServiceType {
return value === "mcp" || value === "inference" || value === "a2a" || value === "egress";
}
-/** The DHT key of a service: by type and name, or by type alone when name is omitted. */
-export async function serviceCID(type: ServiceType, name?: string): Promise<CID> {
- const key = ["mesh:service", type, ...(name !== undefined && name !== "" ? [name] : [])].join(":");
- return CID.createV1(raw.code, await sha256.digest(new TextEncoder().encode(key)));
+/** The sha256 multihash of a name: the two-byte header and the digest. */
+async function directoryKey(name: string): Promise<Uint8Array> {
+ return (await sha256.digest(new TextEncoder().encode(name))).bytes;
+}
+
+/** The directory key of a service type, or of one named service of that type (api.ServiceKey). */
+export async function serviceKey(type: ServiceType, name?: string): Promise<Uint8Array> {
+ return directoryKey(["mesh:service", type, ...(name !== undefined && name !== "" ? [name] : [])].join(":"));
+}
+
+/** The directory key a member announces where it is reached under (api.PeerKey). */
+export async function peerKey(peerId: string): Promise<Uint8Array> {
+ return directoryKey(`mesh:peer:${peerId}`);
}
/** Splits "mcp://calculator" into its type and name; "" is the node's own catalog. */
-export function parseServiceTarget(target: string): { type: ServiceType | "" ; name: string } {
+export function parseServiceTarget(target: string): { type: ServiceType | ""; name: string } {
if (target === "") {
return { type: "", name: "" };
}
@@ -53,3 +71,89 @@ export function parseServiceTarget(target: string): { type: ServiceType | "" ; n
}
return { type: m[1] as ServiceType, name: m[2] as string };
}
+
+/** No held router answered a directory request. */
+export class DirectoryError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "DirectoryError";
+ }
+}
+
+/** A router connection a request goes over. */
+export interface DirectoryRouter {
+ peerId: string;
+ connection(): Connection | undefined;
+}
+
+/** One request to one router, answered or thrown. */
+async function ask(conn: Connection, req: DirectoryRequest, signal: AbortSignal): Promise<DirectoryResponse> {
+ const stream = await conn.newStream(DIRECTORY_PROTOCOL, { signal });
+ try {
+ const lp = lpStream(stream, { maxDataLength: MAX_DIRECTORY_MESSAGE_BYTES });
+ await lp.write(toBinary(DirectoryRequestSchema, req), { signal });
+ const resp = fromBinary(DirectoryResponseSchema, (await lp.read({ signal })).subarray());
+ if (resp.error !== "") {
+ throw new DirectoryError(resp.error);
+ }
+ return resp;
+ } finally {
+ await stream.close().catch(() => stream.abort(new Error("directory stream not closed")));
+ }
+}
+
+/**
+ * Sends req to the held routers in turn until one answers. A router that
+ * is restarting costs the request a timeout, not an answer.
+ */
+export async function request(routers: DirectoryRouter[], req: DirectoryRequest, signal?: AbortSignal): Promise<DirectoryResponse> {
+ let last: unknown;
+ let asked = 0;
+ for (const router of routers) {
+ const conn = router.connection();
+ if (conn === undefined) {
+ continue;
+ }
+ asked++;
+ const bounded = signal === undefined ? AbortSignal.timeout(REQUEST_TIMEOUT_MS) : AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+ try {
+ return await ask(conn, req, bounded);
+ } catch (err) {
+ last = err;
+ if (signal?.aborted === true) {
+ break;
+ }
+ }
+ }
+ if (asked === 0) {
+ throw new DirectoryError("no held router to ask");
+ }
+ throw new DirectoryError(`no held router answered: ${last instanceof Error ? last.message : String(last)}`);
+}
+
+/**
+ * Announces this member as a provider of key, reached at addrs, to a held
+ * router; the router keeps the record and places it on the routers closest
+ * to the key.
+ */
+export async function provide(routers: DirectoryRouter[], key: Uint8Array, addrs: string[], signal?: AbortSignal): Promise<void> {
+ await request(routers, create(DirectoryRequestSchema, { request: { case: "provide", value: { key, addrs } } }), signal);
+}
+
+/** Who provides key, up to limit, with their addresses; empty when nobody does. */
+export async function findProviders(routers: DirectoryRouter[], key: Uint8Array, limit = DEFAULT_LIMIT, signal?: AbortSignal): Promise<PeerRecord[]> {
+ const resp = await request(routers, create(DirectoryRequestSchema, { request: { case: "findProviders", value: { key, limit: Math.max(limit, 1) } } }), signal);
+ return resp.providers.slice(0, limit);
+}
+
+/**
+ * Where a peer is reached: its addresses, each ending in its peer ID,
+ * relayed ones included. Undefined when nobody knows the peer.
+ */
+export async function findPeer(routers: DirectoryRouter[], peerId: string, signal?: AbortSignal): Promise<PeerRecord | undefined> {
+ const resp = await request(routers, create(DirectoryRequestSchema, { request: { case: "findPeer", value: { peerId } } }), signal);
+ if (resp.peer === undefined || resp.peer.peerId !== peerId) {
+ return undefined;
+ }
+ return resp.peer;
+}
diff --git a/sdk/js/src/host.ts b/sdk/js/src/host.ts
index 388874e2..a16a6017 100644
--- a/sdk/js/src/host.ts
+++ b/sdk/js/src/host.ts
@@ -21,14 +21,12 @@
import { yamux } from "@chainsafe/libp2p-yamux";
import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
import { privateKeyFromProtobuf } from "@libp2p/crypto/keys";
-import { gossipsub, type GossipSub } from "@libp2p/gossipsub";
+import { gossipsub, type GossipSub, type GossipSubComponents } from "@libp2p/gossipsub";
import { identify, identifyPush } from "@libp2p/identify";
import type { Libp2p, PeerId } from "@libp2p/interface";
-import { kadDHT, passthroughMapper } from "@libp2p/kad-dht";
import { ping } from "@libp2p/ping";
import type { Multiaddr } from "@multiformats/multiaddr";
import { createLibp2p, type Libp2pOptions } from "libp2p";
-import { DEFAULT_DHT_REPLICATION, DHT_PROTOCOL } from "./discovery.ts";
import type { Identity } from "./identity.ts";
import { connectionEncrypters, transports } from "./platform/transports.ts";
@@ -47,14 +45,27 @@ export interface MeshHostOptions {
banned?: { has(peerId: string): boolean };
/** The resolver for `/dnsaddr` and `/dns*` addresses; the system's by default. */
dns?: Libp2pOptions["dns"];
- /**
- * The mesh's replication factor, from /info (AgentMesh.dhtReplication):
- * kademlia's k on this member. A record lives on that many routers, the
- * closest to its key, and a lookup asks those, that many at a time. The
- * same figure on every member of a mesh, which is why it comes from the
- * control plane; DEFAULT_DHT_REPLICATION when it published none.
- */
- dhtReplication?: number;
+}
+
+/** The floodsub protocol, the one a member speaks (see leafPubsub). */
+const FLOODSUB_PROTOCOL = "/floodsub/1.0.0";
+
+/**
+ * A member is a leaf of the gossip: it speaks floodsub only, so a router
+ * delivers every control plane event to it outright and it takes no part
+ * in the routers' gossipsub mesh, its heartbeats, grafts and peer exchange.
+ * The gossipsub implementation serves as the floodsub one, told to register
+ * that protocol alone; the message envelope is the same.
+ */
+function leafPubsub(): (components: GossipSubComponents) => GossipSub {
+ // StrictSign, as every Go component pins it: the pubsub envelope is
+ // signed by the author, and the event inside by the control plane.
+ const build = gossipsub({ globalSignaturePolicy: "StrictSign", allowPublishToZeroTopicPeers: true, emitSelf: false });
+ return (components) => {
+ const ps = build(components);
+ ps.protocols = [FLOODSUB_PROTOCOL];
+ return ps;
+ };
}
/** The services a mesh host runs; `services.pubsub` carries the control plane's events. */
@@ -63,7 +74,6 @@ export type MeshHost = Libp2p<{ pubsub: GossipSub }>;
export async function createMeshHost(identity: Identity, options: MeshHostOptions = {}): Promise<MeshHost> {
const banned = options.banned ?? { has: () => false };
const denyBanned = (peerId: PeerId) => banned.has(peerId.toString());
- const replication = options.dhtReplication !== undefined && options.dhtReplication >= 1 ? Math.floor(options.dhtReplication) : DEFAULT_DHT_REPLICATION;
return createLibp2p({
privateKey: privateKeyFromProtobuf(identity.toLibp2pPrivateKey()),
addresses: { listen: options.listenAddrs ?? [] },
@@ -95,14 +105,8 @@ export async function createMeshHost(identity: Identity, options: MeshHostOption
// them, where the member is reached now, as agentmesh-node does.
identifyPush: identifyPush(),
ping: ping(),
- // A client of the mesh DHT: it looks providers up and does not hold
- // records. Peers keep their private addresses; a mesh member often
- // is one, and the router relays to it.
- dht: kadDHT({ protocol: DHT_PROTOCOL, clientMode: true, peerInfoMapper: passthroughMapper, initialQuerySelfInterval: 20, kBucketSize: replication, alpha: replication }),
// The control plane's events reach members through the routers.
- // StrictSign, as every Go component pins it: the pubsub envelope is
- // signed by the author, and the event inside by the control plane.
- pubsub: gossipsub({ globalSignaturePolicy: "StrictSign", allowPublishToZeroTopicPeers: true, emitSelf: false }),
+ pubsub: leafPubsub(),
},
});
}
diff --git a/sdk/js/src/index.ts b/sdk/js/src/index.ts
index fe486479..947fd3ba 100644
--- a/sdk/js/src/index.ts
+++ b/sdk/js/src/index.ts
@@ -109,7 +109,7 @@ export {
type GoAwayServerOptions,
} from "./auth.ts";
export { createMeshHost, type MeshHost, type MeshHostOptions } from "./host.ts";
-export { DHT_PROTOCOL, isServiceType, parseServiceTarget, serviceCID, type ServiceType } from "./discovery.ts";
+export { DIRECTORY_PROTOCOL, DirectoryError, isServiceType, parseServiceTarget, peerKey, serviceKey, type ServiceType } from "./discovery.ts";
export { LabelsNotSatisfiedError, StreamTransport, openMCPSession, requireEgressLabels, requireLabels, type MCPSession, type MCPSessionOptions } from "./mcp.ts";
export { AuthorizationError, authorizeCaller, type AuthorizeRequest, type ProviderAuthorizerOptions } from "./authorizer.ts";
export {
diff --git a/sdk/js/src/mcp.test.ts b/sdk/js/src/mcp.test.ts
index 80ef7adc..4dd9afc7 100644
--- a/sdk/js/src/mcp.test.ts
+++ b/sdk/js/src/mcp.test.ts
@@ -33,7 +33,7 @@ import { z } from "zod";
import { AuthRejectedError, MAX_AUTH_FRAME_BYTES, MCP_PROTOCOL } from "./auth.ts";
import { ROLE_ROUTER, loadBiscuit, verifyPeerBiscuit } from "./biscuit.ts";
import { ROLE_NODE } from "./controlplane.ts";
-import { parseServiceTarget, serviceCID } from "./discovery.ts";
+import { parseServiceTarget, serviceKey } from "./discovery.ts";
import { AuthFrameSchema, AuthResponseSchema } from "./gen/agentmesh_pb.ts";
import { Identity } from "./identity.ts";
import { LabelsNotSatisfiedError, StreamTransport, openMCPSession, requireEgressLabels, requireLabels } from "./mcp.ts";
@@ -119,14 +119,12 @@ function frame(target: string, biscuit = callerBiscuit): Uint8Array {
return toBinary(AuthFrameSchema, create(AuthFrameSchema, { biscuit, targetService: target }));
}
-test("service keys match internal/node/service.go", async () => {
+test("service keys match api.ServiceKey", async () => {
const fixture = JSON.parse(readFileSync(new URL("../../testdata/service_keys.json", import.meta.url), "utf8")) as {
services: Array<{ type: "mcp" | "inference" | "a2a"; name: string; cid: string; multihash: string }>;
};
for (const s of fixture.services) {
- const cid = await serviceCID(s.type, s.name);
- assert.equal(cid.toString(), s.cid, `${s.type}:${s.name}`);
- assert.equal(Buffer.from(cid.multihash.bytes).toString("hex"), s.multihash);
+ assert.equal(Buffer.from(await serviceKey(s.type, s.name)).toString("hex"), s.multihash, `${s.type}:${s.name}`);
}
assert.deepEqual(parseServiceTarget("mcp://calc"), { type: "mcp", name: "calc" });
assert.deepEqual(parseServiceTarget("egress://api.github.com"), { type: "egress", name: "api.github.com" });
diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.ts
index f1b9bc0e..606ccc21 100644
--- a/sdk/js/src/mesh.ts
+++ b/sdk/js/src/mesh.ts
@@ -15,7 +15,6 @@
import type { MessageInitShape } from "@bufbuild/protobuf";
import { toHex } from "./bytes.ts";
import { ControlPlaneClient, KeysNotTrustedError, ROLE_NODE, type Enrollment } from "./controlplane.ts";
-import { DEFAULT_DHT_REPLICATION } from "./discovery.ts";
import {
attenuateCredential,
credentialFromJSON,
@@ -145,7 +144,6 @@ export class AgentMesh {
readonly controlPlane: ControlPlaneClient;
#credential: MeshCredential;
#routers: RouterInfo[] = [];
- #dhtReplication = DEFAULT_DHT_REPLICATION;
readonly #state: StateStore | undefined;
readonly #jwtSource: (() => Promise<string>) | undefined;
// Refreshes run one after another, as agentmesh-node's refreshMu: the control
@@ -180,15 +178,6 @@ export class AgentMesh {
return this.#routers;
}
- /**
- * How many routers hold each record and answer each lookup on this mesh,
- * as /info last published it (ControlPlaneInfoResponse.directory);
- * DEFAULT_DHT_REPLICATION until the control plane has answered or when it
- * publishes none.
- */
- get dhtReplication(): number {
- return this.#dhtReplication;
- }
/** Returns a new MeshCredential with a tar_block appended offline in memory. */
attenuate(rule: MessageInitShape<typeof TaskAuthorizationRuleSchema>): Promise<MeshCredential> {
@@ -419,9 +408,6 @@ export class AgentMesh {
const info = await this.controlPlane.info();
routers = info.routers;
this.#routers = info.routers;
- if (info.directory !== undefined && info.directory.replication >= 1) {
- this.#dhtReplication = info.directory.replication;
- }
const discovered =
info.routerAddresses.length > 0
? info.routerAddresses
diff --git a/sdk/js/src/session.test.ts b/sdk/js/src/session.test.ts
index 227d9314..54344127 100644
--- a/sdk/js/src/session.test.ts
+++ b/sdk/js/src/session.test.ts
@@ -28,6 +28,7 @@ import type { Libp2p } from "@libp2p/interface";
import { tcp } from "@libp2p/tcp";
import { tls } from "@libp2p/tls";
import { lpStream } from "@libp2p/utils";
+import { DIRECTORY_PROTOCOL } from "./discovery.ts";
import { multiaddr } from "@multiformats/multiaddr";
import { createLibp2p } from "libp2p";
import assert from "node:assert/strict";
@@ -38,7 +39,7 @@ import { after, before, test } from "node:test";
import { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, AuthRejectedError, GOAWAY_MAX_RETRY_AFTER_MS, GOAWAY_PROTOCOL, ROUTER_SHUN_DURATION_MS, authenticateWithPeer, authStreamHandler, clampGoAwayRetryAfterMs } from "./auth.ts";
import { BiscuitVerificationError, ROLE_ROUTER, loadBiscuit, verifyPeerBiscuit } from "./biscuit.ts";
import { ROLE_NODE } from "./controlplane.ts";
-import { BootstrapEnrollRequestSchema, BootstrapEnrollResponseSchema, ControlPlaneInfoResponseSchema, EnrollmentStatus, KeysResponseSchema, AuthFrameSchema, RouterGoAwaySchema, RouterGoAway_Reason, RouterInfoSchema, TokenRefreshRequestSchema, TokenRefreshResponseSchema, type RouterInfo } from "./gen/agentmesh_pb.ts";
+import { BootstrapEnrollRequestSchema, BootstrapEnrollResponseSchema, ControlPlaneInfoResponseSchema, EnrollmentStatus, KeysResponseSchema, AuthFrameSchema, DirectoryRequestSchema, DirectoryResponseSchema, PeerRecordSchema, RouterGoAwaySchema, RouterGoAway_Reason, RouterInfoSchema, TokenRefreshRequestSchema, TokenRefreshResponseSchema, type RouterInfo } from "./gen/agentmesh_pb.ts";
import { Identity } from "./identity.ts";
import { HTTP_HANDLER_OPTIONS, HTTP_PROTOCOL, a2aEndpoint, httpIngressHandler } from "./libp2p-http.ts";
import { LabelsNotSatisfiedError } from "./mcp.ts";
@@ -405,13 +406,11 @@ test("a member on one router reaches a member on another", async () => {
}
});
-test("a connection to a listed router is authenticated, and released after a lookup", async () => {
- // The DHT client connects to whichever listed router kademlia puts closest
- // to a key. A router serves its DHT only to a member that authenticated
- // on the connection, so the handshake runs on connection:open for any
- // listed router, held or not; a router met this way is not held, and the
- // connection is closed once the lookup ends.
- const routerB = await createLibp2p({
+test("discovery asks a held router over the directory protocol and connects to no other", async () => {
+ // A member keeps no DHT: a lookup is one request to a router it holds,
+ // which answers from the routers' directory. A second listed router is
+ // never connected to for it.
+ const otherRouter = await createLibp2p({
addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
transports: [tcp()],
connectionEncrypters: [tls()],
@@ -419,31 +418,39 @@ test("a connection to a listed router is authenticated, and released after a loo
services: { identify: identify(), relay: circuitRelayServer() },
});
try {
- const handshakesB: string[] = [];
- await routerB.handle(AUTH_PROTOCOL, authStreamHandler({ ownBiscuit: () => mint(routerB.peerId.toString(), ROLE_ROUTER), trustedKeys: () => [cpKey], onAuthenticated: (p) => handshakesB.push(p) }));
- const routerBAddr = (routerB.getMultiaddrs()[0] as ReturnType<typeof multiaddr>).toString();
- const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([routerAddr, routerBAddr]) });
+ const otherAddr = (otherRouter.getMultiaddrs()[0] as ReturnType<typeof multiaddr>).toString();
+ const provider = "12D3KooWA4Xop1JaT3MHxwYMkCepYsv4iPVopMXwCz5iHYdBfeSB";
+ const asked: string[] = [];
+ await router.handle(DIRECTORY_PROTOCOL, (stream) => {
+ void (async () => {
+ const lp = lpStream(stream, { maxDataLength: 64 * 1024 });
+ const req = fromBinary(DirectoryRequestSchema, (await lp.read()).subarray());
+ asked.push(req.request.case ?? "");
+ const resp = create(DirectoryResponseSchema, {});
+ if (req.request.case === "findProviders") {
+ resp.providers = [create(PeerRecordSchema, { peerId: provider, addrs: [`${routerAddr}/p2p-circuit/p2p/${provider}`] })];
+ } else if (req.request.case === "findPeer" && req.request.value.peerId === provider) {
+ resp.peer = create(PeerRecordSchema, { peerId: provider, addrs: [`${routerAddr}/p2p-circuit/p2p/${provider}`] });
+ }
+ await lp.write(toBinary(DirectoryResponseSchema, resp));
+ await stream.close();
+ })();
+ });
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([routerAddr, otherAddr]) });
const session = await mesh.join({ refreshLeadMs: 0, routerAddresses: [routerAddr], reserveRelay: false });
try {
- assert.deepEqual(session.routers.map((r) => r.peerId), [router.peerId.toString()]);
-
- await session.node.dial(multiaddr(routerBAddr));
- const deadline = Date.now() + 10_000;
- while (handshakesB.length === 0 && Date.now() < deadline) {
- await new Promise((r) => setTimeout(r, 20));
- }
- assert.deepEqual(handshakesB, [mesh.peerId], "the member authenticated on connecting to a listed router");
- assert.deepEqual(session.routers.map((r) => r.peerId), [router.peerId.toString()], "a router met for a lookup is not held");
-
- await session.discover("mcp", undefined, { timeoutMs: 500 }).catch(() => {});
+ const found = await session.discover("mcp", undefined, { timeoutMs: 5_000 });
+ assert.deepEqual(found, [{ peerId: provider, addrs: [`${routerAddr}/p2p-circuit/p2p/${provider}`] }]);
+ assert.deepEqual(session.dialTargets(provider).addrs.map(String), [`${routerAddr}/p2p-circuit/p2p/${provider}`], "the provider is reached through the held router");
+ assert.deepEqual(asked, ["findProviders"]);
const connected = session.node.getConnections().map((c) => c.remotePeer.toString());
- assert.ok(!connected.includes(routerB.peerId.toString()), "the lookup's connection to the router it does not hold is released");
- assert.ok(connected.includes(router.peerId.toString()), "the held router's connection stays");
+ assert.ok(!connected.includes(otherRouter.peerId.toString()), "the member connected to a router it does not hold");
} finally {
await session.close();
+ await router.unhandle(DIRECTORY_PROTOCOL);
}
} finally {
- await routerB.stop();
+ await otherRouter.stop();
}
});
diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.ts
index 63fc5852..3d426f63 100644
--- a/sdk/js/src/session.ts
+++ b/sdk/js/src/session.ts
@@ -32,8 +32,8 @@ import { ROLE_ROUTER, attenuateBiscuit, requireRole, sealBiscuit, type VerifiedB
import { ROLE_NODE } from "./controlplane.ts";
import { encodeAuthFrame } from "./credential.ts";
import { canonicalPeerId } from "./identity.ts";
-import { isServiceType, parseServiceTarget, serviceCID } from "./discovery.ts";
-import type { RouterGoAway, RouterInfo, TaskAuthorizationRuleSchema } from "./gen/agentmesh_pb.ts";
+import { findPeer, findProviders, isServiceType, parseServiceTarget, serviceKey, type DirectoryRouter } from "./discovery.ts";
+import type { PeerRecord, RouterGoAway, RouterInfo, TaskAuthorizationRuleSchema } from "./gen/agentmesh_pb.ts";
import { createMeshHost, listenThroughRelay, type MeshHost, type MeshHostOptions, type RelayListener } from "./host.ts";
import { openMCPSession, requireEgressLabels, type MCPSession, type MCPSessionOptions } from "./mcp.ts";
import type { AgentMesh, ControlPlaneSync } from "./mesh.ts";
@@ -499,16 +499,12 @@ export class MeshSession {
* A router forgets the admission with the connection it came on, and
* js-libp2p reconnects to a relay on its own, so every new connection to a
* router runs the handshake again: the relay's own renewal of the
- * reservation then still passes the router's check. A router serves its
- * DHT and gossip only to a member that authenticated on the connection,
- * so a connection the DHT client opens to any router the control plane
- * lists is authenticated the same way; the router holds the streams the
- * client opened meanwhile and serves them once the handshake is done.
+ * reservation then still passes the router's check.
*/
#keepRouterAdmissions(): void {
this.node.addEventListener("connection:open", (evt) => {
const conn = evt.detail;
- if (this.#closed || !this.#isRouter(conn.remotePeer.toString())) {
+ if (this.#closed || !this.routers.some((r) => r.peerId === conn.remotePeer.toString())) {
return;
}
void this.#authenticateRouter(conn).catch(() => {});
@@ -535,26 +531,12 @@ export class MeshSession {
return run;
}
- /** Whether peerId is a router this member holds or one the mesh lists for it. */
- #isRouter(peerId: string): boolean {
- return (
- this.routers.some((r) => r.peerId === peerId) ||
- candidatesFromRouterInfos(this.mesh.routers, this.mesh.credential.routerAddresses).some((c) => c.peerId === peerId)
- );
- }
-
- /**
- * Closes the connections a lookup opened to routers this member does not
- * hold: the member keeps sessions with the routers it holds and with no
- * other, and the next lookup connects and authenticates again.
- */
- async #releaseLookupRouters(): Promise<void> {
- for (const conn of this.node.getConnections()) {
- const peerId = conn.remotePeer.toString();
- if (this.#isRouter(peerId) && !this.routers.some((r) => r.peerId === peerId)) {
- await this.node.hangUp(conn.remotePeer).catch(() => {});
- }
- }
+ /** The held routers as the directory client asks them, each with its open connection. */
+ #directoryRouters(): DirectoryRouter[] {
+ return this.routers.map((r) => ({
+ peerId: r.peerId,
+ connection: () => this.node.getConnections(peerIdFromString(r.peerId)).find((c) => c.status === "open"),
+ }));
}
/**
@@ -758,24 +740,25 @@ export class MeshSession {
}
/**
- * The addresses the routers' DHT knows for a peer, its relayed ones
- * through routers this member has admitted by then: a relay opens a
- * circuit only for a source it authenticated, so a router met this way is
- * dialed and passed the handshake first, and joins the admitted set.
+ * The addresses the directory knows for a peer, its relayed ones through
+ * routers this member has admitted by then: a relay opens a circuit only
+ * for a source it authenticated, so a router met this way is dialed and
+ * passed the handshake first, and joins the admitted set.
*/
async #routedAddresses(peerId: string, signal?: AbortSignal): Promise<Multiaddr[]> {
const lookup = signal ?? AbortSignal.timeout(PEER_ROUTING_TIMEOUT_MS);
- let found: { multiaddrs: Multiaddr[] };
+ let found: PeerRecord | undefined;
try {
- found = await this.node.peerRouting.findPeer(peerIdFromString(peerId), { signal: lookup });
+ found = await findPeer(this.#directoryRouters(), peerId, lookup);
} catch {
return [];
- } finally {
- await this.#releaseLookupRouters();
+ }
+ if (found === undefined) {
+ return [];
}
const out: Multiaddr[] = [];
- for (const ma of found.multiaddrs) {
- const text = ma.toString();
+ for (const text of found.addrs) {
+ const ma = multiaddr(text);
const circuit = text.indexOf("/p2p-circuit");
if (circuit === -1) {
out.push(targetPeerOf(ma) === undefined ? ma.encapsulate(`/p2p/${peerId}`) : ma);
@@ -841,53 +824,33 @@ export class MeshSession {
}
/**
- * Looks the DHT up for peers offering a service: `"mcp://calc"`, the
+ * Asks the directory for peers offering a service: `"mcp://calc"`, the
* same string callTool and request take, or a type alone (`"mcp"`) for
- * every service of that type, or (type, name). Bounded by the timeout;
- * the DHT walk itself is what agentmesh-node's discover does.
+ * every service of that type, or (type, name). A router this member holds
+ * answers; bounded by the timeout.
*/
async discover(service: string, name?: string, options: { timeoutMs?: number; limit?: number } = {}): Promise<DiscoveredProvider[]> {
const target = service.includes("://") ? parseServiceTarget(service) : { type: service, name };
if (!isServiceType(target.type)) {
throw new Error(`service type must be mcp, inference, a2a or egress, got ${JSON.stringify(target.type)}`);
}
- const cid = await serviceCID(target.type, target.name);
- const ac = new AbortController();
- const signal = AbortSignal.any([ac.signal, AbortSignal.timeout(options.timeoutMs ?? DISCOVERY_TIMEOUT_MS)]);
- let settleTimer: ReturnType<typeof setTimeout> | undefined;
+ const key = await serviceKey(target.type, target.name);
+ const signal = AbortSignal.timeout(options.timeoutMs ?? DISCOVERY_TIMEOUT_MS);
+ const limit = options.limit ?? 20;
const found = new Map<string, DiscoveredProvider>();
- try {
- for await (const provider of this.node.contentRouting.findProviders(cid, { signal })) {
- const peerId = provider.id.toString();
- if (peerId === this.peerId) {
- continue;
- }
- const entry = found.get(peerId) ?? { peerId, addrs: [] };
- for (const ma of provider.multiaddrs) {
- const text = ma.toString();
- if (!entry.addrs.includes(text)) {
- entry.addrs.push(text);
- }
- }
- found.set(peerId, entry);
- if (found.size >= (options.limit ?? 20)) {
- break;
- }
- if (settleTimer === undefined) {
- settleTimer = setTimeout(() => ac.abort(), 200);
- settleTimer.unref?.();
- }
+ for (const record of await findProviders(this.#directoryRouters(), key, limit, signal)) {
+ if (record.peerId === this.peerId) {
+ continue;
}
- } catch (err) {
- // The lookup ended on its deadline; what was found so far is the answer.
- if (!(err instanceof Error && err.name === "TimeoutError") && !signal.aborted) {
- throw err;
+ const entry = found.get(record.peerId) ?? { peerId: record.peerId, addrs: [] };
+ for (const text of record.addrs) {
+ if (!entry.addrs.includes(text)) {
+ entry.addrs.push(text);
+ }
}
- } finally {
- clearTimeout(settleTimer);
- await this.#releaseLookupRouters();
+ found.set(record.peerId, entry);
}
- return [...found.values()];
+ return [...found.values()].slice(0, limit);
}
/**
@@ -1409,7 +1372,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom
}
const banned = new BanSet();
- const node = await createMeshHost(mesh.identity, { ...options, banned, dhtReplication: mesh.dhtReplication });
+ const node = await createMeshHost(mesh.identity, { ...options, banned });
const authenticatedPeers = new Map<string, Date>();
let session: MeshSession | undefined;
try {
diff --git a/sdk/js/src/sync.test.ts b/sdk/js/src/sync.test.ts
index 63817e06..d9f24081 100644
--- a/sdk/js/src/sync.test.ts
+++ b/sdk/js/src/sync.test.ts
@@ -35,7 +35,6 @@ import { AUTH_PROTOCOL, authenticateWithPeer, authStreamHandler } from "./auth.t
import { ROLE_ROUTER, loadBiscuit, verifyPeerBiscuit } from "./biscuit.ts";
import { ROLE_NODE } from "./controlplane.ts";
import { credentialPredatesRotation } from "./credential.ts";
-import { DEFAULT_DHT_REPLICATION } from "./discovery.ts";
import {
AuthFrameSchema,
BootstrapEnrollRequestSchema,
@@ -81,8 +80,6 @@ class SigningKey {
class FakeControlPlane {
keys: SigningKey[];
banned: string[] = [];
- /** The replication /info publishes; undefined is a control plane that predates the field. */
- replication: number | undefined;
refreshes = 0;
constructor(initial: SigningKey) {
this.keys = [initial];
@@ -124,7 +121,6 @@ class FakeControlPlane {
create(ControlPlaneInfoResponseSchema, {
routerAddresses: [routerAddr],
bannedPeerIds: this.banned,
- ...(this.replication !== undefined ? { directory: { replication: this.replication } } : {}),
}),
),
);
@@ -224,25 +220,6 @@ test("a mesh event verifies only under a trusted key and only when fresh", () =>
assert.equal(verifyMeshEvent(bannedNobody, [key.pub], now), undefined, "not a peer id");
});
-test("a pull takes the mesh's replication from /info, and the default when it publishes none", async () => {
- const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
- assert.equal(mesh.dhtReplication, DEFAULT_DHT_REPLICATION, "before any pull");
- cp.replication = 5;
- try {
- await mesh.syncControlPlane();
- assert.equal(mesh.dhtReplication, 5);
- // A control plane that stops publishing it, or publishes nothing usable, leaves the last value.
- cp.replication = 0;
- await mesh.syncControlPlane();
- assert.equal(mesh.dhtReplication, 5);
- cp.replication = undefined;
- await mesh.syncControlPlane();
- assert.equal(mesh.dhtReplication, 5);
- } finally {
- cp.replication = undefined;
- }
-});
-
test("a pull learns a key rotation and refreshes the credential under the new key", async () => {
const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
const session = await mesh.join({ refreshLeadMs: 0, controlPlaneSyncIntervalMs: 0 });