google.golang.org/protobuf v1.36.4: proto.Merge

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 google.golang.org/protobuf/proto.Merge in pkg:golang/google.golang.org/protobuf@v1.36.4
Kind: HOW

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

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.

{"case":{"caseId":"case:sha256:cb8cf661c7b015674667e6db297c259b817d06539489f105edf77d5734b386dd","contract":["proto.Merge copies populated scalar fields from src into dst while preserving dst scalar values when src fields hold implicit default zero values","proto.Merge appends repeated slice elements from src onto dst in order rather than replacing the slice","proto.Merge overwrites dst when src explicitly sets a proto3_optional field to zero, recursively merges singular nested messages, and replaces map entry values for matching keys","proto.Merge is a no-op for a typed-nil src of matching type and panics when dst and src have different message descriptors"],"goal":"verify google.golang.org/protobuf/proto.Merge in pkg:golang/google.golang.org/protobuf@v1.36.4","kind":"HOW","packages":["pkg:golang/google.golang.org/protobuf@v1.36.4"],"schemaVersion":1,"symbols":["google.golang.org/protobuf/proto.Merge"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/google.golang.org/protobuf@v1.36.4"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/protobuf@v1.36.4","symbols":["google.golang.org/protobuf/proto.Merge"],"verifierAdapter":"golang@1"}

module sample

go 1.23

require google.golang.org/protobuf v1.36.4

github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/protobuf v1.36.4 h1:6A3ZDJHn/eNqc1i+IdefRzy/9PokBTPvcqMySR7NNIM=
google.golang.org/protobuf v1.36.4/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=

package main

import (
	"fmt"
	"os"

	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/known/durationpb"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

func main() {
	dstDur := &durationpb.Duration{Seconds: 60, Nanos: 100}
	srcDur := &durationpb.Duration{Nanos: 250}
	proto.Merge(dstDur, srcDur)
	if dstDur.Seconds != 60 || dstDur.Nanos != 250 {
		fmt.Fprintf(os.Stderr, "unexpected merged duration: %v\n", dstDur)
		os.Exit(1)
	}

	dstMask := &fieldmaskpb.FieldMask{Paths: []string{"a", "b"}}
	srcMask := &fieldmaskpb.FieldMask{Paths: []string{"c"}}
	proto.Merge(dstMask, srcMask)
	if len(dstMask.Paths) != 3 {
		fmt.Fprintf(os.Stderr, "unexpected merged paths: %v\n", dstMask.Paths)
		os.Exit(1)
	}

	fmt.Printf("Verified proto.Merge: seconds=%d nanos=%d paths=%v\n", dstDur.Seconds, dstDur.Nanos, dstMask.Paths)
}

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

package main

import (
	"fmt"
	"os"
	"reflect"

	"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"
	"google.golang.org/protobuf/types/known/durationpb"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
	"google.golang.org/protobuf/types/known/wrapperspb"
)

func buildDynamicSchema() (protoreflect.MessageDescriptor, protoreflect.MessageDescriptor, error) {
	fd := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("merge_contract.proto"),
		Package: proto.String("example.merge"),
		Syntax:  proto.String("proto3"),
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("SubConfig"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("host"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						JsonName: proto.String("host"),
					},
					{
						Name:     proto.String("port"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName: proto.String("port"),
					},
				},
			},
			{
				Name: proto.String("AppConfig"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("timeout"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName: proto.String("timeout"),
					},
					{
						Name:           proto.String("retries"),
						Number:         proto.Int32(2),
						Type:           descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName:       proto.String("retries"),
						Proto3Optional: proto.Bool(true),
						OneofIndex:     proto.Int32(0),
					},
					{
						Name:     proto.String("primary"),
						Number:   proto.Int32(3),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.merge.SubConfig"),
						JsonName: proto.String("primary"),
					},
					{
						Name:     proto.String("routes"),
						Number:   proto.Int32(4),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.merge.AppConfig.RoutesEntry"),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REPEATED.Enum(),
						JsonName: proto.String("routes"),
					},
				},
				NestedType: []*descriptorpb.DescriptorProto{
					{
						Name: proto.String("RoutesEntry"),
						Field: []*descriptorpb.FieldDescriptorProto{
							{
								Name:     proto.String("key"),
								Number:   proto.Int32(1),
								Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
								JsonName: proto.String("key"),
							},
							{
								Name:     proto.String("value"),
								Number:   proto.Int32(2),
								Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
								TypeName: proto.String(".example.merge.SubConfig"),
								JsonName: proto.String("value"),
							},
						},
						Options: &descriptorpb.MessageOptions{
							MapEntry: proto.Bool(true),
						},
					},
				},
				OneofDecl: []*descriptorpb.OneofDescriptorProto{
					{
						Name: proto.String("_retries"),
					},
				},
			},
		},
	}

	fileDesc, err := protodesc.NewFile(fd, protoregistry.GlobalFiles)
	if err != nil {
		return nil, nil, err
	}
	appDesc := fileDesc.Messages().ByName("AppConfig")
	subDesc := fileDesc.Messages().ByName("SubConfig")
	return appDesc, subDesc, nil
}

func main() {
	// Assertion 1: proto.Merge updates populated scalar fields from src while leaving dst fields unchanged when src holds implicit default zero values
	{
		dst := &durationpb.Duration{Seconds: 120, Nanos: 100}
		src := &durationpb.Duration{Nanos: 900}
		proto.Merge(dst, src)

		if dst.Seconds != 120 || dst.Nanos != 900 {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected Seconds=120 Nanos=900, got Seconds=%d Nanos=%d\n", dst.Seconds, dst.Nanos)
			os.Exit(1)
		}

		// Merging a typed-nil source message of the same concrete type is a no-op
		var nilSrc *durationpb.Duration
		proto.Merge(dst, nilSrc)
		if dst.Seconds != 120 || dst.Nanos != 900 {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: merging typed nil modified dst: %v\n", dst)
			os.Exit(1)
		}
	}

	// Assertion 2: proto.Merge appends repeated slice elements from src onto dst in order rather than replacing the slice
	{
		dst := &fieldmaskpb.FieldMask{Paths: []string{"user.id", "user.email"}}
		src := &fieldmaskpb.FieldMask{Paths: []string{"user.name", "user.id"}}
		proto.Merge(dst, src)

		expected := []string{"user.id", "user.email", "user.name", "user.id"}
		if !reflect.DeepEqual(dst.Paths, expected) {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected %v, got %v\n", expected, dst.Paths)
			os.Exit(1)
		}
	}

	// Assertion 3: proto.Merge overwrites dst when src explicitly sets a proto3_optional field to zero, recursively merges singular nested messages, and replaces map entry values for matching keys
	{
		appDesc, subDesc, err := buildDynamicSchema()
		if err != nil {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: schema error: %v\n", err)
			os.Exit(1)
		}

		timeoutField := appDesc.Fields().ByName("timeout")
		retriesField := appDesc.Fields().ByName("retries")
		primaryField := appDesc.Fields().ByName("primary")
		routesField := appDesc.Fields().ByName("routes")
		hostField := subDesc.Fields().ByName("host")
		portField := subDesc.Fields().ByName("port")

		dst := dynamicpb.NewMessage(appDesc)
		dst.Set(timeoutField, protoreflect.ValueOfInt32(3000))
		dst.Set(retriesField, protoreflect.ValueOfInt32(5))

		dstPrimary := dst.Mutable(primaryField).Message()
		dstPrimary.Set(hostField, protoreflect.ValueOfString("primary.example.com"))
		dstPrimary.Set(portField, protoreflect.ValueOfInt32(8080))

		dstRoutes := dst.Mutable(routesField).Map()
		routeA := dynamicpb.NewMessage(subDesc)
		routeA.Set(hostField, protoreflect.ValueOfString("a.example.com"))
		routeA.Set(portField, protoreflect.ValueOfInt32(8000))
		dstRoutes.Set(protoreflect.ValueOfString("svc-a").MapKey(), protoreflect.ValueOfMessage(routeA))

		src := dynamicpb.NewMessage(appDesc)
		// timeout is left unset (implicit 0), retries is explicitly set to 0 (proto3_optional)
		src.Set(retriesField, protoreflect.ValueOfInt32(0))

		srcPrimary := src.Mutable(primaryField).Message()
		srcPrimary.Set(portField, protoreflect.ValueOfInt32(9090))

		srcRoutes := src.Mutable(routesField).Map()
		routeAOverride := dynamicpb.NewMessage(subDesc)
		routeAOverride.Set(portField, protoreflect.ValueOfInt32(8001))
		srcRoutes.Set(protoreflect.ValueOfString("svc-a").MapKey(), protoreflect.ValueOfMessage(routeAOverride))

		proto.Merge(dst, src)

		if got := dst.Get(timeoutField).Int(); got != 3000 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected timeout=3000, got %d\n", got)
			os.Exit(1)
		}
		if got := dst.Get(retriesField).Int(); got != 0 || !dst.ProtoReflect().Has(retriesField) {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected explicit 0 retries to overwrite dst, got %d (has=%v)\n", got, dst.ProtoReflect().Has(retriesField))
			os.Exit(1)
		}

		mergedPrimary := dst.Get(primaryField).Message()
		if mergedPrimary.Get(hostField).String() != "primary.example.com" || mergedPrimary.Get(portField).Int() != 9090 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: singular message not recursively merged: host=%q port=%d\n", mergedPrimary.Get(hostField).String(), mergedPrimary.Get(portField).Int())
			os.Exit(1)
		}

		mergedRouteA := dst.Get(routesField).Map().Get(protoreflect.ValueOfString("svc-a").MapKey()).Message()
		if mergedRouteA.Get(hostField).String() != "" || mergedRouteA.Get(portField).Int() != 8001 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: map entry value should be replaced rather than recursively merged, got host=%q port=%d\n", mergedRouteA.Get(hostField).String(), mergedRouteA.Get(portField).Int())
			os.Exit(1)
		}
	}

	// Assertion 4: proto.Merge panics when dst and src have different message descriptors
	{
		panicked := false
		func() {
			defer func() {
				if r := recover(); r != nil {
					panicked = true
				}
			}()
			var dst proto.Message = wrapperspb.String("hello")
			var src proto.Message = wrapperspb.Int32(42)
			proto.Merge(dst, src)
		}()
		if !panicked {
			fmt.Fprintln(os.Stderr, "assertion 4 failed: expected proto.Merge to panic on mismatched message descriptors")
			os.Exit(1)
		}
	}

	fmt.Println("All proto.Merge contract assertions passed.")
}