runner

Documentation

Index

• Variables
• type Option
  • func ByIdOnly() Option
  • func WithAcceptTimeout(dur time.Duration) Option
  • func WithClient(client pb.WaypointClient) Option
  • func WithComponentFactory(t component.Type, f *factory.Factory) Option
  • func WithCookie(v string) Option
  • func WithDynamicConfig(set bool) Option
  • func WithId(id string) Option
  • func WithLabels(v map[string]string) Option
  • func WithLocal(ui terminal.UI) Option
  • func WithLogger(logger hclog.Logger) Option
  • func WithODR(profileId string) Option
  • func WithStateDir(v string) 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) AcceptParallel(ctx context.Context, count int)
  • func (r *Runner) Close() error
  • func (r *Runner) Id() string
  • func (r *Runner) Start(ctx context.Context) error

Variables

var (
	ErrClosed  = errors.New("runner is closed")
	ErrTimeout = errors.New("runner timed out waiting for a job")
)

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 WithAcceptTimeout

func WithAcceptTimeout(dur time.Duration) Option

WithAcceptTimeout sets a maximum amount of time to wait for a job before returning that one was not accepted.

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.

If this is specified, the client MUST use a tokenutil.ContextToken type for the PerRPCCredentials setting. This package and others will use context overrides for the token. If you do not use this, things will break.

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 WithCookie

func WithCookie(v string) Option

WithCookie sets the cookie to send with all API requests. If this cookie does not match the remote server, API requests will fail.

A cookie is REQUIRED FOR ADOPTION. If this is not set, the adoption process will be skipped and only pre-adoption (a preset token) will work.

func WithDynamicConfig

func WithDynamicConfig(set bool) Option

func WithId

func WithId(id string) Option

WithId sets the id of the runner directly. This isused when the when the server is expecting the runner to use a certain ID, such as when used via ondemand runners.

func WithLabels

func WithLabels(v map[string]string) Option

WithLabels sets the labels for this runner.

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().

func WithODR

func WithODR(profileId string) Option

WithODR configures this runner to be an on-demand runner. This will flag this to the server on registration.

func WithStateDir

func WithStateDir(v string) Option

WithStateDir sets the state directory. This directory is used for runner state between restarts. This is optional, a runner can be stateless, but has some limitations. The state dir enables:

• persisted runner ID across restarts
• persisted adoption token across restarts

The state directory will be created if it does not exist.

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 its own errors via r's logger.

func (*Runner) AcceptParallel

func (r *Runner) AcceptParallel(ctx context.Context, count int)

AcceptParallel allows up to count jobs to be accepted and executing concurrently.

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(ctx context.Context) 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.