backup

Documentation

Overview

Package backup implements the backup engine for doomsday. It orchestrates walking the filesystem, chunking files, deduplicating, compressing, encrypting, packing, and saving snapshots.

Index

• func DryRunPaths(ctx context.Context, opts Options) ([]string, error)
• func Run(ctx context.Context, r *repo.Repository, opts Options) (*snapshot.Snapshot, error)
• type DryRunResult
  • func DryRun(ctx context.Context, opts Options) (*DryRunResult, error)
• type Options
• type ProgressFunc
• type SourceOptions
• type Stats

Functions

func DryRunPaths

func DryRunPaths(ctx context.Context, opts Options) ([]string, error)

DryRunPaths returns the list of filesystem paths that would be included in a backup, applying the exclusion patterns.

func Run

func Run(ctx context.Context, r *repo.Repository, opts Options) (*snapshot.Snapshot, error)

Run executes a backup and returns the resulting snapshot.

Pipeline:

1. Walk filesystem, producing file entries
2. For each file: read -> chunk (FastCDC) -> for each chunk: dedup check -> compress -> encrypt -> pack
3. Accumulate blobs in packer. When packer is full (~16 MiB), flush pack via repo.SavePack
4. Build tree blobs for directory structure
5. Create snapshot metadata, save it

Types

type DryRunResult

type DryRunResult struct {
	FilesTotal int64 // total regular files discovered
	DirsTotal  int64 // total directories discovered
	BytesTotal int64 // total size of regular files in bytes
	Errors     int64 // files/dirs that couldn't be read
}

DryRunResult holds the results of a dry-run backup scan.

func DryRun

func DryRun(ctx context.Context, opts Options) (*DryRunResult, error)

DryRun walks the filesystem and reports what would be backed up, without reading file contents or writing to any repository.

type Options

type Options struct {
	// Paths is the list of filesystem paths to back up.
	Paths []string
	// Excludes is a list of global glob patterns to exclude.
	Excludes []string
	// PerSource is optional per-path configuration. Keys are cleaned absolute paths.
	// Per-source excludes are merged with global Excludes for that specific root.
	PerSource map[string]SourceOptions
	// ConfigName is the name of the backup configuration (stored in snapshot).
	ConfigName string
	// Hostname is the machine hostname (stored in snapshot).
	Hostname string
	// CompressionLevel is the zstd compression level (0 = default).
	CompressionLevel int
	// OnProgress is called periodically with backup statistics.
	OnProgress ProgressFunc
	// Tags are optional tags stored in the snapshot.
	Tags []string
	// FileSaverWorkers controls the number of concurrent file processing goroutines.
	// Default: 2.
	FileSaverWorkers int
	// DryRun walks and chunks files but does not write any data to the repository.
	// The returned snapshot will have accurate stats but is not persisted.
	DryRun bool
}

Options configures a backup run.

type ProgressFunc

type ProgressFunc func(Stats)

ProgressFunc is called periodically during backup to report progress. Implementations must be safe for concurrent use.

type SourceOptions

type SourceOptions struct {
	// Excludes is additional exclude patterns for this source (merged with global).
	Excludes []string
	// OneFilesystem prevents crossing filesystem boundaries for this source.
	OneFilesystem bool
}

SourceOptions holds per-source configuration for the backup.

type Stats

type Stats struct {
	// Filesystem walk
	FilesTotal     int64 // total files discovered by walker
	DirsTotal      int64 // total directories discovered
	FilesProcessed int64 // files fully processed (chunked + packed)
	FilesChanged   int64 // files with at least one new chunk
	FilesUnchanged int64 // files with all chunks already in repo

	// Data
	BytesRead   int64 // bytes read from filesystem
	BytesNew    int64 // bytes of new (non-duplicate) data
	BytesPacked int64 // bytes written to packs (post-compress+encrypt)
	ChunksTotal int64 // total chunks produced
	ChunksDup   int64 // chunks skipped (dedup)
	ChunksNew   int64 // chunks stored (new)

	// Packs
	PacksFlushed int64

	// Errors
	Errors int64

	// Current
	CurrentFile string // relative path of file currently being processed

	// Timing
	StartTime time.Time
	Elapsed   time.Duration
}

Stats holds real-time backup statistics.