feat(gossipsub): add addDirectPeer/removeDirectPeer/getDirectPeers

[paschal533]

Summary

Ports ChainSafe/js-libp2p-gossipsub#541 into the monorepo, adding three new public methods that let applications manage direct peers at runtime — without restarting GossipSub.

Before this PR, the only way to change the directPeers set was to stop GossipSub, construct a new instance with the updated directPeers config array, and start it again (~6 ms, all mesh state lost).

After this PR, three methods handle it at runtime in ~1 ms with no disruption to existing mesh connections.

New API

// Add a peer to the direct set. Stores its addresses and dials immediately
// if GossipSub is already running. Returns the peer ID string on success,
// null if rejected (self-dial, empty addrs, or peerStore failure).
addDirectPeer(peerId: PeerId, addrs: Multiaddr[]): Promise<PeerIdStr | null>

// Remove a peer from the direct set.
// The existing connection ages out through normal mesh pruning.
// Returns true if the peer was removed, false if it was not a direct peer.
removeDirectPeer(peerId: PeerId | string): boolean

// Return a snapshot of the current direct peer ID strings.
getDirectPeers(): PeerIdStr[]

Motivation

• Aligns with ChainSafe/lodestar#8853 — Lodestar needs to hot-add trusted peers discovered after startup without downtime.
• Direct peers discovered during operation can now be registered immediately.
• Misbehaving direct peers can be removed from the list without a restart.

Implementation notes

• addDirectPeer stores addresses via peerStore.merge before adding to this.direct, so a peerStore failure leaves the set clean.
• connect() is fire-and-forget (.catch() only) — consistent with the existing directConnect() heartbeat path.
• removeDirectPeer intentionally does not close the existing connection; it expires naturally through mesh pruning. This matches GossipSub spec behaviour.
• this.direct remains public readonly for backwards compatibility with existing tests that read it directly.

Benchmark results

Operation	Throughput	Latency
BEFORE: stop + reconstruct + start	—	~6 ms
addDirectPeer (new API)	2,813 ops/s	~1 ms
removeDirectPeer	3,351,722 ops/s	~0.0003 ms
getDirectPeers (100-peer set)	1,285,181 ops/s	~0.0008 ms

~6× faster than the restart approach for adding a single peer.

Files changed

File	Change
packages/gossipsub/src/gossipsub.ts	3 method implementations
packages/gossipsub/src/index.ts	3 method signatures added to GossipSub interface + imports
packages/gossipsub/test/direct-peers.spec.ts	10 unit tests (all edge cases covered)
packages/gossipsub/test/benchmark/direct-peers.benchmark.ts	5 benchmark cases including BEFORE vs AFTER comparison
packages/gossipsub/test/demo-direct-peers.ts	11-step real-time demo on a live 3-node network
packages/gossipsub/test/types.d.ts	benchmark module type declaration (fixes pre-existing TS build error)

Test plan

• addDirectPeer adds peer to direct set and stores addresses in peerStore
• addDirectPeer attempts connection when GossipSub is running
• addDirectPeer returns null when adding self
• addDirectPeer returns null when no addresses provided
• addDirectPeer does not connect when GossipSub is stopped (but still adds to set)
• removeDirectPeer removes peer and returns true (PeerId form)
• removeDirectPeer removes peer and returns true (string form)
• removeDirectPeer returns false for non-member
• getDirectPeers returns all current entries
• getDirectPeers reflects removals immediately
• Integration: all three methods verified on a live 3-node connected network

[dozyio]

Thanks @paschal533 - made a few changes. Hopefully will get this merged over the next few days

[wemeetagain]

should we await this.connect?