Files
archie/internal/infrastructure/cronstore/errors.go
T
sam c132aa980d feat(cronstore): durable job store with cross-process locking
Slice 1 of the cron/scheduling epic (archie-core-1786637496320-249-be6d9a20).
Implements the file-backed job store the scheduling ticker engine polls
through scheduling.JobSource. The engine applies no schedule arithmetic
of its own, so the store owns cron expressions, fixed intervals, and
catch-up windows — Slice 1 ships Interval fully, with Once accepted at
Create/fired at Due, and Cron reserved as a wire shape for Slice 2.

Files: per-profile JSON at <path>/jobs.json with a version-stamped
schema. CRUD by job id with merge-semantic Update (nil Patch fields are
preserved). Truncated/partial-write files return ErrCorruptFile; forward
schema versions return ErrUnsupportedSchema. DisallowUnknownFields means
additive shape changes must bump schemaVersion.

Concurrency: three locks stack in fixed order. (1) A package-level
mutex keyed by lock-file path serialises Stores within one process —
Linux flock is per file description, so two Store instances in the
same process have independent fds and would otherwise proceed in
parallel. (2) Cross-process flock serialises Stores across processes
(CLI vs daemon). (3) s.mu guards the in-memory mirror. Every
operation re-hydrates from disk before applying its change so a writer
that just acquired the locks sees every change the previous writer
committed. Atomic write via temp-file + rename + fsync for durability.

Validation: Create and Update validate Pool, Schedule, and required
fields up front so a hand-edited file cannot persist a job the engine
cannot reason about. MarkRun on a kind without next-run arithmetic
returns ErrScheduleUnsupported. Get/List return deep copies so caller
mutation cannot corrupt the in-memory mirror. Files are written 0o600
because payloads can carry operator-identifying data; SetEscapeHTML(false)
keeps operator-readable files human-friendly.
2026-08-28 22:28:49 +10:00

40 lines
1.8 KiB
Go

package cronstore
import "errors"
// Sentinel errors callers can match with errors.Is.
var (
// ErrUnsupportedSchema is returned by Open when the persisted file
// declares a schema version this build does not understand. The
// store treats that as an explicit refusal to read: a forward
// version may have shape we cannot safely render back out, and
// silently downgrading would lose data.
ErrUnsupportedSchema = errors.New("cronstore: unsupported schema version")
// ErrCorruptFile is returned by Open when the file exists but does
// not decode as a valid envelope: truncated, garbage, or fields of
// the wrong shape. The store never panics on bad input, so the
// engine can surface this as phase="source" KindJobError.
ErrCorruptFile = errors.New("cronstore: corrupt file")
// ErrJobExists is returned by Create when the requested id is
// already present. Callers that want upsert semantics should
// follow up with Update.
ErrJobExists = errors.New("cronstore: job already exists")
// ErrJobNotFound is returned by Get, Update and MarkRun when the
// id is absent. Delete is the exception: it is idempotent.
ErrJobNotFound = errors.New("cronstore: job not found")
// ErrInvalidSpec is returned by Create and Update when the supplied
// JobSpec / Patch fails the store's structural validation (empty id,
// unknown schedule kind, non-positive interval).
ErrInvalidSpec = errors.New("cronstore: invalid job spec")
// ErrScheduleUnsupported is returned by MarkRun when the job's
// schedule kind cannot compute its next run time. Slice 1 only
// knows interval arithmetic; cron / once return this so callers
// can surface a clear error rather than silently advancing.
ErrScheduleUnsupported = errors.New("cronstore: schedule kind not implemented")
)