google.golang.org/protobuf v1.28.0: Text format serialization, multiline formatting, indentation, and unknown field discarding in Protocol Buffers

# Protocol Buffers Text Format Serialization and Parsing

A known-solution search for `pkg:golang/google.golang.org/protobuf@v1.28.0` identified existing samples for JSON serialization (`protojson`), gRPC payload/interceptor limits, and core message lifecycle operations (`proto.Merge`, `proto.Clone`, `proto.Equal`, `proto.Reset`). A specific query for `prototext.Marshal`, `prototext.MarshalOptions`, `prototext.Unmarshal`, and `prototext.UnmarshalOptions` returned no safe match.

This sample tests and verifies text format encoding and decoding semantics in `google.golang.org/protobuf` pinned to release `v1.28.0`.

## Observed Behavior

1. **Default Text Formatting (`prototext.Marshal`)**:
   - `prototext.Marshal` encodes messages into a compact single-line text representation without newlines.
   - Enum fields are emitted using their symbolic identifier names (e.g. `log_level:INFO`) rather than integer values.
   - Unpopulated scalar fields with default zero values are omitted.

2. **Multiline and Indented Output (`prototext.MarshalOptions`)**:
   - Setting `Multiline: true` in `prototext.MarshalOptions` formats the output across multiple lines with proper nesting and newlines.
   - Setting `EmitUnknown: true` causes wire-format unknown fields stored in the message to be emitted in text format (e.g. `999: "..."`), whereas default `prototext.Marshal` suppresses unknown fields.

3. **Text Format Parsing and Comment Support (`prototext.Unmarshal`)**:
   - `prototext.Unmarshal` parses standard protobuf text format strings into message descriptors.
   - Comments beginning with `#` are supported throughout the input payload.
   - When encountering unknown or unrecognized field names, default `prototext.Unmarshal` rejects the input with an unknown field error.

4. **Unknown Field Discarding (`prototext.UnmarshalOptions`)**:
   - `prototext.UnmarshalOptions{DiscardUnknown: true}` allows the unmarshaler to skip unrecognized field names gracefully without returning 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: Text format serialization, multiline formatting, indentation, and unknown field discarding in Protocol Buffers
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/protobuf@v1.28.0
Demonstrate these symbols/APIs:
  - google.golang.org/protobuf/encoding/prototext.Marshal
  - google.golang.org/protobuf/encoding/prototext.MarshalOptions
  - google.golang.org/protobuf/encoding/prototext.Unmarshal
  - google.golang.org/protobuf/encoding/prototext.UnmarshalOptions

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:c6fa4f631eb9d0906b713a2749e6789b22928d89fa22b57ff88bf4600db26a07","contract":["prototext.Marshal produces compact single-line text format without newlines and formats enums by name rather than integer value.","prototext.MarshalOptions with Multiline set to true outputs indented multi-line text format with newlines.","prototext.Unmarshal parses text format containing comments, nested messages, enums, and repeated fields into a proto.Message.","prototext.Unmarshal fails with an unknown field error when encountering unrecognized field names.","prototext.UnmarshalOptions with DiscardUnknown set to true successfully skips unknown fields without returning an error.","prototext.MarshalOptions with EmitUnknown set to true outputs raw wire-format unknown fields stored in the message."],"goal":"Text format serialization, multiline formatting, indentation, and unknown field discarding in Protocol Buffers","kind":"HOW","packages":["pkg:golang/google.golang.org/protobuf@v1.28.0"],"schemaVersion":1,"symbols":["google.golang.org/protobuf/encoding/prototext.Marshal","google.golang.org/protobuf/encoding/prototext.MarshalOptions","google.golang.org/protobuf/encoding/prototext.Unmarshal","google.golang.org/protobuf/encoding/prototext.UnmarshalOptions"]},"contractCommand":["go","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.28.0"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/protobuf@v1.28.0","symbols":["google.golang.org/protobuf/encoding/prototext.Marshal","google.golang.org/protobuf/encoding/prototext.MarshalOptions","google.golang.org/protobuf/encoding/prototext.Unmarshal","google.golang.org/protobuf/encoding/prototext.UnmarshalOptions"],"verifierAdapter":"golang@1"}

