builder

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2020 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package builder contains a means of building and modifying proto descriptors programmatically. There are numerous factory methods to aid in constructing new descriptors as are there methods for converting existing descriptors into builders, for modification.

Factory Functions

Builders are created using the numerous factory functions. Each type of descriptor has two kinds of factory functions for the corresponding type of builder.

One accepts a descriptor (From*) and returns a copy of it as a builder. The descriptor can be manipulated and built to produce a new variant of the original. So this is useful for changing existing constructs.

The other kind of factory function (New*) accepts basic arguments and returns a new, empty builder (other than the arguments required by that function). This second kind can be used to fabricate descriptors from scratch.

Factory functions panic on bad input. Bad input includes invalid names (all identifiers must begin with letter or underscore and include only letters, numbers, and underscores), invalid types (for example, map field keys must be an integer type, bool, or string), invalid tag numbers (anything greater than 2^29-1, anything in the range 19,000->19,999, any non-positive number), and nil values for required fields (such as field types, RPC method types, and extendee type for extensions).

Auto-Assigning Tag Numbers and File Names

The factory function for fields does not accept a tag number. This is because tags, for fields where none is set or is explicitly set to zero, are automatically assigned. The tags are assigned in the order the fields were added to a message builder. Fields in one-ofs are assigned after other fields that were added to the message before the one-of. Within a single one-of, fields are assigned tags in the order they were added to the one-of. Across one-ofs, fields are assigned in the order their one-of was added to a message builder. It is fine if some fields have tags and some do not. The assigned tags will start at one and proceed from there but will not conflict with tags that were explicitly assigned to fields.

Similarly, when constructing a file builder, a name is accepted but can be blank. A blank name means that the file will be given a generated, unique name when the descriptor is built.

Note that extensions *must* be given a tag number. Only non-extension fields can have their tags auto-assigned. If an extension is constructed with a zero tag (which is not valid), the factory function will panic.

Descriptor Hierarchy

The hierarchy for builders is mutable. A descriptor builder, such as a field, can be moved from one message to another. When this is done, the field is unlinked from its previous location (so the message to which it previously belonged will no longer have any reference to such a field) and linked with its new parent. To instead *duplicate* a descriptor builder, its struct value can simply be copied. This allows for copying a descriptor from one parent to another, like so: 

msg := builder.FromMessage(someMsgDesc)
field1 := msg.GetField("foo")
field2 := *field1 // field2 is now a copy
otherMsg.AddField(&field2)

All descriptors have a link up the hierarchy to the file in which they were declared. However, it is *not* necessary to construct this full hierarchy with builders. One can create a message builder, for example, and then immediately build it to get the descriptor for that message. If it was never added to a file then the GetFile() method on the resulting descriptor returns a synthetic file that contains only the one message.

Note, however, that this is not true for enum values, methods, and non-extension fields. These kinds of builders *must* be added to an enum, a service, or a message (respectively) before they can be "built" into a descriptor.

When descriptors are created this way, they are created in the default (e.g. unnamed) package. In order to put descriptors into a proper package namespace, they must be added to a file that has the right package name.

Builder Pattern and Method Chaining

Each descriptor has some special fields that can only be updated via a Set* method. They also all have some exported fields that can be updated by just assigning to the field. But even exported fields have accompanying Set* methods in order to support a typical method-chaining flow when building objects: 

msg, err := builder.NewMessage("MyMessage").
    AddField(NewField("foo", FieldTypeScalar(descriptor.FieldDescriptorProto_TYPE_STRING)).
        SetDefaultValue("bar")).
    AddField(NewField("baz", FieldTypeScalar(descriptor.FieldDescriptorProto_TYPE_INT64)).
        SetLabel(descriptor.FieldDescriptorProto_LABEL_REPEATED).
        SetOptions(&descriptor.FieldOptions{Packed: proto.Bool(true)})).
    Build()

So the various Set* methods all return the builder itself so that multiple fields may be set in a single invocation chain.

The Set* operations which perform validations also have a TrySet* form which can return an error if validation fails. If the method-chaining Set* form is used with inputs that fail validation, the Set* method will panic.

Type References and Imported Types

When defining fields whose type is a message or enum and when defining methods (whose request and response type are a message), the type can be set to an actual descriptor (e.g. a *desc.MessageDescriptor) or to a builder for the type (e.g. a *builder.MessageBuilder). Since Go does not allow method overloading, the naming convention is that types referring to descriptors are "imported types" (since their use will result in an import statement in the resulting file descriptor, to import the file in which the type was defined.)

When referring to other builders, it is not necessary that the referenced types be in the same file. When building the descriptors, multiple file descriptors may be created, so that all referenced builders are themselves resolved into descriptors.

However, it is illegal to create an import cycle. So if two messages, for example, refer to each other (message Foo has a field "bar" of type Bar, and message Bar has a field "foo" of type Foo), they must explicitly be assigned to the same file builder. If they are not assigned to any files, they will be assigned to synthetic files which would result in an import cycle (each file imports the other). And the same would be true if one or both files were explicitly assigned to a file, but not both to the same file.

Validations and Caveats

Descriptors that are attained from a builder do not necessarily represent a valid construct in the proto source language. There are some validations enforced by protoc that are not enforced by builders, for example, ensuring that there are no namespace conflicts (e.g. file "foo.proto" declares an element named "pkg.bar" and so does a file that it imports). Because of this, it is possible for builders to wire up references in a way that the resulting descriptors are incorrect. This is mainly possible when file builders are used to create files with duplicate symbols and then cross-linked. It can also happen when a builder is linked to descriptors from more than one version of the same file.

When constructing descriptors using builders, applications should not attempt to build invalid constructs. Even though there are many rules in the protobuf language that are not enforced, those rules that are enforced can result in panics when a violation is detected. Generally, builder methods that do not return errors (like those used for method chaining) will panic on bad input or when trying to mutate a proto into an invalid state.

Several rules are enforced by the builders. Violating these rules will result in errors (or panics for factory functions and methods that do not return errors). These are the rules that are currently enforced:

  1. Import cycles are not allowed. (See above for more details.)
  2. Within a single file, symbols are not allowed to have naming conflicts. This means that is not legal to create a message and an extension with the same name in the same file.
  3. Messages are not allowed to have multiple fields with the same tag. Note that only non-extension fields are checked when using builders. So builders will allow tag collisions for extensions. (Use caution.)
  4. Map keys can only be integer types, booleans, and strings.
  5. Fields cannot have tags in the special reserved range 19000-19999. Also the maximum allowed tag value is 536870911 (2^29 - 1). Finally, fields cannot have negative values.
  6. Element names should include only underscore, letters, and numbers, and must begin with an underscore or letter.

Validation rules that are *not* enforced by builders, and thus would be allowed and result in illegal constructs, include the following:

  1. Files with a syntax of proto3 are not allowed to have required fields.
  2. Files with a syntax of proto3 are not allowed to have messages that define extension ranges.
  3. Files with a syntax of proto3 are not allowed to use groups.
  4. Files with a syntax of proto3 are not allowed to declare default values for fields.
  5. Names are supposed to be globally unique, even across multiple files if multiple files are defined in the same package.
  6. Extension fields must use tag numbers that are in an extension range defined on the extended message.
  7. Multiple extensions for the same message cannot re-use tag numbers, even across multiple files.
  8. Non-extension fields are not allowed to use tags that lie in a message's extension ranges or reserved ranges.
  9. Non-extension fields are not allowed to use names that the message has marked as reserved.
  10. Extension ranges and reserved ranges must not overlap.

This list may change in the future, as more validation rules may be implemented in the builders.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetFullyQualifiedName 

func GetFullyQualifiedName(b Builder) string

GetFullyQualifiedName returns the given builder's fully-qualified name. This name is based on the parent elements the builder may be linked to, which provide context like package and (optional) enclosing message names. 

func Unlink(b Builder)

Unlink removes the given builder from its parent. The parent will no longer refer to the builder and vice versa.

Types

type Builder 

type Builder interface {
	// GetName returns this element's name. The name returned is a simple name,
	// not a qualified name.
	GetName() string

	// TrySetName attempts to set this element's name. If the rename cannot
	// proceed (e.g. this element's parent already has an element with that
	// name) then an error is returned.
	//
	// All builders also have a method named SetName that panics on error and
	// returns the builder itself (for method chaining). But that isn't defined
	// on this interface because its return type varies with the type of the
	// descriptor builder.
	TrySetName(newName string) error

	// GetParent returns this element's parent element. It returns nil if there
	// is no parent element. File builders never have parent elements.
	GetParent() Builder

	// GetFile returns this element's file. This returns nil if the element has
	// not yet been assigned to a file.
	GetFile() *FileBuilder

	// GetChildren returns all of this element's child elements. A file will
	// return all of its top-level messages, enums, extensions, and services. A
	// message will return all of its fields as well as nested messages, enums,
	// and extensions, etc. Children will generally be grouped by type and,
	// within a group, in the same order as the children were added to their
	// parent.
	GetChildren() []Builder

	// GetComments returns the comments for this element. If the element has no
	// comments then the returned struct will have all empty fields. Comments
	// can be added to the element by setting fields of the returned struct.
	//
	// All builders also have a SetComments method that modifies the comments
	// and returns the builder itself (for method chaining). But that isn't
	// defined on this interface because its return type varies with the type of
	// the descriptor builder.
	GetComments() *Comments

	// BuildDescriptor is a generic form of the Build method. Its declared
	// return type is general so that it can be included in this interface and
	// implemented by all concrete builder types.
	//
	// If the builder includes references to custom options, only those known to
	// the calling program (i.e. linked in and registered with the proto
	// package) can be correctly interpreted. If the builder references other
	// custom options, use BuilderOptions.Build instead.
	BuildDescriptor() (desc.Descriptor, error)
	// contains filtered or unexported methods
}

Builder is the core interface implemented by all descriptor builders. It exposes some basic information about the descriptor hierarchy's structure.

All Builders also have a Build() method, but that is not part of this interface because its return type varies with the type of descriptor that is built.

type BuilderOptions 

type BuilderOptions struct {
	// This registry provides definitions for custom options. If a builder
	// refers to an option that is not known by this registry, it can still be
	// interpreted if the extension is "known" to the calling program (i.e.
	// linked in and registered with the proto package).
	Extensions *dynamic.ExtensionRegistry

	// If this option is true, then all options referred to in builders must
	// be interpreted. That means that if an option is present that is neither
	// recognized by Extenions nor known to the calling program, trying to build
	// the descriptor will fail.
	RequireInterpretedOptions bool
}

BuilderOptions includes additional options to use when building descriptors.

func (BuilderOptions) Build 

func (opts BuilderOptions) Build(b Builder) (desc.Descriptor, error)

Build processes the given builder into a descriptor using these options. Using the builder's Build() or BuildDescriptor() method is equivalent to building with a zero-value BuilderOptions.

type Comments 

type Comments struct {
	LeadingDetachedComments []string
	LeadingComment          string
	TrailingComment         string
}

Comments represents the various comments that might be associated with a descriptor. These are equivalent to the various kinds of comments found in a *dpb.SourceCodeInfo_Location struct that protoc associates with elements in the parsed proto source file. This can be used to create or preserve comments (including documentation) for elements.

type EnumBuilder 

type EnumBuilder struct {
	Options        *dpb.EnumOptions
	ReservedRanges []*dpb.EnumDescriptorProto_EnumReservedRange
	ReservedNames  []string
	// contains filtered or unexported fields
}

EnumBuilder is a builder used to construct a desc.EnumDescriptor.

To create a new EnumBuilder, use NewEnum.

func FromEnum 

func FromEnum(ed *desc.EnumDescriptor) (*EnumBuilder, error)

FromEnum returns an EnumBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given enum that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the enum descriptor's parent.

This means that enum builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original enum's package name.

func NewEnum 

func NewEnum(name string) *EnumBuilder

NewEnum creates a new EnumBuilder for an enum with the given name. Since the new message has no parent element, it also has no package name (e.g. it is in the unnamed package, until it is assigned to a file builder that defines a package name).

func (*EnumBuilder) AddReservedName 

func (eb *EnumBuilder) AddReservedName(name string) *EnumBuilder

AddReservedName adds the given name to the list of reserved value names for this enum. This returns the enum, for method chaining.

func (*EnumBuilder) AddReservedRange 

func (eb *EnumBuilder) AddReservedRange(start, end int32) *EnumBuilder

AddReservedRange adds the given reserved range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*EnumBuilder) AddValue 

func (eb *EnumBuilder) AddValue(evb *EnumValueBuilder) *EnumBuilder

AddValue adds the given enum value to this enum. If an error prevents the value from being added, this method panics. This returns the enum builder, for method chaining.

func (*EnumBuilder) Build 

func (eb *EnumBuilder) Build() (*desc.EnumDescriptor, error)

Build constructs an enum descriptor based on the contents of this enum builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*EnumBuilder) BuildDescriptor 

func (eb *EnumBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs an enum descriptor based on the contents of this enum builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*EnumBuilder) GetChildren 

func (eb *EnumBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this enum builder. These will be the enum's values.

func (*EnumBuilder) GetComments 

func (b *EnumBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*EnumBuilder) GetFile 

func (b *EnumBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*EnumBuilder) GetName 

func (b *EnumBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*EnumBuilder) GetParent 

func (b *EnumBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*EnumBuilder) GetValue 

func (eb *EnumBuilder) GetValue(name string) *EnumValueBuilder

GetValue returns the enum value with the given name. If no such value exists in the enum, nil is returned.

func (*EnumBuilder) RemoveValue 

func (eb *EnumBuilder) RemoveValue(name string) *EnumBuilder

RemoveValue removes the enum value with the given name. If no such value exists in the enum, this is a no-op. This returns the enum builder, for method chaining.

func (*EnumBuilder) SetComments 

func (eb *EnumBuilder) SetComments(c Comments) *EnumBuilder

SetComments sets the comments associated with the enum. This method returns the enum builder, for method chaining.

func (*EnumBuilder) SetName 

func (eb *EnumBuilder) SetName(newName string) *EnumBuilder

SetName changes this enum's name, returning the enum builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*EnumBuilder) SetOptions 

func (eb *EnumBuilder) SetOptions(options *dpb.EnumOptions) *EnumBuilder

SetOptions sets the enum options for this enum and returns the enum, for method chaining.

func (*EnumBuilder) SetReservedNames 

func (eb *EnumBuilder) SetReservedNames(names []string) *EnumBuilder

SetReservedNames replaces all of this enum's reserved value names with the given slice of names. This returns the enum, for method chaining.

func (*EnumBuilder) SetReservedRanges 

func (eb *EnumBuilder) SetReservedRanges(ranges []*dpb.EnumDescriptorProto_EnumReservedRange) *EnumBuilder

SetReservedRanges replaces all of this enum's reserved ranges with the given slice of ranges. This returns the enum, for method chaining.

func (*EnumBuilder) TryAddValue 

func (eb *EnumBuilder) TryAddValue(evb *EnumValueBuilder) error

TryAddValue adds the given enum value to this enum, returning any error that prevents the value from being added (such as a name collision with another value already added to the enum).

func (*EnumBuilder) TryRemoveValue 

func (eb *EnumBuilder) TryRemoveValue(name string) bool

TryRemoveValue removes the enum value with the given name and returns false if the enum has no such value.

func (*EnumBuilder) TrySetName 

func (eb *EnumBuilder) TrySetName(newName string) error

TrySetName changes this enum's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

type EnumValueBuilder 

type EnumValueBuilder struct {
	Options *dpb.EnumValueOptions
	// contains filtered or unexported fields
}

EnumValueBuilder is a builder used to construct a desc.EnumValueDescriptor. A enum value builder *must* be added to an enum before calling its Build() method.

To create a new EnumValueBuilder, use NewEnumValue.

func FromEnumValue 

func FromEnumValue(evd *desc.EnumValueDescriptor) (*EnumValueBuilder, error)

FromEnumValue returns an EnumValueBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given enum value that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the enum value descriptor's parent enum.

This means that enum value builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original enum value's package name.

func NewEnumValue 

func NewEnumValue(name string) *EnumValueBuilder

NewEnumValue creates a new EnumValueBuilder for an enum value with the given name. The return value's numeric value will not be set, which means it will be auto-assigned when the descriptor is built, unless explicitly set with a call to SetNumber.

func (*EnumValueBuilder) Build 

func (evb *EnumValueBuilder) Build() (*desc.EnumValueDescriptor, error)

Build constructs an enum value descriptor based on the contents of this enum value builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*EnumValueBuilder) BuildDescriptor 

