sourceinfo

Documentation

Overview

Package sourceinfo provides the ability to register and query source code info for file descriptors that are compiled into the binary. This data is registered by code generated from the protoc-gen-gosrcinfo plugin.

The standard descriptors bundled into the compiled binary are stripped of source code info, to reduce binary size and reduce runtime memory footprint. However, the source code info can be very handy and worth the size cost when used with gRPC services and the server reflection service. Without source code info, the descriptors that a client downloads from the reflection service have no comments. But the presence of comments, and the ability to show them to humans, can greatly improve the utility of user agents that use the reflection service.

When the protoc-gen-gosrcinfo plugin is used, the desc.Load* methods, which load descriptors for compiled-in elements, will automatically include source code info, using the data registered with this package.

In order to make the reflection service use this functionality, you will need to be using v1.45 or higher of the Go runtime for gRPC (google.golang.org/grpc). The following snippet demonstrates how to do this in your server. Do this instead of using the reflection.Register function:

refSvr := reflection.NewServer(reflection.ServerOptions{
    Services:           grpcServer,
    DescriptorResolver: sourceinfo.GlobalFiles,
    ExtensionResolver:  sourceinfo.GlobalFiles,
})
grpc_reflection_v1alpha.RegisterServerReflectionServer(grpcServer, refSvr)

Index

• Variables
• func RegisterEncodedSourceInfo(file string, data []byte) error
• func RegisterSourceInfo(file string, srcInfo *descriptorpb.SourceCodeInfo)
• func SourceInfoForFile(file string) *descriptorpb.SourceCodeInfo
• func WrapEnum(ed protoreflect.EnumDescriptor) protoreflect.EnumDescriptor
• func WrapExtensionType(xt protoreflect.ExtensionType) protoreflect.ExtensionType
• func WrapFile(fd protoreflect.FileDescriptor) protoreflect.FileDescriptor
• func WrapMessage(md protoreflect.MessageDescriptor) protoreflect.MessageDescriptor
• func WrapMessageType(mt protoreflect.MessageType) protoreflect.MessageType
• func WrapService(sd protoreflect.ServiceDescriptor) protoreflect.ServiceDescriptor
• type Resolver
• type TypeResolver

Variables

var (
	// GlobalFiles is a registry of descriptors that include source code info, if the
	// files they belong to were processed with protoc-gen-gosrcinfo.
	//
	// If is mean to serve as a drop-in alternative to protoregistry.GlobalFiles that
	// can include source code info in the returned descriptors.
	GlobalFiles Resolver = registry{}

	// GlobalTypes is a registry of descriptors that include source code info, if the
	// files they belong to were processed with protoc-gen-gosrcinfo.
	//
	// If is mean to serve as a drop-in alternative to protoregistry.GlobalTypes that
	// can include source code info in the returned descriptors.
	GlobalTypes TypeResolver = registry{}
)

Functions

func RegisterEncodedSourceInfo

func RegisterEncodedSourceInfo(file string, data []byte) error

RegisterEncodedSourceInfo registers the given source code info, which is a serialized and gzipped form of a google.protobuf.SourceCodeInfo message.

This is automatically used from generated code if using the protoc-gen-gosrcinfo plugin.

func RegisterSourceInfo

func RegisterSourceInfo(file string, srcInfo *descriptorpb.SourceCodeInfo)

RegisterSourceInfo registers the given source code info for the file descriptor with the given path/name.

This is automatically used from older generated code if using a previous release of the protoc-gen-gosrcinfo plugin.

func SourceInfoForFile

func SourceInfoForFile(file string) *descriptorpb.SourceCodeInfo

SourceInfoForFile queries for any registered source code info for the file descriptor with the given path/name. It returns nil if no source code info was registered.

func WrapEnum

func WrapEnum(ed protoreflect.EnumDescriptor) protoreflect.EnumDescriptor

WrapEnum wraps the given enum descriptor so that it will include source code info that was registered with this package if the file it is defined in was processed with protoc-gen-gosrcinfo. Returns ed without wrapping if ed's parent file already contains source code info.

func WrapExtensionType

func WrapExtensionType(xt protoreflect.ExtensionType) protoreflect.ExtensionType

WrapExtensionType wraps the given extension type so that its associated descriptor will include source code info that was registered with this package if the file it is defined in was processed with protoc-gen-gosrcinfo. Returns xt without wrapping if the parent file of xt's descriptor already contains source code info.

func WrapFile

func WrapFile(fd protoreflect.FileDescriptor) protoreflect.FileDescriptor

WrapFile wraps the given file descriptor so that it will include source code info that was registered with this package if the given file was processed with protoc-gen-gosrcinfo. Returns fd without wrapping if fd already contains source code info.

func WrapMessage

func WrapMessage(md protoreflect.MessageDescriptor) protoreflect.MessageDescriptor

WrapMessage wraps the given message descriptor so that it will include source code info that was registered with this package if the file it is defined in was processed with protoc-gen-gosrcinfo. Returns md without wrapping if md's parent file already contains source code info.

func WrapMessageType

func WrapMessageType(mt protoreflect.MessageType) protoreflect.MessageType

WrapMessageType wraps the given message type so that its associated descriptor will include source code info that was registered with this package if the file it is defined in was processed with protoc-gen-gosrcinfo. Returns mt without wrapping if the parent file of mt's descriptor already contains source code info.

func WrapService

func WrapService(sd protoreflect.ServiceDescriptor) protoreflect.ServiceDescriptor

WrapService wraps the given service descriptor so that it will include source code info that was registered with this package if the file it is defined in was processed with protoc-gen-gosrcinfo. Returns sd without wrapping if sd's parent file already contains source code info.

Types

type Resolver

type Resolver interface {
	protodesc.Resolver
	protoregistry.ExtensionTypeResolver
	RangeExtensionsByMessage(message protoreflect.FullName, f func(protoreflect.ExtensionType) bool)
}

Resolver can resolve file names into file descriptors and also provides methods for resolving extensions.

type TypeResolver

type TypeResolver interface {
	protoregistry.MessageTypeResolver
	protoregistry.ExtensionTypeResolver
	RangeExtensionsByMessage(message protoreflect.FullName, f func(protoreflect.ExtensionType) bool)
}

TypeResolver can resolve message names and URLs into message descriptors and also provides methods for resolving extensions.