go-libp2p-transport-upgrader

Add encryption and multiplexing capabilities to libp2p transport connections

This package is a component of libp2p, a modular networking stack for building peer-to-peer applications.

For two libp2p peers to communicate, the connection between them must be secure, and each peer must be able to open multiple independent streams of communication over a single channel. We call connections with these features "capable" connections.

Many of the underlying transport protocols that are used by libp2p do not provide the required capabilities "out of the box." go-libp2p-transport-upgrader provides the necessary logic to upgrade connections and listeners into fully capable connections and connection listeners.

In order to be upgraded, the underlying connection or listener must be a multiaddr-net Conn or Listener. The multiaddr-net types integrate the Go standard library connection types with multiaddr, an extensible addressing format used throughout libp2p.

As well as the mandatory capabilities of security and multiplexing, the upgrader can optionally apply a Protector for private networking, as well as an address filter to prevent connections to specific addresses.

Install

Most people building applications with libp2p will have no need to install go-libp2p-transport-upgrader directly. It is included as a dependency of the main go-libp2p "entry point" module and is integrated into the libp2p Host.

For users who do not depend on go-libp2p and are managing their libp2p module dependencies in a more manual fashion, go-libp2p-transport-upgrader is a standard Go module which can be installed with:

go get github.com/libp2p/go-libp2p-transport-upgrader

This repo is gomod-compatible, and users of go 1.11 and later with modules enabled will automatically pull the latest tagged release by referencing this package. Upgrades to future releases can be managed using go get, or by editing your go.mod file as described by the gomod documentation.

Usage

To use, construct a new Upgrader with:

• An optional pnet Protector.
• An optional go-maddr-filter address Filter.
• A mandatory stream security transport.
• A mandatory stream multiplexer.

In practice, most users will not need to construct an Upgrader directly. Instead, when constructing a libp2p Host, you can pass in some combination of the PrivateNetwork, Filters, Security, and Muxer Options. This will configure the Upgrader that is created and used by the Host internally.

Example

Below is a simplified TCP transport implementation using the transport upgrader. In practice, you'll want to use go-tcp-transport, which is optimized for production usage.

package tcptransport

import (
	"context"

	tptu "github.com/libp2p/go-libp2p-transport-upgrader"

	ma "github.com/multiformats/go-multiaddr"
	mafmt "github.com/multiformats/go-multiaddr-fmt"
	manet "github.com/multiformats/go-multiaddr-net"
	tpt "github.com/libp2p/go-libp2p-core/transport"
	peer "github.com/libp2p/go-libp2p-core/peer"
)

// TcpTransport is a simple TCP transport.
type TcpTransport struct {
	// Connection upgrader for upgrading insecure stream connections to
	// secure multiplex connections.
	Upgrader *tptu.Upgrader
}

var _ tpt.Transport = &TcpTransport{}

// NewTCPTransport creates a new TCP transport instance.
func NewTCPTransport(upgrader *tptu.Upgrader) *TcpTransport {
	return &TcpTransport{Upgrader: upgrader}
}

// CanDial returns true if this transport believes it can dial the given
// multiaddr.
func (t *TcpTransport) CanDial(addr ma.Multiaddr) bool {
	return mafmt.TCP.Matches(addr)
}

// Dial dials the peer at the remote address.
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (tpt.CapableConn, error) {
	var dialer manet.Dialer
	conn, err := dialer.DialContext(ctx, raddr)
	if err != nil {
		return nil, err
	}
	return t.Upgrader.UpgradeOutbound(ctx, t, conn, p)
}

// Listen listens on the given multiaddr.
func (t *TcpTransport) Listen(laddr ma.Multiaddr) (tpt.Listener, error) {
	list, err := manet.Listen(laddr)
	if err != nil {
		return nil, err
	}
	return t.Upgrader.UpgradeListener(t, list), nil
}

// Protocols returns the list of terminal protocols this transport can dial.
func (t *TcpTransport) Protocols() []int {
	return []int{ma.P_TCP}
}

// Proxy always returns false for the TCP transport.
func (t *TcpTransport) Proxy() bool {
	return false
}

Contribute

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

This repository falls under the libp2p Code of Conduct.

Want to hack on libp2p?

License

MIT

The last gx published version of this module was: 0.1.28: QmeqC5shQjEBRG9B8roZqQCJ9xb7Pq6AbWxJFMyLgqBBWh