agent

type Agent struct {
	// ID is the agent id runs commit as; it also picks each task's jitter.
	ID string
	// Settings and Caches name the store and the caches every run shares,
	// which the agent opens when Open is nil; ID, when set, is the agent id.
	Settings goback.Settings
	Caches   goback.Caches
	// Open opens the store, the index, the key and the caches that every
	// run shares. The agent retries it with backoff until it works. When
	// Open is nil, the agent opens Settings, and a nil Close and AfterRun
	// close it and run job.AfterRun.
	Open func(ctx context.Context) (*job.Env, error)
	// Close closes what Open opened, once every run has ended.
	Close func(env *job.Env)
	// AfterRun runs after each run, never two at once: compaction and cache
	// sweeps.
	AfterRun func(ctx context.Context, env *job.Env)
	// Concurrency is the most tasks running at once, log tasks aside.
	Concurrency int
	// Grace is how long running tasks get once Run's ctx ends, before they
	// are cancelled.
	Grace time.Duration
	// StateDir is where the status file goes; empty writes none.
	StateDir string
	Logger   *slog.Logger
	// Now is the wall clock; nil is time.Now.
	Now func() time.Time
	// contains filtered or unexported fields
}

type Backup struct {
	// Name is the set a path backup writes, and the group a database
	// backup's sets go under; slashes nest it in groups, as in srv1/db.
	Name string `yaml:"name"`
	// Every and Cron say when full backups run; the kind's default when
	// both are empty.
	Every time.Duration `yaml:"every"`
	Cron  string        `yaml:"cron"`
	// Jitter moves every full backup of this agent's backup by the same
	// offset inside [0, Jitter).
	Jitter time.Duration `yaml:"jitter"`
	// Timeout cancels a full backup run after this long; zero never does.
	Timeout time.Duration `yaml:"timeout"`

	Path     *PathBackup     `yaml:"path"`
	Postgres *PostgresBackup `yaml:"postgres"`
	MySQL    *MySQLBackup    `yaml:"mysql"`
}

type Checked struct {
	Jobs      []Planned       `json:"jobs"`
	Databases []DatabaseCheck `json:"databases"`
}

type Config struct {
	Store    Store    `yaml:"store"`
	Schedule Schedule `yaml:"schedule"`
	Backups  []Backup `yaml:"backups"`
}

type Control struct {
	// contains filtered or unexported fields
}

type DatabaseCheck struct {
	Backup   string   `json:"backup"`
	Problems []string `json:"problems"`
}

type JobStatus struct {
	Name   string `json:"name"`
	Backup string `json:"backup"`
	Set    string `json:"set"`
	Kind   string `json:"kind"`
	// State is planning, blocked, waiting, idle or running.
	State       string    `json:"state"`
	LastStart   time.Time `json:"last_start,omitzero"`
	LastResult  string    `json:"last_result,omitempty"`
	LastError   string    `json:"last_error,omitempty"`
	LastSuccess time.Time `json:"last_success,omitzero"`
	LastCommit  string    `json:"last_commit,omitempty"`
	Failures    int       `json:"failures"`
	NextDue     time.Time `json:"next_due,omitzero"`
	// StaleAfter is how long without a success makes the job unhealthy.
	StaleAfter int64 `json:"stale_after_seconds,omitempty"`
	// Details are what a long-running task last reported about itself.
	Details any `json:"details,omitempty"`
}

type MySQLBackup struct {
	DefaultsExtraFile string `yaml:"defaults-extra-file"`
	Mysql             string `yaml:"mysql"`
	Mysqldump         string `yaml:"mysqldump"`
	// Spool is where binlogs wait for their commit; <state-dir>/spool/<set>
	// when empty.
	Spool       string        `yaml:"spool"`
	ServerID    uint32        `yaml:"server-id"`
	CommitEvery time.Duration `yaml:"commit-every"`
	CommitBytes string        `yaml:"commit-bytes"`
	Window      time.Duration `yaml:"window"`
	PITR        bool          `yaml:"pitr"`
	// NoBinlogPosition, with pitr off, has dumps record no binlog position,
	// which spares them the global read lock.
	NoBinlogPosition bool `yaml:"no-binlog-position"`
}

