jobs

Documentation

Overview

Provides the units of work, Jobs, for the reactor pattern implementation in the dispatcher package.

A job is a unit of execution that is abstracted from its environment.

Index

• Variables
• func AddJobExtension(extension JobExtension)
• type ClientResponse
  • func (s *ClientResponse) Failure(e error)
  • func (s *ClientResponse) StreamResult() bool
  • func (s *ClientResponse) Success(t ResponseSuccess)
  • func (s *ClientResponse) SuccessWithData(t ResponseSuccess, data interface{})
  • func (s *ClientResponse) SuccessWithWrite(t ResponseSuccess, flush, structured bool) io.Writer
  • func (s *ClientResponse) WritePending(w io.Writer)
  • func (s *ClientResponse) WritePendingSuccess(name string, value interface{})
• type Job
  • func JobFor(request interface{}) (Job, error)
• type JobContext
• type JobError
• type JobExtension
• type JobExtensionFunc
  • func (f JobExtensionFunc) JobFor(request interface{}) (Job, error)
• type JobFunction
  • func (job JobFunction) Execute(res Response)
• type JobInitializer
  • func (c *JobInitializer) JobFor(request interface{}) (Job, error)
• type Join
• type RequestIdentifier
  • func NewRequestIdentifier() RequestIdentifier
  • func NewRequestIdentifierFromString(s string) (RequestIdentifier, error)
  • func (r RequestIdentifier) Exact() string
  • func (r RequestIdentifier) String() string
• type Response
• type ResponseFailure
• type ResponseSuccess
• type SimpleError
  • func (j SimpleError) Error() string
  • func (j SimpleError) ResponseData() interface{}
  • func (j SimpleError) ResponseFailure() ResponseFailure
• type StructuredJobError
  • func (j StructuredJobError) ResponseData() interface{}
• type UnknownJobError
  • func (s UnknownJobError) ResponseData() interface{}
  • func (s UnknownJobError) ResponseFailure() ResponseFailure

Variables

var ErrNoJobForRequest = errors.New("no job matches that request")

No job exists that matches the request.

var (
	ErrRanToCompletion = SimpleError{ResponseError, "This job has run to completion."}
)

Functions

func AddJobExtension

func AddJobExtension(extension JobExtension)

Register a job extension to this executable during init() or startup

Types

type ClientResponse

type ClientResponse struct {
	// A response stream to output to.  Defaults to DevNull
	Output io.Writer
	// true if output should be captured rather than printed
	Gather bool

	// Data gathered during request parsing FIXME: move to marshal?
	Pending map[string]interface{}
	// Data gathered from the response
	Data interface{}
	// The error set on the response
	Error error
	// contains filtered or unexported fields
}

A default implementation of the Response interface.

func (*ClientResponse) Failure

func (s *ClientResponse) Failure(e error)

func (*ClientResponse) StreamResult

func (s *ClientResponse) StreamResult() bool

func (*ClientResponse) Success

func (s *ClientResponse) Success(t ResponseSuccess)

func (*ClientResponse) SuccessWithData

func (s *ClientResponse) SuccessWithData(t ResponseSuccess, data interface{})

func (*ClientResponse) SuccessWithWrite

func (s *ClientResponse) SuccessWithWrite(t ResponseSuccess, flush, structured bool) io.Writer

func (*ClientResponse) WritePending

func (s *ClientResponse) WritePending(w io.Writer)

func (*ClientResponse) WritePendingSuccess

func (s *ClientResponse) WritePendingSuccess(name string, value interface{})

type Job

type Job interface {
	Execute(Response)
}

A job is a unit of work - it may execute and return structured data or stream a response.

func JobFor

func JobFor(request interface{}) (Job, error)

Return a registered Job implementation that satisfies the requested job. If no such implementation exists, returns ErrNoJobForRequest.

type JobContext

type JobContext struct {
	Id   RequestIdentifier
	User string
}

type JobError

type JobError interface {
	error
	ResponseFailure() ResponseFailure
	ResponseData() interface{} // May be nil if no data is returned to a client
}

A structured error response for a job.

type JobExtension

type JobExtension interface {
	// Return an error if the requested job is invalid, ErrNoJobForRequest
	// if this interface does not recognize the Job, or a valid Job.
	JobFor(request interface{}) (Job, error)
}

Interface for mapping between a request and a Job

type JobExtensionFunc

type JobExtensionFunc func(interface{}) (Job, error)

Convenience wrapper for execution a JobExtension handler

func (JobExtensionFunc) JobFor

func (f JobExtensionFunc) JobFor(request interface{}) (Job, error)

type JobFunction

type JobFunction func(Response)

Convenience wrapper for an anonymous function.

func (JobFunction) Execute

func (job JobFunction) Execute(res Response)

type JobInitializer

type JobInitializer struct {
	Extension JobExtension
	Func      func() error
	// contains filtered or unexported fields
}

func (*JobInitializer) JobFor

func (c *JobInitializer) JobFor(request interface{}) (Job, error)

type Join

type Join interface {
	Join(Job, <-chan bool) (bool, <-chan bool, error)
}

A client may rejoin a running job by re-executing the request, and a job that supports this interface will be notified that a second client has connected. Typically the join will stream output or return the result of the call, but not do any actual work.

type RequestIdentifier

type RequestIdentifier []byte

func NewRequestIdentifier

func NewRequestIdentifier() RequestIdentifier

func NewRequestIdentifierFromString

func NewRequestIdentifierFromString(s string) (RequestIdentifier, error)

func (RequestIdentifier) Exact

func (r RequestIdentifier) Exact() string

func (RequestIdentifier) String

func (r RequestIdentifier) String() string

type Response

type Response interface {
	StreamResult() bool

	Success(t ResponseSuccess)
	SuccessWithData(t ResponseSuccess, data interface{})
	SuccessWithWrite(t ResponseSuccess, flush, structured bool) io.Writer
	Failure(reason error)

	WritePendingSuccess(name string, value interface{})
}

A job may return a structured error, a stream of unstructured data, or a stream of structured data. In general, jobs only stream on success - a failure is written immediately. A streaming job may write speculative side channel data that will be returned when a successful response occurs, or thrown away when an error is written. Error writes are final

type ResponseFailure

type ResponseFailure int

const (
	ResponseError ResponseFailure = iota
	ResponseAlreadyExists
	ResponseNotFound
	ResponseInvalidRequest
	ResponseRateLimit
	ResponseNotAcceptable
)

type ResponseSuccess

type ResponseSuccess int

const (
	ResponseOk ResponseSuccess = iota
	ResponseAccepted
)

type SimpleError

type SimpleError struct {
	Failure ResponseFailure
	Reason  string
}

An error with a code and message to user

func (SimpleError) Error

func (j SimpleError) Error() string

func (SimpleError) ResponseData

func (j SimpleError) ResponseData() interface{}

func (SimpleError) ResponseFailure

func (j SimpleError) ResponseFailure() ResponseFailure

type StructuredJobError

type StructuredJobError struct {
	SimpleError
	Data interface{}
}

An error that has associated response data to communicate to a client.

func (StructuredJobError) ResponseData

func (j StructuredJobError) ResponseData() interface{}

type UnknownJobError

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

Cast error to UnknownJobError for default behavior

func (UnknownJobError) ResponseData

func (s UnknownJobError) ResponseData() interface{}

func (UnknownJobError) ResponseFailure

func (s UnknownJobError) ResponseFailure() ResponseFailure