restore

type ApplyOpts struct {
	// Archives is the backup chain in order: the full backup first, then
	// each increment.
	Archives []string
	// Checksums are the sha256 of each archive, in the same order. Empty
	// skips the check.
	Checksums []string
	// Layout is where each kind of file is put. All three directories have
	// to be named; FlatLayout is the one directory case.
	Layout Layout
	// WorkDir is what the caller called the restore's base directory. It is
	// recorded in the marker and nothing else: the data goes where Layout
	// says. Empty records the snapshot directory instead.
	WorkDir string
	// InstanceName is the instance the directories were resolved for, empty
	// when they were given directly. It is recorded in the marker.
	InstanceName string
	// Point is where the final xlog is cut. Nil replays the chain whole.
	Point *Point
	// PointName is the cluster recovery point the position came from; it is
	// recorded in the marker and not otherwise used.
	PointName string
	// PatchUUID is the instance UUID to stamp into every header. Empty
	// leaves the headers as they are.
	PatchUUID string
	// Config is what the cluster configuration says about the instance the
	// directories were resolved for, nil when they were given directly. With
	// it, restored data the instance would refuse to start on is refused;
	// without it, the same finding is a warning.
	Config *ConfigIdentity
}

type ApplyResult struct {
	// Files are the entry names landed, in the order they were unpacked and
	// relative to the directory of their own kind -- Layout.DirFor says which
	// one that is. Flat for snap/xlog, but vinyl's .run/.index carry a
	// <space_id>/<index_id>/ prefix.
	Files []string
	// Patched counts the headers restamped with the new instance UUID.
	Patched int
	// TrimmedFile is the base name of the xlog cut at the point, empty when
	// nothing was cut.
	TrimmedFile string
	// DroppedFiles are the base names removed for starting past the point.
	DroppedFiles []string
	// StatePath is where the marker was written.
	StatePath string
}

type ClusterTopology struct {
	// Replicasets are the replicasets the configuration declares.
	Replicasets []ConfiguredReplicaset
}

type ConfigDirs struct {
	Snapshot       string
	WAL            string
	Vinyl          string
	ProcessWorkDir string
}

type ConfigIdentity struct {
	// ReplicasetName is the replicaset the configuration puts the instance in.
	ReplicasetName string
	// InstanceUUID and ReplicasetUUID are database.instance_uuid and
	// database.replicaset_uuid, empty when the configuration pins none.
	InstanceUUID   string
	ReplicasetUUID string
	// Anon is replication.anon. An anonymous replica cannot carry a name, so
	// a snapshot without one is no reason for it not to start.
	Anon bool
	// SkipNames is compat.skip_replication_names set to 'old', under which
	// Tarantool compares no names and requires none.
	SkipNames bool
	// EnvInstanceUUID and EnvReplicasetUUID are TT_DATABASE_INSTANCE_UUID and
	// TT_DATABASE_REPLICASET_UUID as tt's own environment has them. They say
	// nothing certain about the instance, whose environment is its own: a
	// matching one only turns a refusal into a warning.
	EnvInstanceUUID   string
	EnvReplicasetUUID string
}

type ConfiguredReplicaset struct {
	// Name is the replicaset name; the configuration has no other stable
	// identifier for it once the UUIDs have been re-generated.
	Name string
	// Instances are the instance names configured in the replicaset.
	Instances []string
}

type DownloadItem struct {
	BackupID string            `json:"backup_id"`
	Type     backup.BackupType `json:"type"`
	// Artifact is the local file, not the storage key: this is the path the
	// orchestrator copies to the node.
	Artifact string `json:"artifact"`
	// ChecksumSHA256 is the sum of the bytes that were downloaded. It travels
	// with the archive so that `tt restore apply --checksums` can re-check it
	// on the node, after a copy this command knows nothing about.
	ChecksumSHA256 string `json:"checksum_sha256"`
	// TrimXlog marks the archive holding the recovery point: everything the
	// journal carries past the point must not be replayed.
	TrimXlog bool `json:"trim_xlog,omitempty"`
	// TrimTo is where that archive's journal is cut.
	TrimTo *Point `json:"trim_to,omitempty"`
}

