buf: github.com/bufbuild/buf/internal/buf/bufcore/bufmodule Index | Files | Directories

package bufmodule

import "github.com/bufbuild/buf/internal/buf/bufcore/bufmodule"

Index

Package Files

bufmodule.go errors.go external_lock_file.go module.go module_file.go module_file_set.go module_name.go nop_module_reader.go nop_module_resolver.go resolved_module_name.go targeting_module.go util.go validate.go

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.

func IsNoDigestError Uses

func IsNoDigestError(err error) bool

IsNoDigestError returns whether the error provided, or any error wrapped by that error, is a NoDigest error.

func ModuleDigestB1 Uses

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

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):

1. Add the string representation of the module track
2. Add the dependency hashes (sorted lexicographically by the string representation)
3. For every file in the module (sorted lexicographically by path):
	1. Add the file path
	2. Add the file contents
4. Produce the final digest by URL-base64 encoding the summed bytes and prefixing it with the digest prefix

func ModuleNameEqual Uses

func ModuleNameEqual(a ModuleName, b ModuleName) bool

ModuleNameEqual returns true if a equals b.

func ModuleToBucket Uses

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 Uses

func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1.Module, error)

ModuleToProtoModule converts the Module to a proto Module.

This takes all Sources and puts them in the Module, not just Targets.

func NewNoDigestError Uses

func NewNoDigestError(moduleName ModuleName) error

NewNoDigestError returns a new error indicating that a module did not have a digest where required.

func NewProtoModuleNameForModuleName Uses

func NewProtoModuleNameForModuleName(moduleName ModuleName) *modulev1.ModuleName

NewProtoModuleNameForModuleName returns a new proto ModuleName for the given ModuleName.

func NewProtoModuleNamesForModuleNames Uses

func NewProtoModuleNamesForModuleNames(moduleNames ...ModuleName) []*modulev1.ModuleName

NewProtoModuleNamesForModuleNames maps the given module names into the protobuf representation.

func NewProtoModuleNamesForResolvedModuleNames Uses

func NewProtoModuleNamesForResolvedModuleNames(resolvedModuleNames ...ResolvedModuleName) []*modulev1.ModuleName

NewProtoModuleNamesForResolvedModuleNames maps the given module names into the protobuf representation.

func TargetModuleFilesToBucket Uses

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 ValidateDigest Uses

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 ValidateModuleDigest Uses

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 Uses

func ValidateModuleNamesUnique(moduleNames []ModuleName) error

ValidateModuleNamesUnique returns an error if the module names contain any duplicates.

func ValidateOwnerName Uses

func ValidateOwnerName(ownerName string, ownerType string) error

ValidateOwnerName is used to validate owner names, i.e. usernames and organization names.

func ValidateProtoModule Uses

func ValidateProtoModule(protoModule *modulev1.Module) error

ValidateProtoModule verifies the given module is well-formed.

func ValidateProtoModuleName Uses

func ValidateProtoModuleName(protoModuleName *modulev1.ModuleName) error

ValidateProtoModuleName verifies the given module name is well-formed.

func ValidateRepositoryName Uses

func ValidateRepositoryName(repositoryName string) error

ValidateRepositoryName verifies the given repository name is well-formed.

func ValidateRepositoryTrackName Uses

func ValidateRepositoryTrackName(trackName string) error

ValidateRepositoryTrackName verifies the given repository track name is well-formed.

func ValidateResolvedModuleNamesUnique Uses

func ValidateResolvedModuleNamesUnique(resolvedModuleNames []ResolvedModuleName) error

ValidateResolvedModuleNamesUnique returns an error if the module names contain any duplicates.

func WriteModuleDependenciesToBucket Uses

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.

type Module Uses

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.
    //
    // The returned ModuleNames are sorted by remote, owner, repository, track, and then digest.
    Dependencies() []ResolvedModuleName
    // 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 Uses

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 Uses

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 Uses

func NewModuleForBucket(
    ctx context.Context,
    readBucket storage.ReadBucket,
) (Module, error)

NewModuleForBucket returns a new Module. It attempts reads dependencies from a lock file in the read bucket.

func NewModuleForBucketWithDependencies Uses

func NewModuleForBucketWithDependencies(
    ctx context.Context,
    readBucket storage.ReadBucket,
    dependencies []ResolvedModuleName,
) (Module, error)

NewModuleForBucketWithDependencies explicitly specifies the dependencies that should be used when creating the Module. The module names must be resolved and unique.

func NewModuleForProto Uses

func NewModuleForProto(
    ctx context.Context,
    protoModule *modulev1.Module,
) (Module, error)

