control

Documentation

Index

• Constants
• func DefaultRestoreContainerName(timeFormat dttm.TimeFormat) string
• func IsValidCollisionPolicy(cp CollisionPolicy) bool
• type BackupConfig
  • func DefaultBackupConfig() BackupConfig
• type BackupM365Config
• type CollisionPolicy
• type ExportConfig
  • func DefaultExportConfig() ExportConfig
• type FailurePolicy
• type FormatType
• type IncrementalsConfig
• type Options
  • func DefaultOptions() Options
• type Parallelism
• type PreviewItemLimits
• type RateLimiter
• type RestoreConfig
  • func DefaultRestoreConfig(timeFormat dttm.TimeFormat) RestoreConfig
  • func EnsureRestoreConfigDefaults(ctx context.Context, rc RestoreConfig) RestoreConfig
  • func (rc RestoreConfig) Conceal() string
  • func (rc RestoreConfig) Format(fs fmt.State, _ rune)
  • func (rc RestoreConfig) PlainString() string
  • func (rc RestoreConfig) String() string
• type Toggles

Constants

const (
	DefaultRestoreLocation = "Corso_Restore_"
)

const RootLocation = "/"

Functions

func DefaultRestoreContainerName

func DefaultRestoreContainerName(timeFormat dttm.TimeFormat) string

func IsValidCollisionPolicy

func IsValidCollisionPolicy(cp CollisionPolicy) bool

Types

type BackupConfig

type BackupConfig struct {
	FailureHandling      FailurePolicy                      `json:"failureHandling"`
	ItemExtensionFactory []extensions.CreateItemExtensioner `json:"-"`
	Parallelism          Parallelism                        `json:"parallelism"`
	ServiceRateLimiter   RateLimiter                        `json:"serviceRateLimiter"`
	Incrementals         IncrementalsConfig                 `json:"incrementalsConfig"`
	M365                 BackupM365Config                   `json:"m365Config"`

	// PreviewLimits defines the number of items and/or amount of data to fetch on
	// a best-effort basis for preview backups.
	//
	// Since this is not split out by service or data categories these limits
	// apply independently to all data categories that appear in a single backup
	// where they are set. For example, if doing a teams backup and there's both a
	// SharePoint site and Messages available, both data categories would try to
	// backup data until the set limits without paying attention to what the other
	// had already backed up.
	PreviewLimits PreviewItemLimits `json:"previewItemLimits"`
}

BackupConfig is the set of options used for backup operations. Each set of options is only applied to the backup operation it's passed to. To use the same set of options for multiple backup operations pass the struct to all operations.

func DefaultBackupConfig

func DefaultBackupConfig() BackupConfig

DefaultBackupOptions provides a Backup with the default values set.

type BackupM365Config

type BackupM365Config struct {
	// DeltaPageSize controls the quantity of items fetched in each page during
	// multi-page queries, such as graph api delta endpoints.
	DeltaPageSize int32 `json:"deltaPageSize"`

	// DisableDelta prevents backups from calling /delta endpoints and will force
	// a full enumeration of all items. This is different from
	// IncrementalsConfig.ForceFullEnumeration in that this does not even
	// make use of delta endpoints if a delta token is available. This is
	// necessary when the user has filled up their mailbox storage as Microsoft
	// prevents the API from being able to make calls to /delta endpoints when a
	// mailbox is over storage limits.
	DisableDeltaEndpoint bool `json:"exchangeDeltaEndpoint,omitempty"`

	// ExchangeImmutableIDs denotes whether Corso should store items with
	// immutable Exchange IDs. This is only safe to set if the previous backup for
	// incremental backups used immutable IDs or if a full backup is being done.
	ExchangeImmutableIDs bool `json:"exchangeImmutableIDs,omitempty"`

	// see: https://github.com/alcionai/corso/issues/4688
	UseOldDriveDeltaProcess bool `json:"useOldDriveDeltaProcess"`
}

BackupM365Config contains config options that are specific to backing up data from M365 or Corso features that are only available during M365 backups.

type CollisionPolicy

type CollisionPolicy string

CollisionPolicy describes how the datalayer behaves in case of a collision.

const (
	Unknown CollisionPolicy = ""
	Skip    CollisionPolicy = "skip"
	Copy    CollisionPolicy = "copy"
	Replace CollisionPolicy = "replace"
)

type ExportConfig

