bufmodule

package
v0.43.3-0...-9926edd Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
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

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

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

ModuleDigest 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 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, module Module) 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.

func ValidateCommit

func ValidateCommit(commit string) error

ValidateCommit verifies the given commit is well-formed.

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

func ValidateModuleMatchesDigest

func ValidateModuleMatchesDigest(ctx context.Context, module Module, modulePin ModulePin) error

ValidateModuleMatchesDigest validates that the Module matches the digest.

This is just a convenience function.

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.

func ValidateOwner

func ValidateOwner(owner string, ownerType string) error

ValidateOwner verifies the given owner name is well-formed.

func ValidateProtoModule

func ValidateProtoModule(protoModule *modulev1alpha1.Module) error

ValidateProtoModule verifies the given module is well-formed.

func ValidateProtoModulePin

func ValidateProtoModulePin(protoModulePin *modulev1alpha1.ModulePin) error

ValidateProtoModulePin verifies the given module pin is well-formed.

func ValidateProtoModuleReference

func ValidateProtoModuleReference(protoModuleReference *modulev1alpha1.ModuleReference) error

ValidateProtoModuleReference verifies the given module reference is well-formed.

func ValidateReference

func ValidateReference(reference string) error

ValidateReference validates that the given ModuleReference reference is well-formed.

func ValidateRepository

func ValidateRepository(repository string) error

ValidateRepository verifies the given repository name is well-formed.

func ValidateTag

func ValidateTag(tag string) error

ValidateTag verifies the given tag is well-formed.

func ValidateUser

func ValidateUser(user string) error

ValidateUser verifies the given user name is well-formed.

Types

type FileInfo

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

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

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 ModuleCommit

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

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

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:{branch,commit}.

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(*moduleOptions)

ModuleOption is used to construct Modules.

func ModuleWithModuleCommit

func ModuleWithModuleCommit(moduleCommit ModuleCommit) ModuleOption

ModuleWithModuleCommit is used to construct a Module with a ModuleCommit.

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}
	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

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 ObjectInfo

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

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

func NewReadBucket(
	sourceReadBucket storage.ReadBucket,
	moduleCommit ModuleCommit,
) ReadBucket

NewReadBucket returns a new ReadBucket.

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL