Skip to content

Commit cabe637

Browse files
laanwjlaanwj
committed
Merge #20877: netinfo: user help and argument parsing improvements
7d3343f cli: update -netinfo help doc following the merge of 882ce25 (Jon Atack) ef614bb cli: small -netinfo simplification and performance improvement (Jon Atack) 6b45ef3 cli: improve -netinfo invalid argument error message (Jon Atack) 3732404 cli: warn in help that -netinfo is not intended to be a stable API (Jon Atack) 7afdd72 cli: enable -netinfo help to run without a remote server (Jon Atack) Pull request description: A few updates, some per IRC discussion today at http://www.erisian.com.au/bitcoin-core-dev/log-2021-01-07.html#l-87 with respect to -netinfo: - enable `-netinfo help` to run without a remote server - warn in `-netinfo help` that -netinfo is not intended to be a stable API - improve the -netinfo invalid argument error message - make a performance improvement and simplification I noticed after the merge of #20764 - update the -netinfo help doc following the merge of #21192 ----- How to test manually: 🔬 🧪 📈 1. check out and build this branch locally; if you need help, don't hesitate to refer to https://jonatack.github.io/articles/how-to-review-pull-requests-in-bitcoin-core#pull-down-the-code-locally or https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests 2. while it is compiling, look at the code changes 3. stop signet (if it is running) with `./src/bitcoin-cli -signet stop` 4. once the build is completed, run `./src/bitcoin-cli -signet -netinfo help` 5. the help should be printed even though the signet server is not running 6. near the top you should see the new warning, "This human-readable interface will change regularly and is not intended to be a stable API" as well as a bit more description about the integer argument values. 7. start signet with `./src/bitcoind -signet` 8. test the improved invalid argument error message if you run `./src/bitcoin-cli -signet -netinfo 256` or `./src/bitcoin-cli -signet -netinfo a` (valid values are from 0 to 255) 9. leave review feedback or `ACK <commit hash>` -- done 🍻 ACKs for top commit: michaelfolkson: Re-ACK 7d3343f pinheadmz: RE-ACK 7d3343f Tree-SHA512: 28c5e9f295ffccba5c2a70faac4987d45f35d4758cf8f10daa767e83212316c4cfc65930e4066f7ad627e9d15b92d43439d1ba9c2f755dfde61885c6a70aa155
2 parents ebd8d66 + 7d3343f commit cabe637

File tree

1 file changed

+70
-75
lines changed

1 file changed

+70
-75
lines changed

‎src/bitcoin-cli.cpp

Lines changed: 70 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -300,7 +300,6 @@ class NetinfoRequestHandler : public BaseRequestHandler
300300
{
301301
private:
302302
static constexpr int8_t UNKNOWN_NETWORK{-1};
303-
static constexpr int8_t NET_I2P{3}; // pos of "i2p" in m_networks
304303
static constexpr uint8_t m_networks_size{4};
305304
static constexpr uint8_t MAX_DETAIL_LEVEL{4};
306305
const std::array<std::string, m_networks_size> m_networks{{"ipv4", "ipv6", "onion", "i2p"}};
@@ -314,13 +313,11 @@ class NetinfoRequestHandler : public BaseRequestHandler
314313
}
315314
return UNKNOWN_NETWORK;
316315
}
317-
uint8_t m_details_level{0}; //!< Optional user-supplied arg to set dashboard details level
318-
bool m_is_help_requested{false}; //!< Optional user-supplied arg to print help documentation
316+
uint8_t m_details_level{0}; //!< Optional user-supplied arg to set dashboard details level
319317
bool DetailsRequested() const { return m_details_level > 0 && m_details_level < 5; }
320318
bool IsAddressSelected() const { return m_details_level == 2 || m_details_level == 4; }
321319
bool IsVersionSelected() const { return m_details_level == 3 || m_details_level == 4; }
322320
bool m_is_asmap_on{false};
323-
bool m_is_i2p_on{false};
324321
size_t m_max_addr_length{0};
325322
size_t m_max_age_length{3};
326323
size_t m_max_id_length{2};
@@ -367,68 +364,6 @@ class NetinfoRequestHandler : public BaseRequestHandler
367364
if (conn_type == "addr-fetch") return "addr";
368365
return "";
369366
}
370-
const UniValue NetinfoHelp()
371-
{
372-
return std::string{
373-
"-netinfo level|\"help\" \n\n"
374-
"Returns a network peer connections dashboard with information from the remote server.\n"
375-
"Under the hood, -netinfo fetches the data by calling getpeerinfo and getnetworkinfo.\n"
376-
"An optional integer argument from 0 to 4 can be passed for different peers listings.\n"
377-
"Pass \"help\" to see this detailed help documentation.\n"
378-
"If more than one argument is passed, only the first one is read and parsed.\n"
379-
"Suggestion: use with the Linux watch(1) command for a live dashboard; see example below.\n\n"
380-
"Arguments:\n"
381-
"1. level (integer 0-4, optional) Specify the info level of the peers dashboard (default 0):\n"
382-
" 0 - Connection counts and local addresses\n"
383-
" 1 - Like 0 but with a peers listing (without address or version columns)\n"
384-
" 2 - Like 1 but with an address column\n"
385-
" 3 - Like 1 but with a version column\n"
386-
" 4 - Like 1 but with both address and version columns\n"
387-
"2. help (string \"help\", optional) Print this help documentation instead of the dashboard.\n\n"
388-
"Result:\n\n"
389-
"* The peers listing in levels 1-4 displays all of the peers sorted by direction and minimum ping time:\n\n"
390-
" Column Description\n"
391-
" ------ -----------\n"
392-
" <-> Direction\n"
393-
" \"in\" - inbound connections are those initiated by the peer\n"
394-
" \"out\" - outbound connections are those initiated by us\n"
395-
" type Type of peer connection\n"
396-
" \"full\" - full relay, the default\n"
397-
" \"block\" - block relay; like full relay but does not relay transactions or addresses\n"
398-
" \"manual\" - peer we manually added using RPC addnode or the -addnode/-connect config options\n"
399-
" \"feeler\" - short-lived connection for testing addresses\n"
400-
" \"addr\" - address fetch; short-lived connection for requesting addresses\n"
401-
" net Network the peer connected through (\"ipv4\", \"ipv6\", \"onion\", \"i2p\", or \"cjdns\")\n"
402-
" mping Minimum observed ping time, in milliseconds (ms)\n"
403-
" ping Last observed ping time, in milliseconds (ms)\n"
404-
" send Time since last message sent to the peer, in seconds\n"
405-
" recv Time since last message received from the peer, in seconds\n"
406-
" txn Time since last novel transaction received from the peer and accepted into our mempool, in minutes\n"
407-
" blk Time since last novel block passing initial validity checks received from the peer, in minutes\n"
408-
" hb High-bandwidth BIP152 compact block relay\n"
409-
" \".\" (to) - we selected the peer as a high-bandwidth peer\n"
410-
" \"*\" (from) - the peer selected us as a high-bandwidth peer\n"
411-
" age Duration of connection to the peer, in minutes\n"
412-
" asmap Mapped AS (Autonomous System) number in the BGP route to the peer, used for diversifying\n"
413-
" peer selection (only displayed if the -asmap config option is set)\n"
414-
" id Peer index, in increasing order of peer connections since node startup\n"
415-
" address IP address and port of the peer\n"
416-
" version Peer version and subversion concatenated, e.g. \"70016/Satoshi:21.0.0/\"\n\n"
417-
"* The connection counts table displays the number of peers by direction, network, and the totals\n"
418-
" for each, as well as two special outbound columns for block relay peers and manual peers.\n\n"
419-
"* The local addresses table lists each local address broadcast by the node, the port, and the score.\n\n"
420-
"Examples:\n\n"
421-
"Connection counts and local addresses only\n"
422-
"> bitcoin-cli -netinfo\n\n"
423-
"Compact peers listing\n"
424-
"> bitcoin-cli -netinfo 1\n\n"
425-
"Full dashboard\n"
426-
"> bitcoin-cli -netinfo 4\n\n"
427-
"Full live dashboard, adjust --interval or --no-title as needed (Linux)\n"
428-
"> watch --interval 1 --no-title bitcoin-cli -netinfo 4\n\n"
429-
"See this help\n"
430-
"> bitcoin-cli -netinfo help\n"};
431-
}
432367
const int64_t m_time_now{GetSystemTimeInSeconds()};
433368

