bufmodule

package
v1.37.0 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2024 License: Apache-2.0 Imports: 32 Imported by: 49

Documentation

Index

Constants

View Source 
const (
	// ModuleVisibilityPublic says the Module is public on the registry.
	ModuleVisibilityPublic = iota + 1
	// ModuleVisibilityPublic says the Module is private on the registry.
	ModuleVisibilityPrivate
)

Variables

View Source 
var (
	// AllDigestTypes are all known DigestTypes.
	AllDigestTypes = []DigestType{
		DigestTypeB4,
		DigestTypeB5,
	}
)
View Source 
var (
	// ErrNoTargetProtoFiles is the error to return if no target .proto files were found in situations where
	// they were expected to be found.
	//
	// Pre-refactor, we had extremely exacting logic that determined if --path and --exclude-path were valid
	// paths, which almost no CLI tool does. This logic had a heavy burden, when typically this error message
	// is enough (and again, is more than almost any other CLI does - most CLIs silently move on if invalid
	// paths are specified). The pre-refactor logic was the "allowNotExist" logic. Removing the allowNotExist
	// logic was not a breaking change - we do not error in any place that we previously did not.
	//
	// This is used by bufctl.Controller.GetTargetImageWithConfigs, bufworkspace.WorkspaceProvider.GetWorkspaceForBucket, and bufimage.BuildImage.
	//
	// We do assume flag names here, but we're just going with reality.
	ErrNoTargetProtoFiles = errors.New("no .proto files were targeted. This can occur if no .proto files are found in your input, --path points to files that do not exist, or --exclude-path excludes all files.")
)

Functions

func DigestEqual added in v1.32.0 

func DigestEqual(a Digest, b Digest) bool

DigestEqual returns true if the given Digests are considered equal.

If both Digests are nil, this returns true.

This checks both the DigestType and Digest value.

func FileInfoPaths added in v1.32.0 

func FileInfoPaths(fileInfos []FileInfo) []string

FileInfoPaths is a convenience function that returns the paths of the FileInfos.

func GetDocStorageReadBucket added in v1.32.0 

func GetDocStorageReadBucket(ctx context.Context, bucket storage.ReadBucket) (storage.ReadBucket, error)

GetDocStorageReadBucket gets a storage.ReadBucket that just contains the documentation file(s).

This is needed for i.e. using RootToExcludes in NewWorkspaceForBucket.

func GetFilePaths added in v1.32.0 

func GetFilePaths(ctx context.Context, moduleReadBucket ModuleReadBucket) ([]string, error)

GetFilePaths is a convenience function that gets all the target and non-target file paths for the ModuleReadBucket.

Sorted.

func GetLicenseStorageReadBucket added in v1.32.0 

func GetLicenseStorageReadBucket(ctx context.Context, bucket storage.ReadBucket) (storage.ReadBucket, error)

GetLicenseStorageReadBucket gets a storage.ReadBucket that just contains the license file(s).

This is needed for i.e. using RootToExcludes in NewWorkspaceForBucket.

func GetTargetFilePaths added in v1.32.0 

func GetTargetFilePaths(ctx context.Context, moduleReadBucket ModuleReadBucket) ([]string, error)

GetTargetFilePaths is a convenience function that gets all the target file paths for the ModuleReadBucket.

Sorted.

func IsValidModuleFilePath added in v1.32.0 

func IsValidModuleFilePath(filePath string) bool

IsValidModuleFilePath returns true if the given file path is a valid Module file path.

This will be true if the file path represents a .proto file, license file, or documentation file.

Note that license and documentation files must be at the root, and cannot be in subdirectories. That is, subdir/LICENSE is not a valid module file (including on push), but LICENSE is.

func ModuleFullNameEqual added in v1.32.0 

func ModuleFullNameEqual(one ModuleFullName, two ModuleFullName) bool

ModuleFullNameEqual returns true if the ModuleFullNames are equal.

func ModuleFullNameStringToUniqueValue added in v1.32.0 

func ModuleFullNameStringToUniqueValue[T HasModuleFullName, S ~[]T](values S) (map[string]T, error)

ModuleFullNameStringToValue maps the values that implement HasModuleFullName to a map from ModuleFullName string to the unique value that has this ModuleFullName.

If any value has a nil ModuleFullName, this value is not added to the map. Therefore, for types that potentially have a nil ModuleFullName, you cannot reply on this function returning a map of the same length as the input values.

Returns error if there are values with duplicate ModuleFullNames.

func ModuleReadBucketToStorageReadBucket added in v1.32.0 

func ModuleReadBucketToStorageReadBucket(bucket ModuleReadBucket) storage.ReadBucket

ModuleReadBucketToStorageReadBucket converts the given ModuleReadBucket to a storage.ReadBucket.

All Files (whether targets or non-targets) are added.

func ModuleSetLocalOpaqueIDs added in v1.32.0 

func ModuleSetLocalOpaqueIDs(moduleSet ModuleSet) []string

ModuleSetLocalOpaqueIDs is a conenience function that returns a slice of the OpaqueIDs of the local Modules in the ModuleSet.

Sorted.

func ModuleSetNonTargetOpaqueIDs added in v1.32.0 

func ModuleSetNonTargetOpaqueIDs(moduleSet ModuleSet) []string

ModuleSetNonTargetOpaqueIDs is a conenience function that returns a slice of the OpaqueIDs of the non-target Modules in the ModuleSet.

Sorted.

func ModuleSetOpaqueIDs added in v1.32.0 

func ModuleSetOpaqueIDs(moduleSet ModuleSet) []string

ModuleSetOpaqueIDs is a convenience function that returns a slice of the OpaqueIDs of the Modules in the ModuleSet.

Sorted.

func ModuleSetRemoteOpaqueIDs added in v1.32.0 

func ModuleSetRemoteOpaqueIDs(moduleSet ModuleSet) []string

ModuleSetRemoteOpaqueIDs is a conenience function that returns a slice of the OpaqueIDs of the remote Modules in the ModuleSet.

Sorted.

func ModuleSetTargetOpaqueIDs added in v1.32.0 

func ModuleSetTargetOpaqueIDs(moduleSet ModuleSet) []string

ModuleSetTargetOpaqueIDs is a convenience function that returns a slice of the OpaqueIDs of the target Modules in the ModuleSet.

Sorted.

func ModuleSetToDAG added in v1.32.0 

func ModuleSetToDAG(moduleSet ModuleSet) (*dag.Graph[string, Module], error)

ModuleSetToDAG gets a DAG of the given ModuleSet.

This only starts at target Modules. If a Module is not part of a graph with a target Module as a source, it will not be added.

Types

type Commit added in v1.32.0 

type Commit interface {
	// ModuleKey returns the ModuleKey for the Commit.
	ModuleKey() ModuleKey
	// CreateTime returns the time the Commit was created on the BSR.
	CreateTime() (time.Time, error)
	// contains filtered or unexported methods
}

Commit represents a Commit on the BSR.

func NewCommit added in v1.32.0 

func NewCommit(
	moduleKey ModuleKey,
	getCreateTime func() (time.Time, error),
	options ...CommitOption,
) Commit

NewCommit returns a new Commit.

type CommitKey added in v1.32.0 

type CommitKey interface {
	// String returns "digestType/registry:dashlessCommitID".
	fmt.Stringer

	// Registry returns the registry of the Commit.
	//
	// Always present.
	Registry() string
	// CommitID returns the ID of the Commit.
	//
	// It is up to the caller to convert this to a dashless ID when necessary.
	//
	// Always present, that is CommitID().IsNil() will always be false.
	CommitID() uuid.UUID
	// DigestType returns the DigestType of the Commit.
	//
	// Note this is *not* a bufcas.Digest - this is a Digest. bufcas.Digests are a lower-level
	// type that just deal in terms of files and content. A ModuleDigest is a specific algorithm
	// applied to a set of files and dependencies.
	DigestType() DigestType
	// contains filtered or unexported methods
}

CommitKey provides identifying information for a Commit when calling the CommitProvider.

func ModuleKeyToCommitKey added in v1.32.0 

func ModuleKeyToCommitKey(moduleKey ModuleKey) (CommitKey, error)

ModuleKeyToCommitKey converts a ModuleKey to a CommitKey.

This is purely lossy - a ModuleKey has more information than a CommitKey, and a CommitKey does not have any information that a ModuleKey does not have.

func NewCommitKey added in v1.32.0 

func NewCommitKey(
	registry string,
	commitID uuid.UUID,
	digestType DigestType,
) (CommitKey, error)

NewCommitKey returns a new CommitKey.

type CommitOption added in v1.32.0 

type CommitOption func(*commitOptions)

CommitOption is an option for a new Commit.

func CommitWithExpectedDigest added in v1.32.0 

func CommitWithExpectedDigest(expectedDigest Digest) CommitOption

CommitWithExpectedDigest returns a new CommitOption that will compare the Digest of the ModuleKey provided at construction with this digest whenever any lazy method is called. If the digests do not match, an error is returned

This is used in situations where we have a Digest from our read location (such as the BSR or the cache), and we want to compare it with a ModuleKey we were provided from a local location.

type CommitProvider added in v1.32.0 

type CommitProvider interface {
	// GetCommitsForModuleKeys gets the Commits for the given ModuleKeys.
	//
	// Returned Commits will be in the same order as the input ModuleKeys.
	//
	// The input ModuleKeys are expected to have the same DigestType. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the Commits returned will match the length of the ModuleKeys.
	// If there is an error, no Commits will be returned.
	// If any ModuleKey is not found, an error with fs.ErrNotExist will be returned.
	GetCommitsForModuleKeys(context.Context, []ModuleKey) ([]Commit, error)
	// GetCommitsForCommitKeys gets the Commits for the given CommitKeys.
	//
	// Returned Commits will be in the same order as the input CommitKeys.
	//
	// The input CommitKeys are expected to have the same DigestType. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the Commits returned will match the length of the CommitKeys.
	// If there is an error, no Commits will be returned.
	// If any CommitKey is not found, an error with fs.ErrNotExist will be returned.
	GetCommitsForCommitKeys(context.Context, []CommitKey) ([]Commit, error)
}

CommitProvider provides Commits for ModuleKeys or CommitIDs.

Use GetCommitForModuleKeys if you already have the ModuleKey, as it should perform better for most implementations, and the ModuleKey Digest will be checked against the retrieved Commit Digest.

The CommitProvider relies on the fact that we don't allow renames for Modules at this point in the BSR. If this were to change, our underlying cache would have to change. Keep this in mind, however so much would have to change in the BSR to allow renames that the local CLI cache is the least of our problems. 

var (
	// NopCommitProvider is a no-op CommitProvider.
	NopCommitProvider CommitProvider = nopCommitProvider{}
)

type Digest added in v1.32.0 

type Digest interface {
	// String() prints typeString:hexValue.
	fmt.Stringer

	// Type returns the type of digest.
	// Always a valid value.
	Type() DigestType
	// Value returns the digest value.
	//
	// Always non-empty.
	Value() []byte
	// contains filtered or unexported methods
}

Digest is a digest of some content.

It consists of a DigestType and a digest value.

func NewDigest added in v1.32.0 

func NewDigest(digestType DigestType, bufcasDigest bufcas.Digest) (Digest, error)

NewDigest creates a new Digest.

func ParseDigest added in v1.32.0 

func ParseDigest(s string) (Digest, error)

ParseDigest parses a Digest from its string representation.

A Digest string is of the form typeString:hexValue. The string is expected to be non-empty, If not, an error is treutned.

This reverses Digest.String().

type DigestMismatchError added in v1.32.0 

type DigestMismatchError struct {
	ModuleFullName ModuleFullName
	CommitID       uuid.UUID
	ExpectedDigest Digest
	ActualDigest   Digest
}

DigestMismatchError is the error returned if the Digest of a downloaded Module or Commit does not match the expected digest in a buf.lock file.

func (*DigestMismatchError) Error added in v1.32.0 

func (m *DigestMismatchError) Error() string

Error implements the error interface.

type DigestType added in v1.32.0 

type DigestType int

DigestType is a type of digest. 

const (
	// DigestTypeB4 represents the b4 module digest type.
	//
	// This represents the pre-refactor shake256 digest type, and the string value of
	// this is "shake256" for backwards-compatibility reasons.
	DigestTypeB4 DigestType = iota + 1
	// DigestTypeB5 represents the b5 digest type.
	//
	// This is the newest digest type, and should generally be used. The string value
	// of this is "b5".
	DigestTypeB5
)

func ParseDigestType added in v1.32.0 

func ParseDigestType(s string) (DigestType, error)

ParseDigestType parses a DigestType from its string representation.

This reverses DigestType.String().

Returns an error of type *ParseError if thie string could not be parsed.

func UniqueDigestTypeForCommitKeys added in v1.32.0 

func UniqueDigestTypeForCommitKeys(commitKeys []CommitKey) (DigestType, error)

UniqueDigestTypeForCommitKeys returns the single DigestType for the Digests on the CommitKeys.

If the CommitKeys have different DigestTypes, an error is returned. If the CommitKeys slice is empty, an error is returned.

func UniqueDigestTypeForModuleKeys added in v1.32.0 

func UniqueDigestTypeForModuleKeys(moduleKeys []ModuleKey) (DigestType, error)

UniqueDigestTypeForModuleKeys returns the single DigestType for the Digests on the ModuleKeys.

If the ModuleKeys have different DigestTypes, an error is returned. If the ModuleKeys slice is empty, an error is returned.

func (DigestType) String added in v1.32.0 

func (d DigestType) String() string

String prints the string representation of the DigestType.

type DuplicateProtoPathError added in v1.32.0 

type DuplicateProtoPathError struct {
	// ProtoPath is the path of the .proto that is duplicated.
	//
	// A well-formed DuplicateProtoPathError will have a normalized and non-empty ProtoPath.
	ProtoPath string
	// OpaqueIDs are the OpaqueIDs of the Module that contain the ProtoPath.
	//
	// A well-formed DuplicateProtoPathError will have two or more OpaqueIDs.
	OpaqueIDs []string
}

DuplicateProtoPathError is the error returned if a .proto file with the same path is detected in two or more Modules.

This check is done as part of ModuleReadBucket.Walks, and Module.ModuleDeps.

func (*DuplicateProtoPathError) Error added in v1.32.0 

func (d *DuplicateProtoPathError) Error() string

Error implements the error interface.

type File added in v1.32.0 

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

File is a file within a Module.

func GetDocFile added in v1.32.0 

func GetDocFile(ctx context.Context, moduleReadBucket ModuleReadBucket) (File, error)

GetDocFile gets the singular documentation File for the Module, if it exists.

When creating a Module from a Bucket, we check the file paths buf.md, README.md, and README.markdown to exist, in that order. The first one to exist is chosen as the documentation File that is considered part of the Module, and any others are discarded. This function will return that File that was chosen.

Returns an error with fs.ErrNotExist if no documentation file exists.

func GetLicenseFile added in v1.32.0 

func GetLicenseFile(ctx context.Context, moduleReadBucket ModuleReadBucket) (File, error)

GetLicenseFile gets the license File for the Module, if it exists.

Returns an error with fs.ErrNotExist if the license File does not exist.

type FileInfo 

type FileInfo interface {
	storage.ObjectInfo

	// Module returns the Module that contains this file.
	Module() Module
	// FileType returns the FileType of the file.
	//
	// This denotes if the File is a .proto file, documentation file, or license file.
	FileType() FileType
	// IsTargetFile returns true if the File is targeted.
	//
	// Files are either targets or imports.
	// If Module.IsTarget() is false, this will always be false.
	//
	// If specific Files were not targeted but Module.IsTarget() is true, all Files in
	// the Module will have IsTargetFile() set to true.
	IsTargetFile() bool

	// ProtoFileImports returns the file's declared .proto imports, if any.
	//
	// Always returns empty if this file is not a .proto file.
	ProtoFileImports() ([]string, error)
	// contains filtered or unexported methods
}

FileInfo is the file info for a Module file.

It comprises the typical storage.ObjectInfo, along with a pointer back to the Module. This allows callers to figure out i.e. the ModuleFullName, Commit, as well as any other data it may need.

func GetFileInfos added in v1.32.0 

func GetFileInfos(ctx context.Context, moduleReadBucket ModuleReadBucket) ([]FileInfo, error)

GetFileInfos is a convenience function that walks the ModuleReadBucket and gets all the FileInfos.

Sorted by path.

func GetTargetFileInfos added in v1.32.0 

func GetTargetFileInfos(ctx context.Context, moduleReadBucket ModuleReadBucket) ([]FileInfo, error)

GetTargetFileInfos is a convenience function that walks the ModuleReadBucket and gets all the FileInfos where IsTargetFile() is set to true.

Sorted by path.

type FileType added in v1.32.0 

type FileType int
const (
	FileTypeProto FileType = iota + 1
	FileTypeDoc
	FileTypeLicense
)

func FileTypeForPath added in v1.32.0 

func FileTypeForPath(path string) (FileType, error)

FileType returns the FileType for the given path.

Returns error if the path cannot be classified as a FileType, that is if it is not a .proto file, license file, or documentation file.

Note that license and documentation files must be at the root, and cannot be in subdirectories. That is, subdir/LICENSE will not be classified as a FileTypeLicnese, but LICENSE will be.

func ParseFileType added in v1.32.0 

func ParseFileType(s string) (FileType, error)

ParseFileType parses the file type from its string representation.

This reverses FileType.String().

Returns an error of type *ParseError if thie string could not be parsed.

func (FileType) String added in v1.32.0 

func (c FileType) String() string

type GraphProvider added in v1.32.0 

type GraphProvider interface {
	// GetGraphForModuleKeys gets the Graph for the given ModuleKeys.
	//
	// The key will be the ModuleKey.CommitID().
	//
	// The input ModuleKeys are expected to be unique by ModuleFullName. The implementation
	// may error if this is not the case.
	//
	// The input ModuleKeys are expected to have the same DigestType. The implementation
	// may error if this is not the case.
	//
	// If any ModuleKey is not found, an error with fs.ErrNotExist will be returned.
	GetGraphForModuleKeys(context.Context, []ModuleKey) (*dag.Graph[RegistryCommitID, ModuleKey], error)
}

GraphProvider provides directed acyclic graphs for ModuleKeys. 

var (
	// NopGraphProvider is a no-op GraphProvider.
	NopGraphProvider GraphProvider = nopGraphProvider{}
)

type HasModuleFullName added in v1.32.0 

type HasModuleFullName interface {
	// ModuleFullName returns the ModuleullName.
	//
	// May be empty.
	ModuleFullName() ModuleFullName
}

HasModuleFullName is any type that has a ModuleFullName() function.

type ImportNotExistError added in v1.32.0 

type ImportNotExistError struct {
	// contains filtered or unexported fields
}

ImportNotExistError is the error returned from ModuleDeps() if an import does not exist.

Unwrap() always returns fs.ErrNotExist.

func (*ImportNotExistError) Error added in v1.32.0 

func (i *ImportNotExistError) Error() string

Error implements the error interface.

func (*ImportNotExistError) Unwrap added in v1.32.0 

func (i *ImportNotExistError) Unwrap() error

Unwrap returns fs.ErrNotExist.

type LocalModuleOption added in v1.32.0 

type LocalModuleOption func(*localModuleOptions)

LocalModuleOption is an option for AddLocalModule.

func LocalModuleWithModuleFullName added in v1.32.0 

func LocalModuleWithModuleFullName(moduleFullName ModuleFullName) LocalModuleOption

LocalModuleWithModuleFullName returns a new LocalModuleOption that adds the given ModuleFullName to the result Module.

Use LocalModuleWithModuleFullNameAndCommitID if you'd also like to add a CommitID.

func LocalModuleWithModuleFullNameAndCommitID added in v1.32.0 

func LocalModuleWithModuleFullNameAndCommitID(moduleFullName ModuleFullName, commitID uuid.UUID) LocalModuleOption

LocalModuleWithModuleFullName returns a new LocalModuleOption that adds the given ModuleFullName and CommitID to the result Module.

func LocalModuleWithProtoFileTargetPath added in v1.32.0 

func LocalModuleWithProtoFileTargetPath(
	protoFileTargetPath string,
	includePackageFiles bool,
) LocalModuleOption

LocalModuleWithProtoFileTargetPath returns a new LocalModuleOption that specifically targets a single .proto file, and optionally targets all other .proto files that are in the same package.

If targetPath is empty, includePackageFiles is ignored. Exclusive with LocalModuleWithTargetPaths - only one of these can have a non-empty value.

This is used for ProtoFileRefs only. Do not use this otherwise.

func LocalModuleWithTargetPaths added in v1.32.0 

func LocalModuleWithTargetPaths(
	targetPaths []string,
	targetExcludePaths []string,
) LocalModuleOption

LocalModuleWithTargetPaths returns a new LocalModuleOption that specifically targets the given paths, and specifically excludes the given paths.

Only valid for a targeted Module. If this option is given to a non-target Module, this will result in an error during Build().

func LocalModuleWithV1Beta1OrV1BufLockObjectData added in v1.32.0 

func LocalModuleWithV1Beta1OrV1BufLockObjectData(v1BufLockObjectData ObjectData) LocalModuleOption

LocalModuleWithV1Beta1OrV1BufLockObjectData returns a new LocalModuleOption that attaches the original source buf.local file associated with this Module for v1 or v1beta1 buf.lock-backed Modules.

If a buf.lock exists on disk, should be set for Modules backed with a v1beta1 or v1 buf.lock. Note that a buf.lock may not exist for a v1 Module, if there are no dependencies, and in this case, this is not set. However, if there is a buf.lock file that was generated, even if it had no dependencies, this is set.

For Modules backed with v2 buf.locks, this should not be set.

This file content is just used for dependency calculations. It is not parsed.

func LocalModuleWithV1Beta1OrV1BufYAMLObjectData added in v1.32.0 

func LocalModuleWithV1Beta1OrV1BufYAMLObjectData(v1BufYAMLObjectData ObjectData) LocalModuleOption

LocalModuleWithV1Beta1OrV1BufYAMLObjectData returns a new LocalModuleOption that attaches the original source buf.yaml file associated with this module for v1 or v1beta1 buf.yaml-backed Modules.

If a buf.yaml exists on disk, should be set for Modules backed with a v1beta1 or v1 buf.yaml. It is possible that a Module has no buf.yaml (if it was built from defaults), in which case this will not be set.

For Modules backed with v2 buf.yamls, this should not be set.

This file content is just used for dependency calculations. It is not parsed.

type Module 

type Module interface {
	// ModuleReadBucket allows for reading of a Module's files.
	//
	// A Module consists of .proto files, documentation file(s), and license file(s). All of these
	// are accessible via the functions on ModuleReadBucket.
	//
	// This bucket is not self-contained - it requires the files from dependencies to be so.
	//
	// A ModuleReadBucket directly derived from a Module will always have at least one .proto file.
	// If this is not the case, WalkFileInfos will return an error when called.
	ModuleReadBucket

	// OpaqueID returns an unstructured ID that can uniquely identify a Module relative
	// to other Modules it was built with from a ModuleSetBuilder.
	//
	// Always present, regardless of whether a Module was provided by a ModuleProvider,
	// or built with a ModuleSetBuilder.
	//
	// An OpaqueID can be used to denote expected uniqueness of content; if two Modules
	// have different IDs, they should be expected to be logically different Modules.
	//
	// An OpaqueID can be used as a human-readable identifier of the Module, suitable for printing
	// to a console. However, the OpaqueID may contain information on local directory structure, so
	// do not log or print it in contexts where such information may be sensitive.
	//
	// An OpaqueID's structure should not be relied upon, and is not a globally-unique identifier.
	// It's uniqueness property only applies to the lifetime of the Module, and only within
	// Modules commonly built from a ModuleSetBuilder.
	//
	// If two Modules have the same ModuleFullName, they will have the same OpaqueID.
	//
	// While this should not be relied upion, this ID is currently equal to the ModuleFullName,
	// and if the ModuleFullName is not present, then the BucketID.
	OpaqueID() string
	// BucketID is an unstructured ID that represents the Bucket that this Module was constructed
	// with via ModuleSetProvider.
	//
	// A BucketID will be unique within a given ModuleSet.
	//
	// A BucketID's structure should not be relied upon, and is not a globally-unique identifier.
	// It's uniqueness property only applies to the lifetime of the Module, and only within
	// Modules commonly built from a ModuleSetBuilder.
	//
	// A BucketID may contain information on local directory structure, so do not log or print it
	// in contexts where such information may be sensitive.
	//
	// May be empty if a Module was not constructed with a Bucket via a ModuleSetProvider.
	BucketID() string
	// ModuleFullName returns the full name of the Module.
	//
	// May be nil. Callers should not rely on this value being present.
	// However, this is always present for remote Modules.
	//
	// At least one of ModuleFullName and BucketID will always be present. Use OpaqueID
	// as an always-present identifier.
	ModuleFullName() ModuleFullName
	// CommitID returns the BSR ID of the Commit.
	//
	// It is up to the caller to convert this to a dashless ID when necessary.
	//
	// May be empty, that is CommitID().IsNil() may be true.
	// Callers should not rely on this value being present.
	//
	// If ModuleFullName is nil, this will always be empty.
	CommitID() uuid.UUID

	// Digest returns the Module digest for the given DigestType.
	//
	// Note this is *not* a bufcas.Digest - this is a Digest. bufcas.Digests are a lower-level
	// type that just deal in terms of files and content. A Digest is a specific algorithm
	// applied to a set of files and dependencies.
	Digest(DigestType) (Digest, error)

	// ModuleDeps returns the dependencies for this specific Module.
	//
	// Includes transitive dependencies. Use ModuleDep.IsDirect() to determine if a dependency is direct
	// or transitive.
	//
	// This list is pruned - only Modules that this Module actually depends on (either directly or transitively)
	// via import statements within its .proto files will be returned.
	//
	// Dependencies with the same ModuleFullName will always have the same Commits and Digests.
	//
	// Sorted by OpaqueID.
	ModuleDeps() ([]ModuleDep, error)

	// IsTarget returns true if the Module is a targeted Module.
	//
	// Modules are either targets or non-targets.
	// Modules directly returned from a ModuleProvider will always be marked as targets.
	// Modules created file ModuleSetBuilders may or may not be marked as targets.
	//
	// Files within a targeted Module can be targets or non-targets themselves (non-target = import).
	// FileInfos have a function FileInfo.IsTargetFile() to denote if they are targets.
	// Note that no Files from a Module will have IsTargetFile() set to true if
	// IsTarget() is false.
	//
	// If specific Files were not targeted but the Module was targeted, all Files in the Module
	// will have FileInfo.IsTargetFile() set to true, and this function will return all Files
	// that WalkFileInfos does.
	//
	// Note that a Module may be targeted but have none of its files targeted - this can occur
	// when path filtering occurs, but no paths given matched any paths in the Module, but
	// the Module itself was targeted.
	IsTarget() bool

	// IsLocal return true if the Module is a local Module.
	//
	// Modules are either local or remote.
	//
	// A local Module is one which was built from sources from the "local context", such
	// a Workspace containing Modules, or a ModuleNode in a CreateCommiteRequest. Local
	// Modules are important for understanding what Modules to push, and what modules to
	// check declared dependencies for unused dependencies.
	//
	// A remote Module is one which was not contained in the local context, such as
	// dependencies specified in a buf.lock (with no correspoding Module in the Workspace),
	// or a DepNode in a CreateCommitRequest with no corresponding ModuleNode.
	//
	// Remote Modules will always have ModuleFullNames.
	IsLocal() bool

	// V1Beta1OrV1BufYAMLObjectData returns the original source buf.yaml associated with this Module, if the
	// Module was backed with a v1beta1 or v1 buf.yaml.
	//
	// This may not be set, in the cases where a v1 Module was built with no buf.yaml (ie the defaults),
	// or with a v2 Module.
	//
	// This file content is just used for dependency calculations. It is not parsed.
	V1Beta1OrV1BufYAMLObjectData() (ObjectData, error)
	// V1Beta1OrV1BufLockObjectData returns the original source buf.lock associated with this Module, if the
	// Module was backed with a v1beta1 or v1 buf.lock.
	//
	// This may not be set, in the cases where a buf.lock was not present due to no dependencies, or
	// with a v2 Module.
	//
	// This file content is just used for dependency calculations. It is not parsed.
	V1Beta1OrV1BufLockObjectData() (ObjectData, error)

	// ModuleSet returns the ModuleSet that this Module is contained within.
	//
	// Always present.
	ModuleSet() ModuleSet
	// contains filtered or unexported methods
}

Module presents a BSR module.

func ModuleSetLocalModules added in v1.32.0 

func ModuleSetLocalModules(moduleSet ModuleSet) []Module

ModuleSetLocalModules is a convenience function that returns the local Modules from a ModuleSet.

func ModuleSetNonTargetModules added in v1.32.0 

func ModuleSetNonTargetModules(moduleSet ModuleSet) []Module

ModuleSetNonTargetModules is a convenience function that returns the non-target Modules from a ModuleSet.

func ModuleSetRemoteModules added in v1.32.0 

func ModuleSetRemoteModules(moduleSet ModuleSet) []Module

ModuleSetRemoteModules is a convenience function that returns the remote Modules from a ModuleSet.

func ModuleSetTargetLocalModulesAndTransitiveLocalDeps added in v1.32.0 

func ModuleSetTargetLocalModulesAndTransitiveLocalDeps(moduleSet ModuleSet) ([]Module, error)

ModuleSetTargetLocalModulesAndTransitiveLocalDeps is a convenience function that returns the targeted local Modules of the ModuleSet, and their transitive local dependencies.

This is used by push to determine what Modules should be uploaded.

Sorted by OpaqueID.

func ModuleSetTargetModules added in v1.32.0 

func ModuleSetTargetModules(moduleSet ModuleSet) []Module

ModuleSetTargetModules is a convenience function that returns the target Modules from a ModuleSet.

type ModuleCycleError added in v1.32.0 

type ModuleCycleError struct {
	// OpaqueIDs are the OpaqueIDs that represent the cycle.
	OpaqueIDs []string
}

ModuleCycleError is the error returned if a cycle is detected in module dependencies.

func (*ModuleCycleError) Error added in v1.32.0 

func (m *ModuleCycleError) Error() string

Error implements the error interface.

type ModuleData added in v1.32.0 

type ModuleData interface {
	// ModuleKey contains the ModuleKey that was used to download this ModuleData.
	//
	// The Digest from this ModuleKey is used for tamper-proofing. It will be checked against
	// the actual data downloaded before Bucket() or DeclaredDepModuleKeys() returns.
	ModuleKey() ModuleKey
	// Bucket returns a Bucket of the Module's files.
	//
	// This bucket is not self-contained - it requires the files from dependencies to be so.
	//
	// This bucket will only contain module files - it will be filtered via NewModuleData.
	Bucket() (storage.ReadBucket, error)
	// DeclaredDepModuleKeys returns the declared dependencies for this specific Module.
	DeclaredDepModuleKeys() ([]ModuleKey, error)

	// V1Beta1OrV1BufYAMLObjectData gets the v1beta1 or v1 buf.yaml ObjectData.
	//
	// This may not be present. It will only be potentially present for v1 buf.yaml files.
	//
	// This is used for digest calculations. It is not used otherwise.
	V1Beta1OrV1BufYAMLObjectData() (ObjectData, error)
	// V1Beta1OrV1BufLockObjectData gets the v1beta1 or v1 buf.lock ObjectData.
	//
	// This may not be present. It will only be potentially present for v1 buf.lock files.
	//
	// This is used for digest calculations. It is not used otherwise.
	V1Beta1OrV1BufLockObjectData() (ObjectData, error)
	// contains filtered or unexported methods
}

ModuleData presents raw Module data read by ModuleKey.

It is not a fully-formed Module; only ModuleSetBuilders (and ModuleSets) can provide Modules.

A ModuleData generally represents the data on a Module read from the BSR API or a cache.

Tamper-proofing is done as part of every function.

func NewModuleData added in v1.32.0 

func NewModuleData(
	ctx context.Context,
	moduleKey ModuleKey,
	getBucket func() (storage.ReadBucket, error),
	getDeclaredDepModuleKeys func() ([]ModuleKey, error),
	getV1BufYAMLObjectData func() (ObjectData, error),
	getV1BufLockObjectData func() (ObjectData, error),
) ModuleData

NewModuleData returns a new ModuleData.

getBucket and getDeclaredDepModuleKeys are meant to be lazily-loaded functions where possible.

It is OK for getBucket to return a bucket that has extra files that are not part of the Module, this bucket will be filtered as part of this function.

type ModuleDataProvider added in v1.32.0 

type ModuleDataProvider interface {
	// GetModuleDatasForModuleKeys gets the ModuleDatas for the ModuleKeys.
	//
	// Returned ModuleDatas will be in the same order as the input ModuleKeys.
	//
	// The input ModuleKeys are expected to be unique by ModuleFullName. The implementation
	// may error if this is not the case.
	//
	// The input ModuleKeys are expected to have the same DigestType. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the ModuleDatas returned will match the length of the ModuleKeys.
	// If there is an error, no ModuleDatas will be returned.
	// If any ModuleKey is not found, an error with fs.ErrNotExist will be returned.
	GetModuleDatasForModuleKeys(
		context.Context,
		[]ModuleKey,
	) ([]ModuleData, error)
}

ModuleDataProvider provides ModulesDatas. 

var (
	// NopModuleDataProvider is a no-op ModuleDataProvider.
	NopModuleDataProvider ModuleDataProvider = nopModuleDataProvider{}
)

type ModuleDep added in v1.32.0 

type ModuleDep interface {
	Module

	// Parent returns the Module that this ModuleDep is a dependency of.
	//
	// Note this is not recursive - this points ot the top-level Module that dependencies
	// were created for. That is, if a -> b -> c, then a will have ModuleDeps b and c, both
	// of which have a as a parent.
	Parent() Module
	// IsDirect returns true if the Module is a direct dependency of this Module.
	IsDirect() bool
	// contains filtered or unexported methods
}

ModuleDep is the dependency of a Module.

It's just a Module as well as whether or not the dependency is direct.

func ModuleDirectModuleDeps added in v1.32.0 

func ModuleDirectModuleDeps(module Module) ([]ModuleDep, error)

ModuleDirectModuleDeps is a convenience function that returns only the direct dependencies of the Module.

type ModuleFullName added in v1.32.0 

type ModuleFullName interface {
	// String returns "registry/owner/name".
	fmt.Stringer

	// Registry returns the hostname of the BSR instance that this Module is contained within.
	Registry() string
	// Owner returns the name of the user or organization that owns this Module.
	Owner() string
	// Name returns the name of the Module.
	Name() string
	// contains filtered or unexported methods
}

ModuleFullName represents the full name of the Module, including its registry, owner, and name.

func NewModuleFullName added in v1.32.0 

func NewModuleFullName(
	registry string,
	owner string,
	name string,
) (ModuleFullName, error)

NewModuleFullName returns a new ModuleFullName for the given components.

func ParseModuleFullName added in v1.32.0 

func ParseModuleFullName(moduleFullNameString string) (ModuleFullName, error)

ParseModuleFullName parses a ModuleFullName from a string in the form "registry/owner/name".

type ModuleKey added in v1.32.0 

type ModuleKey interface {
	// String returns "registry/owner/name:dashlessCommitID".
	fmt.Stringer

	// ModuleFullName returns the full name of the Module.
	//
	// Always present.
	ModuleFullName() ModuleFullName
	// CommitID returns the ID of the Commit.
	//
	// It is up to the caller to convert this to a dashless ID when necessary.
	//
	// Always present, that is CommitID().IsNil() will always be false.
	CommitID() uuid.UUID
	// Digest returns the Module digest.
	//
	// Note this is *not* a bufcas.Digest - this is a Digest. bufcas.Digests are a lower-level
	// type that just deal in terms of files and content. A ModuleDigest is a specific algorithm
	// applied to a set of files and dependencies.
	Digest() (Digest, error)
	// contains filtered or unexported methods
}

ModuleKey provides identifying information for a Module.

ModuleKeys are returned from ModuleKeyProvider, and represent a Module's complete identity. They also match to what we store in buf.lock files. ModuleKeys can be used to get Modules via a ModuleProvider.

func ModuleToModuleKey added in v1.32.0 

