desc

package
v1.10.2 Latest Latest
Warning

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

 Go to latest Published: Jan 18, 2022 License: Apache-2.0 Imports: 17 Imported by: 810

Documentation

Overview

Package desc contains "rich descriptors" for protocol buffers. The built-in descriptor types are simple protobuf messages, each one representing a different kind of element in the AST of a .proto source file.

Because of this inherent "tree" quality, these build-in descriptors cannot refer to their enclosing file descriptor. Nor can a field descriptor refer to a message or enum descriptor that represents the field's type (for enum and nested message fields). All such links must instead be stringly typed. This limitation makes them much harder to use for doing interesting things with reflection.

Without this package, resolving references to types is particularly complex. For example, resolving a field's type, the message type an extension extends, or the request and response types of an RPC method all require searching through symbols defined not only in the file in which these elements are declared but also in its transitive closure of dependencies.

"Rich descriptors" avoid the need to deal with the complexities described above. A rich descriptor has all type references resolved and provides methods to access other rich descriptors for all referenced elements. Each rich descriptor has a usefully broad API, but does not try to mimic the full interface of the underlying descriptor proto. Instead, every rich descriptor provides access to that underlying proto, for extracting descriptor properties that are not immediately accessible through rich descriptor's methods.

Rich descriptors can be accessed in similar ways as their "poor" cousins (descriptor protos). Instead of using proto.FileDescriptor, use desc.LoadFileDescriptor. Message descriptors and extension field descriptors can also be easily accessed using desc.LoadMessageDescriptor and desc.LoadFieldDescriptorForExtension, respectively.

It is also possible create rich descriptors for proto messages that a given Go program doesn't even know about. For example, they could be loaded from a FileDescriptorSet file (which can be generated by protoc) or loaded from a server. This enables interesting things like dynamic clients: where a Go program can be an RPC client of a service it wasn't compiled to know about.

Also see the grpcreflect, dynamic, and grpcdynamic packages in this same repo to see just how useful rich descriptors really are.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateFileDescriptors 

func CreateFileDescriptors(fds []*dpb.FileDescriptorProto) (map[string]*FileDescriptor, error)

CreateFileDescriptors constructs a set of descriptors, one for each of the given descriptor protos. The given set of descriptor protos must include all transitive dependencies for every file.

func CreateFileDescriptorsFromSet added in v1.5.0 

func CreateFileDescriptorsFromSet(fds *dpb.FileDescriptorSet) (map[string]*FileDescriptor, error)

CreateFileDescriptorsFromSet creates file descriptors from the given file descriptor set. The returned map includes all files in the set, keyed b name. The set must include the full set of transitive dependencies for all files therein or else a link error will occur and be returned instead of the slice of descriptors. This is the same format used by protoc when a FileDescriptorSet file with an invocation like so: 

protoc --descriptor_set_out=./test.protoset --include_imports -I. test.proto

func RegisterImportPath added in v1.2.0 

func RegisterImportPath(registerPath, importPath string)

RegisterImportPath registers an alternate import path for a given registered proto file path. For more details on why alternate import paths may need to be configured, see ImportResolver.

This method panics if provided invalid input. An empty importPath is invalid. An un-registered registerPath is also invalid. For example, if an attempt is made to register the import path "foo/bar.proto" as "bar.proto", but there is no "bar.proto" registered in the Go protobuf runtime, this method will panic. This method also panics if an attempt is made to register the same import path more than once.

