bufmodule

package
v0.54.1 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2021 License: Apache-2.0 Imports: 22 Imported by: 49

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 

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 

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 

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 

func ModulePinEqual(a ModulePin, b ModulePin) bool

ModulePinEqual returns true if a equals b.

func ModuleReferenceEqual 

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 

func NewProtoModulePinForModulePin(modulePin ModulePin) *modulev1alpha1.ModulePin

NewProtoModulePinForModulePin returns a new proto ModulePin for the given ModulePin.

func NewProtoModulePinsForModulePins 

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

NewProtoModulePinsForModulePins maps the given module pins into the protobuf representation.

func NewProtoModuleReferenceForModuleReference 

func NewProtoModuleReferenceForModuleReference(moduleReference ModuleReference) *modulev1alpha1.ModuleReference

NewProtoModuleReferenceForModuleReference returns a new proto ModuleReference for the given ModuleReference.

func NewProtoModuleReferencesForModuleReferences 

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

NewProtoModuleReferencesForModuleReferences maps the given module references into the protobuf representation.

func PutModuleDependencyModulePinsToBucket 

func PutModuleDependencyModulePinsToBucket(ctx context.Context, writeBucket storage.WriteBucket, pins []ModulePin) error

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

func SortModulePins 

func SortModulePins(modulePins []ModulePin)

SortModulePins sorts the ModulePins.

func TargetModuleFilesToBucket 

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 

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 

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 

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 

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 

func ValidateModulePinsUniqueByIdentity(modulePins []ModulePin) error

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

This only checks remote, owner, repository.

func ValidateModuleReferencesUniqueByIdentity 

func ValidateModuleReferencesUniqueByIdentity(moduleReferences []ModuleReference) error

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

This only checks remote, owner, repository.

func ValidateOrganization 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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
	// 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
	// WithIsImport returns this FileInfo with the given IsImport value.
	WithIsImport(isImport bool) FileInfo
	// contains filtered or unexported methods
}

FileInfo contains module file info.

func NewFileInfo 

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

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 

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 

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 

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 

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

NewModuleIdentity returns a new ModuleIdentity.

type ModuleOption 

type ModuleOption func(*module)

ModuleOption is used to construct Modules.

func ModuleWithModuleIdentity 

func ModuleWithModuleIdentity(moduleIdentity ModuleIdentity) ModuleOption

ModuleWithModuleIdentity is used to construct a Module with a ModuleIdentity.

func ModuleWithModuleIdentityAndCommit 

func ModuleWithModuleIdentityAndCommit(moduleIdentity ModuleIdentity, commit string) ModuleOption

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

type ModuleOwner 

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 

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 

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

NewModuleOwner returns a new ModuleOwner.

type ModulePin 

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 

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 

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

NewModulePinForProto returns a new ModulePin for the given proto ModulePin.

func NewModulePinsForProtos 

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 

type ModuleReference interface {
	ModuleIdentity

	// Prints either remote/owner/repository:{branch,commit}
	// If the reference is equal to MainBranch, prints remote/owner/repository.
	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 

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 

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

NewModuleReference returns a new validated ModuleReference.

func NewModuleReferenceForProto 

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

NewModuleReferenceForProto returns a new ModuleReference for the given proto ModuleReference.

func NewModuleReferencesForProtos 

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

NewModuleReferencesForProtos maps the Protobuf equivalent into the internal representation.

type ModuleResolver 

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 

func NewNopModuleResolver() ModuleResolver

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

type Workspace 

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.