google.golang.org/protobuf v1.36.11: proto.CheckInitialized

# Protocol Buffers Required Field Initialization (`proto.CheckInitialized`)

This sample tests and verifies message initialization checking behaviors in `google.golang.org/protobuf` pinned to release `v1.36.11`.

## Verified Semantics

1. **Nil Message Handling**:
   - `proto.CheckInitialized(nil)` safely returns `nil` without panic.

2. **Proto3 Message Initialization**:
   - Proto3 messages do not have required fields. Unpopulated proto3 messages always satisfy initialization and `proto.CheckInitialized` returns `nil`.

3. **Proto2 Required Scalar Fields**:
   - For proto2 messages with fields labeled `required`, `proto.CheckInitialized` returns a non-nil error identifying the missing field name if any required field is unpopulated.
   - Once all required fields are populated, `proto.CheckInitialized` returns `nil`.

4. **Nested and Repeated Message Validation**:
   - Populated submessages with unset required fields cause `proto.CheckInitialized` on the parent message to fail, naming the nested missing required field.
   - Unset optional submessages are ignored and do not cause initialization failures.
   - Repeated message slices are scanned element-by-element; if any item contains unset required fields, `proto.CheckInitialized` fails.

5. **Extension Field Validation**:
   - If an extension field containing a message with required fields is populated and uninitialized, `proto.CheckInitialized` returns an error.
   - Unpopulated extensions do not trigger initialization errors.

6. **Wire Serialization Enforcement**:
   - `proto.Marshal` strictly validates initialization and returns an error when required fields are missing.
   - `proto.MarshalOptions{AllowPartial: true}.Marshal` allows serializing uninitialized messages without raising an error.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify proto.CheckInitialized in pkg:golang/google.golang.org/protobuf@v1.36.11
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/protobuf@v1.36.11
Demonstrate these symbols/APIs:
  - proto.CheckInitialized

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package checkinitialized_test

import (
	"strings"
	"testing"

	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/reflect/protodesc"
	"google.golang.org/protobuf/reflect/protoreflect"
	"google.golang.org/protobuf/reflect/protoregistry"
	"google.golang.org/protobuf/types/descriptorpb"
	"google.golang.org/protobuf/types/dynamicpb"
)

func buildSchema(t *testing.T) (*descriptorpb.FileDescriptorProto, protoreflect.FileDescriptor) {
	t.Helper()

	fd := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("check_test.proto"),
		Package: proto.String("example.check"),
		Syntax:  proto.String("proto2"),
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("InnerMessage"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("inner_required_id"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT64.Enum(),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REQUIRED.Enum(),
						JsonName: proto.String("innerRequiredId"),
					},
					{
						Name:     proto.String("inner_optional_name"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
						JsonName: proto.String("innerOptionalName"),
					},
				},
			},
			{
				Name: proto.String("OuterMessage"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("required_title"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REQUIRED.Enum(),
						JsonName: proto.String("requiredTitle"),
					},
					{
						Name:     proto.String("optional_inner"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.check.InnerMessage"),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
						JsonName: proto.String("optionalInner"),
					},
					{
						Name:     proto.String("repeated_inners"),
						Number:   proto.Int32(3),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.check.InnerMessage"),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REPEATED.Enum(),
						JsonName: proto.String("repeatedInners"),
					},
				},
				ExtensionRange: []*descriptorpb.DescriptorProto_ExtensionRange{
					{
						Start: proto.Int32(100),
						End:   proto.Int32(200),
					},
				},
			},
		},
		Extension: []*descriptorpb.FieldDescriptorProto{
			{
				Name:     proto.String("ext_inner"),
				Number:   proto.Int32(100),
				Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
				TypeName: proto.String(".example.check.InnerMessage"),
				Extendee: proto.String(".example.check.OuterMessage"),
				Label:    descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
				JsonName: proto.String("extInner"),
			},
		},
	}

	files := new(protoregistry.Files)
	fileDesc, err := protodesc.NewFile(fd, files)
	if err != nil {
		t.Fatalf("protodesc.NewFile proto2 failed: %v", err)
	}

	return fd, fileDesc
}

func TestCheckInitialized_Nil(t *testing.T) {
	var nilMsg proto.Message
	if err := proto.CheckInitialized(nilMsg); err != nil {
		t.Fatalf("expected CheckInitialized(nil) to return nil, got %v", err)
	}
}

