grpcreflect

Documentation

Overview

Package grpcreflect provides gRPC-specific extensions to protobuf reflection. This includes a way to access rich service descriptors for all services that a gRPC server exports.

Also included is an easy-to-use client for the gRPC reflection service. This client makes it easy to ask a server (that supports the reflection service) for metadata on its exported services, which could be used to construct a dynamic client. (See the grpcdynamic package in this same repo for more on that.)

Index

• func IsElementNotFoundError(err error) bool
• func LoadServiceDescriptor(svc *grpc.ServiceDesc) (protoreflect.ServiceDescriptor, error)
• func LoadServiceDescriptors(s GRPCServer) (map[string]protoreflect.ServiceDescriptor, error)
• type Client
  • func NewClientAuto(ctx context.Context, cc grpc.ClientConnInterface, opts ...ClientOption) *Client
  • func NewClientV1(ctx context.Context, stub refv1.ServerReflectionClient, opts ...ClientOption) *Client
  • func NewClientV1Alpha(ctx context.Context, stub refv1alpha.ServerReflectionClient, ...) *Client
  • func (cr *Client) AllExtensionNumbersForType(extendedMessageName protoreflect.FullName) ([]protoreflect.FieldNumber, error)
  • func (cr *Client) AsResolver() protoresolve.Resolver
  • func (cr *Client) FileByFilename(filename string) (protoreflect.FileDescriptor, error)
  • func (cr *Client) FileContainingExtension(extendedMessageName protoreflect.FullName, ...) (protoreflect.FileDescriptor, error)
  • func (cr *Client) FileContainingSymbol(symbol protoreflect.FullName) (protoreflect.FileDescriptor, error)
  • func (cr *Client) ListServices() ([]protoreflect.FullName, error)
  • func (cr *Client) Reset()
• type ClientOption
  • func WithAllowMissingFileDescriptors() ClientOption
  • func WithFallbackResolver(res interface{ ... }) ClientOption
  • func WithFallbackResolvers(descriptors protodesc.Resolver, exts protoregistry.ExtensionTypeResolver) ClientOption
• type GRPCServer
• type ProtocolError
  • func (p ProtocolError) Error() string

Functions

func IsElementNotFoundError

func IsElementNotFoundError(err error) bool

IsElementNotFoundError determines if the given error indicates that a file name, symbol name, or extension field was could not be found by the server.

func LoadServiceDescriptor

func LoadServiceDescriptor(svc *grpc.ServiceDesc) (protoreflect.ServiceDescriptor, error)

LoadServiceDescriptor loads a rich descriptor for a given service description generated by protoc-gen-go. Generated code contains an exported symbol with a name like "<Service>_serviceDesc" which is the service's description. It is used internally to register a service implementation with a GRPC server. But it can also be used by this package to retrieve the rich descriptor for the service.

func LoadServiceDescriptors

func LoadServiceDescriptors(s GRPCServer) (map[string]protoreflect.ServiceDescriptor, error)

LoadServiceDescriptors loads the service descriptors for all services exposed by the given GRPC server.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a client connection to a server for performing reflection calls and resolving remote symbols.

func NewClientAuto

func NewClientAuto(ctx context.Context, cc grpc.ClientConnInterface, opts ...ClientOption) *Client

NewClientAuto creates a new Client that will use either v1 or v1alpha version of reflection (based on what the server supports) with the given root context and using the given client connection.

It will first the v1 version of the reflection service. If it gets back an "Unimplemented" error, it will fall back to using the v1alpha version. It will remember which version the server supports for any subsequent operations that need to re-invoke the streaming RPC. But, if it's a very long-lived client, it will periodically retry the v1 version (in case the server is updated to support it also). The period for these retries is every hour.

func NewClientV1

func NewClientV1(ctx context.Context, stub refv1.ServerReflectionClient, opts ...ClientOption) *Client

NewClientV1 creates a new Client using the v1 version of reflection with the given root context and using the given RPC stub for talking to the server.

func NewClientV1Alpha

func NewClientV1Alpha(ctx context.Context, stub refv1alpha.ServerReflectionClient, opts ...ClientOption) *Client

