Merge pull request #473 from libp2p/marco/spec-ping

Add ping spec

README.md

@@ -72,6 +72,7 @@ security, multiplexing, and other purposes.
 
 The protocols described below all use [protocol buffers](https://developers.google.com/protocol-buffers/docs/proto?hl=en) (aka protobuf) to define message schemas. Version `proto2` is used unless stated otherwise.
 
+- [ping][spec_ping] - Ping protocol
 - [autonat][spec_autonat] - NAT detection
 - [identify][spec_identify] -  Exchange keys and addresses with other peers
 - [kademlia][spec_kademlia] - The Kademlia Distributed Hash Table (DHT) subsystem
@@ -131,3 +132,4 @@ you feel an issue isn't the appropriate place for your topic, please join our
 [spec_dcutr]: ./relay/DCUtR.md
 [spec_webrtc]: ./webrtc/README.md
 [spec_webtransport]: ./webtransport/README.md
+[spec_ping]: ./ping/ping.md

ping/ping.md

@@ -0,0 +1,62 @@
+# Ping <!-- omit in toc -->
+
+| Lifecycle Stage | Maturity                 | Status | Latest Revision |
+| --------------- | ------------------------ | ------ | --------------- |
+| 3A              | Recommendation | Active | r0, 2022-11-04  |
+
+Authors: [@marcopolo]
+
+Interest Group: [@marcopolo], [@mxinden], [@marten-seemann]
+
+[@marcopolo]: https://github.com/mxinden
+[@mxinden]: https://github.com/mxinden
+[@marten-seemann]: https://github.com/marten-seemann
+
+# Table of Contents <!-- omit in toc -->
+- [Protocol](#protocol)
+- [Diagram](#diagram)
+
+# Protocol
+
+The ping protocol is a simple request response protocol. The client opens a
+stream, sends a payload of 32 random bytes, and the server responds with the
+same 32 bytes on that stream. The client then measures the RTT from the time it
+wrote the bytes to the time it received the bytes. The client MAY repeat the
+process by sending another payload with random bytes on the same stream, so the
+server SHOULD loop and echo the next payload. The client SHOULD close the write
+side of the stream after sending the last payload, and the server SHOULD finish
+writing the echoed payload and then exit the loop and close the stream.
+
+The client MUST NOT keep more than one outbound stream for the ping protocol per
+peer. The server SHOULD accept at most 2 streams per peer since cross stream
+behavior is not linearizable for client and server. In other words, the client
+closing stream A and then opening stream B, might be perceived by the server as
+the client opening stream B and then closing stream A.
+
+The protocol id is `/ipfs/ping/1.0.0`.
+
+# Diagram
+
+![Ping Protocol Diagram](./ping.svg)
+
+<details>
+  <summary>Instructions to reproduce diagram</summary>
+
+From the root, run:  `plantuml -tsvg ping/ping.md`
+
+```
+@startuml
+skinparam backgroundColor white
+
+entity Client
+entity Server
+
+== /ipfs/ping/1.0.0 ==
+loop until Client closes write
+    Client -> Server: 32 random bytes
+    Client <- Server: Same 32 random bytes
+end
+@enduml
+```
+
+</details>