engines

Documentation

Overview

Package engines specifies the interfaces that each engine must implement.

This is all rooted at the EngineProvider interface specified in the extpoints package, where implementors should register their engine.

Consumers of this package should import the extpoints package and use the 'EngineProvider.Lookup(name) EngineProvider' function to load the desired engine.

Notice that many of the features specified are optional, and it's often possible to return an ErrFeatureNotSupported error rather than implementing the feature.

Index

• Variables
• func Engines() map[string]EngineProvider
• func Register(name string, provider EngineProvider)
• type Capabilities
• type Display
• type Engine
• type EngineBase
  • func (EngineBase) Capabilities() Capabilities
  • func (EngineBase) Dispose() error
  • func (EngineBase) Documentation() []runtime.Section
  • func (EngineBase) NewVolume(options interface{}) (Volume, error)
  • func (EngineBase) NewVolumeBuilder(options interface{}) (VolumeBuilder, error)
  • func (EngineBase) PayloadSchema() schematypes.Object
  • func (EngineBase) VolumeSchema() schematypes.Schema
• type EngineOptions
• type EngineProvider
• type EngineProviderBase
  • func (EngineProviderBase) ConfigSchema() schematypes.Schema
• type FileHandler
• type ResultSet
• type ResultSetBase
  • func (ResultSetBase) ArchiveSandbox() (ioext.ReadSeekCloser, error)
  • func (ResultSetBase) Dispose() error
  • func (ResultSetBase) ExtractFile(string) (ioext.ReadSeekCloser, error)
  • func (ResultSetBase) ExtractFolder(string, FileHandler) error
• type Sandbox
• type SandboxBase
  • func (SandboxBase) Abort() error
  • func (SandboxBase) Kill() error
  • func (SandboxBase) ListDisplays() ([]Display, error)
  • func (SandboxBase) NewShell(command []string, tty bool) (Shell, error)
  • func (SandboxBase) OpenDisplay(string) (io.ReadWriteCloser, error)
• type SandboxBuilder
• type SandboxBuilderBase
  • func (SandboxBuilderBase) AttachProxy(string, http.Handler) error
  • func (SandboxBuilderBase) AttachVolume(string, Volume, bool) error
  • func (SandboxBuilderBase) Discard() error
  • func (SandboxBuilderBase) SetEnvironmentVariable(string, string) error
• type SandboxOptions
• type Shell
• type Volume
• type VolumeBase
  • func (VolumeBase) Dispose() error
• type VolumeBuilder
• type VolumeBuilderBase
  • func (VolumeBuilderBase) Discard() error

Variables

var ErrEngineNotSupported = errors.New("Engine is not available in the current configuration")

ErrEngineNotSupported is used to indicate that the engine isn't supported in the current configuration.

var ErrFeatureNotSupported = errors.New("Feature not supported by the current engine")

ErrFeatureNotSupported is a common error that may be returned from optional Engine methods to indicate the engine implementation doesn't support the given feature.

Note, all methods are allowed to return this error, some methods are required, and may not return this error.

When the worker encounters this error from an optional method, it should workaround if possible, but most likely resolve the task as "exception" with reason "malformed-payload".

var ErrHandlerInterrupt = errors.New("Handler returned an error and interrupted iteration")

ErrHandlerInterrupt is returned when a handler that was given returns an error

var ErrImmutableMountNotSupported = errors.New("The engine doesn't support immutable volume attachements")

ErrImmutableMountNotSupported is returned when volume attachements are supported, but immutable mounts aren't supported.

var ErrMaxConcurrencyExceeded = errors.New("Engine is cannot run more than " +
	"Engine.Capabilities().MaxCurrency sandbox in parallel")

ErrMaxConcurrencyExceeded is returned when the engine has limitation on how many sandboxes it can run in parallel and this limit is violated.

var ErrMutableMountNotSupported = errors.New("The engine doesn't support mutable volume attachments")

ErrMutableMountNotSupported is returned when volume attachments are supported, but mutable mounts aren't supported.

var ErrNamingConflict = errors.New("Conflicting name is already in use")

ErrNamingConflict is used to indicate that a name is already in use.

var ErrNoSuchDisplay = errors.New("No such display exists")

ErrNoSuchDisplay is used to indicate that a requested display doesn't exist.

var ErrResourceNotFound = errors.New("The referenced resource wasn't found")

ErrResourceNotFound is returned when trying to extract a file or folder that doesn't exist.

var ErrSandboxAborted = errors.New("Execution of sandbox was aborted")

ErrSandboxAborted is used to indicate that a Sandbox has been aborted.

var ErrSandboxBuilderDiscarded = errors.New("The SandboxBuilder was discarded while StartSandbox() was running")

ErrSandboxBuilderDiscarded is returned when a SandboxBuilder was discarded while StartSandbox() was in the process of starting the sandbox.

var ErrSandboxTerminated = errors.New("The Sandbox has terminated")

ErrSandboxTerminated is used to indicate that a SandBox has already terminated and can't be aborted.

var ErrShellAborted = errors.New("The shell was aborted")

ErrShellAborted is used to indicate that a Shell has been aborted.

var ErrShellTerminated = errors.New("The shell has already terminated")

ErrShellTerminated is used to indicate that a shell has already terminated

Functions

func Engines

func Engines() map[string]EngineProvider

Engines returns a map of registered EngineProviders.

func Register

func Register(name string, provider EngineProvider)

Register will register an EngineProvider, this is intended to be called from func init() {}, to register engines as an import side-effect.

If an engine with the given name is already registered this will panic.

Types

type Capabilities

type Capabilities struct {
	// Maximum number of parallel sandboxes, leave 0 if unbounded.
	MaxConcurrency int
}

The Capabilities structure defines the set of features supported by an engine.

Some plugins will use this for feature detection, most plugins will call the methods in question and handle the ErrFeatureNotSupported error. For this reason it's essential to also return ErrFeatureNotSupported from methods related to unsupported features (see docs of individual methods).

Plugin implementors are advised to call methods and handling unsupported features by handling ErrFeatureNotSupported errors. But in some cases it might be necessary to adjust behavior in case of unsupported methods, for this up-front feature checking using Capabilities is necessary.

To encourage the try and handle errors pattern, the Capabilities shall only list features for which we critically need up-front feature testing.

type Display

type Display struct {
	Name        string
	Description string
	Width       int // 0 if unknown
	Height      int // 0 if unknown
}

The Display struct holds information about a display that exists inside a running sandbox.

type Engine

type Engine interface {
	// Documentation returns a list of sections with end-user documentation.
	//
	// These sections will be combined with documentation sections from all
	// enabled plugins in-order to form end-user documentation.
	Documentation() []runtime.Section

	// PayloadSchema returns a JSON schema description of the payload options,
	// accepted by this engine.
	PayloadSchema() schematypes.Object

	// Capabilities returns a structure declaring which features are supported,
	// this is used for up-front feature checking. Unsupport methods must also
	// return ErrFeatureNotSupported when called.
	//
	// This property is strictly for plugins that need to do up-front feature
	// checking. Consumers are encouraged to just try them and handle errors
	// rather than testing for supported features up-front. Granted this is not
	// always possible, hence, the presence of this property.
	//
	// Implementors must return a constant that is always the same.
	Capabilities() Capabilities

	// NewSandboxBuilder returns a new instance of the SandboxBuilder interface.
	//
	// We'll create a SandboxBuilder for each task run. This is really a setup
	// step where the implementor may acquire resources referenced in the
	// SandboxOptions.
	//
	// Example: An engine implementation based on docker, may start downloading
	// the docker image in before returning from NewSandboxBuilder(). The
	// SandboxBuilder instance returned will then reference the docker image
	// downloading process, and be ready to start a new docker container once
	// StartSandbox() is called. Obviously blocking that call until docker image
	// download is completed.
	//
	// This operation should parse the engine-specific payload parts given in
	// SandboxOptions and return a MalformedPayloadError error if the payload
	// is invalid.
	//
	// Non-fatal errors: MalformedPayloadError, ErrMaxConcurrencyExceeded.
	NewSandboxBuilder(options SandboxOptions) (SandboxBuilder, error)

	// VolumeSchema returns a JSON schema description of the volume options,
	// accepted by this engine.
	VolumeSchema() schematypes.Schema

	// NewVolumeBuilder returns a VolumeBuilder for constructing a volume for this
	// engine, the options must match the VolumeSchema() defined by this engine.
	//
	// This method may return ErrFeatureNotSupported, if volumes are not supported,
	// or if the engine only supports building empty volumes using NewVolume().
	//
	// Non-fatal errors: ErrFeatureNotSupported
	NewVolumeBuilder(options interface{}) (VolumeBuilder, error)

	// NewVolume returns a new empty Volume, may return
	// ErrFeatureNotSupported, if not supported.
	//
	// Non-fatal errors: ErrFeatureNotSupported
	NewVolume(options interface{}) (Volume, error)

	// Dispose cleans up any resources held by the engine. The engine object
	// cannot be used after Dispose() has been called.
	//
	// This method need not be thread-safe! And may NOT be called before all
	// SandboxBuilders, Sandboxes and ResultSets have been disposed.
	//
	// This is mostly useful for cleanup after tests, as we won't switch between
	// engines in production.
	Dispose() error
}

