exec

Documentation

Index

• Variables
• func Do(ctx context.Context, task *api.Task, ctlr Controller) (*api.TaskStatus, error)
• func IsTemporary(err error) bool
• func MakeTemporary(err error) error
• type ConfigGetter
• type ConfigsManager
• type ConfigsProvider
• type ContainerStatuser
• type Controller
  • func Resolve(ctx context.Context, task *api.Task, executor Executor) (Controller, *api.TaskStatus, error)
• type ControllerLogs
• type DependencyGetter
• type DependencyManager
• type Executor
• type ExitCoder
• type LogPublisher
• type LogPublisherFunc
  • func (fn LogPublisherFunc) Publish(ctx context.Context, message api.LogMessage) error
• type LogPublisherProvider
• type PortStatuser
• type SecretGetter
• type SecretsManager
• type SecretsProvider
• type StubController
  • func NewStubController() *StubController
  • func (sc *StubController) Close() error
  • func (sc *StubController) Prepare(ctx context.Context) error
  • func (sc *StubController) Remove(ctx context.Context) error
  • func (sc *StubController) Shutdown(ctx context.Context) error
  • func (sc *StubController) Start(ctx context.Context) error
  • func (sc *StubController) Terminate(ctx context.Context) error
  • func (sc *StubController) Update(ctx context.Context, t *api.Task) error
  • func (sc *StubController) Wait(ctx context.Context) error
• type Temporary

Variables

var (
	// ErrRuntimeUnsupported encountered when a task requires a runtime
	// unsupported by the executor.
	ErrRuntimeUnsupported = errors.New("exec: unsupported runtime")

	// ErrTaskPrepared is called if the task is already prepared.
	ErrTaskPrepared = errors.New("exec: task already prepared")

	// ErrTaskStarted can be returned from any operation that cannot be
	// performed because the task has already been started. This does not imply
	// that the task is running but rather that it is no longer valid to call
	// Start.
	ErrTaskStarted = errors.New("exec: task already started")

	// ErrTaskUpdateRejected is returned if a task update is rejected by a controller.
	ErrTaskUpdateRejected = errors.New("exec: task update rejected")

	// ErrControllerClosed returned when a task controller has been closed.
	ErrControllerClosed = errors.New("exec: controller closed")

	// ErrTaskRetry is returned by Do when an operation failed by should be
	// retried. The status should still be reported in this case.
	ErrTaskRetry = errors.New("exec: task retry")

	// ErrTaskNoop returns when the a subsequent call to Do will not result in
	// advancing the task. Callers should avoid calling Do until the task has been updated.
	ErrTaskNoop = errors.New("exec: task noop")
)

Functions

func Do

func Do(ctx context.Context, task *api.Task, ctlr Controller) (*api.TaskStatus, error)

Do progresses the task state using the controller performing a single operation on the controller. The return TaskStatus should be marked as the new state of the task.

The returned status should be reported and placed back on to task before the next call. The operation can be cancelled by creating a cancelling context.

Errors from the task controller will reported on the returned status. Any errors coming from this function should not be reported as related to the individual task.

If ErrTaskNoop is returned, it means a second call to Do will result in no change. If ErrTaskDead is returned, calls to Do will no longer result in any action.

func IsTemporary

func IsTemporary(err error) bool

IsTemporary returns true if the error or a recursive cause returns true for temporary.

func MakeTemporary

func MakeTemporary(err error) error

MakeTemporary makes the error temporary.

Types

type ConfigGetter

type ConfigGetter interface {
	// Get returns the the config with a specific config ID, if available.
	// When the config is not available, the return will be nil.
	Get(configID string) (*api.Config, error)
}

ConfigGetter contains config data necessary for the Controller.

type ConfigsManager

type ConfigsManager interface {
	ConfigGetter

	Add(configs ...api.Config) // add one or more configs
	Remove(configs []string)   // remove the configs by ID
	Reset()                    // remove all configs
}

ConfigsManager is the interface for config storage and updates.

type ConfigsProvider

type ConfigsProvider interface {
	Configs() ConfigsManager
}

ConfigsProvider is implemented by objects that can store configs, typically an executor.

type ContainerStatuser

type ContainerStatuser interface {
	// ContainerStatus returns the status of the target container, if
	// available. When the container is not available, the status will be nil.
	ContainerStatus(ctx context.Context) (*api.ContainerStatus, error)
}

ContainerStatuser reports status of a container.

This can be implemented by controllers or error types.

type Controller

type Controller interface {
	// Update the task definition seen by the controller. Will return
	// ErrTaskUpdateFailed if the provided task definition changes fields that
	// cannot be changed.
	//
	// Will be ignored if the task has exited.
	Update(ctx context.Context, t *api.Task) error

	// Prepare the task for execution. This should ensure that all resources
	// are created such that a call to start should execute immediately.
	Prepare(ctx context.Context) error

	// Start the target and return when it has started successfully.
	Start(ctx context.Context) error

	// Wait blocks until the target has exited.
	Wait(ctx context.Context) error

	// Shutdown requests to exit the target gracefully.
	Shutdown(ctx context.Context) error

	// Terminate the target.
	Terminate(ctx context.Context) error

	// Remove all resources allocated by the controller.
	Remove(ctx context.Context) error

	// Close closes any ephemeral resources associated with controller instance.
	Close() error
}

