codegen

Overview ¶

Package codegen -- decode_enum.go contains enum-level descriptor decoding: EnumDescriptorProto and EnumValueDescriptorProto wire parsing, and the buildEnumDescriptor pass-2 builder.

Package codegen -- decode_file.go contains file-level descriptor decoding: raw type definitions, lookup tables, the two-pass DecodeFileDescriptors entry-point, and helper functions shared across all decode_*.go files.

Package codegen -- decode_message.go contains message-level descriptor decoding: DescriptorProto, FieldDescriptorProto, OneofDescriptorProto wire parsing, and the buildMessageDescriptor pass-2 builder.

Package codegen -- decode_service.go contains service-level descriptor decoding: ServiceDescriptorProto and MethodDescriptorProto wire parsing, and the buildServiceDescriptor pass-2 builder.

Package codegen implements the protoc code generation engine for Go. It transforms decoded file descriptors into Go source files implementing the protobuf message, enum, and service types defined in .proto files.

The primary entry point is Generate, which accepts a set of linked file descriptors, their raw wire-format counterparts, a set of files to generate, and parsed generator parameters. It returns a map of output file paths to generated Go source content.

The package also implements the protoc plugin wire protocol through CodeGeneratorRequest and CodeGeneratorResponse. CodeGeneratorRequest is unmarshaled from the binary input provided by protoc on stdin, and CodeGeneratorResponse is marshaled to stdout. The RawFileDescriptor type captures the subset of FileDescriptorProto fields needed for code generation without requiring a full descriptor decode.

Code generation produces several categories of output:

• Message structs with Marshal, Unmarshal, Size, Merge, Clone, Reset, Validate, Equal, and ProtoReflect methods
• Enum types with String, Number, and lookup helpers
• Service interfaces and method descriptors
• Builder types for constructing messages with a fluent API
• Oneof interface types and accessor methods
• Pool-integrated allocation helpers with build-tagged GC and TinyGo variants
• File-level descriptor registration via init functions

The GenerateFile function produces the complete Go source for a single .proto file. GenerateAuxFiles produces build-tagged auxiliary files for TinyGo compatibility. Both are called by Generate for each file in the generation set.

Go package resolution is handled by ResolveGoPackage, which parses the go_package option string into an import path and package name. The ImportTable type maps proto file paths and packages to their resolved Go package information, enabling cross-file type reference resolution.

This package depends on descriptor, scalar, field, encode, decode, and wire from this module, plus the Go standard library. It has zero external dependencies.

gen_api_mode.go provides helpers for API-mode-aware code generation. When the resolved GoAPIMode is GoAPIModeOpen, fields use exported PascalCase names (current behavior). When GoAPIModeOpaque, fields use unexported camelCase names with getter/setter accessors.

Package codegen -- gen_binary.go generates MarshalBinary and UnmarshalBinary methods for protobuf messages so that generated types satisfy the encoding.BinaryMarshaler and encoding.BinaryUnmarshaler interfaces. The methods are thin wrappers that delegate to the existing Marshal and Unmarshal methods; no serialization logic is duplicated here. These methods enable generated types to work with encoding/gob, database/sql drivers, and other stdlib-based serialization.

Package codegen -- gen_buildtag.go generates auxiliary build-tagged Go source files for TinyGo compatibility. For each .proto file that contains messages, two additional files are produced alongside the main .pb.go:

