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

# Verification of `proto.MarshalOptions` in `google.golang.org/protobuf@v1.36.11`

This sample verifies the exact serialization behaviors, option flags, and buffer management provided by `google.golang.org/protobuf/proto.MarshalOptions`.

## Verified Semantics

1. **Partial Message Handling (`AllowPartial`)**:
   - When `AllowPartial` is `false` (default), attempting to serialize a message with unpopulated required fields returns an uninitialized error matching `proto.Error`.
   - When `AllowPartial` is `true`, `Marshal` succeeds and returns the partial wire bytes without error.

2. **Deterministic Serialization (`Deterministic`)**:
   - `proto.MarshalOptions{Deterministic: true}.Marshal(m)` guarantees byte-for-byte identical output across repeated serialization invocations by sorting map entries lexically by key.

3. **In-Place Buffer Appending (`MarshalAppend`)**:
   - `MarshalAppend(b, m)` serializes `m` and appends the resulting wire bytes directly onto existing byte buffer `b`, leaving the prefix unmodified.

4. **Wire Size Calculation (`Size`)**:
   - `Size(m)` computes the exact wire byte count matching `len(Marshal(m))`. Calling `Size(nil)` returns `0`.

5. **Cached Size Reuse (`UseCachedSize`)**:
   - When `UseCachedSize: true` is enabled, `Marshal` reuses cached sizes from a prior `Size` computation. Unmarshaling the generated bytes reconstructs the message identically.

6. **Nil Message Handling**:
   - `Marshal(nil)` safely returns an empty byte slice and `nil` 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.MarshalOptions 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.MarshalOptions

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:80e14369d8e06cf6be85cd517a82f26c49c65180a6698d913163651b5c8597a4","contract":["proto.MarshalOptions with AllowPartial: false rejects messages missing required fields by returning an uninitialized error matching proto.Error, whereas AllowPartial: true successfully marshals the partial wire format.","proto.MarshalOptions with Deterministic: true serializes map fields with sorted keys, producing byte-for-byte identical output across repeated runs.","proto.MarshalOptions.MarshalAppend appends wire-format bytes directly onto an existing byte buffer preserving the prefix content.","proto.MarshalOptions.Size calculates the exact encoded wire byte size of a message matching len(Marshal(m)) and returns 0 for nil messages.","proto.MarshalOptions with UseCachedSize: true reuses previously computed size to serialize messages without recomputing lengths.","proto.MarshalOptions.Marshal(nil) safely returns an empty byte slice with nil error."],"goal":"verify proto.MarshalOptions 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.MarshalOptions"]},"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.MarshalOptions"],"verifierAdapter":"golang@1"}

module example.com/protomarshaloptions

go 1.23

require google.golang.org/protobuf v1.36.11

github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package protomarshaloptions_test

import (
	"bytes"
	"errors"
	"testing"

	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/reflect/protodesc"
	"google.golang.org/protobuf/reflect/protoreflect"
	"google.golang.org/protobuf/types/descriptorpb"
	"google.golang.org/protobuf/types/dynamicpb"
	"google.golang.org/protobuf/types/known/structpb"
	"google.golang.org/protobuf/types/known/wrapperspb"
)

// buildRequiredFieldMessageSchema constructs a dynamic proto2 schema containing a required field.
func buildRequiredFieldMessageSchema(t *testing.T) protoreflect.MessageDescriptor {
	t.Helper()

	fd := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("required_test.proto"),
		Package: proto.String("example.test"),
		Syntax:  proto.String("proto2"),
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("RequiredMessage"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:   proto.String("id"),
						Number: proto.Int32(1),
						Label:  descriptorpb.FieldDescriptorProto_LABEL_REQUIRED.Enum(),
						Type:   descriptorpb.FieldDescriptorProto_TYPE_INT64.Enum(),
					},
					{
						Name:   proto.String("name"),
						Number: proto.Int32(2),
						Label:  descriptorpb.FieldDescriptorProto_LABEL_OPTIONAL.Enum(),
						Type:   descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
					},
				},
			},
		},
	}

	files, err := protodesc.NewFiles(&descriptorpb.FileDescriptorSet{
		File: []*descriptorpb.FileDescriptorProto{fd},
	})
	if err != nil {
		t.Fatalf("protodesc.NewFiles failed: %v", err)
	}

	desc, err := files.FindDescriptorByName("example.test.RequiredMessage")
	if err != nil {
		t.Fatalf("FindDescriptorByName failed: %v", err)
	}

	msgDesc, ok := desc.(protoreflect.MessageDescriptor)
	if !ok {
		t.Fatalf("expected MessageDescriptor, got %T", desc)
	}

	return msgDesc
}

// TestMarshalOptions_AllowPartial verifies that AllowPartial: false rejects incomplete messages
// with missing required fields (returning an error matching proto.Error and proto.CheckInitialized),
// while AllowPartial: true successfully serializes the partial wire bytes.
func TestMarshalOptions_AllowPartial(t *testing.T) {
	msgDesc := buildRequiredFieldMessageSchema(t)
	incompleteMsg := dynamicpb.NewMessage(msgDesc)

	// Set only the optional field "name", leaving the required field "id" unset.
	nameField := msgDesc.Fields().ByName("name")
	incompleteMsg.Set(nameField, protoreflect.ValueOfString("test-entity"))

	// Verify CheckInitialized fails on incomplete message
	if err := proto.CheckInitialized(incompleteMsg); err == nil {
		t.Fatal("expected proto.CheckInitialized to fail for unpopulated required field, got nil")
	}

	// 1. Default / AllowPartial: false must fail with proto.Error
	strictOpts := proto.MarshalOptions{AllowPartial: false}
	_, err := strictOpts.Marshal(incompleteMsg)
	if err == nil {
		t.Fatal("expected error when AllowPartial: false on message missing required fields, got nil")
	}
	if !errors.Is(err, proto.Error) {
		t.Fatalf("expected errors.Is(err, proto.Error), got: %v", err)
	}

	// 2. AllowPartial: true must succeed
	partialOpts := proto.MarshalOptions{AllowPartial: true}
	wireBytes, err := partialOpts.Marshal(incompleteMsg)
	if err != nil {
		t.Fatalf("AllowPartial: true failed to marshal incomplete message: %v", err)
	}
	if len(wireBytes) == 0 {
		t.Fatal("expected non-empty wire bytes for partial message")
	}

	// 3. Populate required field and verify AllowPartial: false succeeds
	idField := msgDesc.Fields().ByName("id")
	incompleteMsg.Set(idField, protoreflect.ValueOfInt64(12345))

	if err := proto.CheckInitialized(incompleteMsg); err != nil {
		t.Fatalf("proto.CheckInitialized failed on populated message: %v", err)
	}

	completeBytes, err := strictOpts.Marshal(incompleteMsg)
	if err != nil {
		t.Fatalf("strictOpts.Marshal failed on complete message: %v", err)
	}
	if len(completeBytes) <= len(wireBytes) {
		t.Fatalf("expected complete message bytes (%d) > partial bytes (%d)", len(completeBytes), len(wireBytes))
	}
}

// TestMarshalOptions_Deterministic verifies that Deterministic: true produces byte-for-byte
// identical output across multiple runs for messages containing maps.
func TestMarshalOptions_Deterministic(t *testing.T) {
	// Create a structpb.Struct with multiple keys
	fields := map[string]interface{}{
		"zeta":   "last",
		"alpha":  "first",
		"gamma":  "middle",
		"beta":   "second",
		"delta":  "fourth",
		"omega":  "end",
		"lambda": "core",
	}

	st, err := structpb.NewStruct(fields)
	if err != nil {
		t.Fatalf("structpb.NewStruct failed: %v", err)
	}

	opts := proto.MarshalOptions{Deterministic: true}

	var firstOutput []byte
	for i := 0; i < 50; i++ {
		out, err := opts.Marshal(st)
		if err != nil {
			t.Fatalf("iteration %d: Marshal failed: %v", i, err)
		}
		if i == 0 {
			firstOutput = out
		} else if !bytes.Equal(firstOutput, out) {
			t.Fatalf("iteration %d produced non-deterministic byte output", i)
		}
	}
}

// TestMarshalOptions_MarshalAppend verifies that MarshalAppend appends serialized proto bytes
// onto an existing destination slice without corrupting the prefix buffer.
func TestMarshalOptions_MarshalAppend(t *testing.T) {
	msg := wrapperspb.String("hello protobuf")
	opts := proto.MarshalOptions{}

	prefix := []byte("HEADER_PREFIX:")
	initialLen := len(prefix)

	result, err := opts.MarshalAppend(prefix, msg)
	if err != nil {
		t.Fatalf("MarshalAppend failed: %v", err)
	}

	if !bytes.HasPrefix(result, prefix) {
		t.Fatalf("expected result to start with prefix, got: %s", string(result[:initialLen]))
	}

	standalone, err := opts.Marshal(msg)
	if err != nil {
		t.Fatalf("standalone Marshal failed: %v", err)
	}

	appendedPart := result[initialLen:]
	if !bytes.Equal(appendedPart, standalone) {
		t.Fatalf("appended portion does not match standalone Marshal output")
	}
}

// TestMarshalOptions_Size verifies that Size returns the exact encoded byte count
// matching len(Marshal(m)), and handles nil messages by returning 0.
func TestMarshalOptions_Size(t *testing.T) {
	opts := proto.MarshalOptions{}

	// Nil message size
	if size := opts.Size(nil); size != 0 {
		t.Fatalf("expected Size(nil) == 0, got %d", size)
	}

	msg := wrapperspb.String("testing size calculation with arbitrary text payload")
	expectedSize := opts.Size(msg)

	marshaled, err := opts.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal failed: %v", err)
	}

	if expectedSize != len(marshaled) {
		t.Fatalf("expected Size (%d) == len(Marshal) (%d)", expectedSize, len(marshaled))
	}
}

// TestMarshalOptions_UseCachedSize verifies that Marshal with UseCachedSize: true works
// after size calculation and produces correct wire bytes matching unmarshal round-trip.
func TestMarshalOptions_UseCachedSize(t *testing.T) {
	msg := wrapperspb.String("cached size payload")

	// Call Size to compute and cache size
	calcOpts := proto.MarshalOptions{}
	size := calcOpts.Size(msg)

	cachedOpts := proto.MarshalOptions{UseCachedSize: true}
	marshaled, err := cachedOpts.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with UseCachedSize: true failed: %v", err)
	}

	if len(marshaled) != size {
		t.Fatalf("expected marshaled len (%d) == cached size (%d)", len(marshaled), size)
	}

	// Verify unmarshaling produces identical message
	recovered := &wrapperspb.StringValue{}
	if err := proto.Unmarshal(marshaled, recovered); err != nil {
		t.Fatalf("proto.Unmarshal failed: %v", err)
	}

	if !proto.Equal(msg, recovered) {
		t.Fatalf("recovered message does not equal original message")
	}
}

// TestMarshalOptions_NilMessage verifies that Marshal(nil) safely returns nil slice with no error.
func TestMarshalOptions_NilMessage(t *testing.T) {
	opts := proto.MarshalOptions{}
	b, err := opts.Marshal(nil)
	if err != nil {
		t.Fatalf("Marshal(nil) returned unexpected error: %v", err)
	}
	if len(b) != 0 {
		t.Fatalf("expected empty byte slice for nil message, got %v", b)
	}
}

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