NewClientV1Alpha creates a new Client using the v1alpha version of reflection with the given root context and using the given RPC stub for talking to the server.

func (*Client) AllExtensionNumbersForType

func (cr *Client) AllExtensionNumbersForType(extendedMessageName protoreflect.FullName) ([]protoreflect.FieldNumber, error)

AllExtensionNumbersForType asks the server for all known extension numbers for the given fully-qualified message name.

func (*Client) AsResolver

func (cr *Client) AsResolver() protoresolve.Resolver

AsResolver returns a protoresolve.Resolver that is backed by this client. Iteration via the various Range methods will only enumerate the snapshot of known elements at the time iteration starts. If more elements are discovered, via subsequent calls to the server to handle other queries, they will then be available to later iterations. That means that calls to NumFiles and NumFilesByPackage are not necessarily authoritative as the actual number could change concurrently.

func (*Client) FileByFilename

func (cr *Client) FileByFilename(filename string) (protoreflect.FileDescriptor, error)

FileByFilename asks the server for a file descriptor for the proto file with the given name.

func (*Client) FileContainingExtension

func (cr *Client) FileContainingExtension(extendedMessageName protoreflect.FullName, extensionNumber protoreflect.FieldNumber) (protoreflect.FileDescriptor, error)

FileContainingExtension asks the server for a file descriptor for the proto file that declares an extension with the given number for the given fully-qualified message name.

func (*Client) FileContainingSymbol

func (cr *Client) FileContainingSymbol(symbol protoreflect.FullName) (protoreflect.FileDescriptor, error)

FileContainingSymbol asks the server for a file descriptor for the proto file that declares the given fully-qualified symbol.

func (*Client) ListServices

func (cr *Client) ListServices() ([]protoreflect.FullName, error)

ListServices asks the server for the fully-qualified names of all exposed services.

func (*Client) Reset

func (cr *Client) Reset()

Reset ensures that any active stream with the server is closed, releasing any resources.

type ClientOption

type ClientOption func(*Client)

ClientOption is an option that can be used to configure the behavior of a reflection client created with one of the various NewClient* functions in this package.

func WithAllowMissingFileDescriptors

func WithAllowMissingFileDescriptors() ClientOption

WithAllowMissingFileDescriptors returns an option that configures a client to allow missing files when building descriptors when possible. Missing files are often fatal errors, but with this option they can sometimes be worked around. Building a schema can only succeed with some files missing if the files in question only provide custom options and/or other unused types.

func WithFallbackResolver

func WithFallbackResolver(res interface {
	protoresolve.DependencyResolver
	protoresolve.ExtensionResolver
}) ClientOption

WithFallbackResolver returns an option that configures the client to allow falling back to the given resolvers if the server is unable to supply descriptors for a particular query.

This is the same as the plural version, WithFallbackResolvers, except that a single resolver instance can be used for both files and descriptors as well as extension types.

func WithFallbackResolvers

func WithFallbackResolvers(descriptors protodesc.Resolver, exts protoregistry.ExtensionTypeResolver) ClientOption

WithFallbackResolvers returns an option that configures the client to allow falling back to the given resolvers if the server is unable to supply descriptors for a particular query. This allows working around issues where servers' reflection service provides an incomplete set of descriptors, but the client has knowledge of the missing descriptors from another source. It is usually most appropriate to pass protoregistry.GlobalFiles and protoregistry.GlobalTypes as the resolver values.

The first value is used as a fallback for FileByFilename and FileContainingSymbol queries. The second value is used as a fallback for FileContainingExtension. It can also be used as a fallback for AllExtensionNumbersForType if it provides a method with the following signature (which *protoregistry.Types provides):

RangeExtensionsByMessage(message protoreflect.FullName, f func(protoreflect.ExtensionType) bool)

type GRPCServer

type GRPCServer = reflection.GRPCServer

GRPCServer is the interface provided by a gRPC server. In addition to being a service registrar (for registering services and handlers), it also has an accessor for retrieving metadata about all registered services.

type ProtocolError

type ProtocolError struct {
	// contains filtered or unexported fields
}

ProtocolError is an error returned when the server sends a response of the wrong type.

func (ProtocolError) Error

func (p ProtocolError) Error() string