Documentation ¶
Index ¶
- Constants
- func IsCommitModuleReference(moduleReference ModuleReference) bool
- func ModuleDigest(ctx context.Context, module Module) (string, error)
- func ModulePinEqual(a ModulePin, b ModulePin) bool
- func ModuleReferenceEqual(a ModuleReference, b ModuleReference) bool
- func ModuleToBucket(ctx context.Context, module Module, writeBucket storage.WriteBucket) error
- func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1alpha1.Module, error)
- func NewProtoModulePinForModulePin(modulePin ModulePin) *modulev1alpha1.ModulePin
- func NewProtoModulePinsForModulePins(modulePins ...ModulePin) []*modulev1alpha1.ModulePin
- func NewProtoModuleReferenceForModuleReference(moduleReference ModuleReference) *modulev1alpha1.ModuleReference
- func NewProtoModuleReferencesForModuleReferences(moduleReferences ...ModuleReference) []*modulev1alpha1.ModuleReference
- func PutModuleDependencyModulePinsToBucket(ctx context.Context, writeBucket storage.WriteBucket, module Module) error
- func SortModulePins(modulePins []ModulePin)
- func TargetModuleFilesToBucket(ctx context.Context, module Module, writeBucket storage.WriteBucket) error
- func ValidateBranch(branch string) error
- func ValidateCommit(commit string) error
- func ValidateDigest(digest string) error
- func ValidateModuleFilePath(path string) error
- func ValidateModuleMatchesDigest(ctx context.Context, module Module, modulePin ModulePin) error
- func ValidateModulePinsUniqueByIdentity(modulePins []ModulePin) error
- func ValidateModuleReferencesUniqueByIdentity(moduleReferences []ModuleReference) error
- func ValidateOrganization(organization string) error
- func ValidateOwner(owner string, ownerType string) error
- func ValidateProtoModule(protoModule *modulev1alpha1.Module) error
- func ValidateProtoModulePin(protoModulePin *modulev1alpha1.ModulePin) error
- func ValidateProtoModuleReference(protoModuleReference *modulev1alpha1.ModuleReference) error
- func ValidateReference(reference string) error
- func ValidateRepository(repository string) error
- func ValidateTag(tag string) error
- func ValidateUser(user string) error
- type FileInfo
- type Module
- func ModuleWithTargetPaths(module Module, targetPaths []string) (Module, error)
- func ModuleWithTargetPathsAllowNotExist(module Module, targetPaths []string) (Module, error)
- func NewModuleForBucket(ctx context.Context, readBucket storage.ReadBucket, options ...ModuleOption) (Module, error)
- func NewModuleForBucketWithDependencyModulePins(ctx context.Context, readBucket storage.ReadBucket, ...) (Module, error)
- func NewModuleForProto(ctx context.Context, protoModule *modulev1alpha1.Module, ...) (Module, error)
- type ModuleCommit
- type ModuleFile
- type ModuleFileSet
- type ModuleIdentity
- type ModuleOption
- type ModuleOwner
- type ModulePin
- func NewModulePin(remote string, owner string, repository string, branch string, commit string, ...) (ModulePin, error)
- func NewModulePinForProto(protoModulePin *modulev1alpha1.ModulePin) (ModulePin, error)
- func NewModulePinsForProtos(protoModulePins ...*modulev1alpha1.ModulePin) ([]ModulePin, error)
- type ModuleReader
- type ModuleReference
- func ModuleReferenceForString(path string) (ModuleReference, error)
- func NewModuleReference(remote string, owner string, repository string, reference string) (ModuleReference, error)
- func NewModuleReferenceForProto(protoModuleReference *modulev1alpha1.ModuleReference) (ModuleReference, error)
- func NewModuleReferencesForProtos(protoModuleReferences ...*modulev1alpha1.ModuleReference) ([]ModuleReference, error)
- type ModuleResolver
- type ObjectInfo
- type ReadBucket
- type Workspace
Constants ¶
const ( // LockFilePath defines the path to the lock file, relative to the root of the module. LockFilePath = "buf.lock" // 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 currently means the ModuleReference references a branch, but this will be expanded in the future to include tags. Branch and tag disambiguation needs to be done server-side.
func ModuleDigest ¶ added in v0.34.0
ModuleDigest returns the b1 digest for the Module.
To create the module digest (SHA256):
- For every file in the module (sorted lexicographically by path): a. Add the file path b. Add the file contents
- Add the dependency hashes (sorted lexicographically by the string representation)
- 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
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 ¶
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 ¶
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
ValidateBranch verifies the given repository branch is well-formed.
func ValidateCommit ¶ added in v0.34.0
ValidateCommit verifies the given commit is well-formed.
func ValidateDigest ¶ added in v0.24.0
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 ValidateModuleMatchesDigest ¶ added in v0.34.0
ValidateModuleMatchesDigest validates that the Module matches the digest.
This is just a convenience function.
func ValidateModulePinsUniqueByIdentity ¶ added in v0.34.0
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
ValidateOrganization verifies the given organization name is well-formed.
func ValidateOwner ¶ added in v0.34.0
ValidateOwner verifies the given owner name is well-formed.
func ValidateProtoModule ¶ added in v0.24.0
func ValidateProtoModule(protoModule *modulev1alpha1.Module) error
ValidateProtoModule verifies the given module is well-formed.
func ValidateProtoModulePin ¶ added in v0.34.0
func ValidateProtoModulePin(protoModulePin *modulev1alpha1.ModulePin) error
ValidateProtoModulePin verifies the given module pin is well-formed.
func ValidateProtoModuleReference ¶ added in v0.34.0
func ValidateProtoModuleReference(protoModuleReference *modulev1alpha1.ModuleReference) error
ValidateProtoModuleReference verifies the given module reference is well-formed.
func ValidateReference ¶ added in v0.37.1
ValidateReference validates that the given ModuleReference reference is well-formed.
func ValidateRepository ¶ added in v0.34.0
ValidateRepository verifies the given repository name is well-formed.
func ValidateTag ¶ added in v0.40.0
ValidateTag verifies the given tag is well-formed.
func ValidateUser ¶ added in v0.34.0
ValidateUser verifies the given user name is well-formed.
Types ¶
type FileInfo ¶ added in v0.39.0
type FileInfo interface { bufcore.FileInfo // Note this *can* be nil if we did not build from a named module. // All code must assume this can be nil. // nil checking should work since the backing type is always a pointer ModuleCommit() ModuleCommit // contains filtered or unexported methods }
FileInfo contains module file info.
func NewFileInfo ¶ added in v0.39.0
func NewFileInfo( coreFileInfo bufcore.FileInfo, moduleCommit ModuleCommit, ) FileInfo
NewFileInfo returns a new FileInfo.
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 ¶
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 ¶
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 ModuleCommit ¶ added in v0.42.0
type ModuleCommit interface { ModuleIdentity // Prints remote/owner/repository:commit fmt.Stringer Commit() string // contains filtered or unexported methods }
ModuleCommit is a module commit.
Note that since commits belong to branches, we can deduce the branch from the commit.
func NewModuleCommit ¶ added in v0.42.0
func NewModuleCommit( remote string, owner string, repository string, commit string, ) (ModuleCommit, error)
NewModuleCommit returns a new validated ModuleCommit.
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:{branch,commit}.
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(*moduleOptions)
ModuleOption is used to construct Modules.
func ModuleWithModuleCommit ¶ added in v0.42.0
func ModuleWithModuleCommit(moduleCommit ModuleCommit) ModuleOption
ModuleWithModuleCommit is used to construct a Module with a ModuleCommit.
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, or a commit. Only one of Branch and Commit will be set. 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 ObjectInfo ¶ added in v0.39.0
type ObjectInfo interface { storage.ObjectInfo // ModuleCommit gets this object's ModuleCommit, if any. ModuleCommit() ModuleCommit }
ObjectInfo extends the storage.ObjectInfo interface with information specific to Modules.
TODO: This type is currently not used outside of this package, so we could instead rely on just the concrete struct type. This includes an interface for consistency, and exports it to prevent name collisions.
type ReadBucket ¶ added in v0.39.0
type ReadBucket interface { storage.ReadBucket // StatModuleFile gets info in the object, including info // specific to the file's module. // // Returns ErrNotExist if the path does not exist, other error // if there is a system error. StatModuleFile(ctx context.Context, path string) (ObjectInfo, error) // WalkModuleFiles walks the bucket with the prefix, calling f on // each path. If the prefix doesn't exist, this is a no-op. // // Note that foo/barbaz will not be called for foo/bar, but will // be called for foo/bar/baz. // // All paths given to f are normalized and validated. // If f returns error, Walk will stop short and return this error. // Returns other error on system error. WalkModuleFiles(ctx context.Context, prefix string, f func(ObjectInfo) error) error }
ReadBucket extends the storage.ReadBucket interface with information specific to Modules.
TODO: This type is currently not used outside of this package, so we could instead rely on just the concrete struct type. This includes an interface for consistency, and exports it to prevent name collisions.
func NewReadBucket ¶ added in v0.39.0
func NewReadBucket( sourceReadBucket storage.ReadBucket, moduleCommit ModuleCommit, ) ReadBucket
NewReadBucket returns a new ReadBucket.
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 ¶
- bufmodule.go
- external_lock_file.go
- file_info.go
- module.go
- module_commit.go
- module_file.go
- module_file_set.go
- module_identity.go
- module_option.go
- module_owner.go
- module_pin.go
- module_reference.go
- multi_read_bucket.go
- nop_module_reader.go
- nop_module_resolver.go
- object_info.go
- read_bucket.go
- targeting_module.go
- util.go
- validate.go