Documentation
¶
Overview ¶
Package persist stores the subset of scheduler state that originates from the web UI / REST API and that operators reasonably expect to survive a daemon restart (issue #593).
Scope (intentional):
- Jobs created or updated via POST /api/jobs (origin="api").
- The set of *disabled* job names — disable applies regardless of origin, so an operator can pause an INI-defined job from the UI and have that pause survive restart.
Out of scope:
- Jobs defined in INI or via Docker labels: those sources are authoritative and reloaded fresh every boot.
- Runtime stats (history, last-run, errors): rebuilt by core.
- Webhook configuration, global settings, anything from [global].
Format: stdlib-encoding/json, written atomically (tmp + rename) on every mutation. The on-disk schema carries a Version field so future-incompatible changes can be migrated explicitly rather than silently drift. The file is human-readable so operators can inspect or back it up with rsync; hand-editing is supported but discouraged in favor of API calls (a malformed file fails the daemon boot).
Concurrency: a single *Store is safe for concurrent calls from the web handlers; an internal RWMutex guards both the in-memory snapshot and the file write. Saves are serialized; readers don't block on a save in progress.
Index ¶
- Constants
- Variables
- type Dispatch
- type Job
- type JobType
- type Occurrence
- type Schedule
- type State
- type Store
- func (s *Store) ClearDisabled(name string) error
- func (s *Store) Enabled() bool
- func (s *Store) GetSchedule(name string) (Schedule, bool)
- func (s *Store) Load() error
- func (s *Store) Path() string
- func (s *Store) PutJob(name string, job Job) error
- func (s *Store) PutSchedule(name string, r Schedule) error
- func (s *Store) RemoveJob(name string) error
- func (s *Store) RemoveSchedules(names ...string) error
- func (s *Store) ScheduleNames() []string
- func (s *Store) SetDisabled(name string) error
- func (s *Store) Snapshot() State
Constants ¶
const CurrentVersion = 1
CurrentVersion is the on-disk schema version this build writes. Bump (with a migration path) on any future-incompatible change.
Variables ¶
var ErrNullJobValue = errors.New("persist: job entry is null (expected object)")
ErrNullJobValue is returned by Load when the file contains a job or schedule entry whose value is JSON `null` rather than an object. Pre-fix this would surface as a nil-pointer panic on the next Snapshot or Save; fail-closed at Load with a typed sentinel so callers can distinguish hand-edit hazards from generic decode errors.
var ErrStateFileTooLarge = errors.New("persist: state file exceeds size limit")
ErrStateFileTooLarge is returned by Load when the state file exceeds maxStateFileBytes. Wrapping a sentinel lets callers distinguish "boot must abort" (this + ErrUnsupportedVersion) from generic I/O errors that might warrant a retry.
var ErrUnsupportedVersion = errors.New("persist: unsupported state-file version")
ErrUnsupportedVersion is returned by Load when the file's Version field is newer than CurrentVersion. We intentionally fail closed rather than guess at a forward migration the operator hasn't opted into — silent data loss is the worse outcome.
Functions ¶
This section is empty.
Types ¶
type Dispatch ¶ added in v1.1.0
type Dispatch struct {
Occurrence
// Execution is the execution ID of the run, set when the run starts.
Execution string `json:"execution,omitempty"`
// State is "waiting" (for a global slot), "started" or "ended".
State string `json:"state"`
// Outcome is set once the run ended: "success", "failed", "canceled",
// or "unknown" when the daemon stopped without recording an end.
Outcome string `json:"outcome,omitempty"`
}
Dispatch is an admitted occurrence and how far it got.
type Job ¶
type Job struct {
Type JobType `json:"type"`
Schedule string `json:"schedule"`
Command string `json:"command,omitempty"`
// Run + Exec
Container string `json:"container,omitempty"`
// Run-only
Image string `json:"image,omitempty"`
MaxRuntime string `json:"maxRuntime,omitempty"`
// Compose-only
File string `json:"file,omitempty"`
Service string `json:"service,omitempty"`
Exec bool `json:"exec,omitempty"`
}
Job is the per-entry on-disk representation. Carries the union of fields the web API accepts (web.jobRequest); fields not relevant to a given Type stay zero-value and are omitted by `omitempty`. Adding a new field is backward-compatible (older builds drop it on read, new builds round-trip it).
type JobType ¶
type JobType string
JobType enumerates the API-creatable job kinds. Mirrors web.jobRequest.Type so the round-trip from API → state-file → load is lossless. Kept as a string alias rather than an int enum so the on-disk format reads naturally and so new types can be added without renumbering.
const ( JobTypeRun JobType = "run" // start a fresh container from an image JobTypeExec JobType = "exec" // exec a command inside an already-running container JobTypeLocal JobType = "local" // run a command on the host ofelia itself runs on JobTypeCompose JobType = "compose" // docker compose run/exec against a service in a compose file )
The job kinds the API can create, and therefore the only values that legitimately appear in a state file's `type` field. Each corresponds to an INI section family (job-run, job-exec, job-local, job-compose).
type Occurrence ¶ added in v1.1.0
type Occurrence struct {
// Scheduled is the time the fire was scheduled for, in UTC.
Scheduled time.Time `json:"scheduled"`
// Trigger is what produced it: "scheduled", "catch-up" or "manual".
Trigger string `json:"trigger"`
}
Occurrence is one fire of a schedule entry.
type Schedule ¶ added in v1.1.0
type Schedule struct {
// Revision identifies the schedule the record belongs to: the cron
// expression, its time zone, concurrency and missed_fires. A different
// revision starts the record afresh.
Revision string `json:"revision"`
// Activated is when this revision was first armed.
Activated time.Time `json:"activated"`
// Cursor is the most recent scheduled time the running scheduler
// evaluated. A fire after it that falls into a downtime is missed.
Cursor time.Time `json:"cursor"`
// Dispatch is the occurrence admitted last.
Dispatch *Dispatch `json:"dispatch,omitempty"`
// Pending is the occurrence in the queue slot (concurrency: queue).
Pending *Occurrence `json:"pending,omitempty"`
// Workload is the execution ID whose workload has not been confirmed
// ended. It survives dispatch completion, schedule changes and restarts.
// An empty value means there is no unresolved workload.
Workload string `json:"workload,omitempty"`
// WorkloadEnded distinguishes a confirmed workload end from legacy
// unsuccessful records that did not track workload state at all.
WorkloadEnded bool `json:"workloadEnded,omitempty"`
}
Schedule is the record of one schedule entry (ADR-005): where the scheduler's evaluation of the schedule stands and what happened to the occurrence it admitted last.
type State ¶
type State struct {
Version int `json:"version"`
Jobs map[string]*Job `json:"jobs,omitempty"` // keyed by job name
Disabled []string `json:"disabled,omitempty"` // job names disabled; sorted on write for determinism
// Schedules holds the schedule records of Compose jobs with
// missed_fires: one or concurrency: queue (ADR-005), keyed by job name.
// A build that predates the field rejects a file that contains it,
// because Load refuses unknown fields.
Schedules map[string]*Schedule `json:"schedules,omitempty"`
}
State is the on-disk document.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store wraps an on-disk State with concurrency-safe mutators that atomically persist on every change. Construct with NewStore(path); a zero path means "disabled" and every mutator becomes a no-op so callers don't have to nil-check at every call site.
func NewStore ¶
NewStore returns a Store backed by the given path. An empty path disables persistence — Load returns an empty state, mutators are no-ops, Save never touches disk. This lets callers wire a single nil-safe Store without branching on configuration.
func (*Store) ClearDisabled ¶
ClearDisabled removes a job name from the disabled list. No-op if not present.
func (*Store) GetSchedule ¶ added in v1.1.0
GetSchedule returns a copy of the named schedule record.
func (*Store) Load ¶
Load reads the state file into memory. Missing file is treated as "fresh start" (empty state, no error) so first boot with persistence enabled doesn't fail before any API call has run. A malformed file or a future Version returns an error — boot must fail loudly rather than silently drop persisted state. Unknown JSON fields fail decode so hand-edit typos surface rather than silently no-op.
func (*Store) PutJob ¶
PutJob inserts or replaces a job entry and persists. No-op if the store is disabled.
func (*Store) PutSchedule ¶ added in v1.1.0
PutSchedule inserts or replaces a schedule record and persists it in the same atomic write. No-op if the store is disabled.
func (*Store) RemoveJob ¶
RemoveJob deletes the job entry (if present) and persists. Removing the job does NOT clear it from the disabled list — disable status is kept independent because operators may pre-disable a job before the API recreates it. Returns nil if the name wasn't tracked.
func (*Store) RemoveSchedules ¶ added in v1.1.0
RemoveSchedules deletes the named schedule records and persists once. Names without a record are ignored; nothing is written if none had one.
func (*Store) ScheduleNames ¶ added in v1.1.0
ScheduleNames returns the names that have a schedule record, sorted.
func (*Store) SetDisabled ¶
SetDisabled marks a job name as disabled (persisted across restart). Calling with a name already disabled is a no-op (no save). Idempotent to keep API handlers simple.