README
¶
go-tcp-transport
A libp2p transport implementation for tcp, including reuseport socket options.
go-tcp-transport is an implementation of the libp2p transport
interface that streams data over TCP/IP sockets. It is
included by default in the main go-libp2p "entry point" module.
Table of Contents
Install
go-tcp-transport is included as a dependency of go-libp2p, which is the most
common libp2p entry point. If you depend on go-libp2p, there is generally no
need to explicitly depend on this module.
go-tcp-transport is a standard Go module which can be installed with:
go get github.com/libp2p/go-tcp-transport
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
TCP is one of the default transports enabled when constructing a standard libp2p Host, along with WebSockets.
Calling libp2p.New to construct a libp2p Host will enable
the TCP transport, unless you override the default transports by passing in
Options to libp2p.New.
To explicitly enable the TCP transport while constructing a host, use the
libp2p.Transport option, passing in the NewTCPTransport constructor function:
import (
"context"
libp2p "github.com/libp2p/go-libp2p"
tcp "github.com/libp2p/go-tcp-transport"
)
ctx := context.Background()
// TCP only:
h, err := libp2p.New(ctx,
libp2p.Transport(tcp.NewTCPTransport)
)
The example above will replace the default transports with a single TCP
transport. To add multiple tranports, use ChainOptions:
// TCP and QUIC:
h, err := libp2p.New(ctx,
libp2p.ChainOptions(
libp2p.Transport(tcp.NewTCPTransport),
libp2p.Transport(quic.NewTransport)) // see https://github.com/libp2p/go-libp2p-quic-transport
)
Addresses
The TCP transport supports multiaddrs that contain a tcp
component, provided that there is sufficient addressing information for the IP
layer of the connection.
Examples:
| addr | description |
|---|---|
/ip4/1.2.3.4/tcp/1234 |
IPv4: 1.2.3.4, TCP port 1234 |
/ip6/::1/tcp/1234 |
IPv6 loopback, TCP port 1234 |
/dns4/example.com/tcp/80 |
DNS over IPv4, hostname example.com, TCP port 80 |
Support for IP layer protocols is provided by the go-multiaddr-net module.
Security and Multiplexing
Because TCP lacks native connection security and stream multiplexing facilities, the TCP transport uses a transport upgrader to provide those features. The transport upgrader negotiates transport security and multiplexing for each connection according to the protocols supported by each party.
reuseport
The SO_REUSEPORT socket option allows multiple processes
or threads to bind to the same TCP port, provided that all of them set the
socket option. This has some performance benefits, and it can potentially assist
in NAT traversal by only requiring one port to be accessible for many
connections.
The reuseport functionality is provided by a seperate module,
go-reuseport-transport. It
is enabled by default, but can be disabled at runtime by setting the
LIBP2P_TCP_REUSEPORT environment variable to false or 0.
Contribute
PRs are welcome!
Small note: If editing the Readme, please conform to the standard-readme specification.
License
MIT © Jeromy Johnson
The last gx published version of this module was: 2.0.28: QmTGiDkw4eeKq31wwpQRk5GwWiReaxrcTQLuCCLWgfKo5M
Documentation
¶
Index ¶
- Variables
- func ReuseportIsAvailable() bool
- type TcpTransport
- func (t *TcpTransport) CanDial(addr ma.Multiaddr) bool
- func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (transport.CapableConn, error)
- func (t *TcpTransport) Listen(laddr ma.Multiaddr) (transport.Listener, error)
- func (t *TcpTransport) Protocols() []int
- func (t *TcpTransport) Proxy() bool
- func (t *TcpTransport) String() string
- func (t *TcpTransport) UseReuseport() bool
Constants ¶
This section is empty.
Variables ¶
var DefaultConnectTimeout = 5 * time.Second
DefaultConnectTimeout is the (default) maximum amount of time the TCP transport will spend on the initial TCP connect before giving up.
Functions ¶
func ReuseportIsAvailable ¶
func ReuseportIsAvailable() bool
reuseportIsAvailable returns whether reuseport is available to be used. This is here because we want to be able to turn reuseport on and off selectively. For now we use an ENV variable, as this handles our pressing need:
LIBP2P_TCP_REUSEPORT=false ipfs daemon
If this becomes a sought after feature, we could add this to the config. In the end, reuseport is a stop-gap.
Types ¶
type TcpTransport ¶
type TcpTransport struct {
// Connection upgrader for upgrading insecure stream connections to
// secure multiplex connections.
Upgrader *tptu.Upgrader
// Explicitly disable reuseport.
DisableReuseport bool
// TCP connect timeout
ConnectTimeout time.Duration
// contains filtered or unexported fields
}
TcpTransport is the TCP transport.
func NewTCPTransport ¶
func NewTCPTransport(upgrader *tptu.Upgrader) *TcpTransport
NewTCPTransport creates a tcp transport object that tracks dialers and listeners created. It represents an entire tcp stack (though it might not necessarily be)
func (*TcpTransport) CanDial ¶
func (t *TcpTransport) CanDial(addr ma.Multiaddr) bool
CanDial returns true if this transport believes it can dial the given multiaddr.
func (*TcpTransport) Dial ¶
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (transport.CapableConn, error)
Dial dials the peer at the remote address.
func (*TcpTransport) Protocols ¶
func (t *TcpTransport) Protocols() []int
Protocols returns the list of terminal protocols this transport can dial.
func (*TcpTransport) Proxy ¶
func (t *TcpTransport) Proxy() bool
Proxy always returns false for the TCP transport.
func (*TcpTransport) String ¶
func (t *TcpTransport) String() string
func (*TcpTransport) UseReuseport ¶
func (t *TcpTransport) UseReuseport() bool
UseReuseport returns true if reuseport is enabled and available.
Source Files