bufpluginconfig

Documentation

Overview

Package bufpluginconfig defines the buf.plugin.yaml file.

Index

• Constants
• Variables
• func ExistingConfigFilePath(ctx context.Context, readBucket storage.ReadBucket) (string, error)
• func OptionsSliceToPluginOptions(options []string) map[string]string
• func PluginOptionsToOptionsSlice(pluginOptions map[string]string) []string
• type Config
  • func GetConfigForBucket(ctx context.Context, readBucket storage.ReadBucket, options ...ConfigOption) (*Config, error)
  • func GetConfigForData(ctx context.Context, data []byte, options ...ConfigOption) (*Config, error)
  • func ParseConfig(config string, options ...ConfigOption) (*Config, error)
• type ConfigOption
  • func WithOverrideRemote(remote string) ConfigOption
• type ExternalConfig
• type ExternalDependency
• type ExternalGoRegistryConfig
• type ExternalNPMRegistryConfig
• type ExternalRegistryConfig
• type GoRegistryConfig
• type GoRegistryDependencyConfig
• type NPMRegistryConfig
• type NPMRegistryDependencyConfig
• type RegistryConfig

Constants

const (
	// ExternalConfigFilePath is the default configuration file path for v1.
	ExternalConfigFilePath = "buf.plugin.yaml"
	// V1Version is the version string used to indicate the v1 version of the buf.plugin.yaml file.
	V1Version = "v1"
)

Variables

var (
	// AllConfigFilePaths are all acceptable config file paths without overrides.
	//
	// These are in the order we should check.
	AllConfigFilePaths = []string{
		ExternalConfigFilePath,
	}
)

Functions

func ExistingConfigFilePath

func ExistingConfigFilePath(ctx context.Context, readBucket storage.ReadBucket) (string, error)

ExistingConfigFilePath checks if a configuration file exists, and if so, returns the path within the ReadBucket of this configuration file.

Returns empty string and no error if no configuration file exists.

func OptionsSliceToPluginOptions

func OptionsSliceToPluginOptions(options []string) map[string]string

OptionsSliceToPluginOptions converts a slice of plugin options to a map (using the first '=' as a delimiter between key and value). If no '=' is found, the option will be stored in the map with an empty string value.

func PluginOptionsToOptionsSlice

func PluginOptionsToOptionsSlice(pluginOptions map[string]string) []string

PluginOptionsToOptionsSlice converts a map representation of plugin options to a slice of the form '<key>=<value>' or '<key>' for empty values.

Types

type Config

type Config struct {
	// Name is the name of the plugin (e.g. 'buf.build/protocolbuffers/go').
	Name bufpluginref.PluginIdentity
	// PluginVersion is the version of the plugin's implementation
	// (e.g the protoc-gen-connect-go implementation is v0.2.0).
	//
	// This excludes any other details found in the buf.plugin.yaml
	// or plugin source (e.g. Dockerfile) that would otherwise influence
	// the plugin's behavior.
	PluginVersion string
	// SourceURL is an optional attribute used to specify where the source
	// for the plugin can be found.
	SourceURL string
	// Description is an optional attribute to provide a more detailed
	// description for the plugin.
	Description string
	// Dependencies are the dependencies this plugin has on other plugins.
	//
	// An example of a dependency might be a 'protoc-gen-go-grpc' plugin
	// which depends on the 'protoc-gen-go' generated code.
	Dependencies []bufpluginref.PluginReference
	// DefaultOptions is the default set of options passed into the plugin.
	//
	// For now, all options are string values. This could eventually
	// support other types (like JSON Schema and Terraform variables),
	// where strings are the default value unless otherwise specified.
	//
	// Note that some legacy plugins don't always express their options
	// as key value pairs. For example, protoc-gen-java has an option
	// that can be passed like so:
	//
	//  java_opt=annotate_code
	//
	// In those cases, the option value in this map will be set to
	// the empty string, and the option will be propagated to the
	// compiler without the '=' delimiter.
	DefaultOptions map[string]string
	// OutputLanguages is a list of output languages the plugin supports.
	OutputLanguages []string
	// Registry is the registry configuration, which lets the user specify
	// dependencies and other metadata that applies to a specific
	// remote generation registry (e.g. the Go module proxy, NPM registry,
	// etc).
	Registry *RegistryConfig
}

Config is the plugin config.

func GetConfigForBucket

func GetConfigForBucket(ctx context.Context, readBucket storage.ReadBucket, options ...ConfigOption) (*Config, error)

GetConfigForBucket gets the Config for the YAML data at ConfigFilePath.

If the data is of length 0, returns the default config.

func GetConfigForData

func GetConfigForData(ctx context.Context, data []byte, options ...ConfigOption) (*Config, error)

GetConfigForData gets the Config for the given JSON or YAML data.

If the data is of length 0, returns the default config.

func ParseConfig

func ParseConfig(config string, options ...ConfigOption) (*Config, error)

ParseConfig parses the file at the given path as a Config.

type ConfigOption

type ConfigOption func(*configOptions)

ConfigOption is an optional option used when loading a Config.

func WithOverrideRemote

func WithOverrideRemote(remote string) ConfigOption

WithOverrideRemote will update the remote found in the plugin name and dependencies.

type ExternalConfig

type ExternalConfig struct {
	Version         string                 `json:"version,omitempty" yaml:"version,omitempty"`
	Name            string                 `json:"name,omitempty" yaml:"name,omitempty"`
	PluginVersion   string                 `json:"plugin_version,omitempty" yaml:"plugin_version,omitempty"`
	SourceURL       string                 `json:"source_url,omitempty" yaml:"source_url,omitempty"`
	Description     string                 `json:"description,omitempty" yaml:"description,omitempty"`
	Deps            []ExternalDependency   `json:"deps,omitempty" yaml:"deps,omitempty"`
	DefaultOpts     []string               `json:"default_opts,omitempty" yaml:"default_opts,omitempty"`
	OutputLanguages []string               `json:"output_languages,omitempty" yaml:"output_languages,omitempty"`
	Registry        ExternalRegistryConfig `json:"registry,omitempty" yaml:"registry,omitempty"`
}

ExternalConfig represents the on-disk representation of the plugin configuration at version v1.

type ExternalDependency

type ExternalDependency struct {
	Plugin   string `json:"plugin,omitempty" yaml:"plugin,omitempty"`
	Revision int    `json:"revision,omitempty" yaml:"revision,omitempty"`
}

ExternalDependency represents a dependency on another plugin.

type ExternalGoRegistryConfig

type ExternalGoRegistryConfig struct {
	// The minimum Go version required by the plugin.
	MinVersion string `json:"min_version,omitempty" yaml:"min_version,omitempty"`
	Deps       []struct {
		Module  string `json:"module,omitempty" yaml:"module,omitempty"`
		Version string `json:"version,omitempty" yaml:"version,omitempty"`
	} `json:"deps,omitempty" yaml:"deps,omitempty"`
}

ExternalGoRegistryConfig is the external registry configuration for a Go plugin.

type ExternalNPMRegistryConfig

type ExternalNPMRegistryConfig struct {
	RewriteImportPathSuffix string `json:"rewrite_import_path_suffix,omitempty" yaml:"rewrite_import_path_suffix,omitempty"`
	Deps                    []struct {
		Package string `json:"package,omitempty" yaml:"package,omitempty"`
		Version string `json:"version,omitempty" yaml:"version,omitempty"`
	} `json:"deps,omitempty" yaml:"deps,omitempty"`
}

ExternalNPMRegistryConfig is the external registry configuration for a JavaScript NPM plugin.

type ExternalRegistryConfig

type ExternalRegistryConfig struct {
	Go   *ExternalGoRegistryConfig  `json:"go,omitempty" yaml:"go,omitempty"`
	NPM  *ExternalNPMRegistryConfig `json:"npm,omitempty" yaml:"npm,omitempty"`
	Opts []string                   `json:"opts,omitempty" yaml:"opts,omitempty"`
}

ExternalRegistryConfig is the external configuration for the registry of a plugin.

type GoRegistryConfig

type GoRegistryConfig struct {
	MinVersion string
	Deps       []*GoRegistryDependencyConfig
}

GoRegistryConfig is the registry configuration for a Go plugin.

type GoRegistryDependencyConfig

type GoRegistryDependencyConfig struct {
	Module  string
	Version string
}

GoRegistryDependencyConfig is the go registry dependency configuration.

type NPMRegistryConfig

type NPMRegistryConfig struct {
	RewriteImportPathSuffix string
	Deps                    []*NPMRegistryDependencyConfig
}

NPMRegistryConfig is the registry configuration for a JavaScript NPM plugin.

type NPMRegistryDependencyConfig

type NPMRegistryDependencyConfig struct {
	Package string
	Version string
}

NPMRegistryDependencyConfig is the npm registry dependency configuration.

type RegistryConfig

type RegistryConfig struct {
	Go  *GoRegistryConfig
	NPM *NPMRegistryConfig
	// Options is the set of options passed into the plugin for the
	// remote registry.
	//
	// For now, all options are string values. This could eventually
	// support other types (like JSON Schema and Terraform variables),
	// where strings are the default value unless otherwise specified.
	//
	// Note that some legacy plugins don't always express their options
	// as key value pairs. For example, protoc-gen-java has an option
	// that can be passed like so:
	//
	//  java_opt=annotate_code
	//
	// In those cases, the option value in this map will be set to
	// the empty string, and the option will be propagated to the
	// compiler without the '=' delimiter.
	Options map[string]string
}

RegistryConfig is the configuration for the registry of a plugin.

Only one field will be set.