backup

type ArchiveWalker interface {
	// WalkArchives calls fn with every object of type t, loaded, in the
	// archives but the finished ones skip reports true for, and returns
	// the names of all the finished archives it walked or skipped.
	WalkArchives(ctx context.Context, t proto.ObjectType, skip func(archive string) bool, fn ObjectReceiver) ([]string, error)
}

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

type CommitGate interface {
	// BeginCommit returns the grant for a run on set, or ErrCommitDenied.
	BeginCommit(ctx context.Context, set string) (*CommitGrant, error)
}

type CommitGrant struct {
	// Policy is the store's write policy for this run; nil when the server
	// holds none, which leaves the agent's key file in charge.
	Policy *storekey.Policy
	// Rescan asks the run to read every file again, because the store lost
	// content it could not name a path for.
	Rescan bool
	// Damaged names the paths whose stored content the store lost. A run
	// reads them again whatever its change detection says, and takes no
	// chunk of theirs on trust.
	Damaged []string
}

type CommitSizer interface {
	// CommitSizes is CommitInfo with the size of each commit beside it, in
	// the same order.
	CommitSizes(ctx context.Context, set string, notAfter time.Time, count int) ([]*proto.Commit, []*proto.CommitSize, error)
}

type Confirmer interface {
	// PutFile stores obj when every assumed ref is held; otherwise it
	// returns the refs that are not.
	PutFile(ctx context.Context, obj *proto.Object, assumed []*proto.Ref) (missing []*proto.Ref, err error)
}

type Counter interface {
	// Count reports how many objects the store holds, in total and distinct.
	Count() (total uint64, unique uint64, err error)
}

type DamageIndex interface {
	// PathsOfFiles returns where the given file objects are stored; a file
	// object no live version references any more yields nothing.
	PathsOfFiles(ctx context.Context, refs []*proto.Ref) ([]FilePath, error)
	// MarkDamaged records paths of the set a run must read again.
	MarkDamaged(ctx context.Context, setID int64, paths []string) error
	// MarkLost records versions no run can produce again, so a restore of
	// the commits holding them says so rather than failing.
	MarkLost(ctx context.Context, versions []FilePath) error
	// MarkRescan records that a whole set must be read again.
	MarkRescan(ctx context.Context, setID int64) error
}

type DamageReport struct {
	// Paths are the paths marked for a re-read, by set id.
	Paths map[int64][]string
	// Rescan is the sets marked for a full re-read, because some loss
	// could not be placed at a path.
	Rescan []int64
	// Unplaced are the lost objects no live path holds.
	Unplaced []*proto.Ref
	// Lost are the closed versions nothing can produce again; the commits
	// holding them are damaged for that path.
	Lost []FilePath
}

type DirLister interface {
	// ReadDir lists what the set held directly under dir at notAfter,
	// sorted by name. Directory entries carry a name and a ref only, since
	// the index keeps no stat for them. An unknown set lists nothing.
	ReadDir(ctx context.Context, set string, dir string, notAfter time.Time) ([]*proto.TreeNode, error)
}

type Eraser interface {
	// Erase tombstones the ref as an erasure.
	Erase(context.Context, *proto.Ref) error
}

type EscrowLister interface {
	// EscrowedKeys returns every copy kept.
	EscrowedKeys(ctx context.Context) ([]EscrowedKey, error)
}

type EscrowedKey struct {
	KeyID    string
	Escrowed []byte
}

type FS interface {
	// ReadDir lists dir sorted by name, without following symlinks. Info on
	// an entry may stat it; the walker only asks for entries it includes.
	ReadDir(ctx context.Context, dir string) ([]fs.DirEntry, error)
	// Stat stats path, following a symlink; the walker uses it on Root.
	Stat(ctx context.Context, path string) (os.FileInfo, error)
	Lstat(ctx context.Context, path string) (os.FileInfo, error)
	Open(ctx context.Context, path string) (File, error)
	Readlink(ctx context.Context, path string) (string, error)
	Join(dir, name string) string
	// Owners names a file's user and group; empty when unknown.
	Owners(info os.FileInfo) (user, group string)
	// Traits is read once as a walk starts.
	Traits() Traits
}

type File interface {
	io.ReadCloser
	Stat() (os.FileInfo, error)
}

type FilePath struct {
	Ref   *proto.Ref
	SetID int64
	// Set is the set's name, for reporting; SetID is what identifies it.
	Set  string
	Path string
	// Open reports whether this is the version the set's newest commit
	// points at, which is the only one an agent can produce again.
	Open bool
}

type FileRead struct {
	Ref  *proto.Ref
	Skip []int
}

type FileToRestore struct {
	Path string
	Stat *proto.FileInfo
	Ref  *proto.Ref
	// Written, when set, is handed the size of each part as it lands in
	// the file, as WithWritten does for RestoreFile.
	Written func(n int64)
}

type FilesReader interface {
	// ReadFiles calls object with each file's object in order, then,
	// unless objectsOnly, part with every part of each file not in its
	// Skip, in any order and possibly from several goroutines at once. A
	// part several of the files hold is handed over once, for any of them.
	ReadFiles(ctx context.Context, files []FileRead, objectsOnly bool, object func(file int, obj *proto.Object) error, part func(file, index int, obj *proto.Object) error) error
}

type Getter interface {
	// Get returns the object at the ref, or ErrNotFound.
	Get(context.Context, *proto.Ref) (*proto.Object, error)
}

type Growing struct {
	// Name is the file's name in the commit's root; it replaces any entry
	// of that name.
	Name string
	// Path is where the file is on disk.
	Path string
	// Size is how many bytes of it the commit holds.
	Size int64
	// From names the previous commit's root entry this file continues;
	// empty means Name.
	From string
	// ModTime, when set, is recorded as the file's modification time in
	// place of the one on disk, which its writer keeps changing.
	ModTime time.Time
}

type HasAller interface {
	// HasAll reports Has for each of refs, in their order.
	HasAll(ctx context.Context, refs []*proto.Ref) ([]bool, error)
}

type HeadKeeper interface {
	// AdvanceHead points the commit's set at it, unless the set already
	// points at one received later.
	AdvanceHead(commit *proto.Object) error
}

type HeaderWalker interface {
	// WalkHeaders calls fn for every header of type t; an error from fn
	// stops the walk.
	WalkHeaders(ctx context.Context, t proto.ObjectType, fn func(*proto.ObjectHeader) error) error
}

type Hole struct {
	Path   string
	Offset int64
	Length int64
	// Ref is the part that could not be read.
	Ref *proto.Ref
}

type Index interface {
	// Open readies the index for use.
	Open() error
	// Close releases the index.
	Close() error

	ObjectStore
	// FileInfo lists the versions of name that live commits of the set hold,
	// newest first, none newer than notAfter, at most count.
	FileInfo(ctx context.Context, set string, name string, notAfter time.Time, count int) ([]*proto.TreeNode, error)
	// CommitInfo lists the live, complete commits of the set, newest first,
	// none newer than notAfter, at most count.
	CommitInfo(ctx context.Context, set string, notAfter time.Time, count int) ([]*proto.Commit, error)
	// LatestCommit returns the ref of the set's newest commit, or ErrNotFound.
	LatestCommit(ctx context.Context, set string) (*proto.Ref, error)
	// ReIndex rebuilds the index from the store's objects.
	ReIndex(ctx context.Context) (ReIndexReport, error)
}

type Keeper interface {
	Keep(ctx context.Context, obj *proto.Object)
}

type KeyEscrow interface {
	// PutEscrowedKey keeps one escrowed copy, once: nothing kept is ever
	// replaced. A store keeps copies of one store key only.
	PutEscrowedKey(ctx context.Context, key EscrowedKey) error
	EscrowLister
}

type Leased interface {
	// SessionLease is how long a session lives without a write.
	SessionLease() time.Duration
}

type LocalFS struct{}

type ObjectReceiver func(*proto.Object) error

type ObjectStore interface {
	// Put stores the object.
	Put(context.Context, *proto.Object) error
	// Get returns the object at the ref, or ErrNotFound.
	Get(context.Context, *proto.Ref) (*proto.Object, error)
	// Delete removes the object at the ref.
	Delete(context.Context, *proto.Ref) error
	// Walk calls the receiver for every object of the type, or of every
	// type when it is INVALID; the bool says whether objects are decoded.
	Walk(context.Context, bool, proto.ObjectType, ObjectReceiver) error
	// Has reports whether the store holds the ref.
	Has(context.Context, *proto.Ref) (bool, error)
}

type Outcome int

type OverwriteMode int

type PartReader interface {
	// ReadParts calls fn with every part of file whose index is not in
	// skip, in any order and possibly from several goroutines at once.
	ReadParts(ctx context.Context, file *proto.Ref, skip []int, fn func(index int, obj *proto.Object) error) error
}

type PolicySource interface {
	// StorePolicy returns the store's policy, or nil.
	StorePolicy(ctx context.Context) (*storekey.Policy, error)
}

type PresenceIndex interface {
	// Presence returns the filters of scope; set matters for PresenceSet.
	Presence(ctx context.Context, scope PresenceScope, set string) ([]*proto.PresenceFilter, error)
}

type PresenceScope int

type PresenceSource interface {
	// Presence returns the filters for a run on set.
	Presence(ctx context.Context, set string) (presence.Set, error)
}

type RandomFile interface {
	io.ReaderAt
	io.WriterAt
	Truncate(size int64) error
	// Sync makes what was written durable.
	Sync() error
	Stat() (os.FileInfo, error)
	Close() error
}

type RandomWriteFS interface {
	WriteFS
	// Open opens path to read; a File that is no io.ReaderAt is read only
	// front to back.
	Open(ctx context.Context, path string) (File, error)
	// OpenFile opens path to read and write, creating it.
	OpenFile(ctx context.Context, path string) (RandomFile, error)
}

type ReIndexReport struct {
	// Tied counts the commits received at the same time as their set's
	// newest, indexed a microsecond after it.
	Tied int
	// Behind counts the commits received before their set's newest,
	// left out of the index.
	Behind int
	// Unnamed counts the commits that name no set, indexed under a
	// placeholder set.
	Unnamed int
}

type RecordLocator interface {
	// LocateRecords returns runs holding the records of refs, each
	// record's index naming its ref in refs. A ref it cannot locate is in
	// no run and is read the ordinary way. It authorizes nothing: the
	// caller has already decided the refs are readable.
	LocateRecords(ctx context.Context, refs []*proto.Ref) ([]*proto.LocatedRun, error)
}

type RecordReader interface {
	// ReadRecords returns the object of each of refs it could read, nil
	// for the rest, which are read the ordinary way. It authorizes
	// nothing.
	ReadRecords(ctx context.Context, refs []*proto.Ref) ([]*proto.Object, error)
}

type RefScope interface {
	// References reports whether a set of the store references ref.
	References(ctx context.Context, ref *proto.Ref) (bool, error)
	// ReferencesAll reports the same for each of refs, in their order.
	ReferencesAll(ctx context.Context, refs []*proto.Ref) ([]bool, error)
}

type RestoreLeaser interface {
	// RestoreLeases returns the refs of every live restore session.
	RestoreLeases(ctx context.Context) ([]*proto.Ref, error)
}

type RestoreStats struct {
	Files     int64 `json:"files"`
	Written   int64 `json:"written"`
	Unchanged int64 `json:"unchanged"`
	Skipped   int64 `json:"skipped"`
	// Salvaged counts files written with holes, and MissingBytes the bytes
	// of those holes.
	Salvaged     int64 `json:"salvaged"`
	MissingBytes int64 `json:"missing_bytes"`
	// Unsupported counts the symlinks left out of a tree that cannot hold
	// them.
	Unsupported int64 `json:"unsupported"`

	BytesFromDestination int64 `json:"bytes_from_destination"`
	BytesFromSeeds       int64 `json:"bytes_from_seeds"`
	BytesFromCache       int64 `json:"bytes_from_cache"`
	BytesFromStore       int64 `json:"bytes_from_store"`
}

type RestoredFile struct {
	Path string
	Ref  *proto.Ref
	Size int64
	// Written is how many of its bytes landed in the file; the rest came
	// from the file already there.
	Written int64
	Outcome Outcome
	Err     error
}

type Restorer struct {
	Store ObjectStore
	Key   *storekey.Key
	// FS is the tree restored into; nil is the local disk.
	FS WriteFS

	Seeds *SeedMap
	Cache *blobcache.Cache

	// Workers bounds how much of a restore runs at once, files and the
	// parts of one; 0 means DefaultRestoreWorkers.
	Workers   int
	Overwrite OverwriteMode
	// Verify rehashes every written file before it is renamed into place.
	Verify bool
	// DryRun reports what would change and writes nothing.
	DryRun bool
	// Salvage writes a file whose parts cannot all be read, leaving the
	// unreadable ranges as zeroes, instead of failing it.
	Salvage bool
	// Rechunk cuts a destination on the local disk that does not match at
	// the recorded offsets with the backup's chunker, so parts that only
	// moved are taken from it instead of the network. It costs a read of
	// the file.
	Rechunk bool
	// OnHole, when set, is called for every hole a salvaged file was left
	// with, possibly from several goroutines at once.
	OnHole func(Hole)
	// contains filtered or unexported fields
}

type Retention interface {
	// DeleteCommit retires a commit into its trash window, after which
	// LatestCommit no longer returns it; the only live commit of an active
	// set is refused with ErrNewestCommit.
	DeleteCommit(ctx context.Context, ref *proto.Ref) error
	// UndeleteCommit moves a retired commit back to live; a tombstoned
	// one is refused with ErrTombstoned.
	UndeleteCommit(ctx context.Context, ref *proto.Ref) error
	// TrashedCommits pages through the set's deleted commits that are not
	// tombstoned yet, newest deleted first: those deleted before before, or
	// all when it is zero, at most limit, every one when limit is zero, and
	// then the others deleted at the last one's instant, so its
	// DeletedAtNs is the before of the next page.
	TrashedCommits(ctx context.Context, set string, before time.Time, limit int) ([]*proto.TrashedCommit, error)
	// CountCommits counts the set's live complete commits received in
	// [from, to), or with deleted the ones TrashedCommits lists, per period
	// as it falls in the IANA zone, "" for UTC. It returns the non-empty
	// periods oldest first, each starting at its first instant; the first
	// may start before from.
	CountCommits(ctx context.Context, set string, period proto.Period, from, to time.Time, zone string, deleted bool) ([]*proto.CommitCount, error)
	// DeleteSet closes a set and retires every commit; erase uses a zero
	// window.
	DeleteSet(ctx context.Context, set string, erase bool) error
	// UndeleteSet reopens a closed set and revives its commits.
	UndeleteSet(ctx context.Context, set string) error
	// Unpin tombstones a pin.
	Unpin(ctx context.Context, pin *proto.Ref) error
	// Pins lists the live pins.
	Pins(ctx context.Context) ([]*proto.PinInfo, error)
}

type Retirer interface {
	// Retire tombstones the commits whose window has passed at now and
	// returns how many.
	Retire(ctx context.Context, now time.Time) (int, error)
}

type Revival struct {
	Commit *proto.Ref
	// Missing names some of the objects the commit reaches that the store
	// holds no copy of, and MissingCount counts them all.
	Missing      []*proto.Ref
	MissingCount int
}

type Reviver interface {
	// Revive checks what each commit reaches and, unless dryRun, takes back
	// the tombstones of every commit missing nothing and of what it
	// reaches, so collections keep them again. A commit missing anything is
	// reported and left as it is.
	Revive(ctx context.Context, commits []*proto.Ref, dryRun bool) ([]Revival, error)
	// Revived reports whether a revival takes back the commit's tombstone.
	Revived(ctx context.Context, commit *proto.Ref) (bool, error)
	// Holds reports, for each commit, whether the store still holds a copy
	// of the commit object, tombstoned or not; one it does not hold cannot
	// be revived.
	Holds(ctx context.Context, commits []*proto.Ref) ([]bool, error)
}

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

type Session struct {
	ID      string
	AgentID string
	Set     string
	// Restore names the object a restore session reads; retirement and
	// garbage collection keep it and everything it names while the session
	// lives.
	Restore  *proto.Ref
	Started  time.Time
	LastSeen time.Time
}

type SessionStore interface {
	// BeginSession opens s, fills in its ID and returns a context that
	// carries it.
	BeginSession(ctx context.Context, s *Session) (context.Context, error)
	// EndSession ends the context's session.
	EndSession(ctx context.Context) error
}

type SetScope interface {
	// Reachable reports whether one of the named sets references ref.
	Reachable(ctx context.Context, sets []string, ref *proto.Ref) (bool, error)
}

type StatCache interface {
	// Lookup reports whether an entry exists for path and whether it still
	// matches the file's identity.
	Lookup(path string, info os.FileInfo) (present bool, matches bool)
	// Store records the file's identity and the ref its read produced.
	Store(path string, info os.FileInfo, ref *proto.Ref) error
}

type Stream struct {
	Tar io.Reader
	// Name and File, set instead of Tar, store File's content as the one
	// file Name of the commit's tree.
	Name string
	File io.Reader
	// Inspect, when set, sees every entry's header before it is stored; a
	// writer it returns gets a copy of the entry's content.
	Inspect func(hdr *tar.Header) io.Writer
	// Finish, when set, runs once Tar is read to its end and before the
	// commit is stored; an error fails the run without a commit.
	Finish func() error
}

type Traits struct {
	// Resolution is the step mtimes are truncated to; 0 means exact. An FS
	// must report every mtime truncated to it, the same way on every run,
	// or files read with a finer time once look changed the next time.
	Resolution time.Duration
	// Skew bounds how far the FS's clock may be from ours.
	Skew time.Duration
	// Identity reports whether stat data carries ctime and inode, which
	// the stat cache compares; without it the walk consults no stat cache.
	Identity bool
	// Reread reports whether reading a file again is cheap enough for a
	// sampled re-hash; without it ForceHashPercent is ignored.
	Reread bool
}

type TraverserHandler func(string, *proto.TreeNode) error

type TreeFetcher interface {
	// GetTree returns the tree at ref and the trees below it, maxDepth
	// levels down.
	GetTree(ctx context.Context, ref *proto.Ref, maxDepth uint32) ([]*proto.Object, error)
}

type TreeOptions struct {
	// From restores only the subtree at this slash-separated path of the
	// commit.
	From string
	// Paths restores only these entries, slash-separated paths of the
	// commit, files or directories, each at its own path under the
	// directory. It excludes From and Delete.
	Paths []string
	// Name, when set, names each entry Paths names, or without Paths each
	// entry the tree holds directly, given its path in the tree; what a
	// renamed directory holds keeps its names. It excludes Delete.
	Name func(path string, info os.FileInfo) string
	// Delete removes everything under the directory the tree does not
	// hold, except the partial files a later restore resumes from.
	Delete bool
	// Listed is handed the files and bytes the tree holds once it is
	// listed, before anything is written.
	Listed func(files, bytes int64)
	// Written is handed the size of each part as it lands in a file,
	// possibly from several goroutines at once.
	Written func(n int64)
	// Done is called once for every file, possibly from several goroutines
	// at once. An error it returns stops the restore; returning nil for a
	// file that failed passes over it. Without Done, a failed file stops
	// the restore.
	Done func(file RestoredFile) error
	// Removing is called for each path Delete removes, before it is
	// removed, or instead of removing it in a dry run.
	Removing func(path string)
}

type TreeWriter interface {
	// File records a regular file whose content the callback writes;
	// ErrSkipFile from it leaves the file out.
	File(context.Context, os.FileInfo, func(io.Writer) error) error
	// Tree records a subdirectory the callback fills; ErrSkipFile from it
	// leaves the directory out.
	Tree(context.Context, os.FileInfo, func(TreeWriter) error) error
	// Node adds a finished node.
	Node(*proto.TreeNode)
}

type WalkFn func(path string, info os.FileInfo, ref *proto.Ref) error

type WalkResult struct {
	Ref    *proto.Ref
	Commit *proto.Commit
	Base   *proto.Ref
	Files  int64
	// Bytes is what those files hold on disk, whether or not the walk
	// had to read them; Uploaded is the chunk bytes actually sent.
	Bytes       int64
	Uploaded    int64
	Reused      int64
	Read        int64
	Torn        int64
	Unreadable  int64
	Skipped     int64
	Checkpoints int64
	// Assumed counts parts skipped because a filter or the previous version
	// held them; Repaired counts those the store then turned out to lack.
	Assumed  int64
	Repaired int64
}

