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 Job
- type JobType
- type State
- type Store
- func (s *Store) ClearDisabled(name string) error
- func (s *Store) Enabled() bool
- func (s *Store) Load() error
- func (s *Store) Path() string
- func (s *Store) PutJob(name string, job Job) error
- func (s *Store) RemoveJob(name string) error
- 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 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 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 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
}
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) 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) 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) 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.