An Engine implementation provides a backend upon which tasks can be executed.

We do not intend for a worker to use multiple engines at the same time, whilst it might be fun to try some day, implementors need not design with this use-case in mind. This means that you can safely assume that your engine is the only engine that is instantiated.

While we do not intend to use multiple engines at the same time, implementors must design engines to support running multiple sandboxes in parallel. If the engine can't run an unbounded number of sandboxes in parallel, it should return set MaxConcurrency to non-zero in its Capabilities(). Additionally, it must return ErrMaxConcurrencyExceeded if a sandbox is creation would violate it's declared MaxConcurrency. Obviously, when a sandbox is disposed it should be possible call NewSandboxBuilder() again.

Obviously not all engines are available on all platforms and not all features can be implemented on all platforms. See individual methods to see which are required and which can be implemented by returning ErrFeatureNotSupported.

type EngineBase

type EngineBase struct{}

EngineBase is a base implemenation of Engine. It will implement all optional methods such that they return ErrFeatureNotSupported.

Note: This will not implement NewSandboxBuilder() and other required methods.

Implementors of Engine should embed this struct to ensure source compatibility when we add more optional methods to Engine.

func (EngineBase) Capabilities

func (EngineBase) Capabilities() Capabilities

Capabilities returns an zero value Capabilities struct indicating that most features aren't supported.

func (EngineBase) Dispose

func (EngineBase) Dispose() error

Dispose trivially implements cleanup by doing nothing.

func (EngineBase) Documentation

func (EngineBase) Documentation() []runtime.Section

Documentation returns no documentation.

func (EngineBase) NewVolume

func (EngineBase) NewVolume(options interface{}) (Volume, error)

NewVolume returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (EngineBase) NewVolumeBuilder

func (EngineBase) NewVolumeBuilder(options interface{}) (VolumeBuilder, error)

NewVolumeBuilder returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (EngineBase) PayloadSchema

func (EngineBase) PayloadSchema() schematypes.Object

PayloadSchema returns an empty schematypes.Object indicating no contraints on keys of the payload object.

func (EngineBase) VolumeSchema

func (EngineBase) VolumeSchema() schematypes.Schema

VolumeSchema returns an empty schematypes.Object indicating no options for volume creation

type EngineOptions

type EngineOptions struct {
	Environment *runtime.Environment
	Monitor     runtime.Monitor
	Config      interface{}
}

EngineOptions is a wrapper for the set of options/arguments given to an EngineProvider when an Engine is created.

We pass all options as a single argument, so that we can add additional properties without breaking source compatibility.

type EngineProvider

type EngineProvider interface {
	NewEngine(options EngineOptions) (Engine, error)

	// ConfigSchema returns the schema for the engine configuration
	ConfigSchema() schematypes.Schema
}

EngineProvider is the interface engine implementors must implement and register with engines.RegisterEngine("EngineName", provider)

This function must return an Engine implementation, generally this will only be called once in an application. But implementors should aim to write reentrant code.

Any error here will be fatal and likely cause the worker to stop working. If an implementor can determine that the platform isn't supported at compile-time it is recommended to not register the implementation.

type EngineProviderBase

type EngineProviderBase struct{}

EngineProviderBase is a base struct that provides empty implementations of some methods for EngineProvider

Implementors of EngineProvider should embed this struct to ensure forward compatibility when we add new optional method to EngineProvider.

func (EngineProviderBase) ConfigSchema

func (EngineProviderBase) ConfigSchema() schematypes.Schema

ConfigSchema returns an empty object schema.

type FileHandler

type FileHandler func(path string, stream ioext.ReadSeekCloser) error

FileHandler is given as callback when iterating through a list of files.

ResultSet.ExtractFolder(path, handler) takes a FileHandler as the handler parameter. This function may be called sequentially or concurrently, but if it returns an error, the ResultSet should stop calling it and return ErrHandlerInterrupt from ResultSet.ExtractFolder.

The path argument is a relative path to the file, as in relative to the path given to ResultSet.ExtraFolder(path, handler). The path does not start with slash, but always uses slash as separator regardless of underlying OS.

The stream argument is a read/seek/closer for the file, this can be the actual file, or a copy of the file, or some seekable stream interface.

type ResultSet

type ResultSet interface {
	// Success returns true if the execution was successful, typically implying
	// that the process exited zero.
	Success() bool

	// Extract a file from the sandbox.
	//
	// Interpretation of the string path format is engine specific and must be
	// documented by the engine implementor. The engine may impose restrictions on
	// the string, if these restrictions are violated the engine should return a
	// MalformedPayloadError.
	//
	// If the file requested doesn't exist the engine should return
	// ErrResourceNotFound. Further more the engine may return
	// ErrFeatureNotSupported rather than implementing this method.
	//
	// Non-fatal erorrs: ErrFeatureNotSupported, ErrResourceNotFound,
	// MalformedPayloadError
	ExtractFile(path string) (ioext.ReadSeekCloser, error)

	// Extract all files under a folder (recursively) from the sandbox.
	//
	// Interpretation of the string path format is engine specific and must be
	// documented by the engine implementor. The engine may impose restrictions on
	// the string, if these restrictions are violated the engine should return a
	// MalformedPayloadError.
	//
	// If the folder requested doesn't exist the engine should return
	// ErrResourceNotFound. Further more the engine may return
	// ErrFeatureNotSupported rather than implementing this method.
	//
	// For each file found under the given path the handler(path, stream) is
	// called. Implementor may call this function sequentially or in parallel.
	// If a handler(path, stream) call returns an error then ErrHandlerInterrupt
	// should be passed as return value from the ExtractFolder call.
	//
	// If an error occurs during iteration, iteration is halted, and when all
	// calls to handler(path, stream) have returned, ExtractFolder should return
	// with ErrHandlerInterrupt.
	//
	// The only non-fatal error is ErrNonFatalInternalError, indicating that
	// something went wrong while streaming out artfacts and all artifacts may not
	// have been extracted, or they may not have been streamed out completely.
	//
	// The ErrNonFatalInternalError may only be returned if the engine expected
	// further request to be successful. And attempts to call other methods or
	// extract other paths might work out fine.
	//
	// Non-fatal erorrs: ErrFeatureNotSupported, ErrResourceNotFound,
	// MalformedPayloadError, ErrNonFatalInternalError, ErrHandlerInterrupt
	ExtractFolder(path string, handler FileHandler) error

	// ArchiveSandbox streams out the entire sandbox (or as much as possible)
	// as a tar-stream. Ideally this also includes cache folders.
	ArchiveSandbox() (ioext.ReadSeekCloser, error)

	// Dispose shall release all resources.
	//
	// CacheFolders given to the sandbox shall not be disposed, instead they are
	// just no longer owned by the engine.
	//
	// Implementors should only return an error if cleaning up fails and the
	// worker therefor needs to stop operation.
	Dispose() error
}

The ResultSet interface represents the results of a sandbox that has finished execution, but is hanging around while results are being extracted.

When returned from Sandbox this takes ownership of all resources. If the engine uses docker then the ResultSet would have ownership of cache folders as well as the terminated docker container.

All methods on this interface must be thread-safe.

type ResultSetBase

type ResultSetBase struct{}

ResultSetBase is a base implemenation of ResultSet. It will implement all optional methods such that they return ErrFeatureNotSupported.

Note: This will not implement Success() and other required methods.

Implementors of ResultSet should embed this struct to ensure source compatibility when we add more optional methods to ResultSet.

func (ResultSetBase) ArchiveSandbox

func (ResultSetBase) ArchiveSandbox() (ioext.ReadSeekCloser, error)

ArchiveSandbox returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (ResultSetBase) Dispose

func (ResultSetBase) Dispose() error

Dispose returns nil indicating that resources have been released.

func (ResultSetBase) ExtractFile

func (ResultSetBase) ExtractFile(string) (ioext.ReadSeekCloser, error)

ExtractFile returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (ResultSetBase) ExtractFolder

func (ResultSetBase) ExtractFolder(string, FileHandler) error

ExtractFolder returns ErrFeatureNotSupported indicating that the feature isn't supported.

