bufconfig

package
v1.42.0 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2024 License: Apache-2.0 Imports: 28 Imported by: 18

Documentation

Index

Constants

View Source 
const (
	// DefaultBufLockFileName is default buf.lock file name.
	DefaultBufLockFileName = "buf.lock"
)
View Source 
const (
	// DefaultBufWorkYAMLFileName is the default buf.work.yaml file name.
	DefaultBufWorkYAMLFileName = "buf.work.yaml"
)
View Source 
const (
	// DefaultBufYAMLFileName is the default buf.yaml file name.
	DefaultBufYAMLFileName = "buf.yaml"
)

Variables

View Source 
var (
	// AllFileVersions are all FileVersions.
	AllFileVersions = []FileVersion{
		FileVersionV1Beta1,
		FileVersionV1,
		FileVersionV2,
	}
)
View Source 
var (
	// ProtocProxyPluginNames are the names of the plugins that should be proxied through protoc
	// in the absence of a binary.
	ProtocProxyPluginNames = map[string]struct{}{
		"cpp":    {},
		"csharp": {},
		"java":   {},
		"js":     {},
		"objc":   {},
		"php":    {},
		"python": {},
		"pyi":    {},
		"ruby":   {},
		"kotlin": {},
		"rust":   {},
	}
)

Functions

func NewManagedOverrideRuleForFileOption added in v1.32.0 

func NewManagedOverrideRuleForFileOption(
	path string,
	moduleFullName string,
	fileOption FileOption,
	value interface{},
) (*managedOverrideRule, error)

NewFieldOptionOverrideRule returns a new ManagedOverrideRule for a file option.

func PutBufGenYAMLFileForPrefix added in v1.32.0 

func PutBufGenYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.WriteBucket,
	prefix string,
	bufYAMLFile BufGenYAMLFile,
) error

PutBufGenYAMLFileForPrefix puts the buf.gen.yaml file at the given bucket prefix.

The buf.gen.yaml file will be attempted to be written to prefix/buf.gen.yaml. The buf.gen.yaml file will be written atomically.

func PutBufLockFileForPrefix added in v1.32.0 

func PutBufLockFileForPrefix(
	ctx context.Context,
	bucket storage.WriteBucket,
	prefix string,
	bufLockFile BufLockFile,
) error

PutBufLockFileForPrefix puts the buf.lock file at the given bucket prefix.

The buf.lock file will be attempted to be written to prefix/buf.lock. The buf.lock file will be written atomically.

func PutBufWorkYAMLFileForPrefix added in v1.32.0 

func PutBufWorkYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.WriteBucket,
	prefix string,
	bufYAMLFile BufWorkYAMLFile,
) error

PutBufWorkYAMLFileForPrefix puts the buf.work.yaml file at the given bucket prefix.

The buf.work.yaml file will be attempted to be written to prefix/buf.work.yaml. The buf.work.yaml file will be written atomically.

func PutBufYAMLFileForPrefix added in v1.32.0 

func PutBufYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.WriteBucket,
	prefix string,
	bufYAMLFile BufYAMLFile,
) error

PutBufYAMLFileForPrefix puts the buf.yaml file at the given bucket prefix.

The buf.yaml file will be attempted to be written to prefix/buf.yaml. The buf.yaml file will be written atomically.

func WalkFileInfos added in v1.32.0 

func WalkFileInfos(
	ctx context.Context,
	readBucket storage.ReadBucket,
	f func(path string, fileInfo FileInfo) error,
) error

WalkFileInfos walks all the FileInfos in the ReadBucket.

The path will be normalized.

func WriteBufGenYAMLFile added in v1.32.0 

func WriteBufGenYAMLFile(writer io.Writer, bufGenYAMLFile BufGenYAMLFile) error

WriteBufGenYAMLFile writes the BufGenYAMLFile to the io.Writer.

func WriteBufLockFile added in v1.32.0 

func WriteBufLockFile(writer io.Writer, bufLockFile BufLockFile) error

WriteBufLockFile writes the BufLockFile to the io.Writer.

func WriteBufWorkYAMLFile added in v1.32.0 

func WriteBufWorkYAMLFile(writer io.Writer, bufWorkYAMLFile BufWorkYAMLFile) error

WriteBufWorkYAMLFile writes the buf.work.yaml to the io.Writer.

func WriteBufYAMLFile added in v1.32.0 

func WriteBufYAMLFile(writer io.Writer, bufYAMLFile BufYAMLFile) error

WriteBufYAMLFile writes the BufYAMLFile to the io.Writer.

Types

type BreakingConfig added in v1.32.0 

type BreakingConfig interface {
	CheckConfig

	IgnoreUnstablePackages() bool
	// contains filtered or unexported methods
}

BreakingConfig is breaking configuration for a specific Module. 

var (
	// DefaultBreakingConfigV1 is the default breaking config for v1.
	DefaultBreakingConfigV1 BreakingConfig = NewBreakingConfig(
		defaultCheckConfigV1,
		false,
	)

	// DefaultBreakingConfigV2 is the default breaking config for v1.
	DefaultBreakingConfigV2 BreakingConfig = NewBreakingConfig(
		defaultCheckConfigV2,
		false,
	)
)

func NewBreakingConfig added in v1.32.0 

func NewBreakingConfig(
	checkConfig CheckConfig,
	ignoreUnstablePackages bool,
) BreakingConfig

NewBreakingConfig returns a new BreakingConfig.

type BufGenYAMLFile added in v1.32.0 

type BufGenYAMLFile interface {
	File

	// GenerateConfig returns the generate config.
	GenerateConfig() GenerateConfig
	// InputConfigs returns the input configs, which can be empty.
	InputConfigs() []InputConfig
	// contains filtered or unexported methods
}

BufGenYAMLFile represents a buf.gen.yaml file.

For v2, generation configuration has been merged into BufYAMLFiles.

func GetBufGenYAMLFileForPrefix added in v1.32.0 

func GetBufGenYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (BufGenYAMLFile, error)

GetBufGenYAMLFileForPrefix gets the buf.gen.yaml file at the given bucket prefix.