module example.com/prototextsample

go 1.26.6

require google.golang.org/protobuf v1.28.0

github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
google.golang.org/protobuf v1.28.0 h1:w43yiav+6bVFTBQFZX0r7ipe9JQ1QsbMgHwbBziscLw=
google.golang.org/protobuf v1.28.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=

package prototextsample_test

import (
	"strings"
	"testing"

	"google.golang.org/protobuf/encoding/prototext"
	"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.MessageDescriptor, protoreflect.MessageDescriptor) {
	t.Helper()

	fd := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("config.proto"),
		Package: proto.String("example.config"),
		Syntax:  proto.String("proto3"),
		EnumType: []*descriptorpb.EnumDescriptorProto{
			{
				Name: proto.String("LogLevel"),
				Value: []*descriptorpb.EnumValueDescriptorProto{
					{Name: proto.String("LOG_LEVEL_UNSPECIFIED"), Number: proto.Int32(0)},
					{Name: proto.String("DEBUG"), Number: proto.Int32(1)},
					{Name: proto.String("INFO"), Number: proto.Int32(2)},
					{Name: proto.String("WARN"), Number: proto.Int32(3)},
					{Name: proto.String("ERROR"), Number: proto.Int32(4)},
				},
			},
		},
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("Endpoint"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("ip"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						JsonName: proto.String("ip"),
					},
					{
						Name:     proto.String("weight"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName: proto.String("weight"),
					},
				},
			},
			{
				Name: proto.String("ServerConfig"),
				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("enabled"),
						Number:   proto.Int32(3),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_BOOL.Enum(),
						JsonName: proto.String("enabled"),
					},
					{
						Name:     proto.String("tags"),
						Number:   proto.Int32(4),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REPEATED.Enum(),
						JsonName: proto.String("tags"),
					},
					{
						Name:     proto.String("log_level"),
						Number:   proto.Int32(5),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_ENUM.Enum(),
						TypeName: proto.String(".example.config.LogLevel"),
						JsonName: proto.String("logLevel"),
					},
					{
						Name:     proto.String("primary_endpoint"),
						Number:   proto.Int32(6),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.config.Endpoint"),
						JsonName: proto.String("primaryEndpoint"),
					},
				},
			},
		},
	}

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

	serverDesc := fileDesc.Messages().ByName("ServerConfig")
	endpointDesc := fileDesc.Messages().ByName("Endpoint")
	if serverDesc == nil || endpointDesc == nil {
		t.Fatalf("failed to resolve message descriptors")
	}

	return fd, serverDesc, endpointDesc
}

func TestPrototextMarshalDefaultAndFormatting(t *testing.T) {
	_, serverDesc, endpointDesc := buildSchema(t)

	hostField := serverDesc.Fields().ByName("host")
	portField := serverDesc.Fields().ByName("port")
	enabledField := serverDesc.Fields().ByName("enabled")
	tagsField := serverDesc.Fields().ByName("tags")
	logLevelField := serverDesc.Fields().ByName("log_level")
	endpointField := serverDesc.Fields().ByName("primary_endpoint")

	ipField := endpointDesc.Fields().ByName("ip")
	weightField := endpointDesc.Fields().ByName("weight")

	msg := dynamicpb.NewMessage(serverDesc)
	msg.Set(hostField, protoreflect.ValueOfString("api.example.com"))
	msg.Set(portField, protoreflect.ValueOfInt32(8443))
	msg.Set(enabledField, protoreflect.ValueOfBool(true))
	msg.Set(logLevelField, protoreflect.ValueOfEnum(2)) // INFO

	tagsList := msg.Mutable(tagsField).List()
	tagsList.Append(protoreflect.ValueOfString("gateway"))
	tagsList.Append(protoreflect.ValueOfString("v2"))

	ep := msg.Mutable(endpointField).Message()
	ep.Set(ipField, protoreflect.ValueOfString("10.0.0.1"))
	ep.Set(weightField, protoreflect.ValueOfInt32(100))

	// 1. prototext.Marshal default formatting: emits compact single-line text without newlines
	outBytes, err := prototext.Marshal(msg)
	if err != nil {
		t.Fatalf("prototext.Marshal failed: %v", err)
	}
	outText := string(outBytes)

	if strings.Contains(outText, "\n") {
		t.Errorf("default prototext.Marshal should output compact single-line, got: %s", outText)
	}
	if !strings.Contains(outText, `host:"api.example.com"`) {
		t.Errorf("expected host string in output, got: %s", outText)
	}
	if !strings.Contains(outText, `port:8443`) {
		t.Errorf("expected port in output, got: %s", outText)
	}
	if !strings.Contains(outText, `enabled:true`) {
		t.Errorf("expected enabled:true in output, got: %s", outText)
	}
	if !strings.Contains(outText, `log_level:INFO`) {
		t.Errorf("expected enum name INFO instead of raw integer 2, got: %s", outText)
	}

	// 2. prototext.MarshalOptions Multiline formatting with newlines and indentation
	multilineOpts := prototext.MarshalOptions{Multiline: true}
	multilineOut, err := multilineOpts.Marshal(msg)
	if err != nil {
		t.Fatalf("multilineOpts.Marshal failed: %v", err)
	}
	multilineText := string(multilineOut)
	if !strings.Contains(multilineText, "\n") {
		t.Errorf("expected multiline output with newlines, got: %s", multilineText)
	}
	if !strings.Contains(multilineText, "  ip:") {
		t.Errorf("expected indented nested field in output, got: %s", multilineText)
	}
}

func TestPrototextUnmarshalBasicAndComments(t *testing.T) {
	_, serverDesc, endpointDesc := buildSchema(t)

	inputText := `# Primary gateway configuration
host: "srv.example.com"
port: 9000
enabled: false
tags: ["auth", "edge"]
log_level: WARN
primary_endpoint: {
  ip: "192.168.1.10" # Internal subnet
  weight: 50
}
`
	msg := dynamicpb.NewMessage(serverDesc)
	if err := prototext.Unmarshal([]byte(inputText), msg); err != nil {
		t.Fatalf("prototext.Unmarshal failed on valid input with comments: %v", err)
	}

	hostField := serverDesc.Fields().ByName("host")
	portField := serverDesc.Fields().ByName("port")
	enabledField := serverDesc.Fields().ByName("enabled")
	tagsField := serverDesc.Fields().ByName("tags")
	logLevelField := serverDesc.Fields().ByName("log_level")
	endpointField := serverDesc.Fields().ByName("primary_endpoint")

	ipField := endpointDesc.Fields().ByName("ip")
	weightField := endpointDesc.Fields().ByName("weight")

	if got := msg.Get(hostField).String(); got != "srv.example.com" {
		t.Errorf("expected host 'srv.example.com', got %q", got)
	}
	if got := msg.Get(portField).Int(); got != 9000 {
		t.Errorf("expected port 9000, got %d", got)
	}
	if got := msg.Get(enabledField).Bool(); got != false {
		t.Errorf("expected enabled false, got %v", got)
	}
	if got := msg.Get(logLevelField).Enum(); got != 3 { // WARN
		t.Errorf("expected log_level enum value 3 (WARN), got %d", got)
	}

	tagsList := msg.Get(tagsField).List()
	if tagsList.Len() != 2 || tagsList.Get(0).String() != "auth" || tagsList.Get(1).String() != "edge" {
		t.Errorf("tags list mismatch, got: %v", tagsList)
	}

	ep := msg.Get(endpointField).Message()
	if got := ep.Get(ipField).String(); got != "192.168.1.10" {
		t.Errorf("expected ip '192.168.1.10', got %q", got)
	}
	if got := ep.Get(weightField).Int(); got != 50 {
		t.Errorf("expected weight 50, got %d", got)
	}
}

