DAOS-17321 ddb: Add checksum dump command to ddb GO code

Add the csum_dump command to the ddb Go CLI, wiring the ddb_run_csum_dump()
C API (added in #18543) through the build-tag CGo stub layer introduced by
#18124:

- Add CsumDump() to DdbContext (commands_wrapper.go): builds the C
  csum_dump_options (path, optional dst, epoch) and invokes the C command.
- Add real and stub ddb_run_csum_dump() wrappers (libddb.go /
  libddb_stubs.go), following the existing per-command _RC/_Fn hook
  pattern used for Go unit testing.
- Register the "csum_dump" command in ddb_commands.go: a required
  positional path, an optional positional dst (file to dump the
  checksum to; prints to the screen when omitted), and a -e/--epoch
  flag (default EPOCH_MAX).
- The epoch selects which version of the checksum to dump: for a
  single value akey it is the epoch at or before which the value is
  fetched; for an array akey it is the maximal epoch of the visible
  record extent(s) to select.

Tests: add TestDdb_Cmds cases for csum_dump covering a missing required
path argument, an invalid flag, the default epoch, the short and long
--epoch forms, a file destination, and a destination combined with a
custom epoch.

Features: recovery
Signed-off-by: Cedric Koch-Hofer <cedric.koch-hofer@hpe.com>

Author: kanard38

src/control/cmd/ddb/commands_wrapper.go

@@ -380,3 +380,22 @@ func (ctx *DdbContext) DtxAggr(path string, cmtTime uint64, cmtDate string) erro
 	/* Run the c code command */
 	return daosError(ddb_run_dtx_aggr(&ctx.ctx, &options))
 }
+
+// CsumDump dumps the visible checksum(s) at the VOS tree path to the screen, or to the
+// file at dst if provided. epoch selects which version to dump: for a single value akey
+// it is the epoch at or before which the value is fetched, and for an array akey it is the
+// maximal epoch of the visible record extent(s) to select. Pass math.MaxUint64 (EPOCH_MAX)
+// to select the latest.
+func (ctx *DdbContext) CsumDump(path string, dst string, epoch uint64) error {
+	/* Set up the options */
+	options := C.struct_csum_dump_options{}
+	options.path = C.CString(path)
+	defer freeString(options.path)
+	if dst != "" {
+		options.dst = C.CString(dst)
+		defer freeString(options.dst)
+	}
+	options.epoch = C.uint64_t(epoch)
+	/* Run the c code command */
+	return daosError(ddb_run_csum_dump(&ctx.ctx, &options))
+}

src/control/cmd/ddb/ddb_commands.go

@@ -481,4 +481,30 @@ If --db_path is provided, a VOS file path must also be given as a positional arg
 		},
 		Completer: nil,
 	})
+	// Command csum_dump
+	app.AddCommand(&grumble.Command{
+		Name:    "csum_dump",
+		Aliases: nil,
+		Help:    "Dump visible checksum(s)",
+		LongHelp: `Dump visible checksum(s) to the screen or in a file.  The vos
+path should be a complete path, including the akey and if the value is an array
+value it should include the extent. If a path to a file was provided then the
+value(s) will be written to the file, else it will be printed to the screen.
+The --epoch flag selects which version of the checksum to dump: for a single
+value akey it selects the value visible at or before that epoch, and for an
+array value it defines the maximal epoch of the visible record extent to
+select`,
+		HelpGroup: "vos",
+		Args: func(a *grumble.Args) {
+			a.String("path", "VOS tree path to dump.")
+			a.String("dst", "Optional, file path to dump the value to.", grumble.Default(""))
+		},
+		Flags: func(f *grumble.Flags) {
+			f.Uint64("e", "epoch", math.MaxUint64, "Maximal epoch of the checksum value to select (default EPOCH_MAX).")
+		},
+		Run: func(c *grumble.Context) error {
+			return ctx.CsumDump(c.Args.String("path"), c.Args.String("dst"), c.Flags.Uint64("epoch"))
+		},
+		Completer: nil,
+	})
 }

src/control/cmd/ddb/ddb_commands_test.go

@@ -10,6 +10,7 @@ package main
 
 import (
 	"fmt"
+	"math"
 	"os"
 	"path"
 	"path/filepath"
@@ -32,6 +33,10 @@ func TestDdb_HelpCmds(t *testing.T) {
 			cmdStr:     "open",
 			helpSubStr: "Usage:\n  open [flags] path\n",
 		},
+		"help for 'csum_dump' command": {
+			cmdStr:     "csum_dump",
+			helpSubStr: "Usage:\n  csum_dump [flags] path [dst]\n",
+		},
 		// TODO(follow-up PR): Add help tests for the remaining commands.
 	} {
 		t.Run(name, func(t *testing.T) {
@@ -52,8 +57,7 @@ func TestDdb_HelpCmds(t *testing.T) {
 			if err != nil {
 				t.Fatalf("unexpected error when running '%s --help' via command file: want nil, got %v", tc.cmdStr, err)
 			}
-			test.AssertTrue(t, strings.Contains(stdoutCmdFile, tc.helpSubStr),
-				fmt.Sprintf("expected stdout to contain %q: got\n%s", tc.helpSubStr, stdoutCmdFile))
+			test.AssertStringContains(t, stdoutCmdFile, tc.helpSubStr)
 
 			// Run the help command with a command line
 			args = test.JoinArgs(nil, tc.cmdStr, "--help")
@@ -63,8 +67,7 @@ func TestDdb_HelpCmds(t *testing.T) {
 			if err != nil {
 				t.Fatalf("unexpected error when running '%s --help' via command line: want nil, got %v", tc.cmdStr, err)
 			}
-			test.AssertTrue(t, strings.Contains(stdoutCmdLine, tc.helpSubStr),
-				fmt.Sprintf("expected stdout to contain %q: got\n%s", tc.helpSubStr, stdoutCmdLine))
+			test.AssertStringContains(t, stdoutCmdLine, tc.helpSubStr)
 
 			// Compare command line and command file outputs
 			test.AssertEqual(t, stdoutCmdFile, stdoutCmdLine,
@@ -132,6 +135,16 @@ func TestDdb_Cmds(t *testing.T) {
 		}
 	}
 
+	csumDumpFnChecking := func(t *testing.T, wantPath, wantDst string, wantEpoch uint64) func(string, string, uint64) error {
+		return func(path, dst string, epoch uint64) error {
+			fmt.Println("csum_dump called")
+			test.CmpAny(t, "path", wantPath, path)
+			test.CmpAny(t, "dst", wantDst, dst)
+			test.CmpAny(t, "epoch", wantEpoch, epoch)
+			return nil
+		}
+	}
+
 	for name, tc := range map[string]struct {
 		args      []string
 		setup     func(*testing.T)
@@ -394,6 +407,51 @@ func TestDdb_Cmds(t *testing.T) {
 			expStdout: []string{"prov_mem called"},
 		},
 
+		// --- csum_dump command ---
+		"csum_dump missing path": {
+			args:   []string{"csum_dump"},
+			expErr: ddbTestErr("missing argument 'path'"),
+		},
+		"csum_dump invalid options": {
+			args:   []string{"csum_dump", "--bar"},
+			expErr: ddbTestErr("invalid flag: --bar"),
+		},
+		"csum_dump default": {
+			args: []string{"csum_dump", "/[0]"},
+			setup: func(t *testing.T) {
+				ddb_run_csum_dump_Fn = csumDumpFnChecking(t, "/[0]", "", math.MaxUint64)
+			},
+			expStdout: []string{"csum_dump called"},
+		},
+		"csum_dump epoch short": {
+			args: []string{"csum_dump", "-e", "999", "/[0]"},
+			setup: func(t *testing.T) {
+				ddb_run_csum_dump_Fn = csumDumpFnChecking(t, "/[0]", "", 999)
+			},
+			expStdout: []string{"csum_dump called"},
+		},
+		"csum_dump epoch long": {
+			args: []string{"csum_dump", "--epoch=666", "/[0]"},
+			setup: func(t *testing.T) {
+				ddb_run_csum_dump_Fn = csumDumpFnChecking(t, "/[0]", "", 666)
+			},
+			expStdout: []string{"csum_dump called"},
+		},
+		"csum_dump destination": {
+			args: []string{"csum_dump", "/[0]", "/tmp/csum_dump.out"},
+			setup: func(t *testing.T) {
+				ddb_run_csum_dump_Fn = csumDumpFnChecking(t, "/[0]", "/tmp/csum_dump.out", math.MaxUint64)
+			},
+			expStdout: []string{"csum_dump called"},
+		},
+		"csum_dump destination with epoch": {
+			args: []string{"csum_dump", "-e", "500", "/[0]", "/tmp/csum_dump.out"},
+			setup: func(t *testing.T) {
+				ddb_run_csum_dump_Fn = csumDumpFnChecking(t, "/[0]", "/tmp/csum_dump.out", 500)
+			},
+			expStdout: []string{"csum_dump called"},
+		},
+
 		// TODO(follow-up PR): Add TestCmds cases for the remaining commands.
 		// Each new test case follows the same pattern as the cases above: set the
 		// corresponding ddb_run_<cmd>_Fn hook in setup() to verify argument passing,

src/control/cmd/ddb/libddb.go

@@ -131,3 +131,7 @@ func ddb_run_prov_mem(ctx *C.struct_ddb_ctx, opts *C.struct_prov_mem_options) C.
 func ddb_run_dtx_aggr(ctx *C.struct_ddb_ctx, opts *C.struct_dtx_aggr_options) C.int {
 	return C.ddb_run_dtx_aggr(ctx, opts)
 }
+
+func ddb_run_csum_dump(ctx *C.struct_ddb_ctx, opts *C.struct_csum_dump_options) C.int {
+	return C.ddb_run_csum_dump(ctx, opts)
+}

src/control/cmd/ddb/libddb_stubs.go

@@ -59,6 +59,7 @@ func resetDdbStubs() {
 	ddb_run_dtx_stat_RC, ddb_run_dtx_stat_Fn = 0, nil
 	ddb_run_prov_mem_RC, ddb_run_prov_mem_Fn = 0, nil
 	ddb_run_dtx_aggr_RC, ddb_run_dtx_aggr_Fn = 0, nil
+	ddb_run_csum_dump_RC, ddb_run_csum_dump_Fn = 0, nil
 }
 
 var ddb_init_RC C.int = 0
@@ -458,3 +459,19 @@ func ddb_run_dtx_aggr(_ *C.struct_ddb_ctx, opts *C.struct_dtx_aggr_options) C.in
 	}
 	return ddb_run_dtx_aggr_RC
 }
+
+var (
+	ddb_run_csum_dump_RC C.int = 0
+	ddb_run_csum_dump_Fn func(path string, dst string, epoch uint64) error
+)
+
+func ddb_run_csum_dump(_ *C.struct_ddb_ctx, opts *C.struct_csum_dump_options) C.int {
+	if ddb_run_csum_dump_Fn != nil {
+		return fromGoErr(ddb_run_csum_dump_Fn(
+			C.GoString(opts.path),
+			C.GoString(opts.dst),
+			uint64(opts.epoch),
+		))
+	}
+	return ddb_run_csum_dump_RC
+}