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 } // 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 }