dbbackup

type Binary struct {
	Path    string
	Version string
	Major   int
	Minor   int
	Patch   int
	// Flavor distinguishes mysql/mariadb tools
	Flavor string
}

type Command struct {
	// Name is the logical tool name for logs and errors
	Name   string
	Path   string
	Args   []string
	Env    []string
	Dir    string
	Stdout io.Writer
	// RunAs names the OS user to run the tool as (peer / socket authentication on the
	// database host); "" keeps the agent's own user. Unix only; the agent must be root.
	RunAs string
	// Secrets are masked in everything the tool writes to stderr before it reaches
	// error messages or the agent log (mongodump echoes its URI, password included)
	Secrets []string
}

type DetectResult struct {
	Engine string
	Tools  ToolInfo
	Err    error
}

type DumpRequest struct {
	RunID string
	JobID string
	Label string
	Spec  *dbspec.Spec
	Creds dbspec.Credentials
	Tools ToolInfo
	// Server is filled by Precheck
	Server ServerInfo
	// Databases is the resolved list to dump (filled by Precheck; nil = all-in-one dump)
	Databases []string
	// SpoolDir exists and is empty on entry; SecretDir (0700) holds credential files
	SpoolDir  string
	SecretDir string
	// Snapshot is the PBS snapshot this run writes (type/id/time); engines that keep
	// a chain record it so later runs can point back at it
	Snapshot string
	// PrevState is the last successful run's state (nil on the first run)
	PrevState *dbspec.JobState
	Progress  ProgressFunc
	Runner    Runner
}

type Engine interface {
	Name() string
	// Detect finds the client binaries and their versions; it never contacts a server
	Detect(ctx context.Context, r Runner, tools dbspec.ToolConfig) (ToolInfo, error)
	// Precheck connects to the server and verifies versions, privileges and options
	// the dump would otherwise fail on late; configuration problems are *PrecheckError
	Precheck(ctx context.Context, req *DumpRequest) (ServerInfo, error)
	// Dump writes everything for this run under req.SpoolDir
	Dump(ctx context.Context, req *DumpRequest) (*EngineResult, error)
}

type EngineResult struct {
	ConsistentAsOf time.Time
	Databases      []dbspec.DatabaseEntry
	Warnings       []string
	Notes          []string
	Postgres       *dbspec.PostgresManifest
	MySQL          *dbspec.MySQLManifest
	MongoDB        *dbspec.MongoManifest
	MSSQL          *dbspec.MSSQLManifest
	Restore        dbspec.Restore
	// State is the engine part of the job state saved after a successful upload
	State *dbspec.JobStateRecord
}

type FileStateStore struct{ Dir string }

type MemoryStateStore struct {
	Prev  *dbspec.JobState
	Saved *dbspec.JobState
}

type PrecheckError struct {
	Msg  string
	Hint string
	Err  error
}

type Progress struct {
	// Phase: detect, precheck, dump, basebackup, binlog, manifest, upload
	Phase string
	// Current names the database/file being processed
	Current      string
	BytesInSpool int64
}

type ProgressFunc func(Progress)

type Result struct {
	ExitCode int
	Stderr   string
	Duration time.Duration
}

type RunOptions struct {
	Session *temporal.BackupSessionInfo
	Spec    *dbspec.Spec
	// Password is the server-stored job password ("" = resolve from an agent profile)
	Password string
	Config   dbspec.Config
	Upload   UploadFunc
	Progress ProgressFunc
	// Runner overrides the process runner (tests)
	Runner       Runner
	Hostname     string
	AgentVersion string
	// PollInterval overrides the spool poll interval (tests)
	PollInterval time.Duration
	// State overrides where the job's chain state is read and written (default: JSON
	// files under Config.StateDir)
	State StateStore
	// Generator names the agent in the manifest (default fallbck-agent)
	Generator string
}

type Runner interface {
	Run(ctx context.Context, c Command) (Result, error)
	LookPath(name string) (string, error)
}

type ServerInfo struct {
	Version    string
	VersionNum int
	Flavor     string
	IsReplica  bool
	// EstimatedBytes of the dump (0 = unknown)
	EstimatedBytes int64
	// Superuser reports whether the backup role is a superuser (PostgreSQL)
	Superuser bool
	// Attrs carries engine-specific server facts needed by Dump (binlog state, gtid mode)
	Attrs map[string]string
	Notes []string
}

type ServerVersion struct {
	Major   int
	Flavor  string // postgres, mysql, mariadb
	Version string
}

type StateStore interface {
	// Load returns the job state or nil when none exists
	Load(ctx context.Context, jobID string) (*dbspec.JobState, error)
	Save(ctx context.Context, jobID string, st *dbspec.JobState) error
}

type ToolError struct {
	Tool     string
	ExitCode int
	Stderr   string
	// Hint explains known failure messages; Config marks configuration problems
	Hint   string
	Config bool
}

type ToolInfo struct {
	// Binaries by logical name (pg_dump, pg_dumpall, pg_basebackup; dump, binlog; mongodump)
	Binaries map[string]Binary
	// Alternatives are complete tool sets found in other well-known directories
	// (several PostgreSQL majors installed side by side); Precheck may switch to one
	Alternatives []map[string]Binary
}

type UploadFunc func(ctx context.Context, spoolDir string, blobs []gopbs.Blob) (*temporal.BackupExecutionResult, error)