From 8383370a89ef85da7cba32831c87c8fa372da0d4 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 4 Nov 2022 17:46:45 -0700 Subject: [PATCH 1/4] Add ping spec --- ping/ping.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++ ping/ping.svg | 22 ++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 ping/ping.md create mode 100644 ping/ping.svg diff --git a/ping/ping.md b/ping/ping.md new file mode 100644 index 000000000..196058fa2 --- /dev/null +++ b/ping/ping.md @@ -0,0 +1,56 @@ +# Ping + +| Lifecycle Stage | Maturity | Status | Latest Revision | +| --------------- | ------------------------ | ------ | --------------- | +| 1A | Candidate 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 +- [Protocol](#protocol) +- [Diagram](#diagram) + +# Protocol + +The ping protocol is a simple request response protocol. The client sends a +payload of 32 random bytes, and the server responds with the same 32 bytes. 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, so the server _should_ loop and echo the next payload. The +client may close the write side of the stream after sending a payload, the +server _should_ finish writing the echoed payload and then exit the loop and +close the stream. + +The protocol id is `/ipfs/ping/1.0.0`. + +# Diagram + +![Ping Protocol Diagram](./ping.svg) + +
+ Instructions to reproduce diagram + +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 +``` + +
\ No newline at end of file diff --git a/ping/ping.svg b/ping/ping.svg new file mode 100644 index 000000000..51edd425e --- /dev/null +++ b/ping/ping.svg @@ -0,0 +1,22 @@ +ClientClientServerServer/ipfs/ping/1.0.0loop[until Client closes write]32 random bytesSame 32 random bytes \ No newline at end of file From 8af5686ad924ea5f5a95fff6b0f2f04ce8b7afd4 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Sat, 5 Nov 2022 05:45:03 -0700 Subject: [PATCH 2/4] More precise language --- README.md | 2 ++ ping/ping.md | 22 ++++++++++++++-------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ef45cc94e..1480e0712 100644 --- a/README.md +++ b/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 @@ -129,3 +130,4 @@ you feel an issue isn't the appropriate place for your topic, please join our [spec_autonat]: ./autonat/README.md [spec_dcutr]: ./relay/DCUtR.md [spec_webtransport]: ./webtransport/README.md +[spec_ping]: ./ping/ping.md diff --git a/ping/ping.md b/ping/ping.md index 196058fa2..f03804e9c 100644 --- a/ping/ping.md +++ b/ping/ping.md @@ -18,14 +18,20 @@ Interest Group: [@marcopolo], [@mxinden], [@marten-seemann] # Protocol -The ping protocol is a simple request response protocol. The client sends a -payload of 32 random bytes, and the server responds with the same 32 bytes. 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, so the server _should_ loop and echo the next payload. The -client may close the write side of the stream after sending a payload, the -server _should_ finish writing the echoed payload and then exit the loop and -close the stream. +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`. From a26355033ac4499f887eb924e664adc5b03e250a Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Sat, 5 Nov 2022 05:46:40 -0700 Subject: [PATCH 3/4] Fix double space --- ping/ping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ping/ping.md b/ping/ping.md index f03804e9c..4941e5920 100644 --- a/ping/ping.md +++ b/ping/ping.md @@ -28,7 +28,7 @@ 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 +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. From bdbb9a1fa7ce1979b2369fc6d7bfb33eb0d9f1eb Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Tue, 15 Nov 2022 07:41:00 -0800 Subject: [PATCH 4/4] Update ping/ping.md Co-authored-by: Max Inden --- ping/ping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ping/ping.md b/ping/ping.md index 4941e5920..e6d036296 100644 --- a/ping/ping.md +++ b/ping/ping.md @@ -2,7 +2,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | | --------------- | ------------------------ | ------ | --------------- | -| 1A | Candidate Recommendation | Active | r0, 2022-11-04 | +| 3A | Recommendation | Active | r0, 2022-11-04 | Authors: [@marcopolo]