type ExportConfig struct {
	// Archive decides if we should create an archive from the data
	// instead of just returning all the files. If Archive is set to
	// true, we return a single collection with a single file which is
	// the archive.
	Archive bool

	// Format decides the format in which we return the data.
	// ex: html vs pst vs other.
	// Default format is decided on a per-service or per-data basis.
	Format FormatType
}

ExportConfig contains config for exports

func DefaultExportConfig

func DefaultExportConfig() ExportConfig

type FailurePolicy

type FailurePolicy string

const (
	// fails and exits the run immediately
	FailFast FailurePolicy = "fail-fast"
	// recovers whenever possible, reports non-zero recoveries as a failure
	FailAfterRecovery FailurePolicy = "fail-after-recovery"
	// recovers whenever possible, does not report recovery as failure
	BestEffort FailurePolicy = "best-effort"
)

type FormatType

type FormatType string

var (
	// Follow whatever format is the default for the service or data type.
	DefaultFormat FormatType
	// export the data as raw, unmodified json
	JSONFormat FormatType = "json"
)

type IncrementalsConfig

type IncrementalsConfig struct {
	// ForceFullEnumeration prevents the use of a previous backup as the starting
	// point for the current backup. All data in the external service will be
	// enumerated whether or not it's changed. Per-item storage will only get
	// updated if changes have occurred.
	ForceFullEnumeration bool `json:"forceFullEnumeration,omitempty"`

	// ForceItemDataRefresh causes the data for all enumerated items to replace
	// stored data, even if no changes have been detected. Storage-side data
	// deduplication still applies, but that's after item download, and items are
	// always downloaded when this flag is set.
	ForceItemDataRefresh bool `json:"forceItemDataRefresh,omitempty"`
}

IncrementalsConfig contains options specific to incremental backups and affects what data will be fetched from the external service being backed up.

type Options

type Options struct {
	// DeltaPageSize controls the quantity of items fetched in each page
	// during multi-page queries, such as graph api delta endpoints.
	DeltaPageSize        int32                              `json:"deltaPageSize"`
	DisableMetrics       bool                               `json:"disableMetrics"`
	FailureHandling      FailurePolicy                      `json:"failureHandling"`
	ItemExtensionFactory []extensions.CreateItemExtensioner `json:"-"`
	Parallelism          Parallelism                        `json:"parallelism"`
	Repo                 repository.Options                 `json:"repo"`
	SkipReduce           bool                               `json:"skipReduce"`
	ToggleFeatures       Toggles                            `json:"toggleFeatures"`
	// PreviewItemLimits defines the number of items and/or amount of data to
	// fetch on a best-effort basis. Right now it's used for preview backups.
	//
	// Since this is not split out by service or data categories these limits
	// apply independently to all data categories that appear in a single backup
	// where they are set. For example, if doing a teams backup and there's both a
	// SharePoint site and Messages available, both data categories would try to
	// backup data until the set limits without paying attention to what the other
	// had already backed up.
	PreviewLimits PreviewItemLimits `json:"previewItemLimits"`

	// specifying a resource tuple in this map allows that resource to produce
	// a Skip instead of a recoverable error in case of a failure due to 503 when
	// retrieving calendar event item data.
	SkipEventsOnInstance503ForResources map[string]struct{}
}

Options holds the optional configurations for a process

func DefaultOptions

func DefaultOptions() Options

DefaultOptions provides an Options with the default values set.

type Parallelism

type Parallelism struct {
	// CollectionBuffer sets the number of items in a collection to buffer before
	// blocking.
	CollectionBuffer int

	// ItemFetch sets the number of items to fetch in parallel when populating
	// items within a collection.
	ItemFetch int
}

type PreviewItemLimits

type PreviewItemLimits struct {
	MaxItems             int
	MaxItemsPerContainer int
	MaxContainers        int
	MaxBytes             int64
	MaxPages             int
	Enabled              bool
}

PreviewItemLimits describes best-effort maximum values to attempt to reach in this backup. Preview backups are used to demonstrate value by being quick to create.

type RateLimiter

type RateLimiter struct {
	DisableSlidingWindowLimiter bool `json:"disableSlidingWindowLimiter"`
}

RateLimiter is the set of options applied to any external service facing rate limiters Corso may use during backups or restores.

type RestoreConfig