type Sandbox

type Sandbox interface {
	// Wait for task execution and termination of all associated shells, and
	// return immediately if sandbox execution has finished.
	//
	// When this method returns, all resources held by the Sandbox instance must
	// have been released or transferred to the ResultSet instance returned. If an
	// internal error occurred, resources may be freed and WaitForResult() may
	// return ErrNonFatalInternalError if the error didn't leak resources and we
	// don't expect the error to be persistent.
	//
	// When this method has returned, any calls to Abort() or NewShell() should
	// return ErrSandboxTerminated. If Abort() is called before WaitForResult()
	// returns, WaitForResult() should return ErrSandboxAborted and release all
	// resources held.
	//
	// Notice that this method may be invoked more than once. In all cases it
	// should return the same value when it decides to return. In particular, it
	// must keep a reference to the ResultSet instance created and return the same
	// instance, so that any resources held aren't transferred to multiple
	// different ResultSet instances.
	//
	// Non-fatal errors: ErrNonFatalInternalError, ErrSandboxAborted.
	WaitForResult() (ResultSet, error)

	// NewShell creates a new Shell for interaction with the sandbox. The shell
	// and arguments to be launched can be specified with command, if no command
	// arguments are given the sandbox should create a shell of the platforms
	// default type.
	//
	// If the engine doesn't support interactive shells it may return
	// ErrFeatureNotSupported. This should not interrupt/abort the execution of
	// the task which should proceed as normal.
	//
	// If given command can't be started a MalformedPayloadError may be returned
	// indicating why the specified command doesn't work.
	//
	// If the WaitForResult() method has returned and the sandbox isn't running
	// anymore this method must return ErrSandboxTerminated, signaling that you
	// can't interact with the sandbox anymore.
	//
	// Non-fatal errors: ErrFeatureNotSupported, ErrSandboxTerminated,
	// ErrSandboxAborted, MalformedPayloadError.
	NewShell(command []string, tty bool) (Shell, error)

	// ListDisplays returns a list of Display objects that describes displays
	// that exists inside the Sandbox while it's running.
	//
	// Non-fatal errors: ErrFeatureNotSupported, ErrSandboxTerminated.
	ListDisplays() ([]Display, error)

	// OpenDisplay returns an active VNC connection to a display with the given
	// name inside the running Sandbox.
	//
	// If no such display exist within the sandbox this method should return:
	// ErrNoSuchDisplay.
	//
	// Non-fatal errors: ErrFeatureNotSupported, ErrNoSuchDisplay,
	// ErrSandboxTerminated, ErrSandboxAborted.
	OpenDisplay(name string) (io.ReadWriteCloser, error)

	// Abort the sandbox. This means killing the task execution as well as all
	// associated shells and releasing all resources held.
	//
	// If called before the sandbox execution finished, then WaitForResult() must
	// return ErrSandboxAborted. If sandbox execution has finished when Abort() is
	// called, Abort() should return ErrSandboxTerminated and not release any
	// resources as they should have been released by WaitForResult() or
	// transferred to the ResultSet instance returned.
	//
	// Non-fatal errors: ErrSandboxTerminated
	Abort() error

	// Kill all processes running in the sandbox, aborting shells and closing all
	// displays. This should cause WaitForResult() to return a ResultSet with
	// ResultSet.Success() returning false.
	//
	// Non-fatal errors: ErrSandboxTerminated, ErrSandboxAborted,
	// ErrFeatureNotSupported
	Kill() error
}

The Sandbox interface represents an active sandbox.

All methods on this interface must be thread-safe.

type SandboxBase

type SandboxBase struct{}

SandboxBase is a base implemenation of Sandbox. It will implement all optional methods such that they return ErrFeatureNotSupported.

Note: This will not implement WaitForResult() and other required methods.

Implementors of SandBox should embed this struct to ensure source compatibility when we add more optional methods to SandBox.

func (SandboxBase) Abort

func (SandboxBase) Abort() error

Abort returns nil indicating that resources have been released.

func (SandboxBase) Kill

func (SandboxBase) Kill() error

Kill returns ErrFeatureNotSupported

func (SandboxBase) ListDisplays

func (SandboxBase) ListDisplays() ([]Display, error)

ListDisplays returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (SandboxBase) NewShell

func (SandboxBase) NewShell(command []string, tty bool) (Shell, error)

NewShell returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (SandboxBase) OpenDisplay

