1go-tcp-transport 2================== 3 4[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai) 5[![](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](https://libp2p.io/) 6[![](https://img.shields.io/badge/freenode-%23libp2p-yellow.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23libp2p) 7[![Discourse posts](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg)](https://discuss.libp2p.io) 8[![Coverage Status](https://coveralls.io/repos/github/libp2p/go-tcp-transport/badge.svg?branch=master)](https://coveralls.io/github/libp2p/go-tcp-transport?branch=master) 9[![Travis CI](https://travis-ci.com/libp2p/go-tcp-transport.svg?branch=master)](https://travis-ci.com/libp2p/go-tcp-transport) 10 11> A libp2p transport implementation for tcp, including reuseport socket options. 12 13`go-tcp-transport` is an implementation of the [libp2p transport 14interface][concept-transport] that streams data over TCP/IP sockets. It is 15included by default in the main [`go-libp2p`][go-libp2p] "entry point" module. 16 17## Table of Contents 18 19- [go-tcp-transport](#go-tcp-transport) 20 - [Table of Contents](#table-of-contents) 21 - [Install](#install) 22 - [Usage](#usage) 23 - [Security and Multiplexing](#security-and-multiplexing) 24 - [reuseport](#reuseport) 25 - [Contribute](#contribute) 26 - [License](#license) 27 28## Install 29 30`go-tcp-transport` is included as a dependency of `go-libp2p`, which is the most 31common libp2p entry point. If you depend on `go-libp2p`, there is generally no 32need to explicitly depend on this module. 33 34`go-tcp-transport` is a standard Go module which can be installed with: 35 36``` sh 37go get github.com/libp2p/go-tcp-transport 38``` 39 40 41This repo is [gomod](https://github.com/golang/go/wiki/Modules)-compatible, and users of 42go 1.11 and later with modules enabled will automatically pull the latest tagged release 43by referencing this package. Upgrades to future releases can be managed using `go get`, 44or 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). 45 46## Usage 47 48TCP is one of the default transports enabled when constructing a standard libp2p 49Host, along with [WebSockets](https://github.com/libp2p/go-ws-transport). 50 51Calling [`libp2p.New`][godoc-libp2p-new] to construct a libp2p Host will enable 52the TCP transport, unless you override the default transports by passing in 53`Options` to `libp2p.New`. 54 55To explicitly enable the TCP transport while constructing a host, use the 56`libp2p.Transport` option, passing in the `NewTCPTransport` constructor function: 57 58``` go 59 60import ( 61 "context" 62 63 libp2p "github.com/libp2p/go-libp2p" 64 tcp "github.com/libp2p/go-tcp-transport" 65) 66 67ctx := context.Background() 68 69// TCP only: 70h, err := libp2p.New(ctx, 71 libp2p.Transport(tcp.NewTCPTransport) 72) 73``` 74 75The example above will replace the default transports with a single TCP 76transport. To add multiple tranports, use `ChainOptions`: 77 78``` go 79// TCP and QUIC: 80h, err := libp2p.New(ctx, 81 libp2p.ChainOptions( 82 libp2p.Transport(tcp.NewTCPTransport), 83 libp2p.Transport(quic.NewTransport)) // see https://github.com/libp2p/go-libp2p-quic-transport 84) 85``` 86 87## Addresses 88 89The TCP transport supports [multiaddrs][multiaddr] that contain a `tcp` 90component, provided that there is sufficient addressing information for the IP 91layer of the connection. 92 93Examples: 94 95| addr | description | 96|----------------------------|----------------------------------------------------| 97| `/ip4/1.2.3.4/tcp/1234` | IPv4: 1.2.3.4, TCP port 1234 | 98| `/ip6/::1/tcp/1234` | IPv6 loopback, TCP port 1234 | 99| `/dns4/example.com/tcp/80` | DNS over IPv4, hostname `example.com`, TCP port 80 | 100 101 102Support for IP layer protocols is provided by the 103[go-multiaddr-net](https://github.com/multiformats/go-multiaddr-net) module. 104 105## Security and Multiplexing 106 107Because TCP lacks native connection security and stream multiplexing facilities, 108the TCP transport uses a [transport upgrader][transport-upgrader] to provide 109those features. The transport upgrader negotiates transport security and 110multiplexing for each connection according to the protocols supported by each 111party. 112 113## reuseport 114 115The [`SO_REUSEPORT`][explain-reuseport] socket option allows multiple processes 116or threads to bind to the same TCP port, provided that all of them set the 117socket option. This has some performance benefits, and it can potentially assist 118in NAT traversal by only requiring one port to be accessible for many 119connections. 120 121The reuseport functionality is provided by a seperate module, 122[go-reuseport-transport](https://github.com/libp2p/go-reuseport-transport). It 123is enabled by default, but can be disabled at runtime by setting the 124`LIBP2P_TCP_REUSEPORT` environment variable to `false` or `0`. 125 126## Contribute 127 128PRs are welcome! 129 130Small note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. 131 132## License 133 134MIT © Jeromy Johnson 135 136--- 137 138The last gx published version of this module was: 2.0.28: QmTGiDkw4eeKq31wwpQRk5GwWiReaxrcTQLuCCLWgfKo5M 139 140<!-- reference links --> 141[go-libp2p]: https://github.com/libp2p/go-libp2p 142[concept-transport]: https://docs.libp2p.io/concepts/transport/ 143[interface-host]: https://github.com/libp2p/go-libp2p-core/blob/master/host/host.go 144[godoc-libp2p-new]: https://godoc.org/github.com/libp2p/go-libp2p#New 145[transport-upgrader]: https://github.com/libp2p/go-libp2p-transport-upgrader 146[explain-reuseport]: https://lwn.net/Articles/542629/ 147[multiaddr]: https://github.com/multiformats/multiaddr 148