Help us shape the future of Go! Take the 2026 Go Developer Survey

backup

package
v2.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: BSD-3-Clause Imports: 37 Imported by: 0

Documentation

Overview

Package backup owns the shared Rustic backup engine used by volume and system backups: typed repository operations, per-repository serialization and run admission.

Index

Constants

View Source
const (
	VolumeAdmissionScope = "volume-backup"
	SystemAdmissionScope = "system-backup"
	// SystemAdmissionID is the one admission key system and system-managed volume backups share.
	SystemAdmissionID   = "system"
	RecoveryKeyConfigID = "system-recovery"
	// VolumeRoot is the S3 prefix under which each instance keeps its volume backup repository.
	VolumeRoot = "arcane-volume-backups"
)
View Source
const RemoteDisabledMessage = "S3 backup storage is missing. Remote backups were disabled; edit the policy to resume."

Variables

View Source
var (
	ErrRecoveryKeyNotConfigured = errors.New("recovery key is not configured")
	// ErrBackupSettled reports a checkpointed backup whose own attempt already failed it, so there is nothing to
	// resume; a retry starts a new backup instead.
	ErrBackupSettled = errors.New("the checkpointed backup already failed")

	// RecoveryKeyFormat is 8 hyphenated groups of 6 base32 characters, used verbatim as the Rustic password.
	RecoveryKeyFormat = regexp.MustCompile(`^[A-Z2-7]{6}(-[A-Z2-7]{6}){7}$`)
)
View Source
var ErrRemoteRepositoryMissing = errors.New("S3 backup storage is missing")

Functions

func AcceptedBackupID added in v2.16.0

func AcceptedBackupID(run scheduler.Run) string

AcceptedBackupID returns the backup a manual backup workflow's run owns, from its AcceptedTarget.

func AcceptedTarget added in v2.16.0

func AcceptedTarget(backupID string) scheduler.TargetOutcome

AcceptedTarget is the progress a manual backup's workflow starts with, so startup recovery protects its record from the moment the backup is accepted.

func CheckRemoteRepository added in v2.15.1

func CheckRemoteRepository(ctx context.Context, destinations *s3.S3DestinationService, destinationID, root string) (backup.RepositoryObservation, error)

CheckRemoteRepository probes the destination's repository config within a bounded budget. Transport and credential failures are returned as errors so callers never forget snapshots blindly.

func CheckScheduledRemote added in v2.11.0

func CheckScheduledRemote(ctx context.Context, db *database.DB, destinations *s3.S3DestinationService, table, destinationID, root string) error

CheckScheduledRemote permits first-use initialization, but detects lost repositories.

func DisableMissingRemote added in v2.16.0

func DisableMissingRemote(remoteErr error, localEnabled bool, s3Enabled, enabled *bool, save func(field string) (bool, error)) (bool, error)

DisableMissingRemote stops a scheduled policy from using S3 storage that went missing: a policy that also backs up locally loses S3, an S3-only one is disabled. save clears that field on the stored policy unless it changed since it was loaded, and reports whether it did; the loaded flags then follow. It reports whether S3 was turned off.

func DisableStoredRemote added in v2.16.0

func DisableStoredRemote(ctx context.Context, db *database.DB, model any, id, destinationID string, localEnabled bool, field string) (bool, error)

DisableStoredRemote is DisableMissingRemote's save for a policy table row, which it changes only while the row still matches the loaded policy.

func ExpiredRunIDs

func ExpiredRunIDs(ctx context.Context, db *database.DB, table, policyID string, keep int) ([]string, error)

ExpiredRunIDs returns the IDs of succeeded runs with snapshots that fall outside the newest keep entries for one policy, oldest last. Callers delete each run through their own delete path so snapshots are forgotten too.

func GenerateRecoveryKey added in v2.12.0

func GenerateRecoveryKey() (string, error)

GenerateRecoveryKey creates a random recovery key in RecoveryKeyFormat.

func NewRequester added in v2.16.0

func NewRequester(ctx context.Context, requestedBy user.Actor, environmentID, permission string) backup.Requester

NewRequester captures the user, and API key if any, behind a manual backup request.

func RemoteSnapshotChecker added in v2.11.0

func RemoteSnapshotChecker(ctx context.Context, destinations *s3.S3DestinationService) func(destinationID, root, snapshotID string) *bool

RemoteSnapshotChecker memoizes targeted checks within one response budget; each lookup names the repository root that holds the snapshot. A nil result means the remote copy could not be verified.

func RunSnapshotTag added in v2.15.0

func RunSnapshotTag(runID string) string

RunSnapshotTag links committed snapshots to their durable backup record.

func ValidatePolicyUpdate added in v2.10.0

func ValidatePolicyUpdate(ctx context.Context, domain string, update backup.UpdateBackupPolicy, s3Service *s3.S3DestinationService) (backup.UpdateBackupPolicy, error)

