Skip to content
This repository has been archived by the owner on Sep 10, 2022. It is now read-only.

readme: add context & fix example code #26

Merged
merged 1 commit into from
Sep 9, 2019
Merged

readme: add context & fix example code #26

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 73 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,42 @@
[![Build Status](https://travis-ci.org/libp2p/go-libp2p-transport-upgrader.svg?branch=master)](https://travis-ci.org/libp2p/go-libp2p-transport-upgrader)
[![Discourse posts](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg)](https://discuss.libp2p.io)

> Stream connection to libp2p connection upgrader
> Add encryption and multiplexing capabilities to libp2p transport connections

This package provides the necessary logic to upgrade [multiaddr-net][manet] connections listeners into full [libp2p-transport][tpt] connections and listeners.
This package is a component of [libp2p](https://libp2p.io), a modular networking
stack for building peer-to-peer applications.

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

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

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

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

## Install

`go-libp2p-transport-upgrader` is a standard Go module which can be installed with:
Most people building applications with libp2p will have no need to install
`go-libp2p-transport-upgrader` directly. It is included as a dependency of the
main [`go-libp2p`][go-libp2p] "entry point" module and is integrated into the
libp2p `Host`.

For users who do not depend on `go-libp2p` and are managing their libp2p module
dependencies in a more manual fashion, `go-libp2p-transport-upgrader` is a
standard Go module which can be installed with:

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

## Usage

To use, construct a new `Upgrader` with:

* An optional [pnet][pnet] `Protector`.
* An optional [go-maddr-filter][maddr-filter] address `Filter`.
* A mandatory [stream security transport][ss].
* A mandatory [stream multiplexer][smux].

In practice, most users will not need to construct an `Upgrader` directly.
Instead, when constructing a libp2p [`Host`][godoc-host], you can pass in some
combination of the [`PrivateNetwork`][godoc-pnet-option],
[`Filters`][godoc-filters-option], [`Security`][godoc-security-option], and
[`Muxer`][godoc-muxer-option] `Option`s. This will configure the `Upgrader` that
is created and used by the `Host` internally.

## Example

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).
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 is
optimized for production usage.

```go
package tcptransport
Expand All @@ -54,9 +85,10 @@ import (
tptu "github.com/libp2p/go-libp2p-transport-upgrader"

ma "github.com/multiformats/go-multiaddr"
mafmt "github.com/whyrusleeping/mafmt"
mafmt "github.com/multiformats/go-multiaddr-fmt"
manet "github.com/multiformats/go-multiaddr-net"
tpt "github.com/libp2p/go-libp2p-transport"
tpt "github.com/libp2p/go-libp2p-core/transport"
peer "github.com/libp2p/go-libp2p-core/peer"
)

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

// Dial dials the peer at the remote address.
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (tpt.Conn, error) {
var dialer manet.Dialer
conn, err := dialer.DialContext(ctx, raddr)
func (t *TcpTransport) Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (tpt.CapableConn, error) {
var dialer manet.Dialer
conn, err := dialer.DialContext(ctx, raddr)
if err != nil {
return nil, err
}
Expand All @@ -107,17 +139,18 @@ func (t *TcpTransport) Protocols() []int {
func (t *TcpTransport) Proxy() bool {
return false
}

```

## Contribute

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

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

### Want to hack on IPFS?
### Want to hack on libp2p?

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

## License

Expand All @@ -126,3 +159,20 @@ MIT
---

The last gx published version of this module was: 0.1.28: QmeqC5shQjEBRG9B8roZqQCJ9xb7Pq6AbWxJFMyLgqBBWh

[tpt]: https://godoc.org/github.com/libp2p/go-libp2p-core/transport
[manet]: https://github.com/multiformats/go-multiaddr-net
[ss]: https://godoc.org/github.com/libp2p/go-libp2p-core/sec
[smux]: https://godoc.org/github.com/libp2p/go-libp2p-core/mux
[pnet]: https://godoc.org/github.com/libp2p/go-libp2p-core/pnet
[manet-conn]: https://godoc.org/github.com/multiformats/go-multiaddr-net#Conn
[manet-listener]: https://godoc.org/github.com/multiformats/go-multiaddr-net#Listener
[maddr-filter]: https://github.com/libp2p/go-maddr-filter
[docs-transport]: https://docs.libp2p.io/concepts/transport
[multiaddr]: https://github.com/multiformats/multiaddr
[go-libp2p]: https://github.com/lib2p2/go-libp2p
[godoc-host]: https://godoc.org/github.com/libp2p/go-libp2p-core/host#Host
[godoc-pnet-option]: https://godoc.org/github.com/libp2p/go-libp2p#PrivateNetwork
[godoc-filters-option]: https://godoc.org/github.com/libp2p/go-libp2p#Filters
[godoc-security-option]: https://godoc.org/github.com/libp2p/go-libp2p#Security
[godoc-muxer-option]: https://godoc.org/github.com/libp2p/go-libp2p#Muxer