From a33458f7253d19b5eb6c253bfe8edc231ee3a522 Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Wed, 10 Jul 2019 09:03:25 -0400 Subject: [PATCH 1/2] readme: add install, usage & addressing info --- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e9c52a0..3847cd8 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,33 @@ [![Coverage Status](https://coveralls.io/repos/github/libp2p/go-ws-transport/badge.svg?branch=master)](https://coveralls.io/github/libp2p/go-ws-transport?branch=master) [![Build Status](https://travis-ci.org/libp2p/go-ws-transport.svg?branch=master)](https://travis-ci.org/libp2p/go-ws-transport) -> go-libp2p websocket transport +> A libp2p transport implementation using WebSockets + +`go-ws-transport` is an implementation of the [libp2p transport +interface][concept-transport] that streams data over +[WebSockets][spec-websockets], which are themselves layered over TCP/IP. It is +included by default in the main [`go-libp2p`][go-libp2p] "entry point" module. + +## Table of Contents + +- [go-ws-transport](#go-ws-transport) + - [Table of Contents](#table-of-contents) + - [Install](#install) + - [Usage](#usage) + - [Addresses](#addresses) + - [Security and Multiplexing](#security-and-multiplexing) + - [Contribute](#contribute) + - [Want to hack on IPFS?](#want-to-hack-on-ipfs) + - [License](#license) ## Install +`go-ws-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-ws-transport` is a standard Go module which can be installed with: + ```sh > go get github.com/libp2p/go-ws-transport ``` @@ -23,6 +46,75 @@ or by editing your `go.mod` file as [described by the gomod documentation](https ## Usage +WebSockets are one of the default transports enabled when constructing a standard libp2p +Host, along with [TCP](https://github.com/libp2p/go-tcp-transport). + +Calling [`libp2p.New`][godoc-libp2p-new] to construct a libp2p Host will enable +the WebSocket transport, unless you override the default transports by passing in +`Options` to `libp2p.New`. + +To explicitly enable the WebSocket transport while constructing a host, use the +`libp2p.Transport` option, passing in the `ws.New` constructor function: + +``` go + +import ( + "context" + + libp2p "github.com/libp2p/go-libp2p" + ws "github.com/libp2p/go-ws-transport" +) + +ctx := context.Background() + +// WebSockets only: +h, err := libp2p.New(ctx, + libp2p.Transport(ws.New) +) +``` + +The example above will replace the default transports with a single WebSocket +transport. To add multiple tranports, use `ChainOptions`: + +``` go +// WebSockets and QUIC: +h, err := libp2p.New(ctx, + libp2p.ChainOptions( + libp2p.Transport(ws.New), + libp2p.Transport(quic.NewTransport)) // see https://github.com/libp2p/go-libp2p-quic-transport +) +``` + +## Addresses + +The WebSocket transport supports [multiaddrs][multiaddr] that contain a `ws` +component, which is encapsulated within (or layered onto) another valid TCP +multiaddr. + +Examples: + +| addr | description | +|-------------------------------|----------------------------------------------------| +| `/ip4/1.2.3.4/tcp/1234/ws` | IPv4: 1.2.3.4, TCP port 1234 | +| `/ip6/::1/tcp/1234/ws` | IPv6 loopback, TCP port 1234 | +| `/dns4/example.com/tcp/80/ws` | DNS over IPv4, hostname `example.com`, TCP port 80 | + +Notice that the `/ws` multiaddr component contextualizes an existing TCP/IP +multiaddr and does not require any additional addressing information. + +## Security and Multiplexing + +While the WebSocket spec defines a `wss` URI scheme for encrypted WebSocket +connections, support for `wss` URIs relies on TLS, which wraps the WebSocket +connection in a similar manner to TLS-protected HTTP traffic. + +As libp2p does not integrate with the TLS Certificate Authority infrastructure +by design, security for WebSockets is provided by a [transport +upgrader][transport-upgrader]. The transport upgrader negotiates transport +security for each connection according to the protocols supported by each party. + +The transport upgrader also negotiates a stream multiplexing protocol to allow +many bidirectional streams to coexist on a single WebSocket connection. ## Contribute @@ -41,3 +133,12 @@ MIT --- The last gx published version of this module was: 2.0.27: QmaSWc4ox6SZQF6DHZvDuM9sP1syNajkKuPXmKR1t5BAz5 + + +[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 +[multiaddr]: https://github.com/multiformats/multiaddr +[spec-websockets]: https://tools.ietf.org/html/rfc6455 From 5c97d94c437a9da4e9d05346bef1cecfbe039f0f Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Wed, 10 Jul 2019 12:38:50 -0400 Subject: [PATCH 2/2] readme: replace IPFS contrib links with libp2p --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3847cd8..541a6ce 100644 --- a/README.md +++ b/README.md @@ -120,11 +120,11 @@ many bidirectional streams to coexist on a single WebSocket connection. Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/go-ws-transport/issues)! -This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/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