func ModuleToModuleKey(module Module, digestType DigestType) (ModuleKey, error)

ModuleToModuleKey returns a new ModuleKey for the given Module.

The given Module must have a ModuleFullName and CommitID, otherwise this will return error.

func NewModuleKey added in v1.32.0 

func NewModuleKey(
	moduleFullName ModuleFullName,
	commitID uuid.UUID,
	getDigest func() (Digest, error),
) (ModuleKey, error)

NewModuleKey returns a new ModuleKey.

The Digest will be loaded lazily if needed. Note this means that NewModuleKey does *not* validate the digest. If you need to validate the digest, call Digest() and evaluate the returned error.

type ModuleKeyProvider added in v1.32.0 

type ModuleKeyProvider interface {
	// GetModuleKeysForModuleRefs gets the ModuleKeys for the given ModuleRefs.
	//
	// Returned ModuleKeys will be in the same order as the input ModuleRefs.
	//
	// The input ModuleRefs are expected to be unique by ModuleFullName. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the ModuleKeys returned will match the length of the ModuleRefs.
	// If there is an error, no ModuleKeys will be returned.
	// If any ModuleRef is not found, an error with fs.ErrNotExist will be returned.
	GetModuleKeysForModuleRefs(context.Context, []ModuleRef, DigestType) ([]ModuleKey, error)
}

ModuleKeyProvider provides ModuleKeys for ModuleRefs.

type ModuleReadBucket added in v1.32.0 

type ModuleReadBucket interface {
	// GetFile gets the File within the Module as specified by the path.
	//
	// Returns an error with fs.ErrNotExist if the path is not part of the Module.
	GetFile(ctx context.Context, path string) (File, error)
	// StatFileInfo gets the FileInfo for the File within the Module as specified by the path.
	//
	// Returns an error with fs.ErrNotExist if the path is not part of the Module.
	StatFileInfo(ctx context.Context, path string) (FileInfo, error)
	// WalkFileInfos walks all Files in the Module, passing the FileInfo to a specified function.
	//
	// This will walk the .proto files, documentation file(s), and license files(s). This package
	// currently exposes functionality to walk just the .proto files, and get the singular
	// documentation and license files, via WalkProtoFileInfos, GetDocFile, and GetLicenseFile.
	//
	// GetDocFile and GetLicenseFile may change in the future if other paths are accepted for
	// documentation or licenses, or if we allow multiple documentation or license files to
	// exist within a Module (currently, only one of each is allowed).
	//
	// A ModuleReadBucket directly derived from a Module will always have at least one .proto file.
	// If this is not the case, WalkFileInfos will return an error when called.
	WalkFileInfos(ctx context.Context, f func(FileInfo) error, options ...WalkFileInfosOption) error

	// ShouldBeSelfContained returns true if the ModuleReadBucket was constructed with the intention
	// that it would be self-contained with respect to its .proto files. That is, every .proto
	// file in the ModuleReadBucket only imports other files from the ModuleReadBucket.
	//
	// It is possible for a bucket to be marked as ShouldBeSelfContained without it actually
	// being self-contained.
	//
	// A ModuleReadBucket is self-contained if it was constructed from
	// ModuleSetToModuleReadBucketWithOnlyProtoFiles or
	// ModuleToSelfContainedModuleReadBucketWithOnlyProtoFiles.
	//
	// A ModuleReadBucket as inherited from a Module is not self-contained.
	//
	// A ModuleReadBucket filtered to anything but FileTypeProto is not self-contained.
	ShouldBeSelfContained() bool
	// contains filtered or unexported methods
}

ModuleReadBucket is an object analogous to storage.ReadBucket that supplements ObjectInfos and Objects with the data on the Module that supplied them.

ModuleReadBuckets talk in terms of Files and FileInfos. They are easily converted into storage.ReadBuckets.

The contents of a ModuleReadBucket are specific to its context. In the context of a Module, a ModuleReadBucket will return .proto files, documentation file(s), and license file(s). However, in the context of converting a Workspace into its corresponding .proto files, a ModuleReadBucket will only contain .proto files.

func ModuleReadBucketWithOnlyFileTypes added in v1.32.0 

func ModuleReadBucketWithOnlyFileTypes(
	moduleReadBucket ModuleReadBucket,
	fileTypes ...FileType,
) ModuleReadBucket

ModuleReadBucketWithOnlyFileTypes returns a new ModuleReadBucket that only contains the given FileTypes.

Common use case is to get only the .proto files.

func ModuleReadBucketWithOnlyProtoFiles added in v1.32.0 

func ModuleReadBucketWithOnlyProtoFiles(moduleReadBucket ModuleReadBucket) ModuleReadBucket

ModuleReadBucketWithOnlyProtoFiles is a convenience function that returns a new ModuleReadBucket that only contains the .proto files.

func ModuleReadBucketWithOnlyTargetFiles added in v1.32.0 

func ModuleReadBucketWithOnlyTargetFiles(moduleReadBucket ModuleReadBucket) ModuleReadBucket

ModuleReadBucketWithOnlyTargetFiles returns a new ModuleReadBucket that only contains target Files.

func ModuleSetToModuleReadBucketWithOnlyProtoFiles added in v1.32.0 

func ModuleSetToModuleReadBucketWithOnlyProtoFiles(moduleSet ModuleSet) ModuleReadBucket

ModuleSetToModuleReadBucketWithOnlyProtoFiles converts the ModuleSet to a ModuleReadBucket that contains all the .proto files of the target and non-target Modules of the ModuleSet.

Targeting information will remain the same.

func ModuleSetToModuleReadBucketWithOnlyProtoFilesForTargetModules added in v1.32.0 

func ModuleSetToModuleReadBucketWithOnlyProtoFilesForTargetModules(moduleSet ModuleSet) ModuleReadBucket

ModuleSetToModuleReadBucketWithOnlyProtoFilesForTargetModules converts the ModuleSet to a ModuleReadBucket that contains all the .proto files of the target Modules of the ModuleSet.

Targeting information will remain the same.

func ModuleToSelfContainedModuleReadBucketWithOnlyProtoFiles added in v1.32.0 

func ModuleToSelfContainedModuleReadBucketWithOnlyProtoFiles(module Module) (ModuleReadBucket, error)

ModuleToSelfContainedModuleReadBucketWithOnlyProtoFiles converts the Module to a ModuleReadBucket that contains all the .proto files of the Module and its dependencies.

Targeting information will remain the same. Note that this means that the result ModuleReadBucket may have no target files! This can occur when path filtering was applied, but the path filters did not match any files in the Module, and none of the Module's files were targeted. It can also happen if the Module nor any of its dependencies were targeted.

*** THIS IS PROBABLY NOT THE FUNCTION YOU ARE LOOKING FOR. *** You probably want ModuleSetToModuleReadBucketWithOnlyProtoFiles to convert a ModuleSet/Workspace to a ModuleReadBucket. This function is used for cases where we want to create an Image specifically for one Module, such as when we need to associate LintConfig and BreakingConfig on a per-Module basis for buf lint and buf breaking. See bufctl.Controller, which is likely the only place this should be used outside of testing.

type ModuleRef added in v1.32.0 

type ModuleRef interface {
	// String returns "registry/owner/name[:ref]".
	fmt.Stringer

	// ModuleFullName returns the full name of the Module.
	//
	// Always present.
	ModuleFullName() ModuleFullName
	// Ref returns the reference within the Module.
	//
	// May be a label or dashless commitID.
	//
	// May be empty, in which case this references the commit of the default label of the Module.
	Ref() string
	// contains filtered or unexported methods
}