func (evb *EnumValueBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs an enum value descriptor based on the contents of this enum value builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*EnumValueBuilder) ClearNumber 

func (evb *EnumValueBuilder) ClearNumber() *EnumValueBuilder

ClearNumber clears this enum value's numeric value and then returns the enum value builder, for method chaining. After being cleared, the number will be auto-assigned when the descriptor is built, unless explicitly set by a subsequent call to SetNumber.

func (*EnumValueBuilder) GetChildren 

func (evb *EnumValueBuilder) GetChildren() []Builder

GetChildren returns nil, since enum values cannot have child elements. It is present to satisfy the Builder interface.

func (*EnumValueBuilder) GetComments 

func (b *EnumValueBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*EnumValueBuilder) GetFile 

func (b *EnumValueBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*EnumValueBuilder) GetName 

func (b *EnumValueBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*EnumValueBuilder) GetNumber 

func (evb *EnumValueBuilder) GetNumber() int32

GetNumber returns the enum value's numeric value. If the number has not been set this returns zero.

func (*EnumValueBuilder) GetParent 

func (b *EnumValueBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*EnumValueBuilder) HasNumber 

func (evb *EnumValueBuilder) HasNumber() bool

HasNumber returns whether or not the enum value's numeric value has been set. If it has not been set, it is auto-assigned when the descriptor is built.

func (*EnumValueBuilder) SetComments 

func (evb *EnumValueBuilder) SetComments(c Comments) *EnumValueBuilder

SetComments sets the comments associated with the enum value. This method returns the enum value builder, for method chaining.

func (*EnumValueBuilder) SetName 

func (evb *EnumValueBuilder) SetName(newName string) *EnumValueBuilder

SetName changes this enum value's name, returning the enum value builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*EnumValueBuilder) SetNumber 

func (evb *EnumValueBuilder) SetNumber(number int32) *EnumValueBuilder

SetNumber changes the numeric value for this enum value and then returns the enum value, for method chaining.

func (*EnumValueBuilder) SetOptions 

func (evb *EnumValueBuilder) SetOptions(options *dpb.EnumValueOptions) *EnumValueBuilder

SetOptions sets the enum value options for this enum value and returns the enum value, for method chaining.

func (*EnumValueBuilder) TrySetName 

func (evb *EnumValueBuilder) TrySetName(newName string) error

TrySetName changes this enum value's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent enum builder already has an enum value with the given name.

type FieldBuilder 

type FieldBuilder struct {
	Options        *dpb.FieldOptions
	Label          dpb.FieldDescriptorProto_Label
	Proto3Optional bool
	Default        string
	JsonName       string
	// contains filtered or unexported fields
}

FieldBuilder is a builder used to construct a desc.FieldDescriptor. A field builder is used to create fields and extensions as well as map entry messages. It is also used to link groups (defined via a message builder) into an enclosing message, associating it with a group field. A non-extension field builder *must* be added to a message before calling its Build() method.

To create a new FieldBuilder, use NewField, NewMapField, NewGroupField, NewExtension, or NewExtensionImported (depending on the type of field being built).

func FromField 

func FromField(fld *desc.FieldDescriptor) (*FieldBuilder, error)

FromField returns a FieldBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given field that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the field descriptor's parent.

This means that field builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original field's package name.

func NewExtension 

func NewExtension(name string, tag int32, typ *FieldType, extendee *MessageBuilder) *FieldBuilder

NewExtension creates a new FieldBuilder for an extension field with the given name, tag, type, and extendee. The extendee given is a message builder.

The new field will be optional. See SetLabel and SetRepeated for changing this aspect of the field.

func NewExtensionImported 

func NewExtensionImported(name string, tag int32, typ *FieldType, extendee *desc.MessageDescriptor) *FieldBuilder

NewExtensionImported creates a new FieldBuilder for an extension field with the given name, tag, type, and extendee. The extendee given is a message descriptor.

The new field will be optional. See SetLabel and SetRepeated for changing this aspect of the field.

func NewField 

func NewField(name string, typ *FieldType) *FieldBuilder

NewField creates a new FieldBuilder for a non-extension field with the given name and type. To create a map or group field, see NewMapField or NewGroupField respectively.

The new field will be optional. See SetLabel, SetRepeated, and SetRequired for changing this aspect of the field. The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func NewGroupField 

func NewGroupField(mb *MessageBuilder) *FieldBuilder

NewGroupField creates a new FieldBuilder for a non-extension field whose type is a group with the given definition. The given message's name must start with a capital letter, and the resulting field will have the same name but converted to all lower-case. If a message is given with a name that starts with a lower-case letter, this function will panic.

When this field is added to a message, the associated group message type will also be added.

The new field will be optional. See SetLabel, SetRepeated, and SetRequired for changing this aspect of the field. The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func NewMapField 

func NewMapField(name string, keyTyp, valTyp *FieldType) *FieldBuilder

NewMapField creates a new FieldBuilder for a non-extension field with the given name and whose type is a map of the given key and value types. Map keys can be any of the scalar integer types, booleans, or strings. If any other type is specified, this function will panic. Map values cannot be groups: if a group type is specified, this function will panic.

When this field is added to a message, the associated map entry message type will also be added.

The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func (*FieldBuilder) Build 

func (flb *FieldBuilder) Build() (*desc.FieldDescriptor, error)

Build constructs a field descriptor based on the contents of this field builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*FieldBuilder) BuildDescriptor 

func (flb *FieldBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a field descriptor based on the contents of this field builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*FieldBuilder) GetChildren 

