bufimageutil

package
v1.23.0 Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2023 License: Apache-2.0 Imports: 12 Imported by: 11

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrImageFilterTypeNotFound is returned from ImageFilteredByTypes when
	// a specified type cannot be found in an image.
	ErrImageFilterTypeNotFound = errors.New("not found")

	// ErrImageFilterTypeIsImport is returned from ImageFilteredByTypes when
	// a specified type name is declared in a module dependency.
	ErrImageFilterTypeIsImport = errors.New("type declared in imported module")
)

Functions

func FreeMessageRangeStrings

func FreeMessageRangeStrings(
	ctx context.Context,
	filePaths []string,
	image bufimage.Image,
) ([]string, error)

FreeMessageRangeStrings gets the free MessageRange strings for the target files.

Recursive.

func ImageFilteredByTypes added in v1.1.0

func ImageFilteredByTypes(image bufimage.Image, types ...string) (bufimage.Image, error)

ImageFilteredByTypes returns a minimal image containing only the descriptors required to define those types. The resulting contains only files in which those descriptors and their transitive closure of required descriptors, with each file only contains the minimal required types and imports.

Although this returns a new bufimage.Image, it mutates the original image's underlying file's descriptorpb.FileDescriptorProto. So the old image should not continue to be used.

A descriptor is said to require another descriptor if the dependent descriptor is needed to accurately and completely describe that descriptor. For the following types that includes:

Messages
 - messages & enums referenced in fields
 - proto2 extension declarations for this field
 - custom options for the message, its fields, and the file in which the
   message is defined
 - the parent message if this message is a nested definition

Enums
 - Custom options used in the enum, enum values, and the file
   in which the message is defined
 - the parent message if this message is a nested definition

Services
 - request & response types referenced in methods
 - custom options for the service, its methods, and the file
   in which the message is defined

As an example, consider the following proto structure:

--- foo.proto ---
package pkg;
message Foo {
  optional Bar bar = 1;
  extensions 2 to 3;
}
message Bar { ... }
message Baz {
  other.Qux qux = 1 [(other.my_option).field = "buf"];
}
--- baz.proto ---
package other;
extend Foo {
  optional Qux baz = 2;
}
message Qux{ ... }
message Quux{ ... }
extend google.protobuf.FieldOptions {
  optional Quux my_option = 51234;
}

A filtered image for type `pkg.Foo` would include

files:      [foo.proto, bar.proto]
messages:   [pkg.Foo, pkg.Bar, other.Qux]
extensions: [other.baz]

A filtered image for type `pkg.Bar` would include

 files:      [foo.proto]
 messages:   [pkg.Bar]

A filtered image for type `pkg.Baz` would include
 files:      [foo.proto, bar.proto]
 messages:   [pkg.Baz, other.Quux, other.Qux]
 extensions: [other.my_option]

func ImageFilteredByTypesWithOptions added in v1.10.0

func ImageFilteredByTypesWithOptions(image bufimage.Image, types []string, opts ...ImageFilterOption) (bufimage.Image, error)

ImageFilteredByTypesWithOptions returns a minimal image containing only the descriptors required to define those types. See ImageFilteredByTypes for more details. This version allows for customizing the behavior with options.

func NewInputFiles

func NewInputFiles(imageFiles []bufimage.ImageFile) []protosource.InputFile

NewInputFiles converts the ImageFiles to InputFiles.

Since protosource is a pkg package, it cannot depend on bufmoduleref, which has the definition for bufmoduleref.ModuleIdentity, so we have our own interfaces for this in protosource. Given Go's type system, we need to do a conversion here.

Types

type ImageFilterOption added in v1.10.0

type ImageFilterOption func(*imageFilterOptions)

ImageFilterOption is an option that can be passed to ImageFilteredByTypesWithOptions.

func WithAllowFilterByImportedType added in v1.10.0

func WithAllowFilterByImportedType() ImageFilterOption

WithAllowFilterByImportedType returns an option for ImageFilteredByTypesWithOptions that allows a named filter type to be in an imported file or module. Without this option, only types defined directly in the image to be filtered are allowed.

func WithExcludeCustomOptions added in v1.10.0

func WithExcludeCustomOptions() ImageFilterOption

WithExcludeCustomOptions returns an option that will cause an image filtered via ImageFilteredByTypesWithOptions to *not* include custom options unless they are explicitly named in the list of filter types.

func WithExcludeKnownExtensions added in v1.10.0

func WithExcludeKnownExtensions() ImageFilterOption

WithExcludeKnownExtensions returns an option that will cause an image filtered via ImageFilteredByTypesWithOptions to *not* include the known extensions for included extendable messages unless they are explicitly named in the list of filter types.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL