Releases: protocolbuffers/protobuf-go
v1.29.0
Overview
This version introduces a new package protodelim to marshal and unmarshal size-delimited messages.
It also brings the implementation up to date with the latest protobuf features.
Notable changes
New Features
- CL/419254: encoding: add protodelim package
- CL/450775: reflect/protoreflect: add Value.Equal method
- CL/462315: cmd/protoc-gen-go: make deprecated messages more descriptive
- CL/473015: encoding/prototext: allow whitespace and comments between minus sign and number in negative numeric literal
Alignment with protobuf
- CL/426054: types/descriptorpb: update *.pb.go to use latest protoc release, 21.5
- CL/425554: encoding/protojson: fix parsing of google.protobuf.Timestamp
- CL/461238: protobuf: remove the check for reserved field numbers
- CL/469255: types/descriptorpb: regenerate using latest protobuf v22.0 release
- CL/472696: cmd/protoc-gen-go: support protobuf retention feature
Documentation improvements:
- CL/464275: proto: document Equal behavior of invalid messages
- CL/466375: all: update links to Protocol Buffer documentation
Minor performance improvements
- CL/460215: types/known/structpb: preallocate map in AsMap
- CL/465115: internal/strs: avoid unnecessary allocations in Builder
Breaking changes
- CL/461238: protobuf: remove the check for reserved field numbers
- protowire.(Number).IsValid() no longer returns false for reserved fields because reserved fields are considered semantically valid by the protobuf spec.
v1.28.1
v1.28.0
Overview
The release provides a new unmarshal option for limiting the recursion depth when unmarshalling nested messages to prevent stack overflows. (UnmarshalOptions.RecursionLimit).
Notable changes
New features:
- CL/340489: testing/protocmp: add Message.Unwrap
Documentation improvements:
- CL/339569: reflect/protoreflect: add more docs on Value aliasing
Updated supported versions:
- CL/370055: all: update supported versions
UnmarshalOption RecursionLimit
- CL/385854: all: implement depth limit for unmarshalling
The new UnmarshalOptions.RecursionLimit limits the maximum recursion depth when unmarshalling messages. The limit is applied for nested messages. When messages are nested deeper than the specified limit the unmarshalling will fail. If unspecified, a default limit of 10,000 is applied.
In addition to the configurable limit for message nesting a non-configurable recursion limit for group nesting of 10,000 was introduced.
Upcoming breakage changes
The default recursion limit of 10,000 introduced in the release is subject to change. We want to align this limit with implementations for other languages in the long term. C++ and Java use a limit of 100 which is also the target for the Go implementation.
v1.27.1
v1.27.0
Overview
The release provides new functionality for iterating through a message using protobuf reflection. There are some minor changes to the code generator.
Notable changes
New features:
- CL/309669: testing/protopack: add Message.UnmarshalAbductive
Bug fixes:
- CL/317430: encoding/prototext: fix skipping of unknown fields
- CL/321529: internal/impl: support typed nil source for Merge of aberrant messages
Generator changes
- CL/305574: cmd/protoc-gen-go: remove generation of the ExtensionRangeArray method
- CL/319649: cmd/protoc-gen-go: avoid referencing remote enum values by name
- CL/316949: compiler/protogen: relax rules for valid import paths
- CL/306209: cmd/protoc-gen-go: add protoc suffix
Reflectively ranging over a message
- CL/236540: reflect: add protopath and protorange packages
The new reflect/protorange package supports recursively ranging through all populated fields of a message. There are many use cases for such a feature. See the examples for inspiration.
Upcoming breakage changes
This release removes generation of the ExtensionRangeArray method, as originally announced since the v1.20.0 release on March 2nd, 2020. Our analysis of the entire public module proxy found no static usages of this method. This method is pseudo-internal to the implementation and we expect removal of it to have no material impact. If something is broken by this change, please file an issue and we can consider re-generating this method in a patch release.
There are no new upcoming breaking changes to announce in this release.
v1.26.0
Overview
This release reduces dependencies on other modules, enforces strict behavior with generated Go packages and name conflicts, expands support for aberrant message types, and provides minor new features in protobuf reflection.
Notable changes
New features:
- CL/242377: proto: add MessageName helper
- CL/236777: reflect/protoreflect: add MessageFieldTypes
- CL/239838: reflect/protoreflect: add FieldDescriptor.TextName
- CL/238000: reflect/protoreflect: improve source information usability
Behavior changes:
- CL/240017: internal/impl: introduce instability to protoreflect.Message.Range order
- CL/262681: internal/encoding/text: escape \x7f (DEL) in strings
- CL/262682: internal/encoding/text: escape Unicode control characters in strings
- CL/259900: internal/filedesc: remove ProtoLegacyRawDesc method
- CL/286132: internal/descfmt: always include type name in FormatList
- CL/302330: cmd/protoc-gen-go: support --help flag
- CL/301952: cmd/protoc-gen-go: print version to stdout
- CL/244297: all: return less-specific, but more informative wire unmarshal errors
Bug fixes:
- CL/247458: testing/protocmp: fix representation of empty bytes
- CL/241658: testing/prototest: fix suggestion for field name
- CL/259899: reflect/protodesc: fix round-tripping for package field
- CL/247737: encoding/protojson: restrict valid values for google.protobuf.Value.number_value
- CL/246097: types/known/fieldmaskpb: repeated and map fields are only valid in the last position of a path
- CL/244718: internal/impl: make errInvalidUTF8 be a proto.Error
Performance optimizations:
- CL/253100: proto/equal: reduce equal scalar value allocation
- CL/240378: reflect/protoregistry: avoid checking for '/' in FindMessageByName
Reduced dependencies
- CL/259901: cmd/protoc-gen-go: remove reference to legacy ProtoPackageIsVersion4
- CL/262679: all: rely on dynamic dependency check for genproto
- CL/262683: all: remove weak dependency on github.com/golang/protobuf
- CL/262684: all: add weak dependency on github.com/golang/protobuf
- CL/235283: all: update protobuf toolchain dependency
Go code generated by protoc-gen-go no longer have a hard dependency on the github.com/golang/protobuf module. In previous releases, the generator would emit a reference to the ProtoPackageIsVersion4 constant to statically enforce that a sufficiently new version of the older module was being linked in. In the last year, most of the Go ecosystem has moved to Go modules, where we can rely on Go modules to enforce a minimum version constraint on the older protobuf module. While there continues to be a cyclic dependency between the github.com/golang/protobuf and google.golang.org/protobuf modules, the cyclic dependency was briefly broken and re-added to clear out the infinitely growing list of go.sum entries.
The module dependency on the google.golang.org/genproto module has been removed. Any program that depends on both google.golang.org/protobuf and google.golang.org/genproto must use at least version cb27e3aa from May 26th, 2020. There is a runtime check at program initialization that panics when too old of a version of the genproto module is being linked into the binary.
The well-known types provided by this module are built from v3.15.3 of the protobuf toolchain.
Require Go import path
- CL/301953: compiler/protogen: require that the import path be specified
As mentioned in the v1.20.0 release from March 2nd, 2020, the Go generator will require that the Go import path be specified for all .proto files being generated and their transitive dependencies. Since v1.20.0, every occurrence of a .proto file missing a Go import path has resulted in a warning being printed to standard error that this will eventually become a fatal error. The Go import path is normally specified by declaring a go_package option in the .proto file. Alternatively, this can be specified at compile-time with a M flag passed on the command line. See the developer documentation for more information on the go_package option and M flag.
Fatal namespace conflicts
- CL/235298: reflect/protoregistry: panic upon registration conflicts
- CL/295349: reflect/protoregistry: add compile-time opt-out for registration conflicts
As mentioned in the v1.20.0 release from March 2nd, 2020, the Go protobuf runtime will fatally fail if it detects the registration of duplicate names. Since v1.20.0, every occurrence of a conflict has resulted in a warning being printed to standard error that this will eventually become a fatal error. See the developer documentation for more information about what a namespace conflict is and how to resolve it.
While it is preferable that the source of the conflict be fixed, the fatal error can be immediately worked around in one of two ways:
- At compile time. The default behavior for handling conflicts can be specified at compile time with a linker-initialized variable:
go build -ldflags "-X google.golang.org/protobuf/reflect/protoregistry.conflictPolicy=warn"
- At program execution. The behavior for handling conflicts when executing a particular Go binary can be set with an environment variable:
GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn ./main
This will cause the runtime to use the conflict handling behavior from v1.25.0 and earlier, which is to simply warn about them.
Support for aberrant message types
- CL/300869: internal/impl: add runtime support for aberrant messages
- CL/244937: internal/impl: add runtime support for *[]byte unknown representation
This project's compatibility document specifies that we only guarantee runtime compatibility with messages generated by protoc-gen-go. Use of this module's runtime with any other custom message type will have mixed results, ranging from panics, to unspecified behavior, to working correctly. The proper way for custom message types to perfectly work with this module is for the custom type to implement the protoreflect.ProtoMessage interface, which allows a given message implementation to self-describe how its contents should be introspected.
Since some widely depended upon modules have custom message types not generated by protoc-gen-go, we expand support in this module's runtime to be able to handle those aberrant message types. This change should reduce the probability that using one of those modules with this module results in a panic and instead have reasonably correct behavior.
This support is not covered by this project's compatibility guarantee and may be modified or removed in a future version of this module without notice. Custom types must move to supporting protobuf reflection to ensure long-term compatibility.
Upcoming breakage changes
This release makes some potentially disruptive changes that have been announced since the v1.20.0 release on March 2nd, 2020. Not all breaking changes mentioned in the v1.20.0 have been made and may s...
v1.25.0
Overview
This release provides specialized support for well-known types.
Notable changes
New features:
- CL/225298: types/known: implement first-class WKT support
- CL/237219: types/dynamicpb: add NewEnumType
Minor changes:
- CL/238002: reflect/protoreflect: optimize Name.IsValid and FullName.IsValid
- CL/239339: cmd/protoc-gen-go: use of --version flag exits with 0
Bug fixes:
- CL/236998: encoding/protojson: strict validation of FieldMask serialization
Specialized support for well-known types
This release provides specialized support for well-known types by directly generating methods and functions into the generated package for certain well-known types that improve the usability of such types. The additionally generated APIs are listed below.
-
Package
anypb: New, MarshalFrom, UnmarshalTo, UnmarshalNew, Any.MessageIs, Any.MessageName, Any.MarshalFrom, Any.UnmarshalTo, Any.UnmarshalNew -
Package
timestamppb: Now, New, Timestamp.AsTime, Timestamp.IsValid, Timestamp.CheckValid -
Package
durationpb: New, Duration.AsDuration, Duration.IsValid, Duration.CheckValid -
Package
structpb: NewStruct, Struct.AsMap, Struct.MarshalJSON, Struct.UnmarshalJSON, NewList, ListValue.AsSlice, ListValue.MarshalJSON, ListValue.UnmarshalJSON, NewValue, NewNullValue, NewBoolValue, NewNumberValue, NewStringValue, NewStructValue, NewListValue, Value.AsInterface, Value.MarshalJSON, Value.UnmarshalJSON -
Package
fieldmaskpbNew,, Union,, Intersect,, FieldMask.IsValid,, FieldMask.Append,, FieldMask.Normalize, -
Package
wrapperspbBool, Int32, Int64, UInt32, UInt64, Float, Double, String, Bytes
Upcoming breakage changes
There are no new upcoming breaking changes to announce in this release.
As a reminder, the following have already been announced and may take effect in the near future:
- Deprecations announced on 2020-03-02 with the v1.20.0 release
v1.24.0
Overview
This release moves the generation of well-known types into this module.
Notable changes
New features:
- CL/234937: all: move well-known types
Minor changes:
- CL/235297: all: add weak dependency on google.golang.org/genproto module
Bug fixes:
- CL/234697: testing/protopack: fix format precision
Centralized host for all well-known types
This release moves the generation of well-known types (e.g., FieldMask) into this module. Previously, some of the well-known types were generated into the google.golang.org/genproto module. This sets the stage for a future release of this module to provide first-class support for the well-known types.
As a consequence of this migration, this module incurs a weak dependency on the google.golang.org/genproto module. This dependency may be dropped in the distant future, but it will persist for some time to ensure that users of this module use a sufficiently new version of google.golang.org/genproto (if they happen to depend on it) so as to avoid duplicate registration problems with regard to the well-known types.
Upcoming breakage changes
There are no new upcoming breaking changes to announce in this release.
As a reminder, the following have already been announced and may take effect in the near future:
- Deprecations announced on 2020-03-02 with the v1.20.0 release
v1.23.0
Overview
This release adds some minor new API to encoding/prototext and compiler/protogen.
Notable changes
New features:
- CL/233077: encoding/prototext: adjust handling of invalid UTF-8
- CL/232239: compiler/protogen: add (*GeneratedFile).Unskip
Minor changes:
- CL/232339: all: improve panic messages for better debugability
- CL/232937: internal/impl: avoid inlining fixed coderFieldInfo array
Bug fixes:
- CL/232338: compiler/protogen: avoid suggesting faulty go_package option
Upcoming breakage changes
There are no new upcoming breaking changes to announce in this release.
As a reminder, the following have already been announced and may take effect in the near future:
- Deprecations announced on 2020-03-02 with the v1.20.0 release
v1.22.0
Overview
This release adds support for the experimental proto3 optional semantics coming in the v3.12.0 release of the protobuf language, adjusts the API to ease migration from the old module to the new module, and fixes some minor bugs.
Notable changes
New features:
- CL/230698: all: implement support for proto3 optional semantics
- CL/229157: proto: add RangeExtensions and adjust HasExtension and GetExtension
Minor changes:
- CL/228837: all: consistently treat nil message interface as an empty read-only message
- CL/228838: proto: never return nil []byte from Marshal when successful
- CL/229558: all: improve extension validation
- CL/229277: internal/impl: inline coderInfoFields for better cache locality
Bug fixes:
- CL/229278: internal/impl: fix off-by-one error in message initialization
Proto3 optional semantics
Protocol buffers in v3.12.0 is gaining experimental support to represent true presence for scalars in the proto3 syntax. By default, scalars in proto3 lack presence, so users are unable to distinguish between an unpopulated field and whether the zero value was explicitly stored into that field. With this new language feature, users can explicitly specify the optional keyword for scalars to indicate that presence information should be preserved for that field.
This release adds support to the generator and the runtime for this feature. Generation of proto3 optional fields are represented as pointers to scalar types (similar to proto2 optional scalars).
Adjustments to ease migration
A few minor changes were made to the API to unify the behavior between the old github.com/golang/protobuf module and the new google.golang.org/protobuf module. This should aid users migrating from the former to the latter.
Changes:
- Adjusted all functions to treat a nil
proto.Messageas an untyped, read-only, empty message and provide sensible results given that semantic. - Adjusted
proto.HasExtensionto always report false if the extension descriptor does not extend the parent message (as opposed to panicking previously). - Added
proto.RangeExtensionsas a replacement for the legacyproto.ClearAllExtensionsandproto.ExtensionDescsfunctions. - Fixed
protoreflect.ExtensionType.IsValidInterfaceto never panic and properly report whether the given value is of the right type.
Upcoming breakage changes
There are no new upcoming breaking changes to announce in this release.
As a reminder, the following have already been announced and may take effect in the near future:
- Deprecations announced on 2020-03-02 with the v1.20.0 release