Documentation
¶
Overview ¶
Package registry provides thread-safe runtime registration and lookup of protobuf file descriptors and type descriptors (messages, enums, and extensions) by fully qualified name or file path.
The package exposes two concrete registry types: FileRegistry for file descriptors keyed by path, and TypeRegistry for message, enum, and extension descriptors keyed by full name. Both registries use read-write mutexes to support safe concurrent access from multiple goroutines.
Consumers should depend on the narrow resolver interfaces (FileResolver, MessageResolver, EnumResolver, ExtensionResolver) rather than the concrete registry types, following the Interface Segregation Principle.
Index ¶
- Variables
- func RegisterFileDescriptor(files *FileRegistry, types *TypeRegistry, fd descriptor.FileDescriptorAccessor) error
- type EnumResolver
- type ExtensionResolver
- type FileRegistry
- type FileResolver
- type MessageResolver
- type RegistryError
- type TypeRegistry
- func (r *TypeRegistry) FindEnumByName(fn descriptor.FullName) (descriptor.EnumDescriptorAccessor, error)
- func (r *TypeRegistry) FindExtensionByName(fn descriptor.FullName) (descriptor.FieldDescriptorAccessor, error)
- func (r *TypeRegistry) FindExtensionByNumber(message descriptor.FullName, number uint32) (descriptor.FieldDescriptorAccessor, error)
- func (r *TypeRegistry) FindMessageByName(fn descriptor.FullName) (descriptor.MessageDescriptorAccessor, error)
- func (r *TypeRegistry) RangeEnums(fn func(descriptor.EnumDescriptorAccessor) bool)
- func (r *TypeRegistry) RangeExtensions(fn func(descriptor.FieldDescriptorAccessor) bool)
- func (r *TypeRegistry) RangeExtensionsByMessage(message descriptor.FullName, fn func(descriptor.FieldDescriptorAccessor) bool)
- func (r *TypeRegistry) RangeMessages(fn func(descriptor.MessageDescriptorAccessor) bool)
- func (r *TypeRegistry) RegisterEnum(ed descriptor.EnumDescriptorAccessor) error
- func (r *TypeRegistry) RegisterExtension(fd descriptor.FieldDescriptorAccessor) error
- func (r *TypeRegistry) RegisterMessage(md descriptor.MessageDescriptorAccessor) error
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyRegistered = errors.New("registry: already registered")
ErrAlreadyRegistered is returned when a registration attempt encounters a duplicate entry already present in the registry. Callers should use errors.Is to detect this sentinel through wrapped errors.
var ErrNotFound = errors.New("registry: not found")
ErrNotFound is returned when a lookup finds no matching entry in the registry. Callers should use errors.Is to detect this sentinel through wrapped errors.
var GlobalFiles = NewFileRegistry()
GlobalFiles is the default global file registry used by generated code to register file descriptors at program startup. Application code and tests that need isolation should create their own registries via NewFileRegistry.
var GlobalTypes = NewTypeRegistry()
GlobalTypes is the default global type registry used by generated code to register message, enum, and extension descriptors at program startup. Application code and tests that need isolation should create their own registries via NewTypeRegistry.
Functions ¶
func RegisterFileDescriptor ¶
func RegisterFileDescriptor(files *FileRegistry, types *TypeRegistry, fd descriptor.FileDescriptorAccessor) error
RegisterFileDescriptor registers a file descriptor into the file registry and recursively walks the file's messages, enums, and extensions, registering each into the type registry. On any duplicate registration error it returns immediately with the wrapped error; partial registration is acceptable because duplicate detection means the caller is re-registering an already-known file.
Types ¶
type EnumResolver ¶
type EnumResolver interface {
FindEnumByName(descriptor.FullName) (descriptor.EnumDescriptorAccessor, error)
}
EnumResolver is the interface for looking up enum descriptors by fully qualified name. Consumers should accept this interface rather than the concrete TypeRegistry to follow the Interface Segregation Principle.
type ExtensionResolver ¶
type ExtensionResolver interface {
FindExtensionByName(descriptor.FullName) (descriptor.FieldDescriptorAccessor, error)
FindExtensionByNumber(message descriptor.FullName, number uint32) (descriptor.FieldDescriptorAccessor, error)
}
ExtensionResolver is the interface for looking up extension field descriptors by fully qualified name or by containing message and field number. Consumers should accept this interface rather than the concrete TypeRegistry to follow the Interface Segregation Principle.
type FileRegistry ¶
type FileRegistry struct {
// contains filtered or unexported fields
}
FileRegistry is a thread-safe registry of file descriptors keyed by file path. It supports concurrent registration, lookup, and iteration using a read-write mutex.
func NewFileRegistry ¶
func NewFileRegistry() *FileRegistry
NewFileRegistry returns an initialized FileRegistry ready for use.
func (*FileRegistry) FindFileByPath ¶
func (r *FileRegistry) FindFileByPath(path string) (descriptor.FileDescriptorAccessor, error)
FindFileByPath looks up a file descriptor by its path. It returns an error wrapping ErrNotFound if no file with the given path is registered.
func (*FileRegistry) RangeFiles ¶
func (r *FileRegistry) RangeFiles(fn func(descriptor.FileDescriptorAccessor) bool)
RangeFiles iterates all registered file descriptors under a read lock, calling fn for each. Iteration stops early if fn returns false.
func (*FileRegistry) RegisterFile ¶
func (r *FileRegistry) RegisterFile(fd descriptor.FileDescriptorAccessor) error
RegisterFile registers a file descriptor by its path. It returns an error wrapping ErrAlreadyRegistered if a file with the same path is already registered.
type FileResolver ¶
type FileResolver interface {
FindFileByPath(path string) (descriptor.FileDescriptorAccessor, error)
}
FileResolver is the interface for looking up file descriptors by path. Consumers should accept this interface rather than the concrete FileRegistry to follow the Interface Segregation Principle.
type MessageResolver ¶
type MessageResolver interface {
FindMessageByName(descriptor.FullName) (descriptor.MessageDescriptorAccessor, error)
}
MessageResolver is the interface for looking up message descriptors by fully qualified name. Consumers should accept this interface rather than the concrete TypeRegistry to follow the Interface Segregation Principle.
type RegistryError ¶
type RegistryError struct {
// Op is the operation that failed (e.g. "RegisterFile", "FindMessageByName").
Op string
// Key is the lookup key or registration name that was involved.
Key string
// Cause is the underlying sentinel error (ErrNotFound or ErrAlreadyRegistered).
Cause error
}
RegistryError is a typed error returned by registry operations. It includes the operation name and key context and wraps the underlying sentinel error.
func (*RegistryError) Error ¶
func (e *RegistryError) Error() string
Error returns a human-readable message with operation and key context.
func (*RegistryError) Unwrap ¶
func (e *RegistryError) Unwrap() error
Unwrap returns the underlying sentinel so that errors.Is and errors.As work.
type TypeRegistry ¶
type TypeRegistry struct {
// contains filtered or unexported fields
}
TypeRegistry is a thread-safe registry for protobuf message, enum, and extension descriptors. It supports registration and lookup by fully qualified name, as well as extension lookup by containing message and field number. All methods are safe for concurrent use.
func NewTypeRegistry ¶
func NewTypeRegistry() *TypeRegistry
NewTypeRegistry returns a new TypeRegistry with all internal maps initialized and ready for use.
func (*TypeRegistry) FindEnumByName ¶
func (r *TypeRegistry) FindEnumByName(fn descriptor.FullName) (descriptor.EnumDescriptorAccessor, error)
FindEnumByName looks up a registered enum descriptor by its fully qualified name. It returns an error wrapping ErrNotFound if no enum with the given name is registered.
func (*TypeRegistry) FindExtensionByName ¶
func (r *TypeRegistry) FindExtensionByName(fn descriptor.FullName) (descriptor.FieldDescriptorAccessor, error)
FindExtensionByName looks up a registered extension field descriptor by its fully qualified name. It returns an error wrapping ErrNotFound if no extension with the given name is registered.
func (*TypeRegistry) FindExtensionByNumber ¶
func (r *TypeRegistry) FindExtensionByNumber(message descriptor.FullName, number uint32) (descriptor.FieldDescriptorAccessor, error)
FindExtensionByNumber looks up a registered extension field descriptor by its containing message full name and field number. It returns an error wrapping ErrNotFound if no matching extension is registered.
func (*TypeRegistry) FindMessageByName ¶
func (r *TypeRegistry) FindMessageByName(fn descriptor.FullName) (descriptor.MessageDescriptorAccessor, error)
FindMessageByName looks up a registered message descriptor by its fully qualified name. It returns an error wrapping ErrNotFound if no message with the given name is registered.
func (*TypeRegistry) RangeEnums ¶
func (r *TypeRegistry) RangeEnums(fn func(descriptor.EnumDescriptorAccessor) bool)
RangeEnums iterates over all registered enum descriptors, calling fn for each one. Iteration stops early if fn returns false.
func (*TypeRegistry) RangeExtensions ¶
func (r *TypeRegistry) RangeExtensions(fn func(descriptor.FieldDescriptorAccessor) bool)
RangeExtensions iterates over all registered extension field descriptors, calling fn for each one. Iteration stops early if fn returns false.
func (*TypeRegistry) RangeExtensionsByMessage ¶
func (r *TypeRegistry) RangeExtensionsByMessage(message descriptor.FullName, fn func(descriptor.FieldDescriptorAccessor) bool)
RangeExtensionsByMessage iterates over all registered extension field descriptors whose extendee message matches the given full name. It calls fn for each matching extension. Iteration stops early if fn returns false.
func (*TypeRegistry) RangeMessages ¶
func (r *TypeRegistry) RangeMessages(fn func(descriptor.MessageDescriptorAccessor) bool)
RangeMessages iterates over all registered message descriptors, calling fn for each one. Iteration stops early if fn returns false.
func (*TypeRegistry) RegisterEnum ¶
func (r *TypeRegistry) RegisterEnum(ed descriptor.EnumDescriptorAccessor) error
RegisterEnum registers an enum descriptor by its fully qualified name. It returns an error wrapping ErrAlreadyRegistered if an enum with the same full name is already registered.
func (*TypeRegistry) RegisterExtension ¶
func (r *TypeRegistry) RegisterExtension(fd descriptor.FieldDescriptorAccessor) error
RegisterExtension registers an extension field descriptor into both the extensions map (keyed by full name) and the extensionsByMessage map (keyed by containing message full name and field number). It returns an error wrapping ErrAlreadyRegistered if a duplicate is found in either map.
func (*TypeRegistry) RegisterMessage ¶
func (r *TypeRegistry) RegisterMessage(md descriptor.MessageDescriptorAccessor) error
RegisterMessage registers a message descriptor by its fully qualified name. It returns an error wrapping ErrAlreadyRegistered if a message with the same full name is already registered.
Source Files