bufcore

Documentation

Overview

Package bufcore contains core types.

Index

• Variables
• func ImageToCodeGeneratorRequest(image Image, parameter string) *pluginpb.CodeGeneratorRequest
• func ImageToFileDescriptorProtos(image Image) []*descriptorpb.FileDescriptorProto
• func ImageToFileDescriptorSet(image Image) *descriptorpb.FileDescriptorSet
• func ImageToProtoImage(image Image) *imagev1.Image
• type FileInfo
  • func NewFileInfo(path string, externalPath string, isImport bool) (FileInfo, error)
  • func NewFileInfoForObjectInfo(objectInfo storage.ObjectInfo, isImport bool) FileInfo
• type Image
  • func ImageByDir(image Image) ([]Image, error)
  • func ImageWithOnlyPaths(image Image, paths []string) (Image, error)
  • func ImageWithOnlyPathsAllowNotExist(image Image, paths []string) (Image, error)
  • func ImageWithoutImports(image Image) Image
  • func NewImage(imageFiles []ImageFile) (Image, error)
  • func NewImageForCodeGeneratorRequest(request *pluginpb.CodeGeneratorRequest) (Image, error)
  • func NewImageForProto(protoImage *imagev1.Image) (Image, error)
  • func NewMultiImage(images ...Image) (Image, error)
• type ImageFile
  • func NewImageFile(fileDescriptorProto *descriptorpb.FileDescriptorProto, externalPath string, ...) (ImageFile, error)
• type Module
  • func NewModule(readBucket storage.ReadBucket, options ...ModuleOption) (Module, error)
• type ModuleFile
• type ModuleOption
  • func ModuleWithImports(importReadBucket storage.ReadBucket) ModuleOption
  • func ModuleWithTargetPaths(targetPaths ...string) ModuleOption
  • func ModuleWithTargetPathsAllowNotExistOnWalk() ModuleOption

Variables

var ErrNoTargetFiles = errors.New("no .proto target files found")

ErrNoTargetFiles is the error returned if there are no target files found.

Functions

func ImageToCodeGeneratorRequest

func ImageToCodeGeneratorRequest(image Image, parameter string) *pluginpb.CodeGeneratorRequest

ImageToCodeGeneratorRequest returns a new CodeGeneratorRequest for the Image.

All non-imports are added as files to generate.

func ImageToFileDescriptorProtos

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

ImageToFileDescriptorProtos returns a 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

ImageToProtoImage returns a new ProtoImage for the Image.

Types

type FileInfo

type FileInfo interface {
	// Path is the path of the file relative to the root it is contained within.
	// This will be normalized, validated and never empty,
	// This will be unique within a given Image.
	Path() string

	//   Path: one/one.proto
	//   RootDirPath: proto
	//   ExternalPath: /foo/bar/proto/one/one.proto
	ExternalPath() string
	// IsImport returns true if this file is an import.
	IsImport() bool
	// contains filtered or unexported methods
}

FileInfo contains protobuf file info.

func NewFileInfo

func NewFileInfo(path string, externalPath string, isImport bool) (FileInfo, error)

NewFileInfo returns a new FileInfo.

If externalPath is empty, path is used.

func NewFileInfoForObjectInfo

func NewFileInfoForObjectInfo(objectInfo storage.ObjectInfo, isImport bool) FileInfo

NewFileInfoForObjectInfo returns a new FileInfo for the storage.ObjectInfo.

The same rules apply to ObjectInfos for paths as FileInfos so we do not need to validate.

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.
	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
	// contains filtered or unexported methods
}

Image is a buf 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 directoy'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,
) (Image, error)

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

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

func ImageWithOnlyPathsAllowNotExist

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

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

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: Consider checking the above, and if not, reordering the Files.

func NewImageForCodeGeneratorRequest

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

NewImageForCodeGeneratorRequest returns a new Image from a given CodeGeneratorRequest.

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

func NewImageForProto

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

NewImageForProto returns a new Image for the given proto Image.

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

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

func NewMultiImage

func NewMultiImage(images ...Image) (Image, error)

NewMultiImage returns a new Image for the given Images.

Reorders the ImageFiles to be in DAG order. Duplicates cannot exist across the Images.

type ImageFile

type ImageFile interface {
	FileInfo
	// Proto is the backing FileDescriptorProto for this File.
	//
	// This will never be nil.
	// The value Path() is equal to Proto.GetName() .
	// The value ImportPaths() is equal to Proto().GetDependency().
	Proto() *descriptorpb.FileDescriptorProto
	// ImportPaths returns the root relative file paths of the imports.
	//
	// The values will be normalized, validated, and never empty.
	// This is equal to Proto.GetDependency().
	ImportPaths() []string
	// contains filtered or unexported methods
}

ImageFile is a Protobuf file within an image.

func NewImageFile

func NewImageFile(
	fileDescriptorProto *descriptorpb.FileDescriptorProto,
	externalPath string,
	isImport bool,
) (ImageFile, error)

NewImageFile returns a new ImageFile.

If externalPath is empty, path is used.

type Module

type Module interface {
	// TargetFileInfos gets all FileRefs for the Module that should be built.
	//
	// This does not include imports, or if ModuleWithTargetPaths() was used, files
	// not specified with ModuleWithTargetPaths().
	TargetFileInfos(ctx context.Context) ([]FileInfo, error)
	// GetFile gets the file for the given path.
	//
	// Returns storage.IsNotExist error if the file does not exist.
	GetFile(ctx context.Context, path string) (ModuleFile, error)
	// GetFileInfo gets the FileInfo for the given path.
	//
	// This includes non-source FileInfos, i.e. imports and those not specified as
	// part of ModuleWithTargetPaths().
	//
	// Returns storage.IsNotExist error if the file does not exist.
	GetFileInfo(ctx context.Context, path string) (FileInfo, error)
	// contains filtered or unexported methods
}

Module is a Protobuf module.

func NewModule

func NewModule(readBucket storage.ReadBucket, options ...ModuleOption) (Module, error)

NewModule returns a new Module.

type ModuleFile

type ModuleFile interface {
	FileInfo
	io.ReadCloser
	// contains filtered or unexported methods
}

ModuleFile is a file within a Root.

type ModuleOption

type ModuleOption func(*module)

ModuleOption is an option for a new Module.

func ModuleWithImports

func ModuleWithImports(importReadBucket storage.ReadBucket) ModuleOption

ModuleWithImports returns a new ModuleOption that adds the given ReadBucket for imports.

This bucket CANNOT be the same or have overlap with the bucket given to NewModule.

func ModuleWithTargetPaths

func ModuleWithTargetPaths(targetPaths ...string) ModuleOption

ModuleWithTargetPaths returns a new ModuleOption that specifies specific file paths to build.

These paths must exist. These paths must be relative to any roots. These paths will be normalized and validated. Multiple calls to this option will override previous calls.

func ModuleWithTargetPathsAllowNotExistOnWalk

func ModuleWithTargetPathsAllowNotExistOnWalk() ModuleOption

ModuleWithTargetPathsAllowNotExistOnWalk returns a ModuleOption that says that the target paths specified with ModuleWithTargetPaths may not exist on TargetFileInfos calls.

GetFileInfo and GetFile will still operate as normal.