bufimageutil

Documentation

Index

• Variables
• func FreeMessageRangeStrings(ctx context.Context, filePaths []string, image bufimage.Image) ([]string, error)
• func ImageFilteredByTypes(image bufimage.Image, types ...string) (bufimage.Image, error)
• func ImageFilteredByTypesWithOptions(image bufimage.Image, types []string, opts ...ImageFilterOption) (bufimage.Image, error)
• func StripSourceRetentionOptions(image bufimage.Image) (bufimage.Image, error)
• type ImageFilterOption
  • func WithAllowFilterByImportedType() ImageFilterOption
  • func WithExcludeCustomOptions() ImageFilterOption
  • func WithExcludeKnownExtensions() ImageFilterOption

Variables

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

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

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 StripSourceRetentionOptions

func StripSourceRetentionOptions(image bufimage.Image) (bufimage.Image, error)

StripSourceRetentionOptions strips any options with a retention of "source" from the descriptors in the given image. The image is not mutated but instead a new image is returned. The returned image may share state with the original.

Types

type ImageFilterOption

type ImageFilterOption func(*imageFilterOptions)

ImageFilterOption is an option that can be passed to ImageFilteredByTypesWithOptions.

func WithAllowFilterByImportedType

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

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

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.