148 lines
5.7 KiB
Markdown
148 lines
5.7 KiB
Markdown
go-tcp-transport
|
|
==================
|
|
|
|
[](https://protocol.ai)
|
|
[](https://libp2p.io/)
|
|
[](http://webchat.freenode.net/?channels=%23libp2p)
|
|
[](https://discuss.libp2p.io)
|
|
[](https://coveralls.io/github/libp2p/go-tcp-transport?branch=master)
|
|
[](https://travis-ci.com/libp2p/go-tcp-transport)
|
|
|
|
> A libp2p transport implementation for tcp, including reuseport socket options.
|
|
|
|
`go-tcp-transport` is an implementation of the [libp2p transport
|
|
interface][concept-transport] that streams data over TCP/IP sockets. It is
|
|
included by default in the main [`go-libp2p`][go-libp2p] "entry point" module.
|
|
|
|
## Table of Contents
|
|
|
|
- [go-tcp-transport](#go-tcp-transport)
|
|
- [Table of Contents](#table-of-contents)
|
|
- [Install](#install)
|
|
- [Usage](#usage)
|
|
- [Security and Multiplexing](#security-and-multiplexing)
|
|
- [reuseport](#reuseport)
|
|
- [Contribute](#contribute)
|
|
- [License](#license)
|
|
|
|
## 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:
|
|
|
|
``` sh
|
|
go get github.com/libp2p/go-tcp-transport
|
|
```
|
|
|
|
|
|
This repo is [gomod](https://github.com/golang/go/wiki/Modules)-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](https://github.com/golang/go/wiki/Modules#how-to-upgrade-and-downgrade-dependencies).
|
|
|
|
## Usage
|
|
|
|
TCP is one of the default transports enabled when constructing a standard libp2p
|
|
Host, along with [WebSockets](https://github.com/libp2p/go-ws-transport).
|
|
|
|
Calling [`libp2p.New`][godoc-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:
|
|
|
|
``` go
|
|
|
|
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`:
|
|
|
|
``` go
|
|
// 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][multiaddr] 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](https://github.com/multiformats/go-multiaddr-net) module.
|
|
|
|
## Security and Multiplexing
|
|
|
|
Because TCP lacks native connection security and stream multiplexing facilities,
|
|
the TCP transport uses a [transport upgrader][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`][explain-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](https://github.com/libp2p/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](https://github.com/RichardLitt/standard-readme) specification.
|
|
|
|
## License
|
|
|
|
MIT © Jeromy Johnson
|
|
|
|
---
|
|
|
|
The last gx published version of this module was: 2.0.28: QmTGiDkw4eeKq31wwpQRk5GwWiReaxrcTQLuCCLWgfKo5M
|
|
|
|
<!-- reference links -->
|
|
[go-libp2p]: https://github.com/libp2p/go-libp2p
|
|
[concept-transport]: https://docs.libp2p.io/concepts/transport/
|
|
[interface-host]: https://github.com/libp2p/go-libp2p-core/blob/master/host/host.go
|
|
[godoc-libp2p-new]: https://godoc.org/github.com/libp2p/go-libp2p#New
|
|
[transport-upgrader]: https://github.com/libp2p/go-libp2p-transport-upgrader
|
|
[explain-reuseport]: https://lwn.net/Articles/542629/
|
|
[multiaddr]: https://github.com/multiformats/multiaddr
|