Skip to content

feat: improve pubsub reliability and NAT detection for small clusters#1020

Merged
mudler merged 1 commit into
masterfrom
feat/default-on-libp2p-nat-and-gossipsub-resilience
May 30, 2026
Merged

feat: improve pubsub reliability and NAT detection for small clusters#1020
mudler merged 1 commit into
masterfrom
feat/default-on-libp2p-nat-and-gossipsub-resilience

Conversation

@mudler

@mudler mudler commented May 30, 2026

Copy link
Copy Markdown
Owner

Three additions that together address asymmetric / one-way gossipsub delivery seen on small (2-3 node) overlay networks where the default gossipsub mesh sits below its low-watermark and AutoNAT v1 cannot reach a stable reachability verdict:

  • libp2p AutoNAT v2 is now in defaultLibp2pOptions. v1 needs >=3 peers to give a stable answer, leaving 2-peer clusters stuck in Unknown reachability and degrading downstream behaviour (relay selection, hole punching, identify). v2 produces a verdict from a single peer.

  • Gossipsub now uses FloodPublish + PeerExchange by default. FloodPublish has the publisher flood to ALL connected peers rather than just mesh peers; in a 2-node network the mesh sits at 1 entry (Dlo=4), well below the healthy-mesh threshold, and standard mesh-only delivery becomes unreliable. PeerExchange lets peers gossip about each other and helps recover from one-way mesh links.

  • When bootstrap peers are configured, they are passed to gossipsub as DirectPeers so the router holds a persistent connection and bypasses mesh negotiation when delivering to them — guaranteeing publication reaches known/seed peers regardless of mesh state.

The hub.NewHub signature gains a variadic Option parameter so callers can opt in to direct-peer pinning without forcing the dependency into the hub package's API. node.startNetwork is the only in-tree caller and wires bootstrap peers through automatically.

Three additions that together address asymmetric / one-way gossipsub
delivery seen on small (2-3 node) overlay networks where the default
gossipsub mesh sits below its low-watermark and AutoNAT v1 cannot
reach a stable reachability verdict:

  * libp2p AutoNAT v2 is now in defaultLibp2pOptions. v1 needs >=3 peers
    to give a stable answer, leaving 2-peer clusters stuck in Unknown
    reachability and degrading downstream behaviour (relay selection,
    hole punching, identify). v2 produces a verdict from a single peer.

  * Gossipsub now uses FloodPublish + PeerExchange by default. FloodPublish
    has the publisher flood to ALL connected peers rather than just mesh
    peers; in a 2-node network the mesh sits at 1 entry (Dlo=4), well
    below the healthy-mesh threshold, and standard mesh-only delivery
    becomes unreliable. PeerExchange lets peers gossip about each other
    and helps recover from one-way mesh links.

  * When bootstrap peers are configured, they are passed to gossipsub as
    DirectPeers so the router holds a persistent connection and bypasses
    mesh negotiation when delivering to them — guaranteeing publication
    reaches known/seed peers regardless of mesh state.

The hub.NewHub signature gains a variadic Option parameter so callers
can opt in to direct-peer pinning without forcing the dependency into
the hub package's API. node.startNetwork is the only in-tree caller
and wires bootstrap peers through automatically.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mudler mudler merged commit 89092ec into master May 30, 2026
26 of 33 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant