Keep personal notes private by default and require review before publishing shared notes. Restore backups and replay forgotten notes in one transaction, and retain the installed release when an unattended rollback could bring back forgotten notes.
281 lines
8.8 KiB
Go
281 lines
8.8 KiB
Go
// Package deletions records deletions outside the database. A restore replaces
|
|
// every row with the snapshot's, so a record that lives only in the database
|
|
// cannot stop it bringing back what was deleted later. Deletions are appended to
|
|
// a file under the state directory, which a restore does not overwrite, and
|
|
// applied again once the snapshot is in place.
|
|
package deletions
|
|
|
|
import (
|
|
"bufio"
|
|
"context"
|
|
json "encoding/json/v2"
|
|
"errors"
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
"slices"
|
|
"strings"
|
|
"sync"
|
|
"time"
|
|
|
|
"github.com/google/uuid"
|
|
"golang.org/x/sys/unix"
|
|
)
|
|
|
|
// File is the deletions file's name inside a state directory.
|
|
const File = "deletions.jsonl"
|
|
|
|
// ErrUnsafeRollback is returned when a restore cannot be shown to leave nothing
|
|
// behind that was deleted. The update transaction reports it as a failed rollback
|
|
// rather than retrying: no attempt can settle it without a person deciding what
|
|
// may come back.
|
|
var ErrUnsafeRollback = errors.New("the snapshot holds notes this database no longer has, and the record cannot account for them")
|
|
|
|
// Entry is one deletion: the record it removed, the organisation it belonged to,
|
|
// and when. Ids are unique, so the record is a set and needs no order.
|
|
type Entry struct {
|
|
Table string `json:"table"`
|
|
OrgID string `json:"org_id"`
|
|
ID uuid.UUID `json:"id"`
|
|
At time.Time `json:"at"`
|
|
}
|
|
|
|
// Path returns the deletions file under stateDir.
|
|
func Path(stateDir string) string { return filepath.Join(stateDir, File) }
|
|
|
|
// Dir resolves the state directory the way the other archie binaries resolve
|
|
// it, so the process that records a deletion and the process that applies it
|
|
// again read one path. A leading ~ is the home directory; an empty value is
|
|
// ${XDG_DATA_HOME:-~/.local/share}/<ARCHIE_INSTANCE or archie>; and a relative
|
|
// path is refused, because two processes with different working directories
|
|
// would otherwise disagree about where the record is.
|
|
func Dir(configured string) (string, error) {
|
|
if configured == "" {
|
|
home, err := dataHome()
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
return filepath.Join(home, instance()), nil
|
|
}
|
|
if configured == "~" || strings.HasPrefix(configured, "~/") {
|
|
home, err := os.UserHomeDir()
|
|
if err != nil {
|
|
return "", fmt.Errorf("resolve the state directory: %w", err)
|
|
}
|
|
configured = filepath.Join(home, strings.TrimPrefix(configured, "~"))
|
|
}
|
|
if !filepath.IsAbs(configured) {
|
|
return "", fmt.Errorf("state_dir %q is relative: name an absolute path, or one starting with ~, so every process reads one directory", configured)
|
|
}
|
|
return filepath.Clean(configured), nil
|
|
}
|
|
|
|
// dataHome is $XDG_DATA_HOME, or the home directory's .local/share.
|
|
func dataHome() (string, error) {
|
|
if dir := os.Getenv("XDG_DATA_HOME"); dir != "" {
|
|
return dir, nil
|
|
}
|
|
home, err := os.UserHomeDir()
|
|
if err != nil {
|
|
return "", fmt.Errorf("resolve the state directory: %w", err)
|
|
}
|
|
return filepath.Join(home, ".local", "share"), nil
|
|
}
|
|
|
|
// instance is the instance name the other archie binaries default to.
|
|
func instance() string {
|
|
if name := os.Getenv("ARCHIE_INSTANCE"); name != "" {
|
|
return name
|
|
}
|
|
return "archie"
|
|
}
|
|
|
|
// Log appends deletions to one file. Each append is flushed: the file exists to
|
|
// outlive the database.
|
|
type Log struct {
|
|
path string
|
|
mu sync.Mutex
|
|
}
|
|
|
|
// NewLog returns a log writing to the file at path.
|
|
func NewLog(path string) *Log { return &Log{path: path} }
|
|
|
|
// Path is the file this log writes.
|
|
func (l *Log) Path() string { return l.path }
|
|
|
|
// Ensure creates the log and its directories if they are missing, and flushes the
|
|
// file. A log that exists but was never written to is how an instance that has not
|
|
// deleted anything yet is told apart from one whose log has been lost; the
|
|
// directories are made durable by Append, which is where an entry is
|
|
// acknowledged.
|
|
func (l *Log) Ensure() error {
|
|
l.mu.Lock()
|
|
defer l.mu.Unlock()
|
|
return l.create()
|
|
}
|
|
|
|
// Exists reports whether the log's file is there.
|
|
func (l *Log) Exists() (bool, error) {
|
|
_, err := os.Stat(l.path)
|
|
switch {
|
|
case err == nil:
|
|
return true, nil
|
|
case errors.Is(err, os.ErrNotExist):
|
|
return false, nil
|
|
default:
|
|
return false, fmt.Errorf("read the deletions log: %w", err)
|
|
}
|
|
}
|
|
|
|
// Append records one deletion, making the entry and the directory entries above
|
|
// it durable before it returns: a power loss after the deletion was acknowledged
|
|
// must not lose the record. The file is locked for the whole append, so a second
|
|
// process sharing the state directory cannot interleave a line with this one.
|
|
func (l *Log) Append(_ context.Context, e Entry) error {
|
|
line, err := json.Marshal(e)
|
|
if err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
l.mu.Lock()
|
|
defer l.mu.Unlock()
|
|
if err := l.create(); err != nil {
|
|
return err
|
|
}
|
|
file, err := os.OpenFile(l.path, os.O_WRONLY|os.O_APPEND, 0o600)
|
|
if err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
defer func() { _ = file.Close() }()
|
|
if err := lockFile(file); err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
defer func() { _ = unlockFile(file) }()
|
|
if _, err := file.Write(append(line, '\n')); err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
if err := file.Sync(); err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
// The entry is durable only once the file's name and the names of the
|
|
// directories above it are, and this process cannot tell which of them another
|
|
// process created without syncing, so the chain is synced whatever created it.
|
|
return SyncFileDirs(l.path)
|
|
}
|
|
|
|
// SyncFileDirs flushes the directories that give a file its name, from its own
|
|
// directory up to the root: a directory's entry is durable only after that
|
|
// directory is synced. The walk ends at the root rather than at a bound, because
|
|
// stopping early would report a durability the caller does not have.
|
|
func SyncFileDirs(path string) error {
|
|
dir := filepath.Dir(path)
|
|
if !filepath.IsAbs(dir) {
|
|
return fmt.Errorf("sync %s: the path is relative, so the walk up to the root has no end", path)
|
|
}
|
|
for {
|
|
if err := syncDir(dir); err != nil {
|
|
return err
|
|
}
|
|
parent := filepath.Dir(dir)
|
|
if parent == dir {
|
|
return nil
|
|
}
|
|
dir = parent
|
|
}
|
|
}
|
|
|
|
// create opens the log's file, creating it and its directories if they are
|
|
// missing, and flushes the file itself. The entries that name the file and its
|
|
// directories are not made durable here: Append does that for the whole chain,
|
|
// since it cannot tell which of them this process created.
|
|
func (l *Log) create() error {
|
|
if err := makeDirs(filepath.Dir(l.path)); err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
file, err := os.OpenFile(l.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
|
|
if err != nil {
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
if err := file.Sync(); err != nil {
|
|
_ = file.Close()
|
|
return fmt.Errorf("record deletion: %w", err)
|
|
}
|
|
return file.Close()
|
|
}
|
|
|
|
// makeDirs creates dir and any missing parents.
|
|
func makeDirs(dir string) error {
|
|
var missing []string
|
|
for at := dir; ; at = filepath.Dir(at) {
|
|
if _, err := os.Stat(at); err == nil {
|
|
break
|
|
} else if !errors.Is(err, os.ErrNotExist) {
|
|
return err
|
|
}
|
|
missing = append(missing, at)
|
|
if parent := filepath.Dir(at); parent == at {
|
|
break
|
|
}
|
|
}
|
|
for _, m := range slices.Backward(missing) {
|
|
if err := os.Mkdir(m, 0o700); err != nil && !errors.Is(err, os.ErrExist) {
|
|
return err
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// syncDir flushes a directory, which is what makes the entries it holds durable.
|
|
func syncDir(dir string) error {
|
|
handle, err := os.Open(dir) //nolint:gosec // a directory this package created or was configured with.
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer func() { _ = handle.Close() }()
|
|
return handle.Sync()
|
|
}
|
|
|
|
// Entries reads every recorded deletion. A missing file holds none.
|
|
func (l *Log) Entries() ([]Entry, error) {
|
|
file, err := os.Open(l.path) //nolint:gosec // the path is the state directory this instance configured.
|
|
if errors.Is(err, os.ErrNotExist) {
|
|
return nil, nil
|
|
}
|
|
if err != nil {
|
|
return nil, fmt.Errorf("read deletions: %w", err)
|
|
}
|
|
defer func() { _ = file.Close() }()
|
|
return readEntries(file)
|
|
}
|
|
|
|
// readEntries decodes the file's lines in the order it holds them.
|
|
func readEntries(file *os.File) ([]Entry, error) {
|
|
var out []Entry
|
|
scanner := bufio.NewScanner(file)
|
|
for scanner.Scan() {
|
|
line := scanner.Bytes()
|
|
if len(line) == 0 {
|
|
continue
|
|
}
|
|
var e Entry
|
|
if err := json.Unmarshal(line, &e); err != nil {
|
|
return nil, fmt.Errorf("read deletions: %w", err)
|
|
}
|
|
out = append(out, e)
|
|
}
|
|
if err := scanner.Err(); err != nil {
|
|
return nil, fmt.Errorf("read deletions: %w", err)
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// lockFile takes the exclusive advisory lock on the record, for the length of one
|
|
// append or one read-modify-write.
|
|
func lockFile(file *os.File) error {
|
|
return unix.Flock(int(file.Fd()), unix.LOCK_EX)
|
|
}
|
|
|
|
// unlockFile releases the lock lockFile took.
|
|
func unlockFile(file *os.File) error {
|
|
return unix.Flock(int(file.Fd()), unix.LOCK_UN)
|
|
}
|