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

• func RegisterEncodedSourceInfo(file string, data []byte) error
• func RegisterSourceInfo(file string, srcInfo *descriptorpb.SourceCodeInfo)
• func SourceInfoForFile(file string) *descriptorpb.SourceCodeInfo
• type Resolver

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.

Types

type Resolver

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

var (
	// GlobalFiles is a registry of descriptors that include source code info, if the
	// file 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{}
)