timely

README

⏱ Timely

Timely is a single-node or distributed cron job system with different backends.

Documentation

Index

• Variables
• func Run(ctx context.Context, sched Scheduler, opts ...Option) error
• type Error
  • func (err Error) Error() string
  • func (err Error) Is(other error) bool
  • func (err Error) With(cause error) Error
• type Executor
• type ExecutorFn
  • func (fn ExecutorFn) Execute(ctx context.Context, req Request) error
• type Job
  • func (j Job) JSON() string
• type Option
• type Request
• type Schedule
  • func (sched Schedule) JSON() string
  • func (sched *Schedule) NextN(t time.Time, n int) []Job
  • func (sched *Schedule) Validate() error
• type Scheduler

Variables

var (
	// ErrInvalid is returned when a schedule definition fails validation.
	ErrInvalid = Error{
		Code:    "invalid_schedule",
		Message: "Schedule is not valid",
	}

	// ErrNotFound is returned when a requested resource (e.g., schedule)
	// is not found.
	ErrNotFound = Error{
		Code:    "not_found",
		Message: "Requested resource not found",
	}

	// ErrConflict is returned when a resource with conflicting id exists.
	ErrConflict = Error{
		Code:    "conflict",
		Message: "Conflicting resource already exists",
	}

	// ErrUnsupported is returned when a requested feature is not supported
	// by the currently used backend.
	ErrUnsupported = Error{
		Code:    "unsupported",
		Message: "Requested feature is not supported",
	}
)

Functions

func Run

func Run(ctx context.Context, sched Scheduler, opts ...Option) error

Run spawns all the worker goroutines for consuming and executing the schedule reqs.

Types

type Error

type Error struct {
	Code    string `json:"code"`
	Cause   error  `json:"cause"`
	Message string `json:"message"`
}

Error represents any error returned by the scheduler along with any relevant context.

func (Error) Error

func (err Error) Error() string

func (Error) Is

func (err Error) Is(other error) bool

Is checks if 'other' is of type Error and has the same code. See https://blog.golang.org/go1.13-errors.

func (Error) With

func (err Error) With(cause error) Error

With returns clone of err with the cause added.

type Executor

type Executor interface {
	// Execute should process the request and execute the job as per the
	// parameters in the job definition and the schedule. Executor is also
	// responsible for invoking Ack() to ack/nack the request.
	Execute(ctx context.Context, req Request) error
}

Executor represents the execution backend for available jobs.

type ExecutorFn

type ExecutorFn func(ctx context.Context, req Request) error

ExecutorFn implements Executor using native Go function value.

func (ExecutorFn) Execute

func (fn ExecutorFn) Execute(ctx context.Context, req Request) error

Execute invokes the function value wrapped.

type Job

type Job struct {
	ID         string                 `json:"id"`
	At         time.Time              `json:"at"`
	Params     map[string]interface{} `json:"params"`
	ScheduleID string                 `json:"schedule_id"`
}

Job represents an instance of execution for a schedule.

func (Job) JSON

func (j Job) JSON() string

JSON returns json string version of the Job.

type Option

type Option func(ru *runSession) error

Option can be used with Run to customise the run behaviour.

type Request

type Request struct {
	// Job is the job ready for execution.
	Job Job `json:"job"`

	// Schedule is the schedule that the job is generated from.
	Schedule Schedule `json:"schedule"`

	// Ack should commit the job as done/failed based on the error.
	// If acked with an error, job may be re-delivered later for
	// retry.
	Ack func(err error) `json:"-"`
}

Request represents an execution request for a job that is ready as per the schedule.

type Schedule

type Schedule struct {
	ID         string    `json:"id"`
	Crontab    string    `json:"crontab"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	Concurrent bool      `json:"concurrent"`
	// contains filtered or unexported fields
}

Schedule is the specification of scheduled job executions.

func (Schedule) JSON

func (sched Schedule) JSON() string

JSON returns json string version of the schedule.

func (*Schedule) NextN

func (sched *Schedule) NextN(t time.Time, n int) []Job

NextN returns next 'n' (at-max) job instances relative to 't'.

func (*Schedule) Validate

func (sched *Schedule) Validate() error

Validate sanitises and validates the schedule specification.

type Scheduler

type Scheduler interface {
	Get(ctx context.Context, id string) (*Schedule, error)
	Put(ctx context.Context, sched Schedule, update bool) (*Schedule, error)
	Del(ctx context.Context, id string) error
	List(ctx context.Context, offset, count int) ([]Schedule, error)

	// Requests should spawn goroutines that keep writing reqs to the
	// returned channel when they become available. When the context is
	// cancelled, all workers must exit and finally close the channel.
	Requests(ctx context.Context) (<-chan Request, error)
}

Scheduler provides facilities for persistence and scheduling of jobs.