Protocol Buffer and gRPC Reflection
This repo provides reflection APIs for protocol buffers (also known as "protobufs" for short)
and gRPC. The core of reflection in protobufs is the
A descriptor is itself a protobuf message that describes a
.proto source file or any element
therein. So a collection of descriptors can describe an entire schema of protobuf types, including
This repo was built to work with the original "V1" API of the Protobuf runtime for Go:
Since the creation of this repo, a new runtime for Go has been release, a "V2" of the API in
google.golang.org/protobuf. Most protobuf users have likely upgraded to that newer runtime and thus likely encounter some interop issues using this repo. In the meantime, you can often work around these issues using the
proto.MessageV2 converter functions (both are defined in the V1
proto package). You can also now wrap instances of
protoreflect.Descriptor (using functions in the
desc package), to use them with APIs in this module. Similarly, you can unwrap a
desc.Descriptor to extract a
protoreflect.Descriptor, to use descriptors created by this module with the API v2 reflection functionality.
Later this year (2023), we expect to cut a v2 of this whole repo. The V2 protobuf API now includes support for descriptors and dynamic messages, and it also exposes numerous low-level aspects like the binary wire format. So a lot of what's in this repo is no longer necessary. But some features still are, such as the
grpcreflect packages. These will remain in the V2 form of the repo (though possibly rearranged a little). Noticeably absent from the list above is
desc/protoparse, whose V2 API is already available in a brand new module named
protocompile. It has a much improved API, provides better performance, and directly uses the reflection APIs in the v2 Protobuf runtime.
Descriptors: The Language Model of Protocol Buffers
desc package herein introduces a
Descriptor interface and implementations of it that
correspond to each of the descriptor types. These new types are effectively smart wrappers around
the generated protobuf types
that make them much more useful and easier to use.
You can construct descriptors from file descriptor sets (which can be generated by
you can also load descriptors for messages and services that are linked into the current binary.
"What does it mean for messages and services to be linked in?" you may ask. It means your binary
imports a package that was generated by
protoc. When you generate Go code from your
sources, the resulting package has descriptor information embedded in it. The
desc package allows
you to easily extract those embedded descriptors.
Descriptors can also be acquired directly from
.proto source files (using the
or by programmatically constructing them (using the
protoparse package allows for parsing of
.proto source files into rich descriptors. Without
this package, you must invoke
protoc to either generate a file descriptor set file or to generate
Go code (which has descriptor information embedded in it). This package allows reading the source
directly without having to invoke
protoprint package allows for printing of descriptors to
.proto source files. This is
effectively the inverse of the
protoparse package. Combined with the
builder package, this
is a useful tool for programmatically generating protocol buffer sources.
builder package allows for programmatic construction of rich descriptors. Descriptors can
be constructed programmatically by creating trees of descriptor protos and using the
to link those into rich descriptors. But constructing a valid tree of descriptor protos is far from
So this package provides generous API to greatly simplify that task. It also allows for converting rich descriptors into builders, which means you can programmatically modify/tweak existing descriptors.
Dynamic Messages and Stubs
dynamic package provides a dynamic message implementation. It implements
is backed by a message descriptor and a map of fields->values, instead of a generated struct. This
is useful for acting generically with protocol buffer messages, without having to generate and link
in Go code for every kind of message. This is particularly useful for general-purpose tools that
need to operate on arbitrary protocol buffer schemas. This is made possible by having the tools load
descriptors at runtime.
There is also sub-package named
grpcdynamic, which provides a dynamic stub implementation. The stub can
be used to issue RPC methods using method descriptors instead of generated client interfaces.
gRPC Server Reflection
grpcreflect package provides an easy-to-use client for the
gRPC reflection service,
making it much easier to query for and work with the schemas of remote services.
It also provides some helper methods for querying for rich service descriptors for the services registered in a gRPC server.
Package codec contains a reader/write type that assists with encoding and decoding protobuf's binary representation.
|Package codec contains a reader/write type that assists with encoding and decoding protobuf's binary representation.|
Package desc contains "rich descriptors" for protocol buffers.
|Package desc contains "rich descriptors" for protocol buffers.|
Package builder contains a means of building and modifying proto descriptors programmatically.
|Package builder contains a means of building and modifying proto descriptors programmatically.|
Package protoparse provides functionality for parsing *.proto source files into descriptors that can be used with other protoreflect packages, like dynamic messages and dynamic GRPC clients.
|Package protoparse provides functionality for parsing *.proto source files into descriptors that can be used with other protoreflect packages, like dynamic messages and dynamic GRPC clients.|
Package ast defines types for modeling the AST (Abstract Syntax Tree) for the protocol buffers source language.
|Package ast defines types for modeling the AST (Abstract Syntax Tree) for the protocol buffers source language.|
Package protoprint provides a mechanism to generate protobuf source code from descriptors.
|Package protoprint provides a mechanism to generate protobuf source code from descriptors.|
Package sourceinfo provides the ability to register and query source code info for file descriptors that are compiled into the binary.
|Package sourceinfo provides the ability to register and query source code info for file descriptors that are compiled into the binary.|
Command protoc-gen-gosrcinfo is a protoc plugin.
|Command protoc-gen-gosrcinfo is a protoc plugin.|
Package dynamic provides an implementation for a dynamic protobuf message.
|Package dynamic provides an implementation for a dynamic protobuf message.|
Package grpcdynamic provides a dynamic RPC stub.
|Package grpcdynamic provides a dynamic RPC stub.|
Package msgregistry contains a registry of known message and enum types.
|Package msgregistry contains a registry of known message and enum types.|
Package grpcreflect provides GRPC-specific extensions to protobuf reflection.
|Package grpcreflect provides GRPC-specific extensions to protobuf reflection.|
Package internal contains some code that should not be exported but needs to be shared across more than one of the protoreflect sub-packages.
|Package internal contains some code that should not be exported but needs to be shared across more than one of the protoreflect sub-packages.|