169 lines
5.4 KiB
Go
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
|
|
}
|