bufmodule

package
v0.27.1 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2020 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const LockFilePath = "buf.lock"

LockFilePath defines the path to the lock file, relative to the root of the module.

Variables

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

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

Functions

func IsNoDigestError 

func IsNoDigestError(err error) bool

IsNoDigestError returns whether the error provided, or any error wrapped by that error, is a NoDigest error.

func ModuleDigestB1 

func ModuleDigestB1(
	ctx context.Context,
	moduleVersion string,
	module Module,
) (string, error)

ModuleDigestB1 returns the b1 digest for the module and module name.

The digest on ModuleName must be unset. We might want an UnresolvedModuleName, need to see how this plays out. To create the module digest (SHA256):

  1. Add the string representation of the module version
  2. Add the dependency hashes (sorted lexicographically by the string representation)
  3. For every file in the module (sorted lexicographically by path):
  4. Add the file path
  5. Add the file contents
  6. Produce the final digest by URL-base64 encoding the summed bytes and prefixing it with the digest prefix

func ModuleNameEqual 

func ModuleNameEqual(a ModuleName, b ModuleName) bool

ModuleNameEqual returns true if a equals b.

func ModuleToBucket 

func ModuleToBucket(
	ctx context.Context,
	module Module,
	writeBucket storage.WriteBucket,
) error

ModuleToBucket writes the given Module to the WriteBucket.

This writes the sources and the buf.lock file.

func ModuleToProtoModule 

func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1.Module, error)

ModuleToProtoModule converts the Module to a proto Module.

This takes all Sources and puts them in the Module, not just Targets.

func NewNoDigestError 

func NewNoDigestError(moduleName ModuleName) error

NewNoDigestError returns a new error indicating that a module did not have a digest where required.

func NewProtoModuleNameForModuleName 

func NewProtoModuleNameForModuleName(moduleName ModuleName) *modulev1.ModuleName

NewProtoModuleNameForModuleName returns a new proto ModuleName for the given ModuleName.

func NewProtoModuleNamesForModuleNames 

func NewProtoModuleNamesForModuleNames(moduleNames ...ModuleName) []*modulev1.ModuleName

NewProtoModuleNamesForModuleNames maps the given module names into the protobuf representation.

func NewProtoModuleNamesForResolvedModuleNames added in v0.25.0 

func NewProtoModuleNamesForResolvedModuleNames(resolvedModuleNames ...ResolvedModuleName) []*modulev1.ModuleName

NewProtoModuleNamesForResolvedModuleNames maps the given module names into the protobuf representation.

func ValidateDigest added in v0.24.0 

func ValidateDigest(digest string) error

ValidateDigest verifies the given digest's prefix, decodes its base64 representation and checks the length of the encoded bytes.

func ValidateModuleDigest 

func ValidateModuleDigest(ctx context.Context, moduleName ModuleName, module Module) error

ValidateModuleDigest validates that the Module matches the digest on ModuleName.

The given ModuleName must have a digest.

This is just a convenience function.

func ValidateModuleNamesUnique 

func ValidateModuleNamesUnique(moduleNames []ModuleName) error

ValidateModuleNamesUnique returns an error if the module names contain any duplicates.

func ValidateOwnerName added in v0.24.0 

func ValidateOwnerName(ownerName string, ownerType string) error

ValidateOwnerName is used to validate owner names, i.e. usernames and organization names.

func ValidateProtoModule added in v0.24.0 

func ValidateProtoModule(protoModule *modulev1.Module) error

ValidateProtoModule verifies the given module is well-formed.

func ValidateProtoModuleName added in v0.24.0 

func ValidateProtoModuleName(protoModuleName *modulev1.ModuleName) error

ValidateProtoModuleName verifies the given module name is well-formed.

func ValidateRepositoryName added in v0.24.0 

func ValidateRepositoryName(repositoryName string) error

ValidateRepositoryName verifies the given repository name is well-formed.

func ValidateRepositoryVersionName added in v0.24.0 

func ValidateRepositoryVersionName(versionName string) error

ValidateRepositoryVersionName verifies the given repository version name is well-formed.

func ValidateResolvedModuleNamesUnique added in v0.25.0 

