backend

Documentation

Overview

Package backend provides local and remote storage for restic repositories. All backends need to implement the Backend interface. There is a MemBackend, which stores all data in a map internally and can be used for testing.

Index

• Variables
• func AsBackend[B Backend](b Backend) B
• func ReadAt(ctx context.Context, be Backend, h Handle, offset int64, p []byte) (n int, err error)
• func ReaderAt(ctx context.Context, be Backend, h Handle) io.ReaderAt
• func SplitShellStrings(data string) (strs []string, err error)
• func Transport(opts TransportOptions) (http.RoundTripper, error)
• type ApplyEnvironmenter
• type Backend
• type ByteReader
  • func NewByteReader(buf []byte, hasher hash.Hash) *ByteReader
  • func (b *ByteReader) Hash() []byte
  • func (b *ByteReader) Length() int64
  • func (b *ByteReader) Rewind() error
• type FileInfo
• type FileReader
  • func NewFileReader(f io.ReadSeeker, hash []byte) (*FileReader, error)
  • func (f *FileReader) Hash() []byte
  • func (f *FileReader) Length() int64
  • func (f *FileReader) Rewind() error
• type FileType
  • func (t FileType) String() string
• type FreezeBackend
• type Handle
  • func (h Handle) String() string
  • func (h Handle) Valid() error
• type RewindReader
• type TransportOptions
• type Unwrapper

Variables

var ErrNoRepository = fmt.Errorf("repository does not exist")

Functions

func AsBackend

func AsBackend[B Backend](b Backend) B

func ReadAt

func ReadAt(ctx context.Context, be Backend, h Handle, offset int64, p []byte) (n int, err error)

ReadAt reads from the backend handle h at the given position.

func ReaderAt

func ReaderAt(ctx context.Context, be Backend, h Handle) io.ReaderAt

ReaderAt returns an io.ReaderAt for a file in the backend. The returned reader should not escape the caller function to avoid unexpected interactions with the embedded context

func SplitShellStrings

func SplitShellStrings(data string) (strs []string, err error)

SplitShellStrings returns the list of shell strings from a shell command string.

func Transport

func Transport(opts TransportOptions) (http.RoundTripper, error)

Transport returns a new http.RoundTripper with default settings applied. If a custom rootCertFilename is non-empty, it must point to a valid PEM file, otherwise the function will return an error.

Types

type ApplyEnvironmenter

type ApplyEnvironmenter interface {
	ApplyEnvironment(prefix string)
}

ApplyEnvironmenter fills in a backend configuration from the environment

type Backend

type Backend interface {
	// 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
}

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 ByteReader

type ByteReader struct {
	*bytes.Reader
	Len int64
	// contains filtered or unexported fields
}

ByteReader implements a RewindReader for a byte slice.

func NewByteReader

func NewByteReader(buf []byte, hasher hash.Hash) *ByteReader

NewByteReader prepares a ByteReader that can then be used to read buf.

func (*ByteReader) Hash

func (b *ByteReader) Hash() []byte

Hash return a hash of the data if requested by the backed.

func (*ByteReader) Length

func (b *ByteReader) Length() int64

Length returns the number of bytes read from the reader after Rewind is called.

func (*ByteReader) Rewind

func (b *ByteReader) Rewind() error

Rewind restarts the reader from the beginning of the data.

type FileInfo

type FileInfo struct {
	Size int64
	Name string
}

FileInfo is contains information about a file in the backend.

type FileReader

type FileReader struct {
	io.ReadSeeker
	Len int64
	// contains filtered or unexported fields
}

FileReader implements a RewindReader for an open file.

func NewFileReader

func NewFileReader(f io.ReadSeeker, hash []byte) (*FileReader, error)

NewFileReader wraps f in a *FileReader.

func (*FileReader) Hash

func (f *FileReader) Hash() []byte

Hash return a hash of the data if requested by the backed.

func (*FileReader) Length

func (f *FileReader) Length() int64

Length returns the length of the file.

func (*FileReader) Rewind

func (f *FileReader) Rewind() error

Rewind seeks to the beginning of the file.

type FileType

type FileType uint8

FileType is the type of a file in the backend.

const (
	PackFile FileType = 1 + iota
	KeyFile
	LockFile
	SnapshotFile
	IndexFile
	ConfigFile
)

These are the different data types a backend can store.

func (FileType) String

func (t FileType) String() string

type FreezeBackend

type FreezeBackend interface {
	Backend
	// Freeze blocks all backend operations except those on lock files
	Freeze()
	// Unfreeze allows all backend operations to continue
	Unfreeze()
}

type Handle

type Handle struct {
	Type       FileType
	IsMetadata bool
	Name       string
}

Handle is used to store and access data in a backend.

func (Handle) String

func (h Handle) String() string

func (Handle) Valid

func (h Handle) Valid() error

Valid returns an error if h is not valid.

type RewindReader

type RewindReader interface {
	io.Reader

	// Rewind rewinds the reader so the same data can be read again from the
	// start.
	Rewind() error

	// Length returns the number of bytes that can be read from the Reader
	// after calling Rewind.
	Length() int64

	// Hash return a hash of the data if requested by the backed.
	Hash() []byte
}

RewindReader allows resetting the Reader to the beginning of the data.

type TransportOptions

type TransportOptions struct {
	// contains filenames of PEM encoded root certificates to trust
	RootCertFilenames []string

	// contains the name of a file containing the TLS client certificate and private key in PEM format
	TLSClientCertKeyFilename string

	// Skip TLS certificate verification
	InsecureTLS bool

	// Specify Custom User-Agent for the http Client
	HTTPUserAgent string
}

TransportOptions collects various options which can be set for an HTTP based transport.

type Unwrapper

type Unwrapper interface {
	// Unwrap returns the underlying backend or nil if there is none.
	Unwrap() Backend
}