feat(health): /ipfs/ping/1.0.0 probe, docs, real-network tests, and GUI (#1453) - #1455
Merged
Merged
Conversation
acul71
force-pushed
the
fix/health-monitor-ping-protocol-1453
branch
from
August 18, 2026 12:48
517f456 to
71c9550
Compare
libp2p#1453) Resolves libp2p#1453 — follow-up to the opt-in connection health monitor from PR libp2p#1203. - Add `libp2p/network/health/ping_probe.py`: per-connection `/ipfs/ping/1.0.0` probe using multiselect negotiation + the existing `_ping()` wire format. Returns a `ConnectionPingResult(success, rtt_ms, protocol_supported, skipped)`. - Unsupported ping protocol counted as alive; negotiation RTT recorded. - Probes run even when application streams are open (skip-if-busy is opt-in via `skip_ping_when_streams_open=False` default). - Export `perform_ping_roundtrip()` from `libp2p/host/ping.py` as a public helper. - Refactor `ConnectionHealthMonitor._ping_connection()` to delegate to the new probe and return the structured result; fix latency to use actual ping RTT. - Three new `ConnectionConfig` fields: - `skip_ping_when_streams_open` (default `False`) - `record_ping_latency_in_peerstore` (default `True`) — writes RTT into peerstore LatencyEWMA after each successful ping. - `abort_connection_on_ping_failure` (default `False`) — immediately closes a connection that fails its probe without waiting for the grace-period. - Add `health-demo = ["rich>=13.0"]` optional dependency for the TUI. - Update `tests/core/network/test_health_monitor.py` to mock the new `ping_connection` helper; add cases for unsupported protocol, busy-conn default ping, skip-when-streams-open opt-in, abort-on-failure, and peerstore latency recording. - New `tests/core/network/test_health_ping_probe.py`: real two-host integration tests over live TCP. - New `tests/core/network/test_health_monitor_real_network.py`: non-loopback integration test (skipped on loopback-only environments) asserting RTT updates and closed-connection detection. - Extend `tests/utils/factories.py` to accept an optional `connection_config` parameter in `SwarmFactory`, `HostFactory`, and `host_pair_factory`. - New `docs/connection_health_monitoring.rst`: py-libp2p-only user guide (overview, when-to-enable, full config reference, host/swarm API, operator guide with live demo CLI flags). - Rewrite `docs/examples.connection_health_monitoring.rst`: remove go/js-libp2p comparison language; link to user guide; keep runnable snippets. - Expand `docs/libp2p.network.health.rst` with narrative intro, cross-links, and `ping_probe` automodule; wire into Sphinx TOCs. - Clean `examples/health_monitoring/README.md`: remove comparison language; add GUI usage instructions. - New `examples/health_monitoring/health_view.py`: shared `build_peer_table()` and `get_metrics_snapshot()` helpers. - New `examples/health_monitoring/tui.py`: terminal table with `rich` rendering (ANSI fallback when rich is not installed). - New `examples/health_monitoring/web_gui.py`: stdlib HTTP server on `127.0.0.1:8765` with `GET /`, `GET /api/summary`, `GET /api/metrics` (supports `?format=prometheus`). - Wire `--gui none|tui|web` and `--gui-port` into `live_demo.py`. make pr and make docs pass. Co-authored-by: Cursor <cursoragent@cursor.com>
acul71
force-pushed
the
fix/health-monitor-ping-protocol-1453
branch
from
September 3, 2026 19:33
71c9550 to
8d48e85
Compare
Add the release newsfragment, close aborted/replaced connections through SwarmConn.close, HTML-escape the demo web UI, harden real-network and peerstore tests, and drop go-libp2p wording from monitor comments. Co-authored-by: Cursor <cursoragent@cursor.com>
Wait for health metrics and a record_latency spy instead of EWMA > 0, which fails on CI when integer-ms RTT truncates to zero. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1453 — follow-up to #1203 (opt-in connection health monitor).
What's changed
Protocol
libp2p/network/health/ping_probe.py— per-connection/ipfs/ping/1.0.0probe using multiselect negotiation. Returns a typedConnectionPingResult(success, rtt_ms, protocol_supported, skipped).skip_ping_when_streams_open=False).perform_ping_roundtrip()fromlibp2p/host/ping.pyas a public helper.ConnectionHealthMonitor._ping_connection()to delegate to the new probe; fix latency accounting to use actual ping RTT.ConnectionConfigfields:skip_ping_when_streams_open(defaultFalse) — opt-in to skip probing busy connections.record_ping_latency_in_peerstore(defaultTrue) — write RTT into peerstoreLatencyEWMAafter each successful ping.abort_connection_on_ping_failure(defaultFalse) — immediately close a failing connection without waiting for the grace period.health-demo = ["rich>=13.0"]optional dependency for the TUI.Tests
tests/core/network/test_health_monitor.pywith mockedping_connection; add cases for unsupported protocol, default ping-while-busy, skip-when-streams-open opt-in, abort-on-failure, and peerstore latency recording.tests/core/network/test_health_ping_probe.py— real two-host integration tests over live TCP.tests/core/network/test_health_monitor_real_network.py— non-loopback integration test (auto-skipped on loopback-only CI) asserting RTT updates and closed-connection detection.tests/utils/factories.pyto accept optionalconnection_configinSwarmFactory,HostFactory, andhost_pair_factory.Documentation
docs/connection_health_monitoring.rst— py-libp2p-only user guide: overview, when-to-enable, full config reference, host/swarm API shapes, operator guide.docs/examples.connection_health_monitoring.rst— remove go/js-libp2p comparison language; cross-link to user guide.docs/libp2p.network.health.rst— narrative intro, cross-links,ping_probeautomodule; wire into Sphinx TOCs.examples/health_monitoring/README.md— remove comparison language; document GUI usage.Health GUI
examples/health_monitoring/health_view.py— sharedbuild_peer_table()andget_metrics_snapshot()helpers.examples/health_monitoring/tui.py— terminal table withrichrendering (ANSI fallback).examples/health_monitoring/web_gui.py— stdlib HTTP server on127.0.0.1:8765withGET /,GET /api/summary,GET /api/metrics(supports?format=prometheus).--gui none|tui|weband--gui-portintolive_demo.py.make prandmake docspass.Made with Cursor