Document peer-topology header trust boundary and cross-refs

topology-affinity-filter/-scorer trust peerTopologyHeader without
re-verifying its source; call out that it must only be set on a
profile reachable exclusively through the coordinator. Cross-reference
the x-peer-topology literal across its three independent definitions
so a rename in one is discoverable from the others.

Signed-off-by: Etai Lev Ran <elevran@gmail.com>

Author: elevran

pkg/coordinator/gateway/paths.go

@@ -23,7 +23,10 @@ const (
 	PathCompletions     = "/v1/completions"
 	DefaultGeneratePath = "/inference/v1/generate"
 
-	EPPProfileHeader   = "EPP-Profile"
+	EPPProfileHeader = "EPP-Profile"
+	// PeerTopologyHeader must match the default headerName in
+	// pkg/epp/framework/plugins/requestcontrol/responsereceived/topologystamp
+	// and peerTopologyHeaderName in pkg/epp/util/request/headers.go.
 	PeerTopologyHeader = "x-peer-topology"
 	ContentTypeHeader  = "Content-Type"
 	ContentTypeJSON    = "application/json"

pkg/epp/framework/plugins/requestcontrol/responsereceived/topologystamp/stamp.go

@@ -37,7 +37,9 @@ const PluginType = "topology-stamp-handler"
 
 // defaultHeaderName is the response header the encoded topology is written
 // to, and the header topology-affinity-filter/-scorer read the peer topology
-// from in coordinator deployments.
+// from in coordinator deployments. Must match gateway.PeerTopologyHeader in
+// pkg/coordinator/gateway and peerTopologyHeaderName in
+// pkg/epp/util/request/headers.go.
 const defaultHeaderName = "x-peer-topology"
 
 type parameters struct {

pkg/epp/framework/plugins/scheduling/filter/topologyaffinity/README.md

@@ -64,6 +64,10 @@ attribute is absent.
 | `topologyProducerName`   | no       | default producer | `topology-extractor` instance to read the `Topology` attribute from.        |
 | `peerTopologyHeader`     | no       | unset   | Request header carrying the peer topology in coordinator deployments. Set to `x-peer-topology` when running in a decode EPP behind the coordinator; unused in single-EPP deployments. |
 
+The plugin trusts `peerTopologyHeader` without re-verifying its source. Only set it on a
+profile reachable exclusively through the coordinator's forwarded header; a decode EPP
+reachable directly by a client would let that client spoof its own peer topology.
+
 **Configuration Example, single EPP:**
 ```yaml
 plugins:

pkg/epp/framework/plugins/scheduling/scorer/topologyaffinity/README.md

@@ -86,6 +86,10 @@ attribute is absent.
 | `topologyProducerName`   | no       | default producer | `topology-extractor` instance to read the `Topology` attribute from. |
 | `peerTopologyHeader`     | no       | unset   | Request header carrying the peer topology in coordinator deployments. Set to `x-peer-topology` when running in a decode EPP behind the coordinator; unused in single-EPP deployments. |
 
+The plugin trusts `peerTopologyHeader` without re-verifying its source. Only set it on a
+profile reachable exclusively through the coordinator's forwarded header; a decode EPP
+reachable directly by a client would let that client spoof its own peer topology.
+
 **Configuration Example, single EPP:**
 ```yaml
 plugins:

pkg/epp/util/request/headers.go

@@ -28,7 +28,10 @@ import (
 // peerTopologyHeaderName is the coordinator's cross-EPP header carrying the
 // prefill endpoint's topology to the decode EPP. A client-supplied value must
 // not reach the backend, since topology-affinity-filter and
-// topology-affinity-scorer trust it as the peer to compare against.
+// topology-affinity-scorer trust it as the peer to compare against. Must
+// match gateway.PeerTopologyHeader in pkg/coordinator/gateway and
+// defaultHeaderName in
+// pkg/epp/framework/plugins/requestcontrol/responsereceived/topologystamp.
 const peerTopologyHeaderName = "x-peer-topology"
 
 var (