Documentation ¶
Index ¶
- Constants
- 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) (*modulev1.Module, error)
- func NewProtoModulePinForModulePin(modulePin ModulePin) *modulev1.ModulePin
- func NewProtoModulePinsForModulePins(modulePins ...ModulePin) []*modulev1.ModulePin
- func NewProtoModuleReferenceForModuleReference(moduleReference ModuleReference) *modulev1.ModuleReference
- func NewProtoModuleReferencesForModuleReferences(moduleReferences ...ModuleReference) []*modulev1.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 ValidateCommit(commit string) error
- func ValidateDigest(digest 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 *modulev1.Module) error
- func ValidateProtoModulePin(protoModulePin *modulev1.ModulePin) error
- func ValidateProtoModuleReference(protoModuleReference *modulev1.ModuleReference) error
- func ValidateRepository(repository string) error
- func ValidateTrack(track string) error
- func ValidateUser(user string) error
- 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) (Module, error)
- func NewModuleForBucketWithDependencyModulePins(ctx context.Context, readBucket storage.ReadBucket, ...) (Module, error)
- func NewModuleForProto(ctx context.Context, protoModule *modulev1.Module) (Module, error)
- type ModuleFile
- type ModuleFileSet
- type ModuleIdentity
- type ModulePin
- type ModuleReader
- type ModuleReference
- func ModuleReferenceForString(path string) (ModuleReference, error)
- func NewCommitModuleReference(remote string, owner string, repository string, commit string) (ModuleReference, error)
- func NewModuleReferenceForProto(protoModuleReference *modulev1.ModuleReference) (ModuleReference, error)
- func NewModuleReferencesForProtos(protoModuleReferences ...*modulev1.ModuleReference) ([]ModuleReference, error)
- func NewTrackModuleReference(remote string, owner string, repository string, track string) (ModuleReference, error)
- type ModuleResolver
Constants ¶
const (
// LockFilePath defines the path to the lock file, relative to the root of the module.
LockFilePath = "buf.lock"
)
Variables ¶
This section is empty.
Functions ¶
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
NewProtoModulePinForModulePin returns a new proto ModulePin for the given ModulePin.
func NewProtoModulePinsForModulePins ¶ added in v0.34.0
NewProtoModulePinsForModulePins maps the given module pins into the protobuf representation.
func NewProtoModuleReferenceForModuleReference ¶ added in v0.34.0
func NewProtoModuleReferenceForModuleReference(moduleReference ModuleReference) *modulev1.ModuleReference
NewProtoModuleReferenceForModuleReference returns a new proto ModuleReference for the given ModuleReference.
func NewProtoModuleReferencesForModuleReferences ¶ added in v0.34.0
func NewProtoModuleReferencesForModuleReferences(moduleReferences ...ModuleReference) []*modulev1.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 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 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
ValidateProtoModule verifies the given module is well-formed.
func ValidateProtoModulePin ¶ added in v0.34.0
ValidateProtoModulePin verifies the given module pin is well-formed.
func ValidateProtoModuleReference ¶ added in v0.34.0
func ValidateProtoModuleReference(protoModuleReference *modulev1.ModuleReference) error
ValidateProtoModuleReference verifies the given module reference is well-formed.
func ValidateRepository ¶ added in v0.34.0
ValidateRepository verifies the given repository name is well-formed.
func ValidateTrack ¶ added in v0.34.0
ValidateTrack verifies the given repository track is well-formed.
func ValidateUser ¶ added in v0.34.0
ValidateUser verifies the given user name is well-formed.
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) // 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, track, commit, and then digest. // The returned ModulePins are unique by remote, owner, repository. // // This includes all transitive dependencies. DependencyModulePins() []ModulePin // 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 ¶
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, ) (Module, error)
NewModuleForBucketWithDependencyModulePins explicitly specifies the dependencies that should be used when creating the Module. The module names must be resolved and unique.
type ModuleFile ¶
type ModuleFile interface { bufcore.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) ([]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.
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 { Remote() string Owner() string 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{:track,@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 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 Track() 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, track string, commit string, digest string, createTime time.Time, ) (ModulePin, error)
NewModulePin returns a new validated ModulePin.
func NewModulePinForProto ¶ added in v0.34.0
NewModulePinForProto returns a new ModulePin for the given proto ModulePin.
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:track or remote/owner/repository@commit fmt.Stringer // only one of these will be set Track() string // only one of these will be set Commit() string // contains filtered or unexported methods }
ModuleReference is a module reference.
It references either a track, or a commit. Only one of Track and Commit will be set. Note that since commits belong to tracks, we can deduce the track 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.
This parses the path in the form remote/owner/repository{:track,@commit}.
func NewCommitModuleReference ¶ added in v0.34.0
func NewCommitModuleReference( remote string, owner string, repository string, commit string, ) (ModuleReference, error)
NewCommitModuleReference returns a new validated ModuleReference for a commit.
func NewModuleReferenceForProto ¶ added in v0.34.0
func NewModuleReferenceForProto(protoModuleReference *modulev1.ModuleReference) (ModuleReference, error)
NewModuleReferenceForProto returns a new ModuleReference for the given proto ModuleReference.
func NewModuleReferencesForProtos ¶ added in v0.34.0
func NewModuleReferencesForProtos(protoModuleReferences ...*modulev1.ModuleReference) ([]ModuleReference, error)
NewModuleReferencesForProtos maps the Protobuf equivalent into the internal representation.
func NewTrackModuleReference ¶ added in v0.34.0
func NewTrackModuleReference( remote string, owner string, repository string, track string, ) (ModuleReference, error)
NewTrackModuleReference returns a new validated ModuleReference for a track.
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.