job

type ErrArgNotSet ¶

type ErrArgNotSet struct {
	Arg string
}

ErrArgNotSet should be returned by a job when a required key is not set in jobArgs. For example:

val, ok := jobArgs["srcHost"]
if !ok {
  return job.ErrArgNotSet{"srcHost"}
}

func (e ErrArgNotSet) Error() string

type ErrDataNotSet ¶

type ErrDataNotSet struct {
	Key string
}

ErrDataNotSet should be returned by a job when a required key is not set in jobData.

func (e ErrDataNotSet) Error() string

type ErrWrongArgType ¶

type ErrWrongArgType struct {
	Key        string
	GotType    reflect.Type
	ExpectType reflect.Type
}

ErrWrongArgType should be returned by a job when a jobArgs value is not the expected type. For example:

v := jobArgs["sliceOfStrings"]
sliceOfStrings, ok := v.([]string])
if !ok {
  return job.NewErrWrongArgType("sliceOfStrings", v, []string{})
}

func NewErrWrongArgType(key string, got, expect interface{}) ErrWrongArgType

func (e ErrWrongArgType) Error() string

type ErrWrongDataType ¶

type ErrWrongDataType struct {
	Key        string
	GotType    reflect.Type
	ExpectType reflect.Type
}

ErrWrongDataType should be returned by a job when a jobData value is not the expected type. For example:

type Cluster struct { ... }
v := jobData["cluster"]
cluster, ok := v.(Cluster)
if !ok {
  return job.NewErrWrongDataType("cluster", v, Cluster{})
}

func NewErrWrongDataType(key string, got, expect interface{}) ErrWrongDataType

func (e ErrWrongDataType) Error() string

type Factory ¶

type Factory interface {
	Make(jobType, jobName string) (Job, error)
}

A Factory instantiates a Job of the given type. A factory only instantiates a new Job object, it must not call any Job interface methods on the newly create job. If an error is returned, the returned Job should be ignored.

Spin Cycle does not and should not know how to instantiate jobs because they are external (imported in external/jobs.go). Once a job is instantiated with external, implementation-specific details, Spin Cycle only needs to know and use the Job interface methods.

type Job ¶

type Job interface {
	// Create allows the job to get and save internal data needed to run later.
	// The job can save jobArgs and set new ones for other jobs.
	//
	// This method is only called once by the Request Manager when constructing
	// a job chain. Construction of the job chain fails if an error is returned.
	Create(jobArgs map[string]interface{}) error

	// Serialize returns all internal data needed to run later. The reciprocal
	// method is Deserialize.
	//
	// This method is only called once by the Request Manager when constructing
	// a job chain. Construction of the job chain fails if an error is returned.
	Serialize() ([]byte, error)

	// Deserialize sets internal data needed to run later. The reciprocal
	// method is Serialize.
	//
	// This method is only called once by the Job Runner when reconstructing
	// a job chain. Reconstruction of the job chain fails if an error is
	// returned.
	Deserialize([]byte) error

	// Run runs the job using its interal data and the run-time jobData from
	// previously-ran (upstream) jobs. Run can modify jobData. Run is expected
	// to block, but the job must respond to Stop and Status while running.
	// The returned error, if any, indicates a problem before or after running
	// the job. The final state of the job is returned in the Return structure,
	// along with other things like the error and exit code (if there was one).
	// The final state is the most imporant field because it is used by the JR
	// to determine how to handle a job when it's done running.
	//
	// Currently, the Job Runner only calls this method once. Resuming a job is
	// not currently supported.
	Run(jobData map[string]interface{}) (Return, error)

	// Stop stops a job. The Job Runner calls this method when stopping a job
	// chain before it has completed. The job must respond to Stop while Run
	// is executing. Stop is expected to block but also return quickly.
	Stop() error

	// Status returns the real-time status of the job. The job must respond
	// to Status while Run is executing. Status is expected to block but also
	// return quickly.
	Status() string

	// Name returns the name of the job.
	Name() string

	// Type returns the type of the job.
	Type() string
}

A Job is the smallest, reusable building block in Spin Cycle that has meaning by itself. A job should, ideally, do one thing. For example: "DownSIP" brings down a SIP. This job is meaningful by itself and highly reusable.

Spin Cycle defines the Job interface, but jobs are provided by an external repo (imported in external/jobs.go). This is known as "BYOJ": bring your own jobs. A job must implement and be able to accomplish its purpose only through this interface because Spin Cycle only uses this interface.

The Job interface has two sides: one for the Request Manager (RM), the other for the Job Runner (JR). The RM calls Create and Serialize, and the JR calls the other methods. The call sequence is: Create, Serialize, Deserialize, Run.

type Repo ¶

type Repo interface {
	Add(Job) error
	Remove(Job) error
	Get(jobName string) (Job, error)
}

A Repo stores jobs, abstracting away the actual storage method.

type Return ¶

type Return struct {
	State  byte   // proto/STATE_ const
	Exit   int64  // Unix exit code
	Error  error  // Go error
	Stdout string // stdout output
	Stderr string // stderr output
}

Return represents return values and output from a job. State indicates how the job completed. If State == proto.STATE_COMPLETE, the job completed successfully. Anything else indicates that the job failed or didn't complete, which will probably cause the job chain to stop. The job is responsible for adhering to this convention.

State, Exit, and Error are not mutually exclusive. A job can return State = STATE_COMPLETE to indicate success but also a non-nil Error or a non-zero Exit. This is useful for idempotent jobs and logging that the job was successful because it handled being re-ran. For example, a job could delete a record, but when re-ran the record has already been deleted, so the job is successful but reports Error = ErrRecordNotFound for logging.