flowcontrol: add metadata support to request type

Updates the FlowControlRequest interface to carry request metadata
instead of a pre-resolved list of candidate pods. This prepares the
system for lazy pod resolution.

- Adds GetMetadata() to FlowControlRequest.
- Removes CandidatePodsForScheduling() from FlowControlRequest.
- Updates mocks in flowcontrol/types and contracts.

Author: LukeAVanDrie

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

@@ -41,6 +41,8 @@ import (
 	typesmocks "sigs.k8s.io/gateway-api-inference-extension/pkg/epp/flowcontrol/types/mocks"
 )
 
+// --- RegistryShard Mocks ---
+
 // MockRegistryShard is a simple "stub-style" mock for testing.
 // Its methods are implemented as function fields (e.g., `IDFunc`). A test can inject behavior by setting the desired
 // function field in the test setup. If a func is nil, the method will return a zero value.
@@ -111,6 +113,8 @@ func (m *MockRegistryShard) Stats() contracts.ShardStats {
 	return contracts.ShardStats{}
 }
 
+// --- Dependency Mocks ---
+
 // MockSaturationDetector is a simple "stub-style" mock for testing.
 type MockSaturationDetector struct {
 	IsSaturatedFunc func(ctx context.Context, candidatePods []metrics.PodMetrics) bool
@@ -123,6 +127,30 @@ func (m *MockSaturationDetector) IsSaturated(ctx context.Context, candidatePods
 	return false
 }
 
+// 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 {
+	// LocateFunc allows injecting custom logic.
+	LocateFunc func(ctx context.Context, requestMetadata map[string]any) []metrics.PodMetrics
+	// Pods is a static return value used if LocateFunc is nil.
+	Pods []metrics.PodMetrics
+}
+
+func (m *MockPodLocator) Locate(ctx context.Context, requestMetadata map[string]any) []metrics.PodMetrics {
+	if m.LocateFunc != nil {
+		return m.LocateFunc(ctx, requestMetadata)
+	}
+	// Return copy to be safe
+	if m.Pods == nil {
+		return nil
+	}
+	result := make([]metrics.PodMetrics, len(m.Pods))
+	copy(result, m.Pods)
+	return result
+}
+
+// --- ManagedQueue Mock ---
+
 // MockManagedQueue is a high-fidelity, thread-safe mock of the `contracts.ManagedQueue` interface, designed
 // specifically for testing the concurrent `controller/internal.ShardProcessor`.
 //

pkg/epp/flowcontrol/types/mocks/mocks.go

@@ -21,20 +21,19 @@ package mocks
 import (
 	"time"
 
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/backend/metrics"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/flowcontrol/types"
 )
 
-// MockFlowControlRequest provides a mock implementation of the `types.FlowControlRequest` interface.
+// MockFlowControlRequest provides a mock implementation of the types.FlowControlRequest interface.
 type MockFlowControlRequest struct {
-	FlowKeyV                    types.FlowKey
-	ByteSizeV                   uint64
-	InitialEffectiveTTLV        time.Duration
-	IDV                         string
-	CandidatePodsForSchedulingV []*metrics.FakePodMetrics
+	FlowKeyV             types.FlowKey
+	ByteSizeV            uint64
+	InitialEffectiveTTLV time.Duration
+	IDV                  string
+	MetadataV            map[string]any
 }
 
-// NewMockFlowControlRequest creates a new `MockFlowControlRequest` instance.
+// NewMockFlowControlRequest creates a new MockFlowControlRequest instance.
 func NewMockFlowControlRequest(
 	byteSize uint64,
 	id string,
@@ -44,21 +43,15 @@ func NewMockFlowControlRequest(
 		ByteSizeV: byteSize,
 		IDV:       id,
 		FlowKeyV:  key,
+		MetadataV: make(map[string]any),
 	}
 }
 
 func (m *MockFlowControlRequest) FlowKey() types.FlowKey             { return m.FlowKeyV }
 func (m *MockFlowControlRequest) ByteSize() uint64                   { return m.ByteSizeV }
 func (m *MockFlowControlRequest) InitialEffectiveTTL() time.Duration { return m.InitialEffectiveTTLV }
 func (m *MockFlowControlRequest) ID() string                         { return m.IDV }
-
-func (m *MockFlowControlRequest) CandidatePodsForScheduling() []metrics.PodMetrics {
-	pods := make([]metrics.PodMetrics, 0, len(m.CandidatePodsForSchedulingV))
-	for i, pod := range m.CandidatePodsForSchedulingV {
-		pods[i] = pod
-	}
-	return pods
-}
+func (m *MockFlowControlRequest) GetMetadata() map[string]any        { return m.MetadataV }
 
 var _ types.FlowControlRequest = &MockFlowControlRequest{}
 

pkg/epp/flowcontrol/types/request.go

@@ -18,8 +18,6 @@ package types
 
 import (
 	"time"
-
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/backend/metrics"
 )
 
 // FlowControlRequest is the contract for an incoming request submitted to the `controller.FlowController`. It
@@ -45,15 +43,15 @@ type FlowControlRequest interface {
 	// applied.
 	InitialEffectiveTTL() time.Duration
 
-	// CandidatePodsForScheduling passes through a set of candidate pods a request may be admitted to.
-	// This is necessary for invoking `contracts.SaturationDetector.IsSaturated`, but it is otherwise unused in the Flow
-	// Control system.
-	CandidatePodsForScheduling() []metrics.PodMetrics
-
 	// ID returns an optional, user-facing unique identifier for this specific request. It is intended for logging,
 	// tracing, and observability. The `controller.FlowController` does not use this ID for dispatching decisions; it uses
 	// the internal, opaque `QueueItemHandle`.
 	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)
+	// lazily during the dispatch cycle.
+	GetMetadata() map[string]any
 }
 
 // QueueItemHandle is an opaque handle to an item that has been successfully added to a `framework.SafeQueue`. It acts