The buf.gen.yaml file will be attempted to be read at prefix/buf.gen.yaml.

func NewBufGenYAMLFile added in v1.32.0 

func NewBufGenYAMLFile(
	fileVersion FileVersion,
	generateConfig GenerateConfig,
	inputConfigs []InputConfig,
) BufGenYAMLFile

NewBufGenYAMLFile returns a new BufGenYAMLFile. It is validated given each parameter is validated.

func ReadBufGenYAMLFile added in v1.32.0 

func ReadBufGenYAMLFile(reader io.Reader) (BufGenYAMLFile, error)

ReadBufGenYAMLFile reads the BufGenYAMLFile from the io.Reader.

type BufLockFile added in v1.32.0 

type BufLockFile interface {
	File

	// DepModuleKeys returns the ModuleKeys representing the dependencies as specified in the buf.lock file.
	//
	// All ModuleKeys will have unique ModuleFullNames.
	// ModuleKeys are sorted by ModuleFullName.
	//
	// Files with FileVersionV1Beta1 or FileVersionV1 will only have ModuleKeys with Digests of DigestTypeB4,
	// while Files with FileVersionV2 will only have ModuleKeys with Digests of DigestTypeB5.
	DepModuleKeys() []bufmodule.ModuleKey
	// contains filtered or unexported methods
}

BufLockFile represents a buf.lock file.

func GetBufLockFileForPrefix added in v1.32.0 

func GetBufLockFileForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
	options ...BufLockFileOption,
) (BufLockFile, error)

GetBufLockFileForPrefix gets the buf.lock file at the given bucket prefix.

The buf.lock file will be attempted to be read at prefix/buf.lock.

Note that digests are lazily-loaded; if you need to ensure that all digests are valid, run ValidateFileDigests().

func NewBufLockFile added in v1.32.0 

func NewBufLockFile(fileVersion FileVersion, depModuleKeys []bufmodule.ModuleKey) (BufLockFile, error)

NewBufLockFile returns a new validated BufLockFile.

Note that digests are lazily-loaded; if you need to ensure that all digests are valid, run ValidateBufLockFileDigests().

func ReadBufLockFile added in v1.32.0 

func ReadBufLockFile(ctx context.Context, reader io.Reader, fileName string, options ...BufLockFileOption) (BufLockFile, error)

ReadBufLockFile reads the BufLockFile from the io.Reader.

fileName may be empty.

type BufLockFileOption added in v1.32.0 

type BufLockFileOption func(*bufLockFileOptions)

BufLockFileOption is an option for getting a new BufLockFile via Get or Read.

func BufLockFileWithDigestResolver added in v1.32.0 

func BufLockFileWithDigestResolver(
	digestResolver func(ctx context.Context, remote string, commitID uuid.UUID) (bufmodule.Digest, error),
) BufLockFileOption

BufLockFileWithDigestResolver returns a new BufLockFileOption that will resolve digests from commits.

Pre-approximately-v1.10 of the buf CLI, we did not store digests in buf.lock files, we only stored commits. In these situations, we need to get digests from the BSR based on the commit. All of our new code relies on digests being present, but we are able to backfill them via the CommitService. By having this option, this allows us to do this backfill when reading buf.lock files created by any version of the buf CLI.

TODO FUTURE: use this for all reads of buf.locks, including migrate, prune, update, etc. This really almost should not be an option.

type BufWorkYAMLFile added in v1.32.0 

type BufWorkYAMLFile interface {
	File

	// DirPaths returns all the directory paths specified in buf.work.yaml,
	// relative to the directory with buf.work.yaml. The following are guaranteed:
	//
	// - There is at least one path, i.e. DirPaths() will never be empty..
	// - There are no duplicate paths - all values of DirPaths() are unique.
	// - No path contains another path, i.e. "foo" and "foo/bar" will not be in DirPaths().
	// - "." is not in DirPaths().
	// - Each path is normalized and validated, because this is guaranteed at the
	//   construction time of a BufWorkYAMLFile.
	//
	// Returned paths are sorted.
	DirPaths() []string
	// contains filtered or unexported methods
}

BufWorkYAMLFile represents a buf.work.yaml file.

For v2, buf.work.yaml files have been eliminated. There was never a v1beta1 buf.work.yaml.

func GetBufWorkYAMLFileForPrefix added in v1.32.0 

func GetBufWorkYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (BufWorkYAMLFile, error)

GetBufWorkYAMLFileForPrefix gets the buf.work.yaml file at the given bucket prefix.

The buf.work.yaml file will be attempted to be read at prefix/buf.work.yaml.

func NewBufWorkYAMLFile added in v1.32.0 

func NewBufWorkYAMLFile(fileVersion FileVersion, dirPaths []string) (BufWorkYAMLFile, error)

NewBufWorkYAMLFile returns a new validated BufWorkYAMLFile.

func ReadBufWorkYAMLFile added in v1.32.0 

func ReadBufWorkYAMLFile(reader io.Reader, fileName string) (BufWorkYAMLFile, error)

ReadBufWorkYAMLFile reads the buf.work.yaml file from the io.Reader.

fileName may be empty.

type BufYAMLFile added in v1.32.0 

