feat: add +k8s:immutable tag with KEP semantics allowing unset -> set

Author: aaron-prindle

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

@@ -18,6 +18,7 @@ package validate
 
 import (
 	"context"
+	"reflect"
 
 	"k8s.io/apimachinery/pkg/api/equality"
 	"k8s.io/apimachinery/pkg/api/operation"
@@ -62,3 +63,162 @@ func FrozenByReflect[T any](_ context.Context, op operation.Operation, fldPath *
 	}
 	return nil
 }
+
+// ImmutableValueByCompare allows a field to be set
+// once then prevents any further changes.
+// Semantics:
+// - Zero value is considered "unset"
+// - Allows ONE transition: unset->set
+// - Forbids: modify and clear
+// This function is optimized for comparable types.
+// For non-comparable types use ImmutableByReflect instead.
+func ImmutableValueByCompare[T comparable](ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue *T) field.ErrorList {
+	return immutableCheck(op, fldPath, value, oldValue, func(v *T) bool {
+		if v == nil {
+			return true
+		}
+		var zero T
+		return *v == zero
+	})
+}
+
+// ImmutablePointerByCompare allows a field to be set
+// once then prevents any further changes.
+// Semantics:
+// - nil is considered "unset"
+// - Any non-nil pointer is considered "set" (incl. ptrs to zero values)
+// - Allows ONE transition: unset->set (nil -> non-nil)
+// - Forbids: modify and clear (non-nil -> nil)
+// This function is optimized for comparable types.
+// For non-comparable types, use ImmutableByReflect instead.
+func ImmutablePointerByCompare[T comparable](ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue *T) field.ErrorList {
+	return immutableCheck(op, fldPath, value, oldValue, func(v *T) bool {
+		return v == nil
+	})
+}
+
+// ImmutableByReflect  allows a field to be set
+// once then prevents any further changes.
+// Semantics:
+// - Can be unset at creation
+// - Allows ONE transition: set (unset->set)
+// - Forbids: modify and clear (set->unset)
+// Unlike ImmutableByCompare, this function can be
+// used with types that are not directly comparable
+// at the cost of performance.
+func ImmutableByReflect[T any](_ context.Context, op operation.Operation, fldPath *field.Path, value, oldValue T) field.ErrorList {
+	if op.Type != operation.Update {
+		return nil
+	}
+
+	valueIsUnset := isUnsetForImmutable(value)
+	oldValueIsUnset := isUnsetForImmutable(oldValue)
+
+	if oldValueIsUnset && valueIsUnset {
+		return nil
+	}
+	if !oldValueIsUnset && !valueIsUnset && equality.Semantic.DeepEqual(value, oldValue) {
+		return nil
+	}
+
+	switch {
+	case oldValueIsUnset && !valueIsUnset:
+		return nil
+	case !oldValueIsUnset && valueIsUnset:
+		return field.ErrorList{
+			field.Forbidden(fldPath, "field is immutable"),
+		}
+	case !oldValueIsUnset && !valueIsUnset:
+		return field.ErrorList{
+			field.Forbidden(fldPath, "field is immutable"),
+		}
+	default:
+		// Both unset, shouldn't happen since we checked equality
+		return nil
+	}
+}
+
+func immutableCheck[T comparable](op operation.Operation, fldPath *field.Path,
+	value, oldValue *T,
+	isUnset func(*T) bool,
+) field.ErrorList {
+	if op.Type != operation.Update {
+		return nil
+	}
+
+	if value == nil && oldValue == nil {
+		return nil
+	}
+	if oldValue == nil {
+		return nil
+	}
+	if value == nil {
+		return field.ErrorList{
+			field.Forbidden(fldPath, "field is immutable"),
+		}
+	}
+
+	if *value == *oldValue {
+		return nil
+	}
+
+	oldIsUnset := isUnset(oldValue)
+	newIsUnset := isUnset(value)
+
+	switch {
+	case oldIsUnset && !newIsUnset:
+		return nil
+	case !oldIsUnset && newIsUnset:
+		return field.ErrorList{
+			field.Forbidden(fldPath, "field is immutable"),
+		}
+	case !oldIsUnset && !newIsUnset:
+		return field.ErrorList{
+			field.Forbidden(fldPath, "field is immutable"),
+		}
+	default:
+		// Both unset, shouldn't happen since we checked equality
+		return nil
+	}
+}
+
+// isUnsetForImmutable determines if a value should
+// be considered "unset" for immutability.
+func isUnsetForImmutable(value interface{}) bool {
+	if value == nil {
+		return true
+	}
+
+	v := reflect.ValueOf(value)
+
+	if v.Kind() == reflect.Ptr {
+		if v.IsNil() {
+			return true
+		}
+		elem := v.Elem()
+
+		// If this is a pointer to a struct, check if the struct is zero
+		if elem.Kind() == reflect.Struct {
+			zero := reflect.Zero(elem.Type())
+			return reflect.DeepEqual(elem.Interface(), zero.Interface())
+		}
+
+		// For pointers to other types, being non-nil means it's set.
+		// Aligns with +k8s:required behavior for pointer fields.
+		return false
+	}
+
+	switch v.Kind() {
+	case reflect.Slice, reflect.Map:
+		return v.IsNil() || v.Len() == 0
+	case reflect.String:
+		return v.String() == ""
+	case reflect.Struct:
+		return reflect.DeepEqual(v.Interface(), reflect.Zero(v.Type()).Interface())
+	case reflect.Interface:
+		return v.IsNil()
+	default:
+		// For other types check if it's the zero value.
+		return v.Interface() == reflect.Zero(v.Type()).Interface()
+	}
+}

staging/src/k8s.io/code-generator/cmd/validation-gen/output_tests/tags/frozen/zz_generated.validations.go

@@ -17,6 +17,12 @@ limitations under the License.
 package validators
 
 import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+
+	"k8s.io/code-generator/cmd/validation-gen/util"
+	"k8s.io/gengo/v2"
 	"k8s.io/gengo/v2/types"
 )
 
@@ -34,3 +40,68 @@ func rootTypeString(src, dst *types.Type) string {
 	}
 	return src.String() + " -> " + dst.String()
 }
+
+// hasZeroDefault returns whether the field has a default value and whether
+// that default value is the zero value for the field's type.
+func hasZeroDefault(context Context) (bool, bool, error) {
+	t := util.NonPointer(util.NativeType(context.Type))
+	// This validator only applies to fields, so Member must be valid.
+	tagsByName, err := gengo.ExtractFunctionStyleCommentTags("+", []string{defaultTagName}, context.Member.CommentLines)
+	if err != nil {
+		return false, false, fmt.Errorf("failed to read tags: %w", err)
+	}
+
+	tags, hasDefault := tagsByName[defaultTagName]
+	if !hasDefault {
+		return false, false, nil
+	}
+	if len(tags) == 0 {
+		return false, false, fmt.Errorf("+default tag with no value")
+	}
+	if len(tags) > 1 {
+		return false, false, fmt.Errorf("+default tag with multiple values: %q", tags)
+	}
+
+	payload := tags[0].Value
+	var defaultValue any
+	if err := json.Unmarshal([]byte(payload), &defaultValue); err != nil {
+		return false, false, fmt.Errorf("failed to parse default value %q: %w", payload, err)
+	}
+	if defaultValue == nil {
+		return false, false, fmt.Errorf("failed to parse default value %q: unmarshalled to nil", payload)
+	}
+
+	zero, found := typeZeroValue[t.String()]
+	if !found {
+		return false, false, fmt.Errorf("unknown zero-value for type %s", t.String())
+	}
+
+	return true, reflect.DeepEqual(defaultValue, zero), nil
+}
+
+// This is copied from defaulter-gen.
+// TODO: move this back to gengo as Type.ZeroValue()?
+var typeZeroValue = map[string]any{
+	"uint":        0.,
+	"uint8":       0.,
+	"uint16":      0.,
+	"uint32":      0.,
+	"uint64":      0.,
+	"int":         0.,
+	"int8":        0.,
+	"int16":       0.,
+	"int32":       0.,
+	"int64":       0.,
+	"byte":        0.,
+	"float64":     0.,
+	"float32":     0.,
+	"bool":        false,
+	"time.Time":   "",
+	"string":      "",
+	"integer":     0.,
+	"number":      0.,
+	"boolean":     false,
+	"[]byte":      "", // base64 encoded characters
+	"interface{}": interface{}(nil),
+	"any":         interface{}(nil),
+}

