Skip to content

Agent Mesh

node: a member is a DHT client whatever its reachability

Antonio Ojead323f63ceb65
diff --git a/internal/node/dht.go b/internal/node/dht.go
new file mode 100644
index 00000000..5268de8e
--- /dev/null
+++ b/internal/node/dht.go
@@ -0,0 +1,44 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ dht "github.com/libp2p/go-libp2p-kad-dht"
+ "github.com/libp2p/go-libp2p-kad-dht/records"
+
+ "github.com/google/agentmesh/api"
+)
+
+// dhtOptions configures the member's DHT. A member is a DHT client whatever
+// its reachability: the routers are the directory, and a member that served
+// it would sit in every other member's routing table and take their lookups
+// on a 400-connection budget, answer whoever connects, and be trusted for
+// unsigned provider records. A public member is still dialled directly; the
+// role in the directory and the way it is reached are separate things.
+func dhtOptions(cfg Options) []dht.Option {
+ providerTTL := cfg.DHTProviderAddrTTL
+ if providerTTL <= 0 {
+ providerTTL = DefaultDHTProviderAddrTTL
+ }
+ opts := []dht.Option{
+ dht.Mode(dht.ModeClient),
+ dht.ProtocolPrefix(api.DHTProtocolPrefix),
+ dht.ProviderManagerOpts(records.ProviderAddrTTL(providerTTL), records.ProvideValidity(providerTTL)),
+ }
+ if cfg.DHTMaxRecordAge > 0 {
+ opts = append(opts, dht.MaxRecordAge(cfg.DHTMaxRecordAge))
+ }
+ return opts
+}
diff --git a/internal/node/dht_test.go b/internal/node/dht_test.go
new file mode 100644
index 00000000..5cf36543
--- /dev/null
+++ b/internal/node/dht_test.go
@@ -0,0 +1,83 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "slices"
+ "testing"
+ "time"
+
+ "github.com/libp2p/go-libp2p"
+ dht "github.com/libp2p/go-libp2p-kad-dht"
+ "github.com/libp2p/go-libp2p/core/host"
+ "github.com/libp2p/go-libp2p/core/protocol"
+
+ "github.com/google/agentmesh/api"
+)
+
+// TestMemberDHTStaysClientWhenPublic: a member whose reachability is public
+// must not serve the DHT protocol, or it lands in every other member's
+// routing table. The mode is the decision; the protocol list is what other
+// members see of it. The control DHT, in the mode the node used before,
+// shows that this host setup does flip a ModeAuto DHT to server.
+func TestMemberDHTStaysClientWhenPublic(t *testing.T) {
+ ctx, cancel := context.WithCancel(context.Background())
+ t.Cleanup(cancel)
+
+ newHost := func() host.Host {
+ h, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"), libp2p.ForceReachabilityPublic())
+ if err != nil {
+ t.Fatalf("libp2p.New: %v", err)
+ }
+ t.Cleanup(func() { _ = h.Close() })
+ return h
+ }
+ serves := func(h host.Host) bool {
+ return slices.Contains(h.Mux().Protocols(), protocol.ID(api.DHTProtocolID))
+ }
+
+ control := newHost()
+ controlDHT, err := dht.New(control, dht.Mode(dht.ModeAuto), dht.ProtocolPrefix(api.DHTProtocolPrefix))
+ if err != nil {
+ t.Fatalf("control dht.New: %v", err)
+ }
+ t.Cleanup(func() { _ = controlDHT.Close() })
+
+ member := newHost()
+ memberDHT, err := dht.New(member, dhtOptions(Options{})...)
+ if err != nil {
+ t.Fatalf("member dht.New: %v", err)
+ }
+ t.Cleanup(func() { _ = memberDHT.Close() })
+ if err := memberDHT.Bootstrap(ctx); err != nil {
+ t.Fatalf("Bootstrap: %v", err)
+ }
+
+ deadline := time.Now().Add(10 * time.Second)
+ for !serves(control) {
+ if time.Now().After(deadline) {
+ t.Fatalf("control DHT in ModeAuto on a public host never served %s; protocols: %v", api.DHTProtocolID, control.Mux().Protocols())
+ }
+ time.Sleep(20 * time.Millisecond)
+ }
+
+ if got := memberDHT.Mode(); got != dht.ModeClient {
+ t.Errorf("member DHT mode = %v, want %v", got, dht.ModeClient)
+ }
+ if serves(member) {
+ t.Errorf("member on a public host serves %s; protocols: %v", api.DHTProtocolID, member.Mux().Protocols())
+ }
+}
diff --git a/internal/node/node.go b/internal/node/node.go
index 93a99902..55737cf9 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -50,7 +50,6 @@ import (
"github.com/libp2p/go-libp2p"
gostream "github.com/libp2p/go-libp2p-gostream"
dht "github.com/libp2p/go-libp2p-kad-dht"
- records "github.com/libp2p/go-libp2p-kad-dht/records"
pubsub "github.com/libp2p/go-libp2p-pubsub"
"github.com/libp2p/go-libp2p/core/crypto"
"github.com/libp2p/go-libp2p/core/event"
@@ -688,19 +687,7 @@ func (n *AgentMeshNode) Start(ctx context.Context) error {
}
// Initialize Rendezvous (DHT Client)
- dhtOpts := []dht.Option{
- dht.Mode(dht.ModeAuto),
- dht.ProtocolPrefix(api.DHTProtocolPrefix),
- }
- providerTTL := n.config.DHTProviderAddrTTL
- if providerTTL <= 0 {
- providerTTL = DefaultDHTProviderAddrTTL
- }
- dhtOpts = append(dhtOpts, dht.ProviderManagerOpts(records.ProviderAddrTTL(providerTTL), records.ProvideValidity(providerTTL)))
- if n.config.DHTMaxRecordAge > 0 {
- dhtOpts = append(dhtOpts, dht.MaxRecordAge(n.config.DHTMaxRecordAge))
- }
- kdht, err := dht.New(h, dhtOpts...)
+ kdht, err := dht.New(h, dhtOptions(n.config)...)
if err != nil {
return err
}
diff --git a/site/content/docs/guides/scalability.md b/site/content/docs/guides/scalability.md
index 74f4dfda..02b1835a 100644
--- a/site/content/docs/guides/scalability.md
+++ b/site/content/docs/guides/scalability.md
@@ -82,7 +82,7 @@ dial tries every address at once.
| Role | What it is for the network | What it opens | What opens to it |
|---|---|---|---|
| Router | The dialable endpoint. Relay for members behind NAT, the DHT server every lookup reaches, the point of admission (credential handshake, relay ACL, bans), the hub GossipSub events pass through, and the record of which members hold a reservation on it. | Connections to the other routers (every pair), for the DHT and GossipSub. | Every member that holds it, every member's DHT client when it queries, the control plane's event publisher. |
-| Member (`agentmesh-node`, an SDK) | A client of the routers. It announces where it is reached, looks peers and services up, verifies the peers it talks to and carries the data plane. | K connections to the routers it holds (`--routers`, 2), one to each other router it queries, one to each peer it reaches directly. | Peers that call it: directly when they can, through a router otherwise. |
+| Member (`agentmesh-node`, an SDK) | A client of the routers. It announces where it is reached, looks peers and services up, verifies the peers it talks to and carries the data plane. It is a DHT client whatever its reachability: a public member is dialled directly, and still serves no lookups for others. | K connections to the routers it holds (`--routers`, 2), one to each other router it queries, one to each peer it reaches directly. | Peers that call it: directly when they can, through a router otherwise. |
| Provider | A member that publishes a service: the fan-in point of the mesh. | As a member. | One relayed connection per caller, each a stream on its connection to a router. |
| Control plane | Enrollment, the router catalog, keys, policy and leases, over HTTP. Its event publisher is a member that holds every router. | HTTP only, and the publisher's connections to the routers. | Members and routers, over HTTP. |
@@ -347,7 +347,9 @@ A member that enrolls needs its control plane and its routers reachable
from where it runs. Behind a NAT it is reached through a relay, which costs
a reservation on the router and nothing else; a member with a public
address may run `--reachability auto` and be dialled directly once AutoNAT
-has confirmed the address, which takes it off the relay.
+has confirmed the address, which takes it off the relay. Reachability
+decides how a member is reached and nothing else: it stays a DHT client,
+so it never enters other members' routing tables or serves their lookups.
## Sizing a service