client

type ArgsType int

type Builder interface {
	// AddTask adds a Task to the Labor.
	AddTask(name, desc string, opts ...TaskOption) error

	// AddPreCheck adds a Precheck to a Task. Will be added to the last
	// Task created by AddTask().
	AddPreCheck(cogPath, desc string, args proto.Message) error

	// AddContCheck adds a ContCheck to a Task. Will be added to the last
	// Task created by AddTask().
	AddContCheck(cogPath, desc string, args proto.Message) error

	// AddSequence adds a Sequence to the last Task created with AddTask().
	AddSequence(target, desc string) error

	// AddJob adds a Job to the last Sequence created with AddSequence()/
	AddJob(cogPath, desc string, args proto.Message) error

	// Labor returns a COPY of the Labor object.
	Labor() *Labor
}

type BuilderOption func(b *builder) error

type Control interface {
	// Submit submits a Labor to the Marmot service. If start is set, will start
	// execution immediately.  Otherwise Start() must be called. Returns the
	// ID of the Labor.
	Submit(ctx context.Context, l *Labor, start bool) (string, error)

	// Start starts execution of Labor with ID "id".
	Start(ctx context.Context, id string) error

	// Pause pauses execution of Labor with ID "id".
	Pause(ctx context.Context, id string) error

	// Resume unpauses a Labor the is in the pause state at ID "id".
	Resume(ctx context.Context, id string) error

	// Stop stops an executing Labor with the ID "id".
	Stop(ctx context.Context, id string) error

	// Wait waits for a Labor with id to reach a completion state.
	Wait(ctx context.Context, id string) error

	// Monitor returns Labor objects representing a single Labor as it is executed
	// by the service, stopping when the Labor reaches its final execution.
	// These Labors will only have state data and no args/output data.
	Monitor(ctx context.Context, id string) (chan LaborStream, error)

	// SearchLabors returns a stream of Labors matching the filter.
	SearchLabors(ctx context.Context, filter SearchFilter) (chan LaborStream, error)

	// FetchLabor returns with ID 'id'.  If 'full' is set, the input/output data
	// will be returned.
	FetchLabor(ctx context.Context, id string, full bool) (*Labor, error)

	// Close kills the connection to the service.
	Close()
}

type ControlOption func(c *control) error

type Job struct {
	// CogPath is the name of the Cog the Job will use.
	CogPath string

	// Args are the arguments to the Cog in JSON protocol buffer format.
	// Use .SetArgs() to convert your proto.Message to JSON automatically.
	Args string

	// Output is the output from the Cog.
	Output string

	// Timeout is the amount of time a Job is allowed to run.
	Timeout time.Duration

	// Retries is the number of times to retry a Cog that fails.
	// TODO(johnsiilver): Add support for this on the server side.
	Retries int

	// RetryDelay is how long to wait between retrying a Cog.
	RetryDelay time.Duration

	Meta
}

type Labor struct {
	// Tags are single word text strings that can be used to group Labors when
	// doing a search.
	Tags []string

	// Tasks are the tasks that are associated with this Labor.
	Tasks []*Task

	Meta
}

type LaborStream struct {
	Labor *Labor
	Error error
}

type Meta struct {
	// ID contains a unique UUIDv4 representing the object.
	ID string

	// Name contains the name to be displayed to users.
	Name string

	// Desc contains a description of what the object is doing.
	Desc string

	// State is the current state of the object.  It cannot be set by the client.
	State State

	// Started is when an object begins execution.
	Started time.Time

	// Ended is when an object stops execution.
	Ended time.Time

	// Submitted is when a Labor was submitted to the system.  Only valid for Labors.
	Submitted time.Time

	// Reason contains the failiure reason for an object, which is a type Reason.
	Reason Reason
}

type Reason int

type SearchFilter struct {
	// States returns objects that are currently at one the "states".
	// If empty, all states are included.
	States []pb.States

	// NamePrefix/ NameSuffix locates Labors starting with the string.
	// An empty string has no filter.
	NamePrefix, NameSuffix string

	// Tags matches any Labor that has any tag listed.  An empty list has no filter.
	Tags []string

	// SubmitBegin locates any Labor that was submitted at or after this time.
	SubmitBegin time.Time

	// SubmitEnd locates any Labor that was submitted before this time.
	SubmitEnd time.Time
}

type Sequence struct {
	// Target is the name of what this sequence targets. This could be a device,
	// a service, a directory... whatever makes sense for whatever is being done.
	Target string

	// Jobs is a sequence of jobs to execute.
	Jobs []*Job

	Meta
}

type State int

type Task struct {
	// PreChecks are Jobs that are executed before executing the Jobs in the
	// Task. If any of these fail, the Task is not executed and fails.
	// This is used provide checks before initiating actions. These are run
	// concurrently.
	PreChecks []*Job

	// ContChecks are Jobs that are exeucted continuously until the task ends
	// with ContCheckInterval between runs.  If any check fails, the Task stops
	// execution and fails.  These are run concurrently.
	ContChecks []*Job

	// ToleratedFailures is how many sequence failures to tolerate before stopping.
	ToleratedFailures int

	// Concurrency is how many Jobs to run simultaneously.
	Concurrency int

	// ContCheckInterval is how long between runs of ContCheck Jobs.
	ContCheckInterval time.Duration

	// PassFailures causes the failures in this Task to be passed to the next
	// Task, acting againsts its ToleratedFailures.
	PassFailures bool

	// Sequence are a set of Jobs.
	Sequences []*Sequence

	Meta
}

type TaskOption func(t *Task)