feat: implement DumpState for file-discovery

Expose the set of endpoints currently loaded from the discovery file through
/debug/plugins/state. Only the endpoint identities are reported, sorted and
capped so the payload stays bounded; addresses and labels are left out.

DumpState reads the endpoint set concurrently with file reloads, so a read-write
mutex now guards it and load swaps the set under the lock.

Part of #1755.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

Author: thc1006

pkg/epp/framework/plugins/datalayer/discovery/file/plugin.go

@@ -26,6 +26,7 @@ import (
 	"io"
 	"net"
 	"os"
+	"sort"
 	"strconv"
 	"sync"
 
@@ -71,6 +72,8 @@ type FileDiscovery struct {
 	typedName fwkplugin.TypedName
 	path      string
 	watchFile bool
+	// mu guards endpoints, which DumpState reads concurrently with load.
+	mu sync.RWMutex
 	// endpoints is the set of endpoint identities applied to the datastore
 	// from the last successful load. Used as a key set only -- values are
 	// zero-byte structs. Compared against the entries parsed during a
@@ -81,7 +84,10 @@ type FileDiscovery struct {
 	readyOnce sync.Once
 }
 
-var _ fwkdl.EndpointDiscovery = (*FileDiscovery)(nil)
+var (
+	_ fwkdl.EndpointDiscovery = (*FileDiscovery)(nil)
+	_ fwkplugin.StateDumper   = (*FileDiscovery)(nil)
+)
 
 // Factory is the plugin factory for file-discovery.
 func Factory(name string, parameters *json.Decoder, _ fwkplugin.Handle) (fwkplugin.Plugin, error) {
@@ -108,6 +114,40 @@ func Factory(name string, parameters *json.Decoder, _ fwkplugin.Handle) (fwkplug
 
 func (f *FileDiscovery) TypedName() fwkplugin.TypedName { return f.typedName }
 
+const maxDebugDumpEndpoints = 100
+
+// discoveryState is the sanitized snapshot returned by DumpState: discovered
+// endpoint identities only, never their addresses or labels. The dump is partial
+// when TotalEndpoints exceeds MaxEndpoints.
+type discoveryState struct {
+	Endpoints      []string `json:"endpoints"`
+	TotalEndpoints int      `json:"totalEndpoints"`
+	MaxEndpoints   int      `json:"maxEndpoints"`
+}
+
+// DumpState reports the endpoint identities currently loaded from the file,
+// sorted and capped to maxDebugDumpEndpoints so the payload stays bounded. The
+// set is snapshotted under a read lock, so a concurrent reload may not yet be
+// reflected; best-effort visibility is enough for a debug endpoint.
+func (f *FileDiscovery) DumpState() (json.RawMessage, error) {
+	f.mu.RLock()
+	names := make([]string, 0, len(f.endpoints))
+	for id := range f.endpoints {
+		names = append(names, id.String())
+	}
+	f.mu.RUnlock()
+
+	total := len(names)
+	sort.Strings(names)
+
+	state := discoveryState{TotalEndpoints: total, MaxEndpoints: maxDebugDumpEndpoints}
+	if len(names) > maxDebugDumpEndpoints {
+		names = names[:maxDebugDumpEndpoints]
+	}
+	state.Endpoints = names
+	return json.Marshal(state)
+}
+
 // Ready returns a channel closed after the first successful load of the
 // endpoints file. See EndpointDiscovery.Ready for the contract.
 func (f *FileDiscovery) Ready() <-chan struct{} { return f.ready }
@@ -222,11 +262,15 @@ func (f *FileDiscovery) load(notifier fwkdl.DiscoveryNotifier) error {
 		notifier.Upsert(meta)
 	}
 
-	for id := range f.endpoints {
+	f.mu.Lock()
+	old := f.endpoints
+	f.endpoints = incoming
+	f.mu.Unlock()
+
+	for id := range old {
 		if _, ok := incoming[id]; !ok {
 			notifier.Delete(id)
 		}
 	}
-	f.endpoints = incoming
 	return errors.Join(errs...)
 }

pkg/epp/framework/plugins/datalayer/discovery/file/plugin_test.go

@@ -19,6 +19,7 @@ package file
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"os"
 	"strings"
 	"sync"
@@ -292,3 +293,82 @@ endpoints:
 	cancel()
 	assert.NoError(t, <-done)
 }
+
+func TestDumpState(t *testing.T) {
+	f := &FileDiscovery{
+		endpoints: map[types.NamespacedName]struct{}{
+			{Namespace: "default", Name: "pod-b"}: {},
+			{Namespace: "default", Name: "pod-a"}: {},
+		},
+	}
+
+	payload, err := f.DumpState()
+	require.NoError(t, err)
+
+	var state discoveryState
+	require.NoError(t, json.Unmarshal(payload, &state))
+	assert.Equal(t, []string{"default/pod-a", "default/pod-b"}, state.Endpoints)
+	assert.Equal(t, 2, state.TotalEndpoints)
+	assert.Equal(t, maxDebugDumpEndpoints, state.MaxEndpoints)
+	// The full set fits, so the dump is complete (TotalEndpoints does not exceed MaxEndpoints).
+	assert.LessOrEqual(t, state.TotalEndpoints, state.MaxEndpoints)
+}
+
+func TestDumpStateCaps(t *testing.T) {
+	eps := make(map[types.NamespacedName]struct{}, maxDebugDumpEndpoints+5)
+	for i := 0; i < maxDebugDumpEndpoints+5; i++ {
+		eps[types.NamespacedName{Namespace: "default", Name: fmt.Sprintf("pod-%03d", i)}] = struct{}{}
+	}
+	f := &FileDiscovery{endpoints: eps}
+
+	payload, err := f.DumpState()
+	require.NoError(t, err)
+
+	var state discoveryState
+	require.NoError(t, json.Unmarshal(payload, &state))
+	// The dump is partial: TotalEndpoints exceeds the returned count, capped at MaxEndpoints.
+	assert.Equal(t, maxDebugDumpEndpoints+5, state.TotalEndpoints)
+	assert.Greater(t, state.TotalEndpoints, state.MaxEndpoints)
+	assert.Len(t, state.Endpoints, maxDebugDumpEndpoints)
+	// Sorted ascending, then capped, so the first maxDebugDumpEndpoints names are kept.
+	assert.Equal(t, "default/pod-000", state.Endpoints[0])
+	assert.Equal(t, fmt.Sprintf("default/pod-%03d", maxDebugDumpEndpoints-1), state.Endpoints[maxDebugDumpEndpoints-1])
+}
+
+func TestDumpStateConcurrentWithLoad(t *testing.T) {
+	path := writeTemp(t, "endpoints:\n- name: ep1\n  address: 10.0.0.1\n  port: \"8000\"\n")
+	f := &FileDiscovery{path: path, endpoints: map[types.NamespacedName]struct{}{}}
+	notifier := &recordingNotifier{}
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 100; i++ {
+			_ = f.load(notifier)
+		}
+	}()
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 100; i++ {
+			if _, err := f.DumpState(); err != nil {
+				t.Errorf("DumpState returned error: %v", err)
+			}
+		}
+	}()
+	wg.Wait()
+}
+
+func TestDumpStateEmpty(t *testing.T) {
+	f := &FileDiscovery{endpoints: map[types.NamespacedName]struct{}{}}
+
+	payload, err := f.DumpState()
+	require.NoError(t, err)
+	assert.True(t, json.Valid(payload))
+
+	var state discoveryState
+	require.NoError(t, json.Unmarshal(payload, &state))
+	assert.Empty(t, state.Endpoints)
+	assert.Equal(t, 0, state.TotalEndpoints)
+	assert.Equal(t, maxDebugDumpEndpoints, state.MaxEndpoints)
+}