bufmodule

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
}

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
}

type CommitOption func(*commitOptions)

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

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
}

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

type DigestType int

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
}

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

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
}

type FileType int

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

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

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

type LocalModuleOption func(*localModuleOptions)

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.
	//
	// This ID'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.
	//
	// This ID'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.
	//
	// 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
}

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

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
}

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

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
}

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
}

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
}

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

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
}

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
}

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
}

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
}

type ModuleVisibility int

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
}

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

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

type RegistryCommitID struct {
	Registry string
	CommitID uuid.UUID
}

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
}

type RemoteModuleOption func(*remoteModuleOptions)

type UploadOption func(*uploadOptions)

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
	// contains filtered or unexported methods
}

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

type WalkFileInfosOption func(*walkFileInfosOptions)