component

package
v0.0.0-...-7ae29b8 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2023 License: MPL-2.0 Imports: 18 Imported by: 10

Documentation

Overview

Package component has the interfaces for all the components that can be implemented. A component is the broad term used to describe all providers, provisioners, etc.

Many component interfaces have functions named `XFunc` where "X" is some operation and the return value is "interface{}". These functions should return a method handle to the function implementing that operation. This pattern is done so that we can support custom typed operations that take and return full rich types for an operation. We use a minimal dependency-injection framework (see internal/mapper) to call these functions.

Package component exposes the component types supported and helpers around those types.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultOptionsMap = map[Type]interface{}{
	CommandType: &CommandOptions{

		Primary: true,
	},
	ProviderType: &ProviderOptions{

		Priority: 5,

		Defaultable: true,

		Parallel: false,

		BoxOptional: false,
	},
	SyncedFolderType: &SyncedFolderOptions{

		Priority: 10,
	},
}

DefaultOptions contains default options values for components that use options

View Source 
var OptionsTypeMap = map[Type]interface{}{
	CommandType:      (*CommandOptions)(nil),
	ProviderType:     (*ProviderOptions)(nil),
	SyncedFolderType: (*SyncedFolderOptions)(nil),
}

OptionsTypeMap is a mapping of a type to the nil pointer of the interface to the options struct (if any) for that type. This is used in PluginInfo when decoding options from proto.

View Source 
var TypeMap = map[Type]interface{}{
	AuthenticatorType: (*Authenticator)(nil),
	CommandType:       (*Command)(nil),
	CommunicatorType:  (*Communicator)(nil),
	ConfigType:        (*Config)(nil),
	DownloaderType:    (*Downloader)(nil),
	GuestType:         (*Guest)(nil),
	HostType:          (*Host)(nil),
	LogPlatformType:   (*LogPlatform)(nil),
	LogViewerType:     (*LogViewer)(nil),
	PluginInfoType:    (*PluginInfo)(nil),
	ProviderType:      (*Provider)(nil),
	ProvisionerType:   (*Provisioner)(nil),
	SyncedFolderType:  (*SyncedFolder)(nil),
	PushType:          (*Push)(nil),
}

TypeMap is a mapping of Type to the nil pointer to the interface of that type. This can be used with libraries such as mapper.

Functions

func Configure 

func Configure(c interface{}, body hcl.Body, ctx *hcl.EvalContext) hcl.Diagnostics

Configure configures c with the provided configuration.

If c does not implement Configurable AND body is non-empty, then it is an error. If body is empty in that case, it is not an error.

func ConfigureFromMap 

func ConfigureFromMap(c interface{}, config map[string]interface{}) error

Configure configures c with the provided configuration.

If c does not implement Configurable AND config is non-empty, then it is an error. If body is empty in that case, it is not an error.

func Documentation 

func Documentation(c interface{}) (*docs.Documentation, error)

Documentation returns the documentation for the given component.

If c does not implement Documented, nil is returned.

func FindComponent 

func FindComponent(name string) (interface{}, error)

func Id 

func Id() (string, error)

Id returns a unique Id that can be used for new values. This generates a ulid value but the ID itself should be an internal detail. An error will be returned if the ID could be generated.

func ProtoAny 

func ProtoAny(m interface{}) (*anypb.Any, error)

ProtoAny returns an *anypb.Any for the given ProtoMarshaler object.

func ProtoAnySlice 

func ProtoAnySlice(m interface{}) ([]*anypb.Any, error)

ProtoAny returns []*anypb.Any for the given input slice by encoding each result into a proto value.

func ProtoAnyUnmarshal 

func ProtoAnyUnmarshal(m interface{}, out proto.Message) error

ProtoAnyUnmarshal attempts to unmarshal a ProtoMarshler implementation to another type. This can be used to get more concrete data out of a generic component.

func UnmarshalOptionsProto 

func UnmarshalOptionsProto(typ Type, optsProtoAny interface{}) (result interface{}, err error)

UnmarshalOptionsProto transforms a proto containing component options into its equivalent go struct. The result's type will match the mapping in OptionsTypeMap.

Types

type AuthResult 

type AuthResult struct {
	// Authenticated when true means that the plugin should now be authenticated
	// (given the other fields in this struct). If ValidateAuth is called,
	// it should succeed. If this is false, the auth method may have printed
	// help text or some other information, but it didn't authenticate. However,
	// this is not an error.
	Authenticated bool
}

AuthResult is the return value expected from Authenticator.AuthFunc.

type Authenticator 

type Authenticator interface {
	// AuthFunc should return the method for getting credentials for a
	// plugin. This should return AuthResult.
	AuthFunc() interface{}

	// ValidateAuthFunc should return the method for validating authentication
	// credentials for the plugin
	ValidateAuthFunc() interface{}
}

Authenticator is responsible for authenticating different types of plugins.

type CapabilityPlatform 

type CapabilityPlatform interface {
	// Test if capability is available
	HasCapabilityFunc() interface{}
	// Run a capability
	CapabilityFunc(capName string) interface{}
}

type Command 

type Command interface {
	// Execute a command
	ExecuteFunc([]string) interface{}
	// Retruns command info
	CommandInfoFunc() interface{}
}

type CommandFlag 

type CommandFlag struct {
	LongName     string
	ShortName    string
	Description  string
	DefaultValue string
	Type         FlagType
	Aliases      []string
}

type CommandFlags 

type CommandFlags []*CommandFlag

func (CommandFlags) Display 

func (c CommandFlags) Display() string

type CommandInfo 

type CommandInfo struct {
	Name        string
	Help        string
	Synopsis    string
	Flags       []*CommandFlag
	Subcommands []*CommandInfo
	Primary     bool
}

type CommandOptions 

type CommandOptions struct {
	// Primary indicates that a command should show up in the main help output.
	Primary bool
}

func (*CommandOptions) Proto 

func (co *CommandOptions) Proto() proto.Message

implements ProtoMarshaler

type CommandParams 

type CommandParams struct {
	Flags     map[string]interface{}
	Arguments []string
}

type Communicator 

type Communicator interface {
	// Checks if machine can be used with communicator
	MatchFunc() interface{}
	// Initialize communicator with machine
	InitFunc() interface{}
	// Check if communicator is ready
	ReadyFunc() interface{}
	// Wait for communicator to become ready for given seconds
	WaitForReadyFunc() interface{}
	// Download file from guest path to local path
	DownloadFunc() interface{}
	// Upload file from local path to guest path
	UploadFunc() interface{}
	// Run command
	ExecuteFunc() interface{}
	// Run privileged command
	PrivilegedExecuteFunc() interface{}
	// Run a test command on the guest
	TestFunc() interface{}
	// Reset the communicator. Close and re-establish connection where required.
	ResetFunc() interface{}
}

type ComponentWithOptions 

type ComponentWithOptions struct {
	Component interface{}
	Options   interface{}
}

type Config 

type Config interface {
	// Register a configuration namespace
	Register() (*ConfigRegistration, error)
	// Defines the structure of the supported configuration
	StructFunc() interface{}
	// Initialization of configuration data
	InitFunc() interface{}
	// Merge configuration
	MergeFunc() interface{}
	// Return finalized configuration data
	FinalizeFunc() interface{}
}

type ConfigData 

type ConfigData struct {
	Source string                 // Root type name
	Data   map[string]interface{} // Configuration data
}

type ConfigFinalize 

type ConfigFinalize struct {
	Config *ConfigData
}

type ConfigMerge 

type ConfigMerge struct {
	Base    *ConfigData
	Overlay *ConfigData
}

type ConfigRegistration 

type ConfigRegistration struct {
	Identifier string // Identifier used within Vagrantfile
	Scope      string // Optional scope (provider, provisioner, etc)
}

type Configurable 

type Configurable interface {
	// Config should return a pointer to an allocated configuration
	// structure. This structure will be written to directly with the
	// decoded configuration. If this returns nil, then it is as if
	// Configurable was not implemented.
	Config() (interface{}, error)
}

Configurable can be optionally implemented by any compontent to accept user configuration.

type ConfigurableNotify 

type ConfigurableNotify interface {
	Configurable

	// ConfigSet is called with the value of the configuration after
	// decoding is complete successfully.
	ConfigSet(interface{}) error
}

ConfigurableNotify is an optional interface that can be implemented by any component to receive a notification that the configuration was decoded.

type Direct 

type Direct struct {
	Arguments []interface{}
}

type Documented 

type Documented interface {
	// Documentation() returns a completed docs.Documentation struct
	// describing the components configuration.
	Documentation() (*docs.Documentation, error)
}

Documented can be optionally implemented by any component to return documentation about the component.

type Downloader 

type Downloader interface {
	DownloadFunc() interface{}
}

type FlagType 

type FlagType uint
const (
	FlagString FlagType = 1 << iota // String
	FlagBool                        // Bool
)

func (FlagType) String 

func (i FlagType) String() string

type Guest 

type Guest interface {
	CapabilityPlatform

	// Detect if machine is supported guest
	GuestDetectFunc() interface{}
	// List of parent host names
	ParentFunc() interface{}
}

type Host 

type Host interface {
	CapabilityPlatform

	// Detect if machine is supported host
	HostDetectFunc() interface{}
	// List of parent host names
	ParentFunc() interface{}
}

type JobInfo 

type JobInfo struct {
	// Id is the ID of the job that is executing this plugin operation.
	// If this is empty then it means that the execution is happening
	// outside of a job.
	Id string

	// Local is true if the operation is running locally on a machine
	// alongside the invocation. This can be used to determine if you can
	// do things such as open browser windows, read user files, etc.
	Local bool

	// Workspace is the workspace that this job is executing in. This should
	// be used by plugins to properly isolate resources from each other.
	// TODO(spox): this needs to be removed
	Workspace string
}

JobInfo is available to plugins to get information about the context in which a job is executing.

type LogEvent 

type LogEvent struct {
	Partition string
	Timestamp time.Time
	Message   string
}

LogEvent represents a single log entry.

type LogPlatform 

type LogPlatform interface {
	// LogsFunc should return an implementation of LogViewer.
	LogsFunc() interface{}
}

LogPlatform is responsible for reading the logs for a deployment. This doesn't need to be the same as the Platform but a Platform can also implement this interface to natively provide logs.

type LogViewer 

type LogViewer interface {
	// NextBatch is called to return the next batch of logs. This is expected
	// to block if there are no logs available. The context passed in will be
	// cancelled if the logs viewer is interrupted.
	NextLogBatch(ctx context.Context) ([]LogEvent, error)
}

LogViewer returns batches of log lines. This is expected to be returned by a LogPlatform implementation.

type MetadataSet 

type MetadataSet struct {
	Metadata map[string]string
}

type NamedCapability 

type NamedCapability struct {
	Capability string
}

type PluginInfo 

type PluginInfo interface {
	ComponentOptions() map[Type]interface{}
	ComponentTypes() []Type
	Name() string
}

type ProtoMarshaler 

type ProtoMarshaler interface {
	// Proto returns a proto.Message of this structure. This may also return
	// a proto Any value and it will not be re-wrapped with Any.
	Proto() proto.Message
}

ProtoMarshaler is the interface required by objects that must support protobuf marshaling. This expects the object to go to a proto.Message which is converted to a proto Any value1. The plugin is expected to register a proto type that can decode this Any value.

This enables the project to encode intermediate objects (such as artifacts) and store them in a database.

type Provider 

type Provider interface {
	CapabilityPlatform

	// Check if provider is usable
	UsableFunc() interface{}
	// Check if the provider is installed
	InstalledFunc() interface{}
	// Run an action by name
	ActionFunc(actionName string) interface{}
	// Called when the machine id is changed
	MachineIdChangedFunc() interface{}
	// Get SSH info
	SshInfoFunc() interface{}
	// Get target state
	StateFunc() interface{}
}

type ProviderOptions 

type ProviderOptions struct {
	// Priority indicates the precedence of provider plugin selection (higher overrides lower)
	Priority int

	// Parallel indicates whether or not the provider supports parallel operations
	Parallel bool

	// BoxOptional indicates if the provider can function without a box
	BoxOptional bool

	// Defaultable can be set to false to omit the provider from consideration as a default
	Defaultable bool
}

ProviderOptions stores options about a given provider plugin which are used in provider selection and validation

func (*ProviderOptions) Proto 

func (po *ProviderOptions) Proto() proto.Message

implements ProtoMarshaler

type Provisioner 

type Provisioner interface {
	ConfigureFunc() interface{}
	ProvisionFunc() interface{}
	CleanupFunc() interface{}
}

type Push 

type Push interface {
	// Executes a named push strategy
	PushFunc() interface{}
}

type SyncedFolder 

type SyncedFolder interface {
	CapabilityPlatform

	// Determines if an implementation is usable
	UsableFunc() interface{}
	// Called before the machine is booted and networks are setup
	PrepareFunc() interface{}
	// Called after the machine is booted and networks are setup
	// Adds folders without removing any existing ones
	EnableFunc() interface{}
	// Removes folders from a running machine
	DisableFunc() interface{}
	// Called after destroying a machine
	CleanupFunc() interface{}
}

type SyncedFolderOptions 

type SyncedFolderOptions struct {
	// Priority determines the weight used to select a synced folder plugin
	// when one is not specified explicitly. A higher number is more likely to
	// be selected.
	Priority int
}

SyncedFolderOptions contains attributes that can be configured for a Synced Folder plugin. These are meant to be set on plugin definition via sdk.WithComponent().

func (*SyncedFolderOptions) Proto 

func (po *SyncedFolderOptions) Proto() proto.Message

implements ProtoMarshaler

type Type 

type Type uint

Type is an enum of all the types of components supported. This isn't used directly in this package but is used by other packages to reference the component types. 

const (
	InvalidType       Type = iota // Invalid
	CommandType                   // Command
	CommunicatorType              // Communicator
	GuestType                     // Guest
	HostType                      // Host
	ProviderType                  // Provider
	ProvisionerType               // Provisioner
	SyncedFolderType              // SyncedFolder
	AuthenticatorType             // Authenticator
	LogPlatformType               // LogPlatform
	LogViewerType                 // LogViewer
	MapperType                    // Mapper
	ConfigType                    // Config
	PluginInfoType                // PluginInfo
	PushType                      // Push
	DownloaderType                // Downloader

)

func FindType 

func FindType(name string) (Type, error)

func (Type) String 

func (i Type) String() string

Source Files

View all Source files

Directories

Path Synopsis

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.