Skip to content

Agent Mesh

sdk/js: the mesh's replication factor from /info is the DHT client's k

Antonio Ojea4f28721e4658
diff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.ts
index 0ddee318..9a3669d0 100644
--- a/sdk/js/src/discovery.ts
+++ b/sdk/js/src/discovery.ts
@@ -22,6 +22,14 @@ import { sha256 } from "multiformats/hashes/sha2";
/** The DHT protocol, go-libp2p-kad-dht with dht.ProtocolPrefix("/mesh"). */
export const DHT_PROTOCOL = "/mesh/kad/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;
+
export type ServiceType = "mcp" | "inference" | "a2a" | "egress";
export function isServiceType(value: unknown): value is ServiceType {
diff --git a/sdk/js/src/host.ts b/sdk/js/src/host.ts
index 3d691eaf..388874e2 100644
--- a/sdk/js/src/host.ts
+++ b/sdk/js/src/host.ts
@@ -28,7 +28,7 @@ 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 { DHT_PROTOCOL } from "./discovery.ts";
+import { DEFAULT_DHT_REPLICATION, DHT_PROTOCOL } from "./discovery.ts";
import type { Identity } from "./identity.ts";
import { connectionEncrypters, transports } from "./platform/transports.ts";
@@ -47,6 +47,14 @@ 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 services a mesh host runs; `services.pubsub` carries the control plane's events. */
@@ -55,6 +63,7 @@ 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 ?? [] },
@@ -89,7 +98,7 @@ export async function createMeshHost(identity: Identity, options: MeshHostOption
// 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 }),
+ 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.
diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.ts
index 9f34ac6f..f1b9bc0e 100644
--- a/sdk/js/src/mesh.ts
+++ b/sdk/js/src/mesh.ts
@@ -15,6 +15,7 @@
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,
@@ -144,6 +145,7 @@ 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
@@ -178,6 +180,16 @@ 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> {
return attenuateCredential(this.#credential, rule);
@@ -407,6 +419,9 @@ 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.ts b/sdk/js/src/session.ts
index 579c403f..91bb2b4b 100644
--- a/sdk/js/src/session.ts
+++ b/sdk/js/src/session.ts
@@ -1360,7 +1360,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom
}
const banned = new BanSet();
- const node = await createMeshHost(mesh.identity, { ...options, banned });
+ const node = await createMeshHost(mesh.identity, { ...options, banned, dhtReplication: mesh.dhtReplication });
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 049e7bc2..63817e06 100644
--- a/sdk/js/src/sync.test.ts
+++ b/sdk/js/src/sync.test.ts
@@ -35,6 +35,7 @@ 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,
@@ -80,6 +81,8 @@ 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];
@@ -115,7 +118,16 @@ class FakeControlPlane {
return proto(toBinary(KeysResponseSchema, create(KeysResponseSchema, { ...unsigned, signatures: this.keys.map((k) => k.identity.sign(payload)) })));
}
if (req.method === "GET" && path === "/info") {
- return proto(toBinary(ControlPlaneInfoResponseSchema, create(ControlPlaneInfoResponseSchema, { routerAddresses: [routerAddr], bannedPeerIds: this.banned })));
+ return proto(
+ toBinary(
+ ControlPlaneInfoResponseSchema,
+ create(ControlPlaneInfoResponseSchema, {
+ routerAddresses: [routerAddr],
+ bannedPeerIds: this.banned,
+ ...(this.replication !== undefined ? { directory: { replication: this.replication } } : {}),
+ }),
+ ),
+ );
}
if (req.method === "POST" && path === "/refresh") {
this.refreshes++;
@@ -212,6 +224,25 @@ 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 });