type BufYAMLFile interface {
	File

	// ModuleConfigs returns the ModuleConfigs for the File.
	//
	// For v1 buf.yaml, this will only have a single ModuleConfig.
	//
	// This will always be non-empty.
	// All ModuleConfigs will have unique ModuleFullNames, but not necessarily
	// unique DirPaths.
	//
	// The module configs are sorted by DirPath. If two module configs have the
	// same DirPath, the order defined in the external file is used to break the tie.
	// For example, if in the buf.yaml there are:
	// - path: foo
	//   module: buf.build/acme/foobaz
	//   ...
	// - path: foo
	//   module: buf.build/acme/foobar
	//   ...
	// Then in ModuleConfigs, the config with buf.build/acme/foobaz still comes before buf.build/acme/foobar,
	// because it comes earlier in the buf.yaml. This also gives a deterministic order of ModuleConfigs.
	ModuleConfigs() []ModuleConfig
	// TopLevelLintConfig returns the top-level LintConfig for the File.
	//
	// For v1 buf.yaml files, there is only ever a single LintConfig, so this is returned.
	// For v2 buf.yaml files, if a top-level lint config exists, then it will be the top-level
	// lint config. Otherwise, this will return nil, so callers should be aware this may be
	// empty.
	TopLevelLintConfig() LintConfig
	// TopLevelBreakingConfig returns the top-level BreakingConfig for the File.
	//
	// For v1 buf.yaml files, there is only ever a single BreakingConfig, so this is returned.
	// For v2 buf.yaml files, if a top-level breaking config exists, then it will be the top-level
	// breaking config. Otherwise, this will return nil, so callers should be aware this may be
	// empty.
	TopLevelBreakingConfig() BreakingConfig
	// PluginConfigs returns the PluginConfigs for the File.
	//
	// For v1 buf.yaml files, this will always return nil.
	PluginConfigs() []PluginConfig
	// 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.
	// Sorted by ModuleFullName.
	ConfiguredDepModuleRefs() []bufmodule.ModuleRef
	//IncludeDocsLink specifies whether a top-level comment with a link to our public docs
	// should be included at the top of the buf.yaml file.
	IncludeDocsLink() bool
	// contains filtered or unexported methods
}

BufYAMLFile represents a buf.yaml file.

func GetBufYAMLFileForOverride added in v1.32.0 

func GetBufYAMLFileForOverride(override string) (BufYAMLFile, error)

GetBufYAMLFileForOverride get the buf.yaml file for either the usually-flag-based override.

  • If the override is set and ends in .json, .yaml, or .yml, the override is treated as a **direct file path on disk** and read (ie not via buckets).
  • If the override is otherwise non-empty, it is treated as raw data.

This function is the result of the endlessly annoying and shortsighted design decision that the original author of this repository made to allow overriding configuration files on the command line. Of course, the original author never envisioned buf.work.yamls, merging buf.work.yamls into buf.yamls, buf.gen.yamls, or anything of the like, and was very concentrated on "because Bazel."

func GetBufYAMLFileForPrefix added in v1.32.0 

func GetBufYAMLFileForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (BufYAMLFile, error)

GetBufYAMLFileForPrefix gets the buf.yaml file at the given bucket prefix.

The buf.yaml file will be attempted to be read at prefix/buf.yaml.

func GetBufYAMLFileForPrefixOrOverride added in v1.32.0 

func GetBufYAMLFileForPrefixOrOverride(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
	override string,
) (BufYAMLFile, error)

GetBufYAMLFileForOverride get the buf.yaml file for either the usually-flag-based override, or if the override is not set, falls back to the prefix.

func NewBufYAMLFile added in v1.32.0 

func NewBufYAMLFile(
	fileVersion FileVersion,
	moduleConfigs []ModuleConfig,
	pluginConfigs []PluginConfig,
	configuredDepModuleRefs []bufmodule.ModuleRef,
	options ...BufYAMLFileOption,
) (BufYAMLFile, error)

NewBufYAMLFile returns a new validated BufYAMLFile.

This should generally not be used outside of testing - use GetBufYAMLFileForPrefix instead.

func ReadBufYAMLFile added in v1.32.0 

func ReadBufYAMLFile(reader io.Reader, fileName string) (BufYAMLFile, error)

ReadBufYAMLFile reads the BufYAMLFile from the io.Reader.

fileName may be empty.

type BufYAMLFileOption added in v1.36.0 

type BufYAMLFileOption func(*bufYAMLFileOptions)

BufYAMLFileOption is an option for a new BufYAMLFile 

func BufYAMLFileWithIncludeDocsLink() BufYAMLFileOption

BufYAMLFileWithIncludeDocsLink returns a new BufYAMLFileOption that specifies including a comment with a link to the public docs for the appropriate buf.yaml version at the top of the buf.yaml file.

type CheckConfig added in v1.32.0 

type CheckConfig interface {
	// FileVersion returns the file version that this configuration was derived from.
	//
	// We don't want to have to take FileVersion into account for *Configs, however
	// with lint and breaking configurations, the FileVersion changes the interpretation
	// of the IDs and categories.
	FileVersion() FileVersion

	// Disabled says whether or not the given check should be entirely disabled.
	//
	// This happens if an ignore path matches a module directory, which is valid
	// in cases such as:
	//
	//   version: v2
	//   modules:
	//     - path: proto
	//     - path: vendor
	//   lint:
	//     ignore:
	//       - vendor
	//
	// Or:
	//
	//   version: v2
	//   modules:
	//     - path: proto
	//     - path: vendor
	//       lint:
	//         ignore:
	//           - vendor
	//
	// We no longer produce an error in this case. Instead, we set Disabled(), and
	// do not run checks. This means that the following is no longer an error:
	//
	//   version: v1
	//   lint:
	//     ignore:
	//       - .
	//
	// We could make it so that ignore == moduleDirPath is only allowed for v2, however
	// this feels like overkill, so we're just going to keep this consistent for v1
	// and v2.
	Disabled() bool
	// Sorted.
	UseIDsAndCategories() []string
	// Sorted
	ExceptIDsAndCategories() []string
	// Paths are specific to the Module. Users cannot ignore paths outside of their modules for check
	// configs, which includes any imports from outside of the module.
	// Paths are relative to roots.
	// Paths are sorted.
	IgnorePaths() []string
	// Paths are specific to the Module. Users cannot ignore paths outside of their modules for
	// check configs, which includes any imports from outside of the module.
	// Paths are relative to roots.
	// Paths are sorted.
	IgnoreIDOrCategoryToPaths() map[string][]string
	// DisableBuiltin says to disable the Rules and Categories builtin to the Buf CLI and only
	// use plugins.
	//
	// This will make it as if these rules did not exist.
	DisableBuiltin() bool
	// contains filtered or unexported methods
}

CheckConfig is the common interface for the configuration shared by LintConfig and BreakingConfig.

func NewEnabledCheckConfig added in v1.32.0 

func NewEnabledCheckConfig(
	fileVersion FileVersion,
	use []string,
	except []string,
	ignore []string,
	ignoreOnly map[string][]string,
	disableBuiltin bool,
) (CheckConfig, error)

NewEnabledCheckConfig returns a new enabled CheckConfig.

func NewEnabledCheckConfigForUseIDsAndCategories added in v1.32.0 

func NewEnabledCheckConfigForUseIDsAndCategories(
	fileVersion FileVersion,
	use []string,
	disableBuiltin bool,
) CheckConfig

NewEnabledCheckConfig returns a new enabled CheckConfig for only the use IDs and categories.

type FieldOption added in v1.32.0 

type FieldOption int

FieldOption is a field option. 

const (
	// FieldOptionUnspecified is an unspecified field option.
	FieldOptionUnspecified FieldOption = iota
	// FieldOptionJSType is the field option js_type.
	FieldOptionJSType
)

func (FieldOption) String added in v1.32.0 

func (f FieldOption) String() string

String implements fmt.Stringer.

type File added in v1.32.0 

type File interface {
	FileInfo

	// ObjectData returns the underlying ObjectData.
	//
	// This is non-nil on Files if they were created from storage.ReadBuckets. It is nil
	// if the File was created via a New constructor or Read method.
	//
	// This ObjectData is used for digest calculations.
	ObjectData() ObjectData
	// contains filtered or unexported methods
}

File is the common interface shared by all config files.

type FileInfo added in v1.32.0 

type FileInfo interface {
	// FileVersion returns the version of the file.
	FileVersion() FileVersion
	// FileType returns the type of the file.
	FileType() FileType
	// contains filtered or unexported methods
}

FileInfo contains information on a configuration file.

type FileOption added in v1.32.0 

type FileOption int

FileOption is a file option. 

const (
	// FileOptionUnspecified is an unspecified file option.
	FileOptionUnspecified FileOption = iota
	// FileOptionJavaPackage is the file option java_package.
	FileOptionJavaPackage
	// FileOptionJavaPackagePrefix is the file option java_package_prefix.
	FileOptionJavaPackagePrefix
	// FileOptionJavaPackageSuffix is the file option java_package_suffix.
	FileOptionJavaPackageSuffix
	// FileOptionJavaOuterClassname is the file option java_outer_classname.
	FileOptionJavaOuterClassname
	// FileOptionJavaMultipleFiles is the file option java_multiple_files.
	FileOptionJavaMultipleFiles
	// FileOptionJavaStringCheckUtf8 is the file option java_string_check_utf8.
	FileOptionJavaStringCheckUtf8
	// FileOptionOptimizeFor is the file option optimize_for.
	FileOptionOptimizeFor
	// FileOptionGoPackage is the file option go_package.
	FileOptionGoPackage
	// FileOptionGoPackagePrefix is the file option go_package_prefix.
	FileOptionGoPackagePrefix
	// FileOptionCcEnableArenas is the file option cc_enable_arenas.
	FileOptionCcEnableArenas
	// FileOptionObjcClassPrefix is the file option objc_class_prefix.
	FileOptionObjcClassPrefix
	// FileOptionCsharpNamespace is the file option csharp_namespace.
	FileOptionCsharpNamespace
	// FileOptionCsharpNamespacePrefix is the file option csharp_namespace_prefix.
	FileOptionCsharpNamespacePrefix
	// FileOptionPhpNamespace is the file option php_namespace.
	FileOptionPhpNamespace
	// FileOptionPhpMetadataNamespace is the file option php_metadata_namespace.
	FileOptionPhpMetadataNamespace
	// FileOptionPhpMetadataNamespaceSuffix is the file option php_metadata_namespace_suffix.
	FileOptionPhpMetadataNamespaceSuffix
	// FileOptionRubyPackage is the file option ruby_package.
	FileOptionRubyPackage
	// FileOptionRubyPackageSuffix is the file option ruby_package_suffix.
	FileOptionRubyPackageSuffix
)

func (FileOption) String added in v1.32.0 

func (f FileOption) String() string

String implements fmt.Stringer.

type FileType added in v1.32.0 

type FileType int

FileType is the type of a file. 

const (
	// FileTypeBufYAML represents buf.yaml files.
	FileTypeBufYAML FileType = iota + 1
	// FileTypeBufLock represents buf.lock files.
	FileTypeBufLock
	// FileTypeBufGenYAML represents buf.gen.yaml files.
	FileTypeBufGenYAML
	// FileTypeBufWorkYAML represents buf.work.yaml files.
	FileTypeBufWorkYAML
)

type FileVersion added in v1.32.0 

type FileVersion int

FileVersion is the version of a file. 

const (
	// FileVersionV1Beta represents v1beta1 files.
	FileVersionV1Beta1 FileVersion = iota + 1
	// FileVersionV1 represents v1 files.
	FileVersionV1
	// FileVersionV2 represents v2 files.
	FileVersionV2
)

func GetBufGenYAMLFileVersionForPrefix added in v1.32.0 

func GetBufGenYAMLFileVersionForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (FileVersion, error)

GetBufGenYAMLFileForPrefix gets the buf.gen.yaml file version at the given bucket prefix.

The buf.gen.yaml file will be attempted to be read at prefix/buf.gen.yaml.

func GetBufLockFileVersionForPrefix added in v1.32.0 

func GetBufLockFileVersionForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (FileVersion, error)

GetBufLockFileVersionForPrefix gets the buf.lock file version at the given bucket prefix.

The buf.lock file will be attempted to be read at prefix/buf.lock.

func GetBufWorkYAMLFileVersionForPrefix added in v1.32.0 

func GetBufWorkYAMLFileVersionForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (FileVersion, error)

GetBufWorkYAMLFileForPrefix gets the buf.work.yaml file version at the given bucket prefix.

The buf.work.yaml file will be attempted to be read at prefix/buf.work.yaml.

func GetBufYAMLFileVersionForPrefix added in v1.32.0 

func GetBufYAMLFileVersionForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (FileVersion, error)

GetBufYAMLFileForPrefix gets the buf.yaml file version at the given bucket prefix.

The buf.yaml file will be attempted to be read at prefix/buf.yaml.

func (FileVersion) String added in v1.32.0 

func (f FileVersion) String() string

String prints the string representation of the FileVersion.

This is used in buf.yaml, buf.gen.yaml, buf.work.yaml, and buf.lock files on disk.

type GenerateConfig added in v1.32.0 

type GenerateConfig interface {
	// CleanPluginOuts is whether to delete the output directories, zip files, or jar files before
	// generation is run.
	CleanPluginOuts() bool
	// GeneratePluginConfigs returns the plugin configurations. This will always be
	// non-empty. Zero plugin configs will cause an error at construction time.
	GeneratePluginConfigs() []GeneratePluginConfig
	// GenerateManagedConfig returns the managed mode configuration.
	// This may will never be nil.
	GenerateManagedConfig() GenerateManagedConfig
	// GenerateTypeConfig returns the types to generate code for. This overrides other type
	// filters from input configurations, which exist in v2.
	// This will always be nil in v2
	GenerateTypeConfig() GenerateTypeConfig
	// contains filtered or unexported methods
}

GenerateConfig is a generation configuration.

func NewGenerateConfig added in v1.32.0 

func NewGenerateConfig(
	cleanPluginOuts bool,
	generatePluginConfigs []GeneratePluginConfig,
	generateManagedConfig GenerateManagedConfig,
	generateTypeConfig GenerateTypeConfig,
) (GenerateConfig, error)

NewGenerateConfig returns a validated GenerateConfig.

type GenerateManagedConfig added in v1.32.0 

type GenerateManagedConfig interface {
	// Enabled returns whether managed mode is enabled.
	Enabled() bool
	// Disables returns the disable rules in the configuration.
	Disables() []ManagedDisableRule
	// Overrides returns the override rules in the configuration.
	Overrides() []ManagedOverrideRule
	// contains filtered or unexported methods
}

GenerateManagedConfig is a managed mode configuration.

func NewGenerateManagedConfig added in v1.32.0 

func NewGenerateManagedConfig(
	enabled bool,
	disables []ManagedDisableRule,
	overrides []ManagedOverrideRule,
) GenerateManagedConfig

NewGenerateManagedConfig returns a new GenerateManagedConfig.

type GeneratePluginConfig added in v1.32.0 

type GeneratePluginConfig interface {
	// Type returns the plugin type. This is never the zero value.
	Type() GeneratePluginConfigType
	// Name returns the plugin name. This is never empty.
	Name() string
	// Out returns the output directory for generation. This is never empty.
	Out() string
	// Opt returns the plugin options as a comma separated string.
	Opt() string
	// IncludeImports returns whether to generate code for imported files. This
	// is always false in v1.
	IncludeImports() bool
	// IncludeWKT returns whether to generate code for the well-known types.
	// This returns true only if IncludeImports returns true. This is always
	// false in v1.
	IncludeWKT() bool
	// Strategy returns the generation strategy.
	//
	// This is not empty only when the plugin is local, binary or protoc builtin.
	Strategy() GenerateStrategy
	// Path returns the path, including arguments, to invoke the binary plugin.
	//
	// This is not empty only when the plugin is local.
	Path() []string
	// ProtocPath returns a path to protoc, including any extra arguments.
	//
	// This is not empty only when the plugin is protoc-builtin.
	ProtocPath() []string
	// RemoteHost returns the remote host of the remote plugin.
	//
	// This is not empty only when the plugin is remote.
	RemoteHost() string
	// Revision returns the revision of the remote plugin.
	//
	// This is not empty only when the plugin is remote.
	Revision() int
	// contains filtered or unexported methods
}

GeneratePluginConfig is a configuration for a plugin.

func NewGeneratePluginConfigWithIncludeImportsAndWKT added in v1.37.0 

func NewGeneratePluginConfigWithIncludeImportsAndWKT(
	config GeneratePluginConfig,
	includeImports bool,
	includeWKT bool,
) (GeneratePluginConfig, error)

NewGeneratePluginConfigWithIncludeImportsAndWKT returns a GeneratePluginConfig the same as the input, with include imports and include wkt overridden.

func NewLocalGeneratePluginConfig added in v1.37.0 

func NewLocalGeneratePluginConfig(
	name string,
	out string,
	opt []string,
	includeImports bool,
	includeWKT bool,
	strategy *GenerateStrategy,
	path []string,
) (GeneratePluginConfig, error)

NewLocalGeneratePluginConfig returns a new GeneratePluginConfig for a local plugin.

func NewLocalOrProtocBuiltinGeneratePluginConfig added in v1.37.0 

func NewLocalOrProtocBuiltinGeneratePluginConfig(
	name string,
	out string,
	opt []string,
	includeImports bool,
	includeWKT bool,
	strategy *GenerateStrategy,
) (GeneratePluginConfig, error)

NewLocalOrProtocBuiltinGeneratePluginConfig returns a new GeneratePluginConfig for a local or protoc builtin plugin.

func NewProtocBuiltinGeneratePluginConfig added in v1.37.0 

func NewProtocBuiltinGeneratePluginConfig(
	name string,
	out string,
	opt []string,
	includeImports bool,
	includeWKT bool,
	strategy *GenerateStrategy,
	protocPath []string,
) (GeneratePluginConfig, error)

NewProtocBuiltinGeneratePluginConfig returns a new GeneratePluginConfig for a protoc builtin plugin.

func NewRemoteGeneratePluginConfig added in v1.37.0 

func NewRemoteGeneratePluginConfig(
	name string,
	out string,
	opt []string,
	includeImports bool,
	includeWKT bool,
	revision int,
) (GeneratePluginConfig, error)

NewRemoteGeneratePluginConfig returns a new GeneratePluginConfig for a remote plugin.

type GeneratePluginConfigType added in v1.37.0 

type GeneratePluginConfigType int

GeneratePluginConfigType is a generate plugin configuration type. 

const (
	// GeneratePluginConfigTypeRemote is the remote plugin config type.
	GeneratePluginConfigTypeRemote GeneratePluginConfigType = iota + 1
	// GeneratePluginConfigTypeLocal is the local plugin config type.
	GeneratePluginConfigTypeLocal
	// GeneratePluginConfigTypeProtocBuiltin is the protoc built-in plugin config type.
	GeneratePluginConfigTypeProtocBuiltin
	// GeneratePluginConfigTypeLocalOrProtocBuiltin is a special plugin config type. This type indicates
	// it is to be determined whether the plugin is local or protoc built-in.
	// We defer further classification to the plugin executor. In v2 the exact
	// plugin config type is always specified and it will never be just local.
	GeneratePluginConfigTypeLocalOrProtocBuiltin
)

type GenerateStrategy added in v1.32.0 

type GenerateStrategy int

GenerateStrategy is the generation strategy for a protoc plugin. 

const (
	// GenerateStrategyDirectory is the strategy to generate per directory.
	//
	// This is the default value for local plugins.
	GenerateStrategyDirectory GenerateStrategy = 1
	// GenerateStrategyAll is the strategy to generate with all files at once.
	//
	// This is the only strategy for remote plugins.
	GenerateStrategyAll GenerateStrategy = 2
)

type GenerateTypeConfig added in v1.32.0 

type GenerateTypeConfig interface {
	// If IncludeTypes returns a non-empty list, it means that only those types are
	// generated. Otherwise all types are generated.
	IncludeTypes() []string
	// contains filtered or unexported methods
}

GenerateTypeConfig is a type filter configuration.

func NewGenerateTypeConfig added in v1.32.0 

func NewGenerateTypeConfig(includeTypes []string) GenerateTypeConfig

NewGenerateTypeConfig returns a new GenerateTypeConfig.

type InputConfig added in v1.32.0 

type InputConfig interface {
	// Type returns the input type. This is never the zero value.
	Type() InputConfigType
	// Location returns the location for the input. This is never empty.
	Location() string
	// Compression returns the compression scheme, not empty only if format is
	// one of tarball, binary image, json image or text image.
	Compression() string
	// StripComponents returns the number of directories to strip for tar or zip
	// inputs, not empty only if format is tarball or zip archive.
	StripComponents() uint32
	// SubDir returns the subdirectory to use, not empty only if format is one
	// git repo, tarball and zip archive.
	SubDir() string
	// Branch returns the git branch to checkout out, not empty only if format is git.
	Branch() string
	// CommitOrTag returns the full commit hash or tag to checkout, not empty only if format is git.
	CommitOrTag() string
	// Ref returns the git ref to checkout, not empty only if format is git.
	Ref() string
	// Depth returns the depth to clone the git repo with, not empty only if format is git.
	Depth() *uint32
	// RecurseSubmodules returns whether to clone submodules recursively. Not empty
	// only if input if git.
	RecurseSubmodules() bool
	// IncludePackageFiles returns other files in the same package as the proto file,
	// not empty only if format is proto file.
	IncludePackageFiles() bool
	// TargetPaths returns paths to generate for. An empty slice means to generate for all paths.
	TargetPaths() []string
	// ExcludePaths returns paths not to generate for.
	ExcludePaths() []string
	// IncludeTypes returns the types to generate. An empty slice means to generate for all types.
	IncludeTypes() []string
	// contains filtered or unexported methods
}

InputConfig is an input configuration for code generation.

func NewBinaryImageInputConfig added in v1.32.0 

func NewBinaryImageInputConfig(
	location string,
	compression string,
) (InputConfig, error)

NewBinaryImageInputConfig returns an input config for a binary image.

func NewDirectoryInputConfig added in v1.32.0 

func NewDirectoryInputConfig(
	location string,
) (InputConfig, error)

NewDirectoryInputConfig returns an input config for a directory.

func NewGitRepoInputConfig added in v1.32.0 

func NewGitRepoInputConfig(
	location string,
	subDir string,
	branch string,
	commitOrTag string,
	ref string,
	depth *uint32,
	recurseSubModules bool,
) (InputConfig, error)

NewGitRepoInputConfig returns an input config for a git repo.

func NewJSONImageInputConfig added in v1.32.0 

func NewJSONImageInputConfig(
	location string,
	compression string,
) (InputConfig, error)

NewJSONImageInputConfig returns an input config for a JSON image.

func NewModuleInputConfig added in v1.32.0 

func NewModuleInputConfig(
	location string,
) (InputConfig, error)

NewModuleInputConfig returns an input config for a module.

func NewProtoFileInputConfig added in v1.32.0 

func NewProtoFileInputConfig(
	location string,
	includePackageFiles bool,
) (InputConfig, error)

NewProtoFileInputConfig returns an input config for a proto file.

func NewTarballInputConfig added in v1.32.0 

func NewTarballInputConfig(
	location string,
	subDir string,
	compression string,
	stripComponents uint32,
) (InputConfig, error)

NewTarballInputConfig returns an input config for a tarball.

func NewTextImageInputConfig added in v1.32.0 

func NewTextImageInputConfig(
	location string,
	compression string,
) (InputConfig, error)

NewTextImageInputConfig returns an input config for a text image.

func NewYAMLImageInputConfig added in v1.32.0 

func NewYAMLImageInputConfig(
	location string,
	compression string,
) (InputConfig, error)

NewYAMLImageInputConfig returns an input config for a yaml image.

func NewZipArchiveInputConfig added in v1.32.0 

func NewZipArchiveInputConfig(
	location string,
	subDir string,
	stripComponents uint32,
) (InputConfig, error)

NewZipArchiveInputConfig returns an input config for a zip archive.

type InputConfigType added in v1.32.0 

type InputConfigType int

InputConfigType is an input config's type. 

const (
	// InputConfigTypeModule is the module input type.
	InputConfigTypeModule InputConfigType = iota + 1
	// InputConfigTypeDirectory is the directory input type.
	InputConfigTypeDirectory
	// InputConfigTypeGitRepo is the git repository input type.
	InputConfigTypeGitRepo
	// InputConfigTypeProtoFile is the proto file input type.
	InputConfigTypeProtoFile
	// InputConfigTypeTarball is the tarball input type.
	InputConfigTypeTarball
	// InputConfigTypeZipArchive is the zip archive input type.
	InputConfigTypeZipArchive
	// InputConfigTypeBinaryImage is the binary image input type.
	InputConfigTypeBinaryImage
	// InputConfigTypeJSONImage is the JSON image input type.
	InputConfigTypeJSONImage
	// InputConfigTypeTextImage is the text image input type.
	InputConfigTypeTextImage
	// InputConfigTypeYAMLImage is the yaml image input type.
	InputConfigTypeYAMLImage
)

func (InputConfigType) String added in v1.32.0 

func (i InputConfigType) String() string

String implements fmt.Stringer.

type LintConfig added in v1.32.0 

type LintConfig interface {
	CheckConfig

	EnumZeroValueSuffix() string
	RPCAllowSameRequestResponse() bool
	RPCAllowGoogleProtobufEmptyRequests() bool
	RPCAllowGoogleProtobufEmptyResponses() bool
	ServiceSuffix() string
	AllowCommentIgnores() bool
	// contains filtered or unexported methods
}

LintConfig is lint configuration for a specific Module. 

var (
	// DefaultLintConfigV1 is the default lint config for v1.
	DefaultLintConfigV1 LintConfig = NewLintConfig(
		defaultCheckConfigV1,
		"",
		false,
		false,
		false,
		"",
		false,
	)

	// DefaultLintConfigV2 is the default lint config for v2.
	DefaultLintConfigV2 LintConfig = NewLintConfig(
		defaultCheckConfigV2,
		"",
		false,
		false,
		false,
		"",
		true,
	)
)

func NewLintConfig added in v1.32.0 

func NewLintConfig(
	checkConfig CheckConfig,
	enumZeroValueSuffix string,
	rpcAllowSameRequestResponse bool,
	rpcAllowGoogleProtobufEmptyRequests bool,
	rpcAllowGoogleProtobufEmptyResponses bool,
	serviceSuffix string,
	allowCommentIgnores bool,
) LintConfig

NewLintConfig returns a new LintConfig.

type ManagedDisableRule added in v1.32.0 

type ManagedDisableRule interface {
	// Path returns the file path, relative to its module, to disable managed mode for.
	Path() string
	// ModuleFullName returns the full name string of the module to disable
	// managed mode for.
	ModuleFullName() string
	// FieldName returns the fully qualified name for the field to disable managed
	// mode for. This is guaranteed to be empty if FileOption is not empty.
	FieldName() string
	// FileOption returns the file option to disable managed mode for. This is
	// guaranteed to be empty if FieldName is not empty.
	FileOption() FileOption
	// FieldOption returns the field option to disalbe managed mode for.
	FieldOption() FieldOption
	// contains filtered or unexported methods
}

ManagedDisableRule is a disable rule. A disable rule describes:

  • The options to not modify. If not specified, it means all options (both file options and field options) are not modified.
  • The files/fields for which these options are not modified. If not specified, it means for all files/fields the specified options are not modified.

A ManagedDisableRule is guaranteed to specify at least one of the two aspects. i.e. At least one of Path, ModuleFullName, FieldName, FileOption and FieldOption is not empty. A rule can disable all options for certain files/fields, disable certains options for all files/fields, or disable certain options for certain files/fields. To disable all options for all files/fields, turn off managed mode.

func NewManagedDisableRule added in v1.32.0 

func NewManagedDisableRule(
	path string,
	moduleFullName string,
	fieldName string,
	fileOption FileOption,
	fieldOption FieldOption,
) (ManagedDisableRule, error)

NewManagedDisableRule returns a new ManagedDisableRule.

type ManagedOverrideRule added in v1.32.0 

type ManagedOverrideRule interface {
	// Path is the file path, relative to its module, to disable managed mode for.
	Path() string
	// ModuleFullName is the full name string of the module to disable
	// managed mode for.
	ModuleFullName() string
	// FieldName is the fully qualified name for the field to disable managed
	// mode for. This is guaranteed to be empty is FileOption is not empty.
	FieldName() string
	// FileOption returns the file option to disable managed mode for. This is
	// guaranteed to be empty (FileOptionUnspecified) if FieldName is empty.
	FileOption() FileOption
	// FieldOption returns the field option to disable managed mode for.
	FieldOption() FieldOption
	// Value returns the override value.
	Value() interface{}
	// contains filtered or unexported methods
}

ManagedOverrideRule is an override rule. An override describes:

  • The options to modify. Exactly one of FileOption and FieldOption is not empty.
  • The value to modify these options with.
  • The files/fields for which the options are modified. If all of Path, ModuleFullName
  • or FieldName are empty, all files/fields are modified. Otherwise, only file/fields that match the specified Path, ModuleFullName and FieldName is modified.

func NewManagedOverrideRuleForFieldOption added in v1.32.0 

func NewManagedOverrideRuleForFieldOption(
	path string,
	moduleFullName string,
	fieldName string,
	fieldOption FieldOption,
	value interface{},
) (ManagedOverrideRule, error)

NewManagedOverrideRuleForFieldOption returns a new ManagedOverrideRule for a field option.

type ModuleConfig added in v1.32.0 

type ModuleConfig interface {
	// DirPath returns the path of the Module within the Workspace, if specified.
	//
	// This is always present. For v1beta1 and v1 buf.yamls, this is always ".".
	//
	// In v2, this will be used as the BucketID within Workspaces. For v1, it is up
	// to the Workspace constructor to come up with a BucketID (likely the directory name
	// within buf.work.yaml).
	DirPath() string
	// ModuleFullName returns the ModuleFullName for the Module, if available.
	//
	// This may be nil.
	ModuleFullName() bufmodule.ModuleFullName
	// RootToIncludes contains a map from root to the directories to include for that root.
	// The keys in RootToIncludes are always the same as those in RooToExcludes.
	//
	// Roots are the root directories within a bucket to search for Protobuf files.
	//
	// There will be no between the roots, ie foo/bar and foo are not allowed.
	// All Protobuf files must be unique relative to the roots, ie if foo and bar
	// are roots, then foo/baz.proto and bar/baz.proto are not allowed.
	// All roots will be normalized and validated.
	//
	// A proto file within a root is considered part of the module when it satisfies both:
	//
	// - being inside ONE of the include paths for this root (unless includes is empty, which
	//   does not filter the proto files)
	// - being inside NONE of the exclude paths for this root
	//
	// There should be no overlap between the includes, ie foo/bar and foo are not allowed.
	// All includes must reside within a root, but none will be equal to a root.
	// All includes will be normalized and validated.
	//
	// *** The includes in this map will be relative to the root they map to! ***
	// *** Note that root is relative to DirPath! ***
	// That is, the actual path to a root within a is DirPath()/root, and the
	// actual path to an exclude is DirPath()/root/include (in v1beta1 and v1, this
	// is just root and root/exclude).
	//
	// This will never return a nil or empty value.
	// If RootToIncludes is empty in the buf.yaml, this will return "." -> []string{}.
	//
	// For v1beta1, this may contain multiple keys but the values for these keys are empty slices.
	// For v1, this will contain a single key "." with an empty slice as its value.
	// For v2, this will contain a single key ".", with potentially some includes.
	RootToIncludes() map[string][]string
	// RootToExcludes contains a map from root to the excludes for that root.
	// The keys in RootToExcludes are always the same as those in RootToIncludes.
	//
	// Excludes are the directories within a bucket to exclude.
	// There should be no overlap between the excludes, ie foo/bar and foo are not allowed.
	// All excludes must reside within a root, but none will be equal to a root.
	// All excludes will be normalized and validated.
	//
	// *** The excludes in this map will be relative to the root they map to! ***
	// *** Note that root is relative to DirPath! ***
	// That is, the actual path to a root within a is DirPath()/root, and the
	// actual path to an exclude is DirPath()/root/exclude (in v1beta1 and v1, this
	// is just root and root/exclude).
	//
	// This will never return a nil or empty value.
	// If RootToExcludes is empty in the buf.yaml, this will return "." -> []string{}.
	//
	// For v1beta1, this may contain multiple keys.
	// For v1 and v2, this will contain a single key ".", with potentially some excludes.
	RootToExcludes() map[string][]string
	// LintConfig returns the lint configuration.
	//
	// If this was not set, this will be set to the default lint configuration.
	LintConfig() LintConfig
	// BreakingConfig returns the breaking configuration.
	//
	// If this was not set, this will be set to the default breaking configuration.
	BreakingConfig() BreakingConfig
	// contains filtered or unexported methods
}

ModuleConfig is configuration for a specific Module.

ModuleConfigs do not expose BucketID or OpaqueID, however DirPath is effectively BucketID, and ModuleFullName -> fallback to DirPath effectively is OpaqueID. Given that it is up to the user of this package to decide what to do with these fields, we do not name DirPath as BucketID, and we do not expose OpaqueID. 

var (
	// DefaultModuleConfigV1 is the default ModuleConfig for v1.
	DefaultModuleConfigV1 ModuleConfig

	// DefaultModuleConfigV2 is the default ModuleConfig for v1.
	DefaultModuleConfigV2 ModuleConfig
)

func NewModuleConfig added in v1.32.0 

func NewModuleConfig(
	dirPath string,
	moduleFullName bufmodule.ModuleFullName,
	rootToIncludes map[string][]string,
	rootToExcludes map[string][]string,
	lintConfig LintConfig,
	breakingConfig BreakingConfig,
) (ModuleConfig, error)

NewModuleConfig returns a new ModuleConfig.

type ObjectData added in v1.32.0 

type ObjectData interface {
	// Name returns the name of the underlying storage.ReadObject.
	//
	// This will be normalpath.Base(readObject.Path()).
	Name() string
	// Data returns the data from the underlying storage.ReadObject.
	Data() []byte
	// contains filtered or unexported methods
}

ObjectData is the data of the underlying storage.ReadObject that was used to create a Object.

This is present on Files if they were created from storage.ReadBuckets. It is not present if the File was created via a New constructor or Read method.

func GetBufLockV1Beta1OrV1ObjectDataForPrefix added in v1.32.0 

func GetBufLockV1Beta1OrV1ObjectDataForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (ObjectData, error)

GetBufLockV1Beta1OrV1ObjectDataForPrefix is a helper function that gets the ObjectData for the buf.lock file at the given bucket prefix, if the buf.lock file was v1beta1 or v1.

The file is only parsed for its file version. No additional validation is performed. If the file does not exist, an error that satisfies fs.ErrNotExist is returned.

This function is used to help optionally get ObjectData where it is needed for digest calculations.

func GetBufYAMLV1Beta1OrV1ObjectDataForPrefix added in v1.32.0 

func GetBufYAMLV1Beta1OrV1ObjectDataForPrefix(
	ctx context.Context,
	bucket storage.ReadBucket,
	prefix string,
) (ObjectData, error)

GetBufYAMLV1Beta1OrV1ObjectDataForPrefix is a helper function that gets the ObjectData for the buf.yaml file at the given bucket prefix, if the buf.yaml file was v1beta1 or v1.

The file is only parsed for its file version. No additional validation is performed. If the file does not exist, an error that satisfies fs.ErrNotExist is returned.

This function is used to help optionally get ObjectData where it is needed for digest calculations.

type PluginConfig added in v1.40.0 

type PluginConfig interface {
	// Type returns the plugin type. This is never the zero value.
	Type() PluginConfigType
	// Name returns the plugin name. This is never empty.
	Name() string
	// Options returns the plugin options.
	//
	// TODO: Will want good validation and good error messages for what this decodes.
	// Otherwise we will confuse users. Do QA.
	Options() map[string]any
	// Path returns the path, including arguments, to invoke the binary plugin.
	//
	// This is not empty only when the plugin is local.
	Path() []string
	// contains filtered or unexported methods
}

PluginConfig is a configuration for a plugin.

func NewLocalPluginConfig added in v1.32.0 

func NewLocalPluginConfig(
	name string,
	options map[string]any,
	path []string,
) (PluginConfig, error)

NewLocalPluginConfig returns a new PluginConfig for a local plugin.

type PluginConfigType added in v1.32.0 

type PluginConfigType int

PluginConfigType is a generate plugin configuration type. 

const (
	// PluginConfigTypeLocal is the local plugin config type.
	PluginConfigTypeLocal PluginConfigType = iota + 1
)

Source Files

View all Source files

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.