staging/src/k8s.io/code-generator/cmd/validation-gen/validators/common.go

@@ -24,11 +24,13 @@ import (
 )
 
 const (
-	frozenTagName = "k8s:frozen"
+	frozenTagName    = "k8s:frozen"
+	immutableTagName = "k8s:immutable"
 )
 
 func init() {
 	RegisterTagValidator(frozenTagValidator{})
+	RegisterTagValidator(immutableTagValidator{})
 }
 
 type frozenTagValidator struct{}
@@ -54,11 +56,6 @@ func (frozenTagValidator) GetValidations(context Context, _ codetags.Tag) (Valid
 	var result Validations
 
 	if util.IsDirectComparable(util.NonPointer(util.NativeType(context.Type))) {
-		// This is a minor optimization to just compare primitive values when
-		// possible. Slices and maps are not comparable, and structs might hold
-		// pointer fields, which are directly comparable but not what we need.
-		//
-		// Note: This compares the pointee, not the pointer itself.
 		result.AddFunction(Function(frozenTagName, DefaultFlags, frozenCompareValidator))
 	} else {
 		result.AddFunction(Function(frozenTagName, DefaultFlags, frozenReflectValidator))
@@ -74,3 +71,69 @@ func (ftv frozenTagValidator) Docs() TagDoc {
 		Description: "Indicates that a field may not be updated.",
 	}
 }
+
+type immutableTagValidator struct{}
+
+func (immutableTagValidator) Init(_ Config) {}
+
+func (immutableTagValidator) TagName() string {
+	return immutableTagName
+}
+
+var immutableTagValidScopes = sets.New(ScopeField, ScopeType, ScopeMapVal, ScopeListVal)
+
+func (immutableTagValidator) ValidScopes() sets.Set[Scope] {
+	return immutableTagValidScopes
+}
+
+var (
+	immutableValueByCompareValidator   = types.Name{Package: libValidationPkg, Name: "ImmutableValueByCompare"}
+	immutablePointerByCompareValidator = types.Name{Package: libValidationPkg, Name: "ImmutablePointerByCompare"}
+	immutableReflectValidator          = types.Name{Package: libValidationPkg, Name: "ImmutableByReflect"}
+)
+
+func (itv immutableTagValidator) GetValidations(context Context, _ codetags.Tag) (Validations, error) {
+	var result Validations
+
+	// If validating a field, check for default value.
+	if context.Member != nil {
+		if hasDefault, zeroDefault, err := hasZeroDefault(context); err != nil {
+			return Validations{}, err
+		} else if hasDefault && zeroDefault {
+			result.AddComment("Zero-value defaults are treated as 'unset' by immutable validation.")
+		} else if hasDefault && !zeroDefault {
+			result.AddComment("Non-zero defaults are 'always set' and cannot transition from unset to set.")
+		}
+	}
+
+	if !util.IsDirectComparable(util.NonPointer(util.NativeType(context.Type))) {
+		result.AddFunction(Function(immutableTagName, DefaultFlags, immutableReflectValidator))
+		return result, nil
+	}
+
+	isPointerField := false
+	if context.Member != nil {
+		memberType := context.Member.Type
+		if memberType != nil && memberType.Kind == types.Pointer {
+			isPointerField = true
+		}
+	} else if util.NativeType(context.Type).Kind == types.Pointer {
+		isPointerField = true
+	}
+
+	if isPointerField {
+		result.AddFunction(Function(immutableTagName, DefaultFlags, immutablePointerByCompareValidator))
+	} else {
+		result.AddFunction(Function(immutableTagName, DefaultFlags, immutableValueByCompareValidator))
+	}
+
+	return result, nil
+}
+
+func (itv immutableTagValidator) Docs() TagDoc {
+	return TagDoc{
+		Tag:         itv.TagName(),
+		Scopes:      itv.ValidScopes().UnsortedList(),
+		Description: "Indicates that a field can be set once (now or at creation), then becomes immutable. Allows transition from unset to set, but forbids modify or clear operations. Fields with default values are considered already set.",
+	}
+}