Could the pubsub example be updated to explain what it does?

[markg85]

Hi,

I'm specifically talking about this example:
https://github.com/libp2p/js-libp2p/tree/master/examples/pubsub

What it does there is "magically working" but it's not explained at all why or how it is working.
Consider this bug report to be a bit of constructive feedback to hopefully get the example in super condition!
I'm also more then willing to update it myself and make a PR for that, but i have a hard time understanding what every line means thus i'm asking for some more verbosity.

  addresses: {
    listen: ['/ip4/0.0.0.0/tcp/0']
  },

What's that?
Do i put in one of the connect lines i see in my node when i type ipfs id?
Can i even use IPFS nodes? (nothing tells me i can or can't and as libp2p is a deep part of IPFS, it seems logical to think that i can).
What's the effect of adding that addresses object? Do i create a webserver of sorts by doing that?

const node1 = nodes[0]
const node2 = nodes[1]

Why do i need 2 nodes?
Isn't one node just connecting to the whole IPFS network?
Or should i consider this to be "bootstrapping" where i merely need "a node" to connect to the network as a whole?

node1.peerStore.addressBook.set(node2.peerId, node2.multiaddrs)

What is the peerstore? (this is deep internal technical knowledge of IPFS inner workings, that i do know...)
Why do i need to add a node to that? How am i supposed to know i need any of that?

await node1.dial(node2.peerId)

Say waaa?
Really, what's going on there?
Do i need to dial to all nodes manually and that way be a part of the whole network?
Does that mean i need to handle disconnects?
This really makes no sense to me.

node1.pubsub.on(topic, (msg) => {
  console.log(`node1 received: ${uint8ArrayToString(msg.data)}`)
})
await node1.pubsub.subscribe(topic)

node2.pubsub.on(topic, (msg) => {
  console.log(`node2 received: ${uint8ArrayToString(msg.data)}`)
})
await node2.pubsub.subscribe(topic)

Why do i need to publish and subscribe on 2 nodes?
There is "something" going on in that example with "2 nodes" that it doesn't explain at all.
I get that i need to subscribe and the handler for when a message comes in. That much is clear, but why i need to do it twice is totally unclear to me. Also, and i tested it, this gives me each message twice (which i was expecting with the example). Why would i even want that?

const defaults = {
  config: {
    pubsub: {
      enabled: true,
      emitSelf: false
    }
  }
}

Where can i find more information about the options?
If there is a place where a link to that makes sense, it most definitely is in the example of how to use it!

Also, emitSelf should imho really be false (like in the example) by default. I think it's true if you don't specify it.

I consider myself to be comparatively educated when it comes to IPFS and JavaScript. Yet this example and how libp2p works feels like it has been documented with a super high bias towards someone knowing the deep inner workings of libp2p itself. That makes it super difficult to follow the examples and make sense of it. Which is a bit of a shame as it's really awesome technology that more people should be using imho!

I have a whole slew of issues on top of this when i want to run it in the browser (most notably the libp2p-webrtc-star which is suggested as a must have on one place and about to be killed in another). But I'll leave this for another time.

As a general note for this pubsub example. I'd document it in such a way with the assumption that a user wants to connect to the IPFS network without using an IPFS node. And wants to be using the pubsub functionality in that network. The current example "seems" (i really don't know!) to be tailored towards demonstrating pubsub between 2 specific nodes.

Just fwiw. My personal usecase to want to have pubsub over IPFS is to let a website know that some information changed. Now i can definitely use a socket communication between the server of that site and the browser session. That works and is the old fashioned way of doing stuff centralized. I want the client side (the browser) to connect to a pubsub room where the server would post a message if there is an update. Nice and distributed, the "server" can be anywhere. An ideal case for pubsub to shine i think!

Let's make it an awesome example that's easy to understand! :)

Cheers,
Mark

[vasco-santos]

Hey @markg85

We want to keep the examples simple and direct, which is essential to keep them updated. We have most of the information you are looking for through the repo, and we really don't like the idea of replicating information as it will be prone to be outdated over time. Perhaps it is hidden?

I recommend you go through the list mention in Usage https://github.com/libp2p/js-libp2p#usage . After that, we have more details on the libp2p subsystems in scoped based READMES, such as:

• https://github.com/libp2p/js-libp2p/tree/master/src/address-manager
• https://github.com/libp2p/js-libp2p/tree/master/src/peer-store
• https://github.com/libp2p/js-libp2p/tree/master/src/record

If you have any ideas to improve the docs visibility and how you would expect them to be organised, I would be glad to discuss them with you. Meanwhile, if you don't find answers for some of your questions in the READMEs mentioned, please let me know and I can answer them.

[vasco-santos]

I am closing this issue. Feel free to reopen if you would like to proceed discussing on how we should improve the docs visibility