component

package
v0.0.0-...-dcdb2a0 Latest Latest
Warning

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

 Go to latest Published: Apr 12, 2023 License: MPL-2.0 Imports: 16 Imported by: 53

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 builders, platforms, registries, 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 TypeMap = map[Type]interface{}{
	BuilderType:        (*Builder)(nil),
	RegistryType:       (*Registry)(nil),
	PlatformType:       (*Platform)(nil),
	ReleaseManagerType: (*ReleaseManager)(nil),
	LogPlatformType:    (*LogPlatform)(nil),
	AuthenticatorType:  (*Authenticator)(nil),
	ConfigSourcerType:  (*ConfigSourcer)(nil),
	TaskLauncherType:   (*TaskLauncher)(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 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 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 Proto 

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

Proto returns the proto.Message for a given value that is either already a proto.Message or implements ProtoMarshaler. If the value implements neither, then this returns (nil, nil).

func ProtoAny 

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

ProtoAny returns an *opaqueany.Any for the given ProtoMarshaler object. This will return nil if the given message is nil.

func ProtoAnySlice 

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

ProtoAny returns []*opaqueany.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.

Types

type AccessInfo 

type AccessInfo interface{}

AccessInfo is the type of data returned by AccessInfoFunc and made available to the build plugin.

type Artifact 

type Artifact interface {
	// Labels are the labels to set. These will overwrite any conflicting
	// labels on the value. Please namespace the labels you set. The recommended
	// namespacing is using a URL structure, followed by a slash, and a key.
	// For example: "plugin.example.com/key" as the key. The value can be
	// any string.
	Labels() map[string]string
}

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 Builder 

type Builder interface {
	// BuildFunc should return the method handle for the "build" operation.
	// The build function has access to a *Source and should return an Artifact.
	BuildFunc() interface{}
}

Builder is responsible for building an artifact from source.

type BuilderODR 

type BuilderODR interface {
	// BuildODRFunc should return the method handle for the "build" operation that
	// occurs in the context of an ondemand runner (meaning the job has it's own container
	// environment that it can solely use).
	BuildODRFunc() interface{}
}

BuilderODR is an optional interface that builder type plugins can implement. If the plugin is running in an ondemand runner context, then this function will be called to perform the build, if the inerface is implemented. If the plugin does not define this interface, then BuildFunc will be used for all contexts.

type ConfigRequest 

type ConfigRequest struct {
	Name   string
	Config map[string]string
}

ConfigRequest is sent to ReadFunc for ConfigSourcer to represent a single configuration variable that was requested. The ReadFunc parameters should have a `[]*ConfigRequest` parameter for these.

type ConfigSourcer 

type ConfigSourcer interface {
	// ReadFunc returns the function for reading configuration.
	//
	// The returned function can start a background goroutine to more efficiently
	// watch for changes. The entrypoint will periodically call Read to check for
	// updates.
	//
	// If the configuration changes for any dynamic configuration variable,
	// the entrypoint will call Stop followed by Read, so plugins DO NOT need
	// to implement config diffing. Plugins may safely assume if Read is called
	// after a Stop that the config is new, and that subsequent calls have the
	// same config.
	//
	// Read is called for ALL defined configuration variables for this source.
	// If ANY change, Stop is called followed by Read again. Only one sourcer
	// is active for a set of configs.
	ReadFunc() interface{}

	// StopFunc returns a function for stopping configuration sourcing.
	// You can return nil if stopping is not necessary or supported for
	// this sourcer.
	//
	// The stop function should stop any background processes started with Read.
	StopFunc() interface{}
}

ConfigSourcer can be implemented by plugins that support sourcing dynamic configuration for running applications.

This plugin type runs alongside the application. The initial config loading will block the application start so authors should attempt to source configuration as quickly as possible.

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 component 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 DeclaredResources 

type DeclaredResources struct {
	Resources []*proto.DeclaredResource
}

DeclaredResources is a group of resources that a plugin had declared to be under it's direct management.

func (*DeclaredResources) ByName 

func (d *DeclaredResources) ByName(name string) (*proto.DeclaredResource, error)

ByName finds one DeclaredResource with a matching name. Returns an error if multiple resources are found. Returns a nil DeclaredResource if no match is found.

type DeclaredResourcesResp 

type DeclaredResourcesResp struct {
	// Resources that a plugin declares have been created and are under its management.
	DeclaredResources []*proto.DeclaredResource
}

DeclaredResourcesResp is a component used as a vehicle for plugins to communicate the resources that they declare back to core - an "OutParameter". It can be accepted as an argument to a Platform's Deploy function, and any DeclaredResources added to it will be displayed on the Deployment api.

type Deployment 

type Deployment interface{}

type DeploymentConfig 

type DeploymentConfig struct {
	Id                    string
	Sequence              uint64
	ServerAddr            string
	ServerTls             bool
	ServerTlsSkipVerify   bool
	EntrypointInviteToken string
}

DeploymentConfig is the configuration for the behavior of a deployment. Platforms should take this argument and use the value to set the appropriate settings for the deployment

func (*DeploymentConfig) Env 

func (c *DeploymentConfig) Env() map[string]string

Env returns the environment variables that should be set for the entrypoint binary to have the proper configuration.

type DeploymentInfo 

type DeploymentInfo struct {
	// ComponentName is the name of the plugin that launched this deployment.
	ComponentName string

	// Labels of the deployment
	Labels map[string]string
}

DeploymentInfo is available to some plugins to get information about the deployment.

This is currently only available to ConfigSourcer and provides information about the running deployment.

type DeploymentWithUrl 

type DeploymentWithUrl interface {
	URL() string
}

A DeploymentWithUrl is a Deployment that can be referenced with an URL without using any external URL service (like Hashicorp Horizon). This means that the platform that hosts the workload can provide automatically an URL that is publicly (or company-internally) reachable.

Example: automatic routing of Kubernetes pods with an operator, Cloud Foundry's URLs, ...

type DestroyedResourcesResp 

type DestroyedResourcesResp struct {
	DestroyedResources []*proto.DestroyedResource
}

DestroyedResourcesResp is a component used as a vehicle for plugins to communicate the resources that they destroy back to core - an "OutParameter". It can be accepted as an argument to a Platform's Destroy function

type Destroyer 

type Destroyer interface {
	// DestroyFunc should return the method handle for the destroy operation.
	DestroyFunc() interface{}
}

Destroyer is responsible for destroying resources associated with this implementation. This can be implemented by all of the component types and will be called to perform cleanup on any created resources.

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 ExecResult 

type ExecResult struct {
	// ExitCode is the exit code for the process that was run.
	ExitCode int
}

ExecResult is returned by an Exec function to indicate the status of the run command.

type ExecSessionInfo 

type ExecSessionInfo struct {
	Input  io.Reader // effectively the stdin from the user (stdin)
	Output io.Writer // the output from the session (stdout)
	Error  io.Writer // an error output from the session (stderr)

	IsTTY bool // indicates if the input/output is a terminal

	// If this is a TTY, this is the terminal type (ie, the value of the TERM
	// environment variable)
	Term string

	// If this is a TTY, this is the initial window size.
	InitialWindowSize WindowSize

	// a channel that is sent the size of the users window. A new value
	// is sent on start and on each detection of window change.
	WindowSizeUpdates <-chan WindowSize

	// arguments to pass to the session. Normally interpreted as the first value
	// being the command to run and the rest arguments to that command.
	Arguments []string

	// environment variables to set within the context of the session.
	// This will contain configuration variables from the server
	// as well as any variable derived from external systems like vault
	// or kubernetes.
	Environment []string
}

ExecSessionInfo contains the information required by the exec plugin to setup a new exec and send the data back to a client. A ExecSessionInfo value is passed to a plugins ExecFunc() to allow the function to properly create the exec session.

type Execer 

type Execer interface {
	// ExecFunc should return the method handle for a exec session operation.
	// This function has the following types available:
	//  - hclog.Logger
	//  - context.Context
	//  - The Deployment type implemented by the plugin
	//  - *component.ExecSessionInfo
	//  - UI
	//
	// The ExecSessionInfo value contains all the things required launch the
	// exec session.
	ExecFunc() interface{}
}

Exec is responsible for starting the exec plugin to allow a deployment plugin to provide it's own exec functionality. By default, the waypoint exec functionality is achieved by creating a session on a long running instance of a deployment. But if a platform plugin type does not creat any long running instances, they can implement this interface and provide the exec functionality in their own bespoke way.

type Generation 

type Generation interface {
	// GenerationFunc should return the method handle for a function that
	// returns a `[]byte` result (and optionally an error). The `[]byte` is
	// the unique generation for the operation.
	//
	// The returned function will have access to all of the same parameters
	// as the operation function itself such as Deploy or Release.
	GenerationFunc() interface{}
}

Generation can be implemented by Platform and PlatformReleaser to explicitly specify a "generation" for a deploy or release. If this isn't implemented, Waypoint generates a random new generation per operation and assumes immutable behavior.

A "generation" specifies a unique identifier to the physical resources used by that operation. Two operations with the same generation are operating on the same underlying resources. This is used by Waypoint to detect mutable vs immutable operations; if two operations change generations, then Waypoint knows the operation created new resources rather than mutating old ones.

Waypoint uses this information to alter its behavior slightly. For example:

  • a user can only release a generation that isn't already released.
  • deployment URLs are identical for matching generations
  • certain functionality in the future such as canaries will use this

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.
	Workspace string

	// Project is the name of the project being targeted for the current operation.
	Project string

	// App is the name of the app being targeted for the current operation.
	// This could be blank if this is a project-scoped operation, but is never
	// blank for specific operations like build, deploy, etc.
	App string
}

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

type LabelSet 

type LabelSet struct {
	Labels map[string]string
}

type LinesChunkWriter 

type LinesChunkWriter interface {
	OutputLines([]string) error
}

LinesChunkWriter is used by a logs plugin to output a chunk of lines. A concrete implementation is provided to the plugin inside the LogsSessionInfo value.

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 the method handle for a logs operation.
	// This function has the following types available:
	//  - hclog.Logger
	//  - context.Context
	//  - The Deployment type implemented by the plugin
	//  - *component.LogViewer
	//  - UI
	LogsFunc() interface{}
}

LogPlatform is responsible for starting the logs plugin that allows a plugin to read logs for a deployment in its own way. This function has the following types available:

type LogViewer 

type LogViewer struct {
	// This is the time horizon log entries must be beyond to be emitted.
	StartingAt time.Time

	// The maximum number of log entries to emit.
	Limit int

	// New LogEvents should be sent to this channel.
	Output chan LogEvent
}

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

type LogsSessionInfo 

type LogsSessionInfo struct {
	Output LinesChunkWriter

	// The time horizon to begin showing logs from. Only show logs newer
	// than this time stamp.
	StartingFrom time.Time

	// The maximum number of lines to output.
	Limit int
}

ExecSessionInfo contains the information required by the exec plugin to setup a new exec and send the data back to a client. A ExecSessionInfo value is passed to a plugins ExecFunc() to allow the function to properly create the exec session.

type OutParameter 

type OutParameter interface {
	// contains filtered or unexported methods
}

OutParameter is an argument type that is used by plugins as a vehicle for returning data to core. A struct implementing this interface that indicates to the plugin system that the struct should not be included in a grpc advertised dynamic function spec, because it will be injected on the plugin side, not supplied from core over GRPC.

type Platform 

type Platform interface {
	// DeployFunc should return the method handle for the "deploy" operation.
	// The deploy function has access to the following and should use this
	// as necessary to perform a deploy.
	//
	//   artifact, artifact registry
	//
	DeployFunc() interface{}
}

