Gate the programmed-set debug endpoint to the test environment

The endpoint that reports what the last build intended to change exists only
so a test can confirm the proxy is running exactly that set. Serve it (and do
the per-build recording that backs it) only when NSO_DEBUG_PROGRAMMED_SET is
set, so production exposes nothing and does no extra work on the build path.

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

@@ -258,6 +258,9 @@ func run(o options) {
 		ConnectorInternalListener: serverConfig.Gateway.ConnectorTunnelListenerName(),
 		CorazaRouteBaseDirectives: coraza.RouteBaseDirectives,
 		LocalReply:                buildLocalReplyConfig(serverConfig.Gateway.ErrorPage, log),
+		// The programmed-set debug endpoint is for the test environment only; it
+		// stays off in production unless NSO_DEBUG_PROGRAMMED_SET is set.
+		EnableProgrammedSet: envBool("NSO_DEBUG_PROGRAMMED_SET", false),
 	}
 
 	// --- gRPC panic recovery interceptor ---
@@ -450,9 +453,12 @@ 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())
+	// Read-only debug endpoint that reports what the last build changed, so a test
+	// can confirm the proxy is running exactly that. Test environment only; it is
+	// not served in production. Keeps only the last build.
+	if srvCfg.EnableProgrammedSet {
+		mux.HandleFunc(extserver.ProgrammedSetEndpointPath, extSrv.ProgrammedSetHandler())
+	}
 	healthServer := &http.Server{
 		Addr:    healthAddr,
 		Handler: mux,

internal/extensionserver/server/programmedset_test.go

@@ -306,7 +306,10 @@ func TestPostTranslateModify_RecordsProgrammedSet(t *testing.T) {
 	cl := fake.NewClientBuilder().WithScheme(scheme).
 		WithObjects(ns, tpp, proxy).
 		WithStatusSubresource(connector).WithObjects(connector).Build()
-	srv := New(cl, testServerConfig(), discardLogger())
+	// Recording only happens when the test-environment endpoint is enabled.
+	cfg := testServerConfig()
+	cfg.EnableProgrammedSet = true
+	srv := New(cl, cfg, discardLogger())
 
 	req := &pb.PostTranslateModifyRequest{
 		Clusters: []*clusterv3.Cluster{{Name: connCluster}, {Name: "infra-cluster"}},
@@ -342,3 +345,19 @@ func TestPostTranslateModify_RecordsProgrammedSet(t *testing.T) {
 	require.Len(t, ps.Keys[FamilyWAFRoute], 1)
 	assert.Contains(t, ps.Keys[FamilyWAFRoute][0], "test-project/test-tpp/Observe")
 }
+
+// TestPostTranslateModify_NoRecordingWhenDisabled proves the production default:
+// with the test-only endpoint off, a build records nothing, so the snapshot
+// stays empty and no per-build work is done.
+func TestPostTranslateModify_NoRecordingWhenDisabled(t *testing.T) {
+	cl := fake.NewClientBuilder().WithScheme(testServerScheme(t)).Build()
+	// testServerConfig() leaves EnableProgrammedSet at its false default.
+	srv := New(cl, testServerConfig(), discardLogger())
+
+	_, err := srv.PostTranslateModify(context.Background(), &pb.PostTranslateModifyRequest{})
+	require.NoError(t, err)
+
+	ps := srv.programmed.snapshot()
+	assert.Equal(t, uint64(0), ps.BuildID, "no build was recorded")
+	assert.Empty(t, ps.Keys, "nothing recorded while the endpoint is disabled")
+}

internal/extensionserver/server/server.go

@@ -37,6 +37,12 @@ type ServerConfig struct {
 	// empty, local-reply injection is a no-op. Sourced from
 	// GatewayConfig.ErrorPage + the embedded/override HTML body.
 	LocalReply mutate.LocalReplyConfig
+	// EnableProgrammedSet turns on the read-only /debug/programmed-set endpoint
+	// and the per-build recording that backs it. It exists only to let a test
+	// confirm the proxy is running exactly the set the build intended, so it is
+	// off in production and enabled only in the test environment. When off, the
+	// build does no extra work and the endpoint is not served.
+	EnableProgrammedSet bool
 }
 
 // Server implements pb.EnvoyGatewayExtensionServer for the NSO production
@@ -332,13 +338,15 @@ func (s *Server) PostTranslateModify(
 	extmetrics.ConnectorRoutesTotal.Add(float64(vhCount))
 	extmetrics.ConnectorOfflineRoutesTotal.Add(float64(offlineRtCount))
 
-	// Record what this build changed so a test can later confirm the proxy is
-	// running exactly that. This only reads the configuration just produced; it
-	// changes nothing.
-	s.programmed.record(
-		listeners, routes, clusters, s.cfg.Coraza.FilterName,
-		prunedChains, prunedSecrets, listenersLeftIntact,
-	)
+	// In the test environment, record what this build changed so a test can later
+	// confirm the proxy is running exactly that. This only reads the configuration
+	// just produced; it changes nothing. Off in production, where it does no work.
+	if s.cfg.EnableProgrammedSet {
+		s.programmed.record(
+			listeners, routes, clusters, s.cfg.Coraza.FilterName,
+			prunedChains, prunedSecrets, listenersLeftIntact,
+		)
+	}
 
 	s.log.Info("PostTranslateModify",
 		"clusters", len(clusters),