Files

169 lines
5.4 KiB
Go

package scheduling
import (
"context"
"fmt"
"strings"
"time"
)
// OwnerKind names what a schedule belongs to.
type OwnerKind string
const (
// OwnerInstance is the instance itself; its runs act as the system
// identity.
OwnerInstance OwnerKind = "instance"
// OwnerOrg is one organisation, named by Owner.ID.
OwnerOrg OwnerKind = "org"
)
// Owner references what a schedule belongs to. The dashboard renders the
// referenced thing's name; nothing stores a display string.
type Owner struct {
Kind OwnerKind
// ID is the organisation id for OwnerOrg and empty for OwnerInstance.
ID string
}
// Validate rejects an unknown kind and an ID that does not fit it.
func (o Owner) Validate() error {
switch o.Kind {
case OwnerInstance:
if o.ID != "" {
return fmt.Errorf("%w: an instance owner has no id", ErrInvalidSpec)
}
case OwnerOrg:
if o.ID == "" {
return fmt.Errorf("%w: an organisation owner needs an id", ErrInvalidSpec)
}
default:
return fmt.Errorf("%w: unknown owner kind %q", ErrInvalidSpec, o.Kind)
}
return nil
}
// Schedule is one stored schedule.
type Schedule struct {
ID string
Name string
Owner Owner
Enabled bool
// BuiltIn schedules are defined in code: only Enabled and Timing change.
BuiltIn bool
Timing Timing
// NextRun is when the schedule next fires; zero when it never will.
NextRun time.Time
Created time.Time
Updated time.Time
// LastRun is the most recent run, nil before the first.
LastRun *Run
}
// Validate checks the fields a write needs.
func (s Schedule) Validate() error {
if strings.TrimSpace(s.ID) == "" {
return fmt.Errorf("%w: id is required", ErrInvalidSpec)
}
if strings.TrimSpace(s.Name) == "" {
return fmt.Errorf("%w: name is required", ErrInvalidSpec)
}
if err := s.Owner.Validate(); err != nil {
return err
}
return s.Timing.Validate()
}
// RunResult is a run's state.
type RunResult string
const (
// RunPending is a requested run no scheduler has picked up yet.
RunPending RunResult = "pending"
RunRunning RunResult = "running"
RunSucceeded RunResult = "succeeded"
RunFailed RunResult = "failed"
// RunSkipped is a firing dropped because the schedule's previous run was
// still going.
RunSkipped RunResult = "skipped"
)
// Run is one firing of a schedule.
type Run struct {
ID int64
ScheduleID string
// ScheduledFor is the grid time the run belongs to, or the request time
// of a run started by hand. It is unique per schedule, which is what
// stops two schedulers firing the same slot.
ScheduledFor time.Time
Started time.Time
Finished time.Time
Result RunResult
Error string
// CaptureID is the schedule-fired capture the run recorded, empty when
// none. The tasks it started are binding dispatches against it.
CaptureID string
}
// Claim is a run handed to the scheduler to execute.
type Claim struct {
Run
Name string
BuiltIn bool
// Org is the organisation the firing belongs to: the owner of an org
// schedule, the system org for an instance schedule.
Org string
}
// Builtin is a schedule defined in code, seeded once and then owned by the
// operator's enabled flag and timing.
type Builtin struct {
ID string
Name string
Interval time.Duration
}
// Settings are the instance's schedule settings.
type Settings struct {
// Location is the zone cron expressions are read in.
Location *time.Location
// RunRetention and RunRetentionCount bound run history: a finished run
// goes when it is older than RunRetention or beyond the newest
// RunRetentionCount of its schedule, whichever comes first.
RunRetention time.Duration
RunRetentionCount int
}
// Store persists schedules. Methods that compute a next run take the zone
// cron is read in.
type Store interface {
ListSchedules(ctx context.Context) ([]Schedule, error)
GetSchedule(ctx context.Context, id string) (Schedule, error)
// PutSchedule creates or replaces a schedule and returns it as stored.
// A built-in schedule keeps everything but Enabled and Timing.
PutSchedule(ctx context.Context, s Schedule, loc *time.Location) (Schedule, error)
// DeleteSchedule refuses a built-in schedule with ErrBuiltIn.
DeleteSchedule(ctx context.Context, id string) error
// EnsureBuiltins inserts each missing built-in and leaves existing ones.
EnsureBuiltins(ctx context.Context, builtins []Builtin, loc *time.Location) error
ListRuns(ctx context.Context, scheduleID string, limit int) ([]Run, error)
}
// RunStore persists schedule runs.
type RunStore interface {
// ClaimDue starts every requested run and claims one run for each enabled
// schedule due at now, moving its next run past now. A run left running
// longer than stale is failed first, and a cron schedule whose next run
// was computed in another zone is recomputed in loc.
ClaimDue(ctx context.Context, now time.Time, stale time.Duration, loc *time.Location) ([]Claim, error)
// PruneRuns deletes finished runs older than before or beyond the newest
// keep of their schedule.
PruneRuns(ctx context.Context, before time.Time, keep int) (int64, error)
// RequestRun queues a run of id at now without moving its next run.
RequestRun(ctx context.Context, id string, now time.Time) (Run, error)
// FinishRun records a claimed run's result and returns how many of the
// schedule's latest finished runs failed in a row.
FinishRun(ctx context.Context, runID int64, result RunResult, errText string, at time.Time) (int, error)
SetRunCapture(ctx context.Context, runID int64, captureID string) error
}