Skip to content

Commit a630d2b

Browse files
authored
chore: fix ping doc (#390)
* fix ping doc * fix lint
1 parent d07b55a commit a630d2b

File tree

2 files changed

+27
-42
lines changed

2 files changed

+27
-42
lines changed

content/concepts/fundamentals/protocols.md

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -135,11 +135,34 @@ length is encoded as a [protobuf varint](https://developers.google.com/protocol-
135135
[ping_js]: https://github.com/libp2p/js-libp2p-ping
136136
[ping_rust]: https://github.com/libp2p/rust-libp2p/blob/master/protocols/ping/src/lib.rs
137137

138-
The ping protocol is a simple liveness check that peers can use to quickly see if another peer is online.
138+
The libp2p ping protocol is a simple liveness check that peers can use to test
139+
the connectivity and performance between two peers. The libp2p ping protocol
140+
is different from the ping command line utility
141+
([ICMP ping](https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol)),
142+
as it requires an already established libp2p connection.
139143

140-
After the initial protocol negotiation, the dialing peer sends 32 bytes of random binary data. The listening
141-
peer echoes the data back, and the dialing peer will verify the response and measure
142-
the latency between request and response.
144+
> ICMP Ping is a network utility that uses ICMP packets to
145+
> check the connectivity and latency between two networked devices.
146+
> It is typically used to check the reachability of a host on an IP network and
147+
> to measure the round-trip time for messages sent from the originating host to a
148+
> destination host.
149+
150+
A peer opens a new stream on an existing libp2p connection and sends a ping request with a random 32 byte payload. The receiver echoes these 32 bytes back on the same stream. By measuring the time between the
151+
request and response, the initiator can calculate the round-trip time of the underlying libp2p connection.
152+
The stream can be reused for future pings from the initiator.
153+
154+
#### Example
155+
156+
[Kubo](https://github.com/ipfs/kubo) exposes a command line interface to ping other peers, which uses the libp2p ping protocol.
157+
158+
```shell
159+
ipfs ping /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/ping
160+
161+
PING /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/ping (QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG)
162+
32 bytes from QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG: time=11.34ms
163+
```
164+
165+
{{< alert icon="💡" context="note" text="See the ping <a class=\"text-muted\" href=\"https://github.com/libp2p/specs/blob/master/ping/ping.md\">technical specification</a> for more details." />}}
143166

144167
### Identify
145168

content/concepts/introduction/protocols/ping.md

Lines changed: 0 additions & 38 deletions
This file was deleted.

0 commit comments

Comments
 (0)