The highest tagged major version is
README
¶
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
descriptor.
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
RPC services.
[!NOTE] This branch is for maintenance of the v1.x line of releases. After v1.17.0, the
mainbranch was replaced with the in-progress work for v2.0.0. All future work will be in the v2.x line of releases, and this branch can be used if any changes or fixes need need to be back-ported to v1.x.
[!IMPORTANT] This repo was originally built to work with the "V1" API of the Protobuf runtime for Go:
github.com/golang/protobuf.Since the creation of this repo, a new runtime for Go has been released, a "V2" of the API in
google.golang.org/protobuf. This newer API now includes support for functionality that this repo implements:
- Descriptors: This repo provides
github.com/jhump/protoreflect/desc. The new API now provides alternative types ingoogle.golang.org/protobuf/reflect/protoreflect. It also provides ways to access descriptors for statically linked types ingoogle.golang.org/protobuf/reflect/protoregistryand the ability to convert between these descriptor types and their "poorer cousins", descriptor protos, ingoogle.golang.org/protobuf/reflect/protodesc- Dynamic Messages: This repo provides
github.com/jhump/protoreflect/dynamic. The new API now provides an alternative ingoogle.golang.org/protobuf/types/dynamicpb.- Binary Wire Format: This repo provides
github.com/jhump/protoreflect/codec. The new API now provides an alternative ingoogle.golang.org/protobuf/encoding/protowire.Most protobuf users have certainly upgraded to that newer runtime by now and thus encounter some friction using this repo. It is now recommended to use the above packages in the V2 Protobuf API instead of using the corresponding packages in this repo. But that still leaves a lot of functionality in this repo, such as the
desc/builder,desc/protoparse,desc/protoprint,dynamic/grpcdynamic,dynamic/msgregistry, andgrpcreflectpackages herein. And all of these packages build on the coredesc.Descriptortypes in this repo. As of v1.15.0, you can convert between this repo'sdesc.Descriptortypes and the V2 API'sprotoreflect.Descriptortypes usingWrapfunctions in thedescpackage andUnwrapmethods on thedesc.Descriptortypes. That allows easier interop between these remaining useful packages and new V2 API descriptor implementations.If you have code that uses the
dynamicpackage in this repo and are trying to interop with V2 APIs, in some cases you can use theproto.MessageV2converter function (defined in the V1protopackage ingithub.com/golang/protobuf/proto). However, this wrapper does not provide 100% complete interop, so in some cases you may have to port your code over to the V2 API'sdynamicpbpackage. (Sorry!)
Descriptors: The Language Model of Protocol Buffers
import "github.com/jhump/protoreflect/desc"
The 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 protoc), and
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 .proto
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 protoparse sub-package)
or by programmatically constructing them (using the builder sub-package).
import "github.com/jhump/protoreflect/desc/protoparse"
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 protoc.
import "github.com/jhump/protoreflect/desc/protoprint"
The 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.
import "github.com/jhump/protoreflect/desc/builder"
The builder package allows for programmatic construction of rich descriptors. Descriptors can
be constructed programmatically by creating trees of descriptor protos and using the desc 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.
Dynamic Messages and Stubs
import "github.com/jhump/protoreflect/dynamic"
The dynamic package 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 protocol buffer schemas. This is made possible by having the tools load
descriptors at runtime.
import "github.com/jhump/protoreflect/dynamic/grpcdynamic"
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
import "github.com/jhump/protoreflect/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.
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |
|
builder
Package builder contains a means of building and modifying proto descriptors programmatically.
|
Package builder contains a means of building and modifying proto descriptors programmatically. |
|
protoparse
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. |
|
protoparse/ast
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. |
|
protoparse/internal/protocompile
Package protocompile provides the entry point for a high performance native Go protobuf compiler.
|
Package protocompile provides the entry point for a high performance native Go protobuf compiler. |
|
protoparse/internal/protocompile/ast
Package ast defines types for modeling the AST (Abstract Syntax Tree) for the Protocol Buffers interface definition language.
|
Package ast defines types for modeling the AST (Abstract Syntax Tree) for the Protocol Buffers interface definition language. |
|
protoparse/internal/protocompile/internal/cases
Package cases provides functions for inter-converting between different case styles.
|
Package cases provides functions for inter-converting between different case styles. |
|
protoparse/internal/protocompile/internal/editions
Package editions contains helpers related to resolving features for Protobuf editions.
|
Package editions contains helpers related to resolving features for Protobuf editions. |
|
protoparse/internal/protocompile/internal/ext/unsafex
Package unsafex contains extensions to Go's package unsafe.
|
Package unsafex contains extensions to Go's package unsafe. |
|
protoparse/internal/protocompile/internal/featuresext
Package featuresext provides file descriptors for the "google/protobuf/cpp_features.proto" and "google/protobuf/java_features.proto" standard import files.
|
Package featuresext provides file descriptors for the "google/protobuf/cpp_features.proto" and "google/protobuf/java_features.proto" standard import files. |
|
protoparse/internal/protocompile/linker
Package linker contains logic and APIs related to linking a protobuf file.
|
Package linker contains logic and APIs related to linking a protobuf file. |
|
protoparse/internal/protocompile/options
Package options contains the logic for interpreting options.
|
Package options contains the logic for interpreting options. |
|
protoparse/internal/protocompile/parser
Package parser contains the logic for parsing protobuf source code into an AST (abstract syntax tree) and also for converting an AST into a descriptor proto.
|
Package parser contains the logic for parsing protobuf source code into an AST (abstract syntax tree) and also for converting an AST into a descriptor proto. |
|
protoparse/internal/protocompile/protoutil
Package protoutil contains useful functions for interacting with descriptors.
|
Package protoutil contains useful functions for interacting with descriptors. |
|
protoparse/internal/protocompile/reporter
Package reporter contains the types used for reporting errors from protocompile operations.
|
Package reporter contains the types used for reporting errors from protocompile operations. |
|
protoparse/internal/protocompile/sourceinfo
Package sourceinfo contains the logic for computing source code info for a file descriptor.
|
Package sourceinfo contains the logic for computing source code info for a file descriptor. |
|
protoparse/internal/protocompile/walk
Package walk provides helper functions for traversing all elements in a protobuf file descriptor.
|
Package walk provides helper functions for traversing all elements in a protobuf file descriptor. |
|
protoprint
Package protoprint provides a mechanism to generate protobuf source code from descriptors.
|
Package protoprint provides a mechanism to generate protobuf source code from descriptors. |
|
sourceinfo
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. |
|
sourceinfo/cmd/protoc-gen-gosrcinfo
command
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. |
|
grpcdynamic
Package grpcdynamic provides a dynamic RPC stub.
|
Package grpcdynamic provides a dynamic RPC stub. |
|
msgregistry
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. |