Documentation
¶
Index ¶
- Constants
- Variables
- func NormalizeAgentType(t string) (string, bool)
- func ValidateBackupPaths(paths []string) ([]string, error)
- func ValidateCron(expr string) error
- func ValidateExcludePatterns(patterns []string) error
- type APIKey
- type Agent
- type AgentAuthState
- type AgentStatus
- type BackupJob
- type BackupRun
- type BackupTarget
- type DB
- func (d *DB) BumpAgentTokenVersion(ctx context.Context, id uuid.UUID) (int, error)
- func (d *DB) Close()
- func (d *DB) CreateAPIKey(ctx context.Context, key *APIKey) error
- func (d *DB) CreateAgent(ctx context.Context, agent *Agent) error
- func (d *DB) CreateEnrollmentToken(ctx context.Context, token *EnrollmentToken) error
- func (d *DB) CreateJob(ctx context.Context, job *BackupJob) error
- func (d *DB) CreateRun(ctx context.Context, run *BackupRun) error
- func (d *DB) CreateTarget(ctx context.Context, target *BackupTarget) error
- func (d *DB) DeleteAgent(ctx context.Context, id uuid.UUID) error
- func (d *DB) DeleteEnrollmentToken(ctx context.Context, id uuid.UUID) error
- func (d *DB) DeleteJob(ctx context.Context, id uuid.UUID) error
- func (d *DB) DeleteTarget(ctx context.Context, id uuid.UUID) error
- func (d *DB) GetAPIKeyByHash(ctx context.Context, hash string) (*APIKey, error)
- func (d *DB) GetAgentAuthState(ctx context.Context, id uuid.UUID) (*AgentAuthState, error)
- func (d *DB) GetAgentByID(ctx context.Context, id uuid.UUID) (*Agent, error)
- func (d *DB) GetJobByID(ctx context.Context, id uuid.UUID) (*BackupJob, error)
- func (d *DB) GetRunByID(ctx context.Context, id uuid.UUID) (*BackupRun, error)
- func (d *DB) GetRunByWorkflowID(ctx context.Context, workflowID string) (*BackupRun, error)
- func (d *DB) GetTargetByID(ctx context.Context, id uuid.UUID) (*BackupTarget, error)
- func (d *DB) ListAPIKeys(ctx context.Context) ([]*APIKey, error)
- func (d *DB) ListAgents(ctx context.Context) ([]*Agent, error)
- func (d *DB) ListEnrollmentTokens(ctx context.Context) ([]*EnrollmentToken, error)
- func (d *DB) ListJobs(ctx context.Context) ([]*BackupJob, error)
- func (d *DB) ListRuns(ctx context.Context, limit int) ([]*BackupRun, error)
- func (d *DB) ListTargets(ctx context.Context) ([]*BackupTarget, error)
- func (d *DB) MarkRunStarted(ctx context.Context, id uuid.UUID, temporalRunID string, startedAt time.Time) error
- func (d *DB) Migrate(ctx context.Context) error
- func (d *DB) RevokeAPIKey(ctx context.Context, id uuid.UUID) error
- func (d *DB) RevokeAgent(ctx context.Context, id uuid.UUID) error
- func (d *DB) SetAgentDebugLogging(ctx context.Context, id uuid.UUID, enabled bool) error
- func (d *DB) SetRunStatus(ctx context.Context, id uuid.UUID, status RunStatus, message string, ...) error
- func (d *DB) TouchAPIKey(ctx context.Context, id uuid.UUID) error
- func (d *DB) UpdateAgentHeartbeat(ctx context.Context, id uuid.UUID, status AgentStatus) (bool, error)
- func (d *DB) UpdateJob(ctx context.Context, job *BackupJob) error
- func (d *DB) UpdateRun(ctx context.Context, run *BackupRun) error
- func (d *DB) UpsertAgent(ctx context.Context, agent *Agent) error
- func (d *DB) ValidateAndConsumeToken(ctx context.Context, tokenHash string) (*EnrollmentToken, error)
- type EnrollmentToken
- type Migration
- type RetentionPolicy
- type RunStatus
Constants ¶
const ( AgentTypeFilesystem = config.AgentTypeFilesystem AgentTypeDatabase = config.AgentTypeDatabase JobTypeFilesystem = config.AgentTypeFilesystem JobTypeDatabase = config.AgentTypeDatabase )
Agent / job types: each agent binary handles one kind of job
const ( PxarFormatV1 = "v1" // single stream + catalog; browsable everywhere PxarFormatV2 = "v2" // split metadata/payload streams; PBS 3.2+ )
pxar archive formats a target accepts
Variables ¶
var (
ErrNotFound = errors.New("record not found")
)
Functions ¶
func NormalizeAgentType ¶ added in v0.6.0
NormalizeAgentType maps "" to filesystem and reports unknown values
func ValidateBackupPaths ¶ added in v0.6.0
ValidateBackupPaths normalises a job's backup paths and rejects combinations that cannot form one archive: every path must be absolute, exact duplicates are dropped and no path may lie inside another (its data would be archived twice). Paths sharing a basename are fine; the agent names them after their full path in the archive.
func ValidateCron ¶ added in v0.6.2
ValidateCron rejects schedule expressions the scheduler cannot run; empty = manual
func ValidateExcludePatterns ¶ added in v0.6.0
ValidateExcludePatterns checks exclude patterns against the pxar pattern syntax (proxmox-backup-client --exclude); invalid patterns would otherwise fail the backup only at run time on the agent.
Types ¶
type APIKey ¶
type APIKey struct {
ID uuid.UUID `json:"id"`
Name string `json:"name"`
KeyHash string `json:"-"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
LastUsedAt *time.Time `json:"last_used_at"`
ExpiresAt *time.Time `json:"expires_at"`
RevokedAt *time.Time `json:"revoked_at"`
}
APIKey is an admin credential for fallbck-ctl and scripts. The raw key is never stored.
type Agent ¶
type Agent struct {
ID uuid.UUID `json:"id" db:"id"`
Hostname string `json:"hostname" db:"hostname"`
IPAddress string `json:"ip_address" db:"ip_address"`
OS string `json:"os" db:"os"`
Arch string `json:"arch" db:"arch"`
Version string `json:"version" db:"version"`
AgentType string `json:"agent_type" db:"agent_type"`
TaskQueue string `json:"task_queue" db:"task_queue"`
// DebugLogging raises the agent's log level to debug (applied via heartbeats)
DebugLogging bool `json:"debug_logging" db:"debug_logging"`
Status AgentStatus `json:"status" db:"status"`
LastSeenAt *time.Time `json:"last_seen_at" db:"last_seen_at"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}
Agent represents a registered backup agent host
type AgentAuthState ¶
AgentAuthState is the subset of agent state needed to validate an agent bearer token
type AgentStatus ¶
type AgentStatus string
AgentStatus represents the lifecycle state of an agent
const ( AgentStatusOnline AgentStatus = "online" AgentStatusOffline AgentStatus = "offline" AgentStatusBusy AgentStatus = "busy" AgentStatusError AgentStatus = "error" )
type BackupJob ¶
type BackupJob struct {
ID uuid.UUID `json:"id" db:"id"`
Name string `json:"name" db:"name"`
AgentID uuid.UUID `json:"agent_id" db:"agent_id"`
TargetID uuid.UUID `json:"target_id" db:"target_id"`
ScheduleCron string `json:"schedule_cron" db:"schedule_cron"`
BackupPaths []string `json:"backup_paths" db:"backup_paths"`
ExcludePaths []string `json:"exclude_paths" db:"exclude_paths"`
RetentionPolicy RetentionPolicy `json:"retention_policy" db:"retention_policy"`
Enabled bool `json:"enabled" db:"enabled"`
// DirectPBS makes the agent talk to PBS itself (credentials handed out per run)
// instead of through the server-side tunnel. Server-side setting only.
DirectPBS bool `json:"direct_pbs" db:"direct_pbs"`
// JobType is filesystem (BackupPaths) or database (DBConfig)
JobType string `json:"job_type" db:"job_type"`
// DBConfig is the database job specification; the password is stored but never
// returned by the API (see Sanitize)
DBConfig *dbbackup.Spec `json:"db_config,omitempty" db:"db_config"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
// Joined fields for display
AgentName string `json:"agent_name,omitempty"`
TargetName string `json:"target_name,omitempty"`
}
BackupJob defines what, when, and where an agent backs up
func (*BackupJob) IsDatabase ¶ added in v0.6.0
IsDatabase reports whether the job is a database backup
func (*BackupJob) NextRunString ¶ added in v0.6.2
NextRunString reports when the schedule fires next (UTC), for display; empty when the job is manual, disabled, or the expression does not parse.
type BackupRun ¶
type BackupRun struct {
ID uuid.UUID `json:"id" db:"id"`
JobID uuid.UUID `json:"job_id" db:"job_id"`
AgentID uuid.UUID `json:"agent_id" db:"agent_id"`
TargetID uuid.UUID `json:"target_id" db:"target_id"`
WorkflowID string `json:"workflow_id" db:"workflow_id"`
RunID string `json:"run_id" db:"run_id"`
Status RunStatus `json:"status" db:"status"`
StartTime *time.Time `json:"start_time" db:"start_time"`
EndTime *time.Time `json:"end_time" db:"end_time"`
BytesScanned int64 `json:"bytes_scanned" db:"bytes_scanned"`
BytesUploaded int64 `json:"bytes_uploaded" db:"bytes_uploaded"`
DedupRatio float64 `json:"dedup_ratio" db:"dedup_ratio"`
ChunkCount int `json:"chunk_count" db:"chunk_count"`
ErrorMessage string `json:"error_message" db:"error_message"`
PBSSnapshotID string `json:"pbs_snapshot_id" db:"pbs_snapshot_id"`
// LogTail is the agent's recent log output captured when the run failed
LogTail string `json:"log_tail,omitempty" db:"log_tail"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
// Joined fields
JobName string `json:"job_name,omitempty"`
AgentName string `json:"agent_name,omitempty"`
}
BackupRun records a single execution of a backup job
func (*BackupRun) DurationString ¶ added in v0.6.0
DurationString renders how long the run took (or has been running); "-" before start
type BackupTarget ¶
type BackupTarget struct {
ID uuid.UUID `json:"id" db:"id"`
Name string `json:"name" db:"name"`
TargetType string `json:"target_type" db:"target_type"` // "pbs"
Endpoint string `json:"endpoint" db:"endpoint"`
Datastore string `json:"datastore" db:"datastore"`
Namespace string `json:"namespace" db:"namespace"`
AuthTokenEncrypted string `json:"-" db:"auth_token_encrypted"`
Fingerprint string `json:"fingerprint" db:"fingerprint"`
TLSVerify bool `json:"tls_verify" db:"tls_verify"`
PxarFormat string `json:"pxar_format" db:"pxar_format"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
// HasToken reports whether an API token is stored (the token itself is never returned)
HasToken bool `json:"has_token" db:"-"`
}
BackupTarget represents a remote backup repository such as Proxmox Backup Server
func (*BackupTarget) Sanitize ¶ added in v0.6.0
func (t *BackupTarget) Sanitize() *BackupTarget
Sanitize fills derived, API-safe fields
type DB ¶
DB wraps the pgx connection pool and exposes repository operations
func (*DB) BumpAgentTokenVersion ¶
BumpAgentTokenVersion invalidates every previously issued token for the agent and returns the new version that must be embedded in freshly issued tokens.
func (*DB) CreateEnrollmentToken ¶
func (d *DB) CreateEnrollmentToken(ctx context.Context, token *EnrollmentToken) error
func (*DB) CreateTarget ¶
func (d *DB) CreateTarget(ctx context.Context, target *BackupTarget) error
func (*DB) DeleteEnrollmentToken ¶ added in v0.6.0
DeleteEnrollmentToken invalidates a token immediately (enrollment looks tokens up by hash, so a deleted row can never be consumed again)
func (*DB) GetAPIKeyByHash ¶
func (*DB) GetAgentAuthState ¶
GetAgentAuthState returns the token version and revocation state of an agent. Returns ErrNotFound if the agent does not exist (e.g. it was deleted).
func (*DB) GetAgentByID ¶
func (*DB) GetJobByID ¶
func (*DB) GetRunByID ¶ added in v0.3.1
GetRunByID returns a single run
func (*DB) GetRunByWorkflowID ¶ added in v0.3.1
GetRunByWorkflowID returns the run record created for a Temporal workflow execution
func (*DB) GetTargetByID ¶
func (*DB) ListEnrollmentTokens ¶
func (d *DB) ListEnrollmentTokens(ctx context.Context) ([]*EnrollmentToken, error)
func (*DB) ListTargets ¶
func (d *DB) ListTargets(ctx context.Context) ([]*BackupTarget, error)
func (*DB) MarkRunStarted ¶ added in v0.3.1
func (d *DB) MarkRunStarted(ctx context.Context, id uuid.UUID, temporalRunID string, startedAt time.Time) error
MarkRunStarted moves a pending run to running once the workflow has prepared the session
func (*DB) Migrate ¶
Migrate applies all pending schema migrations to PostgreSQL. Each migration runs in its own transaction and is recorded in schema_migrations so it is applied exactly once.
func (*DB) RevokeAgent ¶
RevokeAgent marks the agent as revoked; its tokens stop validating immediately
func (*DB) SetAgentDebugLogging ¶ added in v0.6.2
SetAgentDebugLogging flips the per-agent debug toggle (delivered on the next heartbeat)
func (*DB) SetRunStatus ¶ added in v0.3.1
func (d *DB) SetRunStatus(ctx context.Context, id uuid.UUID, status RunStatus, message string, endTime *time.Time) error
SetRunStatus updates the status (and optionally end time / message) of a run
func (*DB) TouchAPIKey ¶
TouchAPIKey records the last use of a key (best-effort, called on successful auth)
func (*DB) UpdateAgentHeartbeat ¶
func (d *DB) UpdateAgentHeartbeat(ctx context.Context, id uuid.UUID, status AgentStatus) (bool, error)
UpdateAgentHeartbeat records the heartbeat and returns the agent's remote debug-logging setting for the response.
func (*DB) ValidateAndConsumeToken ¶
type EnrollmentToken ¶
type EnrollmentToken struct {
ID uuid.UUID `json:"id" db:"id"`
TokenHash string `json:"-" db:"token_hash"`
Name string `json:"name" db:"name"`
MaxUses int `json:"max_uses" db:"max_uses"`
UsesCount int `json:"uses_count" db:"uses_count"`
ExpiresAt time.Time `json:"expires_at" db:"expires_at"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
}
EnrollmentToken represents a one-time or multi-use token for agent onboarding
func (*EnrollmentToken) Status ¶ added in v0.6.0
func (t *EnrollmentToken) Status() string
Status describes whether the token can still be used
type Migration ¶
Migration is a single embedded SQL migration file
func LoadMigrations ¶
LoadMigrations returns the embedded migrations ordered by version. Files are named NNN_description.sql; the numeric prefix is the version.
type RetentionPolicy ¶
type RetentionPolicy struct {
KeepLast int `json:"keep_last"`
KeepDaily int `json:"keep_daily"`
KeepWeekly int `json:"keep_weekly"`
KeepMonthly int `json:"keep_monthly"`
KeepYearly int `json:"keep_yearly"`
}
RetentionPolicy defines backup retention counts
func (RetentionPolicy) ToJSON ¶
func (r RetentionPolicy) ToJSON() []byte
Helper to serialize RetentionPolicy to JSON bytes
type RunStatus ¶
type RunStatus string
RunStatus represents the state of a backup run
const ( RunStatusPending RunStatus = "pending" RunStatusRunning RunStatus = "running" RunStatusCompleted RunStatus = "completed" RunStatusFailed RunStatus = "failed" // RunStatusCancelling: cancellation requested, waiting for the agent to stop RunStatusCancelling RunStatus = "cancelling" RunStatusCancelled RunStatus = "cancelled" )