echo

README

Echo client/server with libp2p

This is an example that quickly shows how to use the go-libp2p stack, including Host/Basichost, Network/Swarm, Streams, Peerstores and Multiaddresses.

This example can be started in either listen mode, or dial mode.

In listen mode, it will sit and wait for incoming connections on the /echo/1.0.0 protocol. Whenever it receives a stream, it will write the message "Hello, world!" over the stream and close it.

In dial mode, the node will start up, connect to the given address, open a stream to the target peer, and read a message on the protocol /echo/1.0.0.

Build

From go-libp2p base folder:

> make deps
> go build ./examples/echo

Usage

> ./echo -l 1235
2016/11/10 10:45:37 I am /ip4/127.0.0.1/tcp/1235/ipfs/QmNtX1cvrm2K6mQmMEaMxAuB4rTexhd87vpYVot4sEZzxc
2016/11/10 10:45:37 listening for connections

The listener libp2p host will print its Multiaddress, which indicates how it can be reached (ip4+tcp) and its randomly generated ID (QmNtX1cv...)

Now, launch another node that talks to the listener:

> ./echo -d /ip4/127.0.0.1/tcp/1235/ipfs/QmNtX1cvrm2K6mQmMEaMxAuB4rTexhd87vpYVot4sEZzxc -l 1236

The new node with send the message "Hello, world!" to the listener, which will in turn echo it over the stream and close it. The listener logs the message, and the sender logs the response.

Details

The makeBasicHost() function creates a go-libp2p-basichost object. basichost objects wrap go-libp2 swarms and should be used preferentially. A go-libp2p-swarm Network is a swarm which complies to the go-libp2p-net Network interface and takes care of maintaining streams, connections, multiplexing different protocols on them, handling incoming connections etc.

In order to create the swarm (and a basichost), the example needs:

• An ipfs-procotol ID like QmNtX1cvrm2K6mQmMEaMxAuB4rTexhd87vpYVot4sEZzxc. The example autogenerates this on every run. An optional key-pair to secure communications can be added to it. The example autogenerates them when using -secio.
• A Multiaddress, which indicates how to reach this peer. There can be several of them (using different protocols or locations for example). Example: /ip4/127.0.0.1/tcp/1234.
• A go-libp2p-peerstore, which is used as a address book which matches node IDs to the multiaddresses through which they can be contacted. This peerstore gets autopopulated when manually opening a connection (with Connect(). Alternatively, we can manually AddAddr() as in the example.

A basichost can now open streams (bi-directional channel between to peers) using NewStream and use them to send and receive data tagged with a Protocol.ID (a string). The host can also listen for incoming connections for a given Protocol with SetStreamHandle().

The example makes use of all of this to enable communication between a listener and a sender using protocol /echo/1.0.0 (which could be any other thing).