Controller controls execution of a task.

func Resolve

func Resolve(ctx context.Context, task *api.Task, executor Executor) (Controller, *api.TaskStatus, error)

Resolve attempts to get a controller from the executor and reports the correct status depending on the tasks current state according to the result.

Unlike Do, if an error is returned, the status should still be reported. The error merely reports the failure at getting the controller.

type ControllerLogs

type ControllerLogs interface {
	// Logs will write publisher until the context is cancelled or an error
	// occurs.
	Logs(ctx context.Context, publisher LogPublisher, options api.LogSubscriptionOptions) error
}

ControllerLogs defines a component that makes logs accessible.

Can usually be accessed on a controller instance via type assertion.

type DependencyGetter

type DependencyGetter interface {
	Secrets() SecretGetter
	Configs() ConfigGetter
}

DependencyGetter is a meta-object that can provide access to typed objects such as secrets and configs.

type DependencyManager

type DependencyManager interface {
	SecretsProvider
	ConfigsProvider
}

DependencyManager is a meta-object that can keep track of typed objects such as secrets and configs.

type Executor

type Executor interface {
	// Describe returns the underlying node description.
	Describe(ctx context.Context) (*api.NodeDescription, error)

	// Configure uses the node object state to propagate node
	// state to the underlying executor.
	Configure(ctx context.Context, node *api.Node) error

	// Controller provides a controller for the given task.
	Controller(t *api.Task) (Controller, error)

	// SetNetworkBootstrapKeys passes the symmetric keys from the
	// manager to the executor.
	SetNetworkBootstrapKeys([]*api.EncryptionKey) error
}

Executor provides controllers for tasks.

type ExitCoder

type ExitCoder interface {
	// ExitCode returns the exit code.
	ExitCode() int
}

ExitCoder is implemented by errors that have an exit code.

type LogPublisher

type LogPublisher interface {
	Publish(ctx context.Context, message api.LogMessage) error
}

LogPublisher defines the protocol for receiving a log message.

type LogPublisherFunc

type LogPublisherFunc func(ctx context.Context, message api.LogMessage) error

LogPublisherFunc implements publisher with just a function.

func (LogPublisherFunc) Publish

func (fn LogPublisherFunc) Publish(ctx context.Context, message api.LogMessage) error

Publish calls the wrapped function.

type LogPublisherProvider

type LogPublisherProvider interface {
	Publisher(ctx context.Context, subscriptionID string) (LogPublisher, func(), error)
}

LogPublisherProvider defines the protocol for receiving a log publisher

type PortStatuser

type PortStatuser interface {
	// PortStatus returns the status on a list of PortConfigs
	// which are managed at the host level by the controller.
	PortStatus(ctx context.Context) (*api.PortStatus, error)
}

PortStatuser reports status of ports which are allocated by the executor

type SecretGetter

type SecretGetter interface {
	// Get returns the the secret with a specific secret ID, if available.
	// When the secret is not available, the return will be nil.
	Get(secretID string) (*api.Secret, error)
}

SecretGetter contains secret data necessary for the Controller.

type SecretsManager

type SecretsManager interface {
	SecretGetter

	Add(secrets ...api.Secret) // add one or more secrets
	Remove(secrets []string)   // remove the secrets by ID
	Reset()                    // remove all secrets
}

SecretsManager is the interface for secret storage and updates.

type SecretsProvider

type SecretsProvider interface {
	Secrets() SecretsManager
}

SecretsProvider is implemented by objects that can store secrets, typically an executor.

type StubController

type StubController struct {
	Controller
	UpdateFn    func(ctx context.Context, t *api.Task) error
	PrepareFn   func(ctx context.Context) error
	StartFn     func(ctx context.Context) error
	WaitFn      func(ctx context.Context) error
	ShutdownFn  func(ctx context.Context) error
	TerminateFn func(ctx context.Context) error
	RemoveFn    func(ctx context.Context) error
	CloseFn     func() error
	// contains filtered or unexported fields
}

StubController implements the Controller interface, but allows you to specify behaviors for each of its methods.

func NewStubController

func NewStubController() *StubController

NewStubController returns an initialized StubController

func (*StubController) Close

func (sc *StubController) Close() error

Close is part of the Controller interface

func (*StubController) Prepare

func (sc *StubController) Prepare(ctx context.Context) error

Prepare is part of the Controller interface

func (*StubController) Remove

func (sc *StubController) Remove(ctx context.Context) error

Remove is part of the Controller interface

func (*StubController) Shutdown

func (sc *StubController) Shutdown(ctx context.Context) error

Shutdown is part of the Controller interface

func (*StubController) Start

func (sc *StubController) Start(ctx context.Context) error

Start is part of the Controller interface

func (*StubController) Terminate

func (sc *StubController) Terminate(ctx context.Context) error

Terminate is part of the Controller interface

func (*StubController) Update

func (sc *StubController) Update(ctx context.Context, t *api.Task) error

Update is part of the Controller interface

func (*StubController) Wait

func (sc *StubController) Wait(ctx context.Context) error

Wait is part of the Controller interface

type Temporary

type Temporary interface {
	Temporary() bool
}

Temporary indicates whether or not the error condition is temporary.

If this is encountered in the controller, the failing operation will be retried when this returns true. Otherwise, the operation is considered fatal.