434369
public:
@@ -441,10 +376,8 @@ class NetinfoRequestHandler : public BaseRequestHandler
441376
uint8_t n{0};
442377
if (ParseUInt8(args.at(0), &n)) {
443378
m_details_level = std::min(n, MAX_DETAIL_LEVEL);
444-
} else if (args.at(0) == "help") {
445-
m_is_help_requested = true;
446379
} else {
447-
throw std::runtime_error(strprintf("invalid -netinfo argument: %s", args.at(0)));
380+
throw std::runtime_error(strprintf("invalid -netinfo argument: %s\nFor more information, run: bitcoin-cli -netinfo help", args.at(0)));
448381
}
449382
}
450383
UniValue result(UniValue::VARR);
@@ -455,9 +388,6 @@ class NetinfoRequestHandler : public BaseRequestHandler
455388

456389
UniValue ProcessReply(const UniValue& batch_in) override
457390
{
458-
if (m_is_help_requested) {
459-
return JSONRPCReplyObj(NetinfoHelp(), NullUniValue, 1);
460-
}
461391
const std::vector<UniValue> batch{JSONRPCProcessBatchReply(batch_in)};
462392
if (!batch[ID_PEERINFO]["error"].isNull()) return batch[ID_PEERINFO];
463393
if (!batch[ID_NETWORKINFO]["error"].isNull()) return batch[ID_NETWORKINFO];
@@ -472,7 +402,6 @@ class NetinfoRequestHandler : public BaseRequestHandler
472402
const std::string network{peer["network"].get_str()};
473403
const int8_t network_id{NetworkStringToId(network)};
474404
if (network_id == UNKNOWN_NETWORK) continue;
475-
m_is_i2p_on |= (network_id == NET_I2P);
476405
const bool is_outbound{!peer["inbound"].get_bool()};
477406
const bool is_block_relay{!peer["relaytxes"].get_bool()};
478407
const std::string conn_type{peer["connection_type"].get_str()};
@@ -545,13 +474,14 @@ class NetinfoRequestHandler : public BaseRequestHandler
545474

546475
// Report peer connection totals by type.
547476
result += " ipv4 ipv6 onion";
548-
if (m_is_i2p_on) result += " i2p";
477+
const bool any_i2p_peers = m_counts.at(2).at(3); // false if total i2p peers count is 0, otherwise true
478+
if (any_i2p_peers) result += " i2p";
549479
result += " total block";
550480
if (m_manual_peers_count) result += " manual";
551481
const std::array<std::string, 3> rows{{"in", "out", "total"}};
552482
for (uint8_t i = 0; i < 3; ++i) {
553483
result += strprintf("\n%-5s %5i %5i %5i", rows.at(i), m_counts.at(i).at(0), m_counts.at(i).at(1), m_counts.at(i).at(2)); // ipv4/ipv6/onion peers counts
554-
if (m_is_i2p_on) result += strprintf(" %5i", m_counts.at(i).at(3)); // i2p peers count
484+
if (any_i2p_peers) result += strprintf(" %5i", m_counts.at(i).at(3)); // i2p peers count
555485
result += strprintf(" %5i", m_counts.at(i).at(m_networks_size)); // total peers count
556486
if (i == 1) { // the outbound row has two extra columns for block relay and manual peer counts
557487
result += strprintf(" %5i", m_block_relay_peers_count);
@@ -576,6 +506,67 @@ class NetinfoRequestHandler : public BaseRequestHandler
576506

577507
return JSONRPCReplyObj(UniValue{result}, NullUniValue, 1);
578508
}
509+
510+
const std::string m_help_doc{
511+
"-netinfo level|\"help\" \n\n"
512+
"Returns a network peer connections dashboard with information from the remote server.\n"
513+
"This human-readable interface will change regularly and is not intended to be a stable API.\n"
514+
"Under the hood, -netinfo fetches the data by calling getpeerinfo and getnetworkinfo.\n"
515+
+ strprintf("An optional integer argument from 0 to %d can be passed for different peers listings; %d to 255 are parsed as %d.\n", MAX_DETAIL_LEVEL, MAX_DETAIL_LEVEL, MAX_DETAIL_LEVEL) +
516+
"Pass \"help\" to see this detailed help documentation.\n"
517+
"If more than one argument is passed, only the first one is read and parsed.\n"
518+
"Suggestion: use with the Linux watch(1) command for a live dashboard; see example below.\n\n"
519+
"Arguments:\n"
520+
+ strprintf("1. level (integer 0-%d, optional) Specify the info level of the peers dashboard (default 0):\n", MAX_DETAIL_LEVEL) +
521+
" 0 - Connection counts and local addresses\n"
522+
" 1 - Like 0 but with a peers listing (without address or version columns)\n"
523+
" 2 - Like 1 but with an address column\n"
524+
" 3 - Like 1 but with a version column\n"
525+
" 4 - Like 1 but with both address and version columns\n"
526+
"2. help (string \"help\", optional) Print this help documentation instead of the dashboard.\n\n"
527+
"Result:\n\n"
528+
+ strprintf("* The peers listing in levels 1-%d displays all of the peers sorted by direction and minimum ping time:\n\n", MAX_DETAIL_LEVEL) +
529+
" Column Description\n"
530+
" ------ -----------\n"
531+
" <-> Direction\n"
532+
" \"in\" - inbound connections are those initiated by the peer\n"
533+
" \"out\" - outbound connections are those initiated by us\n"
534+
" type Type of peer connection\n"
535+
" \"full\" - full relay, the default\n"
536+
" \"block\" - block relay; like full relay but does not relay transactions or addresses\n"
537+
" \"manual\" - peer we manually added using RPC addnode or the -addnode/-connect config options\n"
538+
" \"feeler\" - short-lived connection for testing addresses\n"
539+
" \"addr\" - address fetch; short-lived connection for requesting addresses\n"
540+
" net Network the peer connected through (\"ipv4\", \"ipv6\", \"onion\", \"i2p\", or \"cjdns\")\n"
541+
" mping Minimum observed ping time, in milliseconds (ms)\n"
542+
" ping Last observed ping time, in milliseconds (ms)\n"
543+
" send Time since last message sent to the peer, in seconds\n"
544+
" recv Time since last message received from the peer, in seconds\n"
545+
" txn Time since last novel transaction received from the peer and accepted into our mempool, in minutes\n"
546+
" blk Time since last novel block passing initial validity checks received from the peer, in minutes\n"
547+
" hb High-bandwidth BIP152 compact block relay\n"
548+
" \".\" (to) - we selected the peer as a high-bandwidth peer\n"
549+
" \"*\" (from) - the peer selected us as a high-bandwidth peer\n"
550+
" age Duration of connection to the peer, in minutes\n"
551+
" asmap Mapped AS (Autonomous System) number in the BGP route to the peer, used for diversifying\n"
552+
" peer selection (only displayed if the -asmap config option is set)\n"
553+
" id Peer index, in increasing order of peer connections since node startup\n"
554+
" address IP address and port of the peer\n"
555+
" version Peer version and subversion concatenated, e.g. \"70016/Satoshi:21.0.0/\"\n\n"
556+
"* The connection counts table displays the number of peers by direction, network, and the totals\n"
557+
" for each, as well as two special outbound columns for block relay peers and manual peers.\n\n"
558+
"* The local addresses table lists each local address broadcast by the node, the port, and the score.\n\n"
559+
"Examples:\n\n"
560+
"Connection counts and local addresses only\n"
561+
"> bitcoin-cli -netinfo\n\n"
562+
"Compact peers listing\n"
563+
"> bitcoin-cli -netinfo 1\n\n"
564+
"Full dashboard\n"
565+
+ strprintf("> bitcoin-cli -netinfo %d\n\n", MAX_DETAIL_LEVEL) +
566+
"Full live dashboard, adjust --interval or --no-title as needed (Linux)\n"
567+
+ strprintf("> watch --interval 1 --no-title bitcoin-cli -netinfo %d\n\n", MAX_DETAIL_LEVEL) +
568+
"See this help\n"
569+
"> bitcoin-cli -netinfo help\n"};
579570
};
580571

581572
/** Process RPC generatetoaddress request. */
@@ -907,6 +898,10 @@ static int CommandLineRPC(int argc, char *argv[])
907898
if (gArgs.IsArgSet("-getinfo")) {
908899
rh.reset(new GetinfoRequestHandler());
909900
} else if (gArgs.GetBoolArg("-netinfo", false)) {
901+
if (!args.empty() && args.at(0) == "help") {
902+
tfm::format(std::cout, "%s\n", NetinfoRequestHandler().m_help_doc);
903+
return 0;
904+
}
910905
rh.reset(new NetinfoRequestHandler());
911906
} else if (gArgs.GetBoolArg("-generate", false)) {
912907
const UniValue getnewaddress{GetNewAddress()};

0 commit comments

Comments
 (0)