job

type Env struct {
	Store backup.ObjectStore
	Index backup.Index
	// Key seals what runs upload; nil backs up in the clear.
	Key     *storekey.Key
	AgentID string
	// Logger is where runs report; nil means slog.Default.
	Logger *slog.Logger
	// Stderr, when set, takes the stderr of the programs and hooks runs
	// start as it comes; nil logs it through Logger line by line.
	Stderr io.Writer

	// StatCache lets Path skip re-reading files whose stat data match.
	StatCache *statcache.Cache
	// ObjectCache keeps the commits and trees Path diffs against.
	ObjectCache *badger.Store
	// TreeCache keeps the commits and trees PostgresReceive and MySQLReceive
	// read every commit.
	TreeCache *blobcache.Cache
	// BlobCache receives every blob Path uploads.
	BlobCache *blobcache.Cache
}

type Filter func(rel string) bool

type MySQLClient struct {
	// DefaultsExtraFile is the option file the programs read before their
	// own, for the connection and its password; empty reads ~/.my.cnf
	// alone.
	DefaultsExtraFile string
	Mysql             string
	Mysqldump         string
}

type MySQLDumpSettings struct {
	Set    string
	Client MySQLClient
	// BinlogSet is the set the server's binlogs go to, whose chain the dump
	// joins; empty when there is none.
	BinlogSet string
	// NoBinlogPosition records no binary log position even with log_bin
	// on, which spares the dump the global read lock.
	NoBinlogPosition bool
	// InitialRetention, when set, is the retention policy the set starts
	// with if this run creates it; a set that exists keeps its own.
	InitialRetention *retention.Policy
}

type MySQLReceiveSettings struct {
	Set string
	// DumpSet is the set the server's dumps go to.
	DumpSet string
	// Spool is where binlogs wait for their commit.
	Spool string
	// DefaultsExtraFile is the option file read before ~/.my.cnf for the
	// connection and its password.
	DefaultsExtraFile string
	// ServerID is the replica server id; mysql.ReplicaServerID of the set
	// when zero.
	ServerID    uint32
	CommitEvery time.Duration
	CommitBytes int64
	// Window is how far back point-in-time recovery reaches at least.
	Window time.Duration
	// InitialRetention, when set, is the retention policy the set starts
	// with if this run creates it; a set that exists keeps its own.
	InitialRetention *retention.Policy
	// UntilCaughtUp stops MySQLReceive once it has committed the binlog the
	// server had written when it started.
	UntilCaughtUp bool
}

type PathSettings struct {
	Set string
	// Dir is the directory to back up; on the local disk, relative to the
	// working directory when not absolute.
	Dir string
	// FS is the tree Dir is read from; nil means the local disk, and on
	// any other FS Dir is taken as that FS's path.
	FS backup.FS
	// Filters decide what is backed up: a path is when every filter keeps
	// it. Globs makes one from patterns.
	Filters []Filter
	// Unchanged, when set, reports directories known to be as in the set's
	// latest commit, everything under them included, such as from a change
	// journal; the walk takes them from that commit without reading them.
	// Filters must be the ones that commit was made with.
	Unchanged func(rel string) bool
	Workers   int
	// ForceHash is the percent of unchanged files re-hashed as a check.
	ForceHash int
	// Verify reads every file, changed or not.
	Verify             bool
	CheckpointInterval time.Duration
	ScanWorkers        int
	ReadRetries        int
	LostRetries        int
	// ProgressInterval is how often the walk reports; negative never.
	ProgressInterval time.Duration
	// Progress, when set, hears the walk's counters every ProgressInterval,
	// the default when it is not positive, and once more when it ends,
	// in place of the log line.
	Progress    func(backup.WalkResult)
	Meta        map[string]string
	PreHook     string
	PostHook    string
	HookTimeout time.Duration
	// HookOptional backs up anyway when the pre hook fails.
	HookOptional bool
	// VSS reads Dir from a shadow copy taken after the pre hook, on
	// Windows; when none can be taken, the live files are read.
	VSS bool
	// DownloadPlaceholders reads files a cloud sync client keeps only in
	// the cloud, which downloads them; otherwise they are recorded without
	// content.
	DownloadPlaceholders bool
	// InitialRetention, when set, is the retention policy the set starts
	// with if this run creates it; a set that exists keeps its own.
	InitialRetention *retention.Policy
}

type PostgresBaseSettings struct {
	Set string
	// DBName is the connection string pg_basebackup connects with; empty
	// leaves it to the PG* variables.
	DBName string
	// PGBasebackup, when set, is the pg_basebackup that takes the backup;
	// its major version must match the server's. When empty, the backup
	// is taken over a replication connection of its own from Postgres 15
	// on, and by the pg_basebackup on the PATH before.
	PGBasebackup string
	// InitialRetention, when set, is the retention policy the set starts
	// with if this run creates it; a set that exists keeps its own.
	InitialRetention *retention.Policy
}

type PostgresReceiveSettings struct {
	Set string
	// BaseSet is the set the cluster's base backups go to.
	BaseSet string
	// Spool is where WAL waits for its commit.
	Spool string
	// DBName is the connection string of the replication and monitoring
	// connections; empty leaves it to the PG* variables.
	DBName string
	// Slot is the replication slot; postgres.SlotName of the set when
	// empty.
	Slot string
	// AllowUncappedSlot streams when max_slot_wal_keep_size is -1.
	AllowUncappedSlot bool
	CommitEvery       time.Duration
	CommitBytes       int64
	// Window is how far back point-in-time recovery reaches at least.
	Window time.Duration
	// InitialRetention, when set, is the retention policy the set starts
	// with if this run creates it; a set that exists keeps its own.
	InitialRetention *retention.Policy
	// UntilCaughtUp stops PostgresReceive once it has committed the WAL the
	// server had flushed when it started.
	UntilCaughtUp bool
}