ModuleRef is an unresolved reference to a Module.

func NewModuleRef added in v1.32.0 

func NewModuleRef(
	registry string,
	owner string,
	name string,
	ref string,
) (ModuleRef, error)

NewModuleRef returns a new ModuleRef for the given compoonents.

func ParseModuleRef added in v1.32.0 

func ParseModuleRef(moduleRefString string) (ModuleRef, error)

ParseModuleRef parses a ModuleRef from a string in the form "registry/owner/name[:ref]".

type ModuleSet added in v1.32.0 

type ModuleSet interface {
	// Modules returns the Modules in the ModuleSet.
	//
	// This will consist of both targets and non-targets.
	// All dependencies of all Modules will be in this list, that is this list is self-contained.
	//
	// All Modules will have unique Digests and CommitIDs.
	//
	// These will be sorted by OpaqueID.
	Modules() []Module

	// GetModuleForModuleFullName gets the Module for the ModuleFullName, if it exists.
	//
	// Returns nil if there is no Module with the given ModuleFullName.
	GetModuleForModuleFullName(moduleFullName ModuleFullName) Module
	// GetModuleForOpaqueID gets the Module for the OpaqueID, if it exists.
	//
	// Returns nil if there is no Module with the given OpaqueID. However, as long
	// as the OpaqueID came from a Module contained within Modules(), this will always
	// return a non-nil value.
	GetModuleForOpaqueID(opaqueID string) Module
	// GetModuleForBucketID gets the Module for the BucketID, if it exists.
	//
	// Returns nil if there is no Module with the given BucketID.
	GetModuleForBucketID(bucketID string) Module
	// GetModuleForCommitID gets the Module for the CommitID, if it exists.
	//
	// Returns nil if there is no Module with the given CommitID.
	GetModuleForCommitID(commitID uuid.UUID) Module

	// WithTargetOpaqueIDs returns a new ModuleSet that changes the targeted Modules to
	// the Modules with the specified OpaqueIDs.
	WithTargetOpaqueIDs(opaqueIDs ...string) (ModuleSet, error)
	// contains filtered or unexported methods
}

ModuleSet is a set of Modules constructed by a ModuleBuilder.

A ModuleSet is expected to be self-contained, that is Modules only import from other Modules in this ModuleSet.

A ModuleSet may be empty and have no Modules. This is primarily done in testing.

func NewModuleSetForRemoteModule added in v1.32.0 

func NewModuleSetForRemoteModule(
	ctx context.Context,
	tracer tracing.Tracer,
	graphProvider GraphProvider,
	moduleDataProvider ModuleDataProvider,
	commitProvider CommitProvider,
	moduleKey ModuleKey,
	options ...RemoteModuleOption,
) (ModuleSet, error)

NewModuleSetForRemoteModule is a convenience function that build a ModuleSet for for a single remote Module based on ModuleKey.

The remote Module is targeted. All of the remote Module's transitive dependencies are automatically added as non-targets.

type ModuleSetBuilder added in v1.32.0 

type ModuleSetBuilder interface {
	// AddLocalModule adds a new local Module for the given Bucket.
	//
	// The Bucket used to construct the module will only be read for .proto files,
	// license file(s), and documentation file(s).
	//
	// The BucketID is required. If LocalModuleWithModuleFullName.* is used, the OpaqueID will
	// use this ModuleFullName, otherwise the OpaqueID will be the BucketID.
	//
	// The dependencies of the Module are unknown, since bufmodule does not parse configuration,
	// and therefore the dependencies of the Module are *not* automatically added to the ModuleSet.
	//
	// If you are using a v1 buf.yaml-backed Module, be sure to use LocalModuleWithBufYAMLObjectData and
	// LocalModuleWithBufLockObjectData!
	//
	// Returns the same ModuleSetBuilder.
	AddLocalModule(
		bucket storage.ReadBucket,
		bucketID string,
		isTarget bool,
		options ...LocalModuleOption,
	) ModuleSetBuilder

	// specific Module will be targeted, while its dependencies will not be.
	//
	// Returns the same ModuleSetBuilder.
	AddRemoteModule(
		moduleKey ModuleKey,
		isTarget bool,
		options ...RemoteModuleOption,
	) ModuleSetBuilder
	// Build builds the Modules into a ModuleSet.
	//
	// Any errors from Add* calls will be returned here as well.
	//
	// For future consideration, `Build` can take ...buildOption. A use case for this
	// would be for workspaces to have a unified/top-level README and/or LICENSE file.
	// The workspace at build time can pass `BuildWithREADME` and/or `BuildWithLicense` for
	// the module set. Then each module in the module set can refer to this through the module
	// set as needed.
	Build() (ModuleSet, error)
	// contains filtered or unexported methods
}

ModuleSetBuilder builds ModuleSets.

It is the effective primary entrypoint for this package.

Modules are either targets or non-targets. A target Module is a module that we are directly targeting for operations. Targets the specific Modules within a Workspace that you are targeting.

Modules are also either local or remote.

A local Module is one which was built from sources from the "local context", such a Workspace containing Modules, or a ModuleNode in a CreateCommiteRequest. Local Modules are important for understanding what Modules to push, and what modules to check declared dependencies for unused dependencies.

A remote Module is one which was not contained in the local context, such as dependencies specified in a buf.lock (with no correspoding Module in the Workspace), or a DepNode in a CreateCommitRequest with no corresponding ModuleNode. A module retrieved from a ModuleDataProvider via a ModuleKey is always remote.

func NewModuleSetBuilder added in v1.32.0 

func NewModuleSetBuilder(
	ctx context.Context,
	tracer tracing.Tracer,
	moduleDataProvider ModuleDataProvider,
	commitProvider CommitProvider,
) ModuleSetBuilder

NewModuleSetBuilder returns a new ModuleSetBuilder.

type ModuleVisibility added in v1.32.0 

type ModuleVisibility int

ModuleVisibility is the visibility of a Module on a registry.

Only used for Upload for now.

func ParseModuleVisibility added in v1.32.0 

func ParseModuleVisibility(s string) (ModuleVisibility, error)

ParseModuleVisibility parses the ModuleVisibility from the string.

type NoProtoFilesError added in v1.32.0 

type NoProtoFilesError struct {
	// OpaqueID is the OpaqueID of the Module that has no .proto files.
	//
	// A well-formed NoProtoFilesError will have a non-empty OpaqueID.
	OpaqueID string
}

NoProtoFilesError is the error returned if a Module has no .proto files.

This check is done as part of ModuleReadBucket.Walks.

func (*NoProtoFilesError) Error added in v1.32.0 

func (n *NoProtoFilesError) Error() string

Error implements the error interface.

type ObjectData added in v1.32.0 

type ObjectData interface {
	// Name returns the file name.
	//
	// Always non-empty.
	Name() string
	// Data returns the file data.
	Data() []byte
}

ObjectData is individual file data.

It matches bufconfig.ObjectData, but is also defined here to avoid circular dependencies. As opposed to most of our interfaces, it does not have a private method limiting its implementation to this package.

registry-proto Files can be converted into ObjectDatas.

func NewObjectData added in v1.32.0 

func NewObjectData(name string, data []byte) (ObjectData, error)

type ParseError added in v1.32.0 

type ParseError struct {
	// contains filtered or unexported fields
}

