feat(extension-server): report the protections the edge was told to run

Adds a read-only endpoint that reports the set of firewall and connector
protections the platform handed to the edge. Read-only and off the traffic
path; it observes configuration and never touches live requests. This is the
reference point for later confirming the edge runs exactly what it was given.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JbCy8vy66RdNYzGSgqH6P6

Author: scotwells

internal/extensionserver/cmd/run.go

@@ -450,6 +450,9 @@ func run(o options) {
 		}
 	})
 	mux.Handle("/metrics", promhttp.Handler())
+	// Debug endpoint that reports what the last build changed, so a test can
+	// confirm the proxy is running exactly that. Read-only; keeps only the last build.
+	mux.HandleFunc(extserver.ProgrammedSetEndpointPath, extSrv.ProgrammedSetHandler())
 	healthServer := &http.Server{
 		Addr:    healthAddr,
 		Handler: mux,

internal/extensionserver/server/programmedset.go

@@ -0,0 +1,192 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"sync"
+	"time"
+
+	clusterv3 "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3"
+	listenerv3 "github.com/envoyproxy/go-control-plane/envoy/config/listener/v3"
+	routev3 "github.com/envoyproxy/go-control-plane/envoy/config/route/v3"
+	hcmv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/http_connection_manager/v3"
+)
+
+// programmedSetEndpointPath is a read-only debug endpoint that reports the exact
+// set of changes the last build intended to make, so a test can confirm the
+// proxy is running that set and not merely the right number of things.
+const programmedSetEndpointPath = "/debug/programmed-set"
+
+// Marker strings, kept in sync with where the configuration is written, used to
+// recognize each change when reading the configuration back.
+const (
+	datumGatewayMetaKey        = "datum-gateway"
+	connectorInternalTransport = "envoy.transport_sockets.internal_upstream"
+	hcmNetworkFilterName       = "envoy.filters.network.http_connection_manager"
+)
+
+// Family names a kind of change recorded in a snapshot. The strings are stable
+// JSON keys the parity test depends on; do not rename.
+type Family string
+
+const (
+	FamilyWAFRoute         Family = "waf_route"
+	FamilyWAFHCM           Family = "waf_hcm"
+	FamilyLocalReply       Family = "local_reply"
+	FamilyConnectorCluster Family = "connector_cluster"
+	FamilyConnectorRoute   Family = "connector_route"
+	FamilyConnectorOffline Family = "connector_offline"
+	FamilyTLSPrune         Family = "tls_prune"
+)
+
+// ProgrammedSet is a snapshot of one build's intended changes. It is served as
+// JSON and read back by the parity test.
+type ProgrammedSet struct {
+	// BuildID increments once per build so a caller can tell two successive
+	// snapshots apart and know a fresh build has happened.
+	BuildID uint64 `json:"buildID"`
+	// CapturedAt is when the snapshot was recorded.
+	CapturedAt time.Time `json:"capturedAt"`
+	// Keys is, per kind of change, the identity of each thing changed. Each value
+	// is sorted and de-duplicated. The identity format is described on the
+	// record helpers below and mirrored by the parity test.
+	Keys map[Family][]string `json:"keys"`
+	// Counts holds the size of each set in Keys, plus the removed-certificate
+	// outcomes below that have no per-item identity. Used as a secondary check.
+	Counts map[Family]int `json:"counts"`
+	// Removing invalid TLS certificates is confirmed by counting outcomes rather
+	// than by identity, so the raw numbers are carried here.
+	TLSPrunedChains        int `json:"tlsPrunedChains"`
+	TLSPrunedSecrets       int `json:"tlsPrunedSecrets"`
+	TLSListenersLeftIntact int `json:"tlsListenersLeftIntact"`
+}
+
+// programmedRecorder holds the most recent snapshot under a lock, shared between
+// the build that writes it and the endpoint that reads it. Only the last build
+// is kept; each recording replaces the previous one.
+type programmedRecorder struct {
+	mu      sync.RWMutex
+	buildID uint64
+	last    *ProgrammedSet
+}
+
+// newProgrammedRecorder returns an empty recorder. Before the first build it
+// reports a valid empty snapshot with a zero build count, so callers can tell
+// "no build yet" from a real build.
+func newProgrammedRecorder() *programmedRecorder {
+	return &programmedRecorder{}
+}
+
+// snapshot returns the last recorded set, or an empty one if no build has run.
+// The returned value is a copy safe to serialize without the lock.
+func (r *programmedRecorder) snapshot() ProgrammedSet {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	if r.last == nil {
+		return ProgrammedSet{Keys: map[Family][]string{}, Counts: map[Family]int{}}
+	}
+	return *r.last
+}
+
+// record reads the configuration the build just produced and stores a snapshot
+// of it. It only reads, never changes the configuration, and holds the write
+// lock just long enough to store the result so it doesn't slow the build.
+func (r *programmedRecorder) record(
+	listeners []*listenerv3.Listener,
+	routes []*routev3.RouteConfiguration,
+	clusters []*clusterv3.Cluster,
+	corazaFilterName string,
+	tlsPrunedChains, tlsPrunedSecrets, tlsListenersLeftIntact int,
+) {
+	ps := buildProgrammedSet(listeners, routes, clusters, corazaFilterName,
+		tlsPrunedChains, tlsPrunedSecrets, tlsListenersLeftIntact)
+
+	r.mu.Lock()
+	r.buildID++
+	ps.BuildID = r.buildID
+	r.last = &ps
+	r.mu.Unlock()
+}
+
+// buildProgrammedSet walks the produced configuration and extracts an identity
+// for each change. It is a pure function so it can be unit tested directly. The
+// identity formats must match what the parity test looks for; keep both sides
+// in lockstep.
+func buildProgrammedSet(
+	listeners []*listenerv3.Listener,
+	routes []*routev3.RouteConfiguration,
+	clusters []*clusterv3.Cluster,
+	corazaFilterName string,
+	tlsPrunedChains, tlsPrunedSecrets, tlsListenersLeftIntact int,
+) ProgrammedSet {
+	keys := map[Family][]string{}
+	add := func(f Family, k string) { keys[f] = append(keys[f], k) }
+
+	for _, rc := range routes {
+		rcName := rc.GetName()
+		for _, vh := range rc.GetVirtualHosts() {
+			vhName := vh.GetName()
+			for _, rt := range vh.GetRoutes() {
+				// The identity includes the protection policy governing the route,
+				// so a route protected by the wrong policy shows up as a mismatch.
+				if ns, name, mode, ok := datumGatewayTPP(rt); ok {
+					add(FamilyWAFRoute, wafRouteKey(rcName, vhName, rt.GetName(), ns, name, mode))
+				}
+				if isConnectRoute(rt) {
+					add(FamilyConnectorRoute, connectorRouteKey(rcName, vhName, rt.GetName()))
+				}
+				if isOfflineDirectResponse(rt) {
+					add(FamilyConnectorOffline, connectorRouteKey(rcName, vhName, rt.GetName()))
+				}
+			}
+		}
+	}
+
+	for _, cl := range clusters {
+		if isReplacedConnectorCluster(cl) {
+			add(FamilyConnectorCluster, cl.GetName())
+		}
+	}
+
+	for _, l := range listeners {
+		lName := l.GetName()
+		eachHCM(l, func(fcName string, hcm *hcmv3.HttpConnectionManager) {
+			if corazaFilterName != "" && hcmHasFilterAtZero(hcm, corazaFilterName) {
+				add(FamilyWAFHCM, listenerChainKey(lName, fcName))
+			}
+			if hcm.GetLocalReplyConfig() != nil {
+				add(FamilyLocalReply, listenerChainKey(lName, fcName))
+			}
+		})
+	}
+
+	// Sort and de-duplicate so the output can be compared as a set.
+	counts := map[Family]int{}
+	for f := range keys {
+		keys[f] = sortDedup(keys[f])
+		counts[f] = len(keys[f])
+	}
+	// Removed certificates are recorded by count, since they have no identity.
+	counts[FamilyTLSPrune] = tlsPrunedChains
+
+	return ProgrammedSet{
+		CapturedAt:             time.Now().UTC(),
+		Keys:                   keys,
+		Counts:                 counts,
+		TLSPrunedChains:        tlsPrunedChains,
+		TLSPrunedSecrets:       tlsPrunedSecrets,
+		TLSListenersLeftIntact: tlsListenersLeftIntact,
+	}
+}
+
+// programmedSetHandler serves the latest snapshot as JSON. It is a read-only,
+// test-only debug endpoint and returns an empty snapshot before the first build.
+func (r *programmedRecorder) programmedSetHandler() http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		ps := r.snapshot()
+		w.Header().Set("Content-Type", "application/json")
+		enc := json.NewEncoder(w)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(ps)
+	}
+}

internal/extensionserver/server/programmedset_scan.go

@@ -0,0 +1,160 @@
+package server
+
+import (
+	"sort"
+	"strings"
+
+	clusterv3 "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3"
+	listenerv3 "github.com/envoyproxy/go-control-plane/envoy/config/listener/v3"
+	routev3 "github.com/envoyproxy/go-control-plane/envoy/config/route/v3"
+	hcmv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/http_connection_manager/v3"
+)
+
+// These read-only scanners extract an identity for each change the build made.
+// They mirror, in reverse, how the configuration is written, and they define
+// the exact identity format the parity test must reproduce. The "##" separator
+// is used because it cannot appear in any of the names it joins.
+
+const keySep = "##"
+
+// wafRouteKey is the identity of a route protected by a firewall:
+//
+//	<routeConfig>##<virtualHost>##<routeName>##<policyNamespace>/<policyName>/<mode>
+//
+// The governing policy is part of the identity, so a route protected by the
+// wrong policy produces a different identity and is caught as a mismatch.
+func wafRouteKey(rc, vh, rt, tppNS, tppName, mode string) string {
+	return strings.Join([]string{rc, vh, rt, tppNS + "/" + tppName + "/" + mode}, keySep)
+}
+
+// connectorRouteKey is the identity of a connector route (online or offline):
+//
+//	<routeConfig>##<virtualHost>##<routeName>
+func connectorRouteKey(rc, vh, rt string) string {
+	return strings.Join([]string{rc, vh, rt}, keySep)
+}
+
+// listenerChainKey is the identity of a changed listener filter chain:
+//
+//	<listenerName>##<filterChainName>
+func listenerChainKey(listener, chain string) string {
+	return strings.Join([]string{listener, chain}, keySep)
+}
+
+// datumGatewayTPP returns the protection policy governing a route (namespace,
+// name, mode). ok is false when the route carries no such marker, meaning it is
+// not protected.
+func datumGatewayTPP(rt *routev3.Route) (ns, name, mode string, ok bool) {
+	md := rt.GetMetadata()
+	if md == nil {
+		return "", "", "", false
+	}
+	dg := md.GetFilterMetadata()[datumGatewayMetaKey]
+	if dg == nil {
+		return "", "", "", false
+	}
+	res := dg.GetFields()["resources"].GetListValue()
+	if res == nil || len(res.GetValues()) == 0 {
+		return "", "", "", false
+	}
+	f := res.GetValues()[0].GetStructValue().GetFields()
+	return f["namespace"].GetStringValue(),
+		f["name"].GetStringValue(),
+		f["mode"].GetStringValue(),
+		true
+}
+
+// isConnectRoute reports whether a route is an online connector tunnel route.
+func isConnectRoute(rt *routev3.Route) bool {
+	ra := rt.GetRoute()
+	if ra == nil {
+		return false
+	}
+	for _, uc := range ra.GetUpgradeConfigs() {
+		if strings.EqualFold(uc.GetUpgradeType(), "CONNECT") {
+			return true
+		}
+	}
+	return false
+}
+
+// isOfflineDirectResponse reports whether a route directly returns the
+// tunnel-offline 503 response, covering both the dedicated offline route and
+// user-facing routes rewritten to it.
+func isOfflineDirectResponse(rt *routev3.Route) bool {
+	dr := rt.GetDirectResponse()
+	if dr == nil {
+		return false
+	}
+	if dr.GetStatus() != 503 {
+		return false
+	}
+	return dr.GetBody().GetInlineString() == offlineBodyMarker
+}
+
+// offlineBodyMarker is the response body the connector offline path writes,
+// duplicated here so the scanner needs no import dependency.
+const offlineBodyMarker = "Tunnel not online"
+
+// isReplacedConnectorCluster reports whether a connector cluster has been
+// replaced with its tunnel form. A cluster that has not been replaced means the
+// substitution failed.
+func isReplacedConnectorCluster(cl *clusterv3.Cluster) bool {
+	if cl.GetType() != clusterv3.Cluster_STATIC {
+		return false
+	}
+	return cl.GetTransportSocket().GetName() == connectorInternalTransport
+}
+
+// eachHCM invokes fn for every connection manager across all of the listener's
+// filter chains, including the default chain. One that can't be decoded is
+// skipped, since recording must never fail the build.
+func eachHCM(l *listenerv3.Listener, fn func(chainName string, hcm *hcmv3.HttpConnectionManager)) {
+	chains := make([]*listenerv3.FilterChain, 0, len(l.GetFilterChains())+1)
+	chains = append(chains, l.GetFilterChains()...)
+	if dfc := l.GetDefaultFilterChain(); dfc != nil {
+		chains = append(chains, dfc)
+	}
+	for _, fc := range chains {
+		for _, f := range fc.GetFilters() {
+			if f.GetName() != hcmNetworkFilterName {
+				continue
+			}
+			tc := f.GetTypedConfig()
+			if tc == nil {
+				continue
+			}
+			hcm := &hcmv3.HttpConnectionManager{}
+			if err := tc.UnmarshalTo(hcm); err != nil {
+				continue
+			}
+			fn(fc.GetName(), hcm)
+		}
+	}
+}
+
+// hcmHasFilterAtZero reports whether the first filter is named filterName. The
+// firewall is always inserted first, so checking the first position is the
+// precise signal that it was injected.
+func hcmHasFilterAtZero(hcm *hcmv3.HttpConnectionManager, filterName string) bool {
+	fs := hcm.GetHttpFilters()
+	return len(fs) > 0 && fs[0].GetName() == filterName
+}
+
+// sortDedup returns a sorted, de-duplicated copy of in.
+func sortDedup(in []string) []string {
+	if len(in) == 0 {
+		return in
+	}
+	seen := make(map[string]struct{}, len(in))
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	sort.Strings(out)
+	return out
+}