func (SandboxBase) OpenDisplay(string) (io.ReadWriteCloser, error)

OpenDisplay returns ErrFeatureNotSupported indicating that the feature isn't supported.

type SandboxBuilder

type SandboxBuilder interface {
	// Attach a volume at given mountpoint.
	//
	// The volume given must have been created by this engine, using a method like
	// engine.NewVolume(). Implementors are free to make such a type assertion.
	//
	// The mountpoint is a string in engine-specific format. If the given
	// mountpoint violates the engine-specific format, a MalformedPayloadError
	// should be returned. For example a docker engine may expect the mountpoint
	// to be a path, where as a different engine might expect it to be a folder
	// name, or the name of an environement variable pointing to the folder.
	//
	// If the mountpoint is invalid because it's already in use a
	// MalformedPayloadError is also appropriate.
	//
	// If the engine doesn't support mutable or immutable volume attachments, it
	// should return ErrMutableMountNotSupported or ErrImmutableMountNotSupported,
	// respectively.
	//
	// Non-fatal errors: MalformedPayloadError, ErrMutableMountNotSupported,
	// ErrImmutableMountNotSupported, ErrFeatureNotSupported, ErrNamingConflict
	AttachVolume(mountpoint string, volume Volume, readOnly bool) error

	// Attach a proxy to the sandbox.
	//
	// The hostname is a engine-specific format. If the given hostname violates
	// engine-specific format, a MalformedPayloadError should be returned.
	// For example a docker engine may expect the hostname to be an actual
	// hostname, where as a different engine could have it being the path of a
	// unix-domain socket, or the prefix of a URL path.
	//
	// To ensure that all plugins works with all engines, AttachProxy should
	// always allow hostnames matching /[a-z]{3,22}/.
	//
	// It is the engines responsbility to ensure that requests aimed at the given
	// name is forwarded to the handler. And to ensure that no other processes are
	// able to forward requests to the handler.
	// When forarding the hostname should be set to what was given on attachment,
	// the any path prefixes should also be removed.
	//
	// If the engine doesn't support proxy attachments, it should return
	// ErrFeatureNotSupported.
	//
	// Non-fatal errors: MalformedPayloadError, ErrFeatureNotSupported,
	// ErrNamingConflict
	AttachProxy(hostname string, handler http.Handler) error

	// Set an environement variable.
	//
	// If the format of the environment variable name is invalid this method
	// should return a MalformedPayloadError with explaining why the name is
	// invalid.
	//
	// If the environment variable have previously been declared, this method
	// must return ErrNamingConflict.
	//
	// Non-fatal errors: ErrFeatureNotSupported, MalformedPayloadError,
	// ErrNamingConflict
	SetEnvironmentVariable(name string, value string) error

	// Start execution of task in sandbox. After a call to this method resources
	// held by the SandboxBuilder instance should be released or transferred to
	// the Sandbox implementation.
	//
	// Non-fatal errors: MalformedPayloadError, ErrSandboxBuilderDiscarded
	StartSandbox() (Sandbox, error)

	// Discard must free all resources held by the SandboxBuilder interface.
	// Any error returned is fatal, so do not return an error unless there is
	// something very wrong.
	Discard() error
}

The SandboxBuilder interface wraps the state required to start a Sandbox.

Before returning a SandboxBuilder engine implementors should start downloading and setting up all the resources needed to start execution. A docker based engine may wish to ensure the docker image is downloaded, or lay a claim on it so the GarbageCollector won't remove it. A naive Windows engine may wish to create a new user account and setup a folder for the sandbox.

Implementors can be sure that any instance of this interface will only be used to create a single Sandbox, that is StartSandbox() will atmost be called once. If StartSandbox() is called twice a sane implementor should return ErrContractViolation, and feel free to exhibit undefined behavior.

All methods of this interface must be thread-safe.

type SandboxBuilderBase

type SandboxBuilderBase struct{}

SandboxBuilderBase is a base implemenation of SandboxBuilder. It will implement all optional methods such that they return ErrFeatureNotSupported.

Note: This will not implement StartSandbox() and other required methods.

Implementors of SandBoxBuilder should embed this struct to ensure source compatibility when we add more optional methods to SandBoxBuilder.

func (SandboxBuilderBase) AttachProxy

func (SandboxBuilderBase) AttachProxy(string, http.Handler) error

AttachProxy returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (SandboxBuilderBase) AttachVolume

func (SandboxBuilderBase) AttachVolume(string, Volume, bool) error

AttachVolume returns ErrFeatureNotSupported indicating that the feature isn't supported.

func (SandboxBuilderBase) Discard

func (SandboxBuilderBase) Discard() error

Discard returns nil, indicating that resources have been released.

func (SandboxBuilderBase) SetEnvironmentVariable

func (SandboxBuilderBase) SetEnvironmentVariable(string, string) error

SetEnvironmentVariable return ErrFeatureNotSupported indicating that the feature isn't supported.

type SandboxOptions

type SandboxOptions struct {
	// TaskContext contains information about the task we're starting a sandbox
	// for.
	TaskContext *runtime.TaskContext
	// Payload is the subset of keys from the payload that was declared in
	// PayloadSchema(). Implementors can safely assume that it validates against
	// this schema.
	Payload map[string]interface{}
	// Monitor object tagged with task identifiers for logging and error reporting
	Monitor runtime.Monitor
}

The SandboxOptions structure is a wrapper around the options/arguments for creating a NewSandboxBuilder. This allows us to add new arguments without breaking source compatibility with older Engine implementations.

type Shell

type Shell interface {
	StdinPipe() io.WriteCloser
	StdoutPipe() io.ReadCloser
	StderrPipe() io.ReadCloser
	// SetSize will set the TTY size, returns ErrFeatureNotSupported, if the
	// shell wasn't launched as a TTY, or platform doesn't support size options.
	//
	// non-fatal errors: ErrShellTerminated, ErrShellAborted,
	// ErrFeatureNotSupported
	SetSize(columns, rows uint16) error
	// Aborts a shell, causing Wait() to return ErrShellAborted. If the shell has
	// already terminated Abort() returns ErrShellTerminated.
	//
	// non-fatal errors: ErrShellTerminated
	Abort() error
	// Wait will return when the shell has terminated. It returns true/false
	// depending on the exit code. Any error indicates that the shell didn't
	// run in a controlled maner. If Abort() was called Wait() shall return
	// ErrShellAborted.
	//
	// non-fatal errors: ErrShellAborted
	Wait() (bool, error)
}

The Shell interface opens an interactive sh or bash shell inside the Sandbox.

type Volume

type Volume interface {
	// Dispose deletes all resources used by the Volume.
	Dispose() error
}

Volume that we can modify and mount on a Sandbox.

Note, that engine implementations are not responsible for tracking the Volume, deletion and/or if it's mounted on more than one Sandbox at the same time.

The engine is responsible for creating it, mounting it in sandboxes, loading data through the defined interface, extracting data through the defined interface and deleting the underlying storage when Dispose is called.

type VolumeBase

type VolumeBase struct{}

VolumeBase is a base implemenation of Volume. It will implement all optional methods such that they return ErrFeatureNotSupported.

Implementors of Volume should embed this struct to ensure source compatibility when we add more optional methods to Volume.

func (VolumeBase) Dispose

func (VolumeBase) Dispose() error

Dispose returns nil indicating that resources were released.

type VolumeBuilder

type VolumeBuilder interface {
	// Write a folder to the volume being built.
	//
	// Name must be a slash separated path, there is no requirement that
	// intermediate folders have been created.
	WriteFolder(name string) error

	// Write a file to the volume being built.
	//
	// Name must be a slash separated path, there is no requirement that
	// intermediate folders have been created.
	WriteFile(name string) io.WriteCloser

	// Build a volume from the information passed in.
	//
	// This invalidates the VolumeBuilder, which cannot be reused.
	BuildVolume() (Volume, error)

	// Discard resources held by the VolumeBuilder
	//
	// This invalidates the VolumeBuilder, which cannot be reused.
	Discard() error
}

The VolumeBuilder interface wraps the process of building a volume. Notably, it permits writing of files and folders into the volume before it is created.

Once a BuildVolume() or Discard() have been called the VolumeBuilder object is invalid and resources held by it should be considered transferred or released.

type VolumeBuilderBase

type VolumeBuilderBase struct{}

VolumeBuilderBase is a base implemenation of VolumeBuilder. It will implement all optional methods such that they return ErrFeatureNotSupported.

Implementors of VolumeBuilder should embed this struct to ensure source compatibility when we add more optional methods to VolumeBuilder.

func (VolumeBuilderBase) Discard

func (VolumeBuilderBase) Discard() error

Discard returns nil, indicating that resources was released