refactor: Relocate SaturationDetector (#1976)

This commit moves the existing `SaturationDetector` implementation to
its new home under the EPP plugin framework structure. This is a
preparatory step towards making `SaturationDetector` an official EPP
extension point.

- Moved files to `.../framework/plugins/utilizationdetector`
- Renamed `saturationdetector.go` to `detector.go`
- Renamed `saturationdetector_test.go` to `detector_test.go`
- Fixed imports

No functional changes are included in this commit.

Author: LukeAVanDrie

cmd/epp/runner/runner.go

@@ -65,7 +65,7 @@ import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/plugins"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/requestcontrol"
 	testresponsereceived "sigs.k8s.io/gateway-api-inference-extension/pkg/epp/requestcontrol/plugins/test/responsereceived"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/multi/prefix"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/multi/slo_aware_router"
@@ -285,7 +285,7 @@ func (r *Runner) Run(ctx context.Context) error {
 
 	scheduler := scheduling.NewSchedulerWithConfig(r.schedulerConfig)
 
-	saturationDetector := saturationdetector.NewDetector(eppConfig.SaturationDetectorConfig, setupLog)
+	saturationDetector := utilizationdetector.NewDetector(eppConfig.SaturationDetectorConfig, setupLog)
 
 	// --- Admission Control Initialization ---
 	var admissionController requestcontrol.AdmissionController
@@ -508,23 +508,23 @@ func (r *Runner) deprecatedConfigurationHelper(cfg *config.Config, logger logr.L
 	if _, ok := os.LookupEnv(EnvSdQueueDepthThreshold); ok {
 		logger.Info("Configuring Saturation Detector using environment variables is deprecated and will be removed in next version")
 		cfg.SaturationDetectorConfig.QueueDepthThreshold =
-			env.GetEnvInt(EnvSdQueueDepthThreshold, saturationdetector.DefaultQueueDepthThreshold, logger)
+			env.GetEnvInt(EnvSdQueueDepthThreshold, utilizationdetector.DefaultQueueDepthThreshold, logger)
 		if cfg.SaturationDetectorConfig.QueueDepthThreshold <= 0 {
-			cfg.SaturationDetectorConfig.QueueDepthThreshold = saturationdetector.DefaultQueueDepthThreshold
+			cfg.SaturationDetectorConfig.QueueDepthThreshold = utilizationdetector.DefaultQueueDepthThreshold
 		}
 	}
 	if _, ok := os.LookupEnv(EnvSdKVCacheUtilThreshold); ok {
 		logger.Info("Configuring Saturation Detector using environment variables is deprecated and will be removed in next version")
-		cfg.SaturationDetectorConfig.KVCacheUtilThreshold = env.GetEnvFloat(EnvSdKVCacheUtilThreshold, saturationdetector.DefaultKVCacheUtilThreshold, logger)
+		cfg.SaturationDetectorConfig.KVCacheUtilThreshold = env.GetEnvFloat(EnvSdKVCacheUtilThreshold, utilizationdetector.DefaultKVCacheUtilThreshold, logger)
 		if cfg.SaturationDetectorConfig.KVCacheUtilThreshold <= 0 || cfg.SaturationDetectorConfig.KVCacheUtilThreshold >= 1 {
-			cfg.SaturationDetectorConfig.KVCacheUtilThreshold = saturationdetector.DefaultKVCacheUtilThreshold
+			cfg.SaturationDetectorConfig.KVCacheUtilThreshold = utilizationdetector.DefaultKVCacheUtilThreshold
 		}
 	}
 	if _, ok := os.LookupEnv(EnvSdMetricsStalenessThreshold); ok {
 		logger.Info("Configuring Saturation Detector using environment variables is deprecated and will be removed in next version")
-		cfg.SaturationDetectorConfig.MetricsStalenessThreshold = env.GetEnvDuration(EnvSdMetricsStalenessThreshold, saturationdetector.DefaultMetricsStalenessThreshold, logger)
+		cfg.SaturationDetectorConfig.MetricsStalenessThreshold = env.GetEnvDuration(EnvSdMetricsStalenessThreshold, utilizationdetector.DefaultMetricsStalenessThreshold, logger)
 		if cfg.SaturationDetectorConfig.MetricsStalenessThreshold <= 0 {
-			cfg.SaturationDetectorConfig.MetricsStalenessThreshold = saturationdetector.DefaultMetricsStalenessThreshold
+			cfg.SaturationDetectorConfig.MetricsStalenessThreshold = utilizationdetector.DefaultMetricsStalenessThreshold
 		}
 	}
 }

pkg/epp/config/config.go

@@ -18,13 +18,13 @@ package config
 
 import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/datalayer"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling"
 )
 
 // Config is the configuration loaded from the text based configuration
 type Config struct {
 	SchedulerConfig          *scheduling.SchedulerConfig
-	SaturationDetectorConfig *saturationdetector.Config
+	SaturationDetectorConfig *utilizationdetector.Config
 	DataConfig               *datalayer.Config
 }

pkg/epp/config/loader/configloader.go

@@ -30,7 +30,7 @@ import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/config"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/datalayer"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/plugins"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/profile"
@@ -211,11 +211,11 @@ func loadFeatureConfig(gates configapi.FeatureGates) map[string]bool {
 	return config
 }
 
-func buildSaturationConfig(apiConfig *configapi.SaturationDetector) *saturationdetector.Config {
-	cfg := &saturationdetector.Config{
-		QueueDepthThreshold:       saturationdetector.DefaultQueueDepthThreshold,
-		KVCacheUtilThreshold:      saturationdetector.DefaultKVCacheUtilThreshold,
-		MetricsStalenessThreshold: saturationdetector.DefaultMetricsStalenessThreshold,
+func buildSaturationConfig(apiConfig *configapi.SaturationDetector) *utilizationdetector.Config {
+	cfg := &utilizationdetector.Config{
+		QueueDepthThreshold:       utilizationdetector.DefaultQueueDepthThreshold,
+		KVCacheUtilThreshold:      utilizationdetector.DefaultKVCacheUtilThreshold,
+		MetricsStalenessThreshold: utilizationdetector.DefaultMetricsStalenessThreshold,
 	}
 
 	if apiConfig != nil {

pkg/epp/config/loader/configloader_test.go

@@ -32,7 +32,7 @@ import (
 	configapi "sigs.k8s.io/gateway-api-inference-extension/apix/config/v1alpha1"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/datalayer"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/plugins"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/picker"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/profile"
@@ -339,7 +339,7 @@ func TestBuildSaturationConfig(t *testing.T) {
 	tests := []struct {
 		name     string
 		input    *configapi.SaturationDetector
-		expected *saturationdetector.Config
+		expected *utilizationdetector.Config
 	}{
 		{
 			name: "Valid Configuration",
@@ -348,7 +348,7 @@ func TestBuildSaturationConfig(t *testing.T) {
 				KVCacheUtilThreshold:      0.9,
 				MetricsStalenessThreshold: metav1.Duration{Duration: 500 * time.Millisecond},
 			},
-			expected: &saturationdetector.Config{
+			expected: &utilizationdetector.Config{
 				QueueDepthThreshold:       20,
 				KVCacheUtilThreshold:      0.9,
 				MetricsStalenessThreshold: 500 * time.Millisecond,
@@ -357,10 +357,10 @@ func TestBuildSaturationConfig(t *testing.T) {
 		{
 			name:  "Nil Input (Defaults)",
 			input: nil,
-			expected: &saturationdetector.Config{
-				QueueDepthThreshold:       saturationdetector.DefaultQueueDepthThreshold,
-				KVCacheUtilThreshold:      saturationdetector.DefaultKVCacheUtilThreshold,
-				MetricsStalenessThreshold: saturationdetector.DefaultMetricsStalenessThreshold,
+			expected: &utilizationdetector.Config{
+				QueueDepthThreshold:       utilizationdetector.DefaultQueueDepthThreshold,
+				KVCacheUtilThreshold:      utilizationdetector.DefaultKVCacheUtilThreshold,
+				MetricsStalenessThreshold: utilizationdetector.DefaultMetricsStalenessThreshold,
 			},
 		},
 		{
@@ -370,10 +370,10 @@ func TestBuildSaturationConfig(t *testing.T) {
 				KVCacheUtilThreshold:      1.5,
 				MetricsStalenessThreshold: metav1.Duration{Duration: -10 * time.Second},
 			},
-			expected: &saturationdetector.Config{
-				QueueDepthThreshold:       saturationdetector.DefaultQueueDepthThreshold,
-				KVCacheUtilThreshold:      saturationdetector.DefaultKVCacheUtilThreshold,
-				MetricsStalenessThreshold: saturationdetector.DefaultMetricsStalenessThreshold,
+			expected: &utilizationdetector.Config{
+				QueueDepthThreshold:       utilizationdetector.DefaultQueueDepthThreshold,
+				KVCacheUtilThreshold:      utilizationdetector.DefaultKVCacheUtilThreshold,
+				MetricsStalenessThreshold: utilizationdetector.DefaultMetricsStalenessThreshold,
 			},
 		},
 	}

pkg/epp/saturationdetector/config.go …rk/plugins/utilizationdetector/config.gopkg/epp/saturationdetector/config.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/config.go pkg/epp/saturationdetector/config.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/config.go

@@ -5,15 +5,16 @@ Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-	http://www.apache.org/licenses/LICENSE-2.0
+    http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-package saturationdetector
+
+package utilizationdetector
 
 import (
 	"time"

…saturationdetector/saturationdetector.go …/plugins/utilizationdetector/detector.gopkg/epp/saturationdetector/saturationdetector.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/detector.go pkg/epp/saturationdetector/saturationdetector.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/detector.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package saturationdetector implements a mechanism to determine if the
+// Package utilizationdetector implements a mechanism to determine if the
 // backend model servers are considered saturated based on observed metrics.
 //
 // The current implementation provides a saturation signal (IsSaturated)
@@ -27,7 +27,7 @@ limitations under the License.
 //   - Predictive saturation based on trends.
 //   - Hysteresis bands or other smoothing techniques to prevent rapid
 //     oscillations of the saturation signal.
-package saturationdetector
+package utilizationdetector
 
 import (
 	"context"

…ationdetector/saturationdetector_test.go …ins/utilizationdetector/detector_test.gopkg/epp/saturationdetector/saturationdetector_test.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/detector_test.go pkg/epp/saturationdetector/saturationdetector_test.go renamed to pkg/epp/saturationdetector/framework/plugins/utilizationdetector/detector_test.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package saturationdetector
+package utilizationdetector
 
 import (
 	"context"

pkg/epp/server/runserver.go

@@ -42,7 +42,7 @@ import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/datastore"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/handlers"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/requestcontrol"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 )
 
 // ExtProcServerRunner provides methods to manage an external process server.
@@ -58,7 +58,7 @@ type ExtProcServerRunner struct {
 	RefreshPrometheusMetricsInterval time.Duration
 	MetricsStalenessThreshold        time.Duration
 	Director                         *requestcontrol.Director
-	SaturationDetector               *saturationdetector.Detector
+	SaturationDetector               *utilizationdetector.Detector
 	UseExperimentalDatalayerV2       bool // Pluggable data layer feature flag
 
 	// This should only be used in tests. We won't need this once we do not inject metrics in the tests.

test/integration/epp/hermetic_test.go

@@ -66,7 +66,7 @@ import (
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/metadata"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/metrics"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/requestcontrol"
-	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector"
+	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/saturationdetector/framework/plugins/utilizationdetector"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework"
 	"sigs.k8s.io/gateway-api-inference-extension/pkg/epp/scheduling/framework/plugins/multi/prefix"
@@ -1233,12 +1233,12 @@ func BeforeSuite() func() {
 	schedulerConfig := scheduling.NewSchedulerConfig(profileHandler, map[string]*framework.SchedulerProfile{"default": defaultProfile})
 	scheduler := scheduling.NewSchedulerWithConfig(schedulerConfig)
 
-	sdConfig := &saturationdetector.Config{
-		QueueDepthThreshold:       saturationdetector.DefaultQueueDepthThreshold,
-		KVCacheUtilThreshold:      saturationdetector.DefaultKVCacheUtilThreshold,
-		MetricsStalenessThreshold: saturationdetector.DefaultMetricsStalenessThreshold,
+	sdConfig := &utilizationdetector.Config{
+		QueueDepthThreshold:       utilizationdetector.DefaultQueueDepthThreshold,
+		KVCacheUtilThreshold:      utilizationdetector.DefaultKVCacheUtilThreshold,
+		MetricsStalenessThreshold: utilizationdetector.DefaultMetricsStalenessThreshold,
 	}
-	detector := saturationdetector.NewDetector(sdConfig, logger.WithName("saturation-detector"))
+	detector := utilizationdetector.NewDetector(sdConfig, logger.WithName("saturation-detector"))
 	serverRunner.SaturationDetector = detector
 	locator := requestcontrol.NewDatastorePodLocator(serverRunner.Datastore)
 	admissionController := requestcontrol.NewLegacyAdmissionController(detector, locator)