remotereg

package
v2.0.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2024 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DescriptorConverter 

type DescriptorConverter Registry

DescriptorConverter is a type that can be used to convert between descriptors and the other representations of types and services: google.protobuf.Type, google.protobuf.Enum, and google.protobuf.Api.

It uses a Registry to convert the alternate representations, which may involve fetching remote types by type URL in order to create a complete representation of the transitive closure of the type or service.

See Registry.AsDescriptorConverter.

func (*DescriptorConverter) DescriptorAsApi 

func (dc *DescriptorConverter) DescriptorAsApi(sd protoreflect.ServiceDescriptor) *apipb.Api

DescriptorAsApi produces an Api message that represents the given service descriptor.

func (*DescriptorConverter) DescriptorAsEnum 

func (dc *DescriptorConverter) DescriptorAsEnum(ed protoreflect.EnumDescriptor) *typepb.Enum

DescriptorAsEnum produces an Enum message that represents the given enum descriptor.

func (*DescriptorConverter) DescriptorAsType 

func (dc *DescriptorConverter) DescriptorAsType(md protoreflect.MessageDescriptor) *typepb.Type

DescriptorAsType produces a Type message that represents the given message descriptor.

func (*DescriptorConverter) ToEnumDescriptor 

func (dc *DescriptorConverter) ToEnumDescriptor(ctx context.Context, enum *typepb.Enum) (protoreflect.EnumDescriptor, error)

ToEnumDescriptor converts the given Enum message into an enum descriptor.

func (*DescriptorConverter) ToMessageDescriptor 

func (dc *DescriptorConverter) ToMessageDescriptor(ctx context.Context, msg *typepb.Type) (protoreflect.MessageDescriptor, error)

ToMessageDescriptor converts the given Type message into a message descriptor. Since the message's fields may reference other types that are not yet known, other types may be fetched, which could warrant interruption by providing a cancellable context.

func (*DescriptorConverter) ToServiceDescriptor 

func (dc *DescriptorConverter) ToServiceDescriptor(ctx context.Context, api *apipb.Api) (protoreflect.ServiceDescriptor, error)

ToServiceDescriptor converts the given Api message into a service descriptor. Since the service's referenced types may not yet be known, they may be fetched, which could warrant interruption by providing a cancellable context.

type Registry 

type Registry struct {
	// The default base URL to apply when registering types without a URL and
	// when looking up types by name. The message name is prefixed with the
	// base URL to form a full type URL.
	//
	// If not specified or empty, a default of "type.googleapis.com" will be
	// used.
	//
	// If present, the PackageBaseURLMapper will be consulted first before
	// applying this default.
	DefaultBaseURL string
	// A function that provides the base URL for a given package. When types
	// are registered without a URL or looked up by name, this base URL is
	// used to construct a full type URL.
	//
	// If not specified or nil, or if it returns the empty string, the
	// DefaultBaseURL will be applied.
	PackageBaseURLMapper func(packageName protoreflect.FullName) string
	// A value that can retrieve type definitions at runtime. If non-nil,
	// this will be used to resolve types for URLs that have not been
	// explicitly registered.
	TypeFetcher TypeFetcher
	// The final fallback for resolving types. If a type URL has not been
	// explicitly registered and cannot be resolved by TypeFetcher (or
	// TypeFetcher is unset/nil), then Fallback will be used to resolve
	// the type by name.
	//
	// Fallback is also used to resolve custom options found in type
	// definitions returned from TypeFetcher.
	//
	// If not specified or nil, protoregistry.GlobalFiles will be used as
	// the fallback. To prevent any fallback from being used, set this to
	// an empty resolver, such as a new, empty Registry or
	// protoregistry.Files.
	Fallback protoresolve.DescriptorResolver
	// contains filtered or unexported fields
}

Registry is a registry of types that are registered by remote URL. A Registry can be configured with a TypeFetcher, which can be used to dynamically retrieve message definitions.

It differs from a Registry in that it only exposes a subset of the Resolver interface, focused on messages and enums, which are types which may be resolved by downloading schemas from a remote source.

This registry is intended to help resolve message type URLs in google.protobuf.Any messages.

func (*Registry) AsDescriptorConverter 

func (r *Registry) AsDescriptorConverter() *DescriptorConverter

AsDescriptorConverter returns a view of this registry as a DescriptorConverter. The returned value may be used to convert type and service definitions from the descriptor representations to the google.protobuf.Type, google.protobuf.Enum, and google.protobuf.Service representations, and vice versa.

func (*Registry) AsTypeResolver 

func (r *Registry) AsTypeResolver() *RemoteTypeResolver

AsTypeResolver returns a view of this registry that returns types instead of descriptors. The returned resolver implements TypeResolver

func (*Registry) FindEnumByName 

func (r *Registry) FindEnumByName(name protoreflect.FullName) (protoreflect.EnumDescriptor, error)

FindEnumByName has the same signature as the method of the same name in the Resolver interface.

But since finding a type definition may involve retrieving data via a TypeFetcher, it is recommended to use FindEnumByNameContext instead. Calling this version will implicitly use context.Background().

func (*Registry) FindEnumByNameContext 

func (r *Registry) FindEnumByNameContext(ctx context.Context, name protoreflect.FullName) (protoreflect.EnumDescriptor, error)

FindEnumByNameContext finds a type definition for an enum with the given name. This function computes a URL for the given type using the logic described in URLForType and then delegates to FindEnumByURLContext.

func (*Registry) FindEnumByURL 

func (r *Registry) FindEnumByURL(url string) (protoreflect.EnumDescriptor, error)

FindEnumByURL has a signature that is consistent with that of FindMessageByURL and is present for symmetry.

But since finding a type definition may involve retrieving data via a TypeFetcher, it is recommended to use FindEnumByURLContext instead. Calling this version will implicitly use context.Background().

func (*Registry) FindEnumByURLContext 

func (r *Registry) FindEnumByURLContext(ctx context.Context, url string) (protoreflect.EnumDescriptor, error)

FindEnumByURLContext finds a type definition for an enum with the given type URL. This method first examines explicitly registered enum types (via RegisterEnum and RegisterEnumWithURL) and types already downloaded via the TypeFetcher. It will then use the TypeFetcher, if present, to try to download a type definition. And if fails to produce a result, the registry's Fallback is queried.

func (*Registry) FindMessageByName 

func (r *Registry) FindMessageByName(name protoreflect.FullName) (protoreflect.MessageDescriptor, error)

FindMessageByName has the same signature as the method of the same name in the Resolver interface.

But since finding a type definition may involve retrieving data via a TypeFetcher, it is recommended to use FindMessageByNameContext instead. Calling this version will implicitly use context.Background().

func (*Registry) FindMessageByNameContext 

func (r *Registry) FindMessageByNameContext(ctx context.Context, name protoreflect.FullName) (protoreflect.MessageDescriptor, error)

FindMessageByNameContext finds a type definition for a message with the given name. This function computes a URL for the given type using the logic described in URLForType and then delegates to FindMessageByURLContext.

func (*Registry) FindMessageByURL 

func (r *Registry) FindMessageByURL(url string) (protoreflect.MessageDescriptor, error)

FindMessageByURL has the same signature as the method of the same name in the protoresolve.MessageResolver interface.

But since finding a type definition may involve retrieving data via a TypeFetcher, it is recommended to use FindMessageByURLContext instead. Calling this version will implicitly use context.Background().

func (*Registry) FindMessageByURLContext 

func (r *Registry) FindMessageByURLContext(ctx context.Context, url string) (protoreflect.MessageDescriptor, error)

FindMessageByURLContext finds a type definition for a message with the given type URL. This method first examines explicitly registered message types (via RegisterMessage and RegisterMessageWithURL) and types already downloaded via the TypeFetcher. It will then use the TypeFetcher, if present, to try to download a type definition. And if fails to produce a result, the registry's Fallback is queried.

func (*Registry) RegisterEnum 

func (r *Registry) RegisterEnum(ed protoreflect.EnumDescriptor) error

RegisterEnum registers the given enum type. The URL that corresponds to the given type will be computed via URLForType. Also see RegisterEnumWithURL.

func (*Registry) RegisterEnumWithURL 

func (r *Registry) RegisterEnumWithURL(ed protoreflect.EnumDescriptor, url string) error

RegisterEnumWithURL registers the given enum type with the given URL.

func (*Registry) RegisterMessage 

func (r *Registry) RegisterMessage(md protoreflect.MessageDescriptor) error

RegisterMessage registers the given message type. The URL that corresponds to the given type will be computed via URLForType. Also see RegisterMessageWithURL.

func (*Registry) RegisterMessageWithURL 

func (r *Registry) RegisterMessageWithURL(md protoreflect.MessageDescriptor, url string) error

RegisterMessageWithURL registers the given message type with the given URL.

func (*Registry) RegisterPackageBaseURL 

func (r *Registry) RegisterPackageBaseURL(pkgName protoreflect.FullName, baseURL string, includeSubPackages bool) (string, bool)

RegisterPackageBaseURL registers the given base URL to be used with elements in the given package. If includeSubPackages is true, this base URL will also be applied to all sub-packages (unless overridden via separate call to RegisterPackageBaseURL for a particular sub-package).

func (*Registry) RegisterTypesInFile 

func (r *Registry) RegisterTypesInFile(fd protoreflect.FileDescriptor) error

RegisterTypesInFile registers all message and enum types present in the given file. The base URL used for all types will be computed based on explicit base URL registrations, then the registry's PackageBaseURLMapper (if present), and finally the registry's DefaultBaseURL.

func (*Registry) RegisterTypesInFileWithBaseURL 

func (r *Registry) RegisterTypesInFileWithBaseURL(fd protoreflect.FileDescriptor, baseURL string) error

RegisterTypesInFileWithBaseURL registers all message and enum types present in the given file. The given base URL is used to construct the URLs for all types.

func (*Registry) URLForType 

func (r *Registry) URLForType(desc protoreflect.Descriptor) string

URLForType computes the type URL for the given descriptor. If the given type has been explicitly registered or has been fetched by this registry (via configured TypeFetcher), this will return the URL that was associated with the type. Otherwise, this will compute a URL for the type. Computing the URL will first look at explicitly registered package base URLs, then the registry's PackageBaseURLMapper (if configured), and finally the registry's DefaultBaseURL (if configured).

type RemoteTypeResolver 

type RemoteTypeResolver Registry

RemoteTypeResolver is an implementation of TypeResolver that uses a Registry to resolve symbols.

All message and enum types returned will be dynamic types, created using the dynamicpb package, built on the descriptors resolved by the backing Registry.

func (*RemoteTypeResolver) FindEnumByName 

func (r *RemoteTypeResolver) FindEnumByName(name protoreflect.FullName) (protoreflect.EnumType, error)

FindEnumByName implements the method of the same name on the TypeResolver interface. Since finding an enum may incur fetching the definition via a TypeFetcher, it is recommended, where possible, to instead use FindEnumByNameContext. Calling this version will implicitly use context.Background().

func (*RemoteTypeResolver) FindEnumByNameContext 

func (r *RemoteTypeResolver) FindEnumByNameContext(ctx context.Context, name protoreflect.FullName) (protoreflect.EnumType, error)

FindEnumByNameContext finds an enum by name, using the given context if necessary to fetch the message type via a TypeFetcher. This uses the underlying Registry's method of the same name.

func (*RemoteTypeResolver) FindEnumByURL 

func (r *RemoteTypeResolver) FindEnumByURL(url string) (protoreflect.EnumType, error)

FindEnumByURL has a signature that is consistent with that of FindMessageByURL and is present for symmetry. Since finding an enum may incur fetching the definition via a TypeFetcher, it is recommended, where possible, to instead use FindEnumByURLContext. Calling this version will implicitly use context.Background().

func (*RemoteTypeResolver) FindEnumByURLContext 

func (r *RemoteTypeResolver) FindEnumByURLContext(ctx context.Context, url string) (protoreflect.EnumType, error)

FindEnumByURLContext finds an enum by type URL, using the given context if necessary to fetch the message type via a TypeFetcher. This uses the underlying Registry's method of the same name.

func (*RemoteTypeResolver) FindExtensionByName 

func (r *RemoteTypeResolver) FindExtensionByName(field protoreflect.FullName) (protoreflect.ExtensionType, error)

FindExtensionByName implements the SerializationResolver interface.

This method relies on the underlying Registry's fallback resolver. If the registry's fallback resolver is unconfigured or nil, then protoregistry.GlobalTypes will be used to find the extension. Otherwise, if the fallback has a method named AsTypeResolver that returns a TypeResolver, it will be invoked and the resulting type resolver will be used to find the extension type. Failing all of the above, the fallback's FindDescriptorByName method will be used to find the extension. In this case the returned extension type may be a dynamic extension type, created using the dynamicpb package.

func (*RemoteTypeResolver) FindExtensionByNumber 

func (r *RemoteTypeResolver) FindExtensionByNumber(message protoreflect.FullName, field protoreflect.FieldNumber) (protoreflect.ExtensionType, error)

FindExtensionByNumber implements the SerializationResolver interface.

This method relies on the underlying Registry's fallback resolver. If the registry's fallback resolver is unconfigured or nil, then protoregistry.GlobalTypes will be used to find the extension. Otherwise, if the fallback has a method named AsTypeResolver that returns a TypeResolver, it will be invoked and the resulting type resolver will be used to find the extension type. Failing all of the above, the extension can only be found if the fallback resolver implements DescriptorPool or ExtensionResolver and will otherwise return ErrNotFound.

func (*RemoteTypeResolver) FindMessageByName 

func (r *RemoteTypeResolver) FindMessageByName(name protoreflect.FullName) (protoreflect.MessageType, error)

FindMessageByName implements the SerializationResolver interface. Since finding a message may incur fetching the definition via a TypeFetcher, it is recommended, where possible, to instead use FindMessageByNameContext. Calling this version will implicitly use context.Background().

func (*RemoteTypeResolver) FindMessageByNameContext 

func (r *RemoteTypeResolver) FindMessageByNameContext(ctx context.Context, name protoreflect.FullName) (protoreflect.MessageType, error)

FindMessageByNameContext finds a message by name, using the given context if necessary to fetch the message type via a TypeFetcher. This uses the underlying Registry's method of the same name.

func (*RemoteTypeResolver) FindMessageByURL 

func (r *RemoteTypeResolver) FindMessageByURL(url string) (protoreflect.MessageType, error)

FindMessageByURL implements the SerializationResolver interface. Since finding a message may incur fetching the definition via a TypeFetcher, it is recommended, where possible, to instead use FindMessageByURLContext. Calling this version will implicitly use context.Background().

func (*RemoteTypeResolver) FindMessageByURLContext 

func (r *RemoteTypeResolver) FindMessageByURLContext(ctx context.Context, url string) (protoreflect.MessageType, error)

FindMessageByURLContext finds a message by type URL, using the given context if necessary to fetch the message type via a TypeFetcher. This uses the underlying Registry's method of the same name.

type TypeFetcher 

type TypeFetcher interface {
	// FetchMessageType fetches the definition of a message type that is identified
	// by the given URL.
	FetchMessageType(ctx context.Context, url string) (*typepb.Type, error)
	// FetchEnumType fetches the definition of an enum type that is identified by
	// the given URL.
	FetchEnumType(ctx context.Context, url string) (*typepb.Enum, error)
}

TypeFetcher is a value that knows how to fetch type definitions for a URL. The type definitions are represented by google.protobuf.Type and google.protobuf.Enum messages (which were originally part of the specification for google.protobuf.Any and how such types could be resolved at runtime).

func CachingTypeFetcher 

func CachingTypeFetcher(fetcher TypeFetcher) TypeFetcher

CachingTypeFetcher adds a caching layer to the given type fetcher. Queries for types that have already been fetched will not result in another call to the underlying fetcher and instead are retrieved from the cache.

func HttpTypeFetcher 

func HttpTypeFetcher(transport http.RoundTripper, szLimit, parLimit int) TypeFetcher

HttpTypeFetcher returns a TypeFetcher that uses the given HTTP transport to query and download type definitions. The given szLimit is the maximum response size accepted. If used from multiple goroutines (like when a type's dependency graph is resolved in parallel), this resolver limits the number of parallel queries/downloads to the given parLimit.

type TypeFetcherFunc 

type TypeFetcherFunc func(ctx context.Context, url string, enum bool) (proto.Message, error)

TypeFetcherFunc is a TypeFetcher implementation backed by a single function. The function accepts a parameter to have it switch between fetching a message type vs. finding an enum type.

func (TypeFetcherFunc) FetchEnumType 

func (t TypeFetcherFunc) FetchEnumType(ctx context.Context, url string) (*typepb.Enum, error)

FetchEnumType implements the TypeFetcher interface.

func (TypeFetcherFunc) FetchMessageType 

func (t TypeFetcherFunc) FetchMessageType(ctx context.Context, url string) (*typepb.Type, error)

FetchMessageType implements the TypeFetcher interface.

Source Files

View all Source files

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.