README.md
1go-tcp-transport
2==================
3
4[](https://protocol.ai)
5[](https://libp2p.io/)
6[](http://webchat.freenode.net/?channels=%23libp2p)
7[](https://discuss.libp2p.io)
8[](https://coveralls.io/github/libp2p/go-tcp-transport?branch=master)
9[](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
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}