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

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{}) (*any.Any, error)

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

func ProtoAnySlice

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

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

type Deployment interface{}

type DeploymentConfig

type DeploymentConfig struct {
	Id                    string
	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 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
}

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 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 value[1]. 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.

[1]: https://developers.google.com/protocol-buffers/docs/proto3#any

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

)

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.

Directories

Path Synopsis