core

Documentation

Overview

Package core exposes a high-level API for the expected operations of the project. This can be consumed by the CLI, web APIs, etc. This is the safest set of APIs to use.

The entrypoint for core is Project initialized with NewProject. All further APIs and operations hang off of this struct. For example, to initiate a build for an app in a project you could use Project.App.Build().

Eventually this package will also contain UI abstractions or hooks so that you can build a more responsive UI around the long-running operations of this package.

Index

• func TestFactory(t testing.T, typ component.Type) *factory.Factory
• func TestFactoryRegister(t testing.T, f *factory.Factory, n string, v interface{})
• func TestFactorySingle(t testing.T, typ component.Type, n string) (*factory.Factory, *mock.Mock)
• type App
  • func TestApp(t testing.T, p *Project, n string) *App
  • func (a *App) Auth(ctx context.Context, c *Component) (*component.AuthResult, error)
  • func (a *App) Build(ctx context.Context, optFuncs ...BuildOption) (*pb.Build, *pb.PushedArtifact, error)
  • func (a *App) CanAuth(comp *Component) bool
  • func (a *App) CanDestroyDeploy() bool
  • func (a *App) CanDestroyRelease() bool
  • func (a *App) Close() error
  • func (a *App) Components(ctx context.Context) ([]*Component, error)
  • func (a *App) ConfigSync(ctx context.Context) error
  • func (a *App) Deploy(ctx context.Context, push *pb.PushedArtifact) (*pb.Deployment, error)
  • func (a *App) DeploymentStatusReport(ctx context.Context, deployTarget *pb.Deployment) (*pb.StatusReport, error)
  • func (a *App) Destroy(ctx context.Context) error
  • func (a *App) DestroyDeploy(ctx context.Context, d *pb.Deployment) error
  • func (a *App) DestroyRelease(ctx context.Context, d *pb.Release) error
  • func (a *App) Exec(ctx context.Context, id string, d *pb.Deployment, enableDynConfig bool) error
  • func (a *App) Logs(ctx context.Context, id string, d *pb.Deployment, startTime time.Time, ...) error
  • func (a *App) PushBuild(ctx context.Context, optFuncs ...PushBuildOption) (*pb.PushedArtifact, error)
  • func (a *App) Ref() *pb.Ref_Application
  • func (a *App) Release(ctx context.Context, target *pb.Deployment) (*pb.Release, component.Release, error)
  • func (a *App) ReleaseStatusReport(ctx context.Context, releaseTarget *pb.Release) (*pb.StatusReport, error)
  • func (a *App) ValidateAuth(ctx context.Context, c *Component) error
• type BuildOption
  • func BuildWithPush(v bool) BuildOption
• type Component
  • func (c *Component) Close() error
• type Option
  • func WithClient(client pb.WaypointClient) Option
  • func WithComponents(fs map[component.Type]*factory.Factory) Option
  • func WithConfig(c *config.Config) Option
  • func WithDataDir(dir *datadir.Project) Option
  • func WithFactory(t component.Type, f *factory.Factory) Option
  • func WithJobInfo(info *component.JobInfo) Option
  • func WithLabels(m map[string]string) Option
  • func WithLogger(log hclog.Logger) Option
  • func WithMappers(m ...*argmapper.Func) Option
  • func WithUI(ui terminal.UI) Option
  • func WithVariables(vs variables.Values) Option
  • func WithWorkspace(ws string) Option
• type Project
  • func NewProject(ctx context.Context, os ...Option) (*Project, error)
  • func TestProject(t testing.T, opts ...Option) *Project
  • func (p *Project) App(name string) (*App, error)
  • func (p *Project) Apps() []string
  • func (p *Project) Client() pb.WaypointClient
  • func (p *Project) Close() error
  • func (p *Project) Ref() *pb.Ref_Project
  • func (p *Project) WorkspaceRef() *pb.Ref_Workspace
• type PushBuildOption
  • func PushWithBuild(b *pb.Build) PushBuildOption

Functions

func TestFactory

func TestFactory(t testing.T, typ component.Type) *factory.Factory

TestFactory creates a factory for the given component type.

func TestFactoryRegister

func TestFactoryRegister(t testing.T, f *factory.Factory, n string, v interface{})

TestFactoryRegister registers a singleton value to be returned for the factory for the name n.

func TestFactorySingle

func TestFactorySingle(t testing.T, typ component.Type, n string) (*factory.Factory, *mock.Mock)

TestFactorySingle creates a factory for the given component type and registers a single implementation and returns that mock. This is useful to create a factory for the WithFactory option that returns a mocked value that can be tested against.

Types

type App

type App struct {
	// UI is the UI that should be used for any output that is specific
	// to this app vs the project UI.
	UI terminal.UI
	// contains filtered or unexported fields
}

App represents a single application and exposes all the operations that can be performed on an application.

An App is only valid if it was returned by Project.App. The behavior of App if constructed in any other way is undefined and likely to result in crashes.

func TestApp

func TestApp(t testing.T, p *Project, n string) *App

TestApp returns the app named n in the project.

func (*App) Auth

func (a *App) Auth(ctx context.Context, c *Component) (*component.AuthResult, error)

Auth authenticates a component. This will return an error if the component doesn't support auth. If this returns nil, then the auth function succeeded but the component itself may still not be authenticated. You must check again with ValidateAuth.

func (*App) Build

func (a *App) Build(ctx context.Context, optFuncs ...BuildOption) (
	*pb.Build,
	*pb.PushedArtifact,
	error,
)

Build builds the artifact from source for this app. TODO(mitchellh): test

func (*App) CanAuth

func (a *App) CanAuth(comp *Component) bool

CanAuth returns true if the provided component supports authenticating and validating authentication for plugins

func (*App) CanDestroyDeploy

func (a *App) CanDestroyDeploy() bool

CanDestroyDeploy returns true if this app supports destroying deployments.

func (*App) CanDestroyRelease

func (a *App) CanDestroyRelease() bool

CanDestroyRelease returns true if this app supports destroying releases.

func (*App) Close

func (a *App) Close() error

Close is called to clean up any resources. This should be called whenever the app is done being used. This will be called by Project.Close.

func (*App) Components

func (a *App) Components(ctx context.Context) ([]*Component, error)

Components initializes and returns all the components that are defined for this app across all stages. The caller must call close on all the components to clean up resources properly.

func (*App) ConfigSync

func (a *App) ConfigSync(ctx context.Context) error

ConfigSync writes all the app configuration in the waypoint.hcl file to the server.

func (*App) Deploy

func (a *App) Deploy(ctx context.Context, push *pb.PushedArtifact) (*pb.Deployment, error)

Deploy deploys the given artifact. TODO(mitchellh): test

func (*App) DeploymentStatusReport

func (a *App) DeploymentStatusReport(
	ctx context.Context,
	deployTarget *pb.Deployment,
) (*pb.StatusReport, error)

func (*App) Destroy

func (a *App) Destroy(ctx context.Context) error

Destroy will destroy all the physical resources for this app in the current configured workspace. If this returns an error, it is possible that the destroy is in a partial state.

func (*App) DestroyDeploy

func (a *App) DestroyDeploy(ctx context.Context, d *pb.Deployment) error

DestroyDeploy destroyes a specific deployment.

func (*App) DestroyRelease

func (a *App) DestroyRelease(ctx context.Context, d *pb.Release) error

DestroyRelease destroyes a specific release.

func (*App) Exec

func (a *App) Exec(ctx context.Context, id string, d *pb.Deployment, enableDynConfig bool) error

Exec launches an exec plugin. Exec plugins are only used if the plugin's platforms plugin wishes to implement the ExecFunc protocol. And even then, we only trigger this code path if there are no long running instances associated with the given Deployment. Under traditional platform scenarios, we don't need to run a exec plugin, instead the exec command can connect directly to a long running instance to provide the exec session. The result of running this task is that the platform plugin is called and made available as a virtual instance with the given id. enableDynConfig controls if exec jobs will attempt to read from any dynamic config sources. Reading from those sources requires the runner to have credentials to those sources.

func (*App) Logs

func (a *App) Logs(ctx context.Context, id string, d *pb.Deployment, startTime time.Time, limit int) error

Logs launches a logs plugin. Logs plugins are only used if the plugin's platforms plugin wishes to implement the LogsFunc protocol. Under traditional platform scenarios, we don't need to run a logs plugin, instead the logs command returns data buffered on the server sent via the entrypoint binary. The result of running this task is that the platform plugin is called and made available as a virtual instance with the given id. startTime inidcates the time horizon a log entry must be beyond before it is returned. limit controls how many log entries to emit.

func (*App) PushBuild

func (a *App) PushBuild(ctx context.Context, optFuncs ...PushBuildOption) (*pb.PushedArtifact, error)

Push pushes the given build to the configured registry. This requires that the build artifact be available, which we leave up to the caller. Therefore, please note that this generally can't be called on separate machines, long after a build is done (because the person may have deleted the physical artifact, etc.).

TODO(mitchellh): test

func (*App) Ref

func (a *App) Ref() *pb.Ref_Application

Ref returns the reference to this application for us in API calls.

func (*App) Release

func (a *App) Release(ctx context.Context, target *pb.Deployment) (
	*pb.Release,
	component.Release,
	error,
)

Release releases a set of deploys. TODO(mitchellh): test

func (*App) ReleaseStatusReport

func (a *App) ReleaseStatusReport(
	ctx context.Context,
	releaseTarget *pb.Release,
) (*pb.StatusReport, error)

func (*App) ValidateAuth

func (a *App) ValidateAuth(ctx context.Context, c *Component) error

ValidateAuth validates if the component is properly authenticated. This will always return nil if the component doesn't support auth.

type BuildOption

type BuildOption func(*buildOptions) error

BuildOption is used to configure a Build

func BuildWithPush

func BuildWithPush(v bool) BuildOption

BuildWithPush sets whether or not the build will push. The default is for the build to push.

type Component

type Component struct {
	Value interface{}
	Info  *pb.Component
	// contains filtered or unexported fields
}

func (*Component) Close

func (c *Component) Close() error

Close cleans up any resources associated with the Component. Close should always be called when the component is done being used.

type Option

type Option func(*Project, *options)

Option is used to set options for NewProject.

func WithClient

func WithClient(client pb.WaypointClient) Option

WithClient sets the API client to use.

func WithComponents

func WithComponents(fs map[component.Type]*factory.Factory) Option

WithComponents sets the factories for components.

func WithConfig

func WithConfig(c *config.Config) Option

WithConfig uses the given project configuration for initializing the Project. This configuration must be validated already prior to using this option.

func WithDataDir

func WithDataDir(dir *datadir.Project) Option

WithDataDir sets the datadir that will be used for this project.

func WithFactory

func WithFactory(t component.Type, f *factory.Factory) Option

WithFactory sets a factory for a component type. If this isn't set for any component type, then the builtin mapper will be used.

func WithJobInfo

func WithJobInfo(info *component.JobInfo) Option

WithJobInfo sets the base job info used for any executed operations.

func WithLabels

func WithLabels(m map[string]string) Option

WithLabels sets the labels that will override any other labels set.

func WithLogger

func WithLogger(log hclog.Logger) Option

WithLogger sets the logger to use with the project. If this option is not provided, a default logger will be used (`hclog.L()`).

func WithMappers

func WithMappers(m ...*argmapper.Func) Option

WithMappers adds the mappers to the list of mappers.

func WithUI

func WithUI(ui terminal.UI) Option

WithUI sets the UI to use. If this isn't set, a BasicUI is used.

func WithVariables

func WithVariables(vs variables.Values) Option

WithVariables sets the final set of variable values for the operation.

func WithWorkspace

func WithWorkspace(ws string) Option

WithWorkspace sets the workspace we'll be working in.

type Project

type Project struct {

	// UI is the terminal UI to use for messages related to the project
	// as a whole. These messages will show up unprefixed for example compared
	// to the app-specific UI.
	UI terminal.UI
	// contains filtered or unexported fields
}

Project represents a project with one or more applications.

The Close function should be called when finished with the project to properly clean up any open resources.

func NewProject

func NewProject(ctx context.Context, os ...Option) (*Project, error)

NewProject creates a new Project with the given options.

func TestProject

func TestProject(t testing.T, opts ...Option) *Project

TestProject returns a fully in-memory and side-effect free Project that can be used for testing. Additional options can be given to provide your own factories, configuration, etc.

func (*Project) App

func (p *Project) App(name string) (*App, error)

App initializes and returns the app with the given name. This returns an error with codes.NotFound if the app is not found.

func (*Project) Apps

func (p *Project) Apps() []string

Apps returns the list of app names that are present in this project. This is the list of applications defined in the Waypoint configuration and may not match what the Waypoint server knows about.

func (*Project) Client

func (p *Project) Client() pb.WaypointClient

Client returns the API client for the backend server.

func (*Project) Close

func (p *Project) Close() error

Close is called to clean up resources allocated by the project. This should be called and blocked on to gracefully stop the project.

func (*Project) Ref

func (p *Project) Ref() *pb.Ref_Project

Ref returns the project ref for API calls.

func (*Project) WorkspaceRef

func (p *Project) WorkspaceRef() *pb.Ref_Workspace

WorkspaceRef returns the project ref for API calls.

type PushBuildOption

type PushBuildOption func(*pushBuildOptions) error

PushBuildOption is used to configure a Build

func PushWithBuild

func PushWithBuild(b *pb.Build) PushBuildOption

BuildWithPush sets whether or not the build will push. The default is for the build to push.