NewModuleForProto returns a new Module for the given proto Module.

type ModuleFile Uses

type ModuleFile interface {
    bufcore.FileInfo
    io.ReadCloser
    // contains filtered or unexported methods
}

ModuleFile is a file within a Root.

type ModuleFileSet Uses

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

func NewModuleFileSet Uses

func NewModuleFileSet(
    module Module,
    dependencies []Module,
) ModuleFileSet

NewModuleFileSet returns a new ModuleFileSet.

type ModuleName Uses

type ModuleName interface {
    fmt.Stringer

    // Required.
    Remote() string
    // Required.
    Owner() string
    // Required.
    Repository() string
    // Required.
    Track() string
    // Optional.
    Digest() string
    // contains filtered or unexported methods
}

ModuleName is a module name.

func ModuleNameForString Uses

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/track[:digest]

func NewModuleName Uses

func NewModuleName(
    remote string,
    owner string,
    repository string,
    track string,
    digest string,
) (ModuleName, error)

NewModuleName returns a new validated ModuleName.

func NewModuleNameForProto Uses

func NewModuleNameForProto(protoModuleName *modulev1.ModuleName) (ModuleName, error)

NewModuleNameForProto returns a new ModuleName for the given proto ModuleName.

func NewModuleNamesForProtos Uses

func NewModuleNamesForProtos(protoModuleNames ...*modulev1.ModuleName) ([]ModuleName, error)

NewModuleNamesForProtos maps the Protobuf equivalent into the internal representation.

func UnresolvedModuleName Uses

func UnresolvedModuleName(moduleName ModuleName) (ModuleName, error)

UnresolvedModuleName returns the ModuleName without a digest.

This is just a convenience function.

type ModuleReader Uses

type ModuleReader interface {
    // GetModule gets the named Module.
    //
    // Returns an error that fufills storage.IsNotExist if the named Module does not exist.
    GetModule(ctx context.Context, moduleName ResolvedModuleName) (Module, error)
}

ModuleReader reads resolved modules.

func NewNopModuleReader Uses

func NewNopModuleReader() ModuleReader

NewNopModuleReader returns a new ModuleReader that always returns a storage.IsNotExist error.

type ModuleResolver Uses

type ModuleResolver interface {
    // ResolveModule resolves the provided ModuleName.
    //
    // Returns an error that fufills storage.IsNotExist if the named Module does not exist.
    ResolveModule(ctx context.Context, moduleName ModuleName) (ResolvedModuleName, error)
}

ModuleResolver resolves modules.

func NewNopModuleResolver Uses

func NewNopModuleResolver() ModuleResolver

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

type ResolvedModuleName Uses

type ResolvedModuleName interface {
    fmt.Stringer
    ModuleName
    // contains filtered or unexported methods
}

ResolvedModuleName represents a resolved module name, e.g. a module name with a digest.

func DeduplicateResolvedModuleNames Uses

func DeduplicateResolvedModuleNames(resolvedModuleNames []ResolvedModuleName) []ResolvedModuleName

DeduplicateResolvedModuleNames returns a deduplicated slice of resolved module names by selecting the first occurrence of a resolved module name based on the modules representation without the digest.

func NewResolvedModuleName Uses

func NewResolvedModuleName(
    remote string,
    owner string,
    repository string,
    track string,
    digest string,
) (ResolvedModuleName, error)

NewResolvedModuleName returns a new validated ResolvedModuleName.

func NewResolvedModuleNameForProto Uses

func NewResolvedModuleNameForProto(protoModuleName *modulev1.ModuleName) (ResolvedModuleName, error)

NewResolvedModuleNameForProto returns a new ResolvedModuleName for the given proto ModuleName.

func NewResolvedModuleNamesForProtos Uses

func NewResolvedModuleNamesForProtos(protoModuleNames ...*modulev1.ModuleName) ([]ResolvedModuleName, error)

NewResolvedModuleNamesForProtos maps the Protobuf equivalent into the internal representation.

func ResolvedModuleNameForModule Uses

func ResolvedModuleNameForModule(ctx context.Context, moduleName ModuleName, module Module) (ResolvedModuleName, 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 ResolvedModuleNameForString Uses

func ResolvedModuleNameForString(path string) (ResolvedModuleName, error)

ResolvedModuleNameForString returns a new ResolvedModuleName for the given string.

This parses the path in the form remote/owner/repository/track:digest

Directories

PathSynopsis
bufmodulebuild
bufmodulecache
bufmodulestorage
bufmoduletesting

Package bufmodule imports 19 packages (graph) and is imported by 9 packages. Updated 2020-11-28. Refresh now. Tools for package owners.