Platform is responsible for deploying artifacts.

type PlatformReleaser 

type PlatformReleaser interface {
	// DefaultReleaserFunc() should return a function that returns
	// a ReleaseManger implementation. This ReleaseManager will NOT have
	// any config so it must work by default.
	DefaultReleaserFunc() interface{}
}

PlatformReleaser is an optional interface that a Platform can implement to provide default Release functionality. This only takes effect if no release is configured.

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 Registry 

type Registry interface {
	// PushFunc should return the method handle to the function for the "push"
	// operation. The push function should take an artifact type and push it
	// to the registry.
	PushFunc() interface{}
}

Registry is responsible for managing artifacts.

type RegistryAccess 

type RegistryAccess interface {
	AccessInfoFunc() interface{}
}

RegistryAccess is an optional interface that a registry plugin can implement. If it does, this function is called before the build plugin and the results are made available to the build plugin. This allows the build plugin to be doing the creation and export, where the registry plugin is just providing the information on where to publish the image.

type Release 

type Release interface {
	// URL is the URL to access this release.
	URL() string
}

type ReleaseManager 

type ReleaseManager interface {
	// ReleaseFunc should return the method handle for the "release" operation.
	ReleaseFunc() interface{}
}

ReleaseManager is responsible for taking a deployment and making it "released" which means that traffic can now route to it.

type RunningTask 

type RunningTask interface{}

RunningTask is returned from StartTask. It contains the state the plugin can use later to stop the task.

type Source 

type Source struct {
	App  string
	Path string
}

See Args.Source in the protobuf protocol.

type Status 

type Status interface {
	// StatusReportFunc should return a proto.StatusReport that details the
	// result of the most recent health check for a deployment.
	StatusFunc() interface{}
}

StatusReport can be implemented by Platform and PlatformReleaser to query the target platform and build a report of the current deployments health. If this isn't implemented, no status report will be built for the deployments.

type TaskLaunchInfo 

type TaskLaunchInfo struct {
	// OciUrl is a docker-run compatible specifier for an OCI image. For instance,
	// it supports the bare types like `ubuntu`, as well as toplevel versioned
	// types like `ubuntu:latest`, and any values that contain fully qualified
	// hostnames like `docker.io/library/ubuntu:latest`.
	OciUrl string

	// EnvironmentVariables is the set of variables that should be configured
	// for the task to see when it starts.
	EnvironmentVariables map[string]string

	// Entrypoint is the entrypoint override for this image. If this is not
	// set, then the default entrypoint for the OCI image should be used.
	Entrypoint []string

	// Arguments is passed as command line arguments to the image when it started.
	// If the image defines an entrypoint, then the arguments will be passed as
	// arguments to that program.
	Arguments []string
}

TaskLaunchInfo is used by TaskLauncher's StartTaskFunc operation. This type provides the details about how the new task should be configured.

type TaskLauncher 

type TaskLauncher interface {
	// StartTaskFunc should return a method for the "start task" operation.
	// This will have TaskLaunchInfo available to it to understand what the task
	// should do.
	StartTaskFunc() interface{}

	// StopTaskFunc is called to force a previously started task to stop. It will
	// be passed the state value returned by StartTaskFunc for identification.
	StopTaskFunc() interface{}

	// WatchTaskFunc is called after Start but before Stop to block and
	// watch a single task. It should stream output to the given UI and
	// return the exit status after it exits. It is given the state resulting
	// from StartTaskFunc so that it can look up the resource.
	WatchTaskFunc() interface{}
}

TaskLauncher launches a batch task, ie a task that runs to completion and does not restart.

type TaskResult 

type TaskResult struct {
	ExitCode int
}

TaskResult is the result value that must be returned by the RunTask function.

type Template 

type Template interface {
	// TemplateData returns the template information to make available.
	//
	// This should return empty values for available keys even if the
	// struct it is attached to is nil. This enables the automated documentation
	// generator to work properly. Do not return "nil" when there is no data!
	// And expect that this will be called on nil or empty values.
	TemplateData() map[string]interface{}
}

Template can be implemented by Artifact, Deployment, and Release. This will expose this information as available variables in the HCL configuration as well as functions in the `template`-prefixed family, such as `templatefile`.

If Template is NOT implemented, we will automatically infer template data based on exported variables of the result value. This may not be desirable in which case you should implement Template and return nil.

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
	BuilderType                    // Builder
	RegistryType                   // Registry
	PlatformType                   // Platform
	ReleaseManagerType             // ReleaseManager
	LogPlatformType                // LogPlatform
	AuthenticatorType              // Authenticator
	MapperType                     // Mapper
	ConfigSourcerType              // ConfigSourcer
	TaskLauncherType               // TaskLauncher

)

func (Type) String 

func (i Type) String() string

type WindowSize 

type WindowSize struct {
	Height int // the height (in lines) of the terminal
	Width  int // the width (in lines) of the terminal
}

WindowSize provides information about the size of the terminal window.

type WorkspaceDestroyer 

type WorkspaceDestroyer interface {
	// DestroyWorkspaceFunc is called when a workspace destroy operation is performed.
	//
	// This will only be called if that plugin had performed some operation
	// previously on the workspace. This may be called multiple times so it should
	// be idempotent. This will be called after all individual DestroyFuncs are
	// complete.
	DestroyWorkspaceFunc() interface{}
}

WorkspaceDestroyer is called when a workspace destroy operation is performed (typically via the "waypoint destroy" CLI). This can be implemented by any plugin.

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.