msgregistry

Documentation

Overview

Package msgregistry contains a registry of known message and enum types. The MessageRegistry is used for interacting with Any messages where the actual embedded value may be a dynamic message. There is also functionality for resolving type URLs into descriptors, which supports dynamically loading type descriptions (represented using the well-known types: Api, Method, Type, Field, Enum, and EnumValue) and converting them to descriptors. This allows for using these dynamically loaded schemas using dynamic messages. The registry also exposes related functionality for inter-op between descriptors and the proto well-known types that model APIs and types.

Index

• type ErrUnexpectedType
  • func (e *ErrUnexpectedType) Error() string
• type MessageRegistry
  • func NewMessageRegistryWithDefaults() *MessageRegistry
  • func (r *MessageRegistry) AddBaseUrlForElement(baseUrl, packageOrTypeName string)
  • func (r *MessageRegistry) AddEnum(url string, ed *desc.EnumDescriptor) error
  • func (r *MessageRegistry) AddFile(baseUrl string, fd *desc.FileDescriptor)
  • func (r *MessageRegistry) AddMessage(url string, md *desc.MessageDescriptor) error
  • func (r *MessageRegistry) ComputeURL(d desc.Descriptor) string
  • func (r *MessageRegistry) ComputeUrl(d desc.Descriptor) string
  • func (r *MessageRegistry) EnumAsPType(ed *desc.EnumDescriptor) *typepb.Enum
  • func (r *MessageRegistry) FindEnumTypeByUrl(url string) (*desc.EnumDescriptor, error)
  • func (r *MessageRegistry) FindMessageTypeByUrl(url string) (*desc.MessageDescriptor, error)
  • func (r *MessageRegistry) MarshalAny(m proto.Message) (*anypb.Any, error)
  • func (r *MessageRegistry) MessageAsPType(md *desc.MessageDescriptor) *typepb.Type
  • func (r *MessageRegistry) Resolve(typeUrl string) (proto.Message, error)
  • func (r *MessageRegistry) ResolveApiIntoServiceDescriptor(a *apipb.Api) (*desc.ServiceDescriptor, error)
  • func (r *MessageRegistry) ServiceAsApi(sd *desc.ServiceDescriptor) *apipb.Api
  • func (r *MessageRegistry) UnmarshalAny(a *anypb.Any) (proto.Message, error)
  • func (r *MessageRegistry) WithDefaultBaseUrl(baseUrl string) *MessageRegistry
  • func (r *MessageRegistry) WithFetcher(fetcher TypeFetcher) *MessageRegistry
  • func (r *MessageRegistry) WithMessageFactory(mf *dynamic.MessageFactory) *MessageRegistry
• type TypeFetcher
  • func CachingTypeFetcher(fetcher TypeFetcher) TypeFetcher
  • func HttpTypeFetcher(transport http.RoundTripper, szLimit, parLimit int) TypeFetcher

Types

type ErrUnexpectedType

type ErrUnexpectedType struct {
	URL          string
	ShouldBeEnum bool
}

ErrUnexpectedType is returned if the URL that was requested resolved to an enum instead of a message, or vice versa.

func (*ErrUnexpectedType) Error

func (e *ErrUnexpectedType) Error() string

type MessageRegistry

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

MessageRegistry is a registry that maps URLs to message types. It allows for marshalling and unmarshalling Any types to and from dynamic messages.

func NewMessageRegistryWithDefaults

func NewMessageRegistryWithDefaults() *MessageRegistry

NewMessageRegistryWithDefaults is a registry that includes all "default" message types, which are those that are statically linked into the current program (e.g. registered by protoc-generated code via proto.RegisterType). Note that it cannot resolve "default" enum types since those don't actually get registered by protoc-generated code the same way. Any types explicitly added to the registry will override any default message types with the same URL.

func (*MessageRegistry) AddBaseUrlForElement

func (r *MessageRegistry) AddBaseUrlForElement(baseUrl, packageOrTypeName string)

AddBaseUrlForElement adds a base URL for the given package or fully-qualified type name. This is used to construct type URLs for message types. If a given type has an associated base URL, it is used. Otherwise, the base URL for the type's package is used. If that is also absent, the registry's default base URL is used.

func (*MessageRegistry) AddEnum

func (r *MessageRegistry) AddEnum(url string, ed *desc.EnumDescriptor) error

AddEnum adds the given URL and associated enum descriptor to the registry.

func (*MessageRegistry) AddFile

func (r *MessageRegistry) AddFile(baseUrl string, fd *desc.FileDescriptor)

AddFile adds to the registry all message and enum types in the given file. The URL for each type is derived using the given base URL as "baseURL/fully.qualified.type.name".

func (*MessageRegistry) AddMessage

func (r *MessageRegistry) AddMessage(url string, md *desc.MessageDescriptor) error

AddMessage adds the given URL and associated message descriptor to the registry.

func (*MessageRegistry) ComputeURL

func (r *MessageRegistry) ComputeURL(d desc.Descriptor) string

ComputeURL computes a type URL string for the element described by the given descriptor. The given descriptor must be an enum or message descriptor. This will use any registered URLs and base URLs to determine the appropriate URL for the given type.

func (*MessageRegistry) ComputeUrl

func (r *MessageRegistry) ComputeUrl(d desc.Descriptor) string

ComputeUrl computes a type URL for element described by the given descriptor. The given descriptor must be an enum or message descriptor. This will use any registered URLs and base URLs to determine the appropriate URL for the given type.

Deprecated: This method is deprecated due to its use of non-idiomatic naming. Use ComputeURL instead.

func (*MessageRegistry) EnumAsPType

func (r *MessageRegistry) EnumAsPType(ed *desc.EnumDescriptor) *typepb.Enum

EnumAsPType converts the given enum descriptor into a ptype.Enum.

func (*MessageRegistry) FindEnumTypeByUrl

func (r *MessageRegistry) FindEnumTypeByUrl(url string) (*desc.EnumDescriptor, error)

FindEnumTypeByUrl finds an enum descriptor for the type at the given URL. It may return nil if the registry is empty and cannot resolve unknown URLs. If an error occurs while resolving the URL, it is returned. If the resolved type is a message, ErrUnexpectedType is returned.

func (*MessageRegistry) FindMessageTypeByUrl

func (r *MessageRegistry) FindMessageTypeByUrl(url string) (*desc.MessageDescriptor, error)

FindMessageTypeByUrl finds a message descriptor for the type at the given URL. It may return nil if the registry is empty and cannot resolve unknown URLs. If an error occurs while resolving the URL, it is returned. If the resolved type is a enum, ErrUnexpectedType is returned.

func (*MessageRegistry) MarshalAny

func (r *MessageRegistry) MarshalAny(m proto.Message) (*anypb.Any, error)

MarshalAny wraps the given message in an Any value.

func (*MessageRegistry) MessageAsPType

func (r *MessageRegistry) MessageAsPType(md *desc.MessageDescriptor) *typepb.Type

MessageAsPType converts the given message descriptor into a ptype.Type. Registered base URLs are used to compute type URLs for any fields that have message or enum types.

func (*MessageRegistry) Resolve

func (r *MessageRegistry) Resolve(typeUrl string) (proto.Message, error)

Resolve resolves the given type URL into an instance of a message. This implements the jsonpb.AnyResolver interface, for use with marshaling and unmarshaling Any messages to/from JSON.

func (*MessageRegistry) ResolveApiIntoServiceDescriptor

func (r *MessageRegistry) ResolveApiIntoServiceDescriptor(a *apipb.Api) (*desc.ServiceDescriptor, error)

ResolveApiIntoServiceDescriptor constructs a service descriptor that describes the given API. If any of the service's request or response type URLs cannot be resolved by this registry, a nil descriptor is returned.

func (*MessageRegistry) ServiceAsApi

func (r *MessageRegistry) ServiceAsApi(sd *desc.ServiceDescriptor) *apipb.Api

ServiceAsApi converts the given service descriptor into a ptype API description.

func (*MessageRegistry) UnmarshalAny

func (r *MessageRegistry) UnmarshalAny(a *anypb.Any) (proto.Message, error)

UnmarshalAny will unmarshal the value embedded in the given Any value. This will use this registry to resolve the given value's type URL. Use this instead of ptypes.UnmarshalAny for cases where the type might not be statically linked into the current program.

func (*MessageRegistry) WithDefaultBaseUrl

func (r *MessageRegistry) WithDefaultBaseUrl(baseUrl string) *MessageRegistry

WithDefaultBaseUrl sets the default base URL used when constructing type URLs for marshalling messages as Any types and converting descriptors to well-known type descriptions (ptypes). If unspecified, the default base URL will be "type.googleapis.com". This method is not thread-safe and is intended to be used for one-time initialization of the registry, before it is published for use by other threads.

func (*MessageRegistry) WithFetcher

func (r *MessageRegistry) WithFetcher(fetcher TypeFetcher) *MessageRegistry

WithFetcher sets the TypeFetcher that this registry uses to resolve unknown URLs. If no fetcher is configured for the registry then unknown URLs cannot be resolved. Known URLs are those for explicitly registered types and, if the registry includes "default" types, those for statically linked message types. This method is not thread-safe and is intended to be used for one-time initialization of the registry, before it is published for use by other threads.

func (*MessageRegistry) WithMessageFactory

func (r *MessageRegistry) WithMessageFactory(mf *dynamic.MessageFactory) *MessageRegistry

WithMessageFactory sets the MessageFactory used to instantiate any messages. This method is not thread-safe and is intended to be used for one-time initialization of the registry, before it is published for use by other threads.

type TypeFetcher

type TypeFetcher func(url string, enum bool) (proto.Message, error)

TypeFetcher is a simple operation that retrieves a type definition for a given type URL. The returned proto message will be either a *ptype.Enum or a *ptype.Type, depending on whether the enum flag is true or not.

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.