ValidatePolicyUpdate applies the shared cron, retention, and destination rules used by backup policies.

func ValidateRecoveryKey added in v2.12.0

func ValidateRecoveryKey(key string) error

ValidateRecoveryKey checks that a key has the generated recovery key format.

Types

type CreateSnapshotInput added in v2.13.1

type CreateSnapshotInput struct {
	Mounts  []mount.Mount
	Sources []string
	AsPath  string
	Tags    []string
	Globs   []string
}

CreateSnapshotInput describes what one snapshot captures: the mounts to attach to the helper and the helper paths to back up. AsPath rewrites the snapshot path of a single source and cannot combine with several.

func RootSnapshotInput added in v2.13.1

func RootSnapshotInput(source mount.Mount, tags ...string) CreateSnapshotInput

RootSnapshotInput captures one mount with its contents at the snapshot root.

type DiscoveredSnapshot

type DiscoveredSnapshot struct {
	ID      string    `json:"id"`
	Time    time.Time `json:"time"`
	Label   string    `json:"label"`
	Tags    []string  `json:"tags"`
	Summary struct {
		TotalBytesProcessed int64 `json:"total_bytes_processed"`
	} `json:"summary"`
}

DiscoveredSnapshot describes one snapshot found in a repository.

type Engine

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

Engine owns repository serialization and backup admission.

func NewEngine

func NewEngine(admission *runs.Admission, imageService *image.ImageService) *Engine

NewEngine builds the backup engine on the shared admission gate.

func (*Engine) AcquireRun added in v2.16.0

func (e *Engine) AcquireRun(ctx context.Context, scope, id, run string) (*runs.Lease, bool, error)

AcquireRun takes over the lease held for run, or acquires admission otherwise, such as after a restart. A lease parked for another run stays parked, so that run's task still finds its admission.

func (*Engine) Authorize added in v2.16.0

func (e *Engine) Authorize(ctx context.Context, requester backup.Requester) error

Authorize checks that the requester may still run the backup.

func (*Engine) ChangeRepositoryPassword added in v2.12.0

func (e *Engine) ChangeRepositoryPassword(ctx context.Context, dockerClient *client.Client, repository Repository, currentPassword, newPassword string) error

ChangeRepositoryPassword re-keys the repository; the scratch Rustic image has no shell, so the new password travels as an argument.

func (*Engine) ConfirmRunSnapshot added in v2.15.0

func (e *Engine) ConfirmRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, runID, snapshotID string) (Snapshot, error)

ConfirmRunSnapshot makes a validated snapshot discoverable by run ID.

func (*Engine) CreateSnapshot

func (e *Engine) CreateSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, label string, input CreateSnapshotInput) (Snapshot, error)

CreateSnapshot backs the input's sources up into the repository as one snapshot. The repository is initialized on first use.

func (*Engine) FindRunSnapshot added in v2.15.0

func (e *Engine) FindRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, runID, snapshotID string) (Snapshot, bool, error)

FindRunSnapshot verifies a known snapshot or recovers its committed response by run tag.

func (*Engine) ForgetSnapshots added in v2.10.0

func (e *Engine) ForgetSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, password string, snapshotIDs []string) error

ForgetSnapshots removes the snapshots and prunes their data in a single pass; with no IDs it only prunes, skipping an uninitialized repository.

func (*Engine) Hold added in v2.16.0

func (e *Engine) Hold(scope, id, run string, lease *runs.Lease) func(context.Context)

Hold parks a lease won by a manual start for run until that run's task takes it over with AcquireRun. The returned func releases the lease if the run never took it, such as a start that failed to submit.

func (*Engine) ListSnapshotFiles

func (e *Engine) ListSnapshotFiles(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID, filePath string, recursive bool) ([]string, error)

ListSnapshotFiles lists a snapshot path and returns paths relative to the snapshot root. A supplied path is nonrecursive unless recursive is true.

func (*Engine) ListSnapshots

func (e *Engine) ListSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, password string) ([]DiscoveredSnapshot, error)

ListSnapshots enumerates every snapshot in the repository.

func (*Engine) ReadSnapshotTextFile added in v2.10.0

func (e *Engine) ReadSnapshotTextFile(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID, filePath string) (string, error)

ReadSnapshotTextFile returns one text file from a snapshot.

func (*Engine) Replicate

func (e *Engine) Replicate(ctx context.Context, dockerClient *client.Client, from Repository, fromSnapshotID string, to Repository, password, label string, tags ...string) (Snapshot, error)

Replicate copies one snapshot into another repository through a temporary volume, never the live data. Rustic's native `copy` needs a TOML profile for the target, which the env-only Repository cannot express.

func (*Engine) RestoreSnapshot

func (e *Engine) RestoreSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID string, target mount.Mount, options RestoreOptions) error

RestoreSnapshot restores a snapshot (or one path inside it) onto the target mount.

func (*Engine) SetAuthorize added in v2.15.0

func (e *Engine) SetAuthorize(authorize func(context.Context, backup.Requester) error)

SetAuthorize sets the check Authorize applies to manual backup requesters.

func (*Engine) Stop

func (e *Engine) Stop(ctx context.Context) error

Stop releases leases that no workflow task took over.

func (*Engine) TryAcquireRun

func (e *Engine) TryAcquireRun(ctx context.Context, scope, id string) (*runs.Lease, bool, error)

TryAcquireRun takes the admission lease for one backup resource, reporting false while another run holds it.

type PolicyReconciliation

type PolicyReconciliation[P, U any] struct {
	// Domain names the backup flavor in validation errors ("volume", "system").
	Domain string
	DB     *database.DB
	// Existing is every policy currently persisted for the reconciled scope.
	Existing []P
	ID       func(*P) string
	UpdateID func(U) string
	// New returns the blank policy for created entries, pre-scoped by the
	// caller (e.g. with the volume name set).
	New func() P
	// Build validates an update and applies it to an existing or new policy.
	Build func(ctx context.Context, policy *P, update U) error
	// Persist overrides the default GORM transaction for settings-backed policies.
	Persist    func(ctx context.Context, policies []P) error
	Unregister func(ctx context.Context, policyID string)
	Reschedule func(ctx context.Context, policy *P)
}

PolicyReconciliation reconciles a full set of policy updates against the existing policies of one backup domain, then swaps the scheduled jobs.

func (PolicyReconciliation[P, U]) Run

func (r PolicyReconciliation[P, U]) Run(ctx context.Context, updates []U) error

Run applies updates as the full policy set: it saves them, removes the rest, and reschedules their jobs.

type RecoveryKeyStore added in v2.12.0

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

RecoveryKeyStore persists the recovery key shared by the system and volume backup domains.

func NewRecoveryKeyStore added in v2.12.0

func NewRecoveryKeyStore(db *database.DB) *RecoveryKeyStore

NewRecoveryKeyStore builds the recovery key store.

func (*RecoveryKeyStore) Configured added in v2.12.0

func (s *RecoveryKeyStore) Configured(ctx context.Context) (bool, error)

Configured reports whether a recovery key is stored.

func (*RecoveryKeyStore) Get added in v2.12.0

func (s *RecoveryKeyStore) Get(ctx context.Context) (string, error)

Get returns the decrypted recovery key or ErrRecoveryKeyNotConfigured.

func (*RecoveryKeyStore) HoldRunKey added in v2.16.0

func (s *RecoveryKeyStore) HoldRunKey(ctx context.Context, runID, recoveryKey string) error

HoldRunKey keeps a recovery key entered for one backup run, encrypted, until ReleaseRunKey, so the run can resume after a restart without it ever entering the run's workflow payload.

func (*RecoveryKeyStore) ReleaseRunKey added in v2.16.0

func (s *RecoveryKeyStore) ReleaseRunKey(ctx context.Context, runID string) error

ReleaseRunKey forgets the key held for a run.

func (*RecoveryKeyStore) RunKey added in v2.16.0

func (s *RecoveryKeyStore) RunKey(ctx context.Context, runID string) (string, error)

RunKey returns the key held for a run, or "" when none is.

func (*RecoveryKeyStore) Set added in v2.12.0

func (s *RecoveryKeyStore) Set(ctx context.Context, recoveryKey string) error

Set validates and stores the recovery key, encrypted.

type Repository

type Repository struct {
	ID          string
	Environment []string
	Mounts      []mount.Mount
}

type RestoreOptions

type RestoreOptions struct {
	// DeleteExtra removes files in the target that are absent from the snapshot.
	DeleteExtra bool
	// SourcePath restores only this path inside the snapshot when non-empty.
	SourcePath string
	// DestinationPath overrides the restore target path inside the helper
	// container; the target mount's path is used when empty.
	DestinationPath string
	// ExtraMounts are attached alongside the target, e.g. mounts nested inside it.
	ExtraMounts []mount.Mount
}

RestoreOptions selects what a snapshot restore writes and where.

type Snapshot

type Snapshot struct {
	ID   string `json:"id"`
	Size int64  `json:"-"`
}

type SystemBackupRecoveryConfig added in v2.12.0

type SystemBackupRecoveryConfig struct {
	database.BaseModel

	EncryptedRecoveryKey string `gorm:"column:encrypted_recovery_key;type:text;not null"`
}

SystemBackupRecoveryConfig stores the encrypted recovery key; it must be reversible because Rustic needs the plaintext.

func (SystemBackupRecoveryConfig) TableName added in v2.12.0

func (SystemBackupRecoveryConfig) TableName() string

TableName is the recovery key table.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL