v1.20.1

Notable changes since v1.20.0:

• CL/204804: bug fix for dead-lock in the global type registry
• CL/221803: minor performance improvements for Marshal and Size operations
• CL/222678: fix signature of pseudo-internal MarshalState and UnmarshalState methods

v1.20.0

• Overview
  • Backwards compatibility
  • Package index
• Notable changes
  • Message type
  • Reflection
  • Wire serialization
  • JSON serialization
  • Text serialization
  • Extensions
  • Nil values
  • Errors
  • Generated code
  • gRPC support
  • Performance
• Upcoming breakage changes
  • Enforcement of namespace uniqueness
  • Required go_package option
  • Deprecation of protoc-gen-go flags
  • Deprecation of generated APIs

Overview

The google.golang.org/protobuf module is a major revision of the Go bindings for protocol buffers. The API has been completely overhauled with a focus on simplicity and clarity. Deprecated types and functions are removed, complicated packages are split into more manageable pieces, and internal details are separated from the public API. Particular attention was made to ensure that this implementation complies with the protocol buffer language as closely as possible to ensure proper interoperability between the Go implementation and implementations for other languages.

The first version of this module is v1.20.0. The version number is deliberately chosen to avoid overlap with existing and anticipated versions of the github.com/golang/protobuf module. This enables the version alone to unambiguously distinguish between the two modules.

The minimally supported version of Go is v1.9.

Backwards compatibility

The API in this module is not drop-in compatible with the earlier github.com/golang/protobuf module. However, the new API does strive when sensible to be compatible for easier migration.

Version v1.4.0 of the github.com/golang/protobuf module implements most of the existing API in terms of this module, which provides a number of benefits:

• Shared type registry: It ensures that the two modules share a unified type registry, which is necessary for dynamic usages of protocol buffers to work properly.
• Automatic improvements: It provides the older module with a degree of automatic upgrading whenever bug fixes and improvements are made to the newer module.
• Long-term maintainability: It keeps the older module more maintainable since it is largely a thin shim over the newer module.

Some existing features present in the github.com/golang/protobuf module are currently unavailable in this module:

• Manipulation of the wire format: The older module provides functionality for directly manipulating the raw wire format through methods on the proto.Buffer type.
• Helper functions for well-known types: The older module provides the ptypes package containing helper functions for interacting with the well-known types such as Any or Timestamp messages.

We plan to add these features to this module in the near future and improve upon them.

Package index

Summary of the packages provided by this module:

• proto: Package proto provides functions operating on protobuf messages such as cloning, merging, and checking equality, as well as binary serialization.
• encoding/protojson: Package protojson serializes protobuf messages as JSON.
• encoding/prototext: Package prototext serializes protobuf messages as the text format.
• reflect/protoreflect: Package protoreflect provides interfaces to dynamically manipulate protobuf messages.
• reflect/protoregistry: Package protoregistry provides data structures to register and lookup protobuf descriptor types.
• reflect/protodesc: Package protodesc provides functionality for converting descriptorpb.FileDescriptorProto messages to/from the reflective protoreflect.FileDescriptor.
• testing/protocmp: Package protocmp provides protobuf specific options for the cmp package.
• testing/prototest: Package prototest exercises the protobuf reflection implementation for concrete message types.
• types/dynamicpb: Package dynamicpb creates protobuf messages at runtime from protobuf descriptors.
• types/known/anypb: Package anypb is the generated package for google/protobuf/any.proto.
• types/known/emptypb: Package emptypb is the generated package for google/protobuf/empty.proto.
• types/known/timestamppb: Package timestamppb is the generated package for google/protobuf/timestamp.proto.
• types/known/durationpb: Package durationpb is the generated package for google/protobuf/duration.proto.
• types/known/wrapperspb: Package wrapperspb is the generated package for google/protobuf/wrappers.proto.
• types/known/structpb: Package structpb is the generated package for google/protobuf/struct.proto.
• types/descriptorpb: Package descriptorpb is the generated package for google/protobuf/descriptor.proto.
• types/pluginpb: Package pluginpb is the generated package for google/protobuf/compiler/plugin.proto.
• compiler/protogen: Package protogen provides support for writing protoc plugins.
• cmd/protoc-gen-go: The protoc-gen-go binary is a protoc plugin to generate a Go protocol buffer package.

Notable changes

This section summarizes notable changes in this release relative to v1.3.4 of the github.com/golang/protobuf module.

Message type

The definition of the proto.Message interface type has changed (see v1 Message and v2 Message). The new type definition contains a behaviorally-complete specification of a protobuf message. All functions in this module that operate on a proto.Message can be used with values of any concrete type which properly implements this interface.

The github.com/golang/protobuf/proto package contains functions to convert between the old and new proto.Message types (see MessageV1 and MessageV2). These functions are guaranteed to work with types generated by protoc-gen-go, however there is no guarantee that it handles hand-crafted messages or messages generated by different generators.

Reflection

A key feature of the new Go protobuf API is support for protobuf reflection, which is the ability to programmatically interact with a message at runtime. The ProtoReflect method implemented by every proto.Message returns a reflective view of that message. Using protobuf reflection instead of Go reflection is generally easier since it closely follows the protobuf data model, and also more maintainable since it relies on a stable API that is agnostic to the exact underlying implementation of a message. On the other hand, using Go reflection on protobuf messages often needs to make low-level assumptions about a particular implementation of protobuf messages that may not be stable (e.g., assuming that the Go struct field ordering exactly matches the proto message field ordering).

See the protoreflect package for more details.

Wire serialization

The API for wire serialization has changed slightly for better usability. Optional arguments for controlling serialization are specified through the proto.MarshalOptions and proto.UnmarshalOptions types. Both...