func TestCheckInitialized_Proto3(t *testing.T) {
	files := new(protoregistry.Files)
	fd3 := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("proto3_standalone.proto"),
		Package: proto.String("example.proto3"),
		Syntax:  proto.String("proto3"),
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("SimpleProto3"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("val"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						JsonName: proto.String("val"),
					},
				},
			},
		},
	}
	f3, err := protodesc.NewFile(fd3, files)
	if err != nil {
		t.Fatalf("protodesc.NewFile proto3 failed: %v", err)
	}
	simpleDesc := f3.Messages().ByName("SimpleProto3")
	msg := dynamicpb.NewMessage(simpleDesc)

	// Proto3 has no required fields; unpopulated message is always initialized
	if err := proto.CheckInitialized(msg); err != nil {
		t.Fatalf("expected unpopulated proto3 message to return nil, got %v", err)
	}
}

func TestCheckInitialized_Proto2RequiredFields(t *testing.T) {
	_, fileDesc := buildSchema(t)
	innerDesc := fileDesc.Messages().ByName("InnerMessage")
	innerRequiredId := innerDesc.Fields().ByName("inner_required_id")

	// 1. Missing required field on single proto2 message
	inner := dynamicpb.NewMessage(innerDesc)
	err := proto.CheckInitialized(inner)
	if err == nil {
		t.Fatalf("expected error when inner_required_id is missing, got nil")
	}
	if !strings.Contains(err.Error(), "inner_required_id") {
		t.Errorf("expected error to mention 'inner_required_id', got %q", err.Error())
	}

	// 2. Populating required field resolves the error
	inner.Set(innerRequiredId, protoreflect.ValueOfInt64(1001))
	if err := proto.CheckInitialized(inner); err != nil {
		t.Fatalf("expected initialized inner message to return nil, got %v", err)
	}
}

func TestCheckInitialized_NestedAndRepeatedMessages(t *testing.T) {
	_, fileDesc := buildSchema(t)
	innerDesc := fileDesc.Messages().ByName("InnerMessage")
	outerDesc := fileDesc.Messages().ByName("OuterMessage")

	innerRequiredId := innerDesc.Fields().ByName("inner_required_id")
	outerRequiredTitle := outerDesc.Fields().ByName("required_title")
	outerOptionalInner := outerDesc.Fields().ByName("optional_inner")
	outerRepeatedInners := outerDesc.Fields().ByName("repeated_inners")

	outer := dynamicpb.NewMessage(outerDesc)
	outer.Set(outerRequiredTitle, protoreflect.ValueOfString("Config Document"))

	// 1. Unpopulated optional child message does NOT cause initialization failure
	if err := proto.CheckInitialized(outer); err != nil {
		t.Fatalf("expected outer with unset optional child to pass CheckInitialized, got %v", err)
	}

	// 2. Populating optional child with uninitialized message causes CheckInitialized failure
	uninitChild := dynamicpb.NewMessage(innerDesc)
	outer.Set(outerOptionalInner, protoreflect.ValueOfMessage(uninitChild))
	if err := proto.CheckInitialized(outer); err == nil {
		t.Fatalf("expected CheckInitialized to fail when populated optional child is uninitialized")
	}

	// Initializing the child fixes it
	uninitChild.Set(innerRequiredId, protoreflect.ValueOfInt64(2002))
	if err := proto.CheckInitialized(outer); err != nil {
		t.Fatalf("expected CheckInitialized to pass when child is initialized, got %v", err)
	}

	// 3. Repeated message field with uninitialized element causes CheckInitialized failure
	outer.Clear(outerOptionalInner)
	repList := outer.Mutable(outerRepeatedInners).List()

	validItem := dynamicpb.NewMessage(innerDesc)
	validItem.Set(innerRequiredId, protoreflect.ValueOfInt64(3001))
	invalidItem := dynamicpb.NewMessage(innerDesc)

	repList.Append(protoreflect.ValueOfMessage(validItem))
	repList.Append(protoreflect.ValueOfMessage(invalidItem))

	if err := proto.CheckInitialized(outer); err == nil {
		t.Fatalf("expected CheckInitialized to fail when repeated slice has uninitialized item")
	}

	invalidItem.Set(innerRequiredId, protoreflect.ValueOfInt64(3002))
	if err := proto.CheckInitialized(outer); err != nil {
		t.Fatalf("expected CheckInitialized to pass when all repeated items are initialized, got %v", err)
	}
}

func TestCheckInitialized_Extensions(t *testing.T) {
	_, fileDesc := buildSchema(t)
	outerDesc := fileDesc.Messages().ByName("OuterMessage")
	innerDesc := fileDesc.Messages().ByName("InnerMessage")
	extDesc := fileDesc.Extensions().ByName("ext_inner")
	innerRequiredId := innerDesc.Fields().ByName("inner_required_id")
	outerRequiredTitle := outerDesc.Fields().ByName("required_title")

	extType := dynamicpb.NewExtensionType(extDesc)

	msg := dynamicpb.NewMessage(outerDesc)
	msg.Set(outerRequiredTitle, protoreflect.ValueOfString("Extended Message"))

	// Unset extension -> initialized
	if err := proto.CheckInitialized(msg); err != nil {
		t.Fatalf("expected unset extension to be initialized: %v", err)
	}

	// Set extension with uninitialized content -> CheckInitialized fails
	uninitExt := dynamicpb.NewMessage(innerDesc)
	proto.SetExtension(msg, extType, uninitExt)

	if err := proto.CheckInitialized(msg); err == nil {
		t.Fatalf("expected CheckInitialized to fail when extension has uninitialized message")
	}

	// Populate required field in extension -> CheckInitialized passes
	uninitExt.Set(innerRequiredId, protoreflect.ValueOfInt64(9999))
	if err := proto.CheckInitialized(msg); err != nil {
		t.Fatalf("expected CheckInitialized to pass when extension message is initialized: %v", err)
	}
}

func TestCheckInitialized_MarshalEnforcement(t *testing.T) {
	_, fileDesc := buildSchema(t)
	innerDesc := fileDesc.Messages().ByName("InnerMessage")
	innerRequiredId := innerDesc.Fields().ByName("inner_required_id")

	uninitMsg := dynamicpb.NewMessage(innerDesc)

	// Standard proto.Marshal validates initialization and fails
	_, err := proto.Marshal(uninitMsg)
	if err == nil {
		t.Fatalf("expected proto.Marshal to fail on uninitialized message")
	}

	// proto.MarshalOptions{AllowPartial: true} allows marshaling uninitialized messages
	opts := proto.MarshalOptions{AllowPartial: true}
	wire, err := opts.Marshal(uninitMsg)
	if err != nil {
		t.Fatalf("expected Marshal with AllowPartial: true to succeed, got %v", err)
	}
	if len(wire) != 0 {
		t.Errorf("expected empty wire bytes for empty message, got %d bytes", len(wire))
	}

	// When initialized, standard Marshal succeeds
	uninitMsg.Set(innerRequiredId, protoreflect.ValueOfInt64(42))
	wire, err = proto.Marshal(uninitMsg)
	if err != nil {
		t.Fatalf("expected proto.Marshal to succeed for initialized message, got %v", err)
	}
	if len(wire) == 0 {
		t.Errorf("expected non-empty wire bytes for initialized message")
	}
}

{"case":{"caseId":"case:sha256:15cbfa880fa40ded13981fa0fb2539b95e63ed7fa2fd298448bb15b3a8b24900","constraints":{"executionContext":"go"},"contract":["proto.CheckInitialized returns nil for nil message pointers without error.","proto.CheckInitialized returns nil for proto3 messages since proto3 schemas contain no required fields.","proto.CheckInitialized returns an error naming the missing field when proto2 required scalar fields are unset, and returns nil once set.","proto.CheckInitialized recursively validates populated child messages and repeated message elements for missing required fields while ignoring unpopulated optional child messages.","proto.CheckInitialized returns an error when an extension contains uninitialized required message fields.","proto.Marshal enforces message initialization by returning an error on uninitialized messages, while proto.MarshalOptions with AllowPartial: true permits serialization."],"goal":"verify proto.CheckInitialized in pkg:golang/google.golang.org/protobuf@v1.36.11","kind":"HOW","packages":["pkg:golang/google.golang.org/protobuf@v1.36.11"],"schemaVersion":1,"symbols":["proto.CheckInitialized"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/google.golang.org/protobuf@v1.36.11"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/protobuf@v1.36.11","symbols":["proto.CheckInitialized"],"verifierAdapter":"golang@1"}

module example.com/checkinitialized

go 1.26.6

require google.golang.org/protobuf v1.36.11

google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

{
  "schemaVersion": 1,
  "goal": "verify proto.CheckInitialized in pkg:golang/google.golang.org/protobuf@v1.36.11",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/protobuf@v1.36.11"
  ],
  "symbols": [
    "proto.CheckInitialized"
  ]
}