runner

Documentation

Index

• Variables
• type Option
  • func ByIdOnly() Option
  • func WithClient(client pb.WaypointClient) Option
  • func WithComponentFactory(t component.Type, f *factory.Factory) Option
  • func WithDynamicConfig(set bool) Option
  • func WithLocal(ui terminal.UI) Option
  • func WithLogger(logger hclog.Logger) Option
• type Runner
  • func New(opts ...Option) (*Runner, error)
  • func TestRunner(t testing.T, opts ...Option) *Runner
  • func (r *Runner) Accept(ctx context.Context) error
  • func (r *Runner) AcceptExact(ctx context.Context, id string) error
  • func (r *Runner) AcceptMany(ctx context.Context)
  • func (r *Runner) Close() error
  • func (r *Runner) Id() string
  • func (r *Runner) Start() error

Variables

var ErrClosed = errors.New("runner is closed")

Types

type Option

type Option func(*Runner, *config) error

func ByIdOnly

func ByIdOnly() Option

ByIdOnly sets it so that only jobs that target this runner by specific ID may be assigned.

func WithClient

func WithClient(client pb.WaypointClient) Option

WithClient sets the client directly. In this case, the runner won't attempt any connection at all regardless of other configuration (env vars or waypoint config file). This will be used.

func WithComponentFactory

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

WithComponentFactory sets a factory for a component type. If this isn't set for a component type, then the builtins will be used.

func WithDynamicConfig

func WithDynamicConfig(set bool) Option

func WithLocal

func WithLocal(ui terminal.UI) Option

WithLocal sets the runner to local mode. This only changes the UI behavior to use the given UI. If ui is nil then the normal streamed UI will be used.

func WithLogger

func WithLogger(logger hclog.Logger) Option

WithLogger sets the logger that the runner will use. If this isn't set it uses hclog.L().

type Runner

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

Runners in Waypoint execute operations. These can be local (the CLI) or they can be remote (triggered by some webhook). In either case, they share this same underlying implementation.

To use a runner:

1. Initialize it with New. This will setup some initial state but will not register with the server or run jobs.

2. Start the runner with "Start". This will register the runner and kick off some management goroutines. This will not execute any jobs.

3. Run a single job with "Accept". This is named to be similar to a network listener "accepting" a connection. This will request a single job from the Waypoint server, block until one is available, and execute it. Repeat this call for however many jobs you want to execute.

4. Clean up with "Close". This will gracefully exit the runner, waiting for any running jobs to finish.

func New

func New(opts ...Option) (*Runner, error)

New initializes a new runner.

You must call Start to start the runner and register with the Waypoint server. See the Runner struct docs for more details.

func TestRunner

func TestRunner(t testing.T, opts ...Option) *Runner

TestRunner returns an initialized runner pointing to an in-memory test server. This will close automatically on test completion.

This will also change the working directory to a temporary directory so that any side effect file creation doesn't impact the real working directory. If you need to use your working directory, query it before calling this.

func (*Runner) Accept

func (r *Runner) Accept(ctx context.Context) error

Accept will accept and execute a single job. This will block until a job is available.

An error is only returned if there was an error internal to the runner. Errors during job execution are expected (i.e. a project build is misconfigured) and will be reported on the job.

Two specific errors to watch out for are:

• ErrClosed (in this package) which means that the runner is closed and Accept can no longer be called.
• code = NotFound which means that the runner was deregistered. This means the runner has to be fully recycled: Close called, a new runner started.

This is safe to be called concurrently which can be used to execute multiple jobs in parallel as a runner.

func (*Runner) AcceptExact

func (r *Runner) AcceptExact(ctx context.Context, id string) error

AcceptExact is the same as Accept except that it accepts only a job with exactly the given ID. This is used by Waypoint only in local execution mode as an extra security measure to prevent other jobs from being assigned to the runner.

func (*Runner) AcceptMany

func (r *Runner) AcceptMany(ctx context.Context)

AcceptMany will accept jobs and execute them on after another as they are accepted. This is meant to be run in a goroutine and reports it's own errors via r's logger.

func (*Runner) Close

func (r *Runner) Close() error

Close gracefully exits the runner. This will wait for any pending job executions to complete and then deregister the runner. After this is called, Start and Accept will no longer function and will return errors immediately.

func (*Runner) Id

func (r *Runner) Id() string

Id returns the runner ID.

func (*Runner) Start

func (r *Runner) Start() error

Start starts the runner by registering the runner with the Waypoint server. This will spawn goroutines for management. This will return after registration so this should not be executed in a goroutine.