• *_pool_gc.go (//go:build !tinygo): sync.Pool variable, ResetVT, ReturnToPool, and FromPool using sync.Pool.
• *_pool_tinygo.go (//go:build tinygo): ResetVT, ReturnToPool (calls ResetVT only), and FromPool (direct allocation).
• *_unsafe_gc.go (//go:build !tinygo): UnmarshalUnsafe using unsafe.String for zero-copy string aliasing.
• *_unsafe_tinygo.go (//go:build tinygo): UnmarshalUnsafe that delegates to standard Unmarshal (no unsafe import).

gen_equal.go generates the type-specific Equal method for protobuf messages.

The generated Equal(other *MsgType) bool method compares fields directly by name without going through protoreflect.Range or interface dispatch. Scalar fields use ==, bytes fields use bytes.Equal, message fields use recursive x.Field.Equal(other.Field), repeated fields use length check plus element- wise comparison, map fields use length check plus key-wise comparison, and oneof fields use a type-switch comparing the active variant.

For fields with native Go type substitution (go_type option), the comparison uses the substitution's EqualExpr: time.Time uses .Equal(), time.Duration uses ==, and map[string]any uses reflect.DeepEqual.

The reflection-based proto.Equal in proto/equal_message.go remains available as a fallback for dynamic messages and cross-type comparisons. The generated Equal method is used when both operands are the same concrete generated type.

Package codegen -- gen_file_descriptors.go contains functions that emit Go code to build descriptor.XxxDescriptor values via the builder API, used within the generated init() function.

Package codegen -- gen_file_header.go contains the GenerateFile entry-point that produces complete Go source code for a single .proto file, along with the recursive code collectors, file header, and package-level variable emitters.

Package codegen -- gen_file_imports.go contains import tracking and the import block writer for generated Go source files.

Package codegen -- gen_file_registration.go contains the init() function generator and the helper functions that convert descriptor/scalar constants to their Go source code string representations.

Package codegen -- gen_json.go generates MarshalJSON and UnmarshalJSON methods for protobuf messages so that generated types satisfy the encoding/json.Marshaler and encoding/json.Unmarshaler interfaces. The methods are thin wrappers that delegate to the jsoncodec package; no marshaling logic is duplicated here.

Package codegen -- gen_marshal.go generates the MarshalAppend and Marshal methods for protobuf messages, handling singular, repeated, and oneof field encoding using inline wire package calls for zero-dispatch serialization.

Package codegen -- gen_marshal_map.go generates encoding code for protobuf map fields, including map key type resolution, key sorting, and entry-level size computation and wire encoding using inline wire package calls.

gen_merge_clone.go generates the Merge and Clone methods for protobuf messages, handling field-by-field merging and deep copying of singular, repeated, map, and oneof fields. For fields with native Go type substitution (go_type option), values are treated as their native Go types: time.Time and time.Duration are value types (copy by assignment), and map[string]any is deep-copied via a helper.

gen_opaque.go generates getter, setter, Has, and Clear methods for protobuf messages using the opaque API mode (GoAPIModeOpaque). In opaque mode, struct fields are unexported and accessed only through these generated accessor methods. Message-typed fields support lazy decoding: raw bytes are stored in an internal _lazy_fieldName field and decoded on first Get call.

gen_pool.go generates message-level sync.Pool integration for protobuf messages. This includes ResetVT (capacity-preserving reset), ReturnToPool, MsgTypeFromPool, and the package-level pool variable declaration.

Message-level pools are separate from the buffer pool in pool/pool.go. The buffer pool manages reusable byte slices for serialization; message pools manage reusable message struct instances to reduce GC pressure.

For TinyGo compatibility, the pool code is split into two build-tagged files: a gc variant using sync.Pool and a tinygo variant using direct allocation.

gen_reflect.go generates the ProtoReflect method and its supporting reflection adapter struct for protobuf messages, providing access to the descriptor-based reflection API.

gen_shallow_clone.go generates the ShallowClone method for protobuf messages. Unlike the deep-copy Clone method, ShallowClone copies scalar fields by value and copies slice headers, map references, and message pointers without recursing. Mutations to shared slices, maps, or sub-messages will be visible from both the original and the clone.

gen_size.go generates the Size method for protobuf messages, computing the serialized wire size for singular, repeated, map, and oneof fields using inline wire.SizeVarint calls and pre-computed tag size constants.

gen_unmarshal.go generates the Unmarshal and UnmarshalUnsafe methods for protobuf messages, handling singular, repeated, map, and oneof field decoding with inline wire consumption calls for performance.

Package codegen -- gen_unmarshal_tinygo.go generates the TinyGo-variant and gc-variant UnmarshalUnsafe code for build-tagged file splitting. The gc variant uses the unsafe package for zero-copy string aliasing. The TinyGo variant delegates to the standard Unmarshal method since TinyGo does not support the unsafe package features used for zero-copy aliasing.

gen_validate.go generates the Reset and Validate methods for protobuf messages. Reset zeros all fields; Validate checks required fields and closed enum values. In opaque mode, field access uses camelCase names.

native_types.go defines the native Go type substitution table for well-known protobuf types. When a field has the `go_type` option set, the code generator substitutes the default WKT pointer type (e.g., *wkt.Timestamp) with a native Go type (e.g., time.Time). The substitution is opt-in per field; when no `go_type` option is present, behavior is unchanged.

Supported substitutions:

• google.protobuf.Timestamp -> time.Time (import: "time")
• google.protobuf.Duration -> time.Duration (import: "time")
• google.protobuf.Struct -> map[string]any (no import needed)

Each substitution includes conversion function names for marshal (Go native type -> WKT type) and unmarshal (WKT type -> Go native type) directions, enabling the generated code to round-trip through the WKT types for wire encoding.