package backend import ( "context" "hash" "io" ) // Backend is used to store and access data. // // Backend operations that return an error will be retried when a Backend is // wrapped in a RetryBackend. To prevent that from happening, the operations // should return a github.com/cenkalti/backoff/v4.PermanentError. Errors from // the context package need not be wrapped, as context cancellation is checked // separately by the retrying logic. type Backend interface { // Location returns a string that describes the type and location of the // repository. Location() string // Connections returns the maximum number of concurrent backend operations. Connections() uint // Hasher may return a hash function for calculating a content hash for the backend Hasher() hash.Hash // HasAtomicReplace returns whether Save() can atomically replace files HasAtomicReplace() bool // Remove removes a File described by h. Remove(ctx context.Context, h Handle) error // Close the backend Close() error // Save stores the data from rd under the given handle. Save(ctx context.Context, h Handle, rd RewindReader) error // Load runs fn with a reader that yields the contents of the file at h at the // given offset. If length is larger than zero, only a portion of the file // is read. If the length is larger than zero and the file is too short to return // the requested length bytes, then an error MUST be returned that is recognized // by IsPermanentError(). // // The function fn may be called multiple times during the same Load invocation // and therefore must be idempotent. // // Implementations are encouraged to use util.DefaultLoad Load(ctx context.Context, h Handle, length int, offset int64, fn func(rd io.Reader) error) error // Stat returns information about the File identified by h. Stat(ctx context.Context, h Handle) (FileInfo, error) // List runs fn for each file in the backend which has the type t. When an // error occurs (or fn returns an error), List stops and returns it. // // The function fn is called exactly once for each file during successful // execution and at most once in case of an error. // // The function fn is called in the same Goroutine that List() is called // from. List(ctx context.Context, t FileType, fn func(FileInfo) error) error // IsNotExist returns true if the error was caused by a non-existing file // in the backend. // // The argument may be a wrapped error. The implementation is responsible // for unwrapping it. IsNotExist(err error) bool // IsPermanentError returns true if the error can very likely not be resolved // by retrying the operation. Backends should return true if the file is missing, // the requested range does not (completely) exist in the file or the user is // not authorized to perform the requested operation. IsPermanentError(err error) bool // Delete removes all data in the backend. Delete(ctx context.Context) error } type Unwrapper interface { // Unwrap returns the underlying backend or nil if there is none. Unwrap() Backend } func AsBackend[B Backend](b Backend) B { for b != nil { if be, ok := b.(B); ok { return be } if be, ok := b.(Unwrapper); ok { b = be.Unwrap() } else { // not the backend we're looking for break } } var be B return be } type FreezeBackend interface { Backend // Freeze blocks all backend operations except those on lock files Freeze() // Unfreeze allows all backend operations to continue Unfreeze() } // FileInfo is contains information about a file in the backend. type FileInfo struct { Size int64 Name string } // ApplyEnvironmenter fills in a backend configuration from the environment type ApplyEnvironmenter interface { ApplyEnvironment(prefix string) }