Skip to content

Agent Mesh

sdk/python: authenticate with a router before querying it, release after

Antonio Ojea3606ae885415
diff --git a/sdk/python/src/agent_mesh/discovery.py b/sdk/python/src/agent_mesh/discovery.py
index 3d465189..272fa4ec 100644
--- a/sdk/python/src/agent_mesh/discovery.py
+++ b/sdk/python/src/agent_mesh/discovery.py
@@ -24,7 +24,7 @@ from __future__ import annotations
import hashlib
import logging
from dataclasses import dataclass, field
-from typing import Callable, Iterable, Literal
+from typing import Awaitable, Callable, Iterable, Literal
import multiaddr
import trio
@@ -116,7 +116,18 @@ async def _query(host: IHost, peer_id: ID, req: kad.Message) -> kad.Message | No
return resp if resp.type == req.type else None
-async def find_peer(host: IHost, target: ID, seeds: Iterable[ID], replication: int = DEFAULT_DHT_REPLICATION) -> list[multiaddr.Multiaddr]:
+Admit = Callable[[ID], Awaitable[None]]
+"""Authenticates this member with a router before it is queried: a router
+serves its DHT to a peer only once that peer passed the handshake."""
+
+
+async def find_peer(
+ host: IHost,
+ target: ID,
+ seeds: Iterable[ID],
+ replication: int = DEFAULT_DHT_REPLICATION,
+ admit: Admit | None = None,
+) -> list[multiaddr.Multiaddr]:
"""The addresses the DHT knows for a peer, as go-libp2p-kad-dht's FindPeer
learns them: a router answers FIND_NODE for a peer it is connected to with
that peer and its addresses, its relayed one included, and names the
@@ -130,11 +141,18 @@ async def find_peer(host: IHost, target: ID, seeds: Iterable[ID], replication: i
return True
return False
- await _walk(host, kad.Message(type=kad.Message.FIND_NODE, key=target.to_bytes()), seeds, take, skip={target}, replication=replication)
+ await _walk(host, kad.Message(type=kad.Message.FIND_NODE, key=target.to_bytes()), seeds, take, skip={target}, replication=replication, admit=admit)
return found
-async def find_providers(host: IHost, key: bytes, seeds: Iterable[ID], limit: int = 20, replication: int = DEFAULT_DHT_REPLICATION) -> list[DiscoveredProvider]:
+async def find_providers(
+ host: IHost,
+ key: bytes,
+ seeds: Iterable[ID],
+ limit: int = 20,
+ replication: int = DEFAULT_DHT_REPLICATION,
+ admit: Admit | None = None,
+) -> list[DiscoveredProvider]:
"""Asks the seed peers (the routers we are connected to) for providers of
key and follows the closer peers they name for a few rounds."""
found: dict[str, DiscoveredProvider] = {}
@@ -150,7 +168,7 @@ async def find_providers(host: IHost, key: bytes, seeds: Iterable[ID], limit: in
entry.addrs.append(str(ma))
return bool(found)
- await _walk(host, kad.Message(type=kad.Message.GET_PROVIDERS, key=key), seeds, take, replication=replication)
+ await _walk(host, kad.Message(type=kad.Message.GET_PROVIDERS, key=key), seeds, take, replication=replication, admit=admit)
return list(found.values())[:limit]
@@ -161,6 +179,7 @@ async def _walk(
take: Callable[[kad.Message], bool],
skip: frozenset[ID] | set[ID] = frozenset(),
replication: int = DEFAULT_DHT_REPLICATION,
+ admit: Admit | None = None,
) -> None:
"""The Kademlia walk both lookups share. A round asks its peers at once
and ends when an answer satisfies `take`; only otherwise are the closer
@@ -170,8 +189,34 @@ async def _walk(
may list a router this member cannot reach. A peer that did not answer
its dial is not dialed again. A router names the routers closest to the
key in order, and a record lives on the `replication` closest, so only
- that many of them are followed from one round to the next."""
+ that many of them are followed from one round to the next.
+
+ A router serves a query only from a member that authenticated with it,
+ so `admit` runs before each query. A router the walk connected to for
+ the query is disconnected when the walk ends: the member keeps sessions
+ with the routers it holds and with no other."""
self_id = host.get_id()
+ held = set(host.get_connected_peers())
+ try:
+ await _walk_rounds(host, req, seeds, take, skip, replication, admit, self_id)
+ finally:
+ for peer_id in set(host.get_connected_peers()) - held - {self_id}:
+ try:
+ await host.disconnect(peer_id)
+ except Exception as err: # noqa: BLE001 - already gone
+ logger.debug("dht: disconnect from %s after the walk: %s", peer_id, err)
+
+
+async def _walk_rounds(
+ host: IHost,
+ req: kad.Message,
+ seeds: Iterable[ID],
+ take: Callable[[kad.Message], bool],
+ skip: frozenset[ID] | set[ID],
+ replication: int,
+ admit: Admit | None,
+ self_id: ID,
+) -> None:
asked: set[ID] = set()
frontier: list[ID] = list(seeds)
fanout = min(max(replication, 1), _MAX_PEERS_PER_ROUND)
@@ -183,6 +228,12 @@ async def _walk(
answers: list[kad.Message] = []
async def ask(peer_id: ID) -> None:
+ if admit is not None:
+ try:
+ await admit(peer_id)
+ except Exception as err: # noqa: BLE001 - a router that refuses us is skipped
+ logger.debug("dht: %s did not admit this member: %s", peer_id, err)
+ return
resp = await _query(host, peer_id, req)
if resp is not None:
answers.append(resp)
diff --git a/sdk/python/src/agent_mesh/session.py b/sdk/python/src/agent_mesh/session.py
index 08f3734d..6dc35aeb 100644
--- a/sdk/python/src/agent_mesh/session.py
+++ b/sdk/python/src/agent_mesh/session.py
@@ -585,7 +585,7 @@ class MeshSession:
relays: list[multiaddr.Multiaddr] = []
seeds = [ID.from_base58(r.peer_id) for r in self.routers]
suffix = f"/p2p/{target}"
- for ma in await find_peer(self.host, target, seeds, self.mesh.dht_replication):
+ for ma in await find_peer(self.host, target, seeds, self.mesh.dht_replication, admit=self._admit_for_lookup):
text = str(ma)
if "/p2p-circuit" not in text:
try:
@@ -603,6 +603,15 @@ class MeshSession:
relays.append(relay_addr)
return direct, relays
+ async def _admit_for_lookup(self, peer_id: ID) -> None:
+ """Runs the handshake with a router a lookup is about to query. A
+ router this member holds is authenticated already; any other serves
+ the query only once this member authenticated on the connection the
+ walk just opened, and the walk closes that connection when it ends."""
+ if any(r.peer_id == str(peer_id) for r in self.routers):
+ return
+ await _authenticate_router(self.host, self.mesh, peer_id)
+
async def _admit_router(self, addr: multiaddr.Multiaddr) -> AdmittedRouter:
"""Dials a router, runs the handshake and, its role verified, adds it
to the admitted set."""
@@ -649,7 +658,7 @@ class MeshSession:
if service_type not in ("mcp", "inference", "a2a", "egress"):
raise ValueError(f"service type must be mcp, inference, a2a or egress, got {service_type!r}")
seeds = [ID.from_base58(r.peer_id) for r in self.routers]
- return await find_providers(self.host, service_key(service_type, service_name), seeds, limit, self.mesh.dht_replication)
+ return await find_providers(self.host, service_key(service_type, service_name), seeds, limit, self.mesh.dht_replication, admit=self._admit_for_lookup)
def open_mcp(
self,
diff --git a/sdk/python/tests/test_discovery.py b/sdk/python/tests/test_discovery.py
index dd849719..9b7a27af 100644
--- a/sdk/python/tests/test_discovery.py
+++ b/sdk/python/tests/test_discovery.py
@@ -280,3 +280,51 @@ def test_the_walk_follows_only_the_replication_closest_routers():
trio.run(main, 3, [GONE_POD, GONE_POD_2, DARK_ROUTER], clock=trio.testing.MockClock(autojump_threshold=0))
trio.run(main, 1, [GONE_POD], clock=trio.testing.MockClock(autojump_threshold=0))
+
+
+def test_the_walk_authenticates_before_each_query_and_releases_what_it_connected():
+ """A router serves a query only from a member that authenticated with it,
+ so `admit` runs for a router before it is queried: the held router and
+ the closer one the walk connects to for the record. That connection is
+ the walk's alone and is closed when the walk ends; the held router's
+ stays."""
+
+ class ReachableHost(_Host):
+ async def connect(self, info):
+ self.dials.append(info.peer_id)
+ self.connected.add(info.peer_id)
+ self._answers[info.peer_id] = lambda req: kad.Message(type=req.type, providerPeers=[_peer(PROVIDER, "/ip4/10.0.0.9/tcp/4001")])
+
+ def names_router_b(req):
+ return kad.Message(type=req.type, closerPeers=[_peer(ROUTER_B, "/ip4/10.0.0.2/tcp/4501")])
+
+ host = ReachableHost({ROUTER: names_router_b})
+ admitted = []
+
+ async def admit(peer_id):
+ assert peer_id in host.connected, "admit runs on an open connection"
+ admitted.append(peer_id)
+
+ async def main():
+ found = await find_providers(host, b"key", [ROUTER], admit=admit)
+ assert [p.peer_id for p in found] == [str(PROVIDER)]
+ assert admitted == [ROUTER, ROUTER_B], "every router is admitted before it is queried, in walk order"
+ assert host.connected == {ROUTER}, "the router the walk connected to is released; the held one is kept"
+
+ trio.run(main, clock=trio.testing.MockClock(autojump_threshold=0))
+
+
+def test_a_router_that_refuses_the_handshake_is_skipped():
+ """A router that does not admit this member answers nothing; the walk
+ takes the other answers and moves on."""
+ host = _Host({ROUTER: _after_a_rollout, ROUTER_B: _after_a_rollout})
+
+ async def admit(peer_id):
+ if peer_id == ROUTER_B:
+ raise RuntimeError("not admitted")
+
+ async def main():
+ found = await find_providers(host, b"key", [ROUTER, ROUTER_B], admit=admit)
+ assert [p.peer_id for p in found] == [str(PROVIDER)]
+
+ trio.run(main, clock=trio.testing.MockClock(autojump_threshold=0))