Builder constructs type descriptors from a raw file descriptor and associated Go types for each enum and message declaration.
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.
type Builder struct {
// File is the underlying file descriptor builder.
File filedesc.Builder
// 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 accounted for, but represented by nil.
// Enum declarations in "flattened ordering" come first, followed by
// message declarations in "flattened ordering".
//
// 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 5 sub-lists in "flattened ordering" concatenated back-to-back:
// 0. Message field dependencies: list of the enum or message type
// referred to by every message field.
// 1. Extension field targets: list of the extended parent message of
// every extension.
// 2. Extension field dependencies: list of the enum or message type
// referred to by every extension field.
// 3. Service method inputs: list of the input message type
// referred to by every service method.
// 4. Service method outputs: list of the output message type
// referred to by every service method.
//
// The offset into DependencyIndexes for the start of each sub-list
// is appended to the end in reverse order.
DependencyIndexes []int32
// EnumInfos is a list of enum infos in "flattened ordering".
EnumInfos []pimpl.EnumInfo
// MessageInfos is a list of message infos in "flattened ordering".
// If provided, the GoType and PBType for each element is populated.
//
// Requirement: len(MessageInfos) == len(Build.Messages)
MessageInfos []pimpl.MessageInfo
// ExtensionInfos is a list of extension infos in "flattened ordering".
// Each element is initialized and registered with the protoregistry package.
//
// Requirement: len(LegacyExtensions) == len(Build.Extensions)
ExtensionInfos []pimpl.ExtensionInfo
// TypeRegistry is the registry to register each type descriptor.
// If nil, it uses protoregistry.GlobalTypes.
TypeRegistry interface {
RegisterMessage(protoreflect.MessageType) error
RegisterEnum(protoreflect.EnumType) error
RegisterExtension(protoreflect.ExtensionType) error
}
}
func (tb Builder) Build() (out Out)
Out is the output of the builder.
type Out struct {
File protoreflect.FileDescriptor
}