func TestPrototextUnmarshalUnknownFieldHandling(t *testing.T) {
	_, serverDesc, _ := buildSchema(t)

	inputWithUnknown := `host: "edge.example.com"
unknown_field_name: "unexpected_value"
port: 8080
nested_unknown: {
  sub_key: 123
}
`

	// 1. Default prototext.Unmarshal rejects unknown fields with error
	msgDefault := dynamicpb.NewMessage(serverDesc)
	err := prototext.Unmarshal([]byte(inputWithUnknown), msgDefault)
	if err == nil {
		t.Fatalf("expected prototext.Unmarshal to fail with unknown field error, but got nil")
	}
	if !strings.Contains(err.Error(), "unknown field") {
		t.Errorf("expected error message to mention 'unknown field', got: %v", err)
	}

	// 2. prototext.UnmarshalOptions with DiscardUnknown: true skips unknown fields
	discardOpts := prototext.UnmarshalOptions{DiscardUnknown: true}
	msgDiscard := dynamicpb.NewMessage(serverDesc)
	if err := discardOpts.Unmarshal([]byte(inputWithUnknown), msgDiscard); err != nil {
		t.Fatalf("discardOpts.Unmarshal failed: %v", err)
	}

	hostField := serverDesc.Fields().ByName("host")
	portField := serverDesc.Fields().ByName("port")

	if got := msgDiscard.Get(hostField).String(); got != "edge.example.com" {
		t.Errorf("expected host 'edge.example.com', got %q", got)
	}
	if got := msgDiscard.Get(portField).Int(); got != 8080 {
		t.Errorf("expected port 8080, got %d", got)
	}
}

func TestPrototextMarshalOptionsEmitUnknown(t *testing.T) {
	_, serverDesc, _ := buildSchema(t)

	msg := dynamicpb.NewMessage(serverDesc)
	hostField := serverDesc.Fields().ByName("host")
	msg.Set(hostField, protoreflect.ValueOfString("unknown-test.example.com"))

	// Append raw wire-format unknown field: tag 999 (wire type 2, length-delimited string "custom_data")
	// Varint tag 999 << 3 | 2 = 7994 -> 0xba (58 | 0x80), 0x3e (62)
	// Length: 11 (0x0b)
	// Payload: "custom_data"
	unknownBytes := []byte{0xba, 0x3e, 0x0b, 'c', 'u', 's', 't', 'o', 'm', '_', 'd', 'a', 't', 'a'}
	msg.ProtoReflect().SetUnknown(unknownBytes)

	// 1. Default Marshal (EmitUnknown: false) suppresses unknown fields
	defaultOut, err := prototext.Marshal(msg)
	if err != nil {
		t.Fatalf("prototext.Marshal failed: %v", err)
	}
	if strings.Contains(string(defaultOut), "999:") || strings.Contains(string(defaultOut), "custom_data") {
		t.Errorf("default prototext.Marshal should omit unknown fields, got: %s", string(defaultOut))
	}

	// 2. MarshalOptions with EmitUnknown: true emits unknown fields in text format
	emitOpts := prototext.MarshalOptions{EmitUnknown: true}
	emitOut, err := emitOpts.Marshal(msg)
	if err != nil {
		t.Fatalf("emitOpts.Marshal failed: %v", err)
	}
	if !strings.Contains(string(emitOut), "999:") {
		t.Errorf("expected EmitUnknown: true to emit field 999 tag, got: %s", string(emitOut))
	}
	if !strings.Contains(string(emitOut), "custom_data") {
		t.Errorf("expected EmitUnknown: true to emit unknown field content 'custom_data', got: %s", string(emitOut))
	}
}

{
  "schemaVersion": 1,
  "goal": "Text format serialization, multiline formatting, indentation, and unknown field discarding in Protocol Buffers",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/protobuf@v1.28.0"
  ],
  "symbols": [
    "google.golang.org/protobuf/encoding/prototext.Marshal",
    "google.golang.org/protobuf/encoding/prototext.MarshalOptions",
    "google.golang.org/protobuf/encoding/prototext.Unmarshal",
    "google.golang.org/protobuf/encoding/prototext.UnmarshalOptions"
  ]
}