This function works globally, applying to all descriptors loaded by this package. If you instead want more granular support for handling alternate import paths -- such as for a single invocation of a function in this package or when the alternate path is only used from one file (so you don't want the alternate path used when loading every other file), use an ImportResolver instead.

func ResolveImport added in v1.2.0 

func ResolveImport(importPath string) string

ResolveImport resolves the given import path. If it has been registered as an alternate via RegisterImportPath, the registered path is returned. Otherwise, the given import path is returned unchanged.

func ToFileDescriptorSet 

func ToFileDescriptorSet(fds ...*FileDescriptor) *dpb.FileDescriptorSet

ToFileDescriptorSet creates a FileDescriptorSet proto that contains all of the given file descriptors and their transitive dependencies. The files are topologically sorted so that a file will always appear after its dependencies.

Types

type Descriptor 

type Descriptor interface {
	// GetName returns the name of the object described by the descriptor. This will
	// be a base name that does not include enclosing message names or the package name.
	// For file descriptors, this indicates the path and name to the described file.
	GetName() string
	// GetFullyQualifiedName returns the fully-qualified name of the object described by
	// the descriptor. This will include the package name and any enclosing message names.
	// For file descriptors, this returns the path and name to the described file (same as
	// GetName).
	GetFullyQualifiedName() string
	// GetParent returns the enclosing element in a proto source file. If the described
	// object is a top-level object, this returns the file descriptor. Otherwise, it returns
	// the element in which the described object was declared. File descriptors have no
	// parent and return nil.
	GetParent() Descriptor
	// GetFile returns the file descriptor in which this element was declared. File
	// descriptors return themselves.
	GetFile() *FileDescriptor
	// GetOptions returns the options proto containing options for the described element.
	GetOptions() proto.Message
	// GetSourceInfo returns any source code information that was present in the file
	// descriptor. Source code info is optional. If no source code info is available for
	// the element (including if there is none at all in the file descriptor) then this
	// returns nil
	GetSourceInfo() *dpb.SourceCodeInfo_Location
	// AsProto returns the underlying descriptor proto for this descriptor.
	AsProto() proto.Message
}

Descriptor is the common interface implemented by all descriptor objects.

type EnumDescriptor 

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

EnumDescriptor describes an enum declared in a proto file.

func LoadEnumDescriptorForEnum 

func LoadEnumDescriptorForEnum(enum protoEnum) (*EnumDescriptor, error)

LoadEnumDescriptorForEnum loads descriptor using the encoded descriptor proto returned by enum.EnumDescriptor().

func LoadEnumDescriptorForType 

func LoadEnumDescriptorForType(enumType reflect.Type) (*EnumDescriptor, error)

LoadEnumDescriptorForType loads descriptor using the encoded descriptor proto returned by enum.EnumDescriptor() for the given enum type.

func (*EnumDescriptor) AsEnumDescriptorProto 

func (ed *EnumDescriptor) AsEnumDescriptorProto() *dpb.EnumDescriptorProto

AsEnumDescriptorProto returns the underlying descriptor proto.

func (*EnumDescriptor) AsProto 

func (ed *EnumDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsEnumDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*EnumDescriptor) FindValueByName 

func (ed *EnumDescriptor) FindValueByName(name string) *EnumValueDescriptor

FindValueByName finds the enum value with the given name. If no such value exists then nil is returned.

func (*EnumDescriptor) FindValueByNumber 

func (ed *EnumDescriptor) FindValueByNumber(num int32) *EnumValueDescriptor

FindValueByNumber finds the value with the given numeric value. If no such value exists then nil is returned. If aliases are allowed and multiple values have the given number, the first declared value is returned.

func (*EnumDescriptor) GetEnumOptions 

func (ed *EnumDescriptor) GetEnumOptions() *dpb.EnumOptions

GetEnumOptions returns the enum type's options.

func (*EnumDescriptor) GetFile 

func (ed *EnumDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this enum is defined.

func (*EnumDescriptor) GetFullyQualifiedName 

func (ed *EnumDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the enum type. This includes the package name (if there is one) as well as the names of any enclosing messages.

func (*EnumDescriptor) GetName 

func (ed *EnumDescriptor) GetName() string

GetName returns the simple (unqualified) name of the enum type.

func (*EnumDescriptor) GetOptions 

func (ed *EnumDescriptor) GetOptions() proto.Message

GetOptions returns the enum type's options. Most usages will be more interested in GetEnumOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*EnumDescriptor) GetParent 

func (ed *EnumDescriptor) GetParent() Descriptor

GetParent returns the enum type's enclosing descriptor. For top-level enums, this will be a file descriptor. Otherwise it will be the descriptor for the enclosing message.

func (*EnumDescriptor) GetSourceInfo 

func (ed *EnumDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the enum type, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the enum type was defined and also contains comments associated with the enum definition.

func (*EnumDescriptor) GetValues 

func (ed *EnumDescriptor) GetValues() []*EnumValueDescriptor

GetValues returns all of the allowed values defined for this enum.

func (*EnumDescriptor) String 

func (ed *EnumDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type EnumValueDescriptor 

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

EnumValueDescriptor describes an allowed value of an enum declared in a proto file.

func (*EnumValueDescriptor) AsEnumValueDescriptorProto 

func (vd *EnumValueDescriptor) AsEnumValueDescriptorProto() *dpb.EnumValueDescriptorProto

AsEnumValueDescriptorProto returns the underlying descriptor proto.

func (*EnumValueDescriptor) AsProto 

func (vd *EnumValueDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsEnumValueDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*EnumValueDescriptor) GetEnum 

func (vd *EnumValueDescriptor) GetEnum() *EnumDescriptor

GetEnum returns the enum in which this enum value is defined.

func (*EnumValueDescriptor) GetEnumValueOptions 

func (vd *EnumValueDescriptor) GetEnumValueOptions() *dpb.EnumValueOptions

GetEnumValueOptions returns the enum value's options.

func (*EnumValueDescriptor) GetFile 

func (vd *EnumValueDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this enum value is defined.

func (*EnumValueDescriptor) GetFullyQualifiedName 

func (vd *EnumValueDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the enum value. Unlike GetName, this includes fully qualified name of the enclosing enum.

func (*EnumValueDescriptor) GetName 

func (vd *EnumValueDescriptor) GetName() string

GetName returns the name of the enum value.

func (*EnumValueDescriptor) GetNumber 

func (vd *EnumValueDescriptor) GetNumber() int32

GetNumber returns the numeric value associated with this enum value.

func (*EnumValueDescriptor) GetOptions 

func (vd *EnumValueDescriptor) GetOptions() proto.Message

GetOptions returns the enum value's options. Most usages will be more interested in GetEnumValueOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*EnumValueDescriptor) GetParent 

func (vd *EnumValueDescriptor) GetParent() Descriptor

GetParent returns the descriptor for the enum in which this enum value is defined. Most usages will prefer to use GetEnum, which has a concrete return type. This more generic method is present to satisfy the Descriptor interface.

func (*EnumValueDescriptor) GetSourceInfo 

func (vd *EnumValueDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the enum value, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the enum value was defined and also contains comments associated with the enum value definition.

func (*EnumValueDescriptor) String 

func (vd *EnumValueDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type FieldDescriptor 

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

FieldDescriptor describes a field of a protocol buffer message.

func LoadFieldDescriptorForExtension 

func LoadFieldDescriptorForExtension(ext *proto.ExtensionDesc) (*FieldDescriptor, error)

LoadFieldDescriptorForExtension loads the field descriptor that corresponds to the given extension description.

func (*FieldDescriptor) AsFieldDescriptorProto 

func (fd *FieldDescriptor) AsFieldDescriptorProto() *dpb.FieldDescriptorProto

AsFieldDescriptorProto returns the underlying descriptor proto.

func (*FieldDescriptor) AsProto 

func (fd *FieldDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsFieldDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*FieldDescriptor) GetDefaultValue 

func (fd *FieldDescriptor) GetDefaultValue() interface{}

GetDefaultValue returns the default value for this field.

If this field represents a message type, this method always returns nil (even though for proto2 files, the default value should be a default instance of the message type). If the field represents an enum type, this method returns an int32 corresponding to the enum value. If this field is a map, it returns a nil map[interface{}]interface{}. If this field is repeated (and not a map), it returns a nil []interface{}.

Otherwise, it returns the declared default value for the field or a zero value, if no default is declared or if the file is proto3. The type of said return value corresponds to the type of the field: 

+-------------------------+-----------+
|       Declared Type     |  Go Type  |
+-------------------------+-----------+
| int32, sint32, sfixed32 | int32     |
| int64, sint64, sfixed64 | int64     |
| uint32, fixed32         | uint32    |
| uint64, fixed64         | uint64    |
| float                   | float32   |
| double                  | double32  |
| bool                    | bool      |
| string                  | string    |
| bytes                   | []byte    |
+-------------------------+-----------+

func (*FieldDescriptor) GetEnumType 

func (fd *FieldDescriptor) GetEnumType() *EnumDescriptor

GetEnumType returns the type of this field if it is an enum type. If this field is not an enum type, it returns nil.

func (*FieldDescriptor) GetFieldOptions 

func (fd *FieldDescriptor) GetFieldOptions() *dpb.FieldOptions

GetFieldOptions returns the field's options.

func (*FieldDescriptor) GetFile 

func (fd *FieldDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this field is defined.

func (*FieldDescriptor) GetFullyQualifiedJSONName 

func (fd *FieldDescriptor) GetFullyQualifiedJSONName() string

GetFullyQualifiedJSONName returns the JSON format name (same as GetJSONName), but includes the fully qualified name of the enclosing message.

If the field is an extension, it will return the package name (if there is one) as well as the names of any enclosing messages. The package and/or enclosing messages are for where the extension is defined, not the message it extends.

func (*FieldDescriptor) GetFullyQualifiedName 

func (fd *FieldDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the field. Unlike GetName, this includes fully qualified name of the enclosing message for regular fields.

For extension fields, this includes the package (if there is one) as well as any enclosing messages. The package and/or enclosing messages are for where the extension is defined, not the message it extends.

If this field is part of a one-of, the fully qualified name does *not* include the name of the one-of, only of the enclosing message.

func (*FieldDescriptor) GetJSONName 

func (fd *FieldDescriptor) GetJSONName() string

GetJSONName returns the name of the field as referenced in the message's JSON format.

func (*FieldDescriptor) GetLabel 

func (fd *FieldDescriptor) GetLabel() dpb.FieldDescriptorProto_Label

GetLabel returns the label for this field. The label can be required (proto2-only), optional (default for proto3), or required.

func (*FieldDescriptor) GetMapKeyType 

func (fd *FieldDescriptor) GetMapKeyType() *FieldDescriptor

GetMapKeyType returns the type of the key field if this is a map field. If it is not a map field, nil is returned.

func (*FieldDescriptor) GetMapValueType 

func (fd *FieldDescriptor) GetMapValueType() *FieldDescriptor

GetMapValueType returns the type of the value field if this is a map field. If it is not a map field, nil is returned.

func (*FieldDescriptor) GetMessageType 

func (fd *FieldDescriptor) GetMessageType() *MessageDescriptor

GetMessageType returns the type of this field if it is a message type. If this field is not a message type, it returns nil.

func (*FieldDescriptor) GetName 

func (fd *FieldDescriptor) GetName() string

GetName returns the name of the field.

func (*FieldDescriptor) GetNumber 

func (fd *FieldDescriptor) GetNumber() int32

GetNumber returns the tag number of this field.

func (*FieldDescriptor) GetOneOf 

func (fd *FieldDescriptor) GetOneOf() *OneOfDescriptor

GetOneOf returns the one-of field set to which this field belongs. If this field is not part of a one-of then this method returns nil.

func (*FieldDescriptor) GetOptions 

func (fd *FieldDescriptor) GetOptions() proto.Message

GetOptions returns the field's options. Most usages will be more interested in GetFieldOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*FieldDescriptor) GetOwner 

func (fd *FieldDescriptor) GetOwner() *MessageDescriptor

GetOwner returns the message type that this field belongs to. If this is a normal field then this is the same as GetParent. But for extensions, this will be the extendee message whereas GetParent refers to where the extension was declared.

func (*FieldDescriptor) GetParent 

func (fd *FieldDescriptor) GetParent() Descriptor

GetParent returns the fields's enclosing descriptor. For normal (non-extension) fields, this is the enclosing message. For extensions, this is the descriptor in which the extension is defined, not the message that is extended. The parent for an extension may be a file descriptor or a message, depending on where the extension is defined.

func (*FieldDescriptor) GetSourceInfo 

func (fd *FieldDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the field, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the field was defined and also contains comments associated with the field definition.

func (*FieldDescriptor) GetType 

func (fd *FieldDescriptor) GetType() dpb.FieldDescriptorProto_Type

GetType returns the type of this field. If the type indicates an enum, the enum type can be queried via GetEnumType. If the type indicates a message, the message type can be queried via GetMessageType.

func (*FieldDescriptor) HasPresence added in v1.7.0 

func (fd *FieldDescriptor) HasPresence() bool

HasPresence returns true if this field can distinguish when a value is present or not. Scalar fields in "proto3" syntax files, for example, return false since absent values are indistinguishable from zero values.

func (*FieldDescriptor) IsExtension 

func (fd *FieldDescriptor) IsExtension() bool

IsExtension returns true if this is an extension field.

func (*FieldDescriptor) IsMap 

func (fd *FieldDescriptor) IsMap() bool

IsMap returns true if this is a map field. If so, it will have the "repeated" label its type will be a message that represents a map entry. The map entry message will have exactly two fields: tag #1 is the key and tag #2 is the value.

func (*FieldDescriptor) IsProto3Optional added in v1.7.0 

func (fd *FieldDescriptor) IsProto3Optional() bool

IsProto3Optional returns true if this field has an explicit "optional" label and is in a "proto3" syntax file. Such fields, if they are normal fields (not extensions), will be nested in synthetic oneofs that contain only the single field.

func (*FieldDescriptor) IsRepeated 

func (fd *FieldDescriptor) IsRepeated() bool

IsRepeated returns true if this field has the "repeated" label.

func (*FieldDescriptor) IsRequired 

func (fd *FieldDescriptor) IsRequired() bool

IsRequired returns true if this field has the "required" label.

func (*FieldDescriptor) String 

func (fd *FieldDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type FileDescriptor 

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

FileDescriptor describes a proto source file.

func CreateFileDescriptor 

func CreateFileDescriptor(fd *dpb.FileDescriptorProto, deps ...*FileDescriptor) (*FileDescriptor, error)

CreateFileDescriptor instantiates a new file descriptor for the given descriptor proto. The file's direct dependencies must be provided. If the given dependencies do not include all of the file's dependencies or if the contents of the descriptors are internally inconsistent (e.g. contain unresolvable symbols) then an error is returned.

func CreateFileDescriptorFromSet 

func CreateFileDescriptorFromSet(fds *dpb.FileDescriptorSet) (*FileDescriptor, error)

CreateFileDescriptorFromSet creates a descriptor from the given file descriptor set. The set's *last* file will be the returned descriptor. The set's remaining files must comprise the full set of transitive dependencies of that last file. This is the same format and order used by protoc when emitting a FileDescriptorSet file with an invocation like so: 

protoc --descriptor_set_out=./test.protoset --include_imports -I. test.proto

func LoadFileDescriptor 

func LoadFileDescriptor(file string) (*FileDescriptor, error)

LoadFileDescriptor creates a file descriptor using the bytes returned by proto.FileDescriptor. Descriptors are cached so that they do not need to be re-processed if the same file is fetched again later.

func (*FileDescriptor) AsFileDescriptorProto 

func (fd *FileDescriptor) AsFileDescriptorProto() *dpb.FileDescriptorProto

AsFileDescriptorProto returns the underlying descriptor proto.

func (*FileDescriptor) AsProto 

func (fd *FileDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsFileDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*FileDescriptor) FindEnum 

func (fd *FileDescriptor) FindEnum(enumName string) *EnumDescriptor

FindEnum finds the enum with the given fully-qualified name. If no such element exists in this file then nil is returned.

func (*FileDescriptor) FindExtension 

func (fd *FileDescriptor) FindExtension(extendeeName string, tagNumber int32) *FieldDescriptor

FindExtension finds the extension field for the given extended type name and tag number. If no such element exists in this file then nil is returned.

func (*FileDescriptor) FindExtensionByName 

func (fd *FileDescriptor) FindExtensionByName(extName string) *FieldDescriptor

FindExtensionByName finds the extension field with the given fully-qualified name. If no such element exists in this file then nil is returned.

func (*FileDescriptor) FindMessage 

func (fd *FileDescriptor) FindMessage(msgName string) *MessageDescriptor

FindMessage finds the message with the given fully-qualified name. If no such element exists in this file then nil is returned.

func (*FileDescriptor) FindService 

func (fd *FileDescriptor) FindService(serviceName string) *ServiceDescriptor

FindService finds the service with the given fully-qualified name. If no such element exists in this file then nil is returned.

func (*FileDescriptor) FindSymbol 

func (fd *FileDescriptor) FindSymbol(symbol string) Descriptor

FindSymbol returns the descriptor contained within this file for the element with the given fully-qualified symbol name. If no such element exists then this method returns nil.

func (*FileDescriptor) GetDependencies 

func (fd *FileDescriptor) GetDependencies() []*FileDescriptor

GetDependencies returns all of this file's dependencies. These correspond to import statements in the file.

func (*FileDescriptor) GetEnumTypes 

func (fd *FileDescriptor) GetEnumTypes() []*EnumDescriptor

GetEnumTypes returns all top-level enums declared in this file.

func (*FileDescriptor) GetExtensions 

func (fd *FileDescriptor) GetExtensions() []*FieldDescriptor

GetExtensions returns all top-level extensions declared in this file.

func (*FileDescriptor) GetFile 

func (fd *FileDescriptor) GetFile() *FileDescriptor

GetFile returns the receiver, which is a file descriptor. This is present to satisfy the Descriptor interface.

func (*FileDescriptor) GetFileOptions 

func (fd *FileDescriptor) GetFileOptions() *dpb.FileOptions

GetFileOptions returns the file's options.

func (*FileDescriptor) GetFullyQualifiedName 

func (fd *FileDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the name of the file, same as GetName. It is present to satisfy the Descriptor interface.

func (*FileDescriptor) GetMessageTypes 

func (fd *FileDescriptor) GetMessageTypes() []*MessageDescriptor

GetMessageTypes returns all top-level messages declared in this file.

func (*FileDescriptor) GetName 

func (fd *FileDescriptor) GetName() string

GetName returns the name of the file, as it was given to the protoc invocation to compile it, possibly including path (relative to a directory in the proto import path).

func (*FileDescriptor) GetOptions 

func (fd *FileDescriptor) GetOptions() proto.Message

GetOptions returns the file's options. Most usages will be more interested in GetFileOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*FileDescriptor) GetPackage 

func (fd *FileDescriptor) GetPackage() string

GetPackage returns the name of the package declared in the file.

func (*FileDescriptor) GetParent 

func (fd *FileDescriptor) GetParent() Descriptor

GetParent always returns nil: files are the root of descriptor hierarchies. Is it present to satisfy the Descriptor interface.

func (*FileDescriptor) GetPublicDependencies 

func (fd *FileDescriptor) GetPublicDependencies() []*FileDescriptor

GetPublicDependencies returns all of this file's public dependencies. These correspond to public import statements in the file.

func (*FileDescriptor) GetServices 

func (fd *FileDescriptor) GetServices() []*ServiceDescriptor

GetServices returns all services declared in this file.

func (*FileDescriptor) GetSourceInfo 

func (fd *FileDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns nil for files. It is present to satisfy the Descriptor interface.

func (*FileDescriptor) GetWeakDependencies 

func (fd *FileDescriptor) GetWeakDependencies() []*FileDescriptor

GetWeakDependencies returns all of this file's weak dependencies. These correspond to weak import statements in the file.

func (*FileDescriptor) IsProto3 

func (fd *FileDescriptor) IsProto3() bool

IsProto3 returns true if the file declares a syntax of "proto3".

func (*FileDescriptor) String 

func (fd *FileDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type ImportResolver added in v1.2.0 

type ImportResolver struct {

	// By default, an ImportResolver will fallback to consulting any paths
	// registered via the top-level RegisterImportPath function. Setting this
	// field to true will cause the ImportResolver to skip that fallback and
	// only examine its own locally registered paths.
	SkipFallbackRules bool
	// contains filtered or unexported fields
}

ImportResolver lets you work-around linking issues that are caused by mismatches between how a particular proto source file is registered in the Go protobuf runtime and how that same file is imported by other files. The file is registered using the same relative path given to protoc when the file is compiled (i.e. when Go code is generated). So if any file tries to import that source file, but using a different relative path, then a link error will occur when this package tries to load a descriptor for the importing file.

For example, let's say we have two proto source files: "foo/bar.proto" and "fubar/baz.proto". The latter imports the former using a line like so: 

import "foo/bar.proto";

However, when protoc is invoked, the command-line args looks like so: 

protoc -Ifoo/ --go_out=foo/ bar.proto
protoc -I./ -Ifubar/ --go_out=fubar/ baz.proto

Because the path given to protoc is just "bar.proto" and "baz.proto", this is how they are registered in the Go protobuf runtime. So, when loading the descriptor for "fubar/baz.proto", we'll see an import path of "foo/bar.proto" but will find no file registered with that path: 

fd, err := desc.LoadFileDescriptor("baz.proto")
// err will be non-nil, complaining that there is no such file
// found named "foo/bar.proto"

This can be remedied by registering alternate import paths using an ImportResolver. Continuing with the example above, the code below would fix any link issue: 

var r desc.ImportResolver
r.RegisterImportPath("bar.proto", "foo/bar.proto")
fd, err := r.LoadFileDescriptor("baz.proto")
// err will be nil; descriptor successfully loaded!

If there are files that are *always* imported using a different relative path then how they are registered, consider using the global RegisterImportPath function, so you don't have to use an ImportResolver for every file that imports it.

func (*ImportResolver) CreateFileDescriptor added in v1.2.0 

func (r *ImportResolver) CreateFileDescriptor(fdp *dpb.FileDescriptorProto, deps ...*FileDescriptor) (*FileDescriptor, error)

CreateFileDescriptor is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking the given descriptor proto.

func (*ImportResolver) CreateFileDescriptorFromSet added in v1.2.0 

func (r *ImportResolver) CreateFileDescriptorFromSet(fds *dpb.FileDescriptorSet) (*FileDescriptor, error)

CreateFileDescriptorFromSet is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking the descriptor protos in the given set.

func (*ImportResolver) CreateFileDescriptors added in v1.2.0 

func (r *ImportResolver) CreateFileDescriptors(fds []*dpb.FileDescriptorProto) (map[string]*FileDescriptor, error)

CreateFileDescriptors is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking the given descriptor protos.

func (*ImportResolver) CreateFileDescriptorsFromSet added in v1.5.0 

func (r *ImportResolver) CreateFileDescriptorsFromSet(fds *dpb.FileDescriptorSet) (map[string]*FileDescriptor, error)

CreateFileDescriptorsFromSet is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking the descriptor protos in the given set.

func (*ImportResolver) LoadEnumDescriptorForEnum added in v1.2.0 

func (r *ImportResolver) LoadEnumDescriptorForEnum(enum protoEnum) (*EnumDescriptor, error)

LoadEnumDescriptorForEnum is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) LoadEnumDescriptorForType added in v1.2.0 

func (r *ImportResolver) LoadEnumDescriptorForType(enumType reflect.Type) (*EnumDescriptor, error)

LoadEnumDescriptorForType is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) LoadFieldDescriptorForExtension added in v1.2.0 

func (r *ImportResolver) LoadFieldDescriptorForExtension(ext *proto.ExtensionDesc) (*FieldDescriptor, error)

LoadFieldDescriptorForExtension is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) LoadFileDescriptor added in v1.2.0 

func (r *ImportResolver) LoadFileDescriptor(filePath string) (*FileDescriptor, error)

LoadFileDescriptor is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking the given descriptor proto.

func (*ImportResolver) LoadMessageDescriptor added in v1.2.0 

func (r *ImportResolver) LoadMessageDescriptor(msgName string) (*MessageDescriptor, error)

LoadMessageDescriptor is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) LoadMessageDescriptorForMessage added in v1.2.0 

func (r *ImportResolver) LoadMessageDescriptorForMessage(msg proto.Message) (*MessageDescriptor, error)

LoadMessageDescriptorForMessage is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) LoadMessageDescriptorForType added in v1.2.0 

func (r *ImportResolver) LoadMessageDescriptorForType(msgType reflect.Type) (*MessageDescriptor, error)

LoadMessageDescriptorForType is the same as the package function of the same name, but any alternate paths configured in this resolver are used when linking files for the returned descriptor.

func (*ImportResolver) RegisterImportPath added in v1.2.0 

func (r *ImportResolver) RegisterImportPath(registerPath, importPath string)

RegisterImportPath registers an alternate import path for a given registered proto file path with this resolver. Any appearance of the given import path when linking files will instead try to link the given registered path. If the registered path cannot be located, then linking will fallback to the actual imported path.

This method will panic if given an empty path or if the same import path is registered more than once.

To constrain the contexts where the given import path is to be re-written, use RegisterImportPathFrom instead.

func (*ImportResolver) RegisterImportPathFrom added in v1.2.0 

func (r *ImportResolver) RegisterImportPathFrom(registerPath, importPath, source string)

RegisterImportPathFrom registers an alternate import path for a given registered proto file path with this resolver, but only for imports in the specified source context.

The source context can be the name of a folder or a proto source file. Any appearance of the given import path in that context will instead try to link the given registered path. To be in context, the file that is being linked (i.e. the one whose import statement is being resolved) must be the same relative path of the source context or be a sub-path (i.e. a descendant of the source folder).

If the registered path cannot be located, then linking will fallback to the actual imported path.

This method will panic if given an empty path. The source context, on the other hand, is allowed to be blank. A blank source matches all files. This method also panics if the same import path is registered in the same source context more than once.

func (*ImportResolver) ResolveImport added in v1.2.0 

func (r *ImportResolver) ResolveImport(source, importPath string) string

ResolveImport resolves the given import path in the context of the given source file. If a matching alternate has been registered with this resolver via a call to RegisterImportPath or RegisterImportPathFrom, then the registered path is returned. Otherwise, the given import path is returned unchanged.

type MessageDescriptor 

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

MessageDescriptor describes a protocol buffer message.

func LoadMessageDescriptor 

func LoadMessageDescriptor(message string) (*MessageDescriptor, error)

LoadMessageDescriptor loads descriptor using the encoded descriptor proto returned by Message.Descriptor() for the given message type. If the given type is not recognized, then a nil descriptor is returned.

func LoadMessageDescriptorForMessage 

func LoadMessageDescriptorForMessage(message proto.Message) (*MessageDescriptor, error)

LoadMessageDescriptorForMessage loads descriptor using the encoded descriptor proto returned by message.Descriptor(). If the given type is not recognized, then a nil descriptor is returned.

func LoadMessageDescriptorForType 

func LoadMessageDescriptorForType(messageType reflect.Type) (*MessageDescriptor, error)

LoadMessageDescriptorForType loads descriptor using the encoded descriptor proto returned by message.Descriptor() for the given message type. If the given type is not recognized, then a nil descriptor is returned.

func (*MessageDescriptor) AsDescriptorProto 

func (md *MessageDescriptor) AsDescriptorProto() *dpb.DescriptorProto

AsDescriptorProto returns the underlying descriptor proto.

func (*MessageDescriptor) AsProto 

func (md *MessageDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*MessageDescriptor) FindFieldByJSONName 

func (md *MessageDescriptor) FindFieldByJSONName(jsonName string) *FieldDescriptor

FindFieldByJSONName finds the field with the given JSON field name. If no such field exists then nil is returned. Only regular fields are returned, not extensions.

func (*MessageDescriptor) FindFieldByName 

func (md *MessageDescriptor) FindFieldByName(fieldName string) *FieldDescriptor

FindFieldByName finds the field with the given name. If no such field exists then nil is returned. Only regular fields are returned, not extensions.

func (*MessageDescriptor) FindFieldByNumber 

func (md *MessageDescriptor) FindFieldByNumber(tagNumber int32) *FieldDescriptor

FindFieldByNumber finds the field with the given tag number. If no such field exists then nil is returned. Only regular fields are returned, not extensions.

func (*MessageDescriptor) GetExtensionRanges 

func (md *MessageDescriptor) GetExtensionRanges() []proto.ExtensionRange

GetExtensionRanges returns the ranges of extension field numbers for this message.

func (*MessageDescriptor) GetFields 

func (md *MessageDescriptor) GetFields() []*FieldDescriptor

GetFields returns all of the fields for this message.

func (*MessageDescriptor) GetFile 

func (md *MessageDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this message is defined.

func (*MessageDescriptor) GetFullyQualifiedName 

func (md *MessageDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the message. This includes the package name (if there is one) as well as the names of any enclosing messages.

func (*MessageDescriptor) GetMessageOptions 

func (md *MessageDescriptor) GetMessageOptions() *dpb.MessageOptions

GetMessageOptions returns the message's options.

func (*MessageDescriptor) GetName 

func (md *MessageDescriptor) GetName() string

GetName returns the simple (unqualified) name of the message.

func (*MessageDescriptor) GetNestedEnumTypes 

func (md *MessageDescriptor) GetNestedEnumTypes() []*EnumDescriptor

GetNestedEnumTypes returns all of the enums declared inside this message.

func (*MessageDescriptor) GetNestedExtensions 

func (md *MessageDescriptor) GetNestedExtensions() []*FieldDescriptor

GetNestedExtensions returns all of the extensions declared inside this message.

func (*MessageDescriptor) GetNestedMessageTypes 

func (md *MessageDescriptor) GetNestedMessageTypes() []*MessageDescriptor

GetNestedMessageTypes returns all of the message types declared inside this message.

func (*MessageDescriptor) GetOneOfs 

func (md *MessageDescriptor) GetOneOfs() []*OneOfDescriptor

GetOneOfs returns all of the one-of field sets declared inside this message.

func (*MessageDescriptor) GetOptions 

func (md *MessageDescriptor) GetOptions() proto.Message

GetOptions returns the message's options. Most usages will be more interested in GetMessageOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*MessageDescriptor) GetParent 

func (md *MessageDescriptor) GetParent() Descriptor

GetParent returns the message's enclosing descriptor. For top-level messages, this will be a file descriptor. Otherwise it will be the descriptor for the enclosing message.

func (*MessageDescriptor) GetSourceInfo 

func (md *MessageDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the message, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the message was defined and also contains comments associated with the message definition.

func (*MessageDescriptor) IsExtendable 

func (md *MessageDescriptor) IsExtendable() bool

IsExtendable returns true if this message has any extension ranges.

func (*MessageDescriptor) IsExtension 

func (md *MessageDescriptor) IsExtension(tagNumber int32) bool

IsExtension returns true if the given tag number is within any of this message's extension ranges.

func (*MessageDescriptor) IsMapEntry 

func (md *MessageDescriptor) IsMapEntry() bool

IsMapEntry returns true if this is a synthetic message type that represents an entry in a map field.

func (*MessageDescriptor) IsProto3 

func (md *MessageDescriptor) IsProto3() bool

IsProto3 returns true if the file in which this message is defined declares a syntax of "proto3".

func (*MessageDescriptor) String 

func (md *MessageDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type MethodDescriptor 

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

MethodDescriptor describes an RPC method declared in a proto file.

func (*MethodDescriptor) AsMethodDescriptorProto 

func (md *MethodDescriptor) AsMethodDescriptorProto() *dpb.MethodDescriptorProto

AsMethodDescriptorProto returns the underlying descriptor proto.

func (*MethodDescriptor) AsProto 

func (md *MethodDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsMethodDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*MethodDescriptor) GetFile 

func (md *MethodDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this method is defined.

func (*MethodDescriptor) GetFullyQualifiedName 

func (md *MethodDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the method. Unlike GetName, this includes fully qualified name of the enclosing service.

func (*MethodDescriptor) GetInputType 

func (md *MethodDescriptor) GetInputType() *MessageDescriptor

GetInputType returns the input type, or request type, of the RPC method.

func (*MethodDescriptor) GetMethodOptions 

func (md *MethodDescriptor) GetMethodOptions() *dpb.MethodOptions

GetMethodOptions returns the method's options.

func (*MethodDescriptor) GetName 

func (md *MethodDescriptor) GetName() string

GetName returns the name of the method.

func (*MethodDescriptor) GetOptions 

func (md *MethodDescriptor) GetOptions() proto.Message

GetOptions returns the method's options. Most usages will be more interested in GetMethodOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*MethodDescriptor) GetOutputType 

func (md *MethodDescriptor) GetOutputType() *MessageDescriptor

GetOutputType returns the output type, or response type, of the RPC method.

func (*MethodDescriptor) GetParent 

func (md *MethodDescriptor) GetParent() Descriptor

GetParent returns the descriptor for the service in which this method is defined. Most usages will prefer to use GetService, which has a concrete return type. This more generic method is present to satisfy the Descriptor interface.

func (*MethodDescriptor) GetService 

func (md *MethodDescriptor) GetService() *ServiceDescriptor

GetService returns the RPC service in which this method is declared.

func (*MethodDescriptor) GetSourceInfo 

func (md *MethodDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the method, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the method was defined and also contains comments associated with the method definition.

func (*MethodDescriptor) IsClientStreaming 

func (md *MethodDescriptor) IsClientStreaming() bool

IsClientStreaming returns true if this is a client-streaming method.

func (*MethodDescriptor) IsServerStreaming 

func (md *MethodDescriptor) IsServerStreaming() bool

IsServerStreaming returns true if this is a server-streaming method.

func (*MethodDescriptor) String 

func (md *MethodDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type OneOfDescriptor 

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

OneOfDescriptor describes a one-of field set declared in a protocol buffer message.

func (*OneOfDescriptor) AsOneofDescriptorProto 

func (od *OneOfDescriptor) AsOneofDescriptorProto() *dpb.OneofDescriptorProto

AsOneofDescriptorProto returns the underlying descriptor proto.

func (*OneOfDescriptor) AsProto 

func (od *OneOfDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsOneofDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*OneOfDescriptor) GetChoices 

func (od *OneOfDescriptor) GetChoices() []*FieldDescriptor

GetChoices returns the fields that are part of the one-of field set. At most one of these fields may be set for a given message.

func (*OneOfDescriptor) GetFile 

func (od *OneOfDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this one-fof is defined.

func (*OneOfDescriptor) GetFullyQualifiedName 

func (od *OneOfDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the one-of. Unlike GetName, this includes fully qualified name of the enclosing message.

func (*OneOfDescriptor) GetName 

func (od *OneOfDescriptor) GetName() string

GetName returns the name of the one-of.

func (*OneOfDescriptor) GetOneOfOptions 

func (od *OneOfDescriptor) GetOneOfOptions() *dpb.OneofOptions

GetOneOfOptions returns the one-of's options.

func (*OneOfDescriptor) GetOptions 

func (od *OneOfDescriptor) GetOptions() proto.Message

GetOptions returns the one-of's options. Most usages will be more interested in GetOneOfOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*OneOfDescriptor) GetOwner 

func (od *OneOfDescriptor) GetOwner() *MessageDescriptor

GetOwner returns the message to which this one-of field set belongs.

func (*OneOfDescriptor) GetParent 

func (od *OneOfDescriptor) GetParent() Descriptor

GetParent returns the descriptor for the message in which this one-of is defined. Most usages will prefer to use GetOwner, which has a concrete return type. This more generic method is present to satisfy the Descriptor interface.

func (*OneOfDescriptor) GetSourceInfo 

func (od *OneOfDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the one-of, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the one-of was defined and also contains comments associated with the one-of definition.

func (*OneOfDescriptor) IsSynthetic added in v1.7.0 

func (od *OneOfDescriptor) IsSynthetic() bool

func (*OneOfDescriptor) String 

func (od *OneOfDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

type ServiceDescriptor 

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

ServiceDescriptor describes an RPC service declared in a proto file.

func (*ServiceDescriptor) AsProto 

func (sd *ServiceDescriptor) AsProto() proto.Message

AsProto returns the underlying descriptor proto. Most usages will be more interested in AsServiceDescriptorProto, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*ServiceDescriptor) AsServiceDescriptorProto 

func (sd *ServiceDescriptor) AsServiceDescriptorProto() *dpb.ServiceDescriptorProto

AsServiceDescriptorProto returns the underlying descriptor proto.

func (*ServiceDescriptor) FindMethodByName 

func (sd *ServiceDescriptor) FindMethodByName(name string) *MethodDescriptor

FindMethodByName finds the method with the given name. If no such method exists then nil is returned.

func (*ServiceDescriptor) GetFile 

func (sd *ServiceDescriptor) GetFile() *FileDescriptor

GetFile returns the descriptor for the file in which this service is defined.

func (*ServiceDescriptor) GetFullyQualifiedName 

func (sd *ServiceDescriptor) GetFullyQualifiedName() string

GetFullyQualifiedName returns the fully qualified name of the service. This includes the package name (if there is one).

func (*ServiceDescriptor) GetMethods 

func (sd *ServiceDescriptor) GetMethods() []*MethodDescriptor

GetMethods returns all of the RPC methods for this service.

func (*ServiceDescriptor) GetName 

func (sd *ServiceDescriptor) GetName() string

GetName returns the simple (unqualified) name of the service.

func (*ServiceDescriptor) GetOptions 

func (sd *ServiceDescriptor) GetOptions() proto.Message

GetOptions returns the service's options. Most usages will be more interested in GetServiceOptions, which has a concrete return type. This generic version is present to satisfy the Descriptor interface.

func (*ServiceDescriptor) GetParent 

func (sd *ServiceDescriptor) GetParent() Descriptor

GetParent returns the descriptor for the file in which this service is defined. Most usages will prefer to use GetFile, which has a concrete return type. This more generic method is present to satisfy the Descriptor interface.

func (*ServiceDescriptor) GetServiceOptions 

func (sd *ServiceDescriptor) GetServiceOptions() *dpb.ServiceOptions

GetServiceOptions returns the service's options.

func (*ServiceDescriptor) GetSourceInfo 

func (sd *ServiceDescriptor) GetSourceInfo() *dpb.SourceCodeInfo_Location

GetSourceInfo returns source info for the service, if present in the descriptor. Not all descriptors will contain source info. If non-nil, the returned info contains information about the location in the file where the service was defined and also contains comments associated with the service definition.

func (*ServiceDescriptor) String 

func (sd *ServiceDescriptor) String() string

String returns the underlying descriptor proto, in compact text format.

Source Files

View all Source files

Directories

Path Synopsis
Package builder contains a means of building and modifying proto descriptors programmatically.
 Package builder contains a means of building and modifying proto descriptors programmatically.
Package protoparse provides functionality for parsing *.proto source files into descriptors that can be used with other protoreflect packages, like dynamic messages and dynamic GRPC clients.
 Package protoparse provides functionality for parsing *.proto source files into descriptors that can be used with other protoreflect packages, like dynamic messages and dynamic GRPC clients.
ast
Package ast defines types for modeling the AST (Abstract Syntax Tree) for the protocol buffers source language.
 Package ast defines types for modeling the AST (Abstract Syntax Tree) for the protocol buffers source language.
Package protoprint provides a mechanism to generate protobuf source code from descriptors.
 Package protoprint provides a mechanism to generate protobuf source code from descriptors.

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.