engines

package
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 14, 2016 License: MPL-2.0 Imports: 9 Imported by: 1

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

Constants

This section is empty.

Variables

View Source 
var ErrContractViolation = errors.New("Engine has detected a contract violation")

ErrContractViolation is returned when a contract with the engine has been violated.

View Source 
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.

View Source 
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".

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

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

View Source 
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.

View Source 
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.

View Source 
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.

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

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

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

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

View Source 
var ErrNonFatalInternalError = errors.New("Engine encountered a non-fatal internal error")

ErrNonFatalInternalError is used to indicate that the operation failed because of internal error that isn't expected to affect other tasks.

View Source 
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.

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

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

View Source 
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.

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

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

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

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

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

ErrShellTerminated is used to indicate that a shell has already terminated

Functions

func Engines added in v0.0.2 

func Engines() map[string]EngineProvider

Engines returns a map of registered EngineProviders.

func Register added in v0.0.2 

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 added in v0.0.2 

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 {
	// 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)

	// NewCacheFolder returns a new Volume backed by a file system folder
	// if cache-folders folders are supported, otherwise it must return
	// ErrFeatureNotSupported.
	//
	// Non-fatal errors: ErrFeatureNotSupported
	NewCacheFolder() (Volume, error)

	// NewMemoryDisk returns a new Volume backed by a ramdisk, if ramdisks are
	// supported, otherwise it must return ErrFeatureNotSupported.
	//
	// Non-fatal errors: ErrFeatureNotSupported
	NewMemoryDisk() (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 added in v0.0.2 

func (EngineBase) Dispose() error

Dispose trivially implements cleanup by doing nothing.

func (EngineBase) NewCacheFolder 

func (EngineBase) NewCacheFolder() (Volume, error)

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

func (EngineBase) NewMemoryDisk 

func (EngineBase) NewMemoryDisk() (Volume, error)

NewMemoryDisk 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.

type EngineOptions added in v0.0.2 

type EngineOptions struct {
	Environment *runtime.Environment
	Log         *logrus.Entry
	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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 the ResultSet should stop calling it and pass the error through as return value 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 InternalError added in v0.0.2 

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

InternalError are errors that could not be completed because of issues related to the host. These issues could include issues with the engine, host resources, and worker configuration.

func NewInternalError added in v0.0.2 

func NewInternalError(message string) InternalError

NewInternalError creates an InternalError object, please make sure to include a detailed description of the error, preferably using multiple lines and with examples.

These will be printed in the logs and end-users will rely on them to debug their tasks.

func (InternalError) Error added in v0.0.2 

func (e InternalError) Error() string

Error returns the error message and adheres to the Error interface

type MalformedPayloadError 

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

The MalformedPayloadError error type is used to indicate that some operation failed because of malformed-payload. For example a string expected to be path contained invalid characters, a required property was missing, or an integer was outside the permitted range.

func MergeMalformedPayload added in v0.0.2 

func MergeMalformedPayload(errors ...MalformedPayloadError) MalformedPayloadError

MergeMalformedPayload merges a list of MalformedPayloadError objects

func NewMalformedPayloadError 

func NewMalformedPayloadError(a ...interface{}) MalformedPayloadError

NewMalformedPayloadError creates a MalformedPayloadError object, please make sure to include a detailed description of the error, preferably using multiple lines and with examples.

These will be printed in the logs and end-users will rely on them to debug their tasks.

func (MalformedPayloadError) Error 

func (e MalformedPayloadError) Error() string

Error returns the error message and adheres to the Error 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 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.
	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
}

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) ListDisplays added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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{}
}

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.

Source Files

View all Source files

Directories

Path Synopsis
Package enginetest provides utilities for testing generic engine implementations.
 Package enginetest provides utilities for testing generic engine implementations.
Package mockengine implements a MockEngine that doesn't really do anything, but allows us to test plugins without having to run a real engine.
 Package mockengine implements a MockEngine that doesn't really do anything, but allows us to test plugins without having to run a real engine.
mocknet
Package mocknet implements a net.Listener interface that can reached with mocknet.Dial() and establishes connections using net.Pipe() This is useful for testing things that needs net.Listener and net.Conn instances without creating a TCP listener on localhost.
 Package mocknet implements a net.Listener interface that can reached with mocknet.Dial() and establishes connections using net.Pipe() This is useful for testing things that needs net.Listener and net.Conn instances without creating a TCP listener on localhost.
Package osxnative implements the Mac OSX engine
 Package osxnative implements the Mac OSX engine
Package qemuengine implements a QEMU based engine for taskcluster-worker.
 Package qemuengine implements a QEMU based engine for taskcluster-worker.
image
Package image exposes methods and abstractions for extracting and managing virtual machine images.
 Package image exposes methods and abstractions for extracting and managing virtual machine images.
metaservice
Package metaservice implements the meta-data service that the guests use to talk to the host.
 Package metaservice implements the meta-data service that the guests use to talk to the host.
network
Package network contains scripts and abstractions for setting up TAP-device based networks for a set of QEMU virtual machines.
 Package network contains scripts and abstractions for setting up TAP-device based networks for a set of QEMU virtual machines.
vm
Package vm provides virtual machine abstractions for QEMU.
 Package vm provides virtual machine abstractions for QEMU.
Package scriptengine provides an engine that can be configured with a script and a JSON schema, such that the worker executes declarative tasks.
 Package scriptengine provides an engine that can be configured with a script and a JSON schema, such that the worker executes declarative tasks.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.