sourceinfo

package
v1.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 20, 2026 License: Apache-2.0 Imports: 8 Imported by: 7

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

Constants

This section is empty.

Variables

View Source 
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 AddSourceInfoToEnum added in v1.17.0 

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 AddSourceInfoToExtensionType added in v1.17.0 

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 descriptors 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 AddSourceInfoToFile added in v1.17.0 

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 added in v1.17.0 

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 added in v1.17.0 

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 descriptors 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 added in v1.17.0 

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 RegisterEncodedSourceInfo added in v1.13.0 

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 deprecated added in v1.15.0 

func WrapEnum(ed protoreflect.EnumDescriptor) protoreflect.EnumDescriptor

WrapEnum is present for backwards-compatibility reasons. It calls AddSourceInfoToEnum and panics if that function returns an error.

Deprecated: Use AddSourceInfoToEnum directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

func WrapExtensionType deprecated added in v1.15.0 

func WrapExtensionType(xt protoreflect.ExtensionType) protoreflect.ExtensionType

WrapExtensionType is present for backwards-compatibility reasons. It calls AddSourceInfoToExtensionType and panics if that function returns an error.

Deprecated: Use AddSourceInfoToExtensionType directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

func WrapFile deprecated added in v1.15.0 

func WrapFile(fd protoreflect.FileDescriptor) protoreflect.FileDescriptor

WrapFile is present for backwards-compatibility reasons. It calls AddSourceInfoToFile and panics if that function returns an error.

Deprecated: Use AddSourceInfoToFile directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

func WrapMessage deprecated added in v1.15.0 

func WrapMessage(md protoreflect.MessageDescriptor) protoreflect.MessageDescriptor

WrapMessage is present for backwards-compatibility reasons. It calls AddSourceInfoToMessage and panics if that function returns an error.

Deprecated: Use AddSourceInfoToMessage directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

func WrapMessageType deprecated added in v1.15.0 

func WrapMessageType(mt protoreflect.MessageType) protoreflect.MessageType

WrapMessageType is present for backwards-compatibility reasons. It calls AddSourceInfoToMessageType and panics if that function returns an error.

Deprecated: Use AddSourceInfoToMessageType directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

func WrapService deprecated added in v1.15.0 

func WrapService(sd protoreflect.ServiceDescriptor) protoreflect.ServiceDescriptor

WrapService is present for backwards-compatibility reasons. It calls AddSourceInfoToService and panics if that function returns an error.

Deprecated: Use AddSourceInfoToService directly instead. The word "wrap" is a misnomer since this method does not actually wrap the given value. Though unlikely, the operation can technically fail, so the recommended function allows the return of an error instead of panic'ing.

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 added in v1.15.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
protoc-gen-gosrcinfo command
Command protoc-gen-gosrcinfo is a protoc plugin.
 Command protoc-gen-gosrcinfo is a protoc plugin.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.