transport

README

go-libp2p-transport

libp2p transport code

A common interface for network transports.

This is the 'base' layer for any transport that wants to be used by libp2p and ipfs. If you want to make 'ipfs work over X', the first thing you'll want to do is to implement the Transport interface for 'X'.

Transports are:

• Encrypted: Connections must be end-to-end encrypted.
• Authenticated: The endpoints, RemotePeer and LocalPeer, must be authenticated.
• Multiplexed: It must be possible to multiplex multiple reliable streams over a single transport connection.

Install

> gx install --global
> gx-go rewrite

Usage

To actually use a transport, you'll likely want to register it with a transport.Network (e.g., go-libp2p-swarm). However, you're probably more interested in implementing transports.

Transports construct fully featured, encrypted, multiplexed connections. However, there's a fairly good chance your transport won't meet all of those requirements. To make life easier, we've created a helper library called go-libp2p-transport-upgrader for upgrading simple stream transports to fully-featured (encrypted, authenticated, multiplexed) transports. Check out that package's README for an example.

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

MIT

Documentation

Index

• Variables
• type Conn
• type Listener
• type Network
• type Transport

Variables

var AcceptTimeout = 60 * time.Second

AcceptTimeout is the maximum duration an Accept is allowed to take. This includes the time between accepting the raw network connection, protocol selection as well as the handshake, if applicable.

var DialTimeout = 60 * time.Second

DialTimeout is the maximum duration a Dial is allowed to take. This includes the time between dialing the raw network connection, protocol selection as well the handshake, if applicable.

Types

type Conn

type Conn interface {
	smux.Conn
	inet.ConnSecurity
	inet.ConnMultiaddrs

	// Transport returns the transport to which this connection belongs.
	Transport() Transport
}

Conn is an extension of the net.Conn interface that provides multiaddr information, and an accessor for the transport used to create the conn

type Listener

type Listener interface {
	Accept() (Conn, error)
	Close() error
	Addr() net.Addr
	Multiaddr() ma.Multiaddr
}

Listener is an interface closely resembling the net.Listener interface. The only real difference is that Accept() returns Conn's of the type in this package, and also exposes a Multiaddr method as opposed to a regular Addr method

type Network

type Network interface {
	inet.Network

	// AddTransport adds a transport to this Network.
	//
	// When dialing, this Network will iterate over the protocols in the
	// remote multiaddr and pick the first protocol registered with a proxy
	// transport, if any. Otherwise, it'll pick the transport registered to
	// handle the last protocol in the multiaddr.
	//
	// When listening, this Network will iterate over the protocols in the
	// local multiaddr and pick the *last* protocol registered with a proxy
	// transport, if any. Otherwise, it'll pick the transport registered to
	// handle the last protocol in the multiaddr.
	AddTransport(t Transport) error
}

Network is an inet.Network with methods for managing transports.

type Transport

type Transport interface {
	// Dial dials a remote peer. It should try to reuse local listener
	// addresses if possible but it may choose not to.
	Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (Conn, error)

	// CanDial returns true if this transport knows how to dial the given
	// multiaddr.
	//
	// Returning true does not guarantee that dialing this multiaddr will
	// succeed. This function should *only* be used to preemptively filter
	// out addresses that we can't dial.
	CanDial(addr ma.Multiaddr) bool

	// Listen listens on the passed multiaddr.
	Listen(laddr ma.Multiaddr) (Listener, error)

	// Protocol returns the set of protocols handled by this transport.
	//
	// See the Network interface for an explanation of how this is used.
	Protocols() []int

	// Proxy returns true if this is a proxy transport.
	//
	// See the Network interface for an explanation of how this is used.
	// TODO: Make this a part of the go-multiaddr protocol instead?
	Proxy() bool
}

Transport represents any device by which you can connect to and accept connections from other peers. The built-in transports provided are TCP and UTP but many more can be implemented, sctp, audio signals, sneakernet, UDT, a network of drones carrying usb flash drives, and so on.