Skip to content

Agent Mesh

sdk/js: cancel an abandoned join's work instead of waiting past it

Saurave920f31d8917
diff --git a/sdk/js/README.md b/sdk/js/README.md
index db2bc683..1e067d4f 100644
--- a/sdk/js/README.md
+++ b/sdk/js/README.md
@@ -61,21 +61,15 @@ if (argv[0] !== undefined && !argv[0].includes("://")) {
}
const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/caller`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
console.log(`on the mesh as ${session.peerId}`);
// The peer to call: an agent named by ID, or a provider of a published service.
@@ -83,13 +77,9 @@ let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
if (peerId !== undefined) {
// An agent is not in the discovery table; the SDK finds the path to its
// peer ID through the routers.
- console.error(`dialing ${peerId}`);
await session.connect(peerId);
} else {
const providers = await session.discover(service);
- for (const p of providers) {
- console.error(`provider ${p.peerId}`);
- }
if (providers.length === 0) {
throw new Error(`no member of the mesh serves ${service}`);
}
@@ -97,7 +87,6 @@ if (peerId !== undefined) {
let reached = false;
for (const candidate of providers) {
try {
- console.error(`dialing ${candidate.peerId}`);
await session.connect(candidate);
provider = candidate;
reached = true;
diff --git a/sdk/js/examples/a2a-agent.ts b/sdk/js/examples/a2a-agent.ts
index c3c87280..3d2f17f1 100644
--- a/sdk/js/examples/a2a-agent.ts
+++ b/sdk/js/examples/a2a-agent.ts
@@ -20,21 +20,15 @@ import { AgentEvent, DefaultRequestHandler, InMemoryTaskStore, type AgentExecuto
import { UserBuilder, agentCardHandler, jsonRpcHandler } from "@a2a-js/sdk/server/express";
import { AgentMesh, MeshSession } from "@agentmesh-p2p/sdk";
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/a2a-agent`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
// The card names the agent as the mesh reaches it: the URL an A2A client on
// the mesh gives its fetch, http://mesh/mesh/<peer-id>/a2a/agent.
diff --git a/sdk/js/examples/a2a-call.ts b/sdk/js/examples/a2a-call.ts
index f66eeb88..8890f6f1 100644
--- a/sdk/js/examples/a2a-call.ts
+++ b/sdk/js/examples/a2a-call.ts
@@ -21,21 +21,15 @@ if (peerId === undefined) {
throw new Error("usage: a2a-call.js <peer-id> [text]");
}
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/a2a-caller`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
console.log(`on the mesh as ${session.peerId}`);
// The agent's URL on the mesh, and a fetch that carries requests to it.
@@ -46,7 +40,6 @@ const factory = new ClientFactory({
cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
});
// The card lives under the agent's URL; the trailing slash keeps the last segment when the resolver appends the well-known path.
-console.error(`dialing ${peerId}`);
const client = await factory.createFromUrl(agentURL + "/");
const card = await client.getAgentCard();
console.log(`agent: ${card.name}, ${card.description}`);
diff --git a/sdk/js/examples/call.ts b/sdk/js/examples/call.ts
index 6a88ce77..324667cd 100644
--- a/sdk/js/examples/call.ts
+++ b/sdk/js/examples/call.ts
@@ -22,21 +22,15 @@ if (argv[0] !== undefined && !argv[0].includes("://")) {
}
const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/caller`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
console.log(`on the mesh as ${session.peerId}`);
// The peer to call: an agent named by ID, or a provider of a published service.
@@ -44,13 +38,9 @@ let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
if (peerId !== undefined) {
// An agent is not in the discovery table; the SDK finds the path to its
// peer ID through the routers.
- console.error(`dialing ${peerId}`);
await session.connect(peerId);
} else {
const providers = await session.discover(service);
- for (const p of providers) {
- console.error(`provider ${p.peerId}`);
- }
if (providers.length === 0) {
throw new Error(`no member of the mesh serves ${service}`);
}
@@ -58,7 +48,6 @@ if (peerId !== undefined) {
let reached = false;
for (const candidate of providers) {
try {
- console.error(`dialing ${candidate.peerId}`);
await session.connect(candidate);
provider = candidate;
reached = true;
diff --git a/sdk/js/src/auth.ts b/sdk/js/src/auth.ts
index 835deb09..15aea2c6 100644
--- a/sdk/js/src/auth.ts
+++ b/sdk/js/src/auth.ts
@@ -60,9 +60,10 @@ function framed(stream: Stream) {
/**
* Client side: presents frame on a new /mesh/auth/1.0.0 stream and returns
* the peer's verified credential. trustedKeys are the control plane keys.
+ * The handshake has a timeout of its own; outer, when given, can end it sooner.
*/
-export async function authenticateWithPeer(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[]): Promise<VerifiedBiscuit> {
- const signal = AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS);
+export async function authenticateWithPeer(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[], outer?: AbortSignal): Promise<VerifiedBiscuit> {
+ const signal = outer === undefined ? AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS) : AbortSignal.any([outer, AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS)]);
// A peer behind a router is reached over a relayed, limited connection.
const stream = await conn.newStream(AUTH_PROTOCOL, { signal, runOnLimitedConnection: true });
try {
diff --git a/sdk/js/src/controlplane.ts b/sdk/js/src/controlplane.ts
index 636ed346..fd52126f 100644
--- a/sdk/js/src/controlplane.ts
+++ b/sdk/js/src/controlplane.ts
@@ -257,8 +257,8 @@ export class ControlPlaneClient {
}
/** GET /info: OIDC settings, router addresses and the ban list. Unauthenticated. */
- async info(): Promise<ControlPlaneInfoResponse> {
- const body = await this.#request("GET", "/info");
+ async info(signal?: AbortSignal): Promise<ControlPlaneInfoResponse> {
+ const body = await this.#request("GET", "/info", undefined, {}, signal);
return fromBinary(ControlPlaneInfoResponseSchema, body);
}
@@ -266,8 +266,8 @@ export class ControlPlaneClient {
* GET /keys: every signing key the control plane currently trusts,
* verified against a key the caller already trusts (the enrollment key).
*/
- async keys(trusted: Uint8Array[]): Promise<Uint8Array[]> {
- const body = await this.#request("GET", "/keys");
+ async keys(trusted: Uint8Array[], signal?: AbortSignal): Promise<Uint8Array[]> {
+ const body = await this.#request("GET", "/keys", undefined, {}, signal);
return verifyKeysResponse(fromBinary(KeysResponseSchema, body), trusted, this.#now());
}
@@ -426,14 +426,15 @@ export class ControlPlaneClient {
path: string,
body?: Uint8Array,
headers: Record<string, string> = {},
+ signal?: AbortSignal,
): Promise<{ ok: boolean; status: number; buf: Uint8Array; dateHeader: string | null }> {
- const controller = new AbortController();
- const timer = setTimeout(() => controller.abort(new Error(`control plane ${path}: timed out after ${this.#timeoutMs}ms`)), this.#timeoutMs);
+ // The caller's signal cancels the request itself, not only the wait for it.
+ const timeout = AbortSignal.timeout(this.#timeoutMs);
try {
const init: RequestInit = {
method,
headers: { Accept: PROTOBUF_CONTENT_TYPE, ...headers },
- signal: controller.signal,
+ signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
};
if (body !== undefined) {
init.body = new Uint8Array(body);
@@ -445,13 +446,22 @@ export class ControlPlaneClient {
throw new Error(`control plane ${path}: response of ${buf.length} bytes exceeds the ${MAX_RESPONSE_BYTES} byte limit`);
}
return { ok: resp.ok, status: resp.status, buf, dateHeader: resp.headers.get("date") };
- } finally {
- clearTimeout(timer);
+ } catch (err) {
+ if (timeout.aborted && signal?.aborted !== true) {
+ throw new Error(`control plane ${path}: timed out after ${this.#timeoutMs}ms`);
+ }
+ throw err;
}
}
- async #request(method: "GET" | "POST", path: string, body?: Uint8Array, headers: Record<string, string> = {}): Promise<Uint8Array> {
- const outcome = await this.#fetchOnce(method, path, body, headers);
+ async #request(
+ method: "GET" | "POST",
+ path: string,
+ body?: Uint8Array,
+ headers: Record<string, string> = {},
+ signal?: AbortSignal,
+ ): Promise<Uint8Array> {
+ const outcome = await this.#fetchOnce(method, path, body, headers, signal);
if (!outcome.ok) {
throw new ControlPlaneError(path, outcome.status, new TextDecoder().decode(outcome.buf));
}
diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.ts
index 606ccc21..7567bd00 100644
--- a/sdk/js/src/mesh.ts
+++ b/sdk/js/src/mesh.ts
@@ -310,12 +310,13 @@ export class AgentMesh {
* Trades the current biscuit for a fresh one and persists it. The control
* plane redeems only the last biscuit it issued, so a lost refresh result
* means re-enrolling; persisting before returning keeps that rare.
- * Concurrent calls wait for each other.
+ * Concurrent calls wait for each other. A refresh whose signal has
+ * aborted by the time its turn comes does not start.
*/
- async refresh(): Promise<MeshCredential> {
+ async refresh(signal?: AbortSignal): Promise<MeshCredential> {
const run = this.#refreshChain.then(
- () => this.#refreshOnce(),
- () => this.#refreshOnce(),
+ () => this.#refreshOnce(signal),
+ () => this.#refreshOnce(signal),
);
this.#refreshChain = run.then(
() => undefined,
@@ -324,7 +325,8 @@ export class AgentMesh {
return run;
}
- async #refreshOnce(): Promise<MeshCredential> {
+ async #refreshOnce(signal?: AbortSignal): Promise<MeshCredential> {
+ signal?.throwIfAborted();
let jwt: string | undefined;
if (this.#jwtSource !== undefined) {
try {
@@ -336,6 +338,10 @@ export class AgentMesh {
// Best effort: fall back to session-only refresh if the token source is temporarily unavailable.
}
}
+ // The last point to stop. The /refresh request itself is not cut short:
+ // the control plane spends the old biscuit when it answers, so only a
+ // refresh that runs to the end can save the new one.
+ signal?.throwIfAborted();
const result = await this.controlPlane.refresh({
identity: this.identity,
biscuit: this.#credential.biscuit,
@@ -379,25 +385,29 @@ export class AgentMesh {
* addresses and the ban set. Each part is attempted even when another
* fails; the errors are reported together. Gossip events only bring this
* forward; they are never the only way state arrives.
+ *
+ * An aborted signal cancels the request in flight and throws its reason:
+ * nothing more is sent and nothing is written to the state directory.
*/
- async syncControlPlane(): Promise<ControlPlaneSync> {
+ async syncControlPlane(signal?: AbortSignal): Promise<ControlPlaneSync> {
const errors: string[] = [];
let keysChanged = false;
let refreshed = false;
try {
- const keys = await this.controlPlane.keys(this.#credential.controlPlaneKeys);
+ const keys = await this.controlPlane.keys(this.#credential.controlPlaneKeys, signal);
if (keys.length === 0) {
throw new Error("/keys returned no keys");
}
keysChanged = !sameKeySet(keys, this.#credential.controlPlaneKeys);
this.#credential = withCredentialMethods({ ...this.#credential, controlPlaneKeys: keys });
if (credentialPredatesRotation(this.#credential)) {
- await this.refresh();
+ await this.refresh(signal);
refreshed = true;
}
} catch (err) {
errors.push(`keys: ${err instanceof Error ? err.message : String(err)}`);
}
+ signal?.throwIfAborted();
let bannedPeerIds: string[] | undefined;
let routers: RouterInfo[] | undefined;
@@ -405,7 +415,7 @@ export class AgentMesh {
// in the answer, so its absence must not be read as an unban.
const fetchedAt = new Date();
try {
- const info = await this.controlPlane.info();
+ const info = await this.controlPlane.info(signal);
routers = info.routers;
this.#routers = info.routers;
const discovered =
@@ -419,6 +429,7 @@ export class AgentMesh {
} catch (err) {
errors.push(`info: ${err instanceof Error ? err.message : String(err)}`);
}
+ signal?.throwIfAborted();
if (keysChanged || bannedPeerIds !== undefined) {
await this.save();
}
diff --git a/sdk/js/src/session.test.ts b/sdk/js/src/session.test.ts
index 153728b8..9f3633b4 100644
--- a/sdk/js/src/session.test.ts
+++ b/sdk/js/src/session.test.ts
@@ -44,7 +44,7 @@ import { Identity } from "./identity.ts";
import { HTTP_HANDLER_OPTIONS, HTTP_PROTOCOL, a2aEndpoint, httpIngressHandler } from "./libp2p-http.ts";
import { LabelsNotSatisfiedError } from "./mcp.ts";
import { AgentMesh } from "./mesh.ts";
-import { MeshSession, candidatesFromRouterInfos, joinDeadline, selectRouters, type JoinOptions } from "./session.ts";
+import { JOIN_SYNC_TIMEOUT_MS, JOIN_TIMEOUT_MS, MeshSession, candidatesFromRouterInfos, joinMesh, selectRouters, type JoinOptions } from "./session.ts";
type Wasm = Awaited<ReturnType<typeof loadBiscuit>>;
type KeyPair = InstanceType<Wasm["KeyPair"]>;
@@ -127,6 +127,52 @@ function fakeControlPlane(routerAddresses: string[], routers: RouterInfo[] = [])
}) as typeof fetch;
}
+/**
+ * A control plane whose /keys and /info, once stall() is called, take the
+ * request and never answer until it is aborted. paths lists every request
+ * made after stall(), in order.
+ */
+function stallingControlPlane(routes: typeof fetch): { fetch: typeof fetch; stall(): void; paths: string[] } {
+ let stalled = false;
+ const paths: string[] = [];
+ const stalling = (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+ const path = new URL(new Request(input, init).url).pathname;
+ if (!stalled) {
+ return routes(input, init);
+ }
+ paths.push(path);
+ if (path !== "/keys" && path !== "/info") {
+ return routes(input, init);
+ }
+ return new Promise<Response>((_, reject) => {
+ const signal = init?.signal;
+ if (signal === undefined || signal === null) {
+ reject(new Error(`${path} was sent without a signal and would never end`));
+ return;
+ }
+ if (signal.aborted) {
+ reject(signal.reason);
+ return;
+ }
+ signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+ });
+ }) as typeof fetch;
+ return { fetch: stalling, stall: () => { stalled = true; }, paths };
+}
+
+/** A libp2p host that takes the auth stream and never writes back: a router whose handshake neither completes nor fails. */
+async function silentRouter(): Promise<Libp2p> {
+ const node = await createLibp2p({
+ addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
+ transports: [tcp()],
+ connectionEncrypters: [tls()],
+ streamMuxers: [yamux()],
+ services: { identify: identify() },
+ });
+ await node.handle(AUTH_PROTOCOL, () => {});
+ return node;
+}
+
before(async () => {
wasm = await loadBiscuit();
cpKeyPair = biscuitKeyPair(cpIdentity);
@@ -606,17 +652,8 @@ test("join reports a router that refuses the handshake", async () => {
});
test("a join bounded by its signal names the router whose handshake never answered", async () => {
- const silent = await createLibp2p({
- addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
- transports: [tcp()],
- connectionEncrypters: [tls()],
- streamMuxers: [yamux()],
- services: { identify: identify() },
- });
+ const silent = await silentRouter();
try {
- // Takes the auth stream and never writes back, as a router whose
- // handshake neither completes nor fails.
- await silent.handle(AUTH_PROTOCOL, () => {});
const addr = (silent.getMultiaddrs()[0] as ReturnType<typeof multiaddr>).toString();
const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([addr]) });
const started = Date.now();
@@ -631,40 +668,34 @@ test("a join bounded by its signal names the router whose handshake never answer
}
});
-test("a join bounded by its signal says when the control plane never answered", async () => {
- const pending: Array<() => void> = [];
- let hang = false;
- const routes = fakeControlPlane([routerAddr]);
- // Once enrolled, /keys and /info take the request and never answer, until
- // the request is aborted or the test ends.
- const stalling = (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
- const path = new URL(new Request(input, init).url).pathname;
- if (!hang || (path !== "/keys" && path !== "/info")) {
- return routes(input, init);
- }
- return new Promise<Response>((_, reject) => {
- const stop = () => reject(init?.signal?.reason ?? new Error("test over"));
- pending.push(stop);
- init?.signal?.addEventListener("abort", stop, { once: true });
- });
- }) as typeof fetch;
+test("a join stopped by its signal while syncing sends nothing more to the control plane", async () => {
+ const cp = stallingControlPlane(fakeControlPlane([routerAddr]));
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
+ cp.stall();
+ const started = Date.now();
+ await assert.rejects(mesh.join({ signal: AbortSignal.timeout(500) }), (err: Error) => {
+ assert.match(err.message, /^join stopped while syncing with the control plane: /, `got ${JSON.stringify(err.message)}, want the step the join stopped in`);
+ assert.doesNotMatch(err.message, /127\.0\.0\.1:1/, `got ${JSON.stringify(err.message)}, want no control plane URL in the error`);
+ return true;
+ });
+ const took = Date.now() - started;
+ assert.ok(took < JOIN_SYNC_TIMEOUT_MS, `join took ${took}ms, want the caller's signal to end it before the ${JOIN_SYNC_TIMEOUT_MS}ms sync timeout`);
+ // The aborted /keys request ends the sync: no /info, no refresh.
+ assert.deepEqual(cp.paths, ["/keys"], "requests after the control plane stalled");
+});
+
+test("a join goes on with the stored credential when the control plane does not answer", async () => {
+ const cp = stallingControlPlane(fakeControlPlane([routerAddr]));
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
+ cp.stall();
+ const started = Date.now();
+ const session = await mesh.join({ refreshLeadMs: 0, reserveRelay: false, controlPlaneSyncIntervalMs: 0 });
try {
- const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: stalling });
- hang = true;
- const started = Date.now();
- await assert.rejects(mesh.join({ signal: AbortSignal.timeout(500) }), (err: Error) => {
- assert.match(err.message, /syncing with the control plane at http:\/\/127\.0\.0\.1:1/, `got ${JSON.stringify(err.message)}, want the control plane named`);
- return true;
- });
const took = Date.now() - started;
- assert.ok(took < 10_000, `join took ${took}ms, want the join's signal to end it, not the control plane client's 30s request timeout`);
+ assert.ok(took < JOIN_TIMEOUT_MS, `join took ${took}ms, want the sync to give up after about ${JOIN_SYNC_TIMEOUT_MS}ms`);
+ assert.ok(session.isHeldRouter(router.peerId.toString()), `held routers ${session.routers.map((r) => r.peerId).join(",")}, want the router from the stored credential`);
} finally {
- // The sync the join gave up on goes on to its next request; let it
- // through so no request is left holding the client's 30s timer.
- hang = false;
- for (const stop of pending) {
- stop();
- }
+ await session.close();
}
});
@@ -705,17 +736,30 @@ test("a top-up whose signal has aborted tries no router and shuns none", async (
}
});
-test("a join without a signal of its own still has a deadline", async () => {
- const given = AbortSignal.timeout(60_000);
- const own = joinDeadline(given, 20);
- assert.equal(own.signal, given, "a caller's signal bounds the join as given");
- own.clear();
-
- const deadline = joinDeadline(undefined, 20);
- await new Promise((resolve) => deadline.signal.addEventListener("abort", resolve, { once: true }));
- const reason = deadline.signal.reason as Error;
- assert.match(reason.message, /^join timed out after 20ms$/, `abort reason ${JSON.stringify(reason.message)}`);
- deadline.clear();
+test("a join that runs out of its own time keeps the router that admitted it", async () => {
+ const silent = await silentRouter();
+ try {
+ const silentId = silent.peerId.toString();
+ const silentAddr = (silent.getMultiaddrs()[0] as ReturnType<typeof multiaddr>).toString();
+ // The idle router is tried first, the silent one second.
+ const routers = [
+ create(RouterInfoSchema, { peerId: router.peerId.toString(), addresses: [routerAddr], connections: 0, connectionLimit: 100 }),
+ create(RouterInfoSchema, { peerId: silentId, addresses: [silentAddr], connections: 90, connectionLimit: 100 }),
+ ];
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([routerAddr, silentAddr], routers) });
+ const started = Date.now();
+ const session = await joinMesh(mesh, { refreshLeadMs: 0, reserveRelay: false, controlPlaneSyncIntervalMs: 0 }, 2_000);
+ try {
+ const took = Date.now() - started;
+ assert.ok(took < AUTH_HANDSHAKE_TIMEOUT_MS, `join took ${took}ms, want its own timeout to end it before the ${AUTH_HANDSHAKE_TIMEOUT_MS}ms handshake timeout`);
+ assert.deepEqual(session.routers.map((r) => r.peerId), [router.peerId.toString()], "held routers");
+ assert.equal(session.shunnedRouters.has(silentId), false, `${silentId} was shunned for a handshake the join's timeout cut off`);
+ } finally {
+ await session.close();
+ }
+ } finally {
+ await silent.stop();
+ }
});
test("an explicit rejection is reported with its reason", async () => {
diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.ts
index cdafda10..54c04377 100644
--- a/sdk/js/src/session.ts
+++ b/sdk/js/src/session.ts
@@ -128,8 +128,8 @@ export interface JoinOptions extends MeshHostOptions {
/**
* Bounds the whole join: the control plane sync, and the dial, auth
* handshake and relay reservation with every router tried. Without one the
- * join is bounded by JOIN_TIMEOUT_MS (60s). An aborted join throws an error
- * naming each router tried and the step it was in.
+ * join is bounded by JOIN_TIMEOUT_MS (60s). A join that stops throws an
+ * error naming each router tried and the step it was in.
*/
signal?: AbortSignal;
}
@@ -208,6 +208,12 @@ const WITHDRAW_TIMEOUT_MS = 2 * 1000;
* its own, but a join tries them in turn over every router it is offered.
*/
export const JOIN_TIMEOUT_MS = 60_000;
+/**
+ * Bounds the control plane sync a join starts with. The sync is best effort,
+ * so a control plane that does not answer in time leaves the join to go on
+ * with the stored credential instead of using up the whole join.
+ */
+export const JOIN_SYNC_TIMEOUT_MS = 5_000;
/** How long a provider's positive egress verdict is kept; agentmesh-node's labelGateTTL. */
const EGRESS_VERDICT_TTL_MS = 5 * 60 * 1000;
@@ -564,14 +570,15 @@ export class MeshSession {
/**
* Runs the handshake on a router connection once: the connection:open
* listener and an explicit admission both call this, and the second waits
- * for the first instead of running a second handshake.
+ * for the first instead of running a second handshake. The signal applies
+ * to a handshake this call starts; one already running keeps its own.
*/
- #authenticateRouter(conn: Connection): Promise<VerifiedBiscuit> {
+ #authenticateRouter(conn: Connection, signal?: AbortSignal): Promise<VerifiedBiscuit> {
const pending = this.#routerHandshakes.get(conn.id);
if (pending !== undefined) {
return pending;
}
- const run = authenticateWithPeer(conn, this.mesh.authFrame(), this.mesh.credential.controlPlaneKeys).finally(() => {
+ const run = authenticateWithPeer(conn, this.mesh.authFrame(), this.mesh.credential.controlPlaneKeys, signal).finally(() => {
this.#routerHandshakes.delete(conn.id);
});
this.#routerHandshakes.set(conn.id, run);
@@ -722,22 +729,24 @@ export class MeshSession {
try {
const conn = await this.node.dial(cand.addresses, signal !== undefined ? { signal } : {});
step = "auth handshake";
- const credential = await untilAborted(this.#authenticateRouter(conn), signal);
+ const credential = await this.#authenticateRouter(conn, signal);
requireRole(credential, ROLE_ROUTER);
const addr = connectedAddress(conn, cand.peerId);
if (this.#reserveRelay) {
step = "relay reservation";
- await untilAborted(this.#reserveOnRouter(cand.peerId, addr), signal);
+ await this.#reserveOnRouter(cand.peerId, addr);
}
this.#upsertHeldRouter({ peerId: cand.peerId, addr, credential });
progress = true;
} catch (err) {
- this.#shunRouter(cand.peerId, ROUTER_SHUN_DURATION_MS);
- await this.node.hangUp(peerIdFromString(cand.peerId)).catch(() => {});
failures.push(`${cand.peerId}: ${step}: ${errorText(err)}`);
+ await this.node.hangUp(peerIdFromString(cand.peerId)).catch(() => {});
+ // A router cut off by the signal did not fail on its own, so it is
+ // not shunned.
if (aborted()) {
return failures;
}
+ this.#shunRouter(cand.peerId, ROUTER_SHUN_DURATION_MS);
}
}
if (!progress && picks.length < need) {
@@ -1434,30 +1443,13 @@ export function selectRouters(candidates: readonly RouterCandidate[], k: number,
}
/**
- * The signal a join runs under: the caller's, or one that aborts after ms
- * with an error saying the join timed out. clear() stops the timer once the
- * join is over.
+ * Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p.
+ * timeoutMs bounds a join whose caller passed no signal.
*/
-export function joinDeadline(signal: AbortSignal | undefined, ms = JOIN_TIMEOUT_MS): { signal: AbortSignal; clear(): void } {
- if (signal !== undefined) {
- return { signal, clear: () => {} };
- }
- const controller = new AbortController();
- const timer = setTimeout(() => controller.abort(new Error(`join timed out after ${ms}ms`)), ms);
- return { signal: controller.signal, clear: () => clearTimeout(timer) };
-}
-
-/** Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p. */
-export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Promise<MeshSession> {
- const deadline = joinDeadline(options.signal);
- try {
- return await joinUnder(mesh, options, deadline.signal);
- } finally {
- deadline.clear();
- }
-}
-
-async function joinUnder(mesh: AgentMesh, options: JoinOptions, signal: AbortSignal): Promise<MeshSession> {
+export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}, timeoutMs = JOIN_TIMEOUT_MS): Promise<MeshSession> {
+ const signal = options.signal ?? AbortSignal.timeout(timeoutMs);
+ // Why the join stopped: the caller's reason, or its own timeout.
+ const stopReason = () => (options.signal !== undefined ? errorText(signal.reason) : `timed out after ${timeoutMs}ms`);
// The pull agentmesh-node makes before it starts: a member resuming from its
// state directory after a key rotation would otherwise verify the routers,
// which already hold credentials under the new key, against the keys it
@@ -1465,12 +1457,12 @@ async function joinUnder(mesh: AgentMesh, options: JoinOptions, signal: AbortSig
// once joined. Best effort; the stored credential serves when the control
// plane cannot be reached.
try {
- await untilAborted(mesh.syncControlPlane(), signal);
+ await mesh.syncControlPlane(AbortSignal.any([signal, AbortSignal.timeout(JOIN_SYNC_TIMEOUT_MS)]));
} catch {
- // Joining goes on with what the credential holds, unless the join itself
- // ran out while the control plane kept it waiting.
+ // Joining goes on with what the credential holds, unless the caller
+ // stopped the join while the control plane kept it waiting.
if (signal.aborted) {
- throw new Error(`join stopped while syncing with the control plane at ${mesh.controlPlane.url}: ${errorText(signal.reason)}`);
+ throw new Error(`join stopped while syncing with the control plane: ${stopReason()}`);
}
}
const rawAddrs = options.routerAddresses ?? mesh.credential.routerAddresses;
@@ -1508,13 +1500,17 @@ async function joinUnder(mesh: AgentMesh, options: JoinOptions, signal: AbortSig
session = new MeshSession(mesh, node, [], authenticatedPeers, banned, options);
const failures = await session.topUpRouters(signal);
- if (signal.aborted || session.routers.length === 0) {
+ // One admitted router is enough to be on the mesh; only the caller's own
+ // signal turns that into a failure.
+ if (options.signal?.aborted === true || session.routers.length === 0) {
const detail = failures.length > 0 ? `:\n ${failures.join("\n ")}` : "";
- throw new Error(signal.aborted ? `join stopped: ${errorText(signal.reason)}${detail}` : `no router admitted this member${detail}`);
+ throw new Error(signal.aborted ? `join stopped: ${stopReason()}${detail}` : `no router admitted this member${detail}`);
}
// Best effort: a router that does not take the record is a warning the
- // next announcement retries; the member is on the mesh regardless.
- await session.announce(signal).catch(() => {});
+ // next announcement retries; the member is on the mesh regardless. Under
+ // the caller's signal only: a join that ran out of its own time still
+ // announces the routers it holds.
+ await session.announce(options.signal).catch(() => {});
return session;
} catch (err) {
if (session !== undefined) {
@@ -1526,26 +1522,6 @@ async function joinUnder(mesh: AgentMesh, options: JoinOptions, signal: AbortSig
}
}
-/**
- * Settles as p does, or rejects with the signal's reason as soon as it
- * aborts. p is not cancelled: it ends on its own timeout, and the caller
- * tears down what it was using.
- */
-function untilAborted<T>(p: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
- if (signal === undefined) {
- return p;
- }
- if (signal.aborted) {
- p.catch(() => {});
- return Promise.reject(signal.reason);
- }
- return new Promise<T>((resolve, reject) => {
- const onAbort = () => reject(signal.reason);
- signal.addEventListener("abort", onAbort, { once: true });
- void p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
- });
-}
-
function errorText(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.md
index 85743f36..6035e758 100644
--- a/site/content/docs/guides/native-sdks.md
+++ b/site/content/docs/guides/native-sdks.md
@@ -286,21 +286,15 @@ if (argv[0] !== undefined && !argv[0].includes("://")) {
}
const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/caller`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
console.log(`on the mesh as ${session.peerId}`);
// The peer to call: an agent named by ID, or a provider of a published service.
@@ -308,13 +302,9 @@ let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
if (peerId !== undefined) {
// An agent is not in the discovery table; the SDK finds the path to its
// peer ID through the routers.
- console.error(`dialing ${peerId}`);
await session.connect(peerId);
} else {
const providers = await session.discover(service);
- for (const p of providers) {
- console.error(`provider ${p.peerId}`);
- }
if (providers.length === 0) {
throw new Error(`no member of the mesh serves ${service}`);
}
@@ -322,7 +312,6 @@ if (peerId !== undefined) {
let reached = false;
for (const candidate of providers) {
try {
- console.error(`dialing ${candidate.peerId}`);
await session.connect(candidate);
provider = candidate;
reached = true;
@@ -536,21 +525,15 @@ import { AgentEvent, DefaultRequestHandler, InMemoryTaskStore, type AgentExecuto
import { UserBuilder, agentCardHandler, jsonRpcHandler } from "@a2a-js/sdk/server/express";
import { AgentMesh, MeshSession } from "@agentmesh-p2p/sdk";
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/a2a-agent`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
// The card names the agent as the mesh reaches it: the URL an A2A client on
// the mesh gives its fetch, http://mesh/mesh/<peer-id>/a2a/agent.
@@ -753,21 +736,15 @@ if (peerId === undefined) {
throw new Error("usage: a2a-call.js <peer-id> [text]");
}
-// Each stage goes to stderr as it is reached, so a run that hangs shows the
-// last one it got to; stdout carries only what callers parse.
-const controlPlaneUrl = process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com";
-console.error(`enrolling with ${controlPlaneUrl}`);
const mesh = await AgentMesh.enroll({
- controlPlaneUrl,
+ controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
jwtPath: process.env.AGENTMESH_JWT_PATH,
stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/a2a-caller`,
// A plaintext http:// control plane is otherwise accepted only on loopback.
allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
});
-console.error(`enrolled ${mesh.peerId}`);
const session = await mesh.join();
-console.error(`joined via ${session.routers.map((r) => r.peerId).join(", ")}`);
console.log(`on the mesh as ${session.peerId}`);
// The agent's URL on the mesh, and a fetch that carries requests to it.
@@ -778,7 +755,6 @@ const factory = new ClientFactory({
cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
});
// The card lives under the agent's URL; the trailing slash keeps the last segment when the resolver appends the well-known path.
-console.error(`dialing ${peerId}`);
const client = await factory.createFromUrl(agentURL + "/");
const card = await client.getAgentCard();
console.log(`agent: ${card.name}, ${card.description}`);