Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MalformedDep ¶
type MalformedDep interface {
// ModuleRef is the module ref information of the malformed dep.
//
// Always present.
ModuleRef() bufmodule.ModuleRef
// Type is why this dep was malformed.
//
// Always present.
Type() MalformedDepType
// contains filtered or unexported methods
}
MalformedDep is a dep that was malformed in some way in the buf.yaml. It provides the module ref information and the malformed dep type.
func MalformedDepsForWorkspace ¶
func MalformedDepsForWorkspace(workspace Workspace) ([]MalformedDep, error)
MalformedDepsForWorkspace gets the MalformedDeps for the workspace.
type MalformedDepType ¶
type MalformedDepType int
MalformedDepType is the type of malformed dep.
const ( // MalformedDepTypeUnused says that the dep was declared in the buf.yaml but was not used. // // A dep is not used if no .proto file references it, and the dep is not a local Module within the Workspace. // // We ignore local Modules within the Workspace as v1 buf.yamls needed to declare deps within the Workspace, // and there's no easy way for us to determine if a dep is needed or not within our current // Workspace/Module model. We could get more complicated and warn if you are using a v2 buf.lock // and have deps on local Modules, but there's little benefit. MalformedDepTypeUnused MalformedDepType = iota + 1 )
type Workspace ¶
type Workspace interface {
bufmodule.ModuleSet
// GetLintConfigForOpaqueID gets the LintConfig for the OpaqueID, if the OpaqueID
// represents a Module within the workspace.
//
// This will be the default value for Modules that didn't have an associated config,
// such as Modules read from buf.lock files. These Modules will not be target Modules
// in the workspace. This should result in items such as the linter or breaking change
// detector ignoring these configs anyways.
//
// 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.
//
// Note that we originally designed exposing of Configs as:
//
// type WorkspaceModule interface {
// bufmodule.Module
// LintConfig() LintConfig
// }
//
// However, this would mean that Workspace would not inherit ModuleSet, as we'd
// want to create GetWorkspaceModule.* functions instead of GetModule.* functions,
// and then provide a WorkpaceToModuleSet global function. This seems messier in
// practice than having users call GetLintConfigForOpaqueID(module.OpaqueID())
// in the situations where they need configuration.
GetLintConfigForOpaqueID(opaqueID string) bufconfig.LintConfig
// GetLintConfigForOpaqueID gets the LintConfig for the OpaqueID, if the OpaqueID
// represents a Module within the workspace.
//
// This will be the default value for Modules that didn't have an associated config,
// such as Modules read from buf.lock files. These Modules will not be target Modules
// in the workspace. This should result in items such as the linter or breaking change
// detector ignoring these configs anyways.
GetBreakingConfigForOpaqueID(opaqueID string) bufconfig.BreakingConfig
// ConfiguredDepModuleRefs returns the configured dependencies of the Workspace as ModuleRefs.
//
// These come from buf.yaml files.
//
// The ModuleRefs in this list will be unique by ModuleFullName. If there are two ModuleRefs
// in the buf.yaml with the same ModuleFullName but different Refs, an error will be given
// at workspace constructions. For example, with v1 buf.yaml, this is a union of the deps in
// the buf.yaml files in the workspace. If different buf.yamls had different refs, an error
// will be returned - we have no way to resolve what the user intended.
//
// Sorted.
ConfiguredDepModuleRefs() []bufmodule.ModuleRef
// IsV2 signifies if this module was created from a v2 buf.yaml.
//
// THIS SHOULD ONLY BE USED IN EXTREMELY LIMITED SITUATIONS. The codebase should generally
// handle v1 vs v2 transparently. Right now, this is only approved to be used in push
// when we want to know whether we need to print out only CommitIDs. Any other usages
// need to be evaluated.
IsV2() bool
// contains filtered or unexported methods
}
Workspace is a buf workspace.
It is a bufmodule.ModuleSet with associated configuration.
See ModuleSet helper functions for many of your needs. Some examples:
- bufmodule.ModuleSetToModuleReadBucketWithOnlyProtoFiles
- bufmodule.ModuleSetToTargetModules
- bufmodule.ModuleSetRemoteDepsOfLocalModules - gives you exact deps to put in buf.lock
To get a specific file from a Workspace:
moduleReadBucket := bufmodule.ModuleSetToModuleReadBucketWithOnlyProtoFiles(workspace) fileInfo, err := moduleReadBucket.GetFileInfo(ctx, path)
type WorkspaceBucketAndModuleKeyOption ¶
type WorkspaceBucketAndModuleKeyOption interface {
WorkspaceBucketOption
WorkspaceModuleKeyOption
}
WorkspaceOption is an option for a new Workspace created by either a Bucket or ModuleKey.
func WithConfigOverride ¶
func WithConfigOverride(configOverride string) WorkspaceBucketAndModuleKeyOption
If used with NewWorkspaceForModuleKey, this has no effect on the build, i.e. excludes are not respected, and the module name is ignored. This matches old behavior.
This implements the deprected --config flag.
See bufconfig.GetBufYAMLFileForPrefixOrOverride for more details.
*** DO NOT USE THIS OUTSIDE OF THE CLI AND/OR IF YOU DON'T UNDERSTAND IT. *** *** DO NOT ADD THIS TO ANY NEW COMMANDS. ***
Current comments that use this: build, breaking, lint, generate, format, export, ls-breaking-rules, ls-lint-rules.
type WorkspaceBucketOption ¶
type WorkspaceBucketOption interface {
// contains filtered or unexported methods
}
WorkspaceBucketOption is an option for a new Workspace created by a Bucket.
func WithIgnoreAndDisallowV1BufWorkYAMLs ¶
func WithIgnoreAndDisallowV1BufWorkYAMLs() WorkspaceBucketOption
WithIgnoreAndDisallowV1BufWorkYAMLs returns a new WorkspaceBucketOption that says to ignore dependencies from buf.work.yamls at the root of the bucket, and to also disallow directories with buf.work.yamls to be directly targeted.
This is used for v1 updates with buf mod prune and buf mod update.
A the root of the bucket targets a buf.work.yaml, but the targetSubDirPath targets a module, this is allowed.
Example: ./buf.work.yaml, targetSubDirPath = foo/bar, foo/bar/buf.yaml and foo/bar/buf.lock v1 This will result in the dependencies from buf.work.yaml being ignored, and a Workspace with just the Module at foo/bar plus the dependencies from foo/bar/buf.lock being added.
Example: ./buf.work.yaml, targetSubDirPath = . This will result in an error.
Example: ./buf.yaml v1. This is fine.
func WithProtoFileTargetPath ¶
func WithProtoFileTargetPath(protoFileTargetPath string, includePackageFiles bool) WorkspaceBucketOption
WithProtoFileTargetPath returns a new WorkspaceBucketOption 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 WithTargetPaths - only one of these can have a non-empty value.
This is used for ProtoFileRefs only. Do not use this otherwise.
type WorkspaceDepManager ¶
type WorkspaceDepManager interface {
// BufLockFileDigestType returns the DigestType that the buf.lock file expects.
BufLockFileDigestType() bufmodule.DigestType
// ExisingBufLockFileDepModuleKeys returns the ModuleKeys from the buf.lock file.
ExistingBufLockFileDepModuleKeys(ctx context.Context) ([]bufmodule.ModuleKey, error)
// UpdateBufLockFile updates the lock file that backs the Workspace to contain exactly
// the given ModuleKeys.
//
// If a buf.lock does not exist, one will be created.
UpdateBufLockFile(ctx context.Context, depModuleKeys []bufmodule.ModuleKey) error
// ConfiguredDepModuleRefs returns the configured dependencies of the Workspace as ModuleRefs.
//
// These come from buf.yaml files.
//
// The ModuleRefs in this list will be unique by ModuleFullName. If there are two ModuleRefs
// in the buf.yaml with the same ModuleFullName but different Refs, an error will be given
// at workspace constructions. For example, with v1 buf.yaml, this is a union of the deps in
// the buf.yaml files in the workspace. If different buf.yamls had different refs, an error
// will be returned - we have no way to resolve what the user intended.
//
// Sorted.
ConfiguredDepModuleRefs(ctx context.Context) ([]bufmodule.ModuleRef, error)
// contains filtered or unexported methods
}
WorkspaceDepManager is a workspace that can be updated.
A workspace can be updated if it was backed by a v2 buf.yaml, or a single, targeted, local Module from defaults or a v1beta1/v1 buf.yaml exists in the Workspace. Config overrides can also not be used, but this is enforced via the WorkspaceBucketOption/WorkspaceDepManagerBucketOption difference.
buf.work.yamls are ignored when constructing an WorkspaceDepManager.
type WorkspaceDepManagerProvider ¶
type WorkspaceDepManagerProvider interface {
// Note this is the same logic as if WithIgnoreAndDisallowV1BufWorkYAMLs is applied with WorkspaceProvider!! If you want an equivalent
// Workspace, you need to use this option!
//
// All parsing of configuration files is done behind the scenes here.
GetWorkspaceDepManager(
ctx context.Context,
bucket storage.ReadWriteBucket,
bucketTargeting buftarget.BucketTargeting,
) (WorkspaceDepManager, error)
}
WorkspaceDepManagerProvider provides WorkspaceDepManagers.
func NewWorkspaceDepManagerProvider ¶
func NewWorkspaceDepManagerProvider( logger *zap.Logger, tracer tracing.Tracer, ) WorkspaceDepManagerProvider
NewWorkspaceDepManagerProvider returns a new WorkspaceDepManagerProvider.
type WorkspaceModuleKeyOption ¶
type WorkspaceModuleKeyOption interface {
// contains filtered or unexported methods
}
WorkspaceModuleKeyOption is an option for a new Workspace created by a ModuleKey.
func WithTargetPaths ¶
func WithTargetPaths(targetPaths []string, targetExcludePaths []string) WorkspaceModuleKeyOption
Note these paths need to have the path/to/module stripped, and then each new path filtered to the specific module it applies to. If some modules do not have any target paths, but we specified WorkspaceWithTargetPaths, then those modules need to be built as non-targeted.
These paths have to be within the subDirPath, if it exists.
type WorkspaceProvider ¶
type WorkspaceProvider interface {
// GetWorkspaceForBucket returns a new Workspace for the given Bucket.
//
// If the underlying bucket has a v2 buf.yaml at the root, this builds a Workspace for this buf.yaml,
// using TargetSubDirPath for targeting.
//
// If the underlying bucket has a buf.work.yaml at the root, this builds a Workspace with all the modules
// specified in the buf.work.yaml, using TargetSubDirPath for targeting.
//
// Otherwise, this builds a Workspace with a single module at the TargetSubDirPath (which may be "."),
// assuming v1 defaults.
//
// If a config override is specified, all buf.work.yamls are ignored. If the config override is v1,
// this builds a single module at the TargetSubDirPath, if the config override is v2, the builds
// at the root, using TargetSubDirPath for targeting.
//
// All parsing of configuration files is done behind the scenes here.
GetWorkspaceForBucket(
ctx context.Context,
bucket storage.ReadBucket,
bucketTargeting buftarget.BucketTargeting,
options ...WorkspaceBucketOption,
) (Workspace, error)
// GetWorkspaceForModuleKey wraps the ModuleKey into a workspace, returning defaults
// for config values, and empty ConfiguredDepModuleRefs.
//
// This is useful for getting Workspaces for remote modules, but you still need
// associated configuration.
GetWorkspaceForModuleKey(
ctx context.Context,
moduleKey bufmodule.ModuleKey,
options ...WorkspaceModuleKeyOption,
) (Workspace, error)
}
WorkspaceProvider provides Workspaces and UpdateableWorkspaces.
func NewWorkspaceProvider ¶
func NewWorkspaceProvider( logger *zap.Logger, tracer tracing.Tracer, graphProvider bufmodule.GraphProvider, moduleDataProvider bufmodule.ModuleDataProvider, commitProvider bufmodule.CommitProvider, ) WorkspaceProvider
NewWorkspaceProvider returns a new WorkspaceProvider.
Source Files