[Refactor] use the framework types directly instead of the aliased name (#2603)

* use fwkdl.Endpoint instead of metrics.PodMetrics outside of backend/metrics

Signed-off-by: mohamedmahameed <mohamed.mahameed@ibm.com>

* Remove PodMetrics type alias, renames and code enhancements

Signed-off-by: mohamedmahameed <mohamed.mahameed@ibm.com>

* fix detecetor_test.go to use new functions names

Signed-off-by: mohamedmahameed <mohamed.mahameed@ibm.com>

---------

Signed-off-by: mohamedmahameed <mohamed.mahameed@ibm.com>
Signed-off-by: Cyclinder Kuo <qifeng.guo@daocloud.io>

Author: Mohamedma96

cmd/epp/runner/runner.go

@@ -331,10 +331,10 @@ func (r *Runner) setup(ctx context.Context, cfg *rest.Config, opts *runserver.Op
 
 	// --- Admission Control Initialization ---
 	var admissionController requestcontrol.AdmissionController
-	var locator contracts.PodLocator
-	locator = requestcontrol.NewDatastorePodLocator(ds, requestcontrol.WithDisableEndpointSubsetFilter(opts.DisableEndpointSubsetFilter))
+	var endpointCandidates contracts.EndpointCandidates
+	endpointCandidates = requestcontrol.NewDatastoreEndpointCandidates(ds, requestcontrol.WithDisableEndpointSubsetFilter(opts.DisableEndpointSubsetFilter))
 	if r.featureGates[flowcontrol.FeatureGate] {
-		locator = requestcontrol.NewCachedPodLocator(ctx, locator, time.Millisecond*50)
+		endpointCandidates = requestcontrol.NewCachedEndpointCandidates(ctx, endpointCandidates, time.Millisecond*50)
 		setupLog.Info("Initializing experimental Flow Control layer")
 		registry, err := fcregistry.NewFlowRegistry(eppConfig.FlowControlConfig.Registry, setupLog)
 		if err != nil {
@@ -345,7 +345,7 @@ func (r *Runner) setup(ctx context.Context, cfg *rest.Config, opts *runserver.Op
 			opts.PoolName,
 			eppConfig.FlowControlConfig.Controller,
 			registry, saturationDetector,
-			locator,
+			endpointCandidates,
 		)
 		if err != nil {
 			return nil, nil, fmt.Errorf("failed to initialize Flow Controller: %w", err)
@@ -354,10 +354,10 @@ func (r *Runner) setup(ctx context.Context, cfg *rest.Config, opts *runserver.Op
 		admissionController = requestcontrol.NewFlowControlAdmissionController(fc, opts.PoolName)
 	} else {
 		setupLog.Info("Experimental Flow Control layer is disabled, using legacy admission control")
-		admissionController = requestcontrol.NewLegacyAdmissionController(saturationDetector, locator)
+		admissionController = requestcontrol.NewLegacyAdmissionController(saturationDetector, endpointCandidates)
 	}
 
-	director := requestcontrol.NewDirectorWithConfig(ds, scheduler, admissionController, r.parser, locator, r.requestControlConfig)
+	director := requestcontrol.NewDirectorWithConfig(ds, scheduler, admissionController, r.parser, endpointCandidates, r.requestControlConfig)
 
 	// --- Setup ExtProc Server Runner ---
 	serverRunner := &runserver.ExtProcServerRunner{

pkg/epp/flowcontrol/contracts/dependencies.go

@@ -22,13 +22,13 @@ import (
 	fwkdl "sigs.k8s.io/gateway-api-inference-extension/pkg/epp/framework/interface/datalayer"
 )
 
-// PodLocator defines the contract for a component that resolves the set of candidate pods for a request based on its
-// metadata (e.g., subsetting).
+// EndpointCandidates defines the contract for a component that resolves the set of candidate endpoints for a request
+// based on its metadata (e.g., subsetting).
 //
-// This interface allows the Flow Controller to fetch a fresh list of pods dynamically during the dispatch cycle,
-// enabling support for "Scale-from-Zero" scenarios where pods may not exist when the request is first enqueued.
-type PodLocator interface {
-	// Locate returns a list of pod metrics that match the criteria defined in the request metadata.
+// This interface allows the Flow Controller to fetch a fresh list of candidates dynamically during the dispatch cycle,
+// enabling support for "Scale-from-Zero" scenarios where endpoints may not exist when the request is first enqueued.
+type EndpointCandidates interface {
+	// Locate returns a list of endpoint candidate metrics that match the criteria defined in the request metadata.
 	Locate(ctx context.Context, requestMetadata map[string]any) []fwkdl.Endpoint
 }
 

pkg/epp/flowcontrol/contracts/mocks/mocks.go

@@ -120,25 +120,26 @@ func (m *MockSaturationDetector) Saturation(ctx context.Context, candidatePods [
 	return 0.0
 }
 
-// MockPodLocator provides a mock implementation of the contracts.PodLocator interface.
-// It allows tests to control the exact set of pods returned for a given request.
-type MockPodLocator struct {
+// MockEndpointCandidates provides a mock implementation of the contracts.EndpointCandidates interface.
+// It allows tests to control the exact set of endpoint candidates returned for a given request.
+type MockEndpointCandidates struct {
 	// LocateFunc allows injecting custom logic.
 	LocateFunc func(ctx context.Context, requestMetadata map[string]any) []fwkdl.Endpoint
-	// Pods is a static return value used if LocateFunc is nil.
-	Pods []fwkdl.Endpoint
+	// Candidates is a static return value used if LocateFunc is nil.
+	Candidates []fwkdl.Endpoint
 }
 
-func (m *MockPodLocator) Locate(ctx context.Context, requestMetadata map[string]any) []fwkdl.Endpoint {
+func (m *MockEndpointCandidates) Locate(ctx context.Context, requestMetadata map[string]any) []fwkdl.Endpoint {
 	if m.LocateFunc != nil {
 		return m.LocateFunc(ctx, requestMetadata)
 	}
 	// Return copy to be safe
-	if m.Pods == nil {
+	if m.Candidates == nil {
 		return nil
 	}
-	result := make([]fwkdl.Endpoint, len(m.Pods))
-	copy(result, m.Pods)
+
+	result := make([]fwkdl.Endpoint, len(m.Candidates))
+	copy(result, m.Candidates)
 	return result
 }
 

pkg/epp/flowcontrol/controller/controller.go

@@ -63,7 +63,7 @@ type shardProcessorFactory func(
 	ctx context.Context,
 	shard contracts.RegistryShard,
 	saturationDetector contracts.SaturationDetector,
-	podLocator contracts.PodLocator,
+	endpointCandidates contracts.EndpointCandidates,
 	clock clock.WithTicker,
 	cleanupSweepInterval time.Duration,
 	enqueueChannelBufferSize int,
@@ -99,7 +99,7 @@ type FlowController struct {
 	config                *Config
 	registry              registryClient
 	saturationDetector    contracts.SaturationDetector
-	podLocator            contracts.PodLocator
+	endpointCandidates    contracts.EndpointCandidates
 	clock                 clock.WithTicker
 	logger                logr.Logger
 	shardProcessorFactory shardProcessorFactory
@@ -132,14 +132,14 @@ func NewFlowController(
 	config *Config,
 	registry contracts.FlowRegistry,
 	sd contracts.SaturationDetector,
-	podLocator contracts.PodLocator,
+	endpointCandidates contracts.EndpointCandidates,
 	opts ...flowControllerOption,
 ) (*FlowController, error) {
 	fc := &FlowController{
 		config:             config,
 		registry:           registry,
 		saturationDetector: sd,
-		podLocator:         podLocator,
+		endpointCandidates: endpointCandidates,
 		clock:              clock.RealClock{},
 		logger:             log.FromContext(ctx).WithName("flow-controller"),
 		parentCtx:          ctx,
@@ -149,7 +149,7 @@ func NewFlowController(
 		ctx context.Context,
 		shard contracts.RegistryShard,
 		saturationDetector contracts.SaturationDetector,
-		podLocator contracts.PodLocator,
+		endpointCandidates contracts.EndpointCandidates,
 		clock clock.WithTicker,
 		cleanupSweepInterval time.Duration,
 		enqueueChannelBufferSize int,
@@ -160,7 +160,7 @@ func NewFlowController(
 			poolName,
 			shard,
 			saturationDetector,
-			podLocator,
+			endpointCandidates,
 			clock,
 			cleanupSweepInterval,
 			enqueueChannelBufferSize,
@@ -486,7 +486,7 @@ func (fc *FlowController) getOrStartWorker(shard contracts.RegistryShard) *manag
 		processorCtx,
 		shard,
 		fc.saturationDetector,
-		fc.podLocator,
+		fc.endpointCandidates,
 		fc.clock,
 		fc.config.ExpiryCleanupInterval,
 		fc.config.EnqueueChannelBufferSize,

pkg/epp/flowcontrol/controller/controller_test.go

@@ -116,7 +116,7 @@ func newUnitHarness(
 	}
 
 	mockDetector := &mocks.MockSaturationDetector{}
-	mockPodLocator := &mocks.MockPodLocator{}
+	mockEndpointCandidates := &mocks.MockEndpointCandidates{}
 
 	mockProcessorFactory := &mockShardProcessorFactory{
 		processors: make(map[string]*mockShardProcessor),
@@ -132,7 +132,7 @@ func newUnitHarness(
 		withClock(harnessOpts.clock),
 		withShardProcessorFactory(mockProcessorFactory.new),
 	}
-	fc, err := NewFlowController(ctx, "test-pool", cfg, registry, mockDetector, mockPodLocator, fcOpts...)
+	fc, err := NewFlowController(ctx, "test-pool", cfg, registry, mockDetector, mockEndpointCandidates, fcOpts...)
 	require.NoError(t, err, "failed to create FlowController for unit test harness")
 
 	h := &testHarness{
@@ -155,7 +155,7 @@ func newUnitHarness(
 func newIntegrationHarness(t *testing.T, ctx context.Context, cfg *Config, registry *mockRegistryClient) *testHarness {
 	t.Helper()
 	mockDetector := &mocks.MockSaturationDetector{}
-	mockPodLocator := &mocks.MockPodLocator{}
+	mockEndpointCandidates := &mocks.MockEndpointCandidates{}
 
 	// Align FakeClock with system time. See explanation in newUnitHarness.
 	mockClock := testclock.NewFakeClock(time.Now())
@@ -167,7 +167,7 @@ func newIntegrationHarness(t *testing.T, ctx context.Context, cfg *Config, regis
 		withRegistryClient(registry),
 		withClock(mockClock),
 	}
-	fc, err := NewFlowController(ctx, "test-pool", cfg, registry, mockDetector, mockPodLocator, opts...)
+	fc, err := NewFlowController(ctx, "test-pool", cfg, registry, mockDetector, mockEndpointCandidates, opts...)
 	require.NoError(t, err, "failed to create FlowController for integration test harness")
 
 	h := &testHarness{
@@ -277,7 +277,7 @@ func (f *mockShardProcessorFactory) new(
 	_ context.Context, // The factory does not use the lifecycle context; it's passed to the processor's Run method later.
 	shard contracts.RegistryShard,
 	_ contracts.SaturationDetector,
-	_ contracts.PodLocator,
+	_ contracts.EndpointCandidates,
 	_ clock.WithTicker,
 	_ time.Duration,
 	_ int,
@@ -1141,7 +1141,7 @@ func TestFlowController_WorkerManagement(t *testing.T) {
 			ctx context.Context, // The context created by getOrStartWorker for the potential new processor.
 			shard contracts.RegistryShard,
 			_ contracts.SaturationDetector,
-			_ contracts.PodLocator,
+			_ contracts.EndpointCandidates,
 			_ clock.WithTicker,
 			_ time.Duration,
 			_ int,

pkg/epp/flowcontrol/controller/internal/processor.go

@@ -68,7 +68,7 @@ type ShardProcessor struct {
 	poolName             string
 	shard                contracts.RegistryShard
 	saturationDetector   contracts.SaturationDetector
-	podLocator           contracts.PodLocator
+	endpointCandidates   contracts.EndpointCandidates
 	clock                clock.WithTicker
 	cleanupSweepInterval time.Duration
 	logger               logr.Logger
@@ -91,7 +91,7 @@ func NewShardProcessor(
 	poolName string,
 	shard contracts.RegistryShard,
 	saturationDetector contracts.SaturationDetector,
-	podLocator contracts.PodLocator,
+	endpointCandidates contracts.EndpointCandidates,
 	clock clock.WithTicker,
 	cleanupSweepInterval time.Duration,
 	enqueueChannelBufferSize int,
@@ -101,7 +101,7 @@ func NewShardProcessor(
 		shard:                shard,
 		poolName:             poolName,
 		saturationDetector:   saturationDetector,
-		podLocator:           podLocator,
+		endpointCandidates:   endpointCandidates,
 		clock:                clock,
 		cleanupSweepInterval: cleanupSweepInterval,
 		logger:               logger,
@@ -314,7 +314,7 @@ func (sp *ShardProcessor) dispatchCycle(ctx context.Context) bool {
 		metrics.RecordFlowControlDispatchCycleDuration(time.Since(dispatchCycleStart))
 	}()
 
-	pool := sp.podLocator.Locate(ctx, nil)
+	pool := sp.endpointCandidates.Locate(ctx, nil)
 	saturation := sp.saturationDetector.Saturation(ctx, pool)
 
 	// Record pool saturation metric

pkg/epp/flowcontrol/controller/internal/processor_test.go

@@ -75,7 +75,7 @@ type testHarness struct {
 	clock              *testclock.FakeClock
 	logger             logr.Logger
 	saturationDetector *mocks.MockSaturationDetector
-	podLocator         *mocks.MockPodLocator
+	endpointCandidates *mocks.MockEndpointCandidates
 
 	// --- Centralized Mock State ---
 	// The harness's mutex protects the single source of truth for all mock state.
@@ -96,7 +96,7 @@ func newTestHarness(t *testing.T, expiryCleanupInterval time.Duration) *testHarn
 		clock:              testclock.NewFakeClock(time.Now()),
 		logger:             logr.Discard(),
 		saturationDetector: &mocks.MockSaturationDetector{},
-		podLocator:         &mocks.MockPodLocator{Pods: []fwkdl.Endpoint{&metrics.FakePodMetrics{}}},
+		endpointCandidates: &mocks.MockEndpointCandidates{Candidates: []fwkdl.Endpoint{&metrics.FakePodMetrics{}}},
 		startSignal:        make(chan struct{}),
 		queues:             make(map[flowcontrol.FlowKey]*mocks.MockManagedQueue),
 		priorityFlows:      make(map[int][]flowcontrol.FlowKey),
@@ -124,7 +124,7 @@ func newTestHarness(t *testing.T, expiryCleanupInterval time.Duration) *testHarn
 		"test-pool",
 		h,
 		h.saturationDetector,
-		h.podLocator,
+		h.endpointCandidates,
 		h.clock,
 		expiryCleanupInterval,
 		100,

pkg/epp/framework/interface/flowcontrol/request.go

@@ -57,7 +57,7 @@ type FlowControlRequest interface {
 	ID() string
 
 	// GetMetadata returns the opaque metadata associated with the request (e.g., header-derived context, subset filters).
-	// This data is passed transparently to components like the contracts.PodLocator to resolve resources (candidate pods)
+	// This data is passed transparently to components like contracts.EndpointCandidates to resolve resources (endpoint candidates)
 	// lazily during the dispatch cycle.
 	GetMetadata() map[string]any
 

pkg/epp/requestcontrol/admission.go

@@ -65,13 +65,13 @@ type flowController interface {
 func rejectIfSheddableAndSaturated(
 	ctx context.Context,
 	sd contracts.SaturationDetector,
-	locator contracts.PodLocator,
+	endpointCandidates contracts.EndpointCandidates,
 	reqCtx *handlers.RequestContext,
 	priority int,
 	logger logr.Logger,
 ) error {
 	if requtil.IsSheddable(priority) {
-		if sd.Saturation(ctx, locator.Locate(ctx, reqCtx.Request.Metadata)) >= 1.0 {
+		if sd.Saturation(ctx, endpointCandidates.Locate(ctx, reqCtx.Request.Metadata)) >= 1.0 {
 			logger.V(logutil.TRACE).Info("Request rejected: system saturated and request is sheddable",
 				"requestID", reqCtx.SchedulingRequest.RequestId)
 			return errcommon.Error{
@@ -90,17 +90,17 @@ func rejectIfSheddableAndSaturated(
 // saturated. Non-sheddable requests always bypass the saturation check.
 type LegacyAdmissionController struct {
 	saturationDetector contracts.SaturationDetector
-	podLocator         contracts.PodLocator
+	endpointCandidates contracts.EndpointCandidates
 }
 
 // NewLegacyAdmissionController creates a new LegacyAdmissionController.
 func NewLegacyAdmissionController(
 	sd contracts.SaturationDetector,
-	pl contracts.PodLocator,
+	endpointCandidates contracts.EndpointCandidates,
 ) *LegacyAdmissionController {
 	return &LegacyAdmissionController{
 		saturationDetector: sd,
-		podLocator:         pl,
+		endpointCandidates: endpointCandidates,
 	}
 }
 
@@ -117,7 +117,7 @@ func (lac *LegacyAdmissionController) Admit(
 	if err := rejectIfSheddableAndSaturated(
 		ctx,
 		lac.saturationDetector,
-		lac.podLocator,
+		lac.endpointCandidates,
 		reqCtx, priority,
 		logger,
 	); err != nil {

pkg/epp/requestcontrol/admission_test.go

@@ -119,8 +119,8 @@ func TestLegacyAdmissionController_Admit(t *testing.T) {
 					return 0.0
 				},
 			}
-			locator := &mocks.MockPodLocator{Pods: tc.locatorPods}
-			ac := NewLegacyAdmissionController(mockDetector, locator)
+			endpointCandidates := &mocks.MockEndpointCandidates{Candidates: tc.locatorPods}
+			ac := NewLegacyAdmissionController(mockDetector, endpointCandidates)
 
 			err := ac.Admit(ctx, reqCtx, tc.priority)