bufimage

Documentation

Index

• func ImageToCodeGeneratorRequest(image Image, parameter string, compilerVersion *pluginpb.Version, ...) (*pluginpb.CodeGeneratorRequest, error)
• func ImageToFileDescriptorProtos(image Image) []*descriptorpb.FileDescriptorProto
• func ImageToFileDescriptorSet(image Image) *descriptorpb.FileDescriptorSet
• func ImageToProtoImage(image Image) (*imagev1.Image, error)
• func ImagesToCodeGeneratorRequests(images []Image, parameter string, compilerVersion *pluginpb.Version, ...) ([]*pluginpb.CodeGeneratorRequest, error)
• type BuildImageOption
  • func WithExcludeSourceCodeInfo() BuildImageOption
  • func WithNoParallelism() BuildImageOption
• type Image
  • func BuildImage(ctx context.Context, logger *slog.Logger, ...) (Image, error)
  • func CloneImage(image Image) (Image, error)
  • func ImageByDir(image Image) ([]Image, error)
  • func ImageWithOnlyPaths(image Image, paths []string, excludePaths []string) (Image, error)
  • func ImageWithOnlyPathsAllowNotExist(image Image, paths []string, excludePaths []string) (Image, error)
  • func ImageWithoutImports(image Image) Image
  • func NewImage(imageFiles []ImageFile) (Image, error)
  • func NewImageForCodeGeneratorRequest(request *pluginpb.CodeGeneratorRequest, options ...NewImageForProtoOption) (Image, error)
  • func NewImageForProto(protoImage *imagev1.Image, options ...NewImageForProtoOption) (Image, error)
• type ImageFile
  • func CloneImageFile(imageFile ImageFile) (ImageFile, error)
  • func ImageFileWithIsImport(imageFile ImageFile, isImport bool) ImageFile
  • func NewImageFile(fileDescriptor protodescriptor.FileDescriptor, ...) (ImageFile, error)
• type ImageFileInfo
  • func AppendWellKnownTypeImageFileInfos(ctx context.Context, wktBucket storage.ReadBucket, ...) ([]ImageFileInfo, error)
  • func ImageFileInfoForModuleFileInfo(moduleFileInfo bufmodule.FileInfo) ImageFileInfo
  • func ImageFileInfosWithOnlyTargetsAndTargetImports(ctx context.Context, wktBucket storage.ReadBucket, ...) ([]ImageFileInfo, error)
• type NewImageForProtoOption
  • func WithNoReparse() NewImageForProtoOption
  • func WithUnusedImportsComputation() NewImageForProtoOption

Functions

func ImageToCodeGeneratorRequest

func ImageToCodeGeneratorRequest(
	image Image,
	parameter string,
	compilerVersion *pluginpb.Version,
	includeImports bool,
	includeWellKnownTypes bool,
) (*pluginpb.CodeGeneratorRequest, error)

ImageToCodeGeneratorRequest returns a new CodeGeneratorRequest for the Image.

All non-imports are added as files to generate. If includeImports is set, all non-well-known-type imports are also added as files to generate. If includeWellKnownTypes is set, well-known-type imports are also added as files to generate. includeWellKnownTypes has no effect if includeImports is not set.

func ImageToFileDescriptorProtos

func ImageToFileDescriptorProtos(image Image) []*descriptorpb.FileDescriptorProto

ImageToFileDescriptorProtos returns the FileDescriptorProtos for the Image.

func ImageToFileDescriptorSet

func ImageToFileDescriptorSet(image Image) *descriptorpb.FileDescriptorSet

ImageToFileDescriptorSet returns a new FileDescriptorSet for the Image.

func ImageToProtoImage

func ImageToProtoImage(image Image) (*imagev1.Image, error)

ImageToProtoImage returns a new ProtoImage for the Image.

func ImagesToCodeGeneratorRequests

func ImagesToCodeGeneratorRequests(
	images []Image,
	parameter string,
	compilerVersion *pluginpb.Version,
	includeImports bool,
	includeWellKnownTypes bool,
) ([]*pluginpb.CodeGeneratorRequest, error)

ImagesToCodeGeneratorRequests converts the Images to CodeGeneratorRequests.

All non-imports are added as files to generate. If includeImports is set, all non-well-known-type imports are also added as files to generate. If includeImports is set, only one CodeGeneratorRequest will contain any given file as a FileToGenerate. If includeWellKnownTypes is set, well-known-type imports are also added as files to generate. includeWellKnownTypes has no effect if includeImports is not set.

Types

type BuildImageOption

type BuildImageOption func(*buildImageOptions)

BuildImageOption is an option for BuildImage.

func WithExcludeSourceCodeInfo

func WithExcludeSourceCodeInfo() BuildImageOption

WithExcludeSourceCodeInfo returns a new BuildImageOption that excludes sourceCodeInfo.

func WithNoParallelism

func WithNoParallelism() BuildImageOption

WithNoParallelism turns off parallelism for a build.

The default is to use thread.Parallelism().

Used for testing.

type Image

type Image interface {
	// Files are the files that comprise the image.
	//
	// This contains all files, including imports if available.
	// The returned files are in correct DAG order.
	//
	// All files that have the same ModuleFullName will also have the same commit, or no commit.
	// This is enforced at construction time.
	Files() []ImageFile
	// GetFile gets the file for the root relative file path.
	//
	// If the file does not exist, nil is returned.
	// The path is expected to be normalized and validated.
	// Note that all values of GetDependency() can be used here.
	GetFile(path string) ImageFile
	// Resolver returns a resolver backed by this image.
	Resolver() protoencoding.Resolver
	// contains filtered or unexported methods
}

Image is a buf image.

func BuildImage

func BuildImage(
	ctx context.Context,
	logger *slog.Logger,
	moduleReadBucket bufmodule.ModuleReadBucket,
	options ...BuildImageOption,
) (Image, error)

BuildImage runs compilation.

An error of type FileAnnotationSet may be returned. It is up to the caller to parse this if needed. FileAnnotations will use external file paths.

The given ModuleReadBucket must be self-contained.

A ModuleReadBucket is self-contained if it was constructed from ModuleSetToModuleReadBucketWithOnlyProtoFiles. This is likely the only way you should have a ModuleReadBucket that you pass to BuildImage.

The image will contain only files targeted by the input moduleReadBucket, those returned by bufmodule.GetTargetFileInfos.

func CloneImage

func CloneImage(image Image) (Image, error)

CloneImage returns a deep copy of the given image.

func ImageByDir

func ImageByDir(image Image) ([]Image, error)

ImageByDir returns multiple images that have non-imports split by directory.

That is, each Image will only contain a single directory's files as it's non-imports, along with all required imports for the files in that directory.

func ImageWithOnlyPaths

func ImageWithOnlyPaths(
	image Image,
	paths []string,
	excludePaths []string,
) (Image, error)

ImageWithOnlyPaths returns a copy of the Image that only includes the files with the given root relative file paths or directories.

Note that paths can be either files or directories - whether or not a path is included is a result of normalpath.EqualsOrContainsPath.

If a root relative file path does not exist, this errors.

func ImageWithOnlyPathsAllowNotExist

func ImageWithOnlyPathsAllowNotExist(
	image Image,
	paths []string,
	excludePaths []string,
) (Image, error)

ImageWithOnlyPathsAllowNotExist returns a copy of the Image that only includes the files with the given root relative file paths.

Note that paths can be either files or directories - whether or not a path is included is a result of normalpath.EqualsOrContainsPath.

If a root relative file path does not exist, this skips this path.

func ImageWithoutImports

func ImageWithoutImports(image Image) Image

ImageWithoutImports returns a copy of the Image without imports.

The backing Files are not copied.

func NewImage

func NewImage(imageFiles []ImageFile) (Image, error)

NewImage returns a new Image for the given ImageFiles.

The input ImageFiles are expected to be in correct DAG order! TODO FUTURE: Consider checking the above, and if not, reordering the Files. If imageFiles is empty, returns error

func NewImageForCodeGeneratorRequest

func NewImageForCodeGeneratorRequest(request *pluginpb.CodeGeneratorRequest, options ...NewImageForProtoOption) (Image, error)

NewImageForCodeGeneratorRequest returns a new Image from a given CodeGeneratorRequest.

The input Files are expected to be in correct DAG order! TODO FUTURE: Consider checking the above, and if not, reordering the Files.

func NewImageForProto

func NewImageForProto(protoImage *imagev1.Image, options ...NewImageForProtoOption) (Image, error)

NewImageForProto returns a new Image for the given proto Image.

The input Files are expected to be in correct DAG order! TODO FUTURE: Consider checking the above, and if not, reordering the Files.

TODO FUTURE: do we want to add the ability to do external path resolution here?

type ImageFile

type ImageFile interface {
	ImageFileInfo

	// FileDescriptorProto is the backing *descriptorpb.FileDescriptorProto for this File.
	//
	// This will never be nil.
	// The value Path() is equal to FileDescriptorProto().GetName() .
	FileDescriptorProto() *descriptorpb.FileDescriptorProto
	// IsSyntaxUnspecified will be true if the syntax was not explicitly specified.
	IsSyntaxUnspecified() bool
	// UnusedDependencyIndexes returns the indexes of the unused dependencies within
	// FileDescriptor.GetDependency().
	//
	// All indexes will be valid.
	// Will return nil if empty.
	UnusedDependencyIndexes() []int32
	// contains filtered or unexported methods
}

ImageFile is a Protobuf file within an image.

func CloneImageFile

func CloneImageFile(imageFile ImageFile) (ImageFile, error)

CloneImageFile returns a deep copy of the given image file.

func ImageFileWithIsImport

