bufmodule

package
v0.44.0 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2021 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DocumentationFilePath defines the path to the documentation file, relative to the root of the module.
	DocumentationFilePath = "buf.md"
	// MainBranch is the name of the branch created for every repository.
	// This is the default branch used if no branch or commit is specified.
	MainBranch = "main"
)

Variables

This section is empty.

Functions

func IsCommitModuleReference added in v0.37.1 

func IsCommitModuleReference(moduleReference ModuleReference) bool

IsCommitModuleReference returns true if the ModuleReference references a commit.

If false, this means the ModuleReference references a branch or tag. Branch and tag disambiguation needs to be done server-side.

func IsCommitReference added in v0.44.0 

func IsCommitReference(reference string) bool

IsCommitReference returns whether the provided reference is a commit.

func ModuleDigestB1 

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

ModuleDigestB1 returns the b1 digest for the Module.

To create the module digest (SHA256):

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

func ModuleDigestB2 added in v0.44.0 

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

ModuleDigestB2 returns the b2 digest for the Module.

To create the module digest (SHA256):

  1. For every file in the module (sorted lexicographically by path): a. Add the file path b. Add the file contents
  2. Add the dependency commits (sorted lexicographically by remote/owner/repository/commit)
  3. Produce the final digest by URL-base64 encoding the summed bytes and prefixing it with the digest prefix

func ModulePinEqual added in v0.34.0 

func ModulePinEqual(a ModulePin, b ModulePin) bool

ModulePinEqual returns true if a equals b.

func ModuleReferenceEqual added in v0.34.0 

func ModuleReferenceEqual(a ModuleReference, b ModuleReference) bool

ModuleReferenceEqual 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. This copies external paths if the WriteBucket supports setting of external paths.

func ModuleToProtoModule 

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

ModuleToProtoModule converts the Module to a proto Module.

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

func NewProtoModulePinForModulePin added in v0.34.0 

func NewProtoModulePinForModulePin(modulePin ModulePin) *modulev1alpha1.ModulePin

NewProtoModulePinForModulePin returns a new proto ModulePin for the given ModulePin.

func NewProtoModulePinsForModulePins added in v0.34.0 

func NewProtoModulePinsForModulePins(modulePins ...ModulePin) []*modulev1alpha1.ModulePin

NewProtoModulePinsForModulePins maps the given module pins into the protobuf representation.

func NewProtoModuleReferenceForModuleReference added in v0.34.0 

func NewProtoModuleReferenceForModuleReference(moduleReference ModuleReference) *modulev1alpha1.ModuleReference

NewProtoModuleReferenceForModuleReference returns a new proto ModuleReference for the given ModuleReference.

func NewProtoModuleReferencesForModuleReferences added in v0.34.0 

func NewProtoModuleReferencesForModuleReferences(moduleReferences ...ModuleReference) []*modulev1alpha1.ModuleReference

NewProtoModuleReferencesForModuleReferences maps the given module references into the protobuf representation.

func PutModuleDependencyModulePinsToBucket added in v0.34.0 

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

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

func SortModulePins added in v0.34.0 

func SortModulePins(modulePins []ModulePin)

SortModulePins sorts the ModulePins.

func TargetModuleFilesToBucket added in v0.30.1 

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

TargetModuleFilesToBucket writes the target files of the given Module to the WriteBucket.

This does not write the buf.lock file. This copies external paths if the WriteBucket supports setting of external paths.

func ValidateBranch added in v0.36.0 

func ValidateBranch(branch string) error

ValidateBranch verifies the given repository branch is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateCommit added in v0.34.0 

func ValidateCommit(commit string) error

ValidateCommit verifies the given commit is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

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 ValidateModuleFilePath added in v0.39.0 

func ValidateModuleFilePath(path string) error

ValidateModuleFilePath validates that the module file path is not empty. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateModulePinsUniqueByIdentity added in v0.34.0 

func ValidateModulePinsUniqueByIdentity(modulePins []ModulePin) error

ValidateModulePinsUniqueByIdentity returns an error if the module pins contain any duplicates.

This only checks remote, owner, repository.

func ValidateModuleReferencesUniqueByIdentity added in v0.34.0 

func ValidateModuleReferencesUniqueByIdentity(moduleReferences []ModuleReference) error

ValidateModuleReferencesUniqueByIdentity returns an error if the module references contain any duplicates.

This only checks remote, owner, repository.

func ValidateOrganization added in v0.34.0 

func ValidateOrganization(organization string) error

ValidateOrganization verifies the given organization name is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateOwner added in v0.34.0 

func ValidateOwner(owner string, ownerType string) error

ValidateOwner verifies the given owner name is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateProtoModule added in v0.24.0 

func ValidateProtoModule(protoModule *modulev1alpha1.Module) error

ValidateProtoModule verifies the given module is well-formed. It performs client-side validation only, and is limited to fields we do not think will change in the future.

func ValidateProtoModulePin added in v0.34.0 

func ValidateProtoModulePin(protoModulePin *modulev1alpha1.ModulePin) error

ValidateProtoModulePin verifies the given module pin is well-formed. It performs client-side validation only, and is limited to fields we do not think will change in the future.

func ValidateProtoModuleReference added in v0.34.0 

func ValidateProtoModuleReference(protoModuleReference *modulev1alpha1.ModuleReference) error

ValidateProtoModuleReference verifies the given module reference is well-formed. It performs client-side validation only, and is limited to fields we do not think will change in the future.

func ValidateReference added in v0.37.1 

func ValidateReference(reference string) error

ValidateReference validates that the given ModuleReference reference is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateRepository added in v0.34.0 

func ValidateRepository(repository string) error

ValidateRepository verifies the given repository name is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateTag added in v0.40.0 

func ValidateTag(tag string) error

ValidateTag verifies the given tag is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

func ValidateUser added in v0.34.0 

func ValidateUser(user string) error

ValidateUser verifies the given user name is well-formed. It performs client-side validation only, and is limited to properties we do not think will change in the future.

Types

type FileInfo added in v0.39.0 

type FileInfo interface {
	bufcore.FileInfo

	// ModuleIdentity is the module that this file came from.
	//
	// Note this *can* be nil if we did not build from a named module.
	// All code must assume this can be nil.
	// Note that nil checking should work since the backing type is always a pointer.
	ModuleIdentity() ModuleIdentity
	// Commit is the commit for the module that this file came from.
	//
	// This will only be set if ModuleIdentity is set. but may not be set
	// even if ModuleIdentity is set, that is commit is optional information
	// even if we know what module this file came from.
	Commit() string
	// contains filtered or unexported methods
}

FileInfo contains module file info.

func NewFileInfo added in v0.39.0 

func NewFileInfo(
	coreFileInfo bufcore.FileInfo,
	moduleIdentity ModuleIdentity,
	commit string,
) FileInfo

NewFileInfo returns a new FileInfo.

TODO: we should make moduleIdentity and commit options. TODO: we don't validate commit

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) ([]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) ([]FileInfo, error)
	// GetModuleFile gets the source file for the given path.
	//
	// Returns storage.IsNotExist error if the file does not exist.
	GetModuleFile(ctx context.Context, path string) (ModuleFile, error)
	// DependencyModulePins gets the dependency ModulePins.
	//
	// The returned ModulePins are sorted by remote, owner, repository, branch, commit, and then digest.
	// The returned ModulePins are unique by remote, owner, repository.
	//
	// This includes all transitive dependencies.
	DependencyModulePins() []ModulePin
	// Documentation gets the contents of the module documentation file, buf.md and returns the string representation.
	// This may return an empty string if the documentation file does not exist.
	Documentation() string
	// 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 --path 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 or directory 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.

Note that this will result in TargetFileInfos containing only these paths, and not any imports. Imports, and non-targeted files, are still available via SourceFileInfos.

func ModuleWithTargetPathsAllowNotExist 

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

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

Note that this will result in TargetFileInfos containing only these paths, and not any imports. Imports, and non-targeted files, are still available via SourceFileInfos.

func NewModuleForBucket 

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

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

func NewModuleForBucketWithDependencyModulePins added in v0.34.0 

func NewModuleForBucketWithDependencyModulePins(
	ctx context.Context,
	readBucket storage.ReadBucket,
	dependencyModulePins []ModulePin,
	options ...ModuleOption,
) (Module, error)

NewModuleForBucketWithDependencyModulePins 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 *modulev1alpha1.Module,
	options ...ModuleOption,
) (Module, error)

NewModuleForProto returns a new Module for the given proto Module.

type ModuleFile 

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

ModuleFile is a module file.

type ModuleFileSet 

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

ModuleFileSet is a Protobuf module file set.

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

TODO: we should not have ModuleFileSet inherit from Module, this is confusing

func NewModuleFileSet 

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

NewModuleFileSet returns a new ModuleFileSet.

type ModuleIdentity added in v0.34.0 

type ModuleIdentity interface {
	ModuleOwner

	Repository() string

	// IdentityString is the string remote/owner/repository.
	IdentityString() string
	// contains filtered or unexported methods
}

ModuleIdentity is a module identity.

It just contains remote, owner, repository.

This is shared by ModuleReference and ModulePin.

func ModuleIdentityForString added in v0.34.0 

func ModuleIdentityForString(path string) (ModuleIdentity, error)

ModuleIdentityForString returns a new ModuleIdentity for the given string.

This parses the path in the form remote/owner/repository

TODO: we may want to add a special error if we detect / or @ as this may be a common mistake.

func NewModuleIdentity added in v0.34.0 

func NewModuleIdentity(
	remote string,
	owner string,
	repository string,
) (ModuleIdentity, error)

NewModuleIdentity returns a new ModuleIdentity.

type ModuleOption added in v0.39.0 

type ModuleOption func(*module)

ModuleOption is used to construct Modules.

func ModuleWithModuleIdentity added in v0.44.0 

func ModuleWithModuleIdentity(moduleIdentity ModuleIdentity) ModuleOption

ModuleWithModuleIdentity is used to construct a Module with a ModuleIdentity.

func ModuleWithModuleIdentityAndCommit added in v0.44.0 

func ModuleWithModuleIdentityAndCommit(moduleIdentity ModuleIdentity, commit string) ModuleOption

ModuleWithModuleIdentityAndCommit is used to construct a Module with a ModuleIdentity and commit.

type ModuleOwner added in v0.37.0 

type ModuleOwner interface {
	Remote() string
	Owner() string
	// contains filtered or unexported methods
}

ModuleOwner is a module owner.

It just contains remote, owner.

This is shared by ModuleIdentity.

func ModuleOwnerForString added in v0.37.0 

func ModuleOwnerForString(path string) (ModuleOwner, error)

ModuleOwnerForString returns a new ModuleOwner for the given string.

This parses the path in the form remote/owner.

func NewModuleOwner added in v0.37.0 

func NewModuleOwner(
	remote string,
	owner string,
) (ModuleOwner, error)

NewModuleOwner returns a new ModuleOwner.

type ModulePin added in v0.34.0 

type ModulePin interface {
	ModuleIdentity

	// Prints remote/owner/repository:commit, which matches ModuleReference
	fmt.Stringer

	// all of these will be set
	Branch() string
	Commit() string
	Digest() string
	CreateTime() time.Time
	// contains filtered or unexported methods
}

ModulePin is a module pin.

It references a specific point in time of a Module.

Note that a commit does this itself, but we want all this information. This is what is stored in a buf.lock file.

func NewModulePin added in v0.34.0 

func NewModulePin(
	remote string,
	owner string,
	repository string,
	branch string,
	commit string,
	digest string,
	createTime time.Time,
) (ModulePin, error)

NewModulePin returns a new validated ModulePin.

func NewModulePinForProto added in v0.34.0 

func NewModulePinForProto(protoModulePin *modulev1alpha1.ModulePin) (ModulePin, error)

NewModulePinForProto returns a new ModulePin for the given proto ModulePin.

func NewModulePinsForProtos added in v0.34.0 

func NewModulePinsForProtos(protoModulePins ...*modulev1alpha1.ModulePin) ([]ModulePin, error)

NewModulePinsForProtos maps the Protobuf equivalent into the internal representation.

type ModuleReader 

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

ModuleReader reads resolved modules.

func NewNopModuleReader 

func NewNopModuleReader() ModuleReader

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

type ModuleReference added in v0.34.0 

type ModuleReference interface {
	ModuleIdentity

	// Prints either remote/owner/repository:{branch,commit}
	fmt.Stringer

	// Either branch, tag, or commit
	Reference() string
	// contains filtered or unexported methods
}

ModuleReference is a module reference.

It references either a branch, tag, or a commit. Note that since commits belong to branches, we can deduce the branch from the commit when resolving.

func ModuleReferenceForString added in v0.34.0 

func ModuleReferenceForString(path string) (ModuleReference, error)

ModuleReferenceForString returns a new ModuleReference for the given string. If a branch or commit is not provided, the "main" branch is used.

This parses the path in the form remote/owner/repository{:branch,:commit}.

func NewModuleReference added in v0.37.1 

func NewModuleReference(
	remote string,
	owner string,
	repository string,
	reference string,
) (ModuleReference, error)

NewModuleReference returns a new validated ModuleReference.

func NewModuleReferenceForProto added in v0.34.0 

func NewModuleReferenceForProto(protoModuleReference *modulev1alpha1.ModuleReference) (ModuleReference, error)

NewModuleReferenceForProto returns a new ModuleReference for the given proto ModuleReference.

func NewModuleReferencesForProtos added in v0.34.0 

func NewModuleReferencesForProtos(protoModuleReferences ...*modulev1alpha1.ModuleReference) ([]ModuleReference, error)

NewModuleReferencesForProtos maps the Protobuf equivalent into the internal representation.

type ModuleResolver added in v0.25.0 

type ModuleResolver interface {
	// GetModulePin resolves the provided ModuleReference to a ModulePin.
	//
	// Returns an error that fufills storage.IsNotExist if the named Module does not exist.
	GetModulePin(ctx context.Context, moduleReference ModuleReference) (ModulePin, 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 Workspace added in v0.42.0 

type Workspace interface {
	// GetModule gets the module identified by the given ModuleIdentity.
	GetModule(moduleIdentity ModuleIdentity) (Module, bool)
	// GetModules returns all of the modules found in the workspace.
	GetModules() []Module
}

Workspace represents a module workspace.

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.