From c515e53b9133d16a4012c4459c8c2331c8c5295f Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Tue, 9 Jul 2019 12:58:03 -0400 Subject: [PATCH 1/3] readme: add install, usage & addressing info --- README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 114 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ce8ad96..dcee253 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,119 @@ 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 -- [Install](#install) -- [Usage](#usage) -- [API](#api) -- [Contribute](#contribute) -- [License](#license) +- [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 -```sh -make 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](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! @@ -38,3 +136,12 @@ MIT © Jeromy Johnson --- The last gx published version of this module was: 2.0.28: QmTGiDkw4eeKq31wwpQRk5GwWiReaxrcTQLuCCLWgfKo5M + + +[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 From edb8780a5d66d02fb2740995c9c7bea20303f256 Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Tue, 9 Jul 2019 13:02:37 -0400 Subject: [PATCH 2/3] fix link --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dcee253..af4d975 100644 --- a/README.md +++ b/README.md @@ -119,8 +119,8 @@ 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](github.com/libp2p/go-reuseport-transport). It is -enabled by default, but can be disabled at runtime by setting the +[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 From 45f9c901d69bd640c4b393f9f663d3d36cca415a Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Tue, 9 Jul 2019 13:09:06 -0400 Subject: [PATCH 3/3] fix whitespace --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index af4d975..75f5218 100644 --- a/README.md +++ b/README.md @@ -58,9 +58,9 @@ To explicitly enable the TCP transport while constructing a host, use the ``` go import ( - "context" + "context" - libp2p "github.com/libp2p/go-libp2p" + libp2p "github.com/libp2p/go-libp2p" tcp "github.com/libp2p/go-tcp-transport" ) @@ -78,9 +78,9 @@ 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 + libp2p.ChainOptions( + libp2p.Transport(tcp.NewTCPTransport), + libp2p.Transport(quic.NewTransport)) // see https://github.com/libp2p/go-libp2p-quic-transport ) ```