type Layout struct {
	// Snapshot is snapshot.dir: the .snap files.
	Snapshot string
	// WAL is wal.dir: the .xlog files.
	WAL string
	// Vinyl is vinyl.dir: the .vylog and the run/index files under their
	// <space_id>/<index_id>/ subdirectories.
	Vinyl string
}

type MasterDiff struct {
	ReplicasetUUID string `json:"replicaset_uuid"`
	Name           string `json:"name"`
	MasterInstance string `json:"master_instance_name"`
}

type NearestSafe struct {
	Before *time.Time `json:"before,omitempty"`
	After  *time.Time `json:"after,omitempty"`
}

type PlanOpts struct {
	// Storage is the opened backup storage; the plan lists it itself rather
	// than being handed a set of manifests.
	Storage storage.Storage
	// TargetTime is the moment the cluster is to be brought back to.
	TargetTime time.Time
	// Dir is the local directory the manifests and archives land in.
	Dir string
	// Current is the cluster the restore is aimed at. Nil skips the topology
	// check and says so in the warnings: the check is worth having, but the
	// storage is worth reading without a cluster config at hand.
	Current *ClusterTopology
	// Replicasets restricts the restore to the named replicasets, the rest
	// being left to be bootstrapped fresh. The names are the configuration's,
	// so it requires Current; empty restores every replicaset the backup holds.
	Replicasets []string
}

type PlanResult struct {
	// Status decides the exit code and whether the archives were downloaded.
	Status Status `json:"status"`
	// TargetTime echoes the requested moment.
	TargetTime time.Time `json:"target_time"`
	// Reason names what stopped the plan; empty on success.
	Reason string `json:"reason,omitempty"`
	// RecoveryPoint is the cluster point the restore is built around.
	RecoveryPoint *RecoveryPoint `json:"recovery_point,omitempty"`
	// DownloadPlan maps a replicaset UUID to its ordered backup chain.
	DownloadPlan map[string][]DownloadItem `json:"download_plan,omitempty"`
	// RestoreTargets maps a replicaset UUID to the node its chain is restored
	// onto. Keyed like DownloadPlan, so one key answers both what a node
	// replays and what UUID it must own afterwards.
	RestoreTargets map[string]RestoreTarget `json:"restore_targets,omitempty"`
	// NearestSafe are the recovery times on either side of an unreachable
	// target, so that a caller can offer them and retry.
	NearestSafe *NearestSafe `json:"nearest_safe,omitempty"`
	// TopologyDiff explains a topology_mismatch.
	TopologyDiff *TopologyDiff `json:"topology_diff,omitempty"`
	// Warnings are what a restore survives but an operator should know.
	Warnings []string `json:"warnings"`
}

type Point struct {
	ReplicaID uint32 `json:"replica_id"`
	LSN       uint64 `json:"lsn"`
}

type RecoveryPoint struct {
	// Label is the point's cluster-wide label, what the point manager wrote on
	// every shard and what `tt restore apply --point-name` records.
	Label string `json:"label"`
	// Timestamp is the point's effective time: the earliest among its shards.
	Timestamp time.Time `json:"timestamp"`
	// TrimToByReplicaset is where each replicaset's journal is cut, keyed by
	// replicaset UUID. It is what `tt restore apply --target-point` takes.
	TrimToByReplicaset map[string]Point `json:"trim_to_by_replicaset"`
}

type ReplicasetDiff struct {
	ReplicasetUUID string `json:"replicaset_uuid,omitempty"`
	Name           string `json:"name,omitempty"`
	// Instances are the instance names of this replicaset.
	Instances []string `json:"instances"`
	// Candidates are the replicasets on the other side it could equally be.
	Candidates []string `json:"candidates,omitempty"`
}

