exec

package
v0.0.0-...-2c9ee18 Latest Latest
Warning

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

Go to latest
Published: Feb 15, 2017 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrInterrupted = errors.New("interrupted")

ErrInterrupted is returned by steps when they exited as a result of receiving a signal.

Functions

This section is empty.

Types

type Aggregate

type Aggregate []StepFactory

Aggregate constructs a Step that will run each step in parallel.

func (Aggregate) Using

func (a Aggregate) Using(prev Step, repo *worker.ArtifactRepository) Step

Using delegates to each StepFactory and returns an AggregateStep.

type AggregateStep

type AggregateStep []Step

AggregateStep is a step of steps to run in parallel.

func (AggregateStep) Result

func (step AggregateStep) Result(x interface{}) bool

Result indicates Success as true if all of the steps indicate Success as true, or if there were no steps at all. If none of the steps can indicate Success, it will return false and not indicate success itself.

All other result types are ignored, and Result will return false.

func (AggregateStep) Run

func (step AggregateStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run executes all steps in parallel. It will indicate that it's ready when all of its steps are ready, and propagate any signal received to all running steps.

It will wait for all steps to exit, even if one step fails or errors. After all steps finish, their errors (if any) will be aggregated and returned as a single error.

type DependentGetStep

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

DependentGetStep represents a Get step whose version is determined by the previous step. It is used to fetch the resource version produced by a PutStep.

func (DependentGetStep) Using

func (step DependentGetStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs a GetStep that will fetch the version of the resource determined by the VersionInfo result of the previous step.

type DeprecationConfigSource

type DeprecationConfigSource struct {
	Delegate TaskConfigSource
	Stderr   io.Writer
}

DeprecationConfigSource represents a statically configured TaskConfig.

func (DeprecationConfigSource) FetchConfig

func (configSource DeprecationConfigSource) FetchConfig(repo *worker.ArtifactRepository) (atc.TaskConfig, error)

FetchConfig returns the configuration. It cannot fail.

func (DeprecationConfigSource) Warnings

func (configSource DeprecationConfigSource) Warnings() []string

type EnsureStep

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

EnsureStep will run one step, and then a second step regardless of whether the first step fails or errors.

func Ensure

func Ensure(firstStep StepFactory, secondStep StepFactory) EnsureStep

Ensure constructs an EnsureStep factory.

func (*EnsureStep) Result

func (o *EnsureStep) Result(x interface{}) bool

Result indicates Success by and-ing together both step's Success results. If either of them cannot indicate Success, it returns false.

All other result types are ignored.

func (*EnsureStep) Run

func (o *EnsureStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run will call Run on the first step, wait for it to complete, and then call Run on the second step, regardless of whether the first step failed or errored.

If the first step or the second step errors, an aggregate of their errors is returned.

func (EnsureStep) Using

func (o EnsureStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs an *EnsureStep.

type ExitStatus

type ExitStatus int

ExitStatus is the resulting exit code from the process that the step ran. Typically if the ExitStatus result is 0, the Success result is true.

type Factory

type Factory interface {
	// Get constructs a GetStep factory.
	Get(
		lager.Logger,
		StepMetadata,
		worker.ArtifactName,
		worker.Identifier,
		worker.Metadata,
		GetDelegate,
		atc.ResourceConfig,
		atc.Tags,
		int,
		atc.Params,
		atc.Version,
		atc.ResourceTypes,
	) StepFactory

	// Put constructs a PutStep factory.
	Put(
		lager.Logger,
		StepMetadata,
		worker.Identifier,
		worker.Metadata,
		PutDelegate,
		atc.ResourceConfig,
		atc.Tags,
		int,
		atc.Params,
		atc.ResourceTypes,
	) StepFactory

	// DependentGet constructs a GetStep factory whose version is determined by
	// the previous step.
	DependentGet(
		lager.Logger,
		StepMetadata,
		worker.ArtifactName,
		worker.Identifier,
		worker.Metadata,
		GetDelegate,
		atc.ResourceConfig,
		atc.Tags,
		int,
		atc.Params,
		atc.ResourceTypes,
	) StepFactory

	// Task constructs a TaskStep factory.
	Task(
		lager.Logger,
		worker.ArtifactName,
		worker.Identifier,
		worker.Metadata,
		TaskDelegate,
		Privileged,
		atc.Tags,
		int,
		TaskConfigSource,
		atc.ResourceTypes,
		map[string]string,
		map[string]string,
		string,
		clock.Clock,
	) StepFactory
}

Factory is used when building up the steps for a build.

func NewGardenFactory

func NewGardenFactory(
	workerClient worker.Client,
	resourceFetcher resource.Fetcher,
	resourceFactory resource.ResourceFactory,
	dbResourceCacheFactory dbng.ResourceCacheFactory,
) Factory

type FileConfigSource

type FileConfigSource struct {
	Path string
}

FileConfigSource represents a dynamically configured TaskConfig, which will be fetched from a specified file in the worker.ArtifactRepository.

func (FileConfigSource) FetchConfig

func (configSource FileConfigSource) FetchConfig(repo *worker.ArtifactRepository) (atc.TaskConfig, error)

FetchConfig reads the specified file from the worker.ArtifactRepository and loads the TaskConfig contained therein (expecting it to be YAML format).

The path must be in the format SOURCE_NAME/FILE/PATH.yml. The SOURCE_NAME will be used to determine the ArtifactSource in the worker.ArtifactRepository to stream the file out of.

If the source name is missing (i.e. if the path is just "foo.yml"), UnspecifiedArtifactSourceError is returned.

If the specified source name cannot be found, UnknownArtifactSourceError is returned.

If the task config file is not found, or is invalid YAML, or is an invalid task configuration, the respective errors will be bubbled up.

func (FileConfigSource) Warnings

func (configSource FileConfigSource) Warnings() []string

type FileNotFoundError

type FileNotFoundError struct {
	Path string
}

FileNotFoundError is the error to return from StreamFile when the given path does not exist.

func (FileNotFoundError) Error

func (err FileNotFoundError) Error() string

Error prints a helpful message including the file path. The user will see this message if e.g. their task config path does not exist.

type GetDelegate

type GetDelegate interface {
	ResourceDelegate
}

GetDelegate is used to record events related to a GetStep's runtime behavior.

type GetStep

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

GetStep will fetch a version of a resource on a worker that supports the resource type.

func (*GetStep) Result

func (step *GetStep) Result(x interface{}) bool

Result indicates Success as true if the script completed successfully (or didn't have to run) and everything else worked fine.

It also indicates VersionInfo with the fetched or cached resource's version and metadata.

All other types are ignored.

func (*GetStep) Run

func (step *GetStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run ultimately registers the configured resource version's ArtifactSource under the configured SourceName. How it actually does this is determined by a few factors.

First, a worker that supports the given resource type is chosen, and a container is created on the worker.

If the worker has a VolumeManager, and its cache is already warmed, the cache will be mounted into the container, and no fetching will be performed. The container will be used to stream the contents of the cache to later steps that require the artifact but are running on a worker that does not have the cache.

If the worker does not have a VolumeManager, or if the worker does have a VolumeManager but a cache for the version of the resource is not present, the specified version of the resource will be fetched. As long as running the fetch script works, Run will return nil regardless of its exit status.

If the worker has a VolumeManager but did not have the cache initially, the fetched ArtifactSource is initialized, thus warming the worker's cache.

At the end, the resulting ArtifactSource (either from using the cache or fetching the resource) is registered under the step's SourceName.

func (*GetStep) StreamFile

func (step *GetStep) StreamFile(path string) (io.ReadCloser, error)

StreamFile streams a single file out of the resource.

func (*GetStep) StreamTo

func (step *GetStep) StreamTo(destination worker.ArtifactDestination) error

StreamTo streams the resource's data to the destination.

func (GetStep) Using

func (step GetStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using finishes construction of the GetStep and returns a *GetStep. If the *GetStep errors, its error is reported to the delegate.

func (*GetStep) VolumeOn

func (step *GetStep) VolumeOn(worker worker.Worker) (worker.Volume, bool, error)

VolumeOn locates the cache for the GetStep's resource and version on the given worker.

type Identity

type Identity struct{}

Identity constructs a step that just propagates the previous step to the next one, without running anything.

func (Identity) Using

func (Identity) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs an IdentityStep.

type IdentityStep

type IdentityStep struct {
	Step
}

IdentityStep does nothing, and delegates everything else to its nested step.

func (IdentityStep) Run

func (IdentityStep) Run(<-chan os.Signal, chan<- struct{}) error

Run does nothing.

type MergedConfigSource

type MergedConfigSource struct {
	A TaskConfigSource
	B TaskConfigSource
}

MergedConfigSource is used to join two config sources together.

func (MergedConfigSource) FetchConfig

func (configSource MergedConfigSource) FetchConfig(source *worker.ArtifactRepository) (atc.TaskConfig, error)

FetchConfig fetches both config sources, and merges the second config source into the first. This allows the user to set params required by a task loaded from a file by providing them in static configuration.

func (MergedConfigSource) Warnings

func (configSource MergedConfigSource) Warnings() []string

type MissingInputsError

type MissingInputsError struct {
	Inputs []string
}

MissingInputsError is returned when any of the task's required inputs are missing.

func (MissingInputsError) Error

func (err MissingInputsError) Error() string

Error prints a human-friendly message listing the inputs that were missing.

type MissingTaskImageSourceError

type MissingTaskImageSourceError struct {
	SourceName string
}

func (MissingTaskImageSourceError) Error

func (err MissingTaskImageSourceError) Error() string

type NoopStep

type NoopStep struct{}

NoopStep implements a step that successfully does nothing.

func (NoopStep) Result

func (NoopStep) Result(interface{}) bool

Result returns false. Arguably it should at least be able to indicate Success (as true), though it currently does not.

func (NoopStep) Run

func (NoopStep) Run(<-chan os.Signal, chan<- struct{}) error

Run returns nil immediately without doing anything. It does not bother indicating that it's ready or listening for signals.

type OnFailureStep

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

OnFailureStep will run one step, and then a second step if the first step fails (but not errors).

func OnFailure

func OnFailure(firstStep StepFactory, secondStep StepFactory) OnFailureStep

OnFailure constructs an OnFailureStep factory.

func (*OnFailureStep) Result

func (o *OnFailureStep) Result(x interface{}) bool

Result indicates Success as true if the first step completed successfully.

Any other type is ignored.

func (*OnFailureStep) Run

func (o *OnFailureStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run will call Run on the first step and wait for it to complete. If the first step errors, Run returns the error. OnFailureStep is ready as soon as the first step is ready.

If the first step fails (that is, its Success result is false), the second step is executed. If the second step errors, its error is returned.

func (OnFailureStep) Using

func (o OnFailureStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs an *OnFailureStep.

type OnSuccessStep

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

OnSuccessStep will run one step, and then a second step if the first step succeeds.

func OnSuccess

func OnSuccess(firstStep StepFactory, secondStep StepFactory) OnSuccessStep

OnSuccess constructs an OnSuccessStep factory.

func (*OnSuccessStep) Result

func (o *OnSuccessStep) Result(x interface{}) bool

Result indicates Success as true if the first step completed and the second step completed successfully.

Any other type is ignored.

func (*OnSuccessStep) Run

func (o *OnSuccessStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run will call Run on the first step and wait for it to complete. If the first step errors, Run returns the error. OnSuccessStep is ready as soon as the first step is ready.

If the first step succeeds (that is, its Success result is true), the second step is executed. If the second step errors, its error is returned.

func (OnSuccessStep) Using

func (o OnSuccessStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs an *OnSuccessStep.

type Privileged

type Privileged bool

Privileged is used to indicate whether the given step should run with special privileges (i.e. as an administrator user).

type PutDelegate

type PutDelegate interface {
	ResourceDelegate
}

PutDelegate is used to record events related to a PutStep's runtime behavior.

type PutStep

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

PutStep produces a resource version using preconfigured params and any data available in the worker.ArtifactRepository.

func (*PutStep) Result

func (step *PutStep) Result(x interface{}) bool

Result indicates Success as true if the script completed with exit status 0.

It also indicates VersionInfo returned by the script.

Any other type is ignored.

func (*PutStep) Run

func (step *PutStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run chooses a worker that supports the step's resource type and creates a container.

All worker.ArtifactSources present in the worker.ArtifactRepository are then brought into the container, using volumes if possible, and streaming content over if not.

The resource's put script is then invoked. The PutStep is ready as soon as the resource's script starts, and signals will be forwarded to the script.

func (PutStep) Using

func (step PutStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using finishes construction of the PutStep and returns a *PutStep. If the *PutStep errors, its error is reported to the delegate.

type ResourceDelegate

type ResourceDelegate interface {
	Initializing()

	Completed(ExitStatus, *VersionInfo)
	Failed(error)

	ImageVersionDetermined(worker.ResourceCacheIdentifier) error

	Stdout() io.Writer
	Stderr() io.Writer
}

ResourceDelegate is used to record events related to a resource's runtime behavior.

type Retry

type Retry []StepFactory

Retry constructs a Step that will run the steps in order until one of them succeeds.

func (Retry) Using

func (stepFactory Retry) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs a *RetryStep.

type RetryStep

type RetryStep struct {
	Attempts    []Step
	LastAttempt Step
}

RetryStep is a step that will run the steps in order until one of them succeeds.

func (*RetryStep) Result

func (step *RetryStep) Result(x interface{}) bool

Result delegates to the last step that it ran.

func (*RetryStep) Run

func (step *RetryStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run iterates through each step, stopping once a step succeeds. If all steps fail, the RetryStep will fail.

type StaticConfigSource

type StaticConfigSource struct {
	Plan atc.TaskPlan
}

StaticConfigSource represents a statically configured TaskConfig.

func (StaticConfigSource) FetchConfig

func (configSource StaticConfigSource) FetchConfig(*worker.ArtifactRepository) (atc.TaskConfig, error)

FetchConfig returns the configuration.

func (StaticConfigSource) Warnings

func (configSource StaticConfigSource) Warnings() []string

type Step

type Step interface {
	// Run is called when it's time to execute the step. It should indicate when
	// it's ready, and listen for signals at points where the potential time is
	// unbounded (i.e. running a task or a resource action).
	//
	// Steps wrapping other steps should be careful to propagate signals and
	// indicate that they're ready as soon as their wrapped steps are ready.
	//
	// Steps should return ErrInterrupted if they received a signal that caused
	// them to stop.
	//
	// Steps must be idempotent. Each step is responsible for handling its own
	// idempotency; usually this is done by saving off "checkpoints" in some way
	// that can be checked again if the step starts running again from the start.
	// For example, by having the ID for a container be deterministic and unique
	// for each step, and checking for properties on the container to determine
	// how far the step got.
	ifrit.Runner

	// Result is used to collect metadata from the step. Usually this is
	// `Success`, but some steps support more types (e.g. `VersionInfo`).
	//
	// Result returns a bool indicating whether it was able to populate the
	// destination. If the destination's type is unknown to the step, it must
	// return false.
	//
	// Implementers of this method MUST not mutate the given pointer if they
	// are unable to respond (i.e. returning false from this function).
	Result(interface{}) bool
}

A Step is an object that can be executed, whose result (e.g. Success) can be collected, and whose dependent resources (e.g. Containers, Volumes) can be released, allowing them to expire.

type StepFactory

type StepFactory interface {
	Using(Step, *worker.ArtifactRepository) Step
}

StepFactory constructs a step. The previous step and source repository are provided.

Some steps, i.e. DependentGetStep, use information from the previous step to determine how to run.

type StepMetadata

type StepMetadata interface {
	Env() []string
}

StepMetadata is used to inject metadata to make available to the step when it's running.

type Success

type Success bool

Success indicates whether a step completed successfully.

type TaskConfigSource

type TaskConfigSource interface {
	// FetchConfig returns the TaskConfig, and may have to a task config file out
	// of the worker.ArtifactRepository.
	FetchConfig(*worker.ArtifactRepository) (atc.TaskConfig, error)
	Warnings() []string
}

TaskConfigSource is used to determine a Task step's TaskConfig.

type TaskDelegate

type TaskDelegate interface {
	Initializing(atc.TaskConfig)
	Started()

	Finished(ExitStatus)
	Failed(error)

	ImageVersionDetermined(worker.ResourceCacheIdentifier) error

	Stdout() io.Writer
	Stderr() io.Writer
}

TaskDelegate is used to record events related to a TaskStep's runtime behavior.

type TaskStep

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

TaskStep executes a TaskConfig, whose inputs will be fetched from the worker.ArtifactRepository and outputs will be added to the worker.ArtifactRepository.

func (*TaskStep) Result

func (step *TaskStep) Result(x interface{}) bool

Result indicates Success as true if the script's exit status was 0.

It also indicates ExitStatus as the exit status of the script.

All other types are ignored.

func (*TaskStep) Run

func (step *TaskStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run will first load the TaskConfig. A worker will be selected based on the TaskConfig's platform, the TaskStep's tags, and prioritized by availability of volumes for the TaskConfig's inputs. Inputs that did not have volumes available on the worker will be streamed in to the container.

If any inputs are not available in the worker.ArtifactRepository, MissingInputsError is returned.

Once all the inputs are satisfies, the task's script will be executed, and the RunStep indicates that it's ready, and any signals will be forwarded to the script.

If the script exits successfully, the outputs specified in the TaskConfig are registered with the worker.ArtifactRepository. If no outputs are specified, the task's entire working directory is registered as an ArtifactSource under the name of the task.

func (TaskStep) Using

func (step TaskStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using finishes construction of the TaskStep and returns a *TaskStep. If the *TaskStep errors, its error is reported to the delegate.

type TimeoutStep

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

TimeoutStep applies a fixed timeout to a step's Run.

func Timeout

func Timeout(
	step StepFactory,
	duration string,
	clock clock.Clock,
) TimeoutStep

Timeout constructs a TimeoutStep factory.

func (*TimeoutStep) Result

func (ts *TimeoutStep) Result(x interface{}) bool

Result indicates Success as true if the nested step completed successfully and did not time out.

Any other type is ignored.

func (*TimeoutStep) Run

func (ts *TimeoutStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run parses the timeout duration and invokes the nested step.

If the nested step takes longer than the duration, it is sent the Interrupt signal, and the TimeoutStep returns nil once the nested step exits (ignoring the nested step's error).

The result of the nested step's Run is returned.

func (TimeoutStep) Using

func (ts TimeoutStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs a *TimeoutStep.

type TryStep

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

TryStep wraps another step, ignores its errors, and always succeeds.

func Try

func Try(step StepFactory) TryStep

Try constructs a TryStep factory.

func (*TryStep) Result

func (ts *TryStep) Result(x interface{}) bool

Result indicates Success as true, and delegates everything else to the nested step.

func (*TryStep) Run

func (ts *TryStep) Run(signals <-chan os.Signal, ready chan<- struct{}) error

Run runs the nested step, and always returns nil, ignoring the nested step's error.

func (TryStep) Using

func (ts TryStep) Using(prev Step, repo *worker.ArtifactRepository) Step

Using constructs a *TryStep.

type UnknownArtifactSourceError

type UnknownArtifactSourceError struct {
	SourceName worker.ArtifactName
}

UnknownArtifactSourceError is returned when the worker.ArtifactName specified by the path does not exist in the worker.ArtifactRepository.

func (UnknownArtifactSourceError) Error

func (err UnknownArtifactSourceError) Error() string

Error returns a human-friendly error message.

type UnspecifiedArtifactSourceError

type UnspecifiedArtifactSourceError struct {
	Path string
}

UnspecifiedArtifactSourceError is returned when the specified path is of a file in the toplevel directory, and so it does not indicate a SourceName.

func (UnspecifiedArtifactSourceError) Error

Error returns a human-friendly error message.

type ValidatingConfigSource

type ValidatingConfigSource struct {
	ConfigSource TaskConfigSource
}

ValidatingConfigSource delegates to another ConfigSource, and validates its task config.

func (ValidatingConfigSource) FetchConfig

func (configSource ValidatingConfigSource) FetchConfig(source *worker.ArtifactRepository) (atc.TaskConfig, error)

FetchConfig fetches the config using the underlying ConfigSource, and checks that it's valid.

func (ValidatingConfigSource) Warnings

func (configSource ValidatingConfigSource) Warnings() []string

type VersionInfo

type VersionInfo struct {
	Version  atc.Version
	Metadata []atc.MetadataField
}

VersionInfo is the version and metadata of a resource that was fetched or produced. It is used by Put, Get, and DependentGet.

Directories

Path Synopsis
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL