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.

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.Files,
    ExtensionResolver:  sourceinfo.Types,
})
grpc_reflection_v1alpha.RegisterServerReflectionServer(grpcServer, refSvr)

Index

• Variables
• func AddSourceInfoToEnum(ed protoreflect.EnumDescriptor) (protoreflect.EnumDescriptor, error)
• func AddSourceInfoToEnumType(et protoreflect.EnumType) (protoreflect.EnumType, error)
• func AddSourceInfoToExtensionType(xt protoreflect.ExtensionType) (protoreflect.ExtensionType, error)
• func AddSourceInfoToField(fld protoreflect.FieldDescriptor) (protoreflect.FieldDescriptor, error)
• func AddSourceInfoToFile(fd protoreflect.FileDescriptor) (protoreflect.FileDescriptor, error)
• func AddSourceInfoToMessage(md protoreflect.MessageDescriptor) (protoreflect.MessageDescriptor, error)
• func AddSourceInfoToMessageType(mt protoreflect.MessageType) (protoreflect.MessageType, error)
• func AddSourceInfoToService(sd protoreflect.ServiceDescriptor) (protoreflect.ServiceDescriptor, error)
• func ForFile(file string) (*descriptorpb.SourceCodeInfo, error)
• func Register(file string, data []byte)

Variables

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

	// Types is a registry of types that include source code info, if the
	// files they belong to were processed with protoc-gen-gosrcinfo.
	//
	// It is meant to serve as a drop-in alternative to protoregistry.GlobalTypes
	// that can include source code info in the returned types.
	Types protoresolve.TypePool = types{}
)

Functions

func AddSourceInfoToEnum

func AddSourceInfoToEnum(ed protoreflect.EnumDescriptor) (protoreflect.EnumDescriptor, error)

AddSourceInfoToEnum will return a new enum descriptor that is a copy of ed except that it includes source code info. If the file that contains the given enum descriptor already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then ed is returned as is, unchanged.

func AddSourceInfoToEnumType

func AddSourceInfoToEnumType(et protoreflect.EnumType) (protoreflect.EnumType, error)

AddSourceInfoToEnumType will return a new enum type that is a copy of et except that its associated descriptor includes source code info. If the file that contains the given enum already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then et is returned as is, unchanged.

func AddSourceInfoToExtensionType

func AddSourceInfoToExtensionType(xt protoreflect.ExtensionType) (protoreflect.ExtensionType, error)

AddSourceInfoToExtensionType will return a new extension type that is a copy of xt except that its associated descriptor includes source code info. If the file that contains the given extension already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then xt is returned as is, unchanged.

func AddSourceInfoToField

func AddSourceInfoToField(fld protoreflect.FieldDescriptor) (protoreflect.FieldDescriptor, error)

AddSourceInfoToField will return a new field descriptor that is a copy of ed except that it includes source code info. If the file that contains the given enum descriptor already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then ed is returned as is, unchanged.

func AddSourceInfoToFile

func AddSourceInfoToFile(fd protoreflect.FileDescriptor) (protoreflect.FileDescriptor, error)

AddSourceInfoToFile will return a new file descriptor that is a copy of fd except that it includes source code info. If the given file already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then fd is returned as is, unchanged.

func AddSourceInfoToMessage

func AddSourceInfoToMessage(md protoreflect.MessageDescriptor) (protoreflect.MessageDescriptor, error)

AddSourceInfoToMessage will return a new message descriptor that is a copy of md except that it includes source code info. If the file that contains the given message descriptor already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then md is returned as is, unchanged.

func AddSourceInfoToMessageType

func AddSourceInfoToMessageType(mt protoreflect.MessageType) (protoreflect.MessageType, error)

AddSourceInfoToMessageType will return a new message type that is a copy of mt except that its associated descriptor includes source code info. If the file that contains the given message already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then mt is returned as is, unchanged.

func AddSourceInfoToService

func AddSourceInfoToService(sd protoreflect.ServiceDescriptor) (protoreflect.ServiceDescriptor, error)

AddSourceInfoToService will return a new service descriptor that is a copy of sd except that it includes source code info. If the file that contains the given service descriptor already contains source info, was not registered from generated code, or was not processed with the protoc-gen-gosrcinfo plugin, then ed is returned as is, unchanged.

func ForFile

func ForFile(file string) (*descriptorpb.SourceCodeInfo, error)

ForFile 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 Register

func Register(file string, data []byte)

Register 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.