func (flb *FieldBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this field builder. The only kind of children a field can have are message types, that correspond to the field's map entry type or group type (for map and group fields respectively).

func (*FieldBuilder) GetComments 

func (b *FieldBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*FieldBuilder) GetExtendeeTypeName 

func (flb *FieldBuilder) GetExtendeeTypeName() string

GetExtendeeTypeName returns the fully qualified name of the extended message or it returns an empty string if this is not an extension field.

func (*FieldBuilder) GetFile 

func (b *FieldBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*FieldBuilder) GetName 

func (b *FieldBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*FieldBuilder) GetNumber 

func (flb *FieldBuilder) GetNumber() int32

GetNumber returns this field's tag number, or zero if the tag number will be auto-assigned when the field descriptor is built.

func (*FieldBuilder) GetParent 

func (b *FieldBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*FieldBuilder) GetType 

func (flb *FieldBuilder) GetType() *FieldType

GetType returns the field's type.

func (*FieldBuilder) IsExtension 

func (flb *FieldBuilder) IsExtension() bool

IsExtension returns true if this is an extension field.

func (*FieldBuilder) IsMap 

func (flb *FieldBuilder) IsMap() bool

IsMap returns true if this field is a map field.

func (*FieldBuilder) IsOptional 

func (flb *FieldBuilder) IsOptional() bool

IsOptional returns true if this field's label is optional.

func (*FieldBuilder) IsRepeated 

func (flb *FieldBuilder) IsRepeated() bool

IsRepeated returns true if this field's label is repeated. Fields created via NewMapField will be repeated (since map's are represented "under the hood" as a repeated field of map entry messages).

func (*FieldBuilder) IsRequired 

func (flb *FieldBuilder) IsRequired() bool

IsRequired returns true if this field's label is required.

func (*FieldBuilder) SetComments 

func (flb *FieldBuilder) SetComments(c Comments) *FieldBuilder

SetComments sets the comments associated with the field. This method returns the field builder, for method chaining.

func (*FieldBuilder) SetDefaultValue 

func (flb *FieldBuilder) SetDefaultValue(defValue string) *FieldBuilder

SetDefaultValue changes the field's type and returns the field builder, for method chaining.

func (*FieldBuilder) SetJsonName 

func (flb *FieldBuilder) SetJsonName(jsonName string) *FieldBuilder

SetJsonName sets the name used in the field's JSON representation and then returns the field builder, for method chaining.

func (*FieldBuilder) SetLabel 

func (flb *FieldBuilder) SetLabel(lbl dpb.FieldDescriptorProto_Label) *FieldBuilder

SetLabel sets the label for this field, which can be optional, repeated, or required. It returns the field builder, for method chaining.

func (*FieldBuilder) SetName 

func (flb *FieldBuilder) SetName(newName string) *FieldBuilder

SetName changes this field's name, returning the field builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*FieldBuilder) SetNumber 

func (flb *FieldBuilder) SetNumber(tag int32) *FieldBuilder

SetNumber changes the numeric tag for this field and then returns the field, for method chaining. If the given new tag is not valid (e.g. TrySetNumber would have returned an error) then this method will panic.

func (*FieldBuilder) SetOptional 

func (flb *FieldBuilder) SetOptional() *FieldBuilder

SetOptional sets the label for this field to optional. It returns the field builder, for method chaining.

func (*FieldBuilder) SetOptions 

func (flb *FieldBuilder) SetOptions(options *dpb.FieldOptions) *FieldBuilder

SetOptions sets the field options for this field and returns the field, for method chaining.

func (*FieldBuilder) SetProto3Optional 

func (flb *FieldBuilder) SetProto3Optional(p3o bool) *FieldBuilder

SetProto3Optional sets whether this is a proto3 optional field. It returns the field builder, for method chaining.

func (*FieldBuilder) SetRepeated 

func (flb *FieldBuilder) SetRepeated() *FieldBuilder

SetRepeated sets the label for this field to repeated. It returns the field builder, for method chaining.

func (*FieldBuilder) SetRequired 

func (flb *FieldBuilder) SetRequired() *FieldBuilder

SetRequired sets the label for this field to required. It returns the field builder, for method chaining.

func (*FieldBuilder) SetType 

func (flb *FieldBuilder) SetType(ft *FieldType) *FieldBuilder

SetType changes the field's type and returns the field builder, for method chaining.

func (*FieldBuilder) TrySetName 

func (flb *FieldBuilder) TrySetName(newName string) error

TrySetName changes this field's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

If the field is a non-extension whose parent is a one-of, the one-of's enclosing message is checked for elements with a conflicting name. Despite the fact that one-of choices are modeled as children of the one-of builder, in the protobuf IDL they are actually all defined in the message's namespace.

func (*FieldBuilder) TrySetNumber 

func (flb *FieldBuilder) TrySetNumber(tag int32) error

TrySetNumber changes this field's tag number. It will return an error if the given new tag is out of valid range or (for non-extension fields) if the enclosing message already includes a field with the given tag.

Non-extension fields can be set to zero, which means a proper tag number will be auto-assigned when the descriptor is built. Extension field tags, however, must be set to a valid non-zero value.

type FieldType 

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

FieldType represents the type of a field or extension. It can represent a message or enum type or any of the scalar types supported by protobufs.

Message and enum types can reference a message or enum builder. A type that refers to a built message or enum descriptor is called an "imported" type.

There are numerous factory methods for creating FieldType instances.

func FieldTypeBool 

func FieldTypeBool() *FieldType

FieldTypeBool returns a FieldType for the bool scalar type.

func FieldTypeBytes 

func FieldTypeBytes() *FieldType

FieldTypeBytes returns a FieldType for the bytes scalar type.

func FieldTypeDouble 

func FieldTypeDouble() *FieldType

FieldTypeDouble returns a FieldType for the double scalar type.

func FieldTypeEnum 

func FieldTypeEnum(eb *EnumBuilder) *FieldType

FieldTypeEnum returns a FieldType for the given enum type.

func FieldTypeFixed32 

func FieldTypeFixed32() *FieldType

FieldTypeFixed32 returns a FieldType for the fixed32 scalar type.

func FieldTypeFixed64 

func FieldTypeFixed64() *FieldType

FieldTypeFixed64 returns a FieldType for the fixed64 scalar type.

func FieldTypeFloat 

func FieldTypeFloat() *FieldType

FieldTypeFloat returns a FieldType for the float scalar type.

func FieldTypeImportedEnum 

func FieldTypeImportedEnum(ed *desc.EnumDescriptor) *FieldType

FieldTypeImportedEnum returns a FieldType that references the given enum descriptor.

func FieldTypeImportedMessage 

func FieldTypeImportedMessage(md *desc.MessageDescriptor) *FieldType

FieldTypeImportedMessage returns a FieldType that references the given message descriptor.

func FieldTypeInt32 

func FieldTypeInt32() *FieldType

FieldTypeInt32 returns a FieldType for the int32 scalar type.

func FieldTypeInt64 

func FieldTypeInt64() *FieldType

FieldTypeInt64 returns a FieldType for the int64 scalar type.

func FieldTypeMessage 

func FieldTypeMessage(mb *MessageBuilder) *FieldType

FieldTypeMessage returns a FieldType for the given message type.

func FieldTypeSFixed32 

func FieldTypeSFixed32() *FieldType

FieldTypeSFixed32 returns a FieldType for the sfixed32 scalar type.

func FieldTypeSFixed64 

func FieldTypeSFixed64() *FieldType

FieldTypeSFixed64 returns a FieldType for the sfixed64 scalar type.

func FieldTypeSInt32 

func FieldTypeSInt32() *FieldType

FieldTypeSInt32 returns a FieldType for the sint32 scalar type.

func FieldTypeSInt64 

func FieldTypeSInt64() *FieldType

FieldTypeSInt64 returns a FieldType for the sint64 scalar type.

func FieldTypeScalar 

func FieldTypeScalar(t dpb.FieldDescriptorProto_Type) *FieldType

FieldTypeScalar returns a FieldType for the given scalar type. If the given type is not scalar (e.g. it is a message, group, or enum) than this function will panic.

func FieldTypeString 

func FieldTypeString() *FieldType

FieldTypeString returns a FieldType for the string scalar type.

func FieldTypeUInt32 

func FieldTypeUInt32() *FieldType

