Documentation ¶
Index ¶
- Constants
- Variables
- func IsNoDigestError(err error) bool
- func ModuleDigestB1(ctx context.Context, moduleVersion string, module Module) (string, error)
- func ModuleNameEqual(a ModuleName, b ModuleName) bool
- func ModuleToBucket(ctx context.Context, module Module, writeBucket storage.WriteBucket) error
- func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1.Module, error)
- func NewNoDigestError(moduleName ModuleName) error
- func NewProtoModuleNameForModuleName(moduleName ModuleName) (*modulev1.ModuleName, error)
- func NewProtoModuleNamesForModuleNames(moduleNames ...ModuleName) ([]*modulev1.ModuleName, error)
- func ReadModuleFile(ctx context.Context, module Module, path string) (_ []byte, retErr error)
- func ValidateDigest(digest string) error
- func ValidateModuleDigest(ctx context.Context, moduleName ModuleName, module Module) error
- func ValidateModuleNamesUnique(moduleNames []ModuleName) error
- func ValidateOwnerName(ownerName string, ownerType string) error
- func ValidateProtoModule(protoModule *modulev1.Module) error
- func ValidateProtoModuleName(protoModuleName *modulev1.ModuleName) error
- func ValidateRepositoryName(repositoryName string) error
- func ValidateRepositoryVersionName(versionName string) error
- func WriteModuleDependenciesToBucket(ctx context.Context, writeBucket storage.WriteBucket, module Module) 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 NewModuleForBucketWithDependencies(ctx context.Context, readBucket storage.ReadBucket, dependencies []ModuleName) (Module, error)
- func NewModuleForProto(ctx context.Context, protoModule *modulev1.Module) (Module, error)
- type ModuleFile
- type ModuleFileSet
- type ModuleName
- func DeduplicateModuleNames(moduleNames []ModuleName) []ModuleName
- func ModuleNameForString(path string) (ModuleName, error)
- func NewModuleName(remote string, owner string, repository string, version string, digest string) (ModuleName, error)
- func NewModuleNameForProto(protoModuleName *modulev1.ModuleName) (ModuleName, error)
- func NewModuleNamesForProtos(moduleNames ...*modulev1.ModuleName) ([]ModuleName, error)
- func ResolvedModuleNameForModule(ctx context.Context, moduleName ModuleName, module Module) (ModuleName, error)
- func UnresolvedModuleName(moduleName ModuleName) (ModuleName, error)
- type ModuleReader
Constants ¶
const LockFilePath = "buf.lock"
LockFilePath defines the path to the lock file, relative to the root of the module.
Variables ¶
var ErrNoTargetFiles = errors.New("no .proto target files found")
ErrNoTargetFiles is the error returned if there are no target files found.
Functions ¶
func IsNoDigestError ¶
IsNoDigestError returns whether the error provided, or any error wrapped by that error, is a NoDigest error.
func ModuleDigestB1 ¶
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):
- Add the string representation of the module version
- Add the dependency hashes (sorted lexicographically by the string representation)
- For every file in the module (sorted lexicographically by path):
- Add the file path
- Add the file contents
- 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 ¶
ModuleToBucket writes the given Module to the WriteBucket.
This writes the sources and the buf.lock file.
func ModuleToProtoModule ¶
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, error)
NewProtoModuleNameForModuleName returns a new proto ModuleName for the given ModuleName.
func NewProtoModuleNamesForModuleNames ¶
func NewProtoModuleNamesForModuleNames(moduleNames ...ModuleName) ([]*modulev1.ModuleName, error)
NewProtoModuleNamesForModuleNames maps the given module names into the protobuf representation.
func ReadModuleFile ¶
ReadModuleFile reads the content for the .proto file at the given path in the Module.
Returns an error that fufills storage.IsNotExist if the path does not exist.
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 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
ValidateOwnerName is used to validate owner names, i.e. usernames and organization names.
func ValidateProtoModule ¶ added in v0.24.0
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
ValidateRepositoryName verifies the given repository name is well-formed.
func ValidateRepositoryVersionName ¶ added in v0.24.0
ValidateRepositoryVersionName verifies the given repository version name is well-formed.
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. These are always resolved. // // The returned ModuleNames are sorted by remote, owner, repository, version, and then digest. Dependencies() []ModuleName // 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 ¶
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 ¶
ModuleWithTargetPathsAllowNotExist returns a new Module specified specifie file paths to build, but allows the specified paths to not exist.
func NewModuleForBucket ¶
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 []ModuleName, ) (Module, error)
NewModuleForBucketWithDependencies 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 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 DeduplicateModuleNames ¶
func DeduplicateModuleNames(moduleNames []ModuleName) []ModuleName
DeduplicateModuleNames returns a deduplicated slice of module names by selecting the first occurrence of a module name based on the modules representation without a digest.
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(moduleNames ...*modulev1.ModuleName) ([]ModuleName, error)
NewModuleNamesForProtos maps the Protobuf equivalent into the internal represenation.
func ResolvedModuleNameForModule ¶
func ResolvedModuleNameForModule(ctx context.Context, moduleName ModuleName, module Module) (ModuleName, 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 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. // // The given ModuleName must be resolved, i.e. it must have a digest. // // Returns an error that fufills storage.IsNotExist if the named Module does not exist. GetModule(ctx context.Context, moduleName ModuleName) (Module, error) }
ModuleReader reads modules. If the ModuleReader is asked to get an unresolved ModuleName, it will resolve the module according to the latest digest.
Callers SHOULD NOT rely on this interface for resolving all of a module's dependencies.
func NewNopModuleReader ¶
func NewNopModuleReader() ModuleReader
NewNopModuleReader returns a new ModuleReader that always returns a storage.IsNotExist error.