refactor(blockchain): tighten chain sync operator UX

chain_commands.go

@@ -38,12 +38,12 @@ const chainCommandLong = "Sync from peers, inspect the chain in a terminal UI, o
 const chainExplorerCommandShort = "Open the chain explorer"
 const chainExplorerCommandLong = "Browse blocks and transactions in a terminal UI while the node keeps syncing."
 const chainSyncCommandShort = "Start or stop chain sync"
-const chainSyncCommandLong = "Start syncing from peers in the foreground by default. Use --daemon to keep syncing in the background or --stop to stop a running background sync."
+const chainSyncCommandLong = "Start syncing from peers in the foreground by default. Use --daemon to keep syncing in the background, or --stop to stop the background sync for the selected data directory."
 const chainExplorerExample = "Open the explorer:\n  " + chainExplorerCommandPath + " --data-dir ~/.lethean/chain\n\n" +
 	"Open the explorer on testnet:\n  " + chainExplorerCommandPath + " --testnet"
 const chainSyncExample = "Start a foreground sync:\n  " + chainSyncCommandPath + "\n\n" +
 	"Keep syncing in the background:\n  " + chainSyncCommandPath + " --daemon\n\n" +
-	"Stop the background sync:\n  " + chainSyncCommandPath + " --stop"
+	"Stop the background sync for a data directory:\n  " + chainSyncCommandPath + " --stop --data-dir ~/.lethean/chain"
 const chainCommandExample = chainExplorerExample + "\n" + chainSyncExample
 
 // AddChainCommands registers the `chain` command group on a Cobra root.
@@ -71,9 +71,9 @@ func AddChainCommands(root *cobra.Command) {
 		Args:    cobra.NoArgs,
 	}
 
-	chainCmd.PersistentFlags().StringVar(&dataDir, "data-dir", defaultChainDataDirPath(), "store chain data in this directory")
+	chainCmd.PersistentFlags().StringVar(&dataDir, "data-dir", defaultChainDataDirPath(), "store chain data and sync state in this directory")
 	chainCmd.PersistentFlags().StringVar(&seed, "seed", defaultChainSeed, "connect to this seed peer first (host:port)")
-	chainCmd.PersistentFlags().BoolVar(&testnet, "testnet", false, "use the Lethean testnet (default seed: "+defaultChainTestnetSeed+")")
+	chainCmd.PersistentFlags().BoolVar(&testnet, "testnet", false, "use the Lethean testnet and its default seed ("+defaultChainTestnetSeed+")")
 
 	chainCmd.AddCommand(
 		newChainExplorerCommand(&dataDir, &seed, &testnet),

commands_test.go

@@ -99,7 +99,7 @@ func TestChainCommandLabels_Good(t *testing.T) {
 	assert.Equal(t, "Open the chain explorer", chainExplorerCommandShort)
 	assert.Equal(t, "Browse blocks and transactions in a terminal UI while the node keeps syncing.", chainExplorerCommandLong)
 	assert.Equal(t, "Start or stop chain sync", chainSyncCommandShort)
-	assert.Equal(t, "Start syncing from peers in the foreground by default. Use --daemon to keep syncing in the background or --stop to stop a running background sync.", chainSyncCommandLong)
+	assert.Equal(t, "Start syncing from peers in the foreground by default. Use --daemon to keep syncing in the background, or --stop to stop the background sync for the selected data directory.", chainSyncCommandLong)
 }
 
 func TestValidateChainRuntimeInputs_Good(t *testing.T) {
@@ -196,9 +196,9 @@ func TestAddChainCommands_Good_PersistentFlagHelp(t *testing.T) {
 
 	chainCmd, _, _ := root.Find([]string{ChainCommandName})
 
-	assert.Equal(t, "store chain data in this directory", chainCmd.PersistentFlags().Lookup("data-dir").Usage)
+	assert.Equal(t, "store chain data and sync state in this directory", chainCmd.PersistentFlags().Lookup("data-dir").Usage)
 	assert.Equal(t, "connect to this seed peer first (host:port)", chainCmd.PersistentFlags().Lookup("seed").Usage)
-	assert.Equal(t, "use the Lethean testnet (default seed: localhost:46942)", chainCmd.PersistentFlags().Lookup("testnet").Usage)
+	assert.Equal(t, "use the Lethean testnet and its default seed (localhost:46942)", chainCmd.PersistentFlags().Lookup("testnet").Usage)
 }
 
 func TestNewChainSyncCommand_Good_FlagHelp(t *testing.T) {
@@ -209,7 +209,32 @@ func TestNewChainSyncCommand_Good_FlagHelp(t *testing.T) {
 	cmd := newChainSyncCommand(&dataDir, &seed, &testnet)
 
 	assert.Equal(t, "keep syncing in the background", cmd.Flags().Lookup("daemon").Usage)
-	assert.Equal(t, "stop a background sync started with --daemon", cmd.Flags().Lookup("stop").Usage)
+	assert.Equal(t, "stop the background sync for this data directory", cmd.Flags().Lookup("stop").Usage)
+}
+
+func TestChainSyncExamples_Good(t *testing.T) {
+	assert.Contains(t, chainSyncExample, "core-chain chain sync --daemon")
+	assert.Contains(t, chainSyncExample, "core-chain chain sync --stop --data-dir ~/.lethean/chain")
+}
+
+func TestFormatChainSyncForegroundStart_Good(t *testing.T) {
+	assert.Equal(t, `Starting chain sync in the foreground with data dir "/tmp/chain" and seed "seeds.lthn.io:36942". Press Ctrl+C to stop.`, formatChainSyncForegroundStart("/tmp/chain", "seeds.lthn.io:36942"))
+}
+
+func TestFormatChainSyncForegroundStop_Good(t *testing.T) {
+	assert.Equal(t, "Chain sync stopped.", formatChainSyncForegroundStop())
+}
+
+func TestFormatChainSyncDaemonStarted_Good(t *testing.T) {
+	assert.Equal(t, `Background chain sync started with data dir "/tmp/chain" and seed "seeds.lthn.io:36942". Stop it with core-chain chain sync --stop --data-dir "/tmp/chain".`, formatChainSyncDaemonStarted("/tmp/chain", "seeds.lthn.io:36942"))
+}
+
+func TestFormatChainSyncStopCommand_Good(t *testing.T) {
+	assert.Equal(t, `core-chain chain sync --stop --data-dir "/tmp/chain"`, formatChainSyncStopCommand("/tmp/chain"))
+}
+
+func TestFormatChainSyncDaemonStopping_Good(t *testing.T) {
+	assert.Equal(t, "Stopping background chain sync (PID 42).", formatChainSyncDaemonStopping(42))
 }
 
 func TestRunChainSyncOnce_Bad_RespectsCancelledContext(t *testing.T) {

sync_command.go

@@ -61,7 +61,7 @@ func newChainSyncCommand(dataDir, seed *string, testnet *bool) *cobra.Command {
 	}
 
 	cmd.Flags().BoolVar(&runAsDaemon, "daemon", false, "keep syncing in the background")
-	cmd.Flags().BoolVar(&stopDaemon, "stop", false, "stop a background sync started with --daemon")
+	cmd.Flags().BoolVar(&stopDaemon, "stop", false, "stop the background sync for this data directory")
 
 	return cmd
 }
@@ -87,9 +87,9 @@ func runChainSyncForeground(dataDir, seed string, testnet bool) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer cancel()
 
-	log.Printf("Starting %s with data dir %s and seed %s.", chainSyncDisplayName, dataDir, resolvedSeed)
+	log.Print(formatChainSyncForegroundStart(dataDir, resolvedSeed))
 	runChainSyncLoop(ctx, blockchain, &chainConfig, hardForks, resolvedSeed)
-	log.Printf("%s stopped.", chainSyncDisplayName)
+	log.Print(formatChainSyncForegroundStop())
 	return nil
 }
 
@@ -131,7 +131,7 @@ func runChainSyncDaemon(dataDir, seed string, testnet bool) error {
 	defer cancel()
 
 	syncDaemon.SetReady(true)
-	log.Printf("Background sync started for %s with data dir %s and seed %s. Stop it with %s --stop --data-dir %s.", chainSyncDisplayName, dataDir, resolvedSeed, chainSyncCommandPath, dataDir)
+	log.Print(formatChainSyncDaemonStarted(dataDir, resolvedSeed))
 
 	var wg sync.WaitGroup
 	wg.Add(1)
@@ -165,6 +165,26 @@ func stopChainSyncDaemon(dataDir string) error {
 		return coreerr.E("stopChainSyncDaemon", fmt.Sprintf("signal process %d", pid), err)
 	}
 
-	log.Printf("Stopping background sync for %s (PID %d).", chainSyncDisplayName, pid)
+	log.Print(formatChainSyncDaemonStopping(pid))
 	return nil
 }
+
+func formatChainSyncForegroundStart(dataDir, seed string) string {
+	return fmt.Sprintf("Starting chain sync in the foreground with data dir %q and seed %q. Press Ctrl+C to stop.", dataDir, seed)
+}
+
+func formatChainSyncForegroundStop() string {
+	return "Chain sync stopped."
+}
+
+func formatChainSyncDaemonStarted(dataDir, seed string) string {
+	return fmt.Sprintf("Background chain sync started with data dir %q and seed %q. Stop it with %s.", dataDir, seed, formatChainSyncStopCommand(dataDir))
+}
+
+func formatChainSyncStopCommand(dataDir string) string {
+	return fmt.Sprintf("%s --stop --data-dir %q", chainSyncCommandPath, dataDir)
+}
+
+func formatChainSyncDaemonStopping(pid int) string {
+	return fmt.Sprintf("Stopping background chain sync (PID %d).", pid)
+}