backup: add boxbackup

Added impl of box.backup.start/info/stop over net.box.

Closes TNTP-8389

Author: sssciel

lib/backup/boxbackup/boxbackup.go

@@ -0,0 +1,100 @@
+// Package boxbackup is a thin net.box client over the core box.backup.* API.
+// It wraps start/info/stop and maps the info() response into Go types.
+// Recovery points are created by the vshard role; tt only reads them here.
+package boxbackup
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/mitchellh/mapstructure"
+
+	"github.com/tarantool/tt/cli/connector"
+	"github.com/tarantool/tt/lib/backup"
+)
+
+const defaultTTL = time.Hour
+
+// StartOpts are the parameters of box.backup.start({from_vclock, ttl}).
+type StartOpts struct {
+	// FromVclock selects an incremental backup, nil means a full backup.
+	FromVclock backup.Vclock
+	// TTL is the backup lease duration.
+	TTL time.Duration
+}
+
+// Info is the decoded result of box.backup.info().
+type Info struct {
+	Files          []string                `json:"files"`
+	Type           backup.BackupType       `json:"type"`
+	VclockBegin    backup.Vclock           `json:"vclock_begin"`
+	VclockEnd      backup.Vclock           `json:"vclock_end"`
+	RecoveryPoints *[]backup.RecoveryPoint `json:"recovery_points"`
+}
+
+// Start runs box.backup.start({) on the instance.
+func Start(conn connector.Connector, opts StartOpts) error {
+	ttl := opts.TTL
+	if ttl == 0 {
+		ttl = defaultTTL
+	}
+
+	args := map[string]any{"ttl": ttl.Seconds()}
+	if opts.FromVclock != nil {
+		args["from_vclock"] = map[uint32]uint64(opts.FromVclock)
+	}
+
+	_, err := conn.Eval("box.backup.start(...)", []any{args}, connector.RequestOpts{})
+	if err != nil {
+		return fmt.Errorf("failed to start backup: %w", err)
+	}
+
+	return nil
+}
+
+// GetInfo runs box.backup.info().
+func GetInfo(conn connector.Connector) (*Info, error) {
+	res, err := conn.Eval("return box.backup.info()", []any{}, connector.RequestOpts{})
+	if err != nil {
+		return nil, fmt.Errorf("failed to get backup info: %w", err)
+	}
+	if len(res) == 0 || res[0] == nil {
+		return nil, nil
+	}
+
+	var info Info
+	decoder, err := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+		TagName:          "json",
+		WeaklyTypedInput: true,
+		Result:           &info,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse backup info: %w", err)
+	}
+	if err := decoder.Decode(res[0]); err != nil {
+		return nil, fmt.Errorf("failed to parse backup info: %w", err)
+	}
+
+	// mapstructure cannot tell an absent field from an empty list, so the
+	// recovery_points state is resolved by hand.
+	raw, ok := res[0].(map[any]any)
+	if ok {
+		if _, present := raw["recovery_points"]; !present {
+			info.RecoveryPoints = nil
+		} else if info.RecoveryPoints == nil {
+			info.RecoveryPoints = &[]backup.RecoveryPoint{}
+		}
+	}
+
+	return &info, nil
+}
+
+// Stop runs box.backup.stop().
+func Stop(conn connector.Connector) error {
+	_, err := conn.Eval("box.backup.stop()", []any{}, connector.RequestOpts{})
+	if err != nil {
+		return fmt.Errorf("failed to stop backup: %w", err)
+	}
+
+	return nil
+}

lib/backup/boxbackup/boxbackup_test.go

@@ -0,0 +1,185 @@
+package boxbackup
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/tarantool/tt/cli/connector"
+	"github.com/tarantool/tt/lib/backup"
+)
+
+type mockEvaler struct {
+	exprs []string
+	args  []any
+	ret   []any
+	queue [][]any
+	err   error
+	calls int
+}
+
+func (m *mockEvaler) Eval(expr string, args []any,
+	opts connector.RequestOpts,
+) ([]any, error) {
+	m.exprs = append(m.exprs, expr)
+	m.args = args
+	m.calls++
+	if m.queue != nil {
+		return m.queue[m.calls-1], m.err
+	}
+
+	return m.ret, m.err
+}
+
+func (m *mockEvaler) Close() error { return nil }
+
+// expr returns the expression of the last recorded Eval call.
+func (m *mockEvaler) expr() string {
+	if len(m.exprs) == 0 {
+		return ""
+	}
+
+	return m.exprs[len(m.exprs)-1]
+}
+
+func TestStart_full(t *testing.T) {
+	m := &mockEvaler{}
+
+	require.NoError(t, Start(m, StartOpts{}))
+	require.Equal(t, "box.backup.start(...)", m.expr())
+
+	require.Len(t, m.args, 1)
+	got := m.args[0].(map[string]any)
+	require.Equal(t, defaultTTL.Seconds(), got["ttl"])
+	_, hasFromVclock := got["from_vclock"]
+	require.False(t, hasFromVclock, "full backup must not send from_vclock")
+}
+
+func TestStart_incremental(t *testing.T) {
+	m := &mockEvaler{}
+
+	err := Start(m, StartOpts{FromVclock: backup.Vclock{1: 42}})
+	require.NoError(t, err)
+
+	got := m.args[0].(map[string]any)
+	require.Equal(t, map[uint32]uint64{1: 42}, got["from_vclock"])
+}
+
+func TestStart_customTTL(t *testing.T) {
+	m := &mockEvaler{}
+
+	require.NoError(t, Start(m, StartOpts{TTL: 30 * time.Minute}))
+	got := m.args[0].(map[string]any)
+	require.Equal(t, float64(1800), got["ttl"])
+}
+
+func TestStart_error(t *testing.T) {
+	m := &mockEvaler{err: errors.New("boom")}
+
+	err := Start(m, StartOpts{})
+	require.ErrorContains(t, err, "failed to start backup")
+	require.ErrorContains(t, err, "boom")
+}
+
+func TestGetInfo_noBackup(t *testing.T) {
+	m := &mockEvaler{ret: []any{nil}}
+
+	info, err := GetInfo(m)
+	require.NoError(t, err)
+	require.Nil(t, info)
+}
+
+func TestGetInfo_allFields(t *testing.T) {
+	m := &mockEvaler{ret: []any{map[any]any{
+		"files":        []any{"0.snap", "0.xlog"},
+		"type":         "full",
+		"vclock_begin": map[any]any{uint64(0): uint64(1)},
+		"vclock_end":   map[any]any{uint64(0): uint64(5), uint64(1): uint64(9)},
+		"recovery_points": []any{map[any]any{
+			"uuid": "rp-1", "replica_id": uint64(1),
+			"lsn": uint64(7), "timestamp": uint64(123),
+		}},
+	}}}
+
+	info, err := GetInfo(m)
+	require.NoError(t, err)
+	require.Equal(t, []string{"0.snap", "0.xlog"}, info.Files)
+	require.Equal(t, backup.BackupTypeFull, info.Type)
+	require.Equal(t, backup.Vclock{0: 1}, info.VclockBegin)
+	require.Equal(t, backup.Vclock{0: 5, 1: 9}, info.VclockEnd)
+	require.NotNil(t, info.RecoveryPoints)
+	require.Len(t, *info.RecoveryPoints, 1)
+	rp := (*info.RecoveryPoints)[0]
+	require.Equal(t, "rp-1", rp.UUID)
+	require.Equal(t, uint32(1), rp.ReplicaID)
+	require.Equal(t, uint64(7), rp.LSN)
+	require.Equal(t, int64(123), rp.Timestamp)
+}
+
+func TestGetInfo_recoveryPointsAbsent(t *testing.T) {
+	m := &mockEvaler{ret: []any{map[any]any{"type": "full"}}}
+
+	info, err := GetInfo(m)
+	require.NoError(t, err)
+	require.Nil(t, info.RecoveryPoints, "absent field must map to nil")
+}
+
+func TestGetInfo_recoveryPointsEmpty(t *testing.T) {
+	m := &mockEvaler{ret: []any{map[any]any{
+		"type":            "full",
+		"recovery_points": []any{},
+	}}}
+
+	info, err := GetInfo(m)
+	require.NoError(t, err)
+	require.NotNil(t, info.RecoveryPoints, "empty list must be non-nil")
+	require.Empty(t, *info.RecoveryPoints)
+}
+
+func TestGetInfo_error(t *testing.T) {
+	m := &mockEvaler{err: errors.New("boom")}
+
+	_, err := GetInfo(m)
+	require.ErrorContains(t, err, "failed to get backup info")
+}
+
+func TestStop_ok(t *testing.T) {
+	m := &mockEvaler{}
+
+	require.NoError(t, Stop(m))
+	require.Equal(t, "box.backup.stop()", m.expr())
+}
+
+func TestStop_error(t *testing.T) {
+	m := &mockEvaler{err: errors.New("boom")}
+
+	err := Stop(m)
+	require.ErrorContains(t, err, "failed to stop backup")
+	require.ErrorContains(t, err, "boom")
+}
+
+func TestStartInfoStop(t *testing.T) {
+	m := &mockEvaler{queue: [][]any{
+		nil, // start()
+		{map[any]any{ // info()
+			"files":           []any{"0.snap"},
+			"type":            "full",
+			"recovery_points": []any{},
+		}},
+		nil, // stop()
+	}}
+
+	require.NoError(t, Start(m, StartOpts{}))
+
+	info, err := GetInfo(m)
+	require.NoError(t, err)
+	require.Equal(t, backup.BackupTypeFull, info.Type)
+	require.NotNil(t, info.RecoveryPoints)
+
+	require.NoError(t, Stop(m))
+	require.Equal(t,
+		[]string{"box.backup.start(...)", "return box.backup.info()", "box.backup.stop()"},
+		m.exprs)
+}