type RestoreConfig struct {
	// Defines the per-item collision handling policy.
	// Defaults to Skip.
	OnCollision CollisionPolicy `json:"onCollision"`

	// ProtectedResource specifies which resource the data will be restored to.
	// If empty, restores to the same resource that was backed up.
	// Defaults to empty.
	ProtectedResource string `json:"protectedResource"`

	// Location specifies the container into which the data will be restored.
	// Only accepts container names, does not accept IDs.
	// If empty or "/", data will get restored in place, beginning at the root.
	// Defaults to "Corso_Restore_<current_dttm>"
	Location string `json:"location"`

	// Drive specifies the name of the drive into which the data will be
	// restored. If empty, data is restored to the same drive that was backed
	// up.
	// Defaults to empty.
	Drive string `json:"drive"`

	// IncludePermissions toggles whether the restore will include the original
	// folder- and item-level permissions.
	IncludePermissions bool `json:"includePermissions"`
}

RestoreConfig contains

func DefaultRestoreConfig

func DefaultRestoreConfig(timeFormat dttm.TimeFormat) RestoreConfig

func EnsureRestoreConfigDefaults

func EnsureRestoreConfigDefaults(
	ctx context.Context,
	rc RestoreConfig,
) RestoreConfig

EnsureRestoreConfigDefaults sets all non-supported values in the config struct to the default value.

func (RestoreConfig) Conceal

func (rc RestoreConfig) Conceal() string

Conceal produces a concealed representation of the config, suitable for logging, storing in errors, and other output.

func (RestoreConfig) Format

func (rc RestoreConfig) Format(fs fmt.State, _ rune)

Format produces a concealed representation of the config, even when used within a PrintF, suitable for logging, storing in errors, and other output.

func (RestoreConfig) PlainString

func (rc RestoreConfig) PlainString() string

PlainString returns an unescaped, unmodified string of the restore configuration.

func (RestoreConfig) String

func (rc RestoreConfig) String() string

String returns a plain text version of the restoreConfig.

type Toggles

type Toggles struct {
	// DisableIncrementals prevents backups from using incremental lookups,
	// forcing a new, complete backup of all data regardless of prior state.
	DisableIncrementals bool `json:"exchangeIncrementals,omitempty"`
	// ForceItemDataDownload disables finding cached items in previous failed
	// backups (i.e. kopia-assisted incrementals). Data dedupe will still occur
	// since that is based on content hashes. Items that have not changed since
	// the previous backup (i.e. in the merge base) will not be redownloaded. Use
	// DisableIncrementals to control that behavior.
	ForceItemDataDownload bool `json:"forceItemDataDownload,omitempty"`
	// DisableDelta prevents backups from using delta based lookups,
	// forcing a backup by enumerating all items. This is different
	// from DisableIncrementals in that this does not even makes use of
	// delta endpoints with or without a delta token. This is necessary
	// when the user has filled up the mailbox storage available to the
	// user as Microsoft prevents the API from being able to make calls
	// to delta endpoints.
	DisableDelta bool `json:"exchangeDelta,omitempty"`
	// ExchangeImmutableIDs denotes whether Corso should store items with
	// immutable Exchange IDs. This is only safe to set if the previous backup for
	// incremental backups used immutable IDs or if a full backup is being done.
	ExchangeImmutableIDs bool `json:"exchangeImmutableIDs,omitempty"`

	RunMigrations bool `json:"runMigrations"`

	// DisableSlidingWindowLimiter disables the experimental sliding window rate
	// limiter for graph API requests. This is only relevant for exchange backups.
	// Setting this flag switches exchange backups to fallback to the default token
	// bucket rate limiter.
	DisableSlidingWindowLimiter bool `json:"disableSlidingWindowLimiter"`

	// see: https://github.com/alcionai/corso/issues/4688
	UseDeltaTree       bool `json:"useDeltaTree"`
	UseOldDeltaProcess bool `json:"useOldDeltaProcess"`

	// AddDisableLazyItemReader disables lazy item reader, such that we fall
	// back to prefetch reader. This flag is currently only meant for groups
	// conversations backup. Although it can be utilized for other services
	// in future.
	//
	// This flag should only be used if lazy item reader is the default choice
	// and we want to fallback to prefetch reader.
	DisableLazyItemReader bool `json:"disableLazyItemReader"`
}

Toggles allows callers to force corso to behave in ways that deviate from the default expectations by turning on or shutting off certain features. The default state for every toggle is false; toggles are only turned on if specified by the caller.