github.com/Big-big-orange/protoreflect@v0.0.0-20240408141420-285cedfdf6a4/README.md (about)

     1  # Protocol Buffer and gRPC Reflection
     2  [![Build Status](https://circleci.com/gh/jhump/protoreflect/tree/main.svg?style=svg)](https://circleci.com/gh/jhump/protoreflect/tree/main)
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/Big-big-orange/protoreflect)](https://goreportcard.com/report/github.com/Big-big-orange/protoreflect)
     4  
     5  This repo provides reflection APIs for [protocol buffers](https://developers.google.com/protocol-buffers/) (also known as "protobufs" for short)
     6  and [gRPC](https://grpc.io/). The core of reflection in protobufs is the
     7  [descriptor](https://github.com/google/protobuf/blob/199d82fde1734ab5bc931cd0de93309e50cd7ab9/src/google/protobuf/descriptor.proto).
     8  A descriptor is itself a protobuf message that describes a `.proto` source file or any element
     9  therein. So a collection of descriptors can describe an entire schema of protobuf types, including
    10  RPC services.
    11  
    12  [![GoDoc](https://godoc.org/github.com/Big-big-orange/protoreflect?status.svg)](https://godoc.org/github.com/Big-big-orange/protoreflect)
    13  
    14  ----
    15  
    16  ### ⚠️ Note
    17  
    18  This repo was originally built to work with the "V1" API of the Protobuf runtime for Go: `github.com/golang/protobuf`.
    19  
    20  Since the creation of this repo, a new runtime for Go has been release, a "V2" of the API in `google.golang.org/protobuf`. This new API now includes support for functionality that this repo implements:
    21    * _Descriptors_: This repo provides `github.com/Big-big-orange/protoreflect/desc`. The new API now provides alternative types in [`google.golang.org/protobuf/reflect/protoreflect`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect). It also provides ways to access descriptors for statically linked types in [`google.golang.org/protobuf/reflect/protoregistry`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoregistry) and the ability to convert between these descriptor types and their "poorer cousins", [descriptor protos](https://pkg.go.dev/google.golang.org/protobuf/types/descriptorpb), in [`google.golang.org/protobuf/reflect/protodesc`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protodesc)
    22    * _Dynamic Messages_: This repo provides `github.com/Big-big-orange/protoreflect/dynamic`. The new API now provides an alternative in [`google.golang.org/protobuf/types/dynamicpb`](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb).
    23    * _Binary Wire Format_: This repo provides `github.com/Big-big-orange/protoreflect/codec`. The new API now provides an alternative in [`google.golang.org/protobuf/encoding/protowire`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protowire).
    24  
    25  Most protobuf users have likely upgraded to that newer runtime 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`, and `grpcreflect` packages herein. And all of these packages build on the core `desc.Descriptor` types in this repo. As of v1.15.0, you can convert between this repo's `desc.Descriptor` types and the V2 API's `protoreflect.Descriptor` types using `Wrap` functions in the `desc` package and `Unwrap` methods on the `desc.Descriptor` types. That allows easier interop between these remaining useful packages and new V2 API descriptor implementations.
    26  
    27  If you have code that uses the `dynamic` package in this repo and are trying to interop with V2 APIs, in some cases you can use the [`proto.MessageV2`](https://pkg.go.dev/github.com/golang/protobuf/proto#MessageV2) converter function (defined in the V1 `proto` package in `github.com/golang/protobuf/proto`). This wrapper does not provide 100% complete interop, so in some cases you may have to port your code over to the V2 API's `dynamicpb` package. (Sorry!)
    28  
    29  Later this year, we expect to cut a v2 of this whole repo. A lot of what's in this repo is no longer necessary, but some features still are. The v2 will _drop_ functionality now provided by the V2 Protobuf API. The remaining packages will be updated to make direct use of the V2 Protobuf API and have no more references to the old V1 API. One exception is that a v2 of this repo will _not_ include a new version of the `desc/protoparse` package in this repo -- that is already available in a brand new module named [`protocompile`](https://pkg.go.dev/github.com/bufbuild/protocompile).
    30  
    31  ----
    32  ## Descriptors: The Language Model of Protocol Buffers
    33  
    34  ```go
    35  import "github.com/Big-big-orange/protoreflect/desc"
    36  ```
    37  
    38  The `desc` package herein introduces a `Descriptor` interface and implementations of it that
    39  correspond to each of the descriptor types. These new types are effectively smart wrappers around
    40  the [generated protobuf types](https://github.com/golang/protobuf/blob/master/protoc-gen-go/descriptor/descriptor.pb.go)
    41  that make them *much* more useful and easier to use.
    42  
    43  You can construct descriptors from file descriptor sets (which can be generated by `protoc`), and
    44  you can also load descriptors for messages and services that are linked into the current binary.
    45  "What does it mean for messages and services to be linked in?" you may ask. It means your binary
    46  imports a package that was generated by `protoc`. When you generate Go code from your `.proto`
    47  sources, the resulting package has descriptor information embedded in it. The `desc` package allows
    48  you to easily extract those embedded descriptors.
    49  
    50  Descriptors can also be acquired directly from `.proto` source files (using the `protoparse` sub-package)
    51  or by programmatically constructing them (using the `builder` sub-package).
    52  
    53  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/desc)*
    54  
    55  ```go
    56  import "github.com/Big-big-orange/protoreflect/desc/protoparse"
    57  ```
    58  
    59  The `protoparse` package allows for parsing of `.proto` source files into rich descriptors. Without
    60  this package, you must invoke `protoc` to either generate a file descriptor set file or to generate
    61  Go code (which has descriptor information embedded in it). This package allows reading the source
    62  directly without having to invoke `protoc`.
    63  
    64  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/desc/protoparse)*
    65  
    66  ```go
    67  import "github.com/Big-big-orange/protoreflect/desc/protoprint"
    68  ```
    69  
    70  The `protoprint` package allows for printing of descriptors to `.proto` source files. This is
    71  effectively the inverse of the `protoparse` package. Combined with the `builder` package, this
    72  is a useful tool for programmatically generating protocol buffer sources.
    73  
    74  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/desc/protoprint)*
    75  
    76  ```go
    77  import "github.com/Big-big-orange/protoreflect/desc/builder"
    78  ```
    79  
    80  The `builder` package allows for programmatic construction of rich descriptors. Descriptors can
    81  be constructed programmatically by creating trees of descriptor protos and using the `desc` package
    82  to link those into rich descriptors. But constructing a valid tree of descriptor protos is far from
    83  trivial.
    84  
    85  So this package provides generous API to greatly simplify that task. It also allows for converting
    86  rich descriptors into builders, which means you can programmatically modify/tweak existing
    87  descriptors.
    88  
    89  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/desc/builder)*
    90  
    91  ----
    92  ## Dynamic Messages and Stubs
    93  
    94  ```go
    95  import "github.com/Big-big-orange/protoreflect/dynamic"
    96  ```
    97  
    98  The `dynamic` package provides a dynamic message implementation. It implements `proto.Message` but
    99  is backed by a message descriptor and a map of fields->values, instead of a generated struct. This
   100  is useful for acting generically with protocol buffer messages, without having to generate and link
   101  in Go code for every kind of message. This is particularly useful for general-purpose tools that
   102  need to operate on arbitrary protocol buffer schemas. This is made possible by having the tools load
   103  descriptors at runtime.
   104  
   105  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/dynamic)*
   106  
   107  ```go
   108  import "github.com/Big-big-orange/protoreflect/dynamic/grpcdynamic"
   109  ```
   110  
   111  There is also sub-package named `grpcdynamic`, which provides a dynamic stub implementation. The stub can
   112  be used to issue RPC methods using method descriptors instead of generated client interfaces.
   113  
   114  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/dynamic/grpcdynamic)*
   115  
   116  ----
   117  ## gRPC Server Reflection
   118  
   119  ```go
   120  import "github.com/Big-big-orange/protoreflect/grpcreflect"
   121  ```
   122  
   123  The `grpcreflect` package provides an easy-to-use client for the
   124  [gRPC reflection service](https://github.com/grpc/grpc-go/blob/6bd4f6eb1ea9d81d1209494242554dcde44429a4/reflection/grpc_reflection_v1alpha/reflection.proto#L36),
   125  making it much easier to query for and work with the schemas of remote services.
   126  
   127  It also provides some helper methods for querying for rich service descriptors for the
   128  services registered in a gRPC server.
   129  
   130  *[Read more ≫](https://godoc.org/github.com/Big-big-orange/protoreflect/grpcreflect)*