func ValidateResolvedModuleNamesUnique(resolvedModuleNames []ResolvedModuleName) error

ValidateResolvedModuleNamesUnique returns an error if the module names contain any duplicates.

func WriteModuleDependenciesToBucket 

func WriteModuleDependenciesToBucket(ctx context.Context, writeBucket storage.WriteBucket, module Module) error

WriteModuleDependenciesToBucket writes the module dependencies to the write bucket in the form of a lock file.

Types

type Module 

type Module interface {
	// TargetFileInfos gets all FileInfos specified as target files. This is either
	// all the FileInfos belonging to the module, or those specified by ModuleWithTargetPaths().
	//
	// It does not include dependencies.
	//
	// The returned TargetFileInfos are sorted by path.
	TargetFileInfos(ctx context.Context) ([]bufcore.FileInfo, error)
	// SourceFileInfos gets all FileInfos belonging to the module.
	//
	// It does not include dependencies.
	//
	// The returned SourceFileInfos are sorted by path.
	SourceFileInfos(ctx context.Context) ([]bufcore.FileInfo, error)
	// GetFile gets the source file for the given path.
	//
	// Returns storage.IsNotExist error if the file does not exist.
	GetFile(ctx context.Context, path string) (ModuleFile, error)
	// Dependencies gets the dependency ModuleNames.
	//
	// The returned ModuleNames are sorted by remote, owner, repository, version, and then digest.
	Dependencies() []ResolvedModuleName
	// contains filtered or unexported methods
}

Module is a Protobuf module.

It contains the files for the sources, and the dependency names.

Terminology:

Targets (Modules and ModuleFileSets): 

Just the files specified to build. This will either be sources, or will be specific files
within sources, ie this is a subset of Sources. The difference between Targets and Sources happens
when i.e. the --file flag is used.

Sources (Modules and ModuleFileSets): 

The files with no dependencies. This is a superset of Targets and subset of All.

All (ModuleFileSets only): 

All files including dependencies. This is a superset of Sources.

func ModuleWithTargetPaths 

func ModuleWithTargetPaths(module Module, targetPaths []string) (Module, error)

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

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

func ModuleWithTargetPathsAllowNotExist 

func ModuleWithTargetPathsAllowNotExist(module Module, targetPaths []string) (Module, error)

ModuleWithTargetPathsAllowNotExist returns a new Module specified specifie file paths to build, but allows the specified paths to not exist.

func NewModuleForBucket 

func NewModuleForBucket(
	ctx context.Context,
	readBucket storage.ReadBucket,
) (Module, error)

NewModuleForBucket returns a new Module. It attempts reads dependencies from a lock file in the read bucket.

func NewModuleForBucketWithDependencies 

func NewModuleForBucketWithDependencies(
	ctx context.Context,
	readBucket storage.ReadBucket,
	dependencies []ResolvedModuleName,
) (Module, error)

NewModuleForBucketWithDependencies explicitly specifies the dependencies that should be used when creating the Module. The module names must be resolved and unique.

func NewModuleForProto 

func NewModuleForProto(
	ctx context.Context,
	protoModule *modulev1.Module,
) (Module, error)

NewModuleForProto returns a new Module for the given proto Module.

type ModuleFile 

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

ModuleFile is a file within a Root.

type ModuleFileSet 

type ModuleFileSet interface {
	// Note that GetFile will pull from All files instead of just Source Files!
	Module
	// AllFileInfos gets all FileInfos associated with the module, including depedencies.
	//
	// The returned FileInfos are sorted by path.
	AllFileInfos(ctx context.Context) ([]bufcore.FileInfo, error)
	// contains filtered or unexported methods
}

ModuleFileSet is a Protobuf module file set.

It contains the files for both targets, sources and dependencies.

func NewModuleFileSet 

func NewModuleFileSet(
	module Module,
	dependencies []Module,
) ModuleFileSet

NewModuleFileSet returns a new ModuleFileSet.

type ModuleName 

type ModuleName interface {
	fmt.Stringer

	// Required.
	Remote() string
	// Required.
	Owner() string
	// Required.
	Repository() string
	// Required.
	Version() string
	// Optional.
	Digest() string
	// contains filtered or unexported methods
}

ModuleName is a module name.

func ModuleNameForString 

func ModuleNameForString(path string) (ModuleName, error)

ModuleNameForString returns a new ModuleName for the given string.

This parses the path in the form remote/owner/repository/version[:digest]

func NewModuleName 

func NewModuleName(
	remote string,
	owner string,
	repository string,
	version string,
	digest string,
) (ModuleName, error)

NewModuleName returns a new validated ModuleName.

func NewModuleNameForProto 

func NewModuleNameForProto(protoModuleName *modulev1.ModuleName) (ModuleName, error)

NewModuleNameForProto returns a new ModuleName for the given proto ModuleName.

func NewModuleNamesForProtos 

func NewModuleNamesForProtos(protoModuleNames ...*modulev1.ModuleName) ([]ModuleName, error)

NewModuleNamesForProtos maps the Protobuf equivalent into the internal representation.

func UnresolvedModuleName 

func UnresolvedModuleName(moduleName ModuleName) (ModuleName, error)

UnresolvedModuleName returns the ModuleName without a digest.

This is just a convenience function.

type ModuleReader 

type ModuleReader interface {
	// GetModule gets the named Module.
	//
	// Returns an error that fufills storage.IsNotExist if the named Module does not exist.
	GetModule(ctx context.Context, moduleName ResolvedModuleName) (Module, error)
}

ModuleReader reads resolved modules.

func NewNopModuleReader 

func NewNopModuleReader() ModuleReader

NewNopModuleReader returns a new ModuleReader that always returns a storage.IsNotExist error.

type ModuleResolver added in v0.25.0 

type ModuleResolver interface {
	// ResolveModule resolves the provided ModuleName.
	//
	// Returns an error that fufills storage.IsNotExist if the named Module does not exist.
	ResolveModule(ctx context.Context, moduleName ModuleName) (ResolvedModuleName, error)
}

ModuleResolver resolves modules.

func NewNopModuleResolver added in v0.25.0 

func NewNopModuleResolver() ModuleResolver

NewNopModuleResolver returns a new ModuleResolver that always returns a storage.IsNotExist error.

type ResolvedModuleName added in v0.25.0 

type ResolvedModuleName interface {
	fmt.Stringer
	ModuleName
	// contains filtered or unexported methods
}

ResolvedModuleName represents a resolved module name, e.g. a module name with a digest.

func DeduplicateResolvedModuleNames added in v0.25.0 

func DeduplicateResolvedModuleNames(resolvedModuleNames []ResolvedModuleName) []ResolvedModuleName

DeduplicateResolvedModuleNames returns a deduplicated slice of resolved module names by selecting the first occurrence of a resolved module name based on the modules representation without the digest.

func NewResolvedModuleName added in v0.25.0 

func NewResolvedModuleName(
	remote string,
	owner string,
	repository string,
	version string,
	digest string,
) (ResolvedModuleName, error)

NewResolvedModuleName returns a new validated ResolvedModuleName.

func NewResolvedModuleNameForProto added in v0.25.0 

func NewResolvedModuleNameForProto(protoModuleName *modulev1.ModuleName) (ResolvedModuleName, error)

NewResolvedModuleNameForProto returns a new ResolvedModuleName for the given proto ModuleName.

func NewResolvedModuleNamesForProtos added in v0.25.0 

func NewResolvedModuleNamesForProtos(protoModuleNames ...*modulev1.ModuleName) ([]ResolvedModuleName, error)

NewResolvedModuleNamesForProtos maps the Protobuf equivalent into the internal representation.

func ResolvedModuleNameForModule 

func ResolvedModuleNameForModule(ctx context.Context, moduleName ModuleName, module Module) (ResolvedModuleName, error)

ResolvedModuleNameForModule returns a new validated ModuleName that uses the values from the given ModuleName and the digest from the Module.

The given ModuleName must not already have a digest.

This is just a convenience function.

func ResolvedModuleNameForString added in v0.25.0 

func ResolvedModuleNameForString(path string) (ResolvedModuleName, error)

ResolvedModuleNameForString returns a new ResolvedModuleName for the given string.

This parses the path in the form remote/owner/repository/version:digest

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.