Skip to content

Commit b9655fa

Browse files
yusefnaporayusefnapora
committed
readme: add context & fix example code
1 parent 07ed92c commit b9655fa

File tree

1 file changed

+73
-23
lines changed

1 file changed

+73
-23
lines changed

‎README.md

Lines changed: 73 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,42 @@
77
[![Build Status](https://travis-ci.org/libp2p/go-libp2p-transport-upgrader.svg?branch=master)](https://travis-ci.org/libp2p/go-libp2p-transport-upgrader)
88
[![Discourse posts](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg)](https://discuss.libp2p.io)
99

10-
> Stream connection to libp2p connection upgrader
10+
> Add encryption and multiplexing capabilities to libp2p transport connections
1111
12-
This package provides the necessary logic to upgrade [multiaddr-net][manet] connections listeners into full [libp2p-transport][tpt] connections and listeners.
12+
This package is a component of [libp2p](https://libp2p.io), a modular networking
13+
stack for building peer-to-peer applications.
1314

14-
To use, construct a new `Upgrader` with:
15+
For two libp2p peers to communicate, the connection between them must be secure,
16+
and each peer must be able to open multiple independent streams of communication
17+
over a single channel. We call connections with these features "capable"
18+
connections.
1519

16-
* An optional [pnet][pnet] `Protector`.
17-
* An optional [multiaddr-net][manet] address `Filter`.
18-
* A mandatory [stream security transport][ss].
19-
* A mandatory [stream multiplexer transport][smux].
20+
Many of the underlying [transport protocols][docs-transport] that are used by
21+
libp2p do not provide the required capabilities "out of the box."
22+
`go-libp2p-transport-upgrader` provides the necessary logic to upgrade
23+
connections and listeners into fully capable connections and connection
24+
listeners.
2025

21-
[tpt]: https://github.com/libp2p/go-libp2p-transport
22-
[manet]: https://github.com/multiformats/go-multiaddr-net
23-
[ss]: https://github.com/libp2p/go-conn-security
24-
[smux]: https://github.com/libp2p/go-stream-muxer
25-
[pnet]: https://github.com/libp2p/go-libp2p-interface-pnet
26+
In order to be upgraded, the underlying connection or listener must be a
27+
[`multiaddr-net`][manet] [`Conn`][manet-conn] or [`Listener`][manet-listener].
28+
The `multiaddr-net` types integrate the Go standard library connection types
29+
with [`multiaddr`][multiaddr], an extensible addressing format used throughout
30+
libp2p.
2631

27-
Note: This package largely replaces the functionality of [go-libp2p-conn](https://github.com/libp2p/go-libp2p-conn) but with half the code.
32+
As well as the mandatory capabilities of security and multiplexing, the upgrader
33+
can optionally apply a `Protector` for [private networking][pnet], as well as an
34+
[address filter][maddr-filter] to prevent connections to specific addresses.
2835

2936
## Install
3037

31-
`go-libp2p-transport-upgrader` is a standard Go module which can be installed with:
38+
Most people building applications with libp2p will have no need to install
39+
`go-libp2p-transport-upgrader` directly. It is included as a dependency of the
40+
main [`go-libp2p`][go-libp2p] "entry point" module and is integrated into the
41+
libp2p `Host`.
42+
43+
For users who do not depend on `go-libp2p` and are managing their libp2p module
44+
dependencies in a more manual fashion, `go-libp2p-transport-upgrader` is a
45+
standard Go module which can be installed with:
3246

3347
```sh
3448
go get github.com/libp2p/go-libp2p-transport-upgrader
@@ -41,9 +55,26 @@ or by editing your `go.mod` file as [described by the gomod documentation](https
4155

4256
## Usage
4357

58+
To use, construct a new `Upgrader` with:
59+
60+
* An optional [pnet][pnet] `Protector`.
61+
* An optional [go-maddr-filter][maddr-filter] address `Filter`.
62+
* A mandatory [stream security transport][ss].
63+
* A mandatory [stream multiplexer][smux].
64+
65+
In practice, most users will not need to construct an `Upgrader` directly.
66+
Instead, when constructing a libp2p [`Host`][godoc-host], you can pass in some
67+
combination of the [`PrivateNetwork`][godoc-pnet-option],
68+
[`Filters`][godoc-filters-option], [`Security`][godoc-security-option], and
69+
[`Muxer`][godoc-muxer-option] `Option`s. This will configure the `Upgrader` that
70+
is created and used by the `Host` internally.
71+
4472
## Example
4573

46-
Below is a simplified TCP transport implementation using the transport upgrader. In practice, you'll want to use [go-tcp-transport](https://github.com/libp2p/go-tcp-transport) (which has reuseport support).
74+
Below is a simplified TCP transport implementation using the transport upgrader.
75+
In practice, you'll want to use
76+
[go-tcp-transport](https://github.com/libp2p/go-tcp-transport), which is
77+
optimized for production usage.
4778

4879
```go
4980
package tcptransport
@@ -54,9 +85,10 @@ import (
5485
tptu "github.com/libp2p/go-libp2p-transport-upgrader"
5586

5687
ma "github.com/multiformats/go-multiaddr"
57-
mafmt "github.com/whyrusleeping/mafmt"
88+
mafmt "github.com/multiformats/go-multiaddr-fmt"
5889
manet "github.com/multiformats/go-multiaddr-net"
59-
tpt "github.com/libp2p/go-libp2p-transport"
90+
tpt "github.com/libp2p/go-libp2p-core/transport"
91+
peer "github.com/libp2p/go-libp2p-core/peer"
6092
)
6193

6294
// TcpTransport is a simple TCP transport.
@@ -80,9 +112,9 @@ func (t *TcpTransport) CanDial(addr ma.Multiaddr) bool {
80112
}
81113

82114
// Dial dials the peer at the remote address.
83-
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (tpt.Conn, error) {
84-
var dialer manet.Dialer
85-
conn, err := dialer.DialContext(ctx, raddr)
115+
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (tpt.CapableConn, error) {
116+
var dialer manet.Dialer
117+
conn, err := dialer.DialContext(ctx, raddr)
86118
if err != nil {
87119
return nil, err
88120
}
@@ -107,17 +139,18 @@ func (t *TcpTransport) Protocols() []int {
107139
func (t *TcpTransport) Proxy() bool {
108140
return false
109141
}
142+
110143
```
111144

112145
## Contribute
113146

114147
Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/go-libp2p-transport-upgrader/issues)!
115148

116-
This repository falls under the IPFS [Code of Conduct](https://github.com/libp2p/community/blob/master/code-of-conduct.md).
149+
This repository falls under the libp2p [Code of Conduct](https://github.com/libp2p/community/blob/master/code-of-conduct.md).
117150

118-
### Want to hack on IPFS?
151+
### Want to hack on libp2p?
119152

120-
[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)
153+
[![](https://cdn.rawgit.com/libp2p/community/master/img/contribute.gif)](https://github.com/libp2p/community/blob/master/CONTRIBUTE.md)
121154

122155
## License
123156

@@ -126,3 +159,20 @@ MIT
126159
---
127160

128161
The last gx published version of this module was: 0.1.28: QmeqC5shQjEBRG9B8roZqQCJ9xb7Pq6AbWxJFMyLgqBBWh
162+
163+
[tpt]: https://godoc.org/github.com/libp2p/go-libp2p-core/transport
164+
[manet]: https://github.com/multiformats/go-multiaddr-net
165+
[ss]: https://godoc.org/github.com/libp2p/go-libp2p-core/sec
166+
[smux]: https://godoc.org/github.com/libp2p/go-libp2p-core/mux
167+
[pnet]: https://godoc.org/github.com/libp2p/go-libp2p-core/pnet
168+
[manet-conn]: https://godoc.org/github.com/multiformats/go-multiaddr-net#Conn
169+
[manet-listener]: https://godoc.org/github.com/multiformats/go-multiaddr-net#Listener
170+
[maddr-filter]: https://github.com/libp2p/go-maddr-filter
171+
[docs-transport]: https://docs.libp2p.io/concepts/transport
172+
[multiaddr]: https://github.com/multiformats/multiaddr
173+
[go-libp2p]: https://github.com/lib2p2/go-libp2p
174+
[godoc-host]: https://godoc.org/github.com/libp2p/go-libp2p-core/host#Host
175+
[godoc-pnet-option]: https://godoc.org/github.com/libp2p/go-libp2p#PrivateNetwork
176+
[godoc-filters-option]: https://godoc.org/github.com/libp2p/go-libp2p#Filters
177+
[godoc-security-option]: https://godoc.org/github.com/libp2p/go-libp2p#Security
178+
[godoc-muxer-option]: https://godoc.org/github.com/libp2p/go-libp2p#Muxer

0 commit comments

Comments
 (0)