type RestoreInstance struct {
	// InstanceName is the node this chain goes to.
	InstanceName string `json:"instance_name"`
	// PatchUUID is the instance UUID the restored node must carry: the one it
	// held in the backed-up cluster, read off the manifest's topology entry
	// for it. Absent when the manifest recorded none for the member.
	PatchUUID string `json:"patch_uuid,omitempty"`
	// Role is the member's place in the replicaset: master for the instance
	// the archives were taken on, replica for every other member.
	Role string `json:"role"`
}

type RestoreTarget struct {
	// InstanceName is the node this replicaset's chain goes to: the master,
	// the instance the backup was taken on. It is the master's own entry of
	// Instances, kept at the top level for a reader of the older document.
	InstanceName string `json:"instance_name"`
	// PatchUUID is the instance UUID the restored master must carry: the one
	// it held in the backed-up cluster, which is what `tt restore apply
	// --patch-uuid` stamps into every header. Restoring onto the instance the
	// backup was taken on makes it the UUID already in the files, and the patch
	// a confirmation. It is absent only when the manifest recorded no UUID at
	// all, and then a warning says so rather than an empty value going out as
	// if it meant "do not patch".
	PatchUUID string `json:"patch_uuid,omitempty"`
	// Instances names every node the chain is replayed onto, the master first
	// and the rest by name, each with the instance UUID that node owned in
	// the backed-up cluster - `tt restore apply` runs per instance with its
	// own --patch-uuid. A manifest that recorded no members beside the master
	// lists it alone, and a warning says so: single-target restore.
	Instances []RestoreInstance `json:"instances"`
	// Rejoin are the configured instances of the replicaset the backup holds
	// no member for: wiped before the restore, joining the replicaset from
	// nothing once it is up. Filled only when a cluster config was given,
	// because the backup does not know the composition of the cluster being
	// restored into.
	Rejoin []string `json:"rejoin,omitempty"`
}

type State struct {
	SchemaVersion int `json:"schema_version"`
	// WorkDir is the base directory the restore was called with, so a marker
	// found on its own still says what it belongs to.
	WorkDir string `json:"work_dir"`
	// SnapshotDir, WALDir and VinylDir are the directories the files were
	// actually put in. They are what makes the marker readable on a split
	// layout, where WorkDir names none of them.
	SnapshotDir string `json:"snapshot_dir"`
	WALDir      string `json:"wal_dir"`
	VinylDir    string `json:"vinyl_dir"`
	// InstanceName is the instance whose configuration the directories were
	// resolved from, empty when they were given directly.
	InstanceName string `json:"instance_name,omitempty"`
	// PointName is the cluster recovery point (recovery_point.name of the
	// restore plan). It is what makes the cross-node comparison meaningful:
	// TargetPoint differs per replicaset, the name does not. Empty when the
	// operator did not pass --point-name.
	PointName string `json:"point_name,omitempty"`
	// TargetPoint is the per-replicaset position the final xlog was cut at,
	// nil when the chain was replayed whole.
	TargetPoint *Point `json:"target_point"`
	// InstanceUUID is the UUID stamped into the headers, empty when
	// --patch-uuid was omitted.
	InstanceUUID string `json:"instance_uuid,omitempty"`
	// Archives lists the applied chain in order, by base name.
	Archives  []string  `json:"archives"`
	AppliedAt time.Time `json:"applied_at"`
}

type Status string

type TopologyDiff struct {
	// MissingReplicasets were backed up but no configured replicaset shares an
	// instance name with them: their data has nowhere to go.
	MissingReplicasets []ReplicasetDiff `json:"missing_replicasets,omitempty"`
	// ExtraReplicasets are configured but nothing in the backup maps onto them.
	ExtraReplicasets []ReplicasetDiff `json:"extra_replicasets,omitempty"`
	// AmbiguousReplicasets share instance names with more than one replicaset
	// on the other side, so no mapping can be picked without guessing.
	AmbiguousReplicasets []ReplicasetDiff `json:"ambiguous_replicasets,omitempty"`
	// UncoveredMasters are backed-up masters the matched replicaset of the
	// configuration does not carry.
	UncoveredMasters []MasterDiff `json:"uncovered_masters,omitempty"`
}