Add validation-gen test infrastructure

Introduces the infrastructure for testing validation-gen tags.

Co-authored-by: Tim Hockin <[email protected]>
Co-authored-by: Aaron Prindle <[email protected]>
Co-authored-by: Yongrui Lin <[email protected]>

Author: 4 people

staging/src/k8s.io/apimachinery/pkg/api/validate/README.md

@@ -0,0 +1,64 @@
+# API validation
+
+This package holds functions which validate fields and types in the Kubernetes
+API. It may be useful beyond API validation, but this is the primary goal.
+
+Most of the public functions here have signatures which adhere to the following
+pattern, which is assumed by automation and code-generation:
+
+```
+import (
+        "context"
+        "k8s.io/apimachinery/pkg/api/operation"
+        "k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+func <Name>(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue <ValueType>, <OtherArgs...>) field.ErrorList
+```
+
+The name of validator functions should consider that callers will generally be
+spelling out the package name and the function name, and so should aim for
+legibility.  E.g. `validate.Concept()`.
+
+The `ctx` argument is Go's usual Context.
+
+The `opCtx` argument provides information about the API operation in question.
+
+The `fldPath` argument indicates the path to the field in question, to be used
+in errors.
+
+The `value` and `oldValue` arguments are the thing(s) being validated.  For
+CREATE operations (`opCtx.Operation == operation.Create`), the `oldValue`
+argument will be nil.  Many validators functions only look at the current value
+(`value`) and disregard `oldValue`.
+
+The `value` and `oldValue` arguments are always nilable - pointers to primitive
+types, slices of any type, or maps of any type.  Validator functions should
+avoid dereferencing nil. Callers are expected to not pass a nil `value` unless the
+API field itself was nilable. `oldValue` is always nil for CREATE operations and 
+is also nil for UPDATE operations if the `value` is not correlated with an `oldValue`.
+
+Simple content-validators may have no `<OtherArgs>`, but validator functions
+may take additional arguments.  Some validator functions will be built as
+generics, e.g. to allow any integer type or to handle arbitrary slices.
+
+Examples:
+
+```
+// NonEmpty validates that a string is not empty.
+func NonEmpty(ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ *string) field.ErrorList
+
+// Even validates that a slice has an even number of items.
+func Even[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ []T) field.ErrorList
+
+// KeysMaxLen validates that all of the string keys in a map are under the
+// specified length.
+func KeysMaxLen[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ map[string]T, maxLen int) field.ErrorList
+```
+
+Validator functions always return an `ErrorList` where each item is a distinct
+validation failure and a zero-length return value (not just nil) indicates
+success.
+
+Good validation failure messages follow the Kubernetes API conventions, for
+example using "must" instead of "should".

staging/src/k8s.io/apimachinery/pkg/api/validate/doc.go

@@ -0,0 +1,50 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+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
+
+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 validate holds API validation functions which are designed for use
+// with the k8s.io/code-generator/cmd/validation-gen tool.  Each validation
+// function has a similar fingerprint:
+//
+//	func <Name>(ctx context.Context,
+//	            op operation.Operation,
+//	            fldPath *field.Path,
+//	            value, oldValue <nilable type>,
+//	            <other args...>) field.ErrorList
+//
+// The value and oldValue arguments will always be a nilable type.  If the
+// original value was a string, these will be a *string.  If the original value
+// was a slice or map, these will be the same slice or map type.
+//
+// For a CREATE operation, the oldValue will always be nil.  For an UPDATE
+// operation, either value or oldValue may be nil, e.g. when adding or removing
+// a value in a list-map.  Validators which care about UPDATE operations should
+// look at the opCtx argument to know which operation is being executed.
+//
+// Tightened validation (also known as ratcheting validation) is supported by
+// defining a new validation function. For example:
+//
+//	func TightenedMaxLength(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue *string) field.ErrorList {
+//	  if oldValue != nil && len(MaxLength(ctx, op, fldPath, oldValue, nil)) > 0 {
+//	    // old value is not valid, so this value skips the tightened validation
+//	    return nil
+//	  }
+//	  return MaxLength(ctx, op, fldPath, value, nil)
+//	}
+//
+// In general, we cannot distinguish a non-specified slice or map from one that
+// is specified but empty.  Validators should not rely on nil values, but use
+// len() instead.
+package validate

staging/src/k8s.io/apimachinery/pkg/api/validate/testing.go

@@ -0,0 +1,35 @@
+/*
+Copyright 2014 The Kubernetes Authors.
+
+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
+
+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 validate
+
+import (
+	"context"
+
+	"k8s.io/apimachinery/pkg/api/operation"
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+// FixedResult asserts a fixed boolean result.  This is mostly useful for
+// testing.
+func FixedResult[T any](_ context.Context, op operation.Operation, fldPath *field.Path, value, _ T, result bool, arg string) field.ErrorList {
+	if result {
+		return nil
+	}
+	return field.ErrorList{
+		field.Invalid(fldPath, value, "forced failure: "+arg),
+	}
+}

staging/src/k8s.io/apimachinery/pkg/api/validate/testing_test.go

@@ -0,0 +1,144 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+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
+
+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 validate
+
+import (
+	"context"
+	"testing"
+
+	"k8s.io/apimachinery/pkg/api/operation"
+	"k8s.io/apimachinery/pkg/util/validation/field"
+	"k8s.io/utils/ptr"
+)
+
+func TestFixedResult(t *testing.T) {
+	cases := []struct {
+		value any
+		pass  bool
+	}{{
+		value: "",
+		pass:  false,
+	}, {
+		value: "",
+		pass:  true,
+	}, {
+		value: "nonempty",
+		pass:  false,
+	}, {
+		value: "nonempty",
+		pass:  true,
+	}, {
+		value: 0,
+		pass:  false,
+	}, {
+		value: 0,
+		pass:  true,
+	}, {
+		value: 1,
+		pass:  false,
+	}, {
+		value: 1,
+		pass:  true,
+	}, {
+		value: false,
+		pass:  false,
+	}, {
+		value: false,
+		pass:  true,
+	}, {
+		value: true,
+		pass:  false,
+	}, {
+		value: true,
+		pass:  true,
+	}, {
+		value: nil,
+		pass:  false,
+	}, {
+		value: nil,
+		pass:  true,
+	}, {
+		value: ptr.To(""),
+		pass:  false,
+	}, {
+		value: ptr.To(""),
+		pass:  true,
+	}, {
+		value: ptr.To("nonempty"),
+		pass:  false,
+	}, {
+		value: ptr.To("nonempty"),
+		pass:  true,
+	}, {
+		value: []string(nil),
+		pass:  false,
+	}, {
+		value: []string(nil),
+		pass:  true,
+	}, {
+		value: []string{},
+		pass:  false,
+	}, {
+		value: []string{},
+		pass:  true,
+	}, {
+		value: []string{"s"},
+		pass:  false,
+	}, {
+		value: []string{"s"},
+		pass:  true,
+	}, {
+		value: map[string]string(nil),
+		pass:  false,
+	}, {
+		value: map[string]string(nil),
+		pass:  true,
+	}, {
+		value: map[string]string{},
+		pass:  false,
+	}, {
+		value: map[string]string{},
+		pass:  true,
+	}, {
+		value: map[string]string{"k": "v"},
+		pass:  false,
+	}, {
+		value: map[string]string{"k": "v"},
+		pass:  true,
+	}}
+
+	for i, tc := range cases {
+		result := FixedResult(context.Background(), operation.Operation{}, field.NewPath("fldpath"), tc.value, nil, tc.pass, "detail string")
+		if len(result) != 0 && tc.pass {
+			t.Errorf("case %d: unexpected failure: %v", i, fmtErrs(result))
+			continue
+		}
+		if len(result) == 0 && !tc.pass {
+			t.Errorf("case %d: unexpected success", i)
+			continue
+		}
+		if len(result) > 0 {
+			if len(result) > 1 {
+				t.Errorf("case %d: unexepected multi-error: %v", i, fmtErrs(result))
+				continue
+			}
+			if want, got := "forced failure: detail string", result[0].Detail; got != want {
+				t.Errorf("case %d: wrong error, expected: %q, got: %q", i, want, got)
+			}
+		}
+	}
+}

staging/src/k8s.io/code-generator/cmd/validation-gen/output_tests/tags/README.md

@@ -0,0 +1,7 @@
+# Tag tests
+
+Tests in this directory are intended to validate specific tags, rather than
+general behavior of the code generator. Some tags are deeply integrated into
+the code-generation and will end up with similar tests elsewhere.
+
+These test cases should be as focused as possible.

staging/src/k8s.io/code-generator/cmd/validation-gen/output_tests/tags/validate_false/doc.go

@@ -0,0 +1,32 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+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
+
+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.
+*/
+
+// +k8s:validation-gen=TypeMeta
+// +k8s:validation-gen-scheme-registry=k8s.io/code-generator/cmd/validation-gen/testscheme.Scheme
+
+// This is a test package.
+package validatefalse
+
+import "k8s.io/code-generator/cmd/validation-gen/testscheme"
+
+var localSchemeBuilder = testscheme.New()
+
+type Struct struct {
+	TypeMeta int
+
+	// +k8s:validateFalse="field Struct.StringField"
+	StringField string `json:"stringField"`
+}

staging/src/k8s.io/code-generator/cmd/validation-gen/output_tests/tags/validate_false/doc_test.go

@@ -0,0 +1,37 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+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
+
+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 validatefalse
+
+import (
+	"testing"
+)
+
+func Test(t *testing.T) {
+	st := localSchemeBuilder.Test(t)
+
+	st.Value(&Struct{
+		// All zero-values.
+	}).ExpectValidateFalseByPath(map[string][]string{
+		"stringField": {"field Struct.StringField"},
+	})
+
+	st.Value(&Struct{
+		StringField: "abc",
+	}).ExpectValidateFalseByPath(map[string][]string{
+		"stringField": {"field Struct.StringField"},
+	})
+}