ParseError is an error that occurred during parsing.

This is returned by all Parse.* functions in this package.

func (*ParseError) Error added in v1.32.0 

func (p *ParseError) Error() string

Error implements the error interface.

func (*ParseError) Input added in v1.32.0 

func (p *ParseError) Input() string

Input returns the input string that was attempted to be parsed.

func (*ParseError) Unwrap added in v1.32.0 

func (p *ParseError) Unwrap() error

Unwrap returns the underlying error.

type RegistryCommitID added in v1.32.0 

type RegistryCommitID struct {
	Registry string
	CommitID uuid.UUID
}

RegistryCommitID is the pair of a Commit ID with the registry the commit belongs to.

We need this to be a public, comparable type, as we use it in the GraphProvider.

func ModuleKeyToRegistryCommitID added in v1.32.0 

func ModuleKeyToRegistryCommitID(moduleKey ModuleKey) RegistryCommitID

ModuleKeyToRegistryCommitID converts the ModuleKey to a RegistryCommitID.

func NewRegistryCommitID added in v1.32.0 

func NewRegistryCommitID(registry string, commitID uuid.UUID) RegistryCommitID

NewRegistryCommitID returns a new RegistryCommitID.

type RemoteDep added in v1.32.0 

type RemoteDep interface {
	// All RemoteDeps will have a ModuleFullName, as they are remote.
	Module

	// IsDirect returns true if the remote dependency is a direct dependency of a Module in the ModuleSet.
	IsDirect() bool
	// contains filtered or unexported methods
}

RemoteDep is a remote dependency of some local Module in a ModuleSet.

This is different than ModuleDep in that it doesn't specify the parent Module. There could be multiple modules that are the parents of a given RemoteDep.

We don't care about targeting here - we want to know the remote dependencies for purposes such as figuring out what dependencies are unused and can be pruned.

func RemoteDepsForModuleSet added in v1.32.0 

func RemoteDepsForModuleSet(moduleSet ModuleSet) ([]RemoteDep, error)

RemoteDepsForModuleSet returns the remote dependencies of the local Modules in the ModuleSet.

Sorted by ModuleFullName.

TODO FUTURE: This needs a LOT of testing.

func RemoteDepsForModules added in v1.32.0 

func RemoteDepsForModules(modules []Module) ([]RemoteDep, error)

RemoteDepsForModules returns the remote dependencies of the local Modules.

Sorted by ModuleFullName.

This is used in situations where we have already filtered a ModuleSet down to a specific set of modules, such as in the Uploader. Generally, you want to use RemoteDepsForModuleSet.

This function may validate that all Modules are from the same ModuleSet, although it currently does not.

TODO FUTURE: This needs a LOT of testing.

type RemoteModuleOption added in v1.32.0 

type RemoteModuleOption func(*remoteModuleOptions)

RemoteModuleOption is an option for AddRemoteModule.

func RemoteModuleWithTargetPaths added in v1.32.0 

func RemoteModuleWithTargetPaths(
	targetPaths []string,
	targetExcludePaths []string,
) RemoteModuleOption

RemoteModuleWithTargetPaths returns a new RemoteModuleOption that specifically targets the given paths, and specifically excludes the given paths.

Only valid for a targeted Module. If this option is given to a non-target Module, this will result in an error during Build().

type UploadOption added in v1.32.0 

type UploadOption func(*uploadOptions)

UploadOption is an option for an Upload.

func UploadWithCreateIfNotExist added in v1.32.0 

func UploadWithCreateIfNotExist(createModuleVisibility ModuleVisibility, createDefaultLabel string) UploadOption

UploadWithCreateIfNotExist returns a new UploadOption that will result in the Modules being created on the registry with the given visibility and default label if they do not exist. If the default label name is not provided, the module will be created with the default label "main".

func UploadWithExcludeUnnamed added in v1.33.0 

func UploadWithExcludeUnnamed() UploadOption

UploadWithExcludeUnnamed returns a new UploadOption that will exclude unnamed modules.

func UploadWithLabels added in v1.32.0 

func UploadWithLabels(labels ...string) UploadOption

UploadWithLabels returns a new UploadOption that adds the given labels.

This can be called multiple times. The unique result set of labels will be used. We only ever allow one of labels or tags to be set.

func UploadWithSourceControlURL added in v1.32.0 

func UploadWithSourceControlURL(sourceControlURL string) UploadOption

UploadWithSourceControlURL returns a new UploadOption that will set the source control url for the module contents uploaded.

func UploadWithTags added in v1.32.0 

func UploadWithTags(tags ...string) UploadOption

UploadWithTags returns a new UploadOption that adds the given tags. This is handled separately from labels because we need to resolve the default label(s) when uploading.

This can be called multiple times. The unique result set of tags will be used. We only ever allow one of labels or tags to be set.

type UploadOptions added in v1.32.0 

type UploadOptions interface {
	// Labels returns the unique and sorted set of labels to add.
	// Labels are set using the `--label` flag when calling `buf push` and represent the
	// labels that are set when uploading module content.
	Labels() []string
	// CreateIfNotExist says to create Modules if they do not exist on the registry.
	CreateIfNotExist() bool
	// CreateModuleVisibility returns the visibility to create Modules with.
	//
	// Will always be present if CreateIfNotExist() is true.
	CreateModuleVisibility() ModuleVisibility
	// CreateDefaultLabel returns the default label to create Modules with. If this is an
	// emptry string, then the Modules will be created with default label "main".
	CreateDefaultLabel() string
	// Tags returns unique and sorted set of tags to be added as labels.
	// Tags are set using the `--tag` flag when calling `buf push`, and represent labels
	// that are set **in addition to** the default label when uploading module content.
	//
	// The `--tag` flag is a legacy flag that we are continuing supporting. We need to
	// handle tags differently from labels when uploading because we need to resolve the
	// default label for each module.
	//
	// We disallow the use of `--tag` when the modules we are uploading to do not all have
	// the same default label.
	Tags() []string
	// SourceControlURL returns the source control URL set by the user for the module
	// contents uploaded. We set the same source control URL for all module contents.
	SourceControlURL() string
	// ExcludeUnnamed returns whether to exclude unnamed modules.
	ExcludeUnnamed() bool
	// contains filtered or unexported methods
}

UploadOptions are the possible options for upload.

This is used by Uploader implementations.

func NewUploadOptions added in v1.32.0 

func NewUploadOptions(options []UploadOption) (UploadOptions, error)

NewUploadOptions returns a new UploadOptions.

type Uploader added in v1.32.0 

type Uploader interface {
	// Upload uploads the given ModuleSet.
	Upload(ctx context.Context, moduleSet ModuleSet, options ...UploadOption) ([]Commit, error)
}

Uploader uploads ModuleSets. 

var (
	// NopUploader is a no-op Uploader.
	NopUploader Uploader = nopUploader{}
)

type WalkFileInfosOption added in v1.32.0 

type WalkFileInfosOption func(*walkFileInfosOptions)

WalkFileInfosOption is an option for WalkFileInfos

func WalkFileInfosWithOnlyTargetFiles added in v1.32.0 

func WalkFileInfosWithOnlyTargetFiles() WalkFileInfosOption

WalkFileInfosWithOnlyTargetFiles returns a new WalkFileInfosOption that only walks the target files.

Source Files

View all Source files

Directories

Path Synopsis
cmd/buf-legacyfederation-go-data
cmd/buf-digest
cmd/buf-new-commit-id

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.