This repo builds on top of the reflection capabilities in the Protobuf runtime for Go and also provides reflection APIs for gRPC as well.
Note
Version 2.0.0 is still a work in progress. It is basically feature complete, but still needs more tests for the new functionality.
You can try it out by getting a pre-release version:
go get github.com/jhump/protoreflect/[email protected]
Note that the APIs may change a little bit between now and a final v2.0.0 release. Also note that some packages in v2 still need more tests, so you may find some bugs. But that should mostly be for new functionality. If you're just trying to update your code from v1 of this repo, those packages should be rock-solid and least likely to see any further API changes.
The protoreflect package in
the Protobuf Go runtime provides the Descriptor interface and implementations of it that correspond
to each of the descriptor types. These types are effectively smart wrappers around the generated Protobuf
types in the descriptorpb package.
These wrappers make descriptors much more useful and easier to use.
This repo provides some additional packages for using and interacting with descriptors.
import "github.com/jhump/protoreflect/v2/protoprint"The protoprint package allows for printing of descriptors to .proto source files. This is
effectively the inverse of a parser/compiler (such as the protocompile
package.) Combined with the protobuilder package, this is a useful tool for programmatically
generating protocol buffer sources.
import "github.com/jhump/protoreflect/v2/protobuilder"The protobuilder package allows for programmatic construction of rich descriptors. Descriptors can
be constructed programmatically by creating trees of descriptor protos and using the protodesc
package to link those into rich descriptors. But constructing a valid tree of descriptor protos is far
from trivial.
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.
import "github.com/jhump/protoreflect/v2/protoresolve"The protoresolve package provides named interfaces for many kinds of resolvers. It also provides
a Resolver interface that acts like a union of the various resolver interfaces and unifies both
descriptor resolvers and type resolvers. The former returns descriptor instances; the latter
returns types (often implemented by the dynamicpb package). These interfaces provide a comprehensive
set of types for resolving elements in Protobuf schemas and effectively extend the APIs in
the protoregistry package
provided by the Protobuf Go runtime.
import "github.com/jhump/protoreflect/v2/protomessage"The protomessage package contains helpers for work with proto.Message instances from generic
and/or dynamic code.
import "github.com/jhump/protoreflect/v2/protodescs"The protodescs package contains miscellaneous helpers for working with descriptors.
Generated Protobuf types in Go do not include "source code information". Source code information is data that comes from the original Protobuf source file that defined messages and includes things like position information (i.e. the filename, line, and column on which a message, enum, or service was defined) and comments.
This repo includes some APIs to help work with source code info and also a mechanism (and Proto plugin) for restoring the source code information to the descriptors embedded in generated Go code.
import "github.com/jhump/protoreflect/v2/sourceinfo"The sourceinfo package contains APIs that for retrieving descriptors for generated types that include
source code info. When generating Go code, source code information is not preserved. But if you also
generate code using the included protoc-gen-gosrcinfo plugin and query for the descriptors using this
package, you can access that information. The most immediate use of this information is to provide
comments for services, methods, and types to dynamic RPC clients that use the gRPC server reflection
service.
import "github.com/jhump/protoreflect/v2/sourceloc"The sourceloc package contains helpers for working with instances of protoreflect.SourceLocation
and protoreflect.SourcePath.
The dynamicpb package in the Protobuf
Go runtime provides a dynamic message implementation. It implements proto.Message but 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
Protobuf schemas. This is made possible by having the tools load descriptors at runtime.
This repo provides capabilities on top of dynamicpb to not only use message schemas dynamically but to
also use RPC schemas dynamically. This enables invoking RPCs without having any generated code for the
RPC service to be used.
import "github.com/jhump/protoreflect/v2/grpcdynamic"The grpcdynamic package provides the dynamic stub implementation. The stub can be used to issue
RPC methods using method descriptors instead of generated client interfaces.
import "github.com/jhump/protoreflect/v2/grpcreflect"The 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.