upgrader

package module
Version: v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2022 License: MIT Imports: 8 Imported by: 56

README

DEPRECATION NOTICE

This package has moved into go-libp2p as a sub-package, github.com/libp2p/go-libp2p/p2p/net/upgrader.

go-libp2p-transport-upgrader

GoDoc Build Status Discourse posts

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

Usage

To use, construct a new Upgrader with:

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

Overview

Deprecated: This package has moved into go-libp2p as a sub-package: github.com/libp2p/go-libp2p/p2p/net/upgrader.

Index

Constants

This section is empty.

Variables

View Source
var AcceptQueueLength = 16

AcceptQueueLength is the number of connections to fully setup before not accepting any new connections Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.AcceptQueueLength instead.

View Source
var ErrNilPeer = errors.New("nil peer")

ErrNilPeer is returned when attempting to upgrade an outbound connection without specifying a peer ID. Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.ErrNilPeer instead.

Functions

func New deprecated added in v0.7.0

func New(secureMuxer sec.SecureMuxer, muxer network.Multiplexer, opts ...Option) (transport.Upgrader, error)

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.New instead.

Types

type Option deprecated added in v0.7.0

type Option = upgrader.Option

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.Option instead.

func WithAcceptTimeout deprecated added in v0.7.0

func WithAcceptTimeout(t time.Duration) Option

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.WithAcceptTimeout instead.

func WithConnectionGater deprecated added in v0.7.0

func WithConnectionGater(g connmgr.ConnectionGater) Option

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.WithConnectionGater instead.

func WithPSK deprecated added in v0.7.0

func WithPSK(psk ipnet.PSK) Option

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.WithPSK instead.

func WithResourceManager deprecated added in v0.7.0

func WithResourceManager(m network.ResourceManager) Option

Deprecated: use github.com/libp2p/go-libp2p/p2p/net/upgrader.WithResourceManager instead.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL