Skip to content

Agent Mesh

feat(node): interest-scoped service discovery over gossipsub

Antonio Ojea5e316248c718
diff --git a/api/network.go b/api/network.go
index 0baa0b66..5fdb68d0 100644
--- a/api/network.go
+++ b/api/network.go
@@ -15,6 +15,8 @@
package api
import (
+ "crypto/sha256"
+ "encoding/hex"
"fmt"
"regexp"
"strings"
@@ -43,6 +45,11 @@ const (
// GossipControlPlaneSync is the GossipSub topic used by the control plane to sync cluster state.
GossipControlPlaneSync = "/sam/control-plane/sync/v1"
+ // DiscoveryTopicPrefix is the GossipSub topic namespace for interest-scoped
+ // service announcements (ServiceAnnounce messages). Full topics are built
+ // with DiscoveryTopic; the version segment allows wire evolution.
+ DiscoveryTopicPrefix = "/sam/discovery/v1"
+
// DefaultAudience is the default audience string used in OIDC token validation.
DefaultAudience = "sam-mesh-audience"
)
@@ -100,6 +107,29 @@ const (
// This helps backward-compatibility with services that strictly distinguish
// between a root path "/" and an empty path "".
HeaderSamNoTrailingSlash = "X-Sam-No-Trailing-Slash"
+
+ // HeaderSamRequiredRegion constrains an inference request on the sidecar's
+ // OpenAI-compatible endpoints (/v1/*) to providers whose declared region is
+ // in the comma-separated list. It can only narrow what mesh policy allows,
+ // never widen it. Absent means any region permitted by policy.
+ //
+ // Reserved as part of the sidecar contract; enforced by the provider
+ // scorer. Region declarations are routing hints until attested via the
+ // node's Biscuit (see LabelRegion).
+ HeaderSamRequiredRegion = "X-Sam-Required-Region"
+)
+
+// ============================================================================
+// Well-Known Node Labels
+// ============================================================================
+
+const (
+ // LabelRegion is the operator-declared jurisdiction of a node (e.g. "eu").
+ // It is carried in ServiceAnnounce messages as a routing hint. Absent means
+ // the node makes no region claim, and consumers with a region requirement
+ // will never select it. Operator-declared labels always take precedence
+ // over runtime-derived values.
+ LabelRegion = "region"
)
// ============================================================================
@@ -159,6 +189,23 @@ func ServiceTypeToString(t ServiceType) (string, error) {
}
}
+// DiscoveryTopic returns the GossipSub topic for announcements about one
+// routing key (a model ID for inference, a tool name for MCP). Keys are
+// hashed so topic names stay bounded; consumers match exact keys from the
+// ServiceAnnounce payload, so hash collisions only merge announcement
+// streams, never routing decisions.
+func DiscoveryTopic(t ServiceType, key string) (string, error) {
+ typeStr, err := ServiceTypeToString(t)
+ if err != nil {
+ return "", err
+ }
+ if key == "" {
+ return "", fmt.Errorf("discovery topic key cannot be empty")
+ }
+ sum := sha256.Sum256([]byte(key))
+ return fmt.Sprintf("%s/%s/%s", DiscoveryTopicPrefix, typeStr, hex.EncodeToString(sum[:8])), nil
+}
+
// ============================================================================
// Parsing & Routing Utilities
// ============================================================================
diff --git a/api/sam.pb.go b/api/sam.pb.go
index 2df5a2ba..db4723f2 100644
--- a/api/sam.pb.go
+++ b/api/sam.pb.go
@@ -991,6 +991,115 @@ func (x *DiscoveredProvider) GetSrvDescription() string {
return ""
}
+// ServiceAnnounce is gossiped by a node on per-key topics (see
+// DiscoveryTopic) while those topics have subscribers. It is a routing
+// hint signed at the pubsub layer by the announcing peer: consumers use
+// it for freshness and load awareness, never for authorization.
+type ServiceAnnounce struct {
+ state protoimpl.MessageState `protogen:"open.v1"`
+ PeerId string `protobuf:"bytes,1,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
+ Type ServiceType `protobuf:"varint,2,opt,name=type,proto3,enum=sam.v1.ServiceType" json:"type,omitempty"`
+ ServiceName string `protobuf:"bytes,3,opt,name=service_name,json=serviceName,proto3" json:"service_name,omitempty"`
+ // Routing keys served by this service: model IDs for inference,
+ // tool names for MCP.
+ Keys []string `protobuf:"bytes,4,rep,name=keys,proto3" json:"keys,omitempty"`
+ // Operator-declared labels (e.g. LabelRegion). Operator claims always
+ // take precedence over runtime-derived values.
+ Labels map[string]string `protobuf:"bytes,5,rep,name=labels,proto3" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+ // Runtime load hints; zero values mean unknown.
+ ActiveRequests uint32 `protobuf:"varint,6,opt,name=active_requests,json=activeRequests,proto3" json:"active_requests,omitempty"`
+ LatencyEwmaMs float64 `protobuf:"fixed64,7,opt,name=latency_ewma_ms,json=latencyEwmaMs,proto3" json:"latency_ewma_ms,omitempty"`
+ Timestamp int64 `protobuf:"varint,8,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
+}
+
+func (x *ServiceAnnounce) Reset() {
+ *x = ServiceAnnounce{}
+ mi := &file_api_sam_proto_msgTypes[12]
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ ms.StoreMessageInfo(mi)
+}
+
+func (x *ServiceAnnounce) String() string {
+ return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ServiceAnnounce) ProtoMessage() {}
+
+func (x *ServiceAnnounce) ProtoReflect() protoreflect.Message {
+ mi := &file_api_sam_proto_msgTypes[12]
+ if x != nil {
+ ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+ if ms.LoadMessageInfo() == nil {
+ ms.StoreMessageInfo(mi)
+ }
+ return ms
+ }
+ return mi.MessageOf(x)
+}
+
+// Deprecated: Use ServiceAnnounce.ProtoReflect.Descriptor instead.
+func (*ServiceAnnounce) Descriptor() ([]byte, []int) {
+ return file_api_sam_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *ServiceAnnounce) GetPeerId() string {
+ if x != nil {
+ return x.PeerId
+ }
+ return ""
+}
+
+func (x *ServiceAnnounce) GetType() ServiceType {
+ if x != nil {
+ return x.Type
+ }
+ return ServiceType_SERVICE_TYPE_UNSPECIFIED
+}
+
+func (x *ServiceAnnounce) GetServiceName() string {
+ if x != nil {
+ return x.ServiceName
+ }
+ return ""
+}
+
+func (x *ServiceAnnounce) GetKeys() []string {
+ if x != nil {
+ return x.Keys
+ }
+ return nil
+}
+
+func (x *ServiceAnnounce) GetLabels() map[string]string {
+ if x != nil {
+ return x.Labels
+ }
+ return nil
+}
+
+func (x *ServiceAnnounce) GetActiveRequests() uint32 {
+ if x != nil {
+ return x.ActiveRequests
+ }
+ return 0
+}
+
+func (x *ServiceAnnounce) GetLatencyEwmaMs() float64 {
+ if x != nil {
+ return x.LatencyEwmaMs
+ }
+ return 0
+}
+
+func (x *ServiceAnnounce) GetTimestamp() int64 {
+ if x != nil {
+ return x.Timestamp
+ }
+ return 0
+}
+
type ControlPlaneInfoResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
OidcIssuer string `protobuf:"bytes,1,opt,name=oidc_issuer,json=oidcIssuer,proto3" json:"oidc_issuer,omitempty"`
@@ -1003,7 +1112,7 @@ type ControlPlaneInfoResponse struct {
func (x *ControlPlaneInfoResponse) Reset() {
*x = ControlPlaneInfoResponse{}
- mi := &file_api_sam_proto_msgTypes[12]
+ mi := &file_api_sam_proto_msgTypes[13]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1015,7 +1124,7 @@ func (x *ControlPlaneInfoResponse) String() string {
func (*ControlPlaneInfoResponse) ProtoMessage() {}
func (x *ControlPlaneInfoResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[12]
+ mi := &file_api_sam_proto_msgTypes[13]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1028,7 +1137,7 @@ func (x *ControlPlaneInfoResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use ControlPlaneInfoResponse.ProtoReflect.Descriptor instead.
func (*ControlPlaneInfoResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{12}
+ return file_api_sam_proto_rawDescGZIP(), []int{13}
}
func (x *ControlPlaneInfoResponse) GetOidcIssuer() string {
@@ -1072,7 +1181,7 @@ type RouterLeaseRequest struct {
func (x *RouterLeaseRequest) Reset() {
*x = RouterLeaseRequest{}
- mi := &file_api_sam_proto_msgTypes[13]
+ mi := &file_api_sam_proto_msgTypes[14]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1084,7 +1193,7 @@ func (x *RouterLeaseRequest) String() string {
func (*RouterLeaseRequest) ProtoMessage() {}
func (x *RouterLeaseRequest) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[13]
+ mi := &file_api_sam_proto_msgTypes[14]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1097,7 +1206,7 @@ func (x *RouterLeaseRequest) ProtoReflect() protoreflect.Message {
// Deprecated: Use RouterLeaseRequest.ProtoReflect.Descriptor instead.
func (*RouterLeaseRequest) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{13}
+ return file_api_sam_proto_rawDescGZIP(), []int{14}
}
func (x *RouterLeaseRequest) GetPeerId() string {
@@ -1146,7 +1255,7 @@ type RouterLeaseResponse struct {
func (x *RouterLeaseResponse) Reset() {
*x = RouterLeaseResponse{}
- mi := &file_api_sam_proto_msgTypes[14]
+ mi := &file_api_sam_proto_msgTypes[15]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1158,7 +1267,7 @@ func (x *RouterLeaseResponse) String() string {
func (*RouterLeaseResponse) ProtoMessage() {}
func (x *RouterLeaseResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[14]
+ mi := &file_api_sam_proto_msgTypes[15]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1171,7 +1280,7 @@ func (x *RouterLeaseResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use RouterLeaseResponse.ProtoReflect.Descriptor instead.
func (*RouterLeaseResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{14}
+ return file_api_sam_proto_rawDescGZIP(), []int{15}
}
func (x *RouterLeaseResponse) GetSuccess() bool {
@@ -1207,7 +1316,7 @@ type PolicyRole struct {
func (x *PolicyRole) Reset() {
*x = PolicyRole{}
- mi := &file_api_sam_proto_msgTypes[15]
+ mi := &file_api_sam_proto_msgTypes[16]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1219,7 +1328,7 @@ func (x *PolicyRole) String() string {
func (*PolicyRole) ProtoMessage() {}
func (x *PolicyRole) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[15]
+ mi := &file_api_sam_proto_msgTypes[16]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1232,7 +1341,7 @@ func (x *PolicyRole) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyRole.ProtoReflect.Descriptor instead.
func (*PolicyRole) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{15}
+ return file_api_sam_proto_rawDescGZIP(), []int{16}
}
func (x *PolicyRole) GetName() string {
@@ -1273,7 +1382,7 @@ type PolicyBinding struct {
func (x *PolicyBinding) Reset() {
*x = PolicyBinding{}
- mi := &file_api_sam_proto_msgTypes[16]
+ mi := &file_api_sam_proto_msgTypes[17]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1285,7 +1394,7 @@ func (x *PolicyBinding) String() string {
func (*PolicyBinding) ProtoMessage() {}
func (x *PolicyBinding) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[16]
+ mi := &file_api_sam_proto_msgTypes[17]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1298,7 +1407,7 @@ func (x *PolicyBinding) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyBinding.ProtoReflect.Descriptor instead.
func (*PolicyBinding) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{16}
+ return file_api_sam_proto_rawDescGZIP(), []int{17}
}
func (x *PolicyBinding) GetRole() string {
@@ -1323,7 +1432,7 @@ type PolicyConfigGetRequest struct {
func (x *PolicyConfigGetRequest) Reset() {
*x = PolicyConfigGetRequest{}
- mi := &file_api_sam_proto_msgTypes[17]
+ mi := &file_api_sam_proto_msgTypes[18]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1335,7 +1444,7 @@ func (x *PolicyConfigGetRequest) String() string {
func (*PolicyConfigGetRequest) ProtoMessage() {}
func (x *PolicyConfigGetRequest) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[17]
+ mi := &file_api_sam_proto_msgTypes[18]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1348,7 +1457,7 @@ func (x *PolicyConfigGetRequest) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyConfigGetRequest.ProtoReflect.Descriptor instead.
func (*PolicyConfigGetRequest) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{17}
+ return file_api_sam_proto_rawDescGZIP(), []int{18}
}
type PolicyConfigGetResponse struct {
@@ -1361,7 +1470,7 @@ type PolicyConfigGetResponse struct {
func (x *PolicyConfigGetResponse) Reset() {
*x = PolicyConfigGetResponse{}
- mi := &file_api_sam_proto_msgTypes[18]
+ mi := &file_api_sam_proto_msgTypes[19]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1373,7 +1482,7 @@ func (x *PolicyConfigGetResponse) String() string {
func (*PolicyConfigGetResponse) ProtoMessage() {}
func (x *PolicyConfigGetResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[18]
+ mi := &file_api_sam_proto_msgTypes[19]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1386,7 +1495,7 @@ func (x *PolicyConfigGetResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyConfigGetResponse.ProtoReflect.Descriptor instead.
func (*PolicyConfigGetResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{18}
+ return file_api_sam_proto_rawDescGZIP(), []int{19}
}
func (x *PolicyConfigGetResponse) GetRoles() []*PolicyRole {
@@ -1413,7 +1522,7 @@ type PolicyConfigUpdateRequest struct {
func (x *PolicyConfigUpdateRequest) Reset() {
*x = PolicyConfigUpdateRequest{}
- mi := &file_api_sam_proto_msgTypes[19]
+ mi := &file_api_sam_proto_msgTypes[20]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1425,7 +1534,7 @@ func (x *PolicyConfigUpdateRequest) String() string {
func (*PolicyConfigUpdateRequest) ProtoMessage() {}
func (x *PolicyConfigUpdateRequest) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[19]
+ mi := &file_api_sam_proto_msgTypes[20]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1438,7 +1547,7 @@ func (x *PolicyConfigUpdateRequest) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyConfigUpdateRequest.ProtoReflect.Descriptor instead.
func (*PolicyConfigUpdateRequest) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{19}
+ return file_api_sam_proto_rawDescGZIP(), []int{20}
}
func (x *PolicyConfigUpdateRequest) GetRoles() []*PolicyRole {
@@ -1465,7 +1574,7 @@ type PolicyConfigUpdateResponse struct {
func (x *PolicyConfigUpdateResponse) Reset() {
*x = PolicyConfigUpdateResponse{}
- mi := &file_api_sam_proto_msgTypes[20]
+ mi := &file_api_sam_proto_msgTypes[21]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1477,7 +1586,7 @@ func (x *PolicyConfigUpdateResponse) String() string {
func (*PolicyConfigUpdateResponse) ProtoMessage() {}
func (x *PolicyConfigUpdateResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[20]
+ mi := &file_api_sam_proto_msgTypes[21]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1490,7 +1599,7 @@ func (x *PolicyConfigUpdateResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use PolicyConfigUpdateResponse.ProtoReflect.Descriptor instead.
func (*PolicyConfigUpdateResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{20}
+ return file_api_sam_proto_rawDescGZIP(), []int{21}
}
func (x *PolicyConfigUpdateResponse) GetSuccess() bool {
@@ -1516,7 +1625,7 @@ type KeysResponse struct {
func (x *KeysResponse) Reset() {
*x = KeysResponse{}
- mi := &file_api_sam_proto_msgTypes[21]
+ mi := &file_api_sam_proto_msgTypes[22]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1528,7 +1637,7 @@ func (x *KeysResponse) String() string {
func (*KeysResponse) ProtoMessage() {}
func (x *KeysResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[21]
+ mi := &file_api_sam_proto_msgTypes[22]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1541,7 +1650,7 @@ func (x *KeysResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use KeysResponse.ProtoReflect.Descriptor instead.
func (*KeysResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{21}
+ return file_api_sam_proto_rawDescGZIP(), []int{22}
}
func (x *KeysResponse) GetPublicKeys() [][]byte {
@@ -1561,7 +1670,7 @@ type TokenRefreshRequest struct {
func (x *TokenRefreshRequest) Reset() {
*x = TokenRefreshRequest{}
- mi := &file_api_sam_proto_msgTypes[22]
+ mi := &file_api_sam_proto_msgTypes[23]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1573,7 +1682,7 @@ func (x *TokenRefreshRequest) String() string {
func (*TokenRefreshRequest) ProtoMessage() {}
func (x *TokenRefreshRequest) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[22]
+ mi := &file_api_sam_proto_msgTypes[23]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1586,7 +1695,7 @@ func (x *TokenRefreshRequest) ProtoReflect() protoreflect.Message {
// Deprecated: Use TokenRefreshRequest.ProtoReflect.Descriptor instead.
func (*TokenRefreshRequest) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{22}
+ return file_api_sam_proto_rawDescGZIP(), []int{23}
}
func (x *TokenRefreshRequest) GetChallengeSignature() []byte {
@@ -1614,7 +1723,7 @@ type TokenRefreshResponse struct {
func (x *TokenRefreshResponse) Reset() {
*x = TokenRefreshResponse{}
- mi := &file_api_sam_proto_msgTypes[23]
+ mi := &file_api_sam_proto_msgTypes[24]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1626,7 +1735,7 @@ func (x *TokenRefreshResponse) String() string {
func (*TokenRefreshResponse) ProtoMessage() {}
func (x *TokenRefreshResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[23]
+ mi := &file_api_sam_proto_msgTypes[24]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1639,7 +1748,7 @@ func (x *TokenRefreshResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use TokenRefreshResponse.ProtoReflect.Descriptor instead.
func (*TokenRefreshResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{23}
+ return file_api_sam_proto_rawDescGZIP(), []int{24}
}
func (x *TokenRefreshResponse) GetBiscuitToken() []byte {
@@ -1672,7 +1781,7 @@ type TokenRevokeRequest struct {
func (x *TokenRevokeRequest) Reset() {
*x = TokenRevokeRequest{}
- mi := &file_api_sam_proto_msgTypes[24]
+ mi := &file_api_sam_proto_msgTypes[25]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1684,7 +1793,7 @@ func (x *TokenRevokeRequest) String() string {
func (*TokenRevokeRequest) ProtoMessage() {}
func (x *TokenRevokeRequest) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[24]
+ mi := &file_api_sam_proto_msgTypes[25]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1697,7 +1806,7 @@ func (x *TokenRevokeRequest) ProtoReflect() protoreflect.Message {
// Deprecated: Use TokenRevokeRequest.ProtoReflect.Descriptor instead.
func (*TokenRevokeRequest) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{24}
+ return file_api_sam_proto_rawDescGZIP(), []int{25}
}
func (x *TokenRevokeRequest) GetPeerId() string {
@@ -1717,7 +1826,7 @@ type TokenRevokeResponse struct {
func (x *TokenRevokeResponse) Reset() {
*x = TokenRevokeResponse{}
- mi := &file_api_sam_proto_msgTypes[25]
+ mi := &file_api_sam_proto_msgTypes[26]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -1729,7 +1838,7 @@ func (x *TokenRevokeResponse) String() string {
func (*TokenRevokeResponse) ProtoMessage() {}
func (x *TokenRevokeResponse) ProtoReflect() protoreflect.Message {
- mi := &file_api_sam_proto_msgTypes[25]
+ mi := &file_api_sam_proto_msgTypes[26]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -1742,7 +1851,7 @@ func (x *TokenRevokeResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use TokenRevokeResponse.ProtoReflect.Descriptor instead.
func (*TokenRevokeResponse) Descriptor() ([]byte, []int) {
- return file_api_sam_proto_rawDescGZIP(), []int{25}
+ return file_api_sam_proto_rawDescGZIP(), []int{26}
}
func (x *TokenRevokeResponse) GetSuccess() bool {
@@ -1834,7 +1943,19 @@ const file_api_sam_proto_rawDesc = "" +
"\apeer_id\x18\x01 \x01(\tR\x06peerId\x12&\n" +
"\x0flocal_proxy_url\x18\x02 \x01(\tR\rlocalProxyUrl\x12\x19\n" +
"\bsrv_name\x18\x03 \x01(\tR\asrvName\x12'\n" +
- "\x0fsrv_description\x18\x04 \x01(\tR\x0esrvDescription\"\x9f\x01\n" +
+ "\x0fsrv_description\x18\x04 \x01(\tR\x0esrvDescription\"\xf1\x02\n" +
+ "\x0fServiceAnnounce\x12\x17\n" +
+ "\apeer_id\x18\x01 \x01(\tR\x06peerId\x12'\n" +
+ "\x04type\x18\x02 \x01(\x0e2\x13.sam.v1.ServiceTypeR\x04type\x12!\n" +
+ "\fservice_name\x18\x03 \x01(\tR\vserviceName\x12\x12\n" +
+ "\x04keys\x18\x04 \x03(\tR\x04keys\x12;\n" +
+ "\x06labels\x18\x05 \x03(\v2#.sam.v1.ServiceAnnounce.LabelsEntryR\x06labels\x12'\n" +
+ "\x0factive_requests\x18\x06 \x01(\rR\x0eactiveRequests\x12&\n" +
+ "\x0flatency_ewma_ms\x18\a \x01(\x01R\rlatencyEwmaMs\x12\x1c\n" +
+ "\ttimestamp\x18\b \x01(\x03R\ttimestamp\x1a9\n" +
+ "\vLabelsEntry\x12\x10\n" +
+ "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" +
+ "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\x9f\x01\n" +
"\x18ControlPlaneInfoResponse\x12\x1f\n" +
"\voidc_issuer\x18\x01 \x01(\tR\n" +
"oidcIssuer\x12\x1b\n" +
@@ -1910,7 +2031,7 @@ func file_api_sam_proto_rawDescGZIP() []byte {
}
var file_api_sam_proto_enumTypes = make([]protoimpl.EnumInfo, 3)
-var file_api_sam_proto_msgTypes = make([]protoimpl.MessageInfo, 27)
+var file_api_sam_proto_msgTypes = make([]protoimpl.MessageInfo, 29)
var file_api_sam_proto_goTypes = []any{
(EnrollmentStatus)(0), // 0: sam.v1.EnrollmentStatus
(ServiceType)(0), // 1: sam.v1.ServiceType
@@ -1927,38 +2048,42 @@ var file_api_sam_proto_goTypes = []any{
(*CommandBackend)(nil), // 12: sam.v1.CommandBackend
(*RegisterServiceRequest)(nil), // 13: sam.v1.RegisterServiceRequest
(*DiscoveredProvider)(nil), // 14: sam.v1.DiscoveredProvider
- (*ControlPlaneInfoResponse)(nil), // 15: sam.v1.ControlPlaneInfoResponse
- (*RouterLeaseRequest)(nil), // 16: sam.v1.RouterLeaseRequest
- (*RouterLeaseResponse)(nil), // 17: sam.v1.RouterLeaseResponse
- (*PolicyRole)(nil), // 18: sam.v1.PolicyRole
- (*PolicyBinding)(nil), // 19: sam.v1.PolicyBinding
- (*PolicyConfigGetRequest)(nil), // 20: sam.v1.PolicyConfigGetRequest
- (*PolicyConfigGetResponse)(nil), // 21: sam.v1.PolicyConfigGetResponse
- (*PolicyConfigUpdateRequest)(nil), // 22: sam.v1.PolicyConfigUpdateRequest
- (*PolicyConfigUpdateResponse)(nil), // 23: sam.v1.PolicyConfigUpdateResponse
- (*KeysResponse)(nil), // 24: sam.v1.KeysResponse
- (*TokenRefreshRequest)(nil), // 25: sam.v1.TokenRefreshRequest
- (*TokenRefreshResponse)(nil), // 26: sam.v1.TokenRefreshResponse
- (*TokenRevokeRequest)(nil), // 27: sam.v1.TokenRevokeRequest
- (*TokenRevokeResponse)(nil), // 28: sam.v1.TokenRevokeResponse
- nil, // 29: sam.v1.CommandBackend.EnvEntry
+ (*ServiceAnnounce)(nil), // 15: sam.v1.ServiceAnnounce
+ (*ControlPlaneInfoResponse)(nil), // 16: sam.v1.ControlPlaneInfoResponse
+ (*RouterLeaseRequest)(nil), // 17: sam.v1.RouterLeaseRequest
+ (*RouterLeaseResponse)(nil), // 18: sam.v1.RouterLeaseResponse
+ (*PolicyRole)(nil), // 19: sam.v1.PolicyRole
+ (*PolicyBinding)(nil), // 20: sam.v1.PolicyBinding
+ (*PolicyConfigGetRequest)(nil), // 21: sam.v1.PolicyConfigGetRequest
+ (*PolicyConfigGetResponse)(nil), // 22: sam.v1.PolicyConfigGetResponse
+ (*PolicyConfigUpdateRequest)(nil), // 23: sam.v1.PolicyConfigUpdateRequest
+ (*PolicyConfigUpdateResponse)(nil), // 24: sam.v1.PolicyConfigUpdateResponse
+ (*KeysResponse)(nil), // 25: sam.v1.KeysResponse
+ (*TokenRefreshRequest)(nil), // 26: sam.v1.TokenRefreshRequest
+ (*TokenRefreshResponse)(nil), // 27: sam.v1.TokenRefreshResponse
+ (*TokenRevokeRequest)(nil), // 28: sam.v1.TokenRevokeRequest
+ (*TokenRevokeResponse)(nil), // 29: sam.v1.TokenRevokeResponse
+ nil, // 30: sam.v1.CommandBackend.EnvEntry
+ nil, // 31: sam.v1.ServiceAnnounce.LabelsEntry
}
var file_api_sam_proto_depIdxs = []int32{
2, // 0: sam.v1.MeshEvent.type:type_name -> sam.v1.MeshEvent.Type
0, // 1: sam.v1.BootstrapEnrollResponse.status:type_name -> sam.v1.EnrollmentStatus
1, // 2: sam.v1.ServiceInfo.type:type_name -> sam.v1.ServiceType
- 29, // 3: sam.v1.CommandBackend.env:type_name -> sam.v1.CommandBackend.EnvEntry
+ 30, // 3: sam.v1.CommandBackend.env:type_name -> sam.v1.CommandBackend.EnvEntry
11, // 4: sam.v1.RegisterServiceRequest.service:type_name -> sam.v1.ServiceInfo
12, // 5: sam.v1.RegisterServiceRequest.command:type_name -> sam.v1.CommandBackend
- 18, // 6: sam.v1.PolicyConfigGetResponse.roles:type_name -> sam.v1.PolicyRole
- 19, // 7: sam.v1.PolicyConfigGetResponse.bindings:type_name -> sam.v1.PolicyBinding
- 18, // 8: sam.v1.PolicyConfigUpdateRequest.roles:type_name -> sam.v1.PolicyRole
- 19, // 9: sam.v1.PolicyConfigUpdateRequest.bindings:type_name -> sam.v1.PolicyBinding
- 10, // [10:10] is the sub-list for method output_type
- 10, // [10:10] is the sub-list for method input_type
- 10, // [10:10] is the sub-list for extension type_name
- 10, // [10:10] is the sub-list for extension extendee
- 0, // [0:10] is the sub-list for field type_name
+ 1, // 6: sam.v1.ServiceAnnounce.type:type_name -> sam.v1.ServiceType
+ 31, // 7: sam.v1.ServiceAnnounce.labels:type_name -> sam.v1.ServiceAnnounce.LabelsEntry
+ 19, // 8: sam.v1.PolicyConfigGetResponse.roles:type_name -> sam.v1.PolicyRole
+ 20, // 9: sam.v1.PolicyConfigGetResponse.bindings:type_name -> sam.v1.PolicyBinding
+ 19, // 10: sam.v1.PolicyConfigUpdateRequest.roles:type_name -> sam.v1.PolicyRole
+ 20, // 11: sam.v1.PolicyConfigUpdateRequest.bindings:type_name -> sam.v1.PolicyBinding
+ 12, // [12:12] is the sub-list for method output_type
+ 12, // [12:12] is the sub-list for method input_type
+ 12, // [12:12] is the sub-list for extension type_name
+ 12, // [12:12] is the sub-list for extension extendee
+ 0, // [0:12] is the sub-list for field type_name
}
func init() { file_api_sam_proto_init() }
@@ -1976,7 +2101,7 @@ func file_api_sam_proto_init() {
GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
RawDescriptor: unsafe.Slice(unsafe.StringData(file_api_sam_proto_rawDesc), len(file_api_sam_proto_rawDesc)),
NumEnums: 3,
- NumMessages: 27,
+ NumMessages: 29,
NumExtensions: 0,
NumServices: 0,
},
diff --git a/api/sam.proto b/api/sam.proto
index d5f1413e..12076f00 100644
--- a/api/sam.proto
+++ b/api/sam.proto
@@ -121,6 +121,26 @@ message DiscoveredProvider {
string srv_description = 4;
}
+// ServiceAnnounce is gossiped by a node on per-key topics (see
+// DiscoveryTopic) while those topics have subscribers. It is a routing
+// hint signed at the pubsub layer by the announcing peer: consumers use
+// it for freshness and load awareness, never for authorization.
+message ServiceAnnounce {
+ string peer_id = 1;
+ ServiceType type = 2;
+ string service_name = 3;
+ // Routing keys served by this service: model IDs for inference,
+ // tool names for MCP.
+ repeated string keys = 4;
+ // Operator-declared labels (e.g. LabelRegion). Operator claims always
+ // take precedence over runtime-derived values.
+ map<string, string> labels = 5;
+ // Runtime load hints; zero values mean unknown.
+ uint32 active_requests = 6;
+ double latency_ewma_ms = 7;
+ int64 timestamp = 8;
+}
+
message ControlPlaneInfoResponse {
string oidc_issuer = 1;
string client_id = 2;
diff --git a/api/validation.go b/api/validation.go
index 74272723..bd8b879c 100644
--- a/api/validation.go
+++ b/api/validation.go
@@ -5,6 +5,51 @@ import (
"strings"
)
+// Caps for ServiceAnnounce fields: announcements are unsolicited gossip, so
+// receivers bound every dimension before processing.
+const (
+ MaxAnnounceKeys = 64
+ MaxAnnounceLabels = 16
+ MaxAnnounceStringLen = 256
+)
+
+// ValidateServiceAnnounce bounds and sanity-checks a gossiped announcement.
+// Origin authenticity and freshness are the receiver's responsibility.
+func ValidateServiceAnnounce(a *ServiceAnnounce) error {
+ if a == nil {
+ return fmt.Errorf("announce is nil")
+ }
+ if a.GetPeerId() == "" || len(a.GetPeerId()) > MaxAnnounceStringLen {
+ return fmt.Errorf("invalid peer_id")
+ }
+ if _, err := ServiceTypeToString(a.GetType()); err != nil {
+ return fmt.Errorf("invalid type: %w", err)
+ }
+ if a.GetServiceName() == "" || len(a.GetServiceName()) > MaxAnnounceStringLen {
+ return fmt.Errorf("invalid service_name")
+ }
+ if len(a.GetKeys()) == 0 || len(a.GetKeys()) > MaxAnnounceKeys {
+ return fmt.Errorf("keys count %d out of range [1, %d]", len(a.GetKeys()), MaxAnnounceKeys)
+ }
+ for _, k := range a.GetKeys() {
+ if k == "" || len(k) > MaxAnnounceStringLen {
+ return fmt.Errorf("invalid key %q", k)
+ }
+ }
+ if len(a.GetLabels()) > MaxAnnounceLabels {
+ return fmt.Errorf("labels count %d exceeds %d", len(a.GetLabels()), MaxAnnounceLabels)
+ }
+ for k, v := range a.GetLabels() {
+ if k == "" || len(k) > MaxAnnounceStringLen || len(v) > MaxAnnounceStringLen {
+ return fmt.Errorf("invalid label %q", k)
+ }
+ }
+ if a.GetTimestamp() <= 0 {
+ return fmt.Errorf("missing timestamp")
+ }
+ return nil
+}
+
// ValidateServiceFormat ensures the service string follows the explicit URI format.
func ValidateServiceFormat(svc string) error {
if svc == "*" {
diff --git a/cmd/sam-node/main.go b/cmd/sam-node/main.go
index e51b11b5..e3eaec23 100644
--- a/cmd/sam-node/main.go
+++ b/cmd/sam-node/main.go
@@ -79,6 +79,7 @@ var (
autoRelayBackoffFlag time.Duration
routerConnectTimeoutFlag time.Duration
apiTokenFlag string
+ regionFlag string
tlsCertFlag string
tlsKeyFlag string
tlsCAFlag string
@@ -229,6 +230,7 @@ func main() {
AutoRelayBackoff: autoRelayBackoffFlag,
RouterConnectTimeout: routerConnectTimeoutFlag,
RequiredRole: api.RoleNode,
+ Region: regionFlag,
PolicySyncInterval: policySyncIntervalFlag,
DHTProviderAddrTTL: dhtProviderAddrTTLFlag,
DHTMaxRecordAge: dhtMaxRecordAgeFlag,
@@ -294,6 +296,7 @@ func main() {
AutoRelayBackoff: autoRelayBackoffFlag,
RouterConnectTimeout: routerConnectTimeoutFlag,
RequiredRole: api.RoleNode,
+ Region: regionFlag,
PolicySyncInterval: policySyncIntervalFlag,
DHTProviderAddrTTL: dhtProviderAddrTTLFlag,
DHTMaxRecordAge: dhtMaxRecordAgeFlag,
@@ -356,6 +359,7 @@ func main() {
AutoRelayBackoff: autoRelayBackoffFlag,
RouterConnectTimeout: routerConnectTimeoutFlag,
RequiredRole: api.RoleNode,
+ Region: regionFlag,
PolicySyncInterval: policySyncIntervalFlag,
})
if err != nil {
@@ -519,6 +523,7 @@ func main() {
AutoRelayBackoff: 3 * time.Second,
RouterConnectTimeout: routerConnectTimeoutFlag,
RequiredRole: api.RoleNode,
+ Region: regionFlag,
PolicySyncInterval: policySyncIntervalFlag,
})
if err != nil {
@@ -575,6 +580,7 @@ func main() {
joinCmd.Flags().BoolVar(&offlineAccessFlag, "offline-access", false, "Request OIDC offline access/refresh token for automatic renewal")
joinCmd.Flags().StringVar(&bootstrapTokenFlag, "bootstrap-token", "", "Pre-shared bootstrap token for enrollment")
runCmd.Flags().StringVar(&apiTokenFlag, "api-token", "", "Static Bearer token for API authorization")
+ runCmd.Flags().StringVar(&regionFlag, "region", "", "Operator-declared region of this node (e.g. \"eu\"); empty means no claim")
runCmd.Flags().StringVar(&tlsCertFlag, "tls-cert", "", "Path to TLS certificate for sidecar API")
runCmd.Flags().StringVar(&tlsKeyFlag, "tls-key", "", "Path to TLS key for sidecar API")
runCmd.Flags().StringVar(&tlsCAFlag, "tls-ca", "", "Path to TLS CA for sidecar API mTLS")
diff --git a/internal/node/discovery/announcer.go b/internal/node/discovery/announcer.go
new file mode 100644
index 00000000..8eb427ce
--- /dev/null
+++ b/internal/node/discovery/announcer.go
@@ -0,0 +1,186 @@
+// 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 discovery
+
+import (
+ "context"
+ "math/rand/v2"
+ "sync"
+ "time"
+
+ "github.com/google/sam/api"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/proto"
+)
+
+// Discovery is the node-facing handle: it announces local services
+// (provider role) and maintains an interest-scoped view of remote
+// providers (consumer role) over a shared set of gossip topics.
+type Discovery struct {
+ ps *pubsub.PubSub
+ self peer.ID
+ tm *topicManager
+
+ interval time.Duration
+ interestTTL time.Duration
+ staleAfter time.Duration
+ maxProviders int
+
+ runCtx context.Context
+
+ // announceTopics is only touched by the announce loop goroutine.
+ announceTopics map[string]*heldTopic
+
+ viewMu sync.Mutex
+ interests map[string]*interest
+ providers map[string]Provider // keyed peer|type|service
+}
+
+type heldTopic struct {
+ topic *pubsub.Topic
+ release func()
+}
+
+type interest struct {
+ sub *pubsub.Subscription
+ release func()
+ expires time.Time
+}
+
+// Option tweaks Discovery timing/bounds (used by tests).
+type Option func(*Discovery)
+
+func WithIntervals(announce, interestTTL, staleAfter time.Duration) Option {
+ return func(d *Discovery) {
+ d.interval = announce
+ d.interestTTL = interestTTL
+ d.staleAfter = staleAfter
+ }
+}
+
+func WithMaxProviders(n int) Option {
+ return func(d *Discovery) { d.maxProviders = n }
+}
+
+func New(ps *pubsub.PubSub, self peer.ID, opts ...Option) *Discovery {
+ d := &Discovery{
+ ps: ps,
+ self: self,
+ tm: newTopicManager(ps),
+ interval: DefaultAnnounceInterval,
+ interestTTL: DefaultInterestTTL,
+ staleAfter: DefaultStaleAfter,
+ maxProviders: DefaultMaxProviders,
+ announceTopics: map[string]*heldTopic{},
+ interests: map[string]*interest{},
+ providers: map[string]Provider{},
+ }
+ for _, o := range opts {
+ o(d)
+ }
+ return d
+}
+
+// Start runs the announce and interest-janitor loops until ctx is done.
+// src may be nil for consume-only nodes.
+func (d *Discovery) Start(ctx context.Context, src SourceFunc) {
+ d.runCtx = ctx
+ go d.janitorLoop(ctx)
+ if src != nil {
+ go d.announceLoop(ctx, src)
+ }
+}
+
+func (d *Discovery) announceLoop(ctx context.Context, src SourceFunc) {
+ for {
+ // ±20% jitter to avoid mesh-wide synchronization.
+ jittered := d.interval + time.Duration((rand.Float64()-0.5)*0.4*float64(d.interval))
+ select {
+ case <-ctx.Done():
+ for _, held := range d.announceTopics {
+ held.release()
+ }
+ d.announceTopics = map[string]*heldTopic{}
+ return
+ case <-time.After(jittered):
+ d.announceOnce(ctx, src())
+ }
+ }
+}
+
+// announceOnce reconciles the joined topic set with the desired one and
+// publishes on every desired topic that currently has subscribers.
+func (d *Discovery) announceOnce(ctx context.Context, anns []Announcement) {
+ desired := map[string][][]byte{}
+
+ for _, ann := range anns {
+ msg := &api.ServiceAnnounce{
+ PeerId: d.self.String(),
+ Type: ann.Type,
+ ServiceName: ann.Name,
+ Keys: ann.Keys,
+ Labels: ann.Labels,
+ ActiveRequests: ann.Load.ActiveRequests,
+ LatencyEwmaMs: ann.Load.LatencyEWMAMs,
+ Timestamp: time.Now().Unix(),
+ }
+ if err := api.ValidateServiceAnnounce(msg); err != nil {
+ logger.Warnf("[Discovery] skipping invalid announcement for %q: %v", ann.Name, err)
+ continue
+ }
+ data, err := proto.Marshal(msg)
+ if err != nil {
+ continue
+ }
+ for _, key := range ann.Keys {
+ name, err := api.DiscoveryTopic(ann.Type, key)
+ if err != nil {
+ continue
+ }
+ desired[name] = append(desired[name], data)
+ }
+ }
+
+ // Release topics no longer served.
+ for name, held := range d.announceTopics {
+ if _, ok := desired[name]; !ok {
+ held.release()
+ delete(d.announceTopics, name)
+ }
+ }
+
+ for name, msgs := range desired {
+ held, ok := d.announceTopics[name]
+ if !ok {
+ topic, release, err := d.tm.acquire(name)
+ if err != nil {
+ logger.Warnf("[Discovery] join %s: %v", name, err)
+ continue
+ }
+ held = &heldTopic{topic: topic, release: release}
+ d.announceTopics[name] = held
+ }
+ // Publish-when-subscribed: silence costs nothing on an idle mesh.
+ if len(held.topic.ListPeers()) == 0 {
+ continue
+ }
+ for _, data := range msgs {
+ if err := held.topic.Publish(ctx, data); err != nil {
+ logger.Debugf("[Discovery] publish %s: %v", name, err)
+ }
+ }
+ }
+}
diff --git a/internal/node/discovery/discovery.go b/internal/node/discovery/discovery.go
new file mode 100644
index 00000000..a77a985f
--- /dev/null
+++ b/internal/node/discovery/discovery.go
@@ -0,0 +1,86 @@
+// 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 discovery provides interest-scoped service announcements over
+// GossipSub. Providers announce routing keys (model IDs, tool names) on
+// per-key topics only while those topics have subscribers; consumers
+// subscribe only for keys they actively use. Cost therefore scales with
+// interest, not mesh size. Announcements are routing hints authenticated by
+// the pubsub layer's message signing — never authorization inputs.
+package discovery
+
+import (
+ "time"
+
+ "github.com/google/sam/api"
+ golog "github.com/ipfs/go-log/v2"
+)
+
+var logger = golog.Logger("sam-discovery")
+
+const (
+ // DefaultAnnounceInterval is how often a provider publishes on topics
+ // with subscribers; each tick is jittered ±20%.
+ DefaultAnnounceInterval = 10 * time.Second
+ // DefaultInterestTTL is how long a consumer stays subscribed to a key's
+ // topic after the last Ensure call for it.
+ DefaultInterestTTL = 5 * time.Minute
+ // DefaultStaleAfter is the age beyond which a provider entry is no
+ // longer returned by Providers.
+ DefaultStaleAfter = 30 * time.Second
+ // DefaultMaxProviders bounds the consumer-side provider table.
+ DefaultMaxProviders = 1024
+ // maxAnnounceSkew rejects announcements too old or too far in the
+ // future (replay/clock defense; pubsub dedup handles exact replays).
+ maxAnnounceSkew = 2 * time.Minute
+)
+
+// Load carries a provider's runtime hints. Zero values mean unknown.
+type Load struct {
+ ActiveRequests uint32
+ LatencyEWMAMs float64
+}
+
+// Announcement is one service's advertised state, fed by the node.
+type Announcement struct {
+ Type api.ServiceType
+ Name string
+ Keys []string
+ Labels map[string]string
+ Load Load
+}
+
+// SourceFunc supplies the current local announcements on each tick.
+type SourceFunc func() []Announcement
+
+// Provider is a remote service observed via gossip.
+type Provider struct {
+ PeerID string
+ Type api.ServiceType
+ Service string
+ Keys []string
+ Labels map[string]string
+ Load Load
+ LastSeen time.Time
+}
+
+// ServesKey reports whether the provider advertised the given routing key.
+func (p Provider) ServesKey(key string) bool {
+ for _, k := range p.Keys {
+ if k == key {
+ return true
+ }
+ }
+ return false
+}
diff --git a/internal/node/discovery/discovery_test.go b/internal/node/discovery/discovery_test.go
new file mode 100644
index 00000000..a2328df1
--- /dev/null
+++ b/internal/node/discovery/discovery_test.go
@@ -0,0 +1,272 @@
+// 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 discovery
+
+import (
+ "context"
+ "crypto/rand"
+ "testing"
+ "time"
+
+ "github.com/google/sam/api"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ pubsub_pb "github.com/libp2p/go-libp2p-pubsub/pb"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+ mocknet "github.com/libp2p/go-libp2p/p2p/net/mock"
+ "google.golang.org/protobuf/proto"
+)
+
+// newPair builds two connected in-memory hosts with gossipsub and Discovery.
+func newPair(t *testing.T) (provider, consumer *Discovery) {
+ t.Helper()
+ ctx, cancel := context.WithCancel(context.Background())
+ t.Cleanup(cancel)
+
+ mn := mocknet.New()
+ h1, err := mn.GenPeer()
+ if err != nil {
+ t.Fatal(err)
+ }
+ h2, err := mn.GenPeer()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := mn.LinkAll(); err != nil {
+ t.Fatal(err)
+ }
+ if err := mn.ConnectAllButSelf(); err != nil {
+ t.Fatal(err)
+ }
+
+ ps1, err := pubsub.NewGossipSub(ctx, h1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ ps2, err := pubsub.NewGossipSub(ctx, h2)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ opts := []Option{WithIntervals(100*time.Millisecond, 5*time.Second, 2*time.Second)}
+ provider = New(ps1, h1.ID(), opts...)
+ consumer = New(ps2, h2.ID(), opts...)
+ return provider, consumer
+}
+
+func TestAnnounceReachesInterestedConsumer(t *testing.T) {
+ provider, consumer := newPair(t)
+ ctx, cancel := context.WithCancel(context.Background())
+ t.Cleanup(cancel)
+
+ provider.Start(ctx, func() []Announcement {
+ return []Announcement{{
+ Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ Name: "llm",
+ Keys: []string{"model-a", "model-b"},
+ Labels: map[string]string{api.LabelRegion: "eu"},
+ Load: Load{ActiveRequests: 3},
+ }}
+ })
+ consumer.Start(ctx, nil)
+
+ // Interest registered after the announcer is already running: the
+ // publish-when-subscribed gate must open once the subscription spreads.
+ consumer.Ensure(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-a")
+
+ deadline := time.Now().Add(10 * time.Second)
+ for time.Now().Before(deadline) {
+ if ps := consumer.Providers(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-a"); len(ps) == 1 {
+ p := ps[0]
+ if p.Service != "llm" || p.Labels[api.LabelRegion] != "eu" || p.Load.ActiveRequests != 3 {
+ t.Fatalf("unexpected provider: %+v", p)
+ }
+ if !p.ServesKey("model-b") {
+ t.Fatalf("provider should carry all keys, got %v", p.Keys)
+ }
+ // Uninterested key on the same service: not subscribed, but the
+ // payload still resolves it once observed.
+ if ps2 := consumer.Providers(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-b"); len(ps2) != 1 {
+ t.Fatalf("model-b should resolve from the same announcement, got %v", ps2)
+ }
+ // Wrong type must not match.
+ if ps3 := consumer.Providers(api.ServiceType_SERVICE_TYPE_MCP, "model-a"); len(ps3) != 0 {
+ t.Fatalf("MCP lookup should be empty, got %v", ps3)
+ }
+ return
+ }
+ time.Sleep(50 * time.Millisecond)
+ }
+ t.Fatal("timeout waiting for announcement to reach consumer")
+}
+
+func TestProvidersGoStaleWithoutAnnouncements(t *testing.T) {
+ provider, consumer := newPair(t)
+ ctx, cancel := context.WithCancel(context.Background())
+ t.Cleanup(cancel)
+
+ announcing := true
+ provider.Start(ctx, func() []Announcement {
+ if !announcing {
+ return nil
+ }
+ return []Announcement{{
+ Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ Name: "llm",
+ Keys: []string{"model-a"},
+ }}
+ })
+ consumer.Start(ctx, nil)
+ consumer.Ensure(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-a")
+
+ deadline := time.Now().Add(10 * time.Second)
+ for time.Now().Before(deadline) {
+ if len(consumer.Providers(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-a")) == 1 {
+ break
+ }
+ time.Sleep(50 * time.Millisecond)
+ }
+
+ announcing = false
+ deadline = time.Now().Add(10 * time.Second)
+ for time.Now().Before(deadline) {
+ if len(consumer.Providers(api.ServiceType_SERVICE_TYPE_INFERENCE, "model-a")) == 0 {
+ return // went stale as expected
+ }
+ time.Sleep(100 * time.Millisecond)
+ }
+ t.Fatal("provider never went stale after announcements stopped")
+}
+
+// testPeerID generates a peer identity for constructing raw messages.
+func testPeerID(t *testing.T) peer.ID {
+ t.Helper()
+ priv, _, err := crypto.GenerateEd25519Key(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ pid, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return pid
+}
+
+func rawMessage(t *testing.T, from peer.ID, ann *api.ServiceAnnounce) *pubsub.Message {
+ t.Helper()
+ data, err := proto.Marshal(ann)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return &pubsub.Message{Message: &pubsub_pb.Message{From: []byte(from), Data: data}}
+}
+
+func TestObserveRejectsForgedAndStale(t *testing.T) {
+ d := New(nil, testPeerID(t))
+ signer := testPeerID(t)
+ other := testPeerID(t)
+
+ valid := &api.ServiceAnnounce{
+ PeerId: signer.String(),
+ Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ ServiceName: "llm",
+ Keys: []string{"m1"},
+ Timestamp: time.Now().Unix(),
+ }
+
+ tests := []struct {
+ name string
+ msg *pubsub.Message
+ want int
+ }{
+ {"valid announce accepted", rawMessage(t, signer, valid), 1},
+ {"peer_id not matching signer dropped", rawMessage(t, other, valid), 0},
+ {"stale timestamp dropped", rawMessage(t, signer, &api.ServiceAnnounce{
+ PeerId: signer.String(), Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ ServiceName: "llm", Keys: []string{"m1"},
+ Timestamp: time.Now().Add(-10 * time.Minute).Unix(),
+ }), 0},
+ {"future timestamp dropped", rawMessage(t, signer, &api.ServiceAnnounce{
+ PeerId: signer.String(), Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ ServiceName: "llm", Keys: []string{"m1"},
+ Timestamp: time.Now().Add(10 * time.Minute).Unix(),
+ }), 0},
+ {"invalid payload dropped", &pubsub.Message{
+ Message: &pubsub_pb.Message{From: []byte(signer), Data: []byte("junk")},
+ }, 0},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ d.providers = map[string]Provider{}
+ d.observe(tt.msg)
+ if got := len(d.providers); got != tt.want {
+ t.Errorf("providers: got %d, want %d", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestProviderTableIsBounded(t *testing.T) {
+ d := New(nil, testPeerID(t), WithMaxProviders(2))
+ for range 3 {
+ signer := testPeerID(t)
+ d.observe(rawMessage(t, signer, &api.ServiceAnnounce{
+ PeerId: signer.String(), Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ ServiceName: "llm", Keys: []string{"m1"},
+ Timestamp: time.Now().Unix(),
+ }))
+ }
+ if got := len(d.providers); got != 2 {
+ t.Fatalf("provider table size: got %d, want 2", got)
+ }
+}
+
+func TestValidateServiceAnnounceCaps(t *testing.T) {
+ base := func() *api.ServiceAnnounce {
+ return &api.ServiceAnnounce{
+ PeerId: "12D3KooWTest", Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ ServiceName: "llm", Keys: []string{"m1"}, Timestamp: 1,
+ }
+ }
+ tooMany := make([]string, api.MaxAnnounceKeys+1)
+ for i := range tooMany {
+ tooMany[i] = "m"
+ }
+
+ tests := []struct {
+ name string
+ mutate func(*api.ServiceAnnounce)
+ wantErr bool
+ }{
+ {"valid", func(a *api.ServiceAnnounce) {}, false},
+ {"no keys", func(a *api.ServiceAnnounce) { a.Keys = nil }, true},
+ {"too many keys", func(a *api.ServiceAnnounce) { a.Keys = tooMany }, true},
+ {"empty peer", func(a *api.ServiceAnnounce) { a.PeerId = "" }, true},
+ {"unspecified type", func(a *api.ServiceAnnounce) { a.Type = api.ServiceType_SERVICE_TYPE_UNSPECIFIED }, true},
+ {"no timestamp", func(a *api.ServiceAnnounce) { a.Timestamp = 0 }, true},
+ {"oversized label", func(a *api.ServiceAnnounce) {
+ a.Labels = map[string]string{"k": string(make([]byte, api.MaxAnnounceStringLen+1))}
+ }, true},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ a := base()
+ tt.mutate(a)
+ if err := api.ValidateServiceAnnounce(a); (err != nil) != tt.wantErr {
+ t.Errorf("ValidateServiceAnnounce: err=%v, wantErr=%v", err, tt.wantErr)
+ }
+ })
+ }
+}
diff --git a/internal/node/discovery/topics.go b/internal/node/discovery/topics.go
new file mode 100644
index 00000000..676cec80
--- /dev/null
+++ b/internal/node/discovery/topics.go
@@ -0,0 +1,71 @@
+// 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 discovery
+
+import (
+ "sync"
+
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+)
+
+// topicManager refcounts pubsub topic handles: gossipsub allows a single
+// Join per topic per host, and the announcer and the view may need the
+// same topic (a node can provide and consume the same key).
+type topicManager struct {
+ ps *pubsub.PubSub
+ mu sync.Mutex
+ topics map[string]*topicRef
+}
+
+type topicRef struct {
+ topic *pubsub.Topic
+ refs int
+}
+
+func newTopicManager(ps *pubsub.PubSub) *topicManager {
+ return &topicManager{ps: ps, topics: map[string]*topicRef{}}
+}
+
+// acquire joins the topic (or reuses the existing handle) and returns a
+// release func. The topic is closed when the last holder releases it.
+func (tm *topicManager) acquire(name string) (*pubsub.Topic, func(), error) {
+ tm.mu.Lock()
+ defer tm.mu.Unlock()
+ ref, ok := tm.topics[name]
+ if !ok {
+ topic, err := tm.ps.Join(name)
+ if err != nil {
+ return nil, nil, err
+ }
+ ref = &topicRef{topic: topic}
+ tm.topics[name] = ref
+ }
+ ref.refs++
+ var once sync.Once
+ release := func() {
+ once.Do(func() {
+ tm.mu.Lock()
+ defer tm.mu.Unlock()
+ ref.refs--
+ if ref.refs == 0 {
+ if err := ref.topic.Close(); err != nil {
+ logger.Debugf("[Discovery] closing topic %s: %v", name, err)
+ }
+ delete(tm.topics, name)
+ }
+ })
+ }
+ return ref.topic, release, nil
+}
diff --git a/internal/node/discovery/view.go b/internal/node/discovery/view.go
new file mode 100644
index 00000000..7e2898b9
--- /dev/null
+++ b/internal/node/discovery/view.go
@@ -0,0 +1,184 @@
+// 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 discovery
+
+import (
+ "context"
+ "time"
+
+ "github.com/google/sam/api"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/proto"
+)
+
+// Ensure registers interest in a routing key: it subscribes to the key's
+// topic (if not already) and refreshes the interest TTL. Safe to call on
+// every request for the key.
+func (d *Discovery) Ensure(t api.ServiceType, key string) {
+ name, err := api.DiscoveryTopic(t, key)
+ if err != nil {
+ return
+ }
+ d.viewMu.Lock()
+ defer d.viewMu.Unlock()
+ if in, ok := d.interests[name]; ok {
+ in.expires = time.Now().Add(d.interestTTL)
+ return
+ }
+ topic, release, err := d.tm.acquire(name)
+ if err != nil {
+ logger.Warnf("[Discovery] join %s: %v", name, err)
+ return
+ }
+ sub, err := topic.Subscribe()
+ if err != nil {
+ release()
+ logger.Warnf("[Discovery] subscribe %s: %v", name, err)
+ return
+ }
+ d.interests[name] = &interest{
+ sub: sub,
+ release: release,
+ expires: time.Now().Add(d.interestTTL),
+ }
+ ctx := d.runCtx
+ if ctx == nil {
+ ctx = context.Background()
+ }
+ go d.readLoop(ctx, sub)
+}
+
+// Providers returns the fresh, non-self providers observed for a key.
+func (d *Discovery) Providers(t api.ServiceType, key string) []Provider {
+ d.viewMu.Lock()
+ defer d.viewMu.Unlock()
+ cutoff := time.Now().Add(-d.staleAfter)
+ var out []Provider
+ for _, p := range d.providers {
+ if p.Type == t && p.LastSeen.After(cutoff) && p.ServesKey(key) {
+ out = append(out, p)
+ }
+ }
+ return out
+}
+
+// readLoop consumes one subscription until it is cancelled or ctx ends.
+func (d *Discovery) readLoop(ctx context.Context, sub *pubsub.Subscription) {
+ for {
+ msg, err := sub.Next(ctx)
+ if err != nil {
+ return // subscription cancelled or ctx done
+ }
+ if msg.GetFrom() == d.self {
+ continue
+ }
+ d.observe(msg)
+ }
+}
+
+// observe validates a gossiped announcement and records the provider.
+func (d *Discovery) observe(msg *pubsub.Message) {
+ var ann api.ServiceAnnounce
+ if err := proto.Unmarshal(msg.Data, &ann); err != nil {
+ logger.Debugf("[Discovery] dropping undecodable announce from %s: %v", msg.GetFrom(), err)
+ return
+ }
+ if err := api.ValidateServiceAnnounce(&ann); err != nil {
+ logger.Debugf("[Discovery] dropping invalid announce from %s: %v", msg.GetFrom(), err)
+ return
+ }
+ // The claimed identity must be the pubsub message signer.
+ claimed, err := peer.Decode(ann.GetPeerId())
+ if err != nil || claimed != msg.GetFrom() {
+ logger.Warnf("[Discovery] dropping announce with peer_id %q not matching signer %s", ann.GetPeerId(), msg.GetFrom())
+ return
+ }
+ ts := time.Unix(ann.GetTimestamp(), 0)
+ if age := time.Since(ts); age > maxAnnounceSkew || age < -maxAnnounceSkew {
+ logger.Debugf("[Discovery] dropping stale/future announce from %s (age %v)", msg.GetFrom(), time.Since(ts))
+ return
+ }
+
+ typeStr, _ := api.ServiceTypeToString(ann.GetType())
+ entryKey := ann.GetPeerId() + "|" + typeStr + "|" + ann.GetServiceName()
+
+ d.viewMu.Lock()
+ defer d.viewMu.Unlock()
+ if _, exists := d.providers[entryKey]; !exists && len(d.providers) >= d.maxProviders {
+ d.evictOldestLocked()
+ }
+ d.providers[entryKey] = Provider{
+ PeerID: ann.GetPeerId(),
+ Type: ann.GetType(),
+ Service: ann.GetServiceName(),
+ Keys: ann.GetKeys(),
+ Labels: ann.GetLabels(),
+ Load: Load{
+ ActiveRequests: ann.GetActiveRequests(),
+ LatencyEWMAMs: ann.GetLatencyEwmaMs(),
+ },
+ LastSeen: time.Now(),
+ }
+}
+
+func (d *Discovery) evictOldestLocked() {
+ var oldestKey string
+ var oldest time.Time
+ for k, p := range d.providers {
+ if oldestKey == "" || p.LastSeen.Before(oldest) {
+ oldestKey, oldest = k, p.LastSeen
+ }
+ }
+ if oldestKey != "" {
+ delete(d.providers, oldestKey)
+ }
+}
+
+// janitorLoop drops expired interests and stale provider entries.
+func (d *Discovery) janitorLoop(ctx context.Context) {
+ ticker := time.NewTicker(d.interestTTL / 4)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ d.viewMu.Lock()
+ for name, in := range d.interests {
+ in.sub.Cancel()
+ in.release()
+ delete(d.interests, name)
+ }
+ d.viewMu.Unlock()
+ return
+ case <-ticker.C:
+ now := time.Now()
+ d.viewMu.Lock()
+ for name, in := range d.interests {
+ if now.After(in.expires) {
+ in.sub.Cancel()
+ in.release()
+ delete(d.interests, name)
+ }
+ }
+ cutoff := now.Add(-2 * d.staleAfter)
+ for k, p := range d.providers {
+ if p.LastSeen.Before(cutoff) {
+ delete(d.providers, k)
+ }
+ }
+ d.viewMu.Unlock()
+ }
+ }
+}
diff --git a/internal/node/discovery_source.go b/internal/node/discovery_source.go
new file mode 100644
index 00000000..e115338c
--- /dev/null
+++ b/internal/node/discovery_source.go
@@ -0,0 +1,68 @@
+// 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"
+ "time"
+
+ "github.com/google/sam/api"
+ "github.com/google/sam/internal/node/discovery"
+)
+
+// discoverySourceProbeTimeout bounds each backend model probe per tick.
+const discoverySourceProbeTimeout = 2 * time.Second
+
+// activeTracker is implemented by services that report in-flight load.
+type activeTracker interface {
+ ActiveRequests() uint32
+}
+
+// discoverySource builds gossip announcements from the registered services.
+// Only inference services announce for now; MCP adoption follows.
+func (n *SamNode) discoverySource() []discovery.Announcement {
+ var labels map[string]string
+ if n.config.Region != "" {
+ labels = map[string]string{api.LabelRegion: n.config.Region}
+ }
+ var out []discovery.Announcement
+ for _, info := range n.services.List(api.ServiceType_SERVICE_TYPE_INFERENCE) {
+ svc, ok := n.services.Get(info.GetName())
+ if !ok {
+ continue
+ }
+ lister, ok := svc.(modelLister)
+ if !ok {
+ continue
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), discoverySourceProbeTimeout)
+ models, err := lister.Models(ctx)
+ cancel()
+ if err != nil || len(models) == 0 {
+ continue
+ }
+ ann := discovery.Announcement{
+ Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ Name: info.GetName(),
+ Keys: models,
+ Labels: labels,
+ }
+ if tracker, ok := svc.(activeTracker); ok {
+ ann.Load.ActiveRequests = tracker.ActiveRequests()
+ }
+ out = append(out, ann)
+ }
+ return out
+}
diff --git a/internal/node/inference_service.go b/internal/node/inference_service.go
index 4da3f8a6..38fceb39 100644
--- a/internal/node/inference_service.go
+++ b/internal/node/inference_service.go
@@ -25,18 +25,30 @@ import (
"net/http/httputil"
"net/url"
"strings"
+ "sync"
+ "sync/atomic"
+ "time"
"github.com/google/sam/api"
"github.com/libp2p/go-libp2p/core/peer"
"github.com/openai/openai-go"
)
+// modelCacheTTL bounds backend /v1/models probes: the announcer ticks more
+// often than models change.
+const modelCacheTTL = 30 * time.Second
+
// InferenceService provides intelligent LLM gateway features: traffic routing
// and token usage tracking for OpenAI-compatible endpoints.
type InferenceService struct {
baseService
backendURL *url.URL
engine InferenceEngine
+ active atomic.Int64
+
+ modelsMu sync.Mutex
+ cachedModels []string
+ modelsExpires time.Time
}
func (s *InferenceService) Init(ctx context.Context) error {
@@ -48,7 +60,7 @@ func (s *InferenceService) Init(ctx context.Context) error {
}
s.backendURL = u
s.engine = newOpenAIEngine(u, nil)
- s.handler = s.newInferenceProxy()
+ s.handler = s.trackActive(s.newInferenceProxy())
case *api.RegisterServiceRequest_Command:
return fmt.Errorf("command-based backends are not supported for InferenceService")
default:
@@ -57,12 +69,41 @@ func (s *InferenceService) Init(ctx context.Context) error {
return nil
}
-// Models probes the backend connector for the model IDs it serves.
+// Models returns the model IDs the backend serves, cached briefly since both
+// the discovery announcer and the OpenAI facade call it repeatedly.
func (s *InferenceService) Models(ctx context.Context) ([]string, error) {
if s.engine == nil {
return nil, fmt.Errorf("inference service %q not initialized", s.info.GetName())
}
- return s.engine.Models(ctx)
+ s.modelsMu.Lock()
+ defer s.modelsMu.Unlock()
+ if s.cachedModels != nil && time.Now().Before(s.modelsExpires) {
+ return s.cachedModels, nil
+ }
+ models, err := s.engine.Models(ctx)
+ if err != nil {
+ return nil, err
+ }
+ s.cachedModels = models
+ s.modelsExpires = time.Now().Add(modelCacheTTL)
+ return models, nil
+}
+
+// ActiveRequests reports in-flight requests, a load hint for announcements.
+func (s *InferenceService) ActiveRequests() uint32 {
+ n := s.active.Load()
+ if n < 0 {
+ return 0
+ }
+ return uint32(n)
+}
+
+func (s *InferenceService) trackActive(next http.Handler) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ s.active.Add(1)
+ defer s.active.Add(-1)
+ next.ServeHTTP(w, r)
+ })
}
func (s *InferenceService) newInferenceProxy() http.Handler {
diff --git a/internal/node/node.go b/internal/node/node.go
index a67b9217..6857aad1 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -39,6 +39,7 @@ import (
"github.com/biscuit-auth/biscuit-go/v2/datalog"
"github.com/google/sam/api"
"github.com/google/sam/internal/identity"
+ samdiscovery "github.com/google/sam/internal/node/discovery"
lru "github.com/hashicorp/golang-lru/v2"
"github.com/ipfs/go-cid"
golog "github.com/ipfs/go-log/v2"
@@ -125,6 +126,7 @@ type SamNode struct {
Host host.Host
DHT *dht.IpfsDHT
PubSub *pubsub.PubSub
+ Discovery *samdiscovery.Discovery
Store *Store
RouterPeerID peer.ID
authenticatedRouters map[peer.ID]bool
@@ -465,6 +467,10 @@ func (n *SamNode) Start(ctx context.Context) error {
}
n.PubSub = ps
+ // Interest-scoped service announcements (provider + consumer roles).
+ n.Discovery = samdiscovery.New(ps, h.ID())
+ n.Discovery.Start(ctx, n.discoverySource)
+
// Subscribe to local address updates to reprovide services and log
sub, err := h.EventBus().Subscribe(new(event.EvtLocalAddressesUpdated))
if err == nil {
diff --git a/internal/node/openai_facade.go b/internal/node/openai_facade.go
index 545637cb..14d90e2c 100644
--- a/internal/node/openai_facade.go
+++ b/internal/node/openai_facade.go
@@ -68,6 +68,10 @@ type openAIFacade struct {
localServices func() []Service
discover func(ctx context.Context) ([]*api.DiscoveredProvider, error)
remoteModels func(ctx context.Context, peerID, srvName string) ([]string, error)
+ // Gossip seams (may be nil): fresh provider knowledge without a probe,
+ // and interest registration so announcements start flowing for a model.
+ viewProviders func(model string) []modelProvider
+ ensureInterest func(model string)
ttl time.Duration
mu sync.Mutex
@@ -96,6 +100,21 @@ func newOpenAIFacade(node *SamNode, egress http.Handler) *openAIFacade {
remoteModels: func(ctx context.Context, peerID, srvName string) ([]string, error) {
return fetchRemoteModels(ctx, node, client, peerID, srvName)
},
+ viewProviders: func(model string) []modelProvider {
+ if node.Discovery == nil {
+ return nil
+ }
+ var out []modelProvider
+ for _, p := range node.Discovery.Providers(api.ServiceType_SERVICE_TYPE_INFERENCE, model) {
+ out = append(out, modelProvider{peerID: p.PeerID, service: p.Service})
+ }
+ return out
+ },
+ ensureInterest: func(model string) {
+ if node.Discovery != nil {
+ node.Discovery.Ensure(api.ServiceType_SERVICE_TYPE_INFERENCE, model)
+ }
+ },
}
}
@@ -132,20 +151,38 @@ func fetchRemoteModels(ctx context.Context, node *SamNode, client *http.Client,
return decodeModelIDs(resp.Body)
}
-// providersFor resolves a model to its providers, force-refreshing once on a
-// miss so newly appeared providers are usable before the TTL lapses.
+// providersFor resolves a model to its providers: registry first (locals
+// preferred), then the gossip view (fresh knowledge without a mesh-wide
+// probe), then one forced registry refresh so newly appeared providers are
+// usable before the TTL lapses. Interest is registered so announcements for
+// this model start flowing.
func (f *openAIFacade) providersFor(ctx context.Context, model string) []modelProvider {
+ if f.ensureInterest != nil {
+ f.ensureInterest(model)
+ }
f.mu.Lock()
- defer f.mu.Unlock()
refreshed := false
if f.staleLocked() {
f.refreshLocked(ctx)
refreshed = true
}
- if providers := f.models[model]; len(providers) > 0 || refreshed {
+ if providers := f.models[model]; len(providers) > 0 {
+ f.mu.Unlock()
return providers
}
- f.refreshLocked(ctx)
+ f.mu.Unlock()
+
+ if f.viewProviders != nil {
+ if providers := f.viewProviders(model); len(providers) > 0 {
+ return providers
+ }
+ }
+
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if !refreshed {
+ f.refreshLocked(ctx)
+ }
return f.models[model]
}
diff --git a/internal/node/openai_facade_test.go b/internal/node/openai_facade_test.go
index beb82eda..462ba237 100644
--- a/internal/node/openai_facade_test.go
+++ b/internal/node/openai_facade_test.go
@@ -302,6 +302,57 @@ func TestFacade_RegistryCacheAndForcedRefresh(t *testing.T) {
}
}
+func TestFacade_GossipViewServesRegistryMiss(t *testing.T) {
+ f := newTestFacade()
+ interestCalls := 0
+ f.ensureInterest = func(model string) { interestCalls++ }
+ f.viewProviders = func(model string) []modelProvider {
+ if model == "m-gossip" {
+ return []modelProvider{{peerID: "peerG", service: "srvG"}}
+ }
+ return nil
+ }
+ var gotPath string
+ f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ })
+
+ req := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m-gossip"}`))
+ f.handleCompletions(httptest.NewRecorder(), req)
+
+ if want := "/sam/peerG/inference/srvG/v1/chat/completions"; gotPath != want {
+ t.Errorf("forwarded path: got %q, want %q", gotPath, want)
+ }
+ if interestCalls != 1 {
+ t.Errorf("ensureInterest calls: got %d, want 1", interestCalls)
+ }
+}
+
+func TestFacade_RegistryHitBeatsGossipView(t *testing.T) {
+ f := newTestFacade()
+ f.discover = func(_ context.Context) ([]*api.DiscoveredProvider, error) {
+ return []*api.DiscoveredProvider{{PeerId: "peerA", SrvName: "srvA"}}, nil
+ }
+ f.remoteModels = func(_ context.Context, _, _ string) ([]string, error) {
+ return []string{"m1"}, nil
+ }
+ f.viewProviders = func(model string) []modelProvider {
+ t.Error("gossip view must not be consulted on a registry hit")
+ return nil
+ }
+ var gotPath string
+ f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ })
+
+ req := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m1"}`))
+ f.handleCompletions(httptest.NewRecorder(), req)
+
+ if want := "/sam/peerA/inference/srvA/v1/chat/completions"; gotPath != want {
+ t.Errorf("forwarded path: got %q, want %q", gotPath, want)
+ }
+}
+
func TestFacade_EmptyRegistryIsNotCached(t *testing.T) {
f := newTestFacade()
discoverCalls := 0
diff --git a/internal/node/options.go b/internal/node/options.go
index e7f4b04a..24a1845b 100644
--- a/internal/node/options.go
+++ b/internal/node/options.go
@@ -58,6 +58,9 @@ type Options struct {
DiscoveryConcurrency int
// RequiredRole restricts enrollment and startup to only accept tokens containing this role.
RequiredRole string
+ // Region is the operator-declared jurisdiction of this node (api.LabelRegion).
+ // Empty means no claim; consumers with a region requirement will not select it.
+ Region string
// PolicySyncInterval specifies how often the node syncs the mesh policy from the control plane.
PolicySyncInterval time.Duration
// PolicySyncJitter specifies the maximum jitter delay when scheduling policy syncs on event broadcasts.
diff --git a/tests/integration/openai_facade_test.go b/tests/integration/openai_facade_test.go
index 2c893f8f..ddd9c852 100644
--- a/tests/integration/openai_facade_test.go
+++ b/tests/integration/openai_facade_test.go
@@ -48,6 +48,7 @@ func TestOpenAIFacadeCUJ(t *testing.T) {
"--listen", "/ip4/127.0.0.1/udp/0/quic-v1",
"--listen", "/ip4/127.0.0.1/tcp/0",
"--discovery-interval", "100ms",
+ "--region", "eu", // exercise the operator region claim end to end
)
t.Log("Starting Node B (consumer)...")
_ = startBackgroundNode(t, nodeBin, hubAddr, homeB,