AtHeartEngineer/specs
1
0
Fork 0
mirror of https://github.com/vacp2p/specs.git synced 2026-01-08 23:08:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Add ping spec
This commit is contained in:
Marco Munizaga
2022-11-15 07:41:20 -08:00
committed by GitHub
parent 29a6b49df8 bdbb9a1fa7
commit a2e37364c1
3 changed files with 86 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -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

62
ping/ping.md Normal file
View File

@@ -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>

22
ping/ping.svg Normal file
View File

@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="264px" preserveAspectRatio="none" style="width:263px;height:264px;background:#FFFFFF;" version="1.1" viewBox="0 0 263 264" width="263px" zoomAndPan="magnify"><defs><filter height="300%" id="f1ko2it6ligp4y" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><rect fill="#FFFFFF" filter="url(#f1ko2it6ligp4y)" height="75.9316" style="stroke:#000000;stroke-width:2.0;" width="236" x="10" y="113.7988"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="43" x2="43" y1="53.4883" y2="206.7305"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="209.5" x2="209.5" y1="53.4883" y2="206.7305"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="40" x="20" y="50.5352">Client</text><ellipse cx="43" cy="21" fill="#FEFECE" filter="url(#f1ko2it6ligp4y)" rx="12" ry="12" style="stroke:#A80036;stroke-width:2.0;"/><line style="stroke:#A80036;stroke-width:2.0;" x1="31" x2="55" y1="35" y2="35"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="40" x="20" y="219.2656">Client</text><ellipse cx="43" cy="238.2188" fill="#FEFECE" filter="url(#f1ko2it6ligp4y)" rx="12" ry="12" style="stroke:#A80036;stroke-width:2.0;"/><line style="stroke:#A80036;stroke-width:2.0;" x1="31" x2="55" y1="252.2188" y2="252.2188"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="43" x="185.5" y="50.5352">Server</text><ellipse cx="210" cy="21" fill="#FEFECE" filter="url(#f1ko2it6ligp4y)" rx="12" ry="12" style="stroke:#A80036;stroke-width:2.0;"/><line style="stroke:#A80036;stroke-width:2.0;" x1="198" x2="222" y1="35" y2="35"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="43" x="185.5" y="219.2656">Server</text><ellipse cx="210" cy="238.2188" fill="#FEFECE" filter="url(#f1ko2it6ligp4y)" rx="12" ry="12" style="stroke:#A80036;stroke-width:2.0;"/><line style="stroke:#A80036;stroke-width:2.0;" x1="198" x2="222" y1="252.2188" y2="252.2188"/><rect fill="#EEEEEE" filter="url(#f1ko2it6ligp4y)" height="3" style="stroke:#EEEEEE;stroke-width:1.0;" width="256" x="0" y="84.1436"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="256" y1="84.1436" y2="84.1436"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="256" y1="87.1436" y2="87.1436"/><rect fill="#EEEEEE" filter="url(#f1ko2it6ligp4y)" height="23.3105" style="stroke:#000000;stroke-width:2.0;" width="128" x="64" y="73.4883"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="110" x="70" y="90.0566">/ipfs/ping/1.0.0</text><path d="M10,113.7988 L84,113.7988 L84,120.7988 L74,130.7988 L10,130.7988 L10,113.7988 " fill="#EEEEEE" style="stroke:#000000;stroke-width:1.0;"/><rect fill="none" height="75.9316" style="stroke:#000000;stroke-width:2.0;" width="236" x="10" y="113.7988"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="29" x="25" y="127.3672">loop</text><text fill="#000000" font-family="sans-serif" font-size="11" font-weight="bold" lengthAdjust="spacing" textLength="142" x="99" y="126.4336">[until Client closes write]</text><polygon fill="#A80036" points="198,148.4199,208,152.4199,198,156.4199,202,152.4199" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="43" x2="204" y1="152.4199" y2="152.4199"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="106" x="50" y="147.6777">32 random bytes</text><polygon fill="#A80036" points="54,177.7305,44,181.7305,54,185.7305,50,181.7305" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="48" x2="209" y1="181.7305" y2="181.7305"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="143" x="60" y="176.9883">Same 32 random bytes</text><!--MD5=[49c3de5794ea7d725149ba6285c2a226]
@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
PlantUML version 1.2021.12(Tue Oct 05 09:01:58 PDT 2021)
(GPL source distribution)
Java Runtime: OpenJDK Runtime Environment
JVM: OpenJDK 64-Bit Server VM
Default Encoding: UTF-8
Language: en
Country: US
--></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB