persist

package
v0.29.1 Latest Latest
Warning

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

Go to latest
Published: Aug 12, 2026 License: MIT Imports: 9 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 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 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"`
	// 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

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