libp2p Demos

Demo 1: DHT for Connecting Peers & Sharing Content (Go and JS nodes)

Directory: content-dht-provide-find

What it demonstrates: A new DHT is created by the Go program dht-interop. In a separate terminal or machine, a Node.js program connects to this DHT. One connected, each verifies that it can find the other's content via the DHT.

First terminal:

cd content-dht-provide-find
make
./dht-interop -b ../util/private_key.bin.bootstrapper.Wa

-b means bootstrap mode. In this example, the go program is always the bootstrap node, so -b is always required. (TODO: eliminate this superfluous option)

Note that the node ID of dht-interop is always Qm...6aJ9oRuEzWa because it is being read in from ../util/private_key.bin.bootstrapper.Wa (a private key marshalled to X.509 generated by the program util/private-key-gen). This is to keep the peer id of the bootstrap server stable across invocations.

Second terminal: run the command printed out by dht-interop, replacing 127.0.0.1 with the IP of the server where dht-interop is listening. Example:

Running the Node.js program:

cd content-dht-provide-find/js-dht-test
npm install  # first time only
node js-dht-test/index.js /ip4/127.0.0.1/tcp/5555/ipfs/QmehVYruznbyDZuHBV4vEHESpDevMoAovET6aJ9oRuEzWa

Demo 2: PubSub

Directory: pubsub

What it demonstrates: Two Go peers, one JS peer, and one Rust peer are all created and run a chat server using a shared PubSub topic. Typing text in any peer sends it to all the other peers.

Quick test: cd pubsub and then run ./test/test.sh. Requires Terminator (eg, sudo apt-get install terminator). The rest of this section describes how to test manually.

(TODO: maybe eliminate centralized bootstrapper; any peer could then bootstrap from any other peer and peers could start in any order; downside is the code will be more complex in all peers)

First terminal: Create the bootstrapper node

cd pubsub
./pubsub-interop ../util/private_key.bin.bootstrapper.Wa --bootstrapper

The bootstrapper creates a new libp2p node, subscribes to the shared topic string, spawns a go routine to emit any publishes to that topic, and then waits forever.

(Note that the node ID of pubsub-interop is going to be Qm...6aJ9oRuEzWa. Node IDs in libp2p are just public keys, and the public key Qm...6aJ9oRuEzWa is derived from the private key file ../util/private_key.bin.bootstrapper.Wa. That file is just an X.509 keypair generated by the included program util/private-key-gen). We use fixed public/private keypairs for each node in this example to keep things simple.)

Second terminal: Create a go peer to connect to bootstrapper and publish on the topic

cd pubsub
./pubsub-interop ../util/private_key.bin.peer.Sk

This peer, which is not in bootstrapper mode, creates a node, subscribes to the shared topic string, spawns the same go routine, and then loops forever requesting user input and publishing each line to the topic.

Third terminal: Create a JS peer to connect to bootstrap and publish on topic

cd pubsub/js
npm install  # first time only
node index.js /ip4/127.0.0.1/tcp/5555/ipfs/QmehVYruznbyDZuHBV4vEHESpDevMoAovET6aJ9oRuEzWa

This JS peer will accept lines of text typed on stdin, and publish them on the PubSub topic.

(Note that the JS peer generates a new identity (public/private keypair) each time, and prints its public key to stdout. This is a deficiency in the demo; to be consistent with the Go code it should accept a private key on the CLI.)

Fourth terminal: Creates a Rust peer to connect to the bootstrap node and then subscribe and publish on the topic:

cd pubsub/rust
cargo run

The Rust peer starts up, listens on port 6002, and then dials the boostrap peer. (TODO: rust-libp2p#471) It is now subscribed to the same topic as the other peers.

If you return to the second, third or fourth terminals and type a message, the bootstrapper and the other 2 peers will all print your message.

Conclusion

You now have a chat app on a private libp2p network where each node can exchange messages using PubSub.

Debugging Notes

JS To see debug messages from the Node.js program, use the DEBUG environment variable:

DEBUG="libp2p:floodsub*,libp2p:switch*,mss:*" node index.js [args...]

Go To see debug messages in Go programs, do this at runtime:

IPFS_LOGGING=debug ./pubsub-interop [args...]

(TODO: describe custom instrumenting the local go code for complex debugging)

If you instrument your go code with custom fmt.Println's, then revert back like this:

cd $GOPATH
go get -u ./...

Other useful commands:

go get -u github.com/libp2p/go-libp2p-kad-dht   # fetch just Kad DHT repo

Acknowledgements: @jhiesey for DHT (content & peer routing) JS+Go interop, @stebalien for PubSub