fileinit

Documentation

Overview

Package fileinit constructs protoreflect.FileDescriptors from the encoded file descriptor proto messages. This package uses a custom proto unmarshaler 1) to avoid a dependency on the descriptor proto 2) for performance to keep the initialization cost as low as possible.

Index

• type FileBuilder
  • func (fb FileBuilder) Init() pref.FileDescriptor

Types

type FileBuilder

type FileBuilder struct {
	// RawDescriptor is the wire-encoded bytes of FileDescriptorProto.
	RawDescriptor []byte

	// GoTypes is a unique set of the Go types for all declarations and
	// dependencies. Each type is represented as a zero value of the Go type.
	//
	// Declarations are Go types generated for enums and messages directly
	// declared (not publicly imported) in the proto source file.
	// Messages for map entries are included, but represented by nil.
	// Enum declarations in "flattened ordering" come first, followed by
	// message declarations in "flattened ordering". The length of each sub-list
	// is len(EnumOutputTypes) and len(MessageOutputTypes), respectively.
	//
	// Dependencies are Go types for enums or messages referenced by
	// message fields (excluding weak fields), for parent extended messages of
	// extension fields, for enums or messages referenced by extension fields,
	// and for input and output messages referenced by service methods.
	// Dependencies must come after declarations, but the ordering of
	// dependencies themselves is unspecified.
	GoTypes []interface{}

	// DependencyIndexes is an ordered list of indexes into GoTypes for the
	// dependencies of messages, extensions, or services. There are 4 sub-lists
	// each in "flattened ordering" concatenated back-to-back:
	//	* Extension field targets: list of the extended parent message of
	//	every extension. Length is len(ExtensionOutputTypes).
	//	* Message field dependencies: list of the enum or message type
	//	referred to by every message field.
	//	* Extension field dependencies: list of the enum or message type
	//	referred to by every extension field.
	//	* Service method dependencies: list of the input and output message type
	//	referred to by every service method.
	DependencyIndexes []int32

	// LegacyExtensions are a list of legacy extension descriptors.
	// If provided, the pointer to the v1 ExtensionDesc will be stored into the
	// associated v2 ExtensionType and accessible via a pseudo-internal API.
	// Also, the v2 ExtensionType will be stored into each v1 ExtensionDesc.
	// If non-nil, len(LegacyExtensions) must equal len(ExtensionOutputTypes).
	LegacyExtensions []piface.ExtensionDescV1

	// EnumOutputTypes is where Init stores all initialized enum types
	// in "flattened ordering".
	EnumOutputTypes []pref.EnumType
	// MessageOutputTypes is where Init stores all initialized message types
	// in "flattened ordering". This includes slots for map entry messages,
	// which are skipped over.
	MessageOutputTypes []pimpl.MessageType
	// ExtensionOutputTypes is where Init stores all initialized extension types
	// in "flattened ordering".
	ExtensionOutputTypes []pref.ExtensionType

	// FilesRegistry is the file registry to register the file descriptor.
	// If nil, no registration occurs.
	FilesRegistry *preg.Files
	// TypesRegistry is the types registry to register each type descriptor.
	// If nil, no registration occurs.
	TypesRegistry *preg.Types
}

FileBuilder construct a protoreflect.FileDescriptor from the raw file descriptor and the Go types for declarations and dependencies.

Flattened Ordering

The protobuf type system represents declarations as a tree. Certain nodes in the tree require us to either associate it with a concrete Go type or to resolve a dependency, which is information that must be provided separately since it cannot be derived from the file descriptor alone.

However, representing a tree as Go literals is difficult to simply do in a space and time efficient way. Thus, we store them as a flattened list of objects where the serialization order from the tree-based form is important.

The "flattened ordering" is defined as a tree traversal of all enum, message, extension, and service declarations using the following algorithm:

def VisitFileDecls(fd):
	for e in fd.Enums:      yield e
	for m in fd.Messages:   yield m
	for x in fd.Extensions: yield x
	for s in fd.Services:   yield s
	for m in fd.Messages:   yield from VisitMessageDecls(m)

def VisitMessageDecls(md):
	for e in md.Enums:      yield e
	for m in md.Messages:   yield m
	for x in md.Extensions: yield x
	for m in md.Messages:   yield from VisitMessageDecls(m)

The traversal starts at the root file descriptor and yields each direct declaration within each node before traversing into sub-declarations that children themselves may have.

func (FileBuilder) Init

func (fb FileBuilder) Init() pref.FileDescriptor

Init constructs a FileDescriptor given the parameters set in FileBuilder. It assumes that the inputs are well-formed and panics if any inconsistencies are encountered.