feat: add validation for vllm endpoint address (#202)

Signed-off-by: bitliu <[email protected]>

Author: Xunzhuo

config/config.yaml

@@ -27,9 +27,12 @@ prompt_guard:
   jailbreak_mapping_path: "models/jailbreak_classifier_modernbert-base_model/jailbreak_type_mapping.json"
 
 # vLLM Endpoints Configuration
+# IMPORTANT: 'address' field must be a valid IP address (IPv4 or IPv6)
+# Supported formats: 127.0.0.1, 192.168.1.1, ::1, 2001:db8::1
+# NOT supported: domain names (example.com), protocol prefixes (http://), paths (/api), ports in address (use 'port' field)
 vllm_endpoints:
   - name: "endpoint1"
-    address: "127.0.0.1"
+    address: "127.0.0.1"  # IPv4 address - REQUIRED format
     port: 8000
     models:
       - "openai/gpt-oss-20b"

deploy/kubernetes/config.yaml

@@ -22,22 +22,25 @@ prompt_guard:
   jailbreak_mapping_path: "models/jailbreak_classifier_modernbert-base_model/jailbreak_type_mapping.json"
 
 # vLLM Endpoints Configuration - supports multiple endpoints, each can serve multiple models
+# IMPORTANT: 'address' field must be a valid IP address (IPv4 or IPv6)
+# Supported formats: 127.0.0.1, 192.168.1.1, ::1, 2001:db8::1
+# NOT supported: domain names (example.com), protocol prefixes (http://), paths (/api), ports in address (use 'port' field)
 vllm_endpoints:
   - name: "endpoint1"
-    address: "127.0.0.1"
+    address: "127.0.0.1"  # IPv4 address - REQUIRED format
     port: 11434
     models:
       - "phi4"
       - "gemma3:27b"
     weight: 1  # Load balancing weight
   - name: "endpoint2"
-    address: "127.0.0.1"
+    address: "127.0.0.1"  # IPv4 address - REQUIRED format
     port: 11434
     models:
       - "mistral-small3.1"
     weight: 1
   - name: "endpoint3"
-    address: "127.0.0.1"
+    address: "127.0.0.1"  # IPv4 address - REQUIRED format
     port: 11434
     models:
       - "phi4"  # Same model can be served by multiple endpoints for redundancy

src/semantic-router/pkg/api/server_test.go

@@ -254,7 +254,7 @@ func TestOpenAIModelsEndpoint(t *testing.T) {
 		VLLMEndpoints: []config.VLLMEndpoint{
 			{
 				Name:    "primary",
-				Address: "localhost",
+				Address: "127.0.0.1", // Changed from localhost to IP address
 				Port:    8000,
 				Models:  []string{"gpt-4o-mini", "llama-3.1-8b-instruct"},
 				Weight:  1,

src/semantic-router/pkg/config/config.go

@@ -364,6 +364,11 @@ func validateConfigStructure(cfg *RouterConfig) error {
 		}
 	}
 
+	// Validate vLLM endpoints address formats
+	if err := validateVLLMEndpoints(cfg.VLLMEndpoints); err != nil {
+		return err
+	}
+
 	return nil
 }
 

src/semantic-router/pkg/config/config_test.go

@@ -998,6 +998,249 @@ default_model: "missing-default-model"
 				Expect(err.Error()).To(ContainSubstring("missing-default-model"))
 			})
 		})
+
+		Describe("vLLM Endpoint Address Validation", func() {
+			Context("with valid IP addresses", func() {
+				It("should accept IPv4 addresses", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "127.0.0.1"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					cfg, err := config.LoadConfig(configFile)
+					Expect(err).NotTo(HaveOccurred())
+					Expect(cfg.VLLMEndpoints[0].Address).To(Equal("127.0.0.1"))
+				})
+
+				It("should accept IPv6 addresses", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "::1"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					cfg, err := config.LoadConfig(configFile)
+					Expect(err).NotTo(HaveOccurred())
+					Expect(cfg.VLLMEndpoints[0].Address).To(Equal("::1"))
+				})
+			})
+
+			Context("with invalid address formats", func() {
+				It("should reject domain names", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "example.com"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+					Expect(err.Error()).To(ContainSubstring("endpoint1"))
+					Expect(err.Error()).To(ContainSubstring("address validation failed"))
+					Expect(err.Error()).To(ContainSubstring("invalid IP address format"))
+				})
+
+				It("should reject protocol prefixes", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "http://127.0.0.1"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+					Expect(err.Error()).To(ContainSubstring("protocol prefixes"))
+					Expect(err.Error()).To(ContainSubstring("are not supported"))
+				})
+
+				It("should reject addresses with paths", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "127.0.0.1/api"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+					Expect(err.Error()).To(ContainSubstring("paths are not supported"))
+				})
+
+				It("should reject addresses with port numbers", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "127.0.0.1:8080"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+					Expect(err.Error()).To(ContainSubstring("port numbers in address are not supported"))
+					Expect(err.Error()).To(ContainSubstring("use 'port' field instead"))
+				})
+
+				It("should provide comprehensive error messages", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "test-endpoint"
+    address: "https://example.com"
+    port: 8000
+    models:
+      - "test-model"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+
+					errorMsg := err.Error()
+					Expect(errorMsg).To(ContainSubstring("test-endpoint"))
+					Expect(errorMsg).To(ContainSubstring("Supported formats"))
+					Expect(errorMsg).To(ContainSubstring("IPv4: 192.168.1.1"))
+					Expect(errorMsg).To(ContainSubstring("IPv6: ::1"))
+					Expect(errorMsg).To(ContainSubstring("Unsupported formats"))
+					Expect(errorMsg).To(ContainSubstring("Domain names: example.com"))
+					Expect(errorMsg).To(ContainSubstring("Protocol prefixes: http://"))
+				})
+			})
+
+			Context("with multiple endpoints", func() {
+				It("should validate all endpoints", func() {
+					configContent := `
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "127.0.0.1"
+    port: 8000
+    models:
+      - "test-model1"
+    weight: 1
+  - name: "endpoint2"
+    address: "example.com"
+    port: 8001
+    models:
+      - "test-model2"
+    weight: 1
+
+categories:
+  - name: "test"
+    model_scores:
+      - model: "test-model1"
+        score: 0.9
+        use_reasoning: true
+
+default_model: "test-model1"
+`
+					err := os.WriteFile(configFile, []byte(configContent), 0o644)
+					Expect(err).NotTo(HaveOccurred())
+
+					_, err = config.LoadConfig(configFile)
+					Expect(err).To(HaveOccurred())
+					Expect(err.Error()).To(ContainSubstring("endpoint2"))
+					Expect(err.Error()).To(ContainSubstring("invalid IP address format"))
+				})
+			})
+		})
 	})
 
 	Describe("Semantic Cache Backend Configuration", func() {

src/semantic-router/pkg/config/validation.go

@@ -0,0 +1,84 @@
+package config
+
+import (
+	"fmt"
+	"net"
+	"regexp"
+	"strings"
+)
+
+var (
+	// Pre-compiled regular expressions for better performance
+	protocolRegex = regexp.MustCompile(`^https?://`)
+	pathRegex     = regexp.MustCompile(`/`)
+	// Pattern to match IPv4 address followed by port number
+	ipv4PortRegex = regexp.MustCompile(`^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d+$`)
+	// Pattern to match IPv6 address followed by port number [::1]:8080
+	ipv6PortRegex = regexp.MustCompile(`^\[.*\]:\d+$`)
+)
+
+// validateIPAddress validates IP address format
+// Supports IPv4 and IPv6 addresses, rejects domain names, protocol prefixes, paths, etc.
+func validateIPAddress(address string) error {
+	// Check for empty string
+	trimmed := strings.TrimSpace(address)
+	if trimmed == "" {
+		return fmt.Errorf("address cannot be empty")
+	}
+
+	// Check for protocol prefixes (http://, https://)
+	if protocolRegex.MatchString(trimmed) {
+		return fmt.Errorf("protocol prefixes (http://, https://) are not supported, got: %s", address)
+	}
+
+	// Check for paths (contains / character)
+	if pathRegex.MatchString(trimmed) {
+		return fmt.Errorf("paths are not supported, got: %s", address)
+	}
+
+	// Check for port numbers (IPv4 address followed by port or IPv6 address followed by port)
+	if ipv4PortRegex.MatchString(trimmed) || ipv6PortRegex.MatchString(trimmed) {
+		return fmt.Errorf("port numbers in address are not supported, use 'port' field instead, got: %s", address)
+	}
+
+	// Use Go standard library to validate IP address format
+	ip := net.ParseIP(trimmed)
+	if ip == nil {
+		return fmt.Errorf("invalid IP address format, got: %s", address)
+	}
+
+	return nil
+}
+
+// validateVLLMEndpoints validates the address format of all vLLM endpoints
+func validateVLLMEndpoints(endpoints []VLLMEndpoint) error {
+	for _, endpoint := range endpoints {
+		if err := validateIPAddress(endpoint.Address); err != nil {
+			return fmt.Errorf("vLLM endpoint '%s' address validation failed: %w\n\nSupported formats:\n- IPv4: 192.168.1.1, 127.0.0.1\n- IPv6: ::1, 2001:db8::1\n\nUnsupported formats:\n- Domain names: example.com, localhost\n- Protocol prefixes: http://, https://\n- Paths: /api/v1, /health\n- Ports in address: use 'port' field instead", endpoint.Name, err)
+		}
+	}
+	return nil
+}
+
+// isValidIPv4 checks if the address is a valid IPv4 address
+func isValidIPv4(address string) bool {
+	ip := net.ParseIP(address)
+	return ip != nil && ip.To4() != nil
+}
+
+// isValidIPv6 checks if the address is a valid IPv6 address
+func isValidIPv6(address string) bool {
+	ip := net.ParseIP(address)
+	return ip != nil && ip.To4() == nil
+}
+
+// getIPAddressType returns the IP address type information for error messages and debugging
+func getIPAddressType(address string) string {
+	if isValidIPv4(address) {
+		return "IPv4"
+	}
+	if isValidIPv6(address) {
+		return "IPv6"
+	}
+	return "invalid"
+}