Skip to content

Improve Protocol Documentation. #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
finlaydotb opened this issue Dec 22, 2021 · 3 comments
Open

Improve Protocol Documentation. #120

finlaydotb opened this issue Dec 22, 2021 · 3 comments
Assignees
Labels
area:general General content and concepts P2 Medium type:enhancement Content enhancement, new feature or request.

Comments

@finlaydotb
Copy link

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.

@MarcoPolo
Copy link
Contributor

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.

@BigLep BigLep added P2 Medium P3 Low and removed P2 Medium labels Jul 1, 2022
@p-shahi
Copy link
Member

p-shahi commented Aug 26, 2022

Will address this in protocol rewrite by @DannyS03 or @p-shahi

@p-shahi p-shahi added P2 Medium and removed P3 Low labels Aug 26, 2022
@p-shahi
Copy link
Member

p-shahi commented Aug 26, 2022

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 😄 

#46

@salmad3 salmad3 self-assigned this Aug 29, 2022
@salmad3 salmad3 added type:enhancement Content enhancement, new feature or request. area:general General content and concepts labels Nov 23, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:general General content and concepts P2 Medium type:enhancement Content enhancement, new feature or request.
Projects
Status: No status
Development

No branches or pull requests

5 participants