README
¶
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
Documentation
¶
Index ¶
- Variables
- type Upgrader
- func (u *Upgrader) UpgradeInbound(ctx context.Context, t transport.Transport, maconn manet.Conn) (transport.CapableConn, error)
- func (u *Upgrader) UpgradeListener(t transport.Transport, list manet.Listener) transport.Listener
- func (u *Upgrader) UpgradeOutbound(ctx context.Context, t transport.Transport, maconn manet.Conn, p peer.ID) (transport.CapableConn, error)
Constants ¶
This section is empty.
Variables ¶
var AcceptQueueLength = 16
AcceptQueueLength is the number of connections to fully setup before not accepting any new connections
var ErrNilPeer = errors.New("nil peer")
ErrNilPeer is returned when attempting to upgrade an outbound connection without specifying a peer ID.
Functions ¶
This section is empty.
Types ¶
type Upgrader ¶
type Upgrader struct {
PSK ipnet.PSK
Secure sec.SecureTransport
Muxer mux.Multiplexer
ConnGater connmgr.ConnectionGater
}
Upgrader is a multistream upgrader that can upgrade an underlying connection to a full transport connection (secure and multiplexed).
func (*Upgrader) UpgradeInbound ¶
func (u *Upgrader) UpgradeInbound(ctx context.Context, t transport.Transport, maconn manet.Conn) (transport.CapableConn, error)
UpgradeInbound upgrades the given inbound multiaddr-net connection into a full libp2p-transport connection.
func (*Upgrader) UpgradeListener ¶
UpgradeListener upgrades the passed multiaddr-net listener into a full libp2p-transport listener.
Source Files