docs
docs copied to clipboard
Improve Protocol Documentation.
First of all, thanks for the documentation. I appreciate the effort that goes into it. Thing is, I just read the protocol section in the documentation here and I have to say it leaves me with more questions than answers.
What I got from it is basically that protocol allows nodes to communicate in a particular way. But I know that already from it being called protocol and I do not have to read the piece. The information about protocol Ids and protocol negotiation also does not provide much value.
I think what I am missing is:
- What is a structure of a protocol in libp2p? What interface does it provide, what are the rules to follow etc
- Do not just list examples of inbuilt protocol (Ping, Identify, secio etc) but show how to use them and relate it to the interface they provide.
- And maybe an advance section that quickly shows how to write a custom protocol.
I think the documentation on protocol will be improved is these points are taken into consideration.
Thanks for the feedback! We'll probably rewrite this soon so we'll keep this in mind. Do you think you would prefer a more tutorial-like version of this doc? Also if you have ideas here we're happy to review contributions.
Will address this in protocol rewrite by @DannyS03 or @p-shahi
Also address
This is a proposal for a tutorial to follow the current ["Getting Started"](https://docs.libp2p.io/tutorials/getting-started/) tutorials based on what I would have found useful as I've been getting to know libp2p in the last week or so.
The tutorial would be called "Implementing a Protocol" and would cover:
- Defining a protocol ID and setting a stream handler
- Reading and writing protocol data
- Defining a set of structured messages that make up the protocol
- Encoding / decoding protocol messages
- Handling different types of messages
- Handling an async request / response flow
- Handling protocol upgrades (i.e. version bumps, semver matching)
Rather than making up a protocol, I suggest using an existing, simple protocol that's easy to understand and doesn't distract from the point of the tutorial, perhaps [JSON-RPC](https://www.jsonrpc.org/specification) over libp2p?
@yusefnapora WDYT? I'd be happy to draft a Go version of this if you think it would be useful? I always like sharing my learning experience to make it easier for others 😄
https://github.com/libp2p/docs/issues/46