persist

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
const CurrentVersion = 1

CurrentVersion is the on-disk schema version this build writes. Bump (with a migration path) on any future-incompatible change.

Variables

View Source
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.

View Source
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.

View Source
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

func NewStore(path string) *Store

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

func (s *Store) ClearDisabled(name string) error

ClearDisabled removes a job name from the disabled list. No-op if not present.

func (*Store) Enabled

func (s *Store) Enabled() bool

Enabled reports whether the store has a backing file.

func (*Store) GetSchedule added in v1.1.0

func (s *Store) GetSchedule(name string) (Schedule, bool)

GetSchedule returns a copy of the named schedule record.

func (*Store) Load

func (s *Store) Load() error

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) Path

func (s *Store) Path() string

Path returns the configured file path (empty if disabled).

func (*Store) PutJob

func (s *Store) PutJob(name string, job Job) error

PutJob inserts or replaces a job entry and persists. No-op if the store is disabled.

func (*Store) PutSchedule added in v1.1.0

func (s *Store) PutSchedule(name string, r Schedule) error

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

func (s *Store) RemoveJob(name string) error

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

func (s *Store) RemoveSchedules(names ...string) error

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

func (s *Store) ScheduleNames() []string

ScheduleNames returns the names that have a schedule record, sorted.

func (*Store) SetDisabled

func (s *Store) SetDisabled(name string) error

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.

func (*Store) Snapshot

func (s *Store) Snapshot() State

Snapshot returns a deep-ish copy of the current state. Callers must not mutate the returned slices/maps in place if they want isolation from subsequent Store changes — typical callers (boot-time loader, tests) only read.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL