bufimageutil

Documentation

Index

• Variables
• func FilterImage(image bufimage.Image, options ...ImageFilterOption) (bufimage.Image, error)
• func FreeMessageRangeStrings(ctx context.Context, filePaths []string, image bufimage.Image) ([]string, error)
• func StripSourceRetentionOptions(image bufimage.Image) (bufimage.Image, error)
• type ImageFilterOption
  • func WithAllowIncludeOfImportedType() ImageFilterOption
  • func WithExcludeCustomOptions() ImageFilterOption
  • func WithExcludeKnownExtensions() ImageFilterOption
  • func WithExcludeTypes(typeNames ...string) ImageFilterOption
  • func WithIncludeTypes(typeNames ...string) ImageFilterOption
  • func WithMutateInPlace() 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 FilterImage

func FilterImage(image bufimage.Image, options ...ImageFilterOption) (bufimage.Image, error)

FilterImage returns a minimal image containing only the descriptors required to define the set of types provided by the filter options. If no filter options are provided, the original image is returned.

The filtered image will contain only the files that contain the definitions of the specified types, and their transitive dependencies. If a file is no longer required, it will be removed from the image. Only the minimal set of types required to define the specified types will be included in the filtered image.

Excluded types and options are not included in the filtered image. If an included type transitively depends on the excluded type, the descriptor will be altered to remove the dependency.

This returns a new bufimage.Image that is a shallow copy of the underlying [descriptorpb.FileDescriptorProto]s of the original. The new image may therefore share state with the original image, so it should not be modified. If the original image is no longer needed, it should be discarded. To mutate the original image, use the WithMutateInPlace option. Otherwise, to avoid sharing of state clone the image before filtering.

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 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 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 WithAllowIncludeOfImportedType

func WithAllowIncludeOfImportedType() ImageFilterOption

WithAllowIncludeOfImportedType returns an option for ImageFilteredByTypesWithOptions that allows a named included type to be in an imported file or module. Without this option, only types defined directly in the image to be filtered are allowed. Excluded types are always allowed to be in imported files or modules.

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.

func WithExcludeTypes

func WithExcludeTypes(typeNames ...string) ImageFilterOption

WithExcludeTypes returns an option for ImageFilteredByTypesWithOptions that specifies the set of types that should be excluded from the filtered image.

May be provided multiple times. The type names should be fully qualified. For example, "google.protobuf.Any" or "buf.validate". Types may be nested, and can be any package, message, enum, extension, service or method name.

If the type does not exist in the image, an error wrapping ErrImageFilterTypeNotFound will be returned.

func WithIncludeTypes

func WithIncludeTypes(typeNames ...string) ImageFilterOption

WithIncludeTypes returns an option for ImageFilteredByTypesWithOptions that specifies the set of types that should be included in the filtered image.

May be provided multiple times. The type names should be fully qualified. For example, "google.protobuf.Any" or "buf.validate". Types may be nested, and can be any package, message, enum, extension, service or method name.

If the type does not exist in the image, an error wrapping ErrImageFilterTypeNotFound will be returned.

func WithMutateInPlace

func WithMutateInPlace() ImageFilterOption

WithMutateInPlace returns an option for ImageFilteredByTypesWithOptions that specifies that the filtered image should be mutated in place. This option is useful when the unfiltered image is no longer needed and the caller wants to avoid the overhead of copying the image.