FieldTypeUInt32 returns a FieldType for the uint32 scalar type.

func FieldTypeUInt64 

func FieldTypeUInt64() *FieldType

FieldTypeUInt64 returns a FieldType for the uint64 scalar type.

func (*FieldType) GetType 

func (ft *FieldType) GetType() dpb.FieldDescriptorProto_Type

GetType returns the enum value indicating the type of the field. If the type is a message (or group) or enum type, GetTypeName provides the name of the referenced type.

func (*FieldType) GetTypeName 

func (ft *FieldType) GetTypeName() string

GetTypeName returns the fully-qualified name of the referenced message or enum type. It returns an empty string if this type does not represent a message or enum type.

type FileBuilder 

type FileBuilder struct {
	IsProto3 bool
	Package  string
	Options  *dpb.FileOptions

	SyntaxComments  Comments
	PackageComments Comments
	// contains filtered or unexported fields
}

FileBuilder is a builder used to construct a desc.FileDescriptor. This is the root of the hierarchy. All other descriptors belong to a file, and thus all other builders also belong to a file.

If a builder is *not* associated with a file, the resulting descriptor will be associated with a synthesized file that contains only the built descriptor and its ancestors. This means that such descriptors will have no associated package name.

To create a new FileBuilder, use NewFile.

func FromFile 

func FromFile(fd *desc.FileDescriptor) (*FileBuilder, error)

FromFile returns a FileBuilder that is effectively a copy of the given descriptor. Note that builders do not retain full source code info, even if the given descriptor included it. Instead, comments are extracted from the given descriptor's source info (if present) and, when built, the resulting descriptor will have just the comment info (no location information).

func NewFile 

func NewFile(name string) *FileBuilder

NewFile creates a new FileBuilder for a file with the given name. The name can be blank, which indicates a unique name should be generated for it.

func (*FileBuilder) AddDependency 

func (fb *FileBuilder) AddDependency(dep *FileBuilder) *FileBuilder

AddDependency adds the given file as an explicit import. Normally, dependencies can be inferred during the build process by finding the files for all referenced types (such as message and enum types used in this file). However, this does not work for custom options, which must be known in order to be interpretable. And they aren't known unless an explicit import is added for the file that contains the custom options.

Knowledge of custom options can also be provided by using BuildOptions with an ExtensionRegistry, when building the file.

func (*FileBuilder) AddEnum 

func (fb *FileBuilder) AddEnum(eb *EnumBuilder) *FileBuilder

AddEnum adds the given enum to this file. If an error prevents the enum from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddExtension 

func (fb *FileBuilder) AddExtension(exb *FieldBuilder) *FileBuilder

AddExtension adds the given extension to this file. If an error prevents the extension from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddImportedDependency 

func (fb *FileBuilder) AddImportedDependency(dep *desc.FileDescriptor) *FileBuilder

AddImportedDependency adds the given file as an explicit import. Normally, dependencies can be inferred during the build process by finding the files for all referenced types (such as message and enum types used in this file). However, this does not work for custom options, which must be known in order to be interpretable. And they aren't known unless an explicit import is added for the file that contains the custom options.

Knowledge of custom options can also be provided by using BuildOptions with an ExtensionRegistry, when building the file.

func (*FileBuilder) AddMessage 

func (fb *FileBuilder) AddMessage(mb *MessageBuilder) *FileBuilder

AddMessage adds the given message to this file. If an error prevents the message from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddService 

func (fb *FileBuilder) AddService(sb *ServiceBuilder) *FileBuilder

AddService adds the given service to this file. If an error prevents the service from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) Build 

func (fb *FileBuilder) Build() (*desc.FileDescriptor, error)

Build constructs a file descriptor based on the contents of this file builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*FileBuilder) BuildDescriptor 

func (fb *FileBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a file descriptor based on the contents of this file builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*FileBuilder) GetChildren 

func (fb *FileBuilder) GetChildren() []Builder

GetChildren returns builders for all nested elements, including all top-level messages, enums, extensions, and services.

func (*FileBuilder) GetComments 

func (fb *FileBuilder) GetComments() *Comments

GetComments returns comments associated with the file itself and not any particular element therein. (Note that such a comment will not be rendered by the protoprint package.)

func (*FileBuilder) GetEnum 

func (fb *FileBuilder) GetEnum(name string) *EnumBuilder

GetEnum returns the top-level enum with the given name. If no such enum exists in the file, nil is returned.

func (*FileBuilder) GetExtension 

func (fb *FileBuilder) GetExtension(name string) *FieldBuilder

GetExtension returns the top-level extension with the given name. If no such extension exists in the file, nil is returned.

func (*FileBuilder) GetFile 

func (fb *FileBuilder) GetFile() *FileBuilder

GetFile implements the Builder interface and always returns this file.

func (*FileBuilder) GetMessage 

func (fb *FileBuilder) GetMessage(name string) *MessageBuilder

GetMessage returns the top-level message with the given name. If no such message exists in the file, nil is returned.

func (*FileBuilder) GetName 

func (fb *FileBuilder) GetName() string

GetName returns the name of the file. It may include relative path information, too.

func (*FileBuilder) GetParent 

func (fb *FileBuilder) GetParent() Builder

GetParent always returns nil since files are the roots of builder hierarchies.

func (*FileBuilder) GetService 

func (fb *FileBuilder) GetService(name string) *ServiceBuilder

GetService returns the top-level service with the given name. If no such service exists in the file, nil is returned.

func (*FileBuilder) RemoveEnum 

func (fb *FileBuilder) RemoveEnum(name string) *FileBuilder

RemoveEnum removes the top-level enum with the given name. If no such enum exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveExtension 

func (fb *FileBuilder) RemoveExtension(name string) *FileBuilder

RemoveExtension removes the top-level extension with the given name. If no such extension exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveMessage 

func (fb *FileBuilder) RemoveMessage(name string) *FileBuilder

RemoveMessage removes the top-level message with the given name. If no such message exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveService 

func (fb *FileBuilder) RemoveService(name string) *FileBuilder

RemoveService removes the top-level service with the given name. If no such service exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) SetComments 

func (fb *FileBuilder) SetComments(c Comments) *FileBuilder

SetComments sets the comments associated with the file itself, not any particular element therein. (Note that such a comment will not be rendered by the protoprint package.) This method returns the file, for method chaining.

func (*FileBuilder) SetName 

func (fb *FileBuilder) SetName(newName string) *FileBuilder

SetName changes this file's name, returning the file builder for method chaining.

func (*FileBuilder) SetOptions 

func (fb *FileBuilder) SetOptions(options *dpb.FileOptions) *FileBuilder

SetOptions sets the file options for this file and returns the file, for method chaining.

func (*FileBuilder) SetPackageComments 

func (fb *FileBuilder) SetPackageComments(c Comments) *FileBuilder

SetPackageComments sets the comments associated with the package declaration element. (This comment will not be rendered if the file's declared package is empty.) This method returns the file, for method chaining.

func (*FileBuilder) SetPackageName 

func (fb *FileBuilder) SetPackageName(pkg string) *FileBuilder

SetPackageName sets the name of the package for this file and returns the file, for method chaining.

func (*FileBuilder) SetProto3 

func (fb *FileBuilder) SetProto3(isProto3 bool) *FileBuilder

SetProto3 sets whether this file is declared to use "proto3" syntax or not and returns the file, for method chaining.

func (*FileBuilder) SetSyntaxComments 

func (fb *FileBuilder) SetSyntaxComments(c Comments) *FileBuilder

SetSyntaxComments sets the comments associated with the syntax declaration element (which, if present, is required to be the first element in a proto file). This method returns the file, for method chaining.

func (*FileBuilder) TryAddEnum 

func (fb *FileBuilder) TryAddEnum(eb *EnumBuilder) error

TryAddEnum adds the given enum to this file, returning any error that prevents the enum from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddExtension 

func (fb *FileBuilder) TryAddExtension(exb *FieldBuilder) error

TryAddExtension adds the given extension to this file, returning any error that prevents the extension from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddMessage 

func (fb *FileBuilder) TryAddMessage(mb *MessageBuilder) error

TryAddMessage adds the given message to this file, returning any error that prevents the message from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddService 

func (fb *FileBuilder) TryAddService(sb *ServiceBuilder) error

TryAddService adds the given service to this file, returning any error that prevents the service from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryRemoveEnum 

func (fb *FileBuilder) TryRemoveEnum(name string) bool

TryRemoveEnum removes the top-level enum with the given name and returns false if the file has no such enum.

func (*FileBuilder) TryRemoveExtension 

func (fb *FileBuilder) TryRemoveExtension(name string) bool

TryRemoveExtension removes the top-level extension with the given name and returns false if the file has no such extension.

func (*FileBuilder) TryRemoveMessage 

func (fb *FileBuilder) TryRemoveMessage(name string) bool

TryRemoveMessage removes the top-level message with the given name and returns false if the file has no such message.

func (*FileBuilder) TryRemoveService 

func (fb *FileBuilder) TryRemoveService(name string) bool

TryRemoveService removes the top-level service with the given name and returns false if the file has no such service.

func (*FileBuilder) TrySetName 

func (fb *FileBuilder) TrySetName(newName string) error

TrySetName changes this file's name. It always returns nil since renaming a file cannot fail. (It is specified to return error to satisfy the Builder interface.)

type MessageBuilder 

type MessageBuilder struct {
	Options         *dpb.MessageOptions
	ExtensionRanges []*dpb.DescriptorProto_ExtensionRange
	ReservedRanges  []*dpb.DescriptorProto_ReservedRange
	ReservedNames   []string
	// contains filtered or unexported fields
}

MessageBuilder is a builder used to construct a desc.MessageDescriptor. A message builder can define nested messages, enums, and extensions in addition to defining the message's fields.

Note that when building a descriptor from a MessageBuilder, not all protobuf validation rules are enforced. See the package documentation for more info.

To create a new MessageBuilder, use NewMessage.

func FromMessage 

func FromMessage(md *desc.MessageDescriptor) (*MessageBuilder, error)

FromMessage returns a MessageBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given message that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the message descriptor's parent.

This means that message builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original message's package name.

func NewMessage 

func NewMessage(name string) *MessageBuilder

NewMessage creates a new MessageBuilder for a message with the given name. Since the new message has no parent element, it also has no package name (e.g. it is in the unnamed package, until it is assigned to a file builder that defines a package name).

func (*MessageBuilder) AddExtensionRange 

func (mb *MessageBuilder) AddExtensionRange(start, end int32) *MessageBuilder

AddExtensionRange adds the given extension range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) AddExtensionRangeWithOptions 

func (mb *MessageBuilder) AddExtensionRangeWithOptions(start, end int32, options *dpb.ExtensionRangeOptions) *MessageBuilder

AddExtensionRangeWithOptions adds the given extension range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) AddField 

func (mb *MessageBuilder) AddField(flb *FieldBuilder) *MessageBuilder

AddField adds the given field to this message. If an error prevents the field from being added, this method panics. If the given field is an extension, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedEnum 

func (mb *MessageBuilder) AddNestedEnum(eb *EnumBuilder) *MessageBuilder

AddNestedEnum adds the given enum as a nested child of this message. If an error prevents the enum from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedExtension 

func (mb *MessageBuilder) AddNestedExtension(exb *FieldBuilder) *MessageBuilder

AddNestedExtension adds the given extension as a nested child of this message. If an error prevents the extension from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedMessage 

func (mb *MessageBuilder) AddNestedMessage(nmb *MessageBuilder) *MessageBuilder

AddNestedMessage adds the given message as a nested child of this message. If an error prevents the message from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddOneOf 

func (mb *MessageBuilder) AddOneOf(oob *OneOfBuilder) *MessageBuilder

AddOneOf adds the given one-of to this message. If an error prevents the one-of from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddReservedName 

func (mb *MessageBuilder) AddReservedName(name string) *MessageBuilder

AddReservedName adds the given name to the list of reserved field names for this message. This returns the message, for method chaining.

func (*MessageBuilder) AddReservedRange 

func (mb *MessageBuilder) AddReservedRange(start, end int32) *MessageBuilder

AddReservedRange adds the given reserved range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) Build 

func (mb *MessageBuilder) Build() (*desc.MessageDescriptor, error)

Build constructs a message descriptor based on the contents of this message builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*MessageBuilder) BuildDescriptor 

func (mb *MessageBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a message descriptor based on the contents of this message builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*MessageBuilder) GetChildren 

func (mb *MessageBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this message builder. These will include the message's fields and one-ofs as well as any nested messages, extensions, and enums.

func (*MessageBuilder) GetComments 

func (b *MessageBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*MessageBuilder) GetField 

func (mb *MessageBuilder) GetField(name string) *FieldBuilder

GetField returns the field with the given name. If no such field exists in the message, nil is returned. The field does not have to be an immediate child of this message but could instead be an indirect child via a one-of.

func (*MessageBuilder) GetFile 

func (b *MessageBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*MessageBuilder) GetName 

func (b *MessageBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*MessageBuilder) GetNestedEnum 

func (mb *MessageBuilder) GetNestedEnum(name string) *EnumBuilder

GetNestedEnum returns the nested enum with the given name. If no such enum exists, nil is returned. The named enum must be in this message's scope. If the enum is nested more deeply, this will return nil. This means the enum must be a direct child of this message.

func (*MessageBuilder) GetNestedExtension 

func (mb *MessageBuilder) GetNestedExtension(name string) *FieldBuilder

GetNestedExtension returns the nested extension with the given name. If no such extension exists, nil is returned. The named extension must be in this message's scope. If the extension is nested more deeply, this will return nil. This means the extension must be a direct child of this message.

func (*MessageBuilder) GetNestedMessage 

func (mb *MessageBuilder) GetNestedMessage(name string) *MessageBuilder

GetNestedMessage returns the nested message with the given name. If no such message exists, nil is returned. The named message must be in this message's scope. If the message is nested more deeply, this will return nil. This means the message must be a direct child of this message or a child of one of this message's fields (e.g. the group type for a group field or a map entry for a map field).

func (*MessageBuilder) GetOneOf 

func (mb *MessageBuilder) GetOneOf(name string) *OneOfBuilder

GetOneOf returns the one-of with the given name. If no such one-of exists in the message, nil is returned.

func (*MessageBuilder) GetParent 

func (b *MessageBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*MessageBuilder) RemoveField 

func (mb *MessageBuilder) RemoveField(name string) *MessageBuilder

RemoveField removes the field with the given name. If no such field exists in the message, this is a no-op. If the field is part of a one-of, the one-of remains assigned to this message and the field is removed from it. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedEnum 

func (mb *MessageBuilder) RemoveNestedEnum(name string) *MessageBuilder

RemoveNestedEnum removes the nested enum with the given name. If no such enum exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedExtension 

func (mb *MessageBuilder) RemoveNestedExtension(name string) *MessageBuilder

RemoveNestedExtension removes the nested extension with the given name. If no such extension exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedMessage 

func (mb *MessageBuilder) RemoveNestedMessage(name string) *MessageBuilder

RemoveNestedMessage removes the nested message with the given name. If no such message exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveOneOf 

func (mb *MessageBuilder) RemoveOneOf(name string) *MessageBuilder

RemoveOneOf removes the one-of with the given name. If no such one-of exists in the message, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) SetComments 

func (mb *MessageBuilder) SetComments(c Comments) *MessageBuilder

SetComments sets the comments associated with the message. This method returns the message builder, for method chaining.

func (*MessageBuilder) SetExtensionRanges 

func (mb *MessageBuilder) SetExtensionRanges(ranges []*dpb.DescriptorProto_ExtensionRange) *MessageBuilder

SetExtensionRanges replaces all of this message's extension ranges with the given slice of ranges. Unlike AddExtensionRange and unlike the way ranges are defined in proto IDL source, a DescriptorProto_ExtensionRange struct treats the end of the range as *exclusive*. So the range is inclusive of the start but exclusive of the end. This returns the message, for method chaining.

func (*MessageBuilder) SetName 

func (mb *MessageBuilder) SetName(newName string) *MessageBuilder

SetName changes this message's name, returning the message builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*MessageBuilder) SetOptions 

func (mb *MessageBuilder) SetOptions(options *dpb.MessageOptions) *MessageBuilder

SetOptions sets the message options for this message and returns the message, for method chaining.

func (*MessageBuilder) SetReservedNames 

func (mb *MessageBuilder) SetReservedNames(names []string) *MessageBuilder

SetReservedNames replaces all of this message's reserved field names with the given slice of names. This returns the message, for method chaining.

func (*MessageBuilder) SetReservedRanges 

func (mb *MessageBuilder) SetReservedRanges(ranges []*dpb.DescriptorProto_ReservedRange) *MessageBuilder

SetReservedRanges replaces all of this message's reserved ranges with the given slice of ranges. Unlike AddReservedRange and unlike the way ranges are defined in proto IDL source, a DescriptorProto_ReservedRange struct treats the end of the range as *exclusive* (so it would be the value defined in the IDL plus one). So the range is inclusive of the start but exclusive of the end. This returns the message, for method chaining.

func (*MessageBuilder) TryAddField 

func (mb *MessageBuilder) TryAddField(flb *FieldBuilder) error

TryAddField adds the given field to this message, returning any error that prevents the field from being added (such as a name collision with another element already added to the message). An error is returned if the given field is an extension field.

func (*MessageBuilder) TryAddNestedEnum 

func (mb *MessageBuilder) TryAddNestedEnum(eb *EnumBuilder) error

TryAddNestedEnum adds the given enum as a nested child of this message, returning any error that prevents the enum from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddNestedExtension 

func (mb *MessageBuilder) TryAddNestedExtension(exb *FieldBuilder) error

TryAddNestedExtension adds the given extension as a nested child of this message, returning any error that prevents the extension from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddNestedMessage 

func (mb *MessageBuilder) TryAddNestedMessage(nmb *MessageBuilder) error

TryAddNestedMessage adds the given message as a nested child of this message, returning any error that prevents the message from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddOneOf 

func (mb *MessageBuilder) TryAddOneOf(oob *OneOfBuilder) error

TryAddOneOf adds the given one-of to this message, returning any error that prevents the one-of from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryRemoveField 

func (mb *MessageBuilder) TryRemoveField(name string) bool

TryRemoveField removes the field with the given name and returns false if the message has no such field. If the field is part of a one-of, the one-of remains assigned to this message and the field is removed from it.

func (*MessageBuilder) TryRemoveNestedEnum 

func (mb *MessageBuilder) TryRemoveNestedEnum(name string) bool

TryRemoveNestedEnum removes the nested enum with the given name and returns false if this message has no nested enum with that name.

func (*MessageBuilder) TryRemoveNestedExtension 

func (mb *MessageBuilder) TryRemoveNestedExtension(name string) bool

TryRemoveNestedExtension removes the nested extension with the given name and returns false if this message has no nested extension with that name.

func (*MessageBuilder) TryRemoveNestedMessage 

func (mb *MessageBuilder) TryRemoveNestedMessage(name string) bool

TryRemoveNestedMessage removes the nested message with the given name and returns false if this message has no nested message with that name. If the named message is a child of a field (e.g. the group type for a group field or the map entry for a map field), it is removed from that field and thus removed from this message's scope.

func (*MessageBuilder) TryRemoveOneOf 

func (mb *MessageBuilder) TryRemoveOneOf(name string) bool

TryRemoveOneOf removes the one-of with the given name and returns false if the message has no such one-of.

func (*MessageBuilder) TrySetName 

func (mb *MessageBuilder) TrySetName(newName string) error

TrySetName changes this message's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

If the message is a map or group type whose parent is the corresponding map or group field, the parent field's enclosing message is checked for elements with a conflicting name. Despite the fact that these message types are modeled as children of their associated field builder, in the protobuf IDL they are actually all defined in the enclosing message's namespace.

type MethodBuilder 

type MethodBuilder struct {
	Options  *dpb.MethodOptions
	ReqType  *RpcType
	RespType *RpcType
	// contains filtered or unexported fields
}

MethodBuilder is a builder used to construct a desc.MethodDescriptor. A method builder *must* be added to a service before calling its Build() method.

To create a new MethodBuilder, use NewMethod.

func FromMethod 

func FromMethod(mtd *desc.MethodDescriptor) (*MethodBuilder, error)

FromMethod returns a MethodBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given method that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the method descriptor's parent service.

This means that method builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original method's package name.

func NewMethod 

func NewMethod(name string, req, resp *RpcType) *MethodBuilder

NewMethod creates a new MethodBuilder for a method with the given name and request and response types.

func (*MethodBuilder) Build 

func (mtb *MethodBuilder) Build() (*desc.MethodDescriptor, error)

Build constructs a method descriptor based on the contents of this method builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*MethodBuilder) BuildDescriptor 

func (mtb *MethodBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a method descriptor based on the contents of this method builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*MethodBuilder) GetChildren 

func (mtb *MethodBuilder) GetChildren() []Builder

GetChildren returns nil, since methods cannot have child elements. It is present to satisfy the Builder interface.

func (*MethodBuilder) GetComments 

func (b *MethodBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*MethodBuilder) GetFile 

func (b *MethodBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*MethodBuilder) GetName 

func (b *MethodBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*MethodBuilder) GetParent 

func (b *MethodBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*MethodBuilder) SetComments 

func (mtb *MethodBuilder) SetComments(c Comments) *MethodBuilder

SetComments sets the comments associated with the method. This method returns the method builder, for method chaining.

func (*MethodBuilder) SetName 

func (mtb *MethodBuilder) SetName(newName string) *MethodBuilder

SetName changes this method's name, returning the method builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*MethodBuilder) SetOptions 

func (mtb *MethodBuilder) SetOptions(options *dpb.MethodOptions) *MethodBuilder

SetOptions sets the method options for this method and returns the method, for method chaining.

func (*MethodBuilder) SetRequestType 

func (mtb *MethodBuilder) SetRequestType(t *RpcType) *MethodBuilder

SetRequestType changes the request type for the method and then returns the method builder, for method chaining.

func (*MethodBuilder) SetResponseType 

func (mtb *MethodBuilder) SetResponseType(t *RpcType) *MethodBuilder

SetResponseType changes the response type for the method and then returns the method builder, for method chaining.

func (*MethodBuilder) TrySetName 

func (mtb *MethodBuilder) TrySetName(newName string) error

TrySetName changes this method's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent service builder already has a method with the given name.

type OneOfBuilder 

type OneOfBuilder struct {
	Options *dpb.OneofOptions
	// contains filtered or unexported fields
}

OneOfBuilder is a builder used to construct a desc.OneOfDescriptor. A one-of builder *must* be added to a message before calling its Build() method.

To create a new OneOfBuilder, use NewOneOf.

func FromOneOf 

func FromOneOf(ood *desc.OneOfDescriptor) (*OneOfBuilder, error)

FromOneOf returns a OneOfBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given one-of that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the one-of descriptor's parent message.

This means that one-of builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original one-of's package name.

This function returns an error if the given descriptor is synthetic.

func NewOneOf 

func NewOneOf(name string) *OneOfBuilder

NewOneOf creates a new OneOfBuilder for a one-of with the given name.

func (*OneOfBuilder) AddChoice 

func (oob *OneOfBuilder) AddChoice(flb *FieldBuilder) *OneOfBuilder

AddChoice adds the given field to this one-of. If an error prevents the field from being added, this method panics. If the given field is an extension, this method panics. If the given field is a group or map field or if it is not optional (e.g. it is required or repeated), this method panics. This returns the one-of builder, for method chaining.

func (*OneOfBuilder) Build 

func (oob *OneOfBuilder) Build() (*desc.OneOfDescriptor, error)

Build constructs a one-of descriptor based on the contents of this one-of builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*OneOfBuilder) BuildDescriptor 

func (oob *OneOfBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a one-of descriptor based on the contents of this one-of builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*OneOfBuilder) GetChildren 

func (oob *OneOfBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this one-of builder. These will be choices for the one-of, each of which will be a field builder.

func (*OneOfBuilder) GetChoice 

func (oob *OneOfBuilder) GetChoice(name string) *FieldBuilder

GetChoice returns the field with the given name. If no such field exists in the one-of, nil is returned.

func (*OneOfBuilder) GetComments 

func (b *OneOfBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*OneOfBuilder) GetFile 

func (b *OneOfBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*OneOfBuilder) GetName 

func (b *OneOfBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*OneOfBuilder) GetParent 

func (b *OneOfBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*OneOfBuilder) RemoveChoice 

func (oob *OneOfBuilder) RemoveChoice(name string) *OneOfBuilder

RemoveChoice removes the field with the given name. If no such field exists in the one-of, this is a no-op. This returns the one-of builder, for method chaining.

func (*OneOfBuilder) SetComments 

func (oob *OneOfBuilder) SetComments(c Comments) *OneOfBuilder

SetComments sets the comments associated with the one-of. This method returns the one-of builder, for method chaining.

func (*OneOfBuilder) SetName 

func (oob *OneOfBuilder) SetName(newName string) *OneOfBuilder

SetName changes this one-of's name, returning the one-of builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*OneOfBuilder) SetOptions 

func (oob *OneOfBuilder) SetOptions(options *dpb.OneofOptions) *OneOfBuilder

SetOptions sets the one-of options for this one-of and returns the one-of, for method chaining.

func (*OneOfBuilder) TryAddChoice 

func (oob *OneOfBuilder) TryAddChoice(flb *FieldBuilder) error

TryAddChoice adds the given field to this one-of, returning any error that prevents the field from being added (such as a name collision with another element already added to the enclosing message). An error is returned if the given field is an extension field, a map or group field, or repeated or required.

func (*OneOfBuilder) TryRemoveChoice 

func (oob *OneOfBuilder) TryRemoveChoice(name string) bool

TryRemoveChoice removes the field with the given name and returns false if the one-of has no such field.

func (*OneOfBuilder) TrySetName 

func (oob *OneOfBuilder) TrySetName(newName string) error

TrySetName changes this one-of's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent message builder already has an element with the given name.

type RpcType 

type RpcType struct {
	IsStream bool
	// contains filtered or unexported fields
}

RpcType represents the type of an RPC request or response. The only allowed types are messages, but can be streams or unary messages.

Message types can reference a message builder. A type that refers to a built message descriptor is called an "imported" type.

To create an RpcType, see RpcTypeMessage and RpcTypeImportedMessage.

func RpcTypeImportedMessage 

func RpcTypeImportedMessage(md *desc.MessageDescriptor, stream bool) *RpcType

RpcTypeImportedMessage creates an RpcType that refers to the given message descriptor.

func RpcTypeMessage 

func RpcTypeMessage(mb *MessageBuilder, stream bool) *RpcType

RpcTypeMessage creates an RpcType that refers to the given message builder.

func (*RpcType) GetTypeName 

func (rt *RpcType) GetTypeName() string

GetTypeName returns the fully qualified name of the message type to which this RpcType refers.

type ServiceBuilder 

type ServiceBuilder struct {
	Options *dpb.ServiceOptions
	// contains filtered or unexported fields
}

ServiceBuilder is a builder used to construct a desc.ServiceDescriptor.

To create a new ServiceBuilder, use NewService.

func FromService 

func FromService(sd *desc.ServiceDescriptor) (*ServiceBuilder, error)

FromService returns a ServiceBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given service that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the service descriptor's parent file.

This means that service builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original service's package name.

func NewService 

func NewService(name string) *ServiceBuilder

NewService creates a new ServiceBuilder for a service with the given name.

func (*ServiceBuilder) AddMethod 

func (sb *ServiceBuilder) AddMethod(mtb *MethodBuilder) *ServiceBuilder

AddMethod adds the given method to this servuce. If an error prevents the method from being added, this method panics. This returns the service builder, for method chaining.

func (*ServiceBuilder) Build 

func (sb *ServiceBuilder) Build() (*desc.ServiceDescriptor, error)

Build constructs a service descriptor based on the contents of this service builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*ServiceBuilder) BuildDescriptor 

func (sb *ServiceBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a service descriptor based on the contents of this service builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*ServiceBuilder) GetChildren 

func (sb *ServiceBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this service builder. These will be the service's methods.

func (*ServiceBuilder) GetComments 

func (b *ServiceBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*ServiceBuilder) GetFile 

func (b *ServiceBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*ServiceBuilder) GetMethod 

func (sb *ServiceBuilder) GetMethod(name string) *MethodBuilder

GetMethod returns the method with the given name. If no such method exists in the service, nil is returned.

func (*ServiceBuilder) GetName 

func (b *ServiceBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*ServiceBuilder) GetParent 

func (b *ServiceBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*ServiceBuilder) RemoveMethod 

func (sb *ServiceBuilder) RemoveMethod(name string) *ServiceBuilder

RemoveMethod removes the method with the given name. If no such method exists in the service, this is a no-op. This returns the service builder, for method chaining.

func (*ServiceBuilder) SetComments 

func (sb *ServiceBuilder) SetComments(c Comments) *ServiceBuilder

SetComments sets the comments associated with the service. This method returns the service builder, for method chaining.

func (*ServiceBuilder) SetName 

func (sb *ServiceBuilder) SetName(newName string) *ServiceBuilder

SetName changes this service's name, returning the service builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*ServiceBuilder) SetOptions 

func (sb *ServiceBuilder) SetOptions(options *dpb.ServiceOptions) *ServiceBuilder

SetOptions sets the service options for this service and returns the service, for method chaining.

func (*ServiceBuilder) TryAddMethod 

func (sb *ServiceBuilder) TryAddMethod(mtb *MethodBuilder) error

TryAddMethod adds the given field to this service, returning any error that prevents the field from being added (such as a name collision with another method already added to the service).

func (*ServiceBuilder) TryRemoveMethod 

func (sb *ServiceBuilder) TryRemoveMethod(name string) bool

TryRemoveMethod removes the method with the given name and returns false if the service has no such method.

func (*ServiceBuilder) TrySetName 

func (sb *ServiceBuilder) TrySetName(newName string) error

TrySetName changes this service's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent file builder already has an element with the given name.

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.