Files
archie/internal/infrastructure/cronstore/lock_unix.go
T
sam 37f7408474 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

69 lines
1.9 KiB
Go

//go:build unix
package cronstore
import (
"fmt"
"os"
"syscall"
)
// lockedFile is an OS-level flock wrapper around a sidecar file. The
// store acquires it before reading or writing the JSON, so a CLI edit
// and a daemon writer cannot tear the same jobs.json.
//
// flock is per-open-file-description, which means a single Store holds
// the lock for as long as it lives; concurrent processes opening the
// same sidecar queue behind it.
type lockedFile struct {
f *os.File
}
// openLock creates (or opens) the lock file and returns it unlocked.
// The lock is acquired separately via Lock, so Open can hydrate without
// holding it.
func openLock(path string) (*lockedFile, error) {
f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o644)
if err != nil {
return nil, fmt.Errorf("open lock file %s: %w", path, err)
}
return &lockedFile{f: f}, nil
}
// Lock blocks until the OS-level exclusive flock is acquired. flock is
// reentrant on Linux per-fd, so calling Lock twice on the same lockedFile
// from the same goroutine is fine; calling it from two goroutines still
// serialises.
func (l *lockedFile) Lock() error {
if l == nil || l.f == nil {
return fmt.Errorf("cronstore: lock not initialised")
}
if err := syscall.Flock(int(l.f.Fd()), syscall.LOCK_EX); err != nil {
return fmt.Errorf("flock LOCK_EX: %w", err)
}
return nil
}
// Unlock releases the exclusive flock. Idempotent in the sense that a
// second call after Close simply returns nil because the fd is closed.
func (l *lockedFile) Unlock() error {
if l == nil || l.f == nil {
return nil
}
if err := syscall.Flock(int(l.f.Fd()), syscall.LOCK_UN); err != nil {
return fmt.Errorf("flock LOCK_UN: %w", err)
}
return nil
}
// Close closes the sidecar fd. The flock is released automatically by
// the kernel.
func (l *lockedFile) Close() error {
if l == nil || l.f == nil {
return nil
}
err := l.f.Close()
l.f = nil
return err
}