surge-ping

surge-ping is an asynchronous ICMP ping library for Rust. It lets you send ICMP echo requests and await the replies from async code, sharing a single system socket across many targets so you can ping thousands of hosts concurrently without opening thousands of sockets. It supports IPv4 and IPv6 and can use non-privileged DGRAM sockets on Linux.

What You Get

• A ping shortcut for one-off echo requests and a Client for high-fan-out pinging
• One shared socket multiplexed across many Pinger targets by (address, identifier, sequence)
• Full IPv4 (ICMP) and IPv6 (ICMPv6) support
• Non-privileged pinging on Linux via DGRAM sockets, with a RAW-socket fallback elsewhere

Common Use Cases

• Building network monitoring and uptime probes that ping many hosts at once
• Measuring round-trip latency to endpoints from async services
• Discovering reachable hosts across a subnet concurrently

Under The Hood

Architecture — client.rs defines the Client, which owns one socket2 socket and spawns a single background task that reads every inbound reply and routes it to a waiter keyed by (address, identifier, sequence). ping.rs holds the Pinger and the top-level ping shortcut; the icmp module builds and parses ICMP/ICMPv6 echo packets via pnet_packet; config.rs exposes a ConfigBuilder for bind address, interface, and TTL; error.rs carries the error type.

Tech Stack — Rust 2024 edition (rust-version 1.85). Key dependencies are tokio (time, sync, net, rt) for the async runtime, socket2 for low-level socket configuration, pnet_packet for ICMP packet construction, parking_lot for the waiter registry, rand for identifiers, thiserror for errors, and tracing for diagnostics.

Code Quality — The crate ships integration tests under tests/ (including a client-destroyed teardown case) and several runnable examples (simple, cmd, multi_ping). Errors are modeled explicitly with thiserror, and the shared-socket design is documented in the README with an architecture diagram.

API Design — Two clear entry points match the two common needs: ping() for a single quick request, and Client plus Pinger for scaled, concurrent pinging. Cloning a Client is cheap and intended, so the ergonomics naturally guide users toward the efficient one-socket pattern.