Objective

Extend the debug CLI to expose sub-commands for driving peer discovery in the P2P module (analogous to how it currently supports driving consensus). This will facilitate both manual and automated testing efforts.

Origin Document

Based on a discussion between @dylanlott and myself about end-to-end test planning for peer discovery. It has been made clear in discussions past (probably in documentation somewhere as well) that we want to prioritize supporting robust manual testing/investigation of these dynamic systems (before they get a chance to run away from us).

Goals

• Expose controls to peer discovery to developers
• Support step-by-step progression through peer discovery
• Support debugging & reproducing peer discovery scenarios (incl. edge cases)

Deliverable

• Extend the debug CLI to expose the sub-commands subcommands outlined below (peer CLI UX)
• (Bonus): draft a design for reproducible peer discovery failure reports or something
  • Could be generic (e.g. trace based)

CLI UX - peer & p2p subcommands

The following commands should send/broadcast debug messages into the network, resulting in nodes to print to their respective logs, similar to the debug subcommand's behavior.

peer discovery status # background router only
peer discovery start  # background router only
peer discovery stop   # background router only
peer list [--all | --staked | --unstaked]
peer forget (--all | <forgetter peer ID>)
peer connections
peer interrogate <peer ID>
peer disconnect <peer ID>

p2pCmd persisten flags:

• --trace

NOTE: p2p commands MAY interact with a remote/standalone node rather than utilize the CLI's own P2P module

p2p send [--trace] <peer ID> <text message>
p2p broadcast [--trace] <text message>

Non-goals / Non-deliverables

• Refactoring/simplifying the Router interface
• Additional, unrelated libp2p integration work

General issue deliverables

• Update the appropriate CHANGELOG(s)
• Update any relevant local/global README(s)
• Update relevant source code tree explanations
• Add or update any relevant or supporting mermaid diagrams

Testing Methodology

• New CLI subcommands behave as expected
• All tests: make test_all
• LocalNet: verify a LocalNet is still functioning correctly by following the instructions at docs/development/README.md
• k8s LocalNet: verify a k8s LocalNet is still functioning correctly by following the instructions here

Creator: @bryanchriswhite