Skip to content

feat(autonat-v2): emit address reachability events#3490

Open
tabcat wants to merge 4 commits into
libp2p:mainfrom
tabcat:feat/autonat-events
Open

feat(autonat-v2): emit address reachability events#3490
tabcat wants to merge 4 commits into
libp2p:mainfrom
tabcat:feat/autonat-events

Conversation

@tabcat
Copy link
Copy Markdown
Member

@tabcat tabcat commented May 5, 2026

Description

Closes #3472.

Adds an event surface to @libp2p/protocol-autonat-v2 so applications
can observe per-address reachability state as it changes.

The service now emits:

  • address:verifying { addr } — first-ever probe of this address has started
  • address:reachable { addr } — verdict reached or flipped to reachable
  • address:unreachable { addr } — verdict reached or flipped to unreachable
  • address:removed { addr } — an address that was being tracked is no
    longer present in the AddressManager

Plus matching getters:

  • service.verifying: Multiaddr[] — addresses currently being probed
    for the first time (no verdict yet)
  • service.reachable: Multiaddr[] — addresses currently REACHABLE
  • service.unreachable: Multiaddr[] — addresses currently UNREACHABLE

Subscribe via libp2p.services.autoNATv2.addEventListener('address:reachable', evt => …).

Notes & open questions

  • Service-local event bus (consistent with Circuit Relay v2's
    relay:created-reservation etc.), not the main libp2p event bus.
  • address:verifying fires only on the first probe of an address; TTL
    re-probes of a verdict'd address stay silent (the verdict persists,
    only an actual flip emits a new event).
  • For an observed address going UNREACHABLE, both address:unreachable
    and address:removed fire on different ticks — removeObservedAddr
    hard-deletes the observed entry, and the next reconcile pass detects
    its absence. The events convey separate signals (verdict vs lifecycle),
    so apps subscribe to whichever they care about.
  • A reachable address can also be removed without ever going unreachable
    (e.g. relay reservation drops, UPnP supersedes an observed entry,
    transport listener stops). Only address:removed fires in those cases.

Change checklist

  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation if necessary (this includes comments as well)
  • I have added tests that prove my fix is effective or that my feature works

tabcat and others added 3 commits May 5, 2026 22:46
Adds address:verifying, address:reachable, address:unreachable, and
address:removed events on the AutoNATv2 service, plus verifying,
reachable, and unreachable getters exposing current state.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@tabcat
Copy link
Copy Markdown
Member Author

tabcat commented May 5, 2026

@srene any feedback here is greatly appreciated.

@tabcat tabcat marked this pull request as ready for review May 5, 2026 15:53
@tabcat tabcat requested a review from a team as a code owner May 5, 2026 15:53
Replaces coined verb forms (verdicted/unverdicted) that tripped CSpell
with standard English ("new" / "reachable").

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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.

AutoNAT v2 does not expose reachability events

1 participant