persist

Documentation

Overview

Package persist is INTERNAL-ONLY — corrupt-file quarantine and warning recovery. Pure infrastructure with no operator-facing contract.

Index

• Constants
• func AxisDir() string
• func AxisPath(elem ...string) string
• func LockFile(path string) (release func(), err error)
• func QuarantineCorruptFile(path string, cause error) error
• func WriteFileAtomic(path string, data []byte, perm os.FileMode) error
• type RecoveryWarning
  • func (w *RecoveryWarning) Error() string

Constants

const AxisHomeEnv = "AXIS_HOME"

AxisHomeEnv names the environment variable that overrides the AXIS home directory. When set to a non-empty value it replaces ~/.axis wholesale — it names the directory itself, not the parent home, so AXIS_HOME=/tmp/x resolves state.json to /tmp/x/state.json.

This is the isolation seam for audit finding C5: without it the test suite resolves every store to the operator's real ~/.axis. The Makefile test targets set it to a disposable directory. HOME is deliberately not used for that purpose — GOCACHE, GOPATH, and GOMODCACHE derive from HOME, so repointing it discards the build cache on every run.

Functions

func AxisDir

func AxisDir() string

AxisDir returns the AXIS home directory: $AXIS_HOME when set and non-empty, otherwise ~/.axis.

When the user's home directory cannot be determined, os.UserHomeDir's error is intentionally ignored and an empty home is used, yielding a relative ".axis" path. This mirrors the historical behaviour of the many call sites that constructed this path inline with `home, _ := os.UserHomeDir()`.

func AxisPath

func AxisPath(elem ...string) string

AxisPath joins elem onto the AXIS home directory. It is the shared replacement for the `filepath.Join(home, ".axis", ...)` pattern that was previously duplicated across the config, state, skills, reservation, daemon, events, auth, api, execution, chat, facts, and CLI packages.

Every AXIS-owned path must resolve through here. Building a ~/.axis path from a direct os.UserHomeDir call bypasses the AXIS_HOME seam above and re-opens C5 for that store.

func LockFile

func LockFile(path string) (release func(), err error)

LockFile acquires an exclusive advisory lock for the store at path, using a sibling "<path>.lock" file. The returned release function is idempotent.

LOCK ORDERING. A caller taking more than one store lock MUST acquire them in this order, and release in reverse:

1. state.Path()
2. skills.Path()

DEADLOCK. flock is associated with the open file description, so a second Open+Flock of the same lock file blocks even within one process. Never call state.Update or skills.Update while holding a lock — including indirectly via state.Load, which persists pending migrations through Update.

func QuarantineCorruptFile

func QuarantineCorruptFile(path string, cause error) error

QuarantineCorruptFile renames a corrupt file aside so the caller can recover with a clean in-memory value. Rename failures are returned as hard errors.

func WriteFileAtomic

func WriteFileAtomic(path string, data []byte, perm os.FileMode) error

Types

type RecoveryWarning

type RecoveryWarning struct {
	Path       string
	BackupPath string
	Cause      error
}

RecoveryWarning reports that a corrupt local persistence file was quarantined and the caller can continue with an empty in-memory store.

func (*RecoveryWarning) Error

func (w *RecoveryWarning) Error() string