stream

README

go-libp2p-transport-upgrader

Stream connection to libp2p connection upgrader

This package provides the necessary logic to upgrade multiaddr-net connections listeners into full libp2p-transport connections and listeners.

To use, construct a new Upgrader with:

• An optional pnet Protector.
• An optional multiaddr-net address Filter.
• A mandatory stream security transport.
• A mandatory stream multiplexer transport.

Note: This package largely replaces the functionality of go-libp2p-conn but with half the code.

Install

go-libp2p-transport-upgrader is a standard Go module which can be installed with:

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

Note that go-libp2p-transport-upgrader is packaged with Gx, so it is recommended to use Gx to install and use it (see the Usage section).

Usage

This module is packaged with Gx. In order to use it in your own project it is recommended that you:

go get -u github.com/whyrusleeping/gx
go get -u github.com/whyrusleeping/gx-go
cd <your-project-repository>
gx init
gx import github.com/libp2p/go-libp2p-transport-upgrader
gx install --global
gx-go --rewrite

Please check Gx and Gx-go documentation for more information.

Example

Below is a simplified TCP transport implementation using the transport upgrader. In practice, you'll want to use go-tcp-transport (which has reuseport support).

package tcptransport

import (
	"context"

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

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

// 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.Conn, 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 IPFS Code of Conduct.

Want to hack on IPFS?

License

MIT

Documentation

Index

• Variables
• type Upgrader
  • func (u *Upgrader) UpgradeInbound(ctx context.Context, t transport.Transport, maconn manet.Conn) (transport.Conn, 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.Conn, error)

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.

Types

type Upgrader

type Upgrader struct {
	Protector pnet.Protector
	Secure    ss.Transport
	Muxer     smux.Transport
	Filters   *filter.Filters
}

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.Conn, error)

UpgradeInbound upgrades the given inbound multiaddr-net connection into a full libp2p-transport connection.

func (*Upgrader) UpgradeListener

func (u *Upgrader) UpgradeListener(t transport.Transport, list manet.Listener) transport.Listener

UpgradeListener upgrades the passed multiaddr-net listener into a full libp2p-transport listener.

func (*Upgrader) UpgradeOutbound

func (u *Upgrader) UpgradeOutbound(ctx context.Context, t transport.Transport, maconn manet.Conn, p peer.ID) (transport.Conn, error)

UpgradeOutbound upgrades the given outbound multiaddr-net connection into a full libp2p-transport connection.