{"id":13473107,"url":"https://github.com/protocolbuffers/protobuf-go","last_synced_at":"2025-05-12T22:45:26.553Z","repository":{"id":37858087,"uuid":"177727591","full_name":"protocolbuffers/protobuf-go","owner":"protocolbuffers","description":"Go support for Google's protocol buffers","archived":false,"fork":false,"pushed_at":"2025-05-07T08:30:42.000Z","size":13301,"stargazers_count":3095,"open_issues_count":8,"forks_count":431,"subscribers_count":53,"default_branch":"master","last_synced_at":"2025-05-12T22:45:10.653Z","etag":null,"topics":["go","golang","protobufs","protocol-buffers"],"latest_commit_sha":null,"homepage":"https://developers.google.com/protocol-buffers","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/protocolbuffers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-26T06:26:40.000Z","updated_at":"2025-05-11T23:04:58.000Z","dependencies_parsed_at":"2024-01-13T18:10:23.300Z","dependency_job_id":"3cf958b1-dfc7-4e45-9562-aa8f7080c987","html_url":"https://github.com/protocolbuffers/protobuf-go","commit_stats":{"total_commits":1147,"total_committers":54,"mean_commits":21.24074074074074,"dds":0.5318221447253706,"last_synced_commit":"29947bbd165cd2034df6d15ae06feb83af40c572"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protocolbuffers%2Fprotobuf-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protocolbuffers%2Fprotobuf-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protocolbuffers%2Fprotobuf-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protocolbuffers%2Fprotobuf-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/protocolbuffers","download_url":"https://codeload.github.com/protocolbuffers/protobuf-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253837387,"owners_count":21971981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","protobufs","protocol-buffers"],"created_at":"2024-07-31T16:01:00.802Z","updated_at":"2025-05-12T22:45:26.505Z","avatar_url":"https://github.com/protocolbuffers.png","language":"Go","readme":"# Go support for Protocol Buffers\n\n[![Go Reference](https://pkg.go.dev/badge/google.golang.org/protobuf.svg)](https://pkg.go.dev/google.golang.org/protobuf)\n[![Build Status](https://travis-ci.org/protocolbuffers/protobuf-go.svg?branch=master)](https://travis-ci.org/protocolbuffers/protobuf-go)\n\nThis project hosts the Go implementation for\n[protocol buffers](https://protobuf.dev), which is a\nlanguage-neutral, platform-neutral, extensible mechanism for serializing\nstructured data. The protocol buffer language is a language for specifying the\nschema for structured data. This schema is compiled into language specific\nbindings. This project provides both a tool to generate Go code for the\nprotocol buffer language, and also the runtime implementation to handle\nserialization of messages in Go. See the\n[protocol buffer developer guide](https://protobuf.dev/overview)\nfor more information about protocol buffers themselves.\n\nThis project is comprised of two components:\n\n*   Code generator: The\n    [`protoc-gen-go`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go)\n    tool is a compiler plugin to `protoc`, the protocol buffer compiler. It\n    augments the `protoc` compiler so that it knows how to\n    [generate Go specific code for a given `.proto` file](https://protobuf.dev/reference/go/go-generated).\n\n*   Runtime library: The\n    [`protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf) module\n    contains a set of Go packages that form the runtime implementation of\n    protobufs in Go. This provides the set of interfaces that\n    [define what a message is](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect)\n    and functionality to serialize message in various formats (e.g.,\n    [wire](https://pkg.go.dev/google.golang.org/protobuf/proto),\n    [JSON](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson),\n    and\n    [text](https://pkg.go.dev/google.golang.org/protobuf/encoding/prototext)).\n\nSee the\n[developer guide for protocol buffers in Go](https://protobuf.dev/getting-started/gotutorial)\nfor a general guide for how to get started using protobufs in Go.\n\nThis project is the second major revision of the Go protocol buffer API\nimplemented by the\n[`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf)\nmodule. The first major version is implemented by the\n[`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf)\nmodule.\n\n## Package index\n\nSummary of the packages provided by this module:\n\n*   [`proto`](https://pkg.go.dev/google.golang.org/protobuf/proto): Package\n    `proto` provides functions operating on protobuf messages such as cloning,\n    merging, and checking equality, as well as binary serialization.\n*   [`encoding/protojson`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson):\n    Package `protojson` serializes protobuf messages as JSON.\n*   [`encoding/prototext`](https://pkg.go.dev/google.golang.org/protobuf/encoding/prototext):\n    Package `prototext` serializes protobuf messages as the text format.\n*   [`encoding/protowire`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protowire):\n    Package `protowire` parses and formats the low-level raw wire encoding. Most\n    users should use package `proto` to serialize messages in the wire format.\n*   [`reflect/protoreflect`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect):\n    Package `protoreflect` provides interfaces to dynamically manipulate\n    protobuf messages.\n*   [`reflect/protoregistry`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoregistry):\n    Package `protoregistry` provides data structures to register and lookup\n    protobuf descriptor types.\n*   [`reflect/protodesc`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protodesc):\n    Package `protodesc` provides functionality for converting\n    `descriptorpb.FileDescriptorProto` messages to/from the reflective\n    `protoreflect.FileDescriptor`.\n*   [`reflect/protopath`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protopath):\n    Package `protopath` provides a representation of a sequence of\n    protobuf reflection operations on a message.\n*   [`reflect/protorange`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protorange):\n    Package `protorange` provides functionality to traverse a protobuf message.\n*   [`testing/protocmp`](https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp):\n    Package `protocmp` provides protobuf specific options for the `cmp` package.\n*   [`testing/protopack`](https://pkg.go.dev/google.golang.org/protobuf/testing/protopack):\n    Package `protopack` aids manual encoding and decoding of the wire format.\n*   [`testing/prototest`](https://pkg.go.dev/google.golang.org/protobuf/testing/prototest):\n    Package `prototest` exercises the protobuf reflection implementation for\n    concrete message types.\n*   [`types/dynamicpb`](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb):\n    Package `dynamicpb` creates protobuf messages at runtime from protobuf\n    descriptors.\n*   [`types/known/anypb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/anypb):\n    Package `anypb` is the generated package for `google/protobuf/any.proto`.\n*   [`types/known/timestamppb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/timestamppb):\n    Package `timestamppb` is the generated package for\n    `google/protobuf/timestamp.proto`.\n*   [`types/known/durationpb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/durationpb):\n    Package `durationpb` is the generated package for\n    `google/protobuf/duration.proto`.\n*   [`types/known/wrapperspb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/wrapperspb):\n    Package `wrapperspb` is the generated package for\n    `google/protobuf/wrappers.proto`.\n*   [`types/known/structpb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb):\n    Package `structpb` is the generated package for\n    `google/protobuf/struct.proto`.\n*   [`types/known/fieldmaskpb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/fieldmaskpb):\n    Package `fieldmaskpb` is the generated package for\n    `google/protobuf/field_mask.proto`.\n*   [`types/known/apipb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/apipb):\n    Package `apipb` is the generated package for\n    `google/protobuf/api.proto`.\n*   [`types/known/typepb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/typepb):\n    Package `typepb` is the generated package for\n    `google/protobuf/type.proto`.\n*   [`types/known/sourcecontextpb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/sourcecontextpb):\n    Package `sourcecontextpb` is the generated package for\n    `google/protobuf/source_context.proto`.\n*   [`types/known/emptypb`](https://pkg.go.dev/google.golang.org/protobuf/types/known/emptypb):\n    Package `emptypb` is the generated package for\n    `google/protobuf/empty.proto`.\n*   [`types/descriptorpb`](https://pkg.go.dev/google.golang.org/protobuf/types/descriptorpb):\n    Package `descriptorpb` is the generated package for\n    `google/protobuf/descriptor.proto`.\n*   [`types/pluginpb`](https://pkg.go.dev/google.golang.org/protobuf/types/pluginpb):\n    Package `pluginpb` is the generated package for\n    `google/protobuf/compiler/plugin.proto`.\n*   [`compiler/protogen`](https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen):\n    Package `protogen` provides support for writing protoc plugins.\n*   [`cmd/protoc-gen-go`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go):\n    The `protoc-gen-go` binary is a protoc plugin to generate a Go protocol\n    buffer package.\n\n## Reporting issues\n\nThe issue tracker for this project is currently located at\n[golang/protobuf](https://github.com/golang/protobuf/issues).\n\nPlease report any issues there with a sufficient description of the bug or\nfeature request. Bug reports should ideally be accompanied by a minimal\nreproduction of the issue. Irreproducible bugs are difficult to diagnose and fix\n(and likely to be closed after some period of time). Bug reports must specify\nthe version of the\n[Go protocol buffer module](https://github.com/protocolbuffers/protobuf-go/releases)\nand also the version of the\n[protocol buffer toolchain](https://github.com/protocolbuffers/protobuf/releases)\nbeing used.\n\n## Contributing\n\nThis project is open-source and accepts contributions. See the\n[contribution guide](https://github.com/protocolbuffers/protobuf-go/blob/master/CONTRIBUTING.md)\nfor more information.\n\n## Compatibility\n\nThis module and the generated code are expected to be stable over time. However,\nwe reserve the right to make breaking changes without notice for the following\nreasons:\n\n*   **Security:** A security issue in the specification or implementation may\n    come to light whose resolution requires breaking compatibility. We reserve\n    the right to address such issues.\n*   **Unspecified behavior:** There are some aspects of the protocol buffer\n    specification that are undefined. Programs that depend on unspecified\n    behavior may break in future releases.\n*   **Specification changes:** It may become necessary to address an\n    inconsistency, incompleteness, or change in the protocol buffer\n    specification, which may affect the behavior of existing programs. We\n    reserve the right to address such changes.\n*   **Bugs:** If a package has a bug that violates correctness, a program\n    depending on the buggy behavior may break if the bug is fixed. We reserve\n    the right to fix such bugs.\n*   **Generated additions**: We reserve the right to add new declarations to\n    generated Go packages of `.proto` files. This includes declared constants,\n    variables, functions, types, fields in structs, and methods on types. This\n    may break attempts at injecting additional code on top of what is generated\n    by `protoc-gen-go`. Such practice is not supported by this project.\n*   **Internal changes**: We reserve the right to add, modify, and remove\n    internal code, which includes all unexported declarations, the\n    [`protoc-gen-go/internal_gengo`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go/internal_gengo)\n    package, the\n    [`runtime/protoimpl`](https://pkg.go.dev/google.golang.org/protobuf/runtime/protoimpl?tab=doc)\n    package, and all packages under\n    [`internal`](https://pkg.go.dev/google.golang.org/protobuf/internal).\n\nAny breaking changes outside of these will be announced 6 months in advance to\n[protobuf@googlegroups.com](https://groups.google.com/forum/#!forum/protobuf).\n\nUsers should use generated code produced by a version of\n[`protoc-gen-go`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go)\nthat is identical to the runtime version provided by the\n[protobuf module](https://pkg.go.dev/mod/google.golang.org/protobuf). This\nproject promises that the runtime remains compatible with code produced by a\nversion of the generator that is no older than 1 year from the version of the\nruntime used, according to the release dates of the minor version. Generated\ncode is expected to use a runtime version that is at least as new as the\ngenerator used to produce it. Generated code contains references to\n[`protoimpl.EnforceVersion`](https://pkg.go.dev/google.golang.org/protobuf/runtime/protoimpl?tab=doc#EnforceVersion)\nto statically ensure that the generated code and runtime do not drift\nsufficiently far apart.\n\n## Historical legacy\n\nThis project is the second major revision\n([released in 2020](https://blog.golang.org/a-new-go-api-for-protocol-buffers))\nof the Go protocol buffer API implemented by the\n[`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf)\nmodule. The first major version\n([released publicly in 2010](https://blog.golang.org/third-party-libraries-goprotobuf-and))\nis implemented by the\n[`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf)\nmodule.\n\nThe first version predates the release of Go 1 by several years. It has a long\nhistory as one of the first core pieces of infrastructure software ever written\nin Go. As such, the Go protobuf project was one of many pioneers for determining\nwhat the Go language should even look like and what would eventually be\nconsidered good design patterns and “idiomatic” Go (by simultaneously being\nboth positive and negative examples of it).\n\nConsider the changing signature of the `proto.Unmarshal` function as an example\nof Go language and library evolution throughout the life of this project:\n\n```go\n// 2007/09/25 - Conception of Go\n\n// 2008/11/12\nexport func UnMarshal(r io.Read, pb_e reflect.Empty) *os.Error\n\n// 2008/11/13\nexport func UnMarshal(buf *[]byte, pb_e reflect.Empty) *os.Error\n\n// 2008/11/24\nexport func UnMarshal(buf *[]byte, pb_e interface{}) *os.Error\n\n// 2008/12/18\nexport func UnMarshal(buf []byte, pb_e interface{}) *os.Error\n\n// 2009/01/20\nfunc UnMarshal(buf []byte, pb_e interface{}) *os.Error\n\n// 2009/04/17\nfunc UnMarshal(buf []byte, pb_e interface{}) os.Error\n\n// 2009/05/22\nfunc Unmarshal(buf []byte, pb_e interface{}) os.Error\n\n// 2011/11/03\nfunc Unmarshal(buf []byte, pb_e interface{}) error\n\n// 2012/03/28 - Release of Go 1\n\n// 2012/06/12\nfunc Unmarshal(buf []byte, pb Message) error\n```\n\nThese changes demonstrate the difficulty of determining what the right API is\nfor any new technology. It takes time multiplied by many users to determine what\nis best; even then, “best” is often still somewhere over the horizon.\n\nThe change on June 6th, 2012 added a degree of type-safety to Go protobufs by\ndeclaring a new interface that all protobuf messages were required to implement:\n\n```go\ntype Message interface {\n   Reset()\n   String() string\n   ProtoMessage()\n}\n```\n\nThis interface reduced the set of types that can be passed to `proto.Unmarshal`\nfrom the universal set of all possible Go types to those with a special\n`ProtoMessage` marker method. The intention of this change is to limit the\nprotobuf API to only operate on protobuf data types (i.e., protobuf messages).\nFor example, there is no sensible operation if a Go channel were passed to the\nprotobuf API as a channel cannot be serialized. The restricted interface would\nprevent that.\n\nThis interface does not behaviorally describe what a protobuf message is, but\nacts as a marker with an undocumented expectation that protobuf messages must be\na Go struct with a specific layout of fields with formatted tags. This\nexpectation is not statically enforced by the Go language, for it is an\nimplementation detail checked dynamically at runtime using Go reflection. Back\nin 2012, the only types with this marker were those generated by\n`protoc-gen-go`. Since `protoc-gen-go` would always generate messages with the\nproper layout of fields, this was deemed an acceptable and dramatic improvement\nover `interface{}`.\n\nOver the next 10 years,\n[use of Go would skyrocket](https://blog.golang.org/10years) and use of\nprotobufs in Go would skyrocket as well. With increased popularity also came\nmore diverse usages and requirements for Go protobufs and an increased number of\ncustom `proto.Message` implementations that were not generated by\n`protoc-gen-go`.\n\nThe increasingly diverse ecosystem of Go types implementing the `proto.Message`\ninterface led to incompatibilities, which often occurred when:\n\n*   **Passing custom `proto.Message` types to the protobuf APIs**: A concrete\n    message implementation might work with some top-level functions (e.g.,\n    `proto.Marshal`), but cause others (e.g., `proto.Equal`) to choke and panic.\n    This occurs because the type only had partial support for being an actual\n    message by only implementing the `proto.Marshaler` interface or having\n    malformed struct field tags that happened to work with one function, but not\n    another.\n\n*   **Using Go reflection on any `proto.Message` types**: A common desire is to\n    write general-purpose code that operates on any protobuf message. For\n    example, a microservice might want to populate a `trace_id` field if it is\n    present in a message. To accomplish this, one would use Go reflection to\n    introspect the message type, and assume it were a pointer to a Go struct\n    with a field named `TraceId` (as would be commonly produced by\n    `protoc-gen-go`). If the concrete message type did not match this\n    expectation, it either failed to work or even resulted in a panic. Such was\n    the case for concrete message types that might be backed by a Go map instead\n    of a Go struct.\n\nBoth of these issues are solved by following the idiom that _interfaces should\ndescribe behavior, not data_. This means that the interface itself should\nprovide sufficient functionality through its methods that users can introspect\nand interact with all aspects of a protobuf message through a principled API.\nThis feature is called _protobuf reflection_. Just as how Go reflection provides\nan API for programmatically interacting with any arbitrary Go value, protobuf\nreflection provides an API for programmatically interacting with any arbitrary\nprotobuf message.\n\nSince an interface cannot be extended in a backwards compatible way, this\nsuggested the need for a new major version that defines a new `proto.Message`\ninterface:\n\n```go\ntype Message interface {\n    ProtoReflect() protoreflect.Message\n}\n```\n\nThe new\n[`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message)\ninterface contains a single `ProtoReflect` method that returns a\n[`protoreflect.Message`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message),\nwhich is a reflective view over a protobuf message. In addition to making a\nbreaking change to the `proto.Message` interface, we took this opportunity to\ncleanup the supporting functionality that operate on a `proto.Message`, split up\ncomplicated functionality apart into manageable packages, and to hide\nimplementation details away from the public API.\n\nThe goal for this major revision is to improve upon all the benefits of, while\naddressing all the shortcomings of the old API. We hope that it will serve the\nGo ecosystem well for the next 10 years and beyond.\n","funding_links":[],"categories":["gRPC","Go","Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotocolbuffers%2Fprotobuf-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotocolbuffers%2Fprotobuf-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotocolbuffers%2Fprotobuf-go/lists"}