type Walker struct {
	Index   Index
	Objects ObjectStore
	Set     string
	AgentID string
	// Root is the directory backed up, a path of FS.
	Root string

	// FS is the tree Root is read from; nil means LocalFS. A run on any
	// other FS takes no Growing files.
	FS FS

	// Metadata is recorded on the commit; the store keeps it and never
	// interprets it.
	Metadata map[string]string

	// Stream, when set, is backed up instead of Root. A stream cannot be
	// read again, so a run with one does not retry a lost session.
	Stream *Stream

	// Carry, when set, keeps every entry of the previous commit's root that
	// is gone from the disk and for which it returns true, so a set can
	// accumulate files that leave the disk once committed. A run with Carry
	// fails with ErrSealChanged over a commit sealed under another key or
	// none.
	Carry func(name string) bool

	// Subdir, when set, puts Root's entries in the directory of that name
	// in the commit's root instead of in the root itself. Carry then applies
	// inside it, and to the previous commit's other root entries. A run with
	// Subdir writes no checkpoints.
	Subdir string

	// Include decides per slash-separated relative path; nil includes all.
	Include func(rel string) bool

	// Growing are files of the root, or of Subdir when it is set, committed
	// up to a length, continuing the previous commit's versions; a run with
	// Stream takes none.
	Growing []Growing

	// Key seals names and blobs; nil backs up in the clear.
	Key *storekey.Key

	// Logger is where the walk reports; nil means slog.Default.
	Logger *slog.Logger

	// Progress, when set, is handed the counters every ProgressInterval
	// while the walk runs, and once more when it ends. It is called from
	// a goroutine of its own and must not block for long.
	Progress func(WalkResult)
	// ProgressInterval is how often Progress hears; zero means
	// DefaultProgressInterval.
	ProgressInterval time.Duration

	// Sessions, when set, wraps the run in a session, so nothing it uploads
	// is visible to others before its commit.
	Sessions SessionStore

	// Verify reads every file, even one the change test would reuse, which
	// catches a write that kept a file's mtime and size.
	Verify bool

	Workers int
	// ForceHashPercent is the share of reused files re-hashed as a check;
	// ignored on an FS whose Traits do not allow a Reread.
	ForceHashPercent   int
	CheckpointInterval time.Duration
	ReadRetries        int

	// LostRetries is how often a commit refused with ErrSessionLost is
	// retried by walking again in the same session.
	LostRetries int

	// ScanWorkers is how many directories are listed ahead of the walk at
	// once; zero means DefaultScanWorkers and a negative number lists every
	// directory on the walk itself.
	ScanWorkers int
	// ScanWindow bounds the entries held for directories the walk has not
	// reached yet; zero means DefaultScanWindow.
	ScanWindow int

	// Quiesced records that a pre hook paused the application before the
	// walk; a clean run then commits as consistent.
	Quiesced bool
	// Cache is consulted only on an FS whose Traits carry Identity.
	Cache         StatCache
	PrefetchDepth uint32

	// WindowBytes bounds the chunk bytes kept for files whose skipped parts
	// the store has not confirmed yet; 0 means DefaultWindowBytes.
	WindowBytes int

	// BlobCache, when set, receives every uploaded blob.
	BlobCache *blobcache.Cache
	// contains filtered or unexported fields
}

type WriteFS interface {
	Join(dir, name string) string
	// Split is path's directory and its last element, which Join puts back
	// together.
	Split(path string) (dir, name string)
	Lstat(ctx context.Context, path string) (os.FileInfo, error)
	// ReadDir lists dir without following symlinks; a restore lists only
	// to delete what its tree does not hold.
	ReadDir(ctx context.Context, dir string) ([]fs.DirEntry, error)
	// MkdirAll makes dir and the directories above it that are missing.
	MkdirAll(ctx context.Context, dir string) error
	// WriteFile writes what r holds to path, front to back, replacing a
	// file there.
	WriteFile(ctx context.Context, path string, r io.Reader) (int64, error)
	// Rename moves from to to, replacing a file there.
	Rename(ctx context.Context, from, to string) error
	Remove(ctx context.Context, path string) error
	RemoveAll(ctx context.Context, path string) error
	Symlink(ctx context.Context, target, path string) error
	Readlink(ctx context.Context, path string) (string, error)
	// Chmod sets the permission, setuid, setgid and sticky bits of mode.
	Chmod(ctx context.Context, path string, mode os.FileMode) error
	Chtimes(ctx context.Context, path string, mtime time.Time) error
}