func ImageFileWithIsImport(imageFile ImageFile, isImport bool) ImageFile

ImageFileWithIsImport returns a copy of the ImageFile with the new ImageFile now marked as an import.

If the original ImageFile was already an import, this returns the original ImageFile.

func NewImageFile

func NewImageFile(
	fileDescriptor protodescriptor.FileDescriptor,
	moduleFullName bufmodule.ModuleFullName,
	commitID uuid.UUID,
	externalPath string,
	localPath string,
	isImport bool,
	isSyntaxUnspecified bool,
	unusedDependencyIndexes []int32,
) (ImageFile, error)

NewImageFile returns a new ImageFile.

If externalPath is empty, path is used.

TODO FUTURE: moduleFullName and commitID should be options since they are optional.

type ImageFileInfo

type ImageFileInfo interface {
	storage.ObjectInfo

	// ModuleFullName returns the full name of the Module that this ImageFile came from,
	// if the ImageFile came from a Module (as opposed to a serialized Protobuf message),
	// and if the ModuleFullName was known.
	//
	// May be nil. Callers should not rely on this value being present.
	ModuleFullName() bufmodule.ModuleFullName
	// CommitID returns the BSR ID of the Commit of the Module that this ImageFile came from.
	// if the ImageFile came from a Module (as opposed to a serialized Protobuf message), and
	// if the CommitID was known..
	//
	// May be empty, that is CommitID() == uuid.Nil may be true. Callers should not rely on this
	// value being present. If ModuleFullName is nil, this will always be empty.
	CommitID() uuid.UUID
	// Imports returns the imports for this ImageFile.
	Imports() ([]string, error)
	// IsImport returns true if this file is an import.
	IsImport() bool
	// contains filtered or unexported methods
}

ImageFileInfo is the minimal interface that can be fulfilled by both an ImageFile and (with conversion) a bufmodule.FileInfo.

This is used by ls-files.

func AppendWellKnownTypeImageFileInfos

func AppendWellKnownTypeImageFileInfos(
	ctx context.Context,
	wktBucket storage.ReadBucket,
	imageFileInfos []ImageFileInfo,
) ([]ImageFileInfo, error)

AppendWellKnownTypeImageFileInfos appends any Well-Known Types that are not already present in the input ImageFileInfos.

For example, if imageFileInfos contains "google/protobuf/timestamp.proto", the returned ImageFileInfos will have all the Well-Known Types except for "google/protobuf/timestamp.proto" appended.

This function uses the input wktBucket to determine what is a Well-Known Type. This bucket should contain all the Well-Known Types, and nothing else. This is used instead of using datawkt directly so that we can pass in a bucket backed by a cache on-disk with the Well-Known Types, and use its LocalPath information.

The appended Well-Known Types will be in sorted order by path, and will all be marked as imports.

func ImageFileInfoForModuleFileInfo

func ImageFileInfoForModuleFileInfo(moduleFileInfo bufmodule.FileInfo) ImageFileInfo

ImageFileInfoForModuleFileInfo returns a new ImageFileInfo for the bufmodule.FileInfo.

func ImageFileInfosWithOnlyTargetsAndTargetImports

func ImageFileInfosWithOnlyTargetsAndTargetImports(
	ctx context.Context,
	wktBucket storage.ReadBucket,
	imageFileInfos []ImageFileInfo,
) ([]ImageFileInfo, error)

ImageFileInfosWithOnlyTargetsAndTargetImports returns a new slice of ImageFileInfos that only contains the non-imports (ie targets), and the files that those non-imports themselves transitively import.

This is used in ls-files.

As an example, assume a module has files a.proto, b.proto, and it has a dependency on a module with files c.proto, d.proto. a.proto imports c.proto. We only target the module with a.proto, b.proto. The resulting slice should have a.proto, b.proto, c.proto, but not d.proto.

It is assumed that the input ImageFileInfos are self-contained, that is every import should be contained within the input, except for the Well-Known Types. If a Well-Known Type is imported and not present in the input, an ImageFileInfo for the Well-Known Type is automatically added to the result from the given bucket.

The result will be sorted by path.

type NewImageForProtoOption

type NewImageForProtoOption func(*newImageForProtoOptions)

NewImageForProtoOption is an option for use with NewImageForProto.

func WithNoReparse

func WithNoReparse() NewImageForProtoOption

WithNoReparse instructs NewImageForProto to skip the reparse step. The reparse step is usually needed when unmarshalling the image from bytes. It reconstitutes custom options, from unrecognized bytes to known extension fields.

func WithUnusedImportsComputation

func WithUnusedImportsComputation() NewImageForProtoOption

WithUnusedImportsComputation instructs NewImageForProto to compute unused imports for the files. These are usually computed by the compiler and stored in the image. But some sources of images may not include this information, so this option can be used to ensure that information is present in the image and accurate.

This option is NOT compatible with WithNoReparse: the image must be re-parsed for there to be adequate information for computing unused imports.