feat: add CEL XValidation for ApisixRouteHTTPMatchExprSubject

Add +kubebuilder:validation:XValidation rule requiring name to be
non-empty when scope is not Path. Regenerate CRD YAML and update
CRD reference docs accordingly. All unit and CEL tests pass.

Author: AlinsRan

api/v2/apisixroute_types.go

@@ -412,6 +412,7 @@ type ApisixRouteAuthenticationLDAPAuth struct {
 }
 
 // ApisixRouteHTTPMatchExprSubject describes the subject of a route matching expression.
+// +kubebuilder:validation:XValidation:rule="self.scope == 'Path' || self.name != ''",message="name is required when scope is not Path"
 type ApisixRouteHTTPMatchExprSubject struct {
 	// Scope specifies the subject scope.
 	// Supported values: `Header`, `Query`, `Path`, `Cookie`, `Variable`, `Body`.

api/v2/apisixroute_types_test.go

@@ -18,14 +18,73 @@
 package v2
 
 import (
+	"os"
 	"testing"
 
+	"github.com/google/cel-go/cel"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"sigs.k8s.io/yaml"
 )
 
 func strPtr(s string) *string { return &s }
 
+// celSubjectRule is the CEL expression used in the +kubebuilder:validation:XValidation
+// marker on ApisixRouteHTTPMatchExprSubject.
+const celSubjectRule = `self.scope == 'Path' || self.name != ''`
+
+func evalCELSubjectRule(t *testing.T, scope, name string) bool {
+	t.Helper()
+	env, err := cel.NewEnv(
+		cel.Variable("self", cel.MapType(cel.StringType, cel.StringType)),
+	)
+	require.NoError(t, err)
+	ast, issues := env.Compile(celSubjectRule)
+	require.NoError(t, issues.Err())
+	prg, err := env.Program(ast)
+	require.NoError(t, err)
+	out, _, err := prg.Eval(map[string]any{
+		"self": map[string]any{"scope": scope, "name": name},
+	})
+	require.NoError(t, err)
+	return out.Value().(bool)
+}
+
+// TestCEL_SubjectRule_Logic verifies the CEL expression used in the XValidation marker.
+func TestCEL_SubjectRule_Logic(t *testing.T) {
+	// Non-Path scopes with a non-empty name must pass.
+	for _, scope := range []string{ScopeHeader, ScopeQuery, ScopeCookie, ScopeVariable, ScopeBody} {
+		assert.True(t, evalCELSubjectRule(t, scope, "field"), "scope=%s with name should pass", scope)
+	}
+	// Path scope with empty name must pass (name is ignored for Path).
+	assert.True(t, evalCELSubjectRule(t, ScopePath, ""), "Path with empty name should pass")
+	// Non-Path scopes with empty name must fail.
+	for _, scope := range []string{ScopeHeader, ScopeQuery, ScopeCookie, ScopeVariable, ScopeBody} {
+		assert.False(t, evalCELSubjectRule(t, scope, ""), "scope=%s with empty name should fail", scope)
+	}
+}
+
+// TestCEL_SubjectRule_InCRD verifies the generated CRD YAML contains the XValidation rule
+// with correct (ASCII) quote characters and not typographic quotes.
+func TestCEL_SubjectRule_InCRD(t *testing.T) {
+	const crdPath = "../../config/crd/bases/apisix.apache.org_apisixroutes.yaml"
+	data, err := os.ReadFile(crdPath)
+	require.NoError(t, err, "CRD file should exist; run 'make manifests' if missing")
+
+	var crd map[string]any
+	require.NoError(t, yaml.Unmarshal(data, &crd))
+
+	raw := string(data)
+	// The CEL rule must appear with ASCII single-quotes only.
+	assert.Contains(t, raw, `self.scope == 'Path' || self.name != ''`,
+		"CRD should contain the XValidation rule with ASCII quotes")
+	// Ensure no typographic/smart quotes crept in.
+	assert.NotContains(t, raw, "\u2018", "CRD must not contain left single quotation mark \u2018")
+	assert.NotContains(t, raw, "\u2019", "CRD must not contain right single quotation mark \u2019")
+	assert.NotContains(t, raw, "\u201c", "CRD must not contain left double quotation mark \u201c")
+	assert.NotContains(t, raw, "\u201d", "CRD must not contain right double quotation mark \u201d")
+}
+
 func TestToVars_ScopeBody_SimpleField(t *testing.T) {
 	exprs := ApisixRouteHTTPMatchExprs{
 		{

config/crd/bases/apisix.apache.org_apisixroutes.yaml

@@ -230,6 +230,9 @@ spec:
                                 required:
                                 - scope
                                 type: object
+                                x-kubernetes-validations:
+                                - message: name is required when scope is not Path
+                                  rule: self.scope == 'Path' || self.name != ''
                               value:
                                 description: |-
                                   Value defines a single value to compare against the subject.

docs/en/latest/reference/api-reference.md

@@ -1119,8 +1119,8 @@ ApisixRouteHTTPMatchExprSubject describes the subject of a route matching expres
 
 | Field | Description |
 | --- | --- |
-| `scope` _string_ | Scope specifies the subject scope and can be `Header`, `Query`, or `Path`. When Scope is `Path`, Name will be ignored. |
-| `name` _string_ | Name is the name of the header or query parameter. |
+| `scope` _string_ | Scope specifies the subject scope. Supported values: `Header`, `Query`, `Path`, `Cookie`, `Variable`, `Body`. When Scope is `Path`, Name will be ignored. When Scope is `Body`, Name supports dot-notation JSON path (e.g., "model.version", "messages[*].role") and maps to APISIX's post_arg.<name> variable, which works with application/json, application/x-www-form-urlencoded, and multipart/form-data. |
+| `name` _string_ | Name is the name of the subject within the given scope: the header name, query parameter name, cookie name, Nginx variable name, or body field name (dot-notation JSON path supported for Body scope). Optional when Scope is Path. |
 
 
 _Appears in:_