maintenance

Documentation

Overview

Package maintenance manages automatic repository maintenance.

Index

• Constants
• Variables
• func DeleteUnreferencedBlobs(ctx context.Context, rep repo.DirectRepositoryWriter, ...) (int, error)
• func DropDeletedContents(ctx context.Context, rep repo.DirectRepositoryWriter, ...) error
• func HasParams(ctx context.Context, rep repo.Repository) (bool, error)
• func IndexCompaction(ctx context.Context, rep repo.DirectRepositoryWriter, safety SafetyParameters) error
• func ReportRun(ctx context.Context, rep repo.DirectRepositoryWriter, taskType TaskType, ...) error
• func RewriteContents(ctx context.Context, rep repo.DirectRepositoryWriter, ...) error
• func Run(ctx context.Context, runParams RunParameters, safety SafetyParameters) error
• func RunExclusive(ctx context.Context, rep repo.DirectRepositoryWriter, mode Mode, force bool, ...) error
• func SetParams(ctx context.Context, rep repo.RepositoryWriter, par *Params) error
• func SetSchedule(ctx context.Context, rep repo.DirectRepositoryWriter, s *Schedule) error
• type CycleParams
• type DeleteUnreferencedBlobsOptions
• type Mode
• type NotOwnedError
  • func (e NotOwnedError) Error() string
• type Params
  • func DefaultParams() Params
  • func GetParams(ctx context.Context, rep repo.Repository) (*Params, error)
• type RewriteContentsOptions
• type RunInfo
• type RunParameters
• type SafetyParameters
• type Schedule
  • func GetSchedule(ctx context.Context, rep repo.DirectRepository) (*Schedule, error)
  • func (s *Schedule) ReportRun(taskType TaskType, info RunInfo)
• type TaskType

Constants

const (
	TaskSnapshotGarbageCollection = "snapshot-gc"
	TaskDeleteOrphanedBlobsQuick  = "quick-delete-blobs"
	TaskDeleteOrphanedBlobsFull   = "full-delete-blobs"
	TaskRewriteContentsQuick      = "quick-rewrite-contents"
	TaskRewriteContentsFull       = "full-rewrite-contents"
	TaskDropDeletedContentsFull   = "full-drop-deleted-content"
	TaskIndexCompaction           = "index-compaction"
)

Task IDs.

Variables

var (
	// SafetyNone has safety parameters which allow full garbage collection without unnecessary
	// delays, but it is safe only if no other kopia clients are running and storage backend is
	// strongly consistent.
	SafetyNone = SafetyParameters{
		BlobDeleteMinAge:                 0,
		DropContentFromIndexExtraMargin:  0,
		MarginBetweenSnapshotGC:          0,
		MinContentAgeSubjectToGC:         0,
		RewriteMinAge:                    0,
		SessionExpirationAge:             0,
		RequireTwoGCCycles:               false,
		DisableEventualConsistencySafety: true,
	}

	// SafetyFull has default safety parameters which allow safe GC concurrent with snapshotting
	// by other Kopia clients.
	SafetyFull = SafetyParameters{
		BlobDeleteMinAge:                2 * time.Hour,
		DropContentFromIndexExtraMargin: time.Hour,
		MarginBetweenSnapshotGC:         4 * time.Hour,
		MinContentAgeSubjectToGC:        24 * time.Hour,
		RewriteMinAge:                   2 * time.Hour,
		SessionExpirationAge:            96 * time.Hour,
		RequireTwoGCCycles:              true,
		MinRewriteToOrphanDeletionDelay: time.Hour,
	}
)

Supported safety levels.

Functions

func DeleteUnreferencedBlobs

func DeleteUnreferencedBlobs(ctx context.Context, rep repo.DirectRepositoryWriter, opt DeleteUnreferencedBlobsOptions, safety SafetyParameters) (int, error)

DeleteUnreferencedBlobs deletes old blobs that are no longer referenced by index entries. nolint:gocyclo

func DropDeletedContents

func DropDeletedContents(ctx context.Context, rep repo.DirectRepositoryWriter, dropDeletedBefore time.Time, safety SafetyParameters) error

DropDeletedContents rewrites indexes while dropping deleted contents above certain age.

func HasParams

func HasParams(ctx context.Context, rep repo.Repository) (bool, error)

HasParams determines whether repository-wide maintenance parameters have been set.

func IndexCompaction

func IndexCompaction(ctx context.Context, rep repo.DirectRepositoryWriter, safety SafetyParameters) error

IndexCompaction rewrites index blobs to reduce their count but does not drop any contents.

func ReportRun

func ReportRun(ctx context.Context, rep repo.DirectRepositoryWriter, taskType TaskType, s *Schedule, run func() error) error

ReportRun reports timing of a maintenance run and persists it in repository.

func RewriteContents

func RewriteContents(ctx context.Context, rep repo.DirectRepositoryWriter, opt *RewriteContentsOptions, safety SafetyParameters) error

RewriteContents rewrites contents according to provided criteria and creates new blobs and index entries to point at the.

func Run

func Run(ctx context.Context, runParams RunParameters, safety SafetyParameters) error

Run performs maintenance activities for a repository.

func RunExclusive

func RunExclusive(ctx context.Context, rep repo.DirectRepositoryWriter, mode Mode, force bool, cb func(runParams RunParameters) error) error

RunExclusive runs the provided callback if the maintenance is owned by local user and lock can be acquired. Lock is passed to the function, which ensures that every call to Run() is within the exclusive context.

func SetParams

func SetParams(ctx context.Context, rep repo.RepositoryWriter, par *Params) error

SetParams sets the maintenance parameters.

func SetSchedule

func SetSchedule(ctx context.Context, rep repo.DirectRepositoryWriter, s *Schedule) error

SetSchedule updates scheduled maintenance times.

Types

type CycleParams

type CycleParams struct {
	Enabled  bool          `json:"enabled"`
	Interval time.Duration `json:"interval"`
}

CycleParams specifies parameters for a maintenance cycle (quick or full).

type DeleteUnreferencedBlobsOptions

type DeleteUnreferencedBlobsOptions struct {
	Parallel int
	Prefix   blob.ID
	DryRun   bool
}

DeleteUnreferencedBlobsOptions provides option for blob garbage collection algorithm.

type Mode

type Mode string

Mode describes the mode of maintenance to perfor.

const (
	ModeNone  Mode = "none"
	ModeQuick Mode = "quick"
	ModeFull  Mode = "full"
	ModeAuto  Mode = "auto" // run either quick of full if required by schedule
)

Supported maintenance modes.

type NotOwnedError

type NotOwnedError struct {
	Owner string
}

NotOwnedError is returned when maintenance cannot run because it is owned by another user.

func (NotOwnedError) Error

func (e NotOwnedError) Error() string

type Params

type Params struct {
	Owner string `json:"owner"`

	QuickCycle CycleParams `json:"quick"`
	FullCycle  CycleParams `json:"full"`
}

Params is a JSON-serialized maintenance configuration stored in a repository.

func DefaultParams

func DefaultParams() Params

DefaultParams represents default values of maintenance parameters.

func GetParams

func GetParams(ctx context.Context, rep repo.Repository) (*Params, error)

GetParams returns repository-wide maintenance parameters.

type RewriteContentsOptions

type RewriteContentsOptions struct {
	Parallel       int
	ContentIDs     []content.ID
	ContentIDRange content.IDRange
	PackPrefix     blob.ID
	ShortPacks     bool
	FormatVersion  int
	DryRun         bool
}

RewriteContentsOptions provides options for RewriteContents.

type RunInfo

type RunInfo struct {
	Start   time.Time `json:"start"`
	End     time.Time `json:"end"`
	Success bool      `json:"success,omitempty"`
	Error   string    `json:"error,omitempty"`
}

RunInfo represents information about a single run of a maintenance task.

type RunParameters

type RunParameters struct {
	Mode Mode

	Params *Params
	// contains filtered or unexported fields
}

RunParameters passes essential parameters for maintenance. It is generated by RunExclusive and can't be create outside of its package and is required to ensure all maintenance tasks run under an exclusive lock.

type SafetyParameters

type SafetyParameters struct {
	// Do not rewrite contents younger than this age.
	RewriteMinAge time.Duration

	// Snapshot GC: MinContentAgeSubjectToGC is the minimum age of content to be subject to garbage collection.
	MinContentAgeSubjectToGC time.Duration

	// MarginBetweenSnapshotGC is the minimal amount of time that must pass between snapshot
	// GC cycles to allow all in-flight snapshots during earlier GC to be flushed and
	// visible to a following GC. The uploader will automatically create a checkpoint every 45 minutes,
	// so ~1 hour should be enough but we're setting this to a higher conservative value for extra safety.
	MarginBetweenSnapshotGC time.Duration

	// RequireTwoGCCycles indicates that two GC cycles are required.
	RequireTwoGCCycles bool

	// DisableEventualConsistencySafety disables wait time to allow settling of eventually-consistent writes in blob stores.
	DisableEventualConsistencySafety bool

	// DropContentFromIndexExtraMargin is the amount of margin time before dropping deleted contents from indices.
	DropContentFromIndexExtraMargin time.Duration

	// Blob GC: Delete unused blobs above this age.
	BlobDeleteMinAge time.Duration

	// Blob GC: Drop incomplete session blobs above this age.
	SessionExpirationAge time.Duration

	// Minimum time that must pass after content rewrite before we delete orphaned blobs.
	MinRewriteToOrphanDeletionDelay time.Duration
}

SafetyParameters specifies timing parameters that affect safety of maintenance.

type Schedule

type Schedule struct {
	NextFullMaintenanceTime  time.Time `json:"nextFullMaintenance"`
	NextQuickMaintenanceTime time.Time `json:"nextQuickMaintenance"`

	Runs map[TaskType][]RunInfo `json:"runs"`
}

Schedule keeps track of scheduled maintenance times.

func GetSchedule

func GetSchedule(ctx context.Context, rep repo.DirectRepository) (*Schedule, error)

GetSchedule gets the scheduled maintenance times.

func (*Schedule) ReportRun

func (s *Schedule) ReportRun(taskType TaskType, info RunInfo)

ReportRun adds the provided run information to the history and discards oldest entried.

type TaskType

type TaskType string

TaskType identifies the type of a maintenance task.