beads/cmd/bd/backup_export.go
Rongjun GENG 874e2866ff
fix(backup): anchor watermark before snapshot (#7044)
Record the commit read before BackupToDir as the newest revision guaranteed
to be in the snapshot. A commit landing during sync then remains pending for
the next backup instead of being hidden by an advanced watermark.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Rongjun GENG
2026-10-04 20:01:43 -07:00

216 lines
7.5 KiB
Go

package main
import (
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"time"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/storage"
)
// backupState tracks watermarks for backup change detection.
type backupState struct {
LastDoltCommit string `json:"last_dolt_commit"`
Timestamp time.Time `json:"timestamp"`
LastCapWarnAt time.Time `json:"last_cap_warn_at"`
}
// backupDir returns the backup directory path, creating it if needed.
// When backup.git-repo is set to a valid git repo, returns a backup/ subdirectory
// inside that repo. Otherwise it requires an active beads workspace and uses its
// backup/ subdirectory.
func backupDir() (string, error) {
gitRepo := config.GetString("backup.git-repo")
if gitRepo != "" {
if strings.HasPrefix(gitRepo, "~/") {
home, _ := os.UserHomeDir()
gitRepo = filepath.Join(home, gitRepo[2:])
}
if _, err := os.Stat(filepath.Join(gitRepo, ".git")); err != nil {
fmt.Fprintf(os.Stderr, "Warning: backup.git-repo %s is not a git repo, falling back to .beads/backup\n", gitRepo)
} else {
dir := filepath.Join(gitRepo, "backup")
if err := os.MkdirAll(dir, 0700); err != nil {
return "", fmt.Errorf("failed to create backup dir in git-repo: %w", err)
}
return dir, nil
}
}
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return "", fmt.Errorf("%s; %s", activeWorkspaceNotFoundError(), diagHint())
}
dir := filepath.Join(beadsDir, "backup")
if err := os.MkdirAll(dir, 0700); err != nil {
return "", fmt.Errorf("failed to create backup directory: %w", err)
}
return dir, nil
}
// loadBackupState reads the backup state file, returning a zero state if missing.
func loadBackupState(dir string) (*backupState, error) {
path := filepath.Join(dir, "backup_state.json")
data, err := os.ReadFile(path) //nolint:gosec // path is constructed internally
if os.IsNotExist(err) {
return &backupState{}, nil
}
if err != nil {
return nil, fmt.Errorf("failed to read backup state: %w", err)
}
var state backupState
if err := json.Unmarshal(data, &state); err != nil {
return nil, fmt.Errorf("failed to parse backup state: %w", err)
}
return &state, nil
}
// saveBackupState writes the backup state file atomically.
func saveBackupState(dir string, state *backupState) error {
data, err := json.MarshalIndent(state, "", " ")
if err != nil {
return fmt.Errorf("failed to marshal backup state: %w", err)
}
return atomicWriteFile(filepath.Join(dir, "backup_state.json"), data)
}
// atomicWriteFile writes data to a same-directory temp file, fsyncs the
// temp file's own contents, then renames it into place. This avoids a
// truncated/partial file at path if the process crashes mid-write.
//
// Two caveats this does NOT cover, narrowing the "crash-safe" claim rather
// than the implementation (existing callers' behavior is unchanged here):
// - Only the temp file's contents are fsynced, not the parent directory
// entry; a crash between the rename and a subsequent directory fsync
// can still lose the rename itself on some filesystems.
// - os.Rename's atomic-replace guarantee is a POSIX/Unix property; it is
// not guaranteed on Windows. It also does not follow a symlink at
// path — it replaces whatever is there, symlink or not — so a caller
// that must preserve a symlink's target should resolve path with
// filepath.EvalSymlinks first (see cmd/bd/proxied_server.go).
func atomicWriteFile(path string, data []byte) error {
dir := filepath.Dir(path)
tmp, err := os.CreateTemp(dir, ".backup-tmp-*")
if err != nil {
return fmt.Errorf("failed to create temp file: %w", err)
}
tmpPath := tmp.Name()
if _, err := tmp.Write(data); err != nil {
_ = tmp.Close()
_ = os.Remove(tmpPath)
return fmt.Errorf("failed to write temp file: %w", err)
}
if err := tmp.Sync(); err != nil {
_ = tmp.Close()
_ = os.Remove(tmpPath)
return fmt.Errorf("failed to sync temp file: %w", err)
}
if err := tmp.Close(); err != nil {
_ = os.Remove(tmpPath)
return fmt.Errorf("failed to close temp file: %w", err)
}
if err := os.Rename(tmpPath, path); err != nil {
_ = os.Remove(tmpPath)
return fmt.Errorf("failed to rename temp file: %w", err)
}
return nil
}
// localBackupBackend is what a Dolt-native backup into a local directory needs
// from storage: the commit it would capture, and the backup itself. The direct
// store supplies one (directLocalBackup) and so does the proxied provider
// (proxiedLocalBackup, backup_proxied_server.go).
type localBackupBackend interface {
CurrentCommit(ctx context.Context) (string, error)
BackupToDir(ctx context.Context, dir string) error
}
// directLocalBackup is localBackupBackend over an embedded or sql-server store.
type directLocalBackup struct {
store storage.DoltStorage
}
func (b directLocalBackup) CurrentCommit(ctx context.Context) (string, error) {
return b.store.GetCurrentCommit(ctx)
}
func (b directLocalBackup) BackupToDir(ctx context.Context, dir string) error {
bs, ok := storage.UnwrapStore(b.store).(storage.BackupStore)
if !ok {
return fmt.Errorf("storage backend does not support backup operations")
}
return bs.BackupDatabase(ctx, dir)
}
// runBackupExport performs a Dolt-native backup to .beads/backup/.
// Returns the updated state.
func runBackupExport(ctx context.Context, backend localBackupBackend, force bool) (*backupState, error) {
dir, err := backupDir()
if err != nil {
return nil, err
}
state, err := loadBackupState(dir)
if err != nil {
return nil, err
}
// Read the watermark before the sync. A concurrent commit may land while
// BackupToDir is running; recording a later HEAD would claim that commit is
// present in a snapshot that started before it existed.
currentCommit, err := backend.CurrentCommit(ctx)
if err != nil {
return nil, fmt.Errorf("failed to get current commit: %w", err)
}
// Change detection: skip if nothing changed (unless forced)
if !force {
if currentCommit == state.LastDoltCommit && state.LastDoltCommit != "" {
debug.Logf("backup: no changes since last backup (commit %s)\n", truncateHash(currentCommit))
return state, nil
}
}
if err := backend.BackupToDir(ctx, dir); err != nil {
// Persist the attempt time even on failure so the throttle
// interval (checked by maybeAutoBackup via state.Timestamp)
// applies to the next command. Without this, a sync that keeps
// failing — e.g. a slow/overloaded shared Dolt server — retries
// on EVERY bd command instead of once per interval, turning a
// transient slowdown into a self-amplifying storm (the 2026-07
// shared-dolt CPU-pin incident). LastDoltCommit is deliberately
// left unchanged so change-detection still sees pending work and
// a real backup runs once the failure clears.
state.Timestamp = time.Now().UTC()
if saveErr := saveBackupState(dir, state); saveErr != nil {
debug.Logf("backup: failed to persist throttle state after error: %v\n", saveErr)
}
return nil, err
}
// The pre-sync commit is the newest commit this backup is guaranteed to
// contain. If HEAD moved during the sync, the next backup must see it.
state.LastDoltCommit = currentCommit
state.Timestamp = time.Now().UTC()
if err := saveBackupState(dir, state); err != nil {
return nil, err
}
return state, nil
}
// truncateHash returns the first 8 characters of a hash, or the full string if shorter.
func truncateHash(h string) string {
if len(h) > 8 {
return h[:8]
}
return h
}