Compare commits

...

2 Commits

Author SHA1 Message Date
Stuckinaboot
e66167fba4 Add quickstart for stream creation 2019-04-21 14:00:51 -04:00
Stuckinaboot
95849b17bc Add libp2p node creation and node connection quickstart 2019-04-21 13:42:53 -04:00

View File

@ -37,6 +37,97 @@ pytest
```
Note that tests/libp2p/test_libp2p.py contains an end-to-end messaging test between two libp2p hosts, which is the bulk of our proof of concept.
## Quickstart Guide
This quickstart guide will teach you how to quickly get py-libp2p up and running, and how to take advantage of its various features. Since libp2p at its core is a distributed systems library, this quickstart guide will use explain all concepts with nodes. These two libp2p nodes that are labelled node1 and node2, respectively.
### Creating a libp2p node
A libp2p node, at a high-level, is used for connecting and communicating with peers running libp2p. Connecting with peers implies opening a connection to a peer over which communication via streams (discussed in next section) can take place.
First, we create a libp2p instance on node1 and start listening on port 8000:
```
node1
-----
import multiaddr
from libp2p import new_node
host = await new_node()
await host.get_network().listen(multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8000"))
```
Then, we create a libp2p instance on node2 and start listening on port 8001
```
node2
-----
import multiaddr
from libp2p import new_node
host = await new_node()
await host.get_network().listen(multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8001"))
```
Now, we have two libp2p nodes. Next, let's make them connect.
### Connecting two libp2p nodes
In order to connect node1 to node2, node1 must have node2 as a peer. This is so that the nodes know who they are connecting to. So, let's add node2 as a peer of node1 and let's add node1 as a peer of node2. TODO: dicuss p2p IDs
```
node1
-----
from libp2p.peer.peerinfo import info_from_p2p_addr
# Add node2 as a peer of node1
addr_of_node2 = multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8001/p2p/TODO")
info_node2 = info_from_p2p_addr(addr_of_node2)
# Connect node1 to node2
await node1.connect(info_node2)
```
### Streams between two peers
The central component to the libp2p paradigm is the stream, which represents a channel for communication over an underlying connection. There can be multiple streams over the same underlying connection. Here, we will go over how to setup two nodes to communicate over streams. When we create a new stream, we need to specify what protocol we would like to communicate over. In order for the opposing node to accept the new stream request, the opposing node needs to support at least one of the protocols specified in the new stream creation message.
First, node2 creates a stream handler for each protocol it supports. The stream handler will be hit when a new stream, initiated by an outside node, is successfully created on that particular protocol. For now, node2 will only support '/foo/1.0.0'.
```
node2
-----
async def stream_handler(stream):
read_data = await stream.read()
read_str = read_data.decode()
# Print read_str
print(read_str)
node2.set_stream_handler("/foo/1.0.0", stream_handler)
```
Next, node1 creates a new stream to node2 by specifiying node2's peer ID and the list of protocol node1 is willing to communicate with node2 over. Since, node2 only has a stream handler '/foo/1.0.0', node1 and node2 will agree to communicate over '/foo/1.0.0'.
```
node1
-----
supported_protocols = ["/foo/1.0.0", "/bar/1.0.0"]
stream = await node1.new_stream(node_b.get_id(), supported_protocols)
# Print out protocol id so we can see which protocol we will be communicating over
print(stream.protocol_id)
# Write data to stream
encoded_str = "I <3 libp2p".encode()
await stream.write(encoded_str)
```
Woohoo! We have successfully written data from node1 to node2. Streams can be used for much more complex communication than just prints. Also, node1 and node2 can open many streams to each other using this same code but with different supported protocols and stream handlers.
Note: In order for node2 to open a stream to node1, node2 must have node1 as a peer (remember, we only added node2 as a peer of node1 earlier). -- TODO: update this statement if we change this
### Floodsub between two peers
## Feature Breakdown
py-libp2p aims for conformity with [the standard libp2p modules](https://github.com/libp2p/libp2p/blob/master/REQUIREMENTS.md#libp2p-modules-implementations). Below is a breakdown of the modules we have developed, are developing, and may develop in the future.