type PathBackup struct {
	Dir                string            `yaml:"dir"`
	Include            []string          `yaml:"include"`
	Exclude            []string          `yaml:"exclude"`
	Workers            int               `yaml:"workers"`
	ForceHash          int               `yaml:"force-hash"`
	CheckpointInterval time.Duration     `yaml:"checkpoint-interval"`
	ScanWorkers        int               `yaml:"scan-workers"`
	ReadRetries        int               `yaml:"read-retries"`
	LostRetries        int               `yaml:"lost-retries"`
	ProgressInterval   time.Duration     `yaml:"progress-interval"`
	Meta               map[string]string `yaml:"meta"`
	PreHook            string            `yaml:"pre-hook"`
	PostHook           string            `yaml:"post-hook"`
	HookTimeout        time.Duration     `yaml:"hook-timeout"`
	HookOptional       bool              `yaml:"hook-optional"`
}

type Plan struct {
	// contains filtered or unexported fields
}

type Planned struct {
	Name   string `json:"name"`
	Backup string `json:"backup"`
	Set    string `json:"set"`
	Kind   string `json:"kind"`
	// Plan is the task's schedule, "always" for one that runs all the time.
	Plan    string    `json:"plan"`
	LastRun time.Time `json:"last_run,omitzero"`
	NextDue time.Time `json:"next_due,omitzero"`
}

type PostgresBackup struct {
	DBName       string `yaml:"dbname"`
	PGBasebackup string `yaml:"pg-basebackup"`
	// Spool is where WAL waits for its commit; <state-dir>/spool/<set>
	// when empty.
	Spool             string        `yaml:"spool"`
	Slot              string        `yaml:"slot"`
	CommitEvery       time.Duration `yaml:"commit-every"`
	CommitBytes       string        `yaml:"commit-bytes"`
	AllowUncappedSlot bool          `yaml:"allow-uncapped-slot"`
	Window            time.Duration `yaml:"window"`
	PITR              bool          `yaml:"pitr"`
}

type RunFunc func(ctx context.Context, env *job.Env) (*backup.WalkResult, error)

type Schedule struct {
	// Concurrency is the most full backups running at once; log capture
	// doesn't count.
	Concurrency int `yaml:"concurrency"`
	// ShutdownGrace is how long running backups get after SIGTERM.
	ShutdownGrace time.Duration `yaml:"shutdown-grace"`
	// StateDir holds the status file and the lock; <cache-dir>/schedule
	// when empty.
	StateDir string `yaml:"state-dir"`
}

type ServeFunc func(ctx context.Context, env *job.Env, c *Control) error

type Status struct {
	PID       int         `json:"pid"`
	State     string      `json:"state"`
	StartedAt time.Time   `json:"started_at"`
	UpdatedAt time.Time   `json:"updated_at"`
	Jobs      []JobStatus `json:"jobs"`
}

type Store struct {
	Storage           string `yaml:"storage"`
	Index             string `yaml:"index"`
	StoreKey          string `yaml:"store-key"`
	AtRestKey         string `yaml:"at-rest-key"`
	PassphraseFile    string `yaml:"passphrase-file"`
	AgentID           string `yaml:"agent-id"`
	CacheDir          string `yaml:"cache-dir"`
	MetadataCacheSize string `yaml:"metadata-cache-size"`
	BlobCacheSize     string `yaml:"blob-cache-size"`
	BlobCacheOnBackup *bool  `yaml:"blob-cache-on-backup"`
}

type Task struct {
	// Name is unique among an agent's tasks; it names the task in logs,
	// the status file and metrics.
	Name   string
	Set    string
	Kind   string
	Backup string
	Plan   *Plan
	// Jitter is the window the task's slots move by a fixed offset in.
	Jitter time.Duration
	// Timeout cancels a run after this long; zero never does.
	Timeout time.Duration
	// StaleAfter is how long a Serve task may go without reporting itself
	// healthy before it counts as unhealthy; zero never judges it.
	StaleAfter time.Duration
	// Log marks log capture, which runs outside the concurrency limit.
	Log bool
	// After names a set that must hold a complete commit before the task
	// starts.
	After string
	// Spec is what the task was built from; a reload replaces a task whose
	// Spec changed.
	Spec  string
	Run   RunFunc
	Serve ServeFunc
}