plugin

Documentation

Overview

Package plugin provides types for managing agent plugins.

It is intended for internal use by buildkite-agent only.

Index

• Variables
• type Definition
  • func LoadDefinitionFromDir(dir string) (*Definition, error)
  • func ParseDefinition(b []byte) (*Definition, error)
• type DeprecatedNameError
  • func NewDeprecatedNameError(oldName, newName string) DeprecatedNameError
  • func (e *DeprecatedNameError) Error() string
  • func (e *DeprecatedNameError) Is(target error) bool
• type DeprecatedNameErrors
  • func (e *DeprecatedNameErrors) Append(errs ...DeprecatedNameError) *DeprecatedNameErrors
  • func (e *DeprecatedNameErrors) Error() string
  • func (e *DeprecatedNameErrors) Is(target error) bool
  • func (e *DeprecatedNameErrors) IsEmpty() bool
  • func (e *DeprecatedNameErrors) Unwrap() []error
• type Plugin
  • func CreateFromJSON(j string) ([]*Plugin, error)
  • func CreatePlugin(location string, config map[string]any) (*Plugin, error)
  • func (p *Plugin) ConfigurationToEnvironment() (*env.Environment, error)
  • func (p *Plugin) Identifier() (string, error)
  • func (p *Plugin) Label() string
  • func (p *Plugin) Name() string
  • func (p *Plugin) Repository() (string, error)
  • func (p *Plugin) RepositorySubdirectory() (string, error)
• type ValidateResult
  • func (vr ValidateResult) Error() string
  • func (vr ValidateResult) Unwrap() []error
  • func (vr ValidateResult) Valid() bool
• type Validator
  • func (v Validator) Validate(ctx context.Context, def *Definition, config map[string]any) ValidateResult

Variables

var (
	// ErrDefinitionNotFound is used when a plugin definition file cannot be
	// found.
	ErrDefinitionNotFound = errors.New("Definition file not found")

	// ErrCommandNotInPATH is the underlying error when a command cannot be
	// found during plugin validation.
	ErrCommandNotInPATH = errors.New("command not found in PATH")
)

Types

type Definition

type Definition struct {
	Name          string             `json:"name"`
	Requirements  []string           `json:"requirements"`
	Configuration *jsonschema.Schema `json:"configuration"`
}

Definition defines the contents of the plugin.{yml,yaml,json} file that each plugin has.

func LoadDefinitionFromDir

func LoadDefinitionFromDir(dir string) (*Definition, error)

LoadDefinitionFromDir looks in a directory for one of plugin.json, plugin.yaml, or plugin.yml. It parses the first one it finds, and returns the resulting Definition. If none of those files can be found, it returns ErrDefinitionNotFound.

func ParseDefinition

func ParseDefinition(b []byte) (*Definition, error)

ParseDefinition parses either YAML or JSON bytes into a Definition.

type DeprecatedNameError

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

DeprecatedNameError contains information about environment variable names that are deprecated. Both the deprecated name and its replacement are held

func NewDeprecatedNameError

func NewDeprecatedNameError(oldName, newName string) DeprecatedNameError

func (*DeprecatedNameError) Error

func (e *DeprecatedNameError) Error() string

func (*DeprecatedNameError) Is

func (e *DeprecatedNameError) Is(target error) bool

type DeprecatedNameErrors

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

DeprecatedNameErrors contains a set of DeprecatedNameError

func (*DeprecatedNameErrors) Append

func (e *DeprecatedNameErrors) Append(errs ...DeprecatedNameError) *DeprecatedNameErrors

Append adds DeprecatedNameError contained set and returns the reciver. Returning the reveiver is necessary to support appending to nil. So this should be used just like the builtin `append` function.

func (*DeprecatedNameErrors) Error

func (e *DeprecatedNameErrors) Error() string

Error returns each contained error on a new line

func (*DeprecatedNameErrors) Is

func (e *DeprecatedNameErrors) Is(target error) bool

Is returns true if and only if a target contains the same set of DeprecatedNameError as the receiver.

func (*DeprecatedNameErrors) IsEmpty

func (e *DeprecatedNameErrors) IsEmpty() bool

IsEmpty return true if and only if `e` contains no errors

func (*DeprecatedNameErrors) Unwrap

func (e *DeprecatedNameErrors) Unwrap() []error

Unwrap returns the a slice of errors in a stable order

type Plugin

type Plugin struct {
	// Where the plugin can be found (can either be a file system path, or
	// a git repository).
	Location string

	// The version of the plugin that should be running.
	Version string

	// The clone method.
	Scheme string

	// Any authentication attached to the repository.
	Authentication string

	// Whether the plugin refers to a vendored path.
	Vendored bool

	// Configuration for the plugin.
	Configuration map[string]any
}

Plugin describes where to find, and how to configure, an agent plugin.

func CreateFromJSON

func CreateFromJSON(j string) ([]*Plugin, error)

CreateFromJSON returns a slice of Plugins loaded from a JSON string.

func CreatePlugin

func CreatePlugin(location string, config map[string]any) (*Plugin, error)

CreatePlugin returns a Plugin for the given location and config.

func (*Plugin) ConfigurationToEnvironment

func (p *Plugin) ConfigurationToEnvironment() (*env.Environment, error)

ConfigurationToEnvironment converts the plugin configuration values to environment variables.

func (*Plugin) Identifier

func (p *Plugin) Identifier() (string, error)

Identifier returns an ID for the plugin that can be used as a folder name.

func (*Plugin) Label

func (p *Plugin) Label() string

Label returns a pretty name for the plugin.

func (*Plugin) Name

func (p *Plugin) Name() string

Name returns the name of the plugin.

func (*Plugin) Repository

func (p *Plugin) Repository() (string, error)

Repository returns the repository host where the code is stored.

func (*Plugin) RepositorySubdirectory

func (p *Plugin) RepositorySubdirectory() (string, error)

RepositorySubdirectory returns the subdirectory path that the plugin is in.

type ValidateResult

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

ValidateResult contains results of a validation check.

func (ValidateResult) Error

func (vr ValidateResult) Error() string

Error returns a single string representing all the inner error strings.

func (ValidateResult) Unwrap

func (vr ValidateResult) Unwrap() []error

Unwrap returns the errors contained in the ValidateResult.

func (ValidateResult) Valid

func (vr ValidateResult) Valid() bool

Valid reports if the result contains no errors.

type Validator

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

Validator validates plugin definitions.

func (Validator) Validate

func (v Validator) Validate(ctx context.Context, def *Definition, config map[string]any) ValidateResult

Validate checks the plugin definition for errors, including missing commands from $PATH and invalid configuration under the definition's JSON Schema.