backup

package
v0.8.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 30 Imported by: 0

Documentation

Overview

Package backup makes a ZIP of a server's data and metadata, and puts one back. An archive is treated as hostile the whole way through, even one this server made: it may have been changed since, or come from someone else.

Making one needs nothing stopped: the database is copied with VACUUM INTO. Bringing one back happens in two steps, as with a reset: it's checked and unpacked beside the data while the server runs, and the swap is made as the server next starts, before anything has these files open. What was there before is moved aside first, and is moved back if anything goes wrong.

Code is never part of a backup. Modules, game cores and helpers come from their signed releases, so an archive can't put a program on this machine.

Index

Constants

View Source
const (
	ManifestName = "manifest.json"
	ReadmeName   = "README.txt"
	PayloadName  = "payload.wmsenc" // the whole inner archive, when protected with a password

)

File names inside an archive.

View Source
const (
	PartLibrary    = "library"
	PartSettings   = "settings"
	PartUsers      = "users"
	PartHistory    = "history"
	PartChannels   = "channels"
	PartArtwork    = "artwork"
	PartModules    = "modules"
	PartMetaFiles  = "metadatafiles"
	PartLyrics     = "lyrics"
	PartRecordings = "recordings"
)

The parts, in the order they're offered.

View Source
const DirName = "backups"

DirName is the folder in the data folder that holds backups. A reset leaves it alone.

View Source
const FormatVersion = 1

FormatVersion is the layout of an archive. An archive with a higher one is refused.

View Source
const (

	// MinPassword is the shortest password accepted.
	MinPassword = 8
)

Variables

View Source
var ErrPasswordNeeded = errors.New("this backup is protected: enter its password")

ErrPasswordNeeded: this archive is protected and no password was given.

Functions

func AskUndo

func AskUndo(f Folders, name string) error

AskUndo asks the next start to put a safety copy back.

func Cancel

func Cancel(f Folders) (bool, error)

Cancel takes back a restore that hasn't happened yet.

func CleanParts

func CleanParts(ids []string) ([]string, error)

CleanParts checks a list of part IDs against what exists, and returns it in order.

func CountUploads

func CountUploads(f Folders, prefix string) int

CountUploads says how many files with this start to their name are waiting in the folder.

func DefaultParts

func DefaultParts() []string

DefaultParts are those on unless someone says otherwise.

func Delete

func Delete(f Folders, name string) error

Delete removes a backup from the folder.

func Interrupted

func Interrupted(f Folders) string

Interrupted names a safety copy from a restore that was cut off part way, or says "". The next start puts it back.

func IsWrongPassword

func IsWrongPassword(err error) bool

IsWrongPassword says whether an error is a password that didn't open it.

func Prune

func Prune(f Folders, keep int) (removed []string)

Prune keeps the newest few scheduled backups. Ones someone made by hand are theirs.

func Refused

func Refused(file, reason string) error

Refused makes one.

func ValidName

func ValidName(name string) bool

ValidName says whether a name is one of this folder's backups, and nothing cleverer.

Types

type AccountInfo

type AccountInfo struct {
	Name  string `json:"name"`
	Admin bool   `json:"admin"`
	Kind  string `json:"kind,omitempty"`
}

AccountInfo says who'd be able to sign in afterwards.

type CryptHeader

type CryptHeader struct {
	Alg       string `json:"alg"`
	KDF       string `json:"kdf"`
	Time      uint32 `json:"time"`
	MemoryKiB uint32 `json:"memoryKiB"`
	Threads   uint8  `json:"threads"`
	Salt      string `json:"salt"`
	Prefix    string `json:"noncePrefix"`
	Chunk     int    `json:"chunk"`
}

CryptHeader is how a payload is protected, and isn't secret.

type FileEntry

type FileEntry struct {
	Path   string `json:"path"`
	Part   string `json:"part"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

FileEntry is one file in an archive.

type Folders

type Folders struct {
	Data   string
	Images string // artwork; usually <data>/cache/images
}

Folders are where the things a backup covers live.

func (Folders) Dir

func (f Folders) Dir() string

Dir is the backups folder.

func (Folders) PathOf

func (f Folders) PathOf(name string) (string, error)

PathOf finds a backup by name.

type Info

type Info struct {
	Name      string    `json:"name"`
	Size      int64     `json:"size"`
	Created   time.Time `json:"created"`
	Auto      bool      `json:"auto"`
	Protected bool      `json:"protected"`
	Version   string    `json:"version,omitempty"`
}

Info is a backup kept on this server.

func List

func List(f Folders) []Info

List returns the backups in the folder, newest first.

type Inspection

type Inspection struct {
	Name          string        `json:"name"`
	Size          int64         `json:"size"`
	ServerVersion string        `json:"serverVersion"`
	Created       time.Time     `json:"created"`
	Protected     bool          `json:"protected"`
	Older         bool          `json:"older"` // made with an older database, which is brought up to date
	Parts         []PartContent `json:"parts"`
	Accounts      []AccountInfo `json:"accounts"`
	Libraries     []LibraryInfo `json:"libraries"`
	Addresses     []string      `json:"addresses"`  // places on the network this backup would make the server contact
	Dropped       []string      `json:"dropped"`    // what won't be taken from it, and why
	HandEdited    []string      `json:"handEdited"` // metadata files changed since it was made
	Problems      []string      `json:"problems"`   // file:line, in those files
	Notes         []string      `json:"notes"`
	Needed        int64         `json:"needed"` // disk space to unpack it
	// contains filtered or unexported fields
}

Inspection is what a check of an archive found: all a person needs to decide, and what's needed to carry on. Nothing has been touched when it's made.

func Inspect

func Inspect(ctx context.Context, archive, password string, f Folders, progress func(Step)) (in *Inspection, err error)

Inspect checks an archive from end to end. It verifies, and touches nothing outside its own work folder. A bad archive returns a *Refusal, a wrong password errWrongPassword.

func (*Inspection) Close

func (in *Inspection) Close()

Close removes what checking left behind.

func (*Inspection) Stage

func (in *Inspection) Stage(ctx context.Context, f Folders, o StageOptions) (*Request, error)

Stage unpacks a checked archive beside the data, and writes the request. Nothing a running server uses is touched: until the next start, this can be taken back.

type Key

type Key struct {
	Secret    []byte `json:"secret"`
	Salt      []byte `json:"salt"`
	Time      uint32 `json:"time"`
	MemoryKiB uint32 `json:"memoryKiB"`
	Threads   uint8  `json:"threads"`
}

Key is what a password turned into, for use later without keeping the password. A schedule keeps one. It opens archives made with it, so it's a secret like any other.

func DeriveKey

func DeriveKey(password string) (*Key, error)

DeriveKey makes a key from a password with a new salt.

type LibraryInfo

type LibraryInfo struct {
	Name    string   `json:"name"`
	Type    string   `json:"type"`
	Folders []string `json:"folders"`
	Items   int64    `json:"items"`
}

LibraryInfo says which folders on this machine the server would be pointed at.

type Manifest

type Manifest struct {
	Format        int           `json:"format"`
	App           string        `json:"app"`
	ServerVersion string        `json:"serverVersion"`
	Created       time.Time     `json:"created"`
	Schema        db.Versions   `json:"schema"`
	Protected     bool          `json:"protected"`       // made with a password, and holds secrets
	Auto          bool          `json:"auto,omitempty"`  // made by the schedule
	Parts         []PartSummary `json:"parts"`           // what was asked for and found
	Files         []FileEntry   `json:"files,omitempty"` // left out of the outer manifest of a protected archive
	DataDir       string        `json:"dataDir,omitempty"`
	Crypt         *CryptHeader  `json:"crypt,omitempty"` // how the payload is protected
}

Manifest describes an archive: what made it, what's in it, and a hash of each file. The hashes catch damage. They can't prove nobody changed the archive on purpose, as anyone can write new ones: only a password can do that.

func Create

func Create(ctx context.Context, o Options) (out string, man *Manifest, err error)

Create makes an archive, and returns its path. Everything happens in a temporary file beside it, so a backup that fails or is cancelled leaves nothing that looks like one.

type Options

type Options struct {
	Folders Folders
	Parts   []string
	// LiveDB is the running server's database. Without it, the file is opened to read.
	LiveDB *sql.DB
	// Password or Key protects the archive. With neither, secrets are left out.
	Password string
	Key      *Key
	// SecretSettings are settings that hold keys and passwords, on top of those that
	// look like it by their name.
	SecretSettings []string
	ServerVersion  string
	Auto           bool
	// Output is the archive's path. Empty: a new name in the backups folder.
	Output string
	// Progress is told how far along it is. It may be nil.
	Progress func(Step)
	// Problem is told about something left out that the backup carries on without.
	Problem func(file, why string)
}

Options say what to make.

type Part

type Part struct {
	ID        string   `json:"id"`
	Label     string   `json:"label"`
	Desc      string   `json:"desc"`
	Default   bool     `json:"default"`
	Needs     []string `json:"needs,omitempty"` // parts it makes no sense without
	HasTables bool     `json:"hasTables,omitempty"`
}

Part is one of the things a backup can hold.

func Parts

func Parts() []Part

Parts lists them. Lyrics corrections and recordings are left out unless asked for.

type PartContent

type PartContent struct {
	ID       string   `json:"id"`
	Label    string   `json:"label"`
	Desc     string   `json:"desc"`
	Files    int      `json:"files"`
	Bytes    int64    `json:"bytes"`
	Rows     int64    `json:"rows"`
	Needs    []string `json:"needs,omitempty"`
	HasFiles bool     `json:"hasFiles"`
}

PartContent is one part of what's inside.

type PartSize

type PartSize struct {
	Part
	Files int   `json:"files"`
	Bytes int64 `json:"bytes"`
}

PartSize is an estimate for the page that asks what to include.

func Estimate

func Estimate(ctx context.Context, f Folders, live *sql.DB) []PartSize

Estimate says about how large each part is, before compression. It reads no file contents, only the folder listings and the database's size.

type PartSummary

type PartSummary struct {
	ID    string `json:"id"`
	Files int    `json:"files"`
	Bytes int64  `json:"bytes"`
}

PartSummary is what the manifest says about one part.

type Refusal

type Refusal struct {
	File   string `json:"file,omitempty"`
	Reason string `json:"reason"`
}

Refusal says why an archive won't be used, in words for the person holding it.

func (*Refusal) Error

func (r *Refusal) Error() string

type Request

type Request struct {
	Mode  string    `json:"mode"` // restore or undo
	Parts []string  `json:"parts,omitempty"`
	HasDB bool      `json:"hasDB"`
	Copy  string    `json:"copy,omitempty"` // undo: the safety copy to bring back
	Name  string    `json:"name,omitempty"` // the archive it came from
	At    time.Time `json:"at"`
}

Request is what the next start is to do.

func Pending

func Pending(f Folders) *Request

Pending says what's waiting for the next start, or nil.

type Result

type Result struct {
	OK     bool      `json:"ok"`
	Mode   string    `json:"mode"`
	Name   string    `json:"name,omitempty"`
	Parts  []string  `json:"parts,omitempty"`
	Safety string    `json:"safety,omitempty"` // the safety copy, by name
	Error  string    `json:"error,omitempty"`
	Notes  []string  `json:"notes,omitempty"`
	At     time.Time `json:"at"`
}

Result says how it went.

func Apply

func Apply(f Folders) *Result

Apply carries out what's waiting. It returns nil when nothing was. On any failure, everything is put back as it was, and the server starts as usual.

func Last

func Last(f Folders) *Result

Last says how the last restore went, or nil.

type SafetyCopy

type SafetyCopy struct {
	Name string    `json:"name"`
	At   time.Time `json:"at"`
}

SafetyCopy is one kept from an earlier restore.

func SafetyCopies

func SafetyCopies(f Folders) []SafetyCopy

SafetyCopies lists what earlier restores moved aside, newest first.

type StageOptions

type StageOptions struct {
	Parts []string
	// LiveDB is the running server's database, to keep what isn't being restored.
	LiveDB   *sql.DB
	Progress func(Step)
}

StageOptions say what to bring back.

type Step

type Step struct {
	Phase string
	Done  int64
	Total int64
	Item  string
}

Step is progress: which stage, how much of how much, what it's on.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL