From 7f60b579cda088970f7b50ecdbf4d342d32f6f0b Mon Sep 17 00:00:00 2001 From: Prithvi Shahi Date: Fri, 28 Jul 2023 12:57:53 -0700 Subject: [PATCH] docs: add archive notice to webrtc star and direct (#1488) * chore: add archive notice to webrtc star and direct * remove refs to star and direct * docs: archive removal of webrtc-star and webrtc-direct * wip * wip * docs: update config readme * chore: move examples to libp2p-in-the-browser * chore: update links --------- Co-authored-by: Alex Potsides Co-authored-by: chad --- doc/CONFIGURATION.md | 108 ++++++------------ doc/GETTING_STARTED.md | 1 - doc/production/README.md | 34 ++---- examples/README.md | 10 +- examples/discovery-mechanisms/README.md | 3 +- .../libp2p-in-the-browser/webrtc}/README.md | 0 .../webrtc}/browser-to-browser/README.md | 0 .../webrtc}/browser-to-browser/index.html | 0 .../webrtc}/browser-to-browser/index.js | 0 .../webrtc}/browser-to-browser/package.json | 0 .../webrtc}/browser-to-browser/relay.js | 0 .../browser-to-browser/tests/test.spec.js | 0 .../webrtc}/browser-to-browser/vite.config.js | 0 .../webrtc}/browser-to-server/README.md | 0 .../webrtc}/browser-to-server/index.html | 0 .../webrtc}/browser-to-server/index.js | 0 .../webrtc}/browser-to-server/package.json | 0 .../browser-to-server/tests/test.spec.js | 0 .../webrtc}/browser-to-server/vite.config.js | 0 .../webrtc}/go-libp2p-server/.gitignore | 0 .../webrtc}/go-libp2p-server/go.mod | 0 .../webrtc}/go-libp2p-server/go.sum | 0 .../webrtc}/go-libp2p-server/main.go | 0 .../{ => websockets}/LICENSE | 0 .../{ => websockets}/LICENSE-APACHE | 0 .../{ => websockets}/LICENSE-MIT | 0 .../{ => websockets}/README.md | 10 +- .../{ => websockets}/index.html | 0 .../{ => websockets}/index.js | 5 +- .../{ => websockets}/package.json | 0 .../{ => websockets}/test.js | 0 .../{ => websockets}/vite.config.js | 0 .../fetch-file-from-kubo/.gitignore | 0 .../fetch-file-from-kubo/README.md | 0 .../fetch-file-from-kubo/img/img1.png | Bin .../fetch-file-from-kubo/img/img2.png | Bin .../fetch-file-from-kubo/index.html | 0 .../fetch-file-from-kubo/package.json | 0 .../fetch-file-from-kubo/src/libp2p.ts | 0 .../fetch-file-from-kubo/src/main.ts | 0 .../fetch-file-from-kubo/src/style.css | 0 .../fetch-file-from-kubo/src/vite-env.d.ts | 0 .../fetch-file-from-kubo/tests/test.spec.js | 0 .../fetch-file-from-kubo/tsconfig.json | 0 .../fetch-file-from-kubo/vite.config.js | 0 45 files changed, 55 insertions(+), 116 deletions(-) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/README.md (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/README.md (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/index.html (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/index.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/package.json (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/relay.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/tests/test.spec.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-browser/vite.config.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/README.md (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/index.html (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/index.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/package.json (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/tests/test.spec.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/browser-to-server/vite.config.js (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/go-libp2p-server/.gitignore (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/go-libp2p-server/go.mod (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/go-libp2p-server/go.sum (100%) rename {packages/transport-webrtc/examples => examples/libp2p-in-the-browser/webrtc}/go-libp2p-server/main.go (100%) rename examples/libp2p-in-the-browser/{ => websockets}/LICENSE (100%) rename examples/libp2p-in-the-browser/{ => websockets}/LICENSE-APACHE (100%) rename examples/libp2p-in-the-browser/{ => websockets}/LICENSE-MIT (100%) rename examples/libp2p-in-the-browser/{ => websockets}/README.md (72%) rename examples/libp2p-in-the-browser/{ => websockets}/index.html (100%) rename examples/libp2p-in-the-browser/{ => websockets}/index.js (96%) rename examples/libp2p-in-the-browser/{ => websockets}/package.json (100%) rename examples/libp2p-in-the-browser/{ => websockets}/test.js (100%) rename examples/libp2p-in-the-browser/{ => websockets}/vite.config.js (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/.gitignore (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/README.md (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/img/img1.png (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/img/img2.png (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/index.html (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/package.json (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/src/libp2p.ts (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/src/main.ts (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/src/style.css (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/src/vite-env.d.ts (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/tests/test.spec.js (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/tsconfig.json (100%) rename {packages/transport-webtransport/examples => examples/libp2p-in-the-browser/webtransport}/fetch-file-from-kubo/vite.config.js (100%) diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md index d74222dab7..c49d4ff4ca 100644 --- a/doc/CONFIGURATION.md +++ b/doc/CONFIGURATION.md @@ -15,7 +15,6 @@ - [Examples](#examples) - [Basic setup](#basic-setup) - [Customizing Peer Discovery](#customizing-peer-discovery) - - [Setup webrtc transport and discovery](#setup-webrtc-transport-and-discovery) - [Customizing Pubsub](#customizing-pubsub) - [Customizing DHT](#customizing-dht) - [Setup with Content and Peer Routing](#setup-with-content-and-peer-routing) @@ -70,10 +69,10 @@ Bear in mind that a **transport** and **connection encryption** module are **req Some available transports are: -- [@libp2p/tcp](https://github.com/libp2p/js-libp2p-tcp) (not available in browsers) -- [@libp2p/webrtc](https://github.com/libp2p/js-libp2p-webrtc) -- [@libp2p/websockets](https://github.com/libp2p/js-libp2p-websockets) -- [@libp2p/webtransport](https://github.com/libp2p/js-libp2p-webtransport) (Work in Progress) +- [@libp2p/tcp](https://github.com/libp2p/tree/master/packages/transport-tcp) (not available in browsers) +- [@libp2p/webrtc](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-webrtc) +- [@libp2p/websockets](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-websockets) +- [@libp2p/webtransport](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-webtransport) If none of the available transports fulfils your needs, you can create a libp2p compatible transport. A libp2p transport just needs to be compliant with the [Transport Interface](https://github.com/libp2p/js-interfaces/tree/master/src/transport). @@ -88,7 +87,7 @@ If you want to know more about libp2p transports, you should read the following Some available stream multiplexers are: -- [@libp2p/mplex](https://github.com/libp2p/js-libp2p-mplex) +- [@libp2p/mplex](https://github.com/libp2p/js-libp2p/tree/master/packages/stream-multiplexer-mplex) - [@chainsafe/libp2p-yamux](https://github.com/chainsafe/js-libp2p-yamux) Some transports such as WebRTC and WebTransport come with their own built-in stream multiplexing capabilities. @@ -127,14 +126,11 @@ If you want to know more about libp2p connection encryption, you should read the Some available peer discovery modules are: -- [@libp2p/mdns](https://github.com/libp2p/js-libp2p-mdns) -- [@libp2p/bootstrap](https://github.com/libp2p/js-libp2p-bootstrap) -- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) -- [@libp2p/webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) +- [@libp2p/mdns](https://github.com/libp2p/js-libp2ptree/master/packages/peer-discovery-mdns) +- [@libp2p/bootstrap](https://github.com/libp2p/js-libp2p/tree/master/packages/peer-discovery-bootstrap) +- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p/tree/master/packages/kad-dht) - [@chainsafe/discv5](https://github.com/chainsafe/discv5) -**Note**: `peer-discovery` services within transports (such as `js-libp2p-webrtc-star`) are automatically gathered from the `transport`, via it's `discovery` property. As such, they do not need to be added in the discovery modules. However, these transports can also be configured and disabled as the other ones. - If none of the available peer discovery protocols fulfills your needs, you can create a libp2p compatible one. A libp2p peer discovery protocol just needs to be compliant with the [Peer Discovery Interface](https://github.com/libp2p/js-interfaces/tree/master/src/peer-discovery). If you want to know more about libp2p peer discovery, you should read the following content: @@ -147,7 +143,7 @@ If you want to know more about libp2p peer discovery, you should read the follow Some available content routing modules are: -- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) +- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p/tree/master/packages/kad-dht) - [@libp2p/delegated-content-routing](https://github.com/libp2p/js-libp2p-delegated-content-routing) - [@libp2p/ipni-content-routing](https://github.com/libp2p/js-ipni-content-routing) @@ -163,7 +159,7 @@ If you want to know more about libp2p content routing, you should read the follo Some available peer routing modules are: -- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) +- [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p/tree/master/packages/kad-dht) - [@libp2p/delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing) If none of the available peer routing protocols fulfills your needs, you can create a libp2p compatible one. A libp2p peer routing protocol just needs to be compliant with the [Peer Routing Interface](https://github.com/libp2p/js-interfaces/tree/master/src/peer-routing). **(WIP: This module is not yet implemented)** @@ -176,7 +172,7 @@ If you want to know more about libp2p peer routing, you should read the followin > A DHT can provide content and peer routing capabilities in a p2p system, as well as peer discovery capabilities. -The DHT implementation currently available is [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p-kad-dht). This implementation is largely based on the Kademlia whitepaper, augmented with notions from S/Kademlia, Coral and mainlineDHT. +The DHT implementation currently available is [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p/tree/master/packages/kad-dht). This implementation is largely based on the Kademlia whitepaper, augmented with notions from S/Kademlia, Coral and mainlineDHT. If this DHT implementation does not fulfill your needs and you want to create or use your own implementation, please get in touch with us through a github issue. We plan to work on improving the ability to bring your own DHT in a future release. @@ -301,36 +297,6 @@ const node = await createLibp2p({ }) ``` -#### Setup webrtc transport and discovery - -```js -import { createLibp2p } from 'libp2p' -import { webSockets } from '@libp2p/websockets' -import { webRTCStar } from '@libp2p/webrtc-star' -import { mplex } from '@libp2p/mplex' -import { yamux } from '@chainsafe/libp2p-yamux' -import { noise } from '@chainsafe/libp2p-noise' - -const webRtc = webRTCStar() - -const node = await createLibp2p({ - transports: [ - webSockets(), - webRtc.transport - ], - peerDiscovery: [ - webRtc.discovery - ], - streamMuxers: [ - yamux(), - mplex() - ], - connectionEncryption: [ - noise() - ] -}) -``` - #### Customizing Pubsub Before a peer can subscribe to a topic it must find other peers and establish network connections with them. The pub/sub system doesn’t have any way to discover peers by itself. Instead, it relies upon the application to find new peers on its behalf, a process called ambient peer discovery. @@ -898,30 +864,25 @@ const node = await createLibp2p({ #### Customizing Transports -Some Transports can be passed additional options when they are created. For example, `libp2p-webrtc-star` accepts an optional, custom `wrtc` implementation. In addition to libp2p passing itself and an `Upgrader` to handle connection upgrading, libp2p will also pass the options, if they are provided, from `config.transport`. +Some Transports can be passed additional options when they are created. For example, [webRTC](../packages/transport-webrtc) accepts optional [DataChannel Options](https://github.com/libp2p/js-libp2p/blob/master/packages/transport-webrtc/src/stream.ts#L13-L17). In addition to libp2p passing itself and an `Upgrader` to handle connection upgrading, libp2p will also pass the options, if they are provided, from `config.transport`. ```js import { createLibp2p } from 'libp2p' -import { webRTCStar } from '@libp2p/webrtc-star' -import { mplex } from '@libp2p/mplex' import { yamux } from '@chainsafe/libp2p-yamux' import { noise } from '@chainsafe/libp2p-noise' -import wrtc from 'wrtc' +import { webRTC } from '@libp2p/webrtc' -const webRTC = webRTCStar({ - wrtc -}) const node = await createLibp2p({ transports: [ - webRTC.transport - ], - peerDiscovery: [ - webRTC.discovery + webRTC({ + dataChannel: { + maxMessageSize: 10 + } + }) ], streamMuxers: [ - yamux(), - mplex() + yamux() ], connectionEncryption: [ noise() @@ -929,35 +890,30 @@ const node = await createLibp2p({ }) ``` -During Libp2p startup, transport listeners will be created for the configured listen multiaddrs. Some transports support custom listener options and you can set them using the `listenerOptions` in the transport configuration. For example, [libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) transport listener supports the configuration of its underlying [simple-peer](https://github.com/feross/simple-peer) ice server(STUN/TURN) config as follows: +During Libp2p startup, transport listeners will be created for the configured listen multiaddrs. Some transports support custom listener options and you can set them using the `listenerOptions` in the transport configuration. For example, [webRTC](../packages/transport-webrtc) transport listener supports the configuration of ice servers (STUN/TURN) config as follows: ```js -const webRTC = webRTCStar({ - listenerOptions: { - config: { - iceServers: [ - {"urls": ["turn:YOUR.TURN.SERVER:3478"], "username": "YOUR.USER", "credential": "YOUR.PASSWORD"}, - {"urls": ["stun:YOUR.STUN.SERVER:3478"], "username": "", "credential": ""}] - } - } -}) - const node = await createLibp2p({ transports: [ - webRTC.transport - ], - peerDiscovery: [ - webRTC.discovery + webRTC({ + rtcConfiguration: { + iceServers:[{ + urls: [ + 'stun:stun.l.google.com:19302', + 'stun:global.stun.twilio.com:3478' + ] + }] + } +}) ], streamMuxers: [ - yamux(), - mplex() + yamux() ], connectionEncryption: [ noise() ], addresses: { - listen: ['/dns4/your-wrtc-star.pub/tcp/443/wss/p2p-webrtc-star'] // your webrtc dns multiaddr + listen: ['/webrtc'] // your webrtc dns multiaddr } }) ``` diff --git a/doc/GETTING_STARTED.md b/doc/GETTING_STARTED.md index ce72872059..50b37076c6 100644 --- a/doc/GETTING_STARTED.md +++ b/doc/GETTING_STARTED.md @@ -197,7 +197,6 @@ For each discovered peer libp2p will emit a `peer:discovery` event which include Looking at the [available peer discovery](./CONFIGURATION.md#peer-discovery) protocols, there are several options to be considered: - If you already know the addresses of some other network peers, you should consider using `@libp2p/bootstrap` as this is the easiest way of getting your peer into the network. - If it is likely that you will have other peers on your local network, `@libp2p/mdns` is a must if you're node is not running in the browser. It allows peers to discover each other when on the same local network. -- If your application is browser based you can use the `@libp2p/webrtc-star` Transport, which includes a rendezvous based peer sharing service. - A random walk approach can be used via `@libp2p/kad-dht`, to crawl the network and find new peers along the way. For this guide we will configure `@libp2p/bootstrap` as this is useful for joining the public network. diff --git a/doc/production/README.md b/doc/production/README.md index e655d0b6ff..78c46fadfc 100644 --- a/doc/production/README.md +++ b/doc/production/README.md @@ -8,13 +8,13 @@ This guide aims to guide you from using the public infrastructure into setting u ## Table of Contents -* [Joining the Network](#joining-the-network) -* [Connecting to Nodes with connectivity limitations](#connecting-to-nodes-with-connectivity-limitations) - * [`webrtc-star` servers](#webrtc-star-servers) - * [Circuit Relay](#circuit-relay) -* [Querying the network from the browser](#querying-the-network-from-the-browser) -* [Others](#others) - * [SSL](#ssl) +- [Production](#production) + - [Table of Contents](#table-of-contents) + - [Joining the Network](#joining-the-network) + - [Connecting to Nodes with connectivity limitations](#connecting-to-nodes-with-connectivity-limitations) + - [Querying the network from the browser](#querying-the-network-from-the-browser) + - [Others](#others) + - [SSL](#ssl) ## Joining the Network @@ -22,32 +22,22 @@ Once a libp2p node stars, it will need to connect to a set of peers in order to Currently `js-libp2p` is not the best choice for being a bootstrap node. Its DHT needs to be improved, in order to become an effective server to enable other nodes to properly bootstrap their network. -Setting up a fleet of [`go-libp2p`](https://github.com/libp2p/go-libp2p) nodes is the recommended way to proceed here. +Setting up a fleet of [`go-libp2p`](https://github.com/libp2p/go-libp2p) nodes is the recommended way to proceed here. ## Connecting to Nodes with connectivity limitations While the libp2p core codebase aims to work in multiple environments, there are some limitations that are not possible to overcome at the time of writing. These limitations include browser nodes, nodes behind NAT, reverse proxies, firewalls, or lack of compatible transports. -In the browser, libp2p supports two transports: `websockets` and `webrtc-star`. Nowadays, browsers do not support listening for connections, but only to dial known addresses. `webrtc-star` servers can be used to enable libp2p nodes to discover other nodes running on the browser and to help them establish a connection. +In the browser, libp2p supports three transports: `WebSockets`, `WebRTC`, and `WebTransport`. -For nodes that cannot be dialed (including browser), circuit relay nodes should be used. - -### `webrtc-star` servers - -Regarding `webRTC` connections, a set of star servers are needed to act as a rendezvous point, where peers can learn about other peers (`peer-discovery`), as well as exchange their SDP offers (signaling data). - -You can read on how to setup your own star servers in [libp2p/js-libp2p-webrtc-star/DEPLOYMENT.md](https://github.com/libp2p/js-libp2p-webrtc-star/blob/master/DEPLOYMENT.md). - -It is worth pointing out that with new discovery protocols on the way, as well as support for distributed signaling, the star servers should be deprecated on the long run. - -### Circuit Relay +- [WebSockets](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-websockets) is generally used as a full-duplex communication protocol over a single TCP connection, allowing for real-time data transfer between the client and the server. +- [WebRTC](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-webrtc) is primarly geared towards facilitating browser-to-browser connections. It also enables browsers to connect to public server nodes without those server nodes providing a TLS certificate within the browser's trustchain. This differs from the `WebSockets` transport as the browser requires the remote to have a trusted TLS certificate. Please note that webRTC iss currently not supported by [go-libp2p](https://github.com/libp2p/go-libp2p/issues/2009) but this is in development. +- [WebTransport](https://github.com/libp2p/js-libp2p/tree/master/packages/transport-webtransport) is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers, that uses QUIC to offer an alternative to WebSocket. It exhibits all the advantages of QUIC over TCP, including faster handshakes, no head-of-line blocking, and being future-proof. Browsers cannot listen for WebTransport connections since it is similar to TCP in that it requires opening sockets on the host machine which is forbidden by the browser security model. Libp2p nodes acting as circuit relay aim to establish connectivity between libp2p nodes (e.g. IPFS nodes) that wouldn't otherwise be able to establish a direct connection to each other. A relay is needed in situations where nodes are behind NAT, reverse proxies, firewalls and/or simply don't support the same transports (e.g. go-libp2p vs. browser-libp2p). The circuit relay protocol exists to overcome those scenarios. Nodes with the `auto-relay` feature enabled can automatically bind themselves on a relay to listen for connections on their behalf. -You can use [libp2p/js-libp2p-relay-server](https://github.com/libp2p/js-libp2p-relay-server) to setup your own relay server. This also includes an easy to customize Docker setup for a HOP Relay. - ## Querying the network from the browser Libp2p nodes in scenarios such as browser environment and constrained devices will not be an efficient node in the libp2p DHT overlay, as a consequence of their known limitations regarding connectivity and performance. diff --git a/examples/README.md b/examples/README.md index fecff8f761..62762e59b4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -18,9 +18,15 @@ Let us know if you find any issues, or if you want to contribute and add a new t ## Other examples -- [Running libp2p in the Browser](./libp2p-in-the-browser) - Running libp2p in the Electron (future) - [The standard echo net example with libp2p](./echo) - [A simple chat app with libp2p](./chat) -For go-libp2p examples, check out https://github.com/libp2p/go-libp2p-examples#examples-and-tutorials +## libp2p in the Browser +There are a number of ways libp2p can be used in the browser. Here are some examples: + +- [webRTC](./libp2p-in-the-browser/webrtc/README.md) +- [websockets](./libp2p-in-the-browser/websockets/README.md) +- [webtransport](./libp2p-in-the-browser/webtransport/README.md) + +There is also an tutorial of how all of these transports can be [universally connected](https://github.com/libp2p/universal-connectivity/tree/main) \ No newline at end of file diff --git a/examples/discovery-mechanisms/README.md b/examples/discovery-mechanisms/README.md index 59af433297..9402e1540f 100644 --- a/examples/discovery-mechanisms/README.md +++ b/examples/discovery-mechanisms/README.md @@ -300,8 +300,7 @@ This is really useful when running libp2p in constrained environments like a bro There are plenty more Peer Discovery Mechanisms out there, you can: -- Find one in [@libp2p/webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star). Yes, a transport with discovery capabilities! This happens because WebRTC requires a rendezvous point for peers to exchange [SDP](https://tools.ietf.org/html/rfc4317) offer, which means we have one or more points that can introduce peers to each other. Think of it as MulticastDNS for the Web, as in MulticastDNS only works in LAN. -- Any DHT will offer you a discovery capability. You can simple *random-walk* the routing tables to find other peers to connect to. For example [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) can be used for peer discovery. An example of how to configure it to enable random walks can be found [here](https://github.com/libp2p/js-libp2p/blob/v0.28.4/doc/CONFIGURATION.md#customizing-dht). +- Any DHT will offer you a discovery capability. You can simple _random-walk_ the routing tables to find other peers to connect to. For example [@libp2p/kad-dht](https://github.com/libp2p/js-libp2p/tree/master/packages/kad-dht) can be used for peer discovery. An example of how to configure it to enable random walks can be found [here](https://github.com/libp2p/js-libp2p/blob/v0.28.4/doc/CONFIGURATION.md#customizing-dht). - You can create your own Discovery service, a registry, a list, a radio beacon, you name it! ## License diff --git a/packages/transport-webrtc/examples/README.md b/examples/libp2p-in-the-browser/webrtc/README.md similarity index 100% rename from packages/transport-webrtc/examples/README.md rename to examples/libp2p-in-the-browser/webrtc/README.md diff --git a/packages/transport-webrtc/examples/browser-to-browser/README.md b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/README.md similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/README.md rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/README.md diff --git a/packages/transport-webrtc/examples/browser-to-browser/index.html b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/index.html similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/index.html rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/index.html diff --git a/packages/transport-webrtc/examples/browser-to-browser/index.js b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/index.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/index.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/index.js diff --git a/packages/transport-webrtc/examples/browser-to-browser/package.json b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/package.json similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/package.json rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/package.json diff --git a/packages/transport-webrtc/examples/browser-to-browser/relay.js b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/relay.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/relay.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/relay.js diff --git a/packages/transport-webrtc/examples/browser-to-browser/tests/test.spec.js b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/tests/test.spec.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/tests/test.spec.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/tests/test.spec.js diff --git a/packages/transport-webrtc/examples/browser-to-browser/vite.config.js b/examples/libp2p-in-the-browser/webrtc/browser-to-browser/vite.config.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-browser/vite.config.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-browser/vite.config.js diff --git a/packages/transport-webrtc/examples/browser-to-server/README.md b/examples/libp2p-in-the-browser/webrtc/browser-to-server/README.md similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/README.md rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/README.md diff --git a/packages/transport-webrtc/examples/browser-to-server/index.html b/examples/libp2p-in-the-browser/webrtc/browser-to-server/index.html similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/index.html rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/index.html diff --git a/packages/transport-webrtc/examples/browser-to-server/index.js b/examples/libp2p-in-the-browser/webrtc/browser-to-server/index.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/index.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/index.js diff --git a/packages/transport-webrtc/examples/browser-to-server/package.json b/examples/libp2p-in-the-browser/webrtc/browser-to-server/package.json similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/package.json rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/package.json diff --git a/packages/transport-webrtc/examples/browser-to-server/tests/test.spec.js b/examples/libp2p-in-the-browser/webrtc/browser-to-server/tests/test.spec.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/tests/test.spec.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/tests/test.spec.js diff --git a/packages/transport-webrtc/examples/browser-to-server/vite.config.js b/examples/libp2p-in-the-browser/webrtc/browser-to-server/vite.config.js similarity index 100% rename from packages/transport-webrtc/examples/browser-to-server/vite.config.js rename to examples/libp2p-in-the-browser/webrtc/browser-to-server/vite.config.js diff --git a/packages/transport-webrtc/examples/go-libp2p-server/.gitignore b/examples/libp2p-in-the-browser/webrtc/go-libp2p-server/.gitignore similarity index 100% rename from packages/transport-webrtc/examples/go-libp2p-server/.gitignore rename to examples/libp2p-in-the-browser/webrtc/go-libp2p-server/.gitignore diff --git a/packages/transport-webrtc/examples/go-libp2p-server/go.mod b/examples/libp2p-in-the-browser/webrtc/go-libp2p-server/go.mod similarity index 100% rename from packages/transport-webrtc/examples/go-libp2p-server/go.mod rename to examples/libp2p-in-the-browser/webrtc/go-libp2p-server/go.mod diff --git a/packages/transport-webrtc/examples/go-libp2p-server/go.sum b/examples/libp2p-in-the-browser/webrtc/go-libp2p-server/go.sum similarity index 100% rename from packages/transport-webrtc/examples/go-libp2p-server/go.sum rename to examples/libp2p-in-the-browser/webrtc/go-libp2p-server/go.sum diff --git a/packages/transport-webrtc/examples/go-libp2p-server/main.go b/examples/libp2p-in-the-browser/webrtc/go-libp2p-server/main.go similarity index 100% rename from packages/transport-webrtc/examples/go-libp2p-server/main.go rename to examples/libp2p-in-the-browser/webrtc/go-libp2p-server/main.go diff --git a/examples/libp2p-in-the-browser/LICENSE b/examples/libp2p-in-the-browser/websockets/LICENSE similarity index 100% rename from examples/libp2p-in-the-browser/LICENSE rename to examples/libp2p-in-the-browser/websockets/LICENSE diff --git a/examples/libp2p-in-the-browser/LICENSE-APACHE b/examples/libp2p-in-the-browser/websockets/LICENSE-APACHE similarity index 100% rename from examples/libp2p-in-the-browser/LICENSE-APACHE rename to examples/libp2p-in-the-browser/websockets/LICENSE-APACHE diff --git a/examples/libp2p-in-the-browser/LICENSE-MIT b/examples/libp2p-in-the-browser/websockets/LICENSE-MIT similarity index 100% rename from examples/libp2p-in-the-browser/LICENSE-MIT rename to examples/libp2p-in-the-browser/websockets/LICENSE-MIT diff --git a/examples/libp2p-in-the-browser/README.md b/examples/libp2p-in-the-browser/websockets/README.md similarity index 72% rename from examples/libp2p-in-the-browser/README.md rename to examples/libp2p-in-the-browser/websockets/README.md index 3d58dd6956..427409863c 100644 --- a/examples/libp2p-in-the-browser/README.md +++ b/examples/libp2p-in-the-browser/websockets/README.md @@ -11,7 +11,6 @@ - [Setup](#setup) - [Running the examples](#running-the-examples) -- [Going to production?](#going-to-production) - [License](#license) - [Contribution](#contribution) @@ -49,17 +48,10 @@ Server running at http://localhost:1234 This will compile the code and start a server listening on port . Now open your browser to `http://localhost:1234`. You should see a log of your node's Peer ID, the discovered peers from the Bootstrap module, and connections to those peers as they are created. -Now, if you open a second browser tab to `http://localhost:1234`, you should discover your node from the previous tab. This is due to the fact that the `libp2p-webrtc-star` transport also acts as a Peer Discovery interface. Your node will be notified of any peer that connects to the same signaling server you are connected to. Once libp2p discovers this new peer, it will attempt to establish a direct WebRTC connection. +Now, if you open a second browser tab to `http://localhost:1234`, you should discover your node from the previous tab. **Note**: In the example we assign libp2p to `window.libp2p`, in case you would like to play around with the API directly in the browser. You can of course make changes to `index.js` and vite will automatically rebuild and reload the browser tabs. -## Going to production? - -This example uses public `libp2p-webrtc-star` servers. These servers should be used for experimenting and demos, they **MUST** not be used in production as there is no guarantee on availability. - -You can see how to deploy your own signaling server in [libp2p/js-libp2p-webrtc-star/DEPLOYMENT.md](https://github.com/libp2p/js-libp2p-webrtc-star/blob/master/packages/webrtc-star-signalling-server/DEPLOYMENT.md). - -Once you have your own server running, you should add its listen address in your libp2p node configuration. ## License diff --git a/examples/libp2p-in-the-browser/index.html b/examples/libp2p-in-the-browser/websockets/index.html similarity index 100% rename from examples/libp2p-in-the-browser/index.html rename to examples/libp2p-in-the-browser/websockets/index.html diff --git a/examples/libp2p-in-the-browser/index.js b/examples/libp2p-in-the-browser/websockets/index.js similarity index 96% rename from examples/libp2p-in-the-browser/index.js rename to examples/libp2p-in-the-browser/websockets/index.js index 0662d405ec..28ea0a93bd 100644 --- a/examples/libp2p-in-the-browser/index.js +++ b/examples/libp2p-in-the-browser/websockets/index.js @@ -1,10 +1,7 @@ -/* eslint-disable no-console */ - import { noise } from '@chainsafe/libp2p-noise' import { yamux } from '@chainsafe/libp2p-yamux' import { bootstrap } from '@libp2p/bootstrap' import { kadDHT } from '@libp2p/kad-dht' -import { mplex } from '@libp2p/mplex' import { webRTCDirect, webRTC } from '@libp2p/webrtc' import { webSockets } from '@libp2p/websockets' import { webTransport } from '@libp2p/webtransport' @@ -28,7 +25,7 @@ document.addEventListener('DOMContentLoaded', async () => { }) ], connectionEncryption: [noise()], - streamMuxers: [yamux(), mplex()], + streamMuxers: [yamux()], peerDiscovery: [ bootstrap({ list: [ diff --git a/examples/libp2p-in-the-browser/package.json b/examples/libp2p-in-the-browser/websockets/package.json similarity index 100% rename from examples/libp2p-in-the-browser/package.json rename to examples/libp2p-in-the-browser/websockets/package.json diff --git a/examples/libp2p-in-the-browser/test.js b/examples/libp2p-in-the-browser/websockets/test.js similarity index 100% rename from examples/libp2p-in-the-browser/test.js rename to examples/libp2p-in-the-browser/websockets/test.js diff --git a/examples/libp2p-in-the-browser/vite.config.js b/examples/libp2p-in-the-browser/websockets/vite.config.js similarity index 100% rename from examples/libp2p-in-the-browser/vite.config.js rename to examples/libp2p-in-the-browser/websockets/vite.config.js diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/.gitignore b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/.gitignore similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/.gitignore rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/.gitignore diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/README.md b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/README.md similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/README.md rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/README.md diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/img/img1.png b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/img/img1.png similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/img/img1.png rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/img/img1.png diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/img/img2.png b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/img/img2.png similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/img/img2.png rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/img/img2.png diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/index.html b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/index.html similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/index.html rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/index.html diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/package.json b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/package.json similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/package.json rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/package.json diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/src/libp2p.ts b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/libp2p.ts similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/src/libp2p.ts rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/libp2p.ts diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/src/main.ts b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/main.ts similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/src/main.ts rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/main.ts diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/src/style.css b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/style.css similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/src/style.css rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/style.css diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/src/vite-env.d.ts b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/vite-env.d.ts similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/src/vite-env.d.ts rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/src/vite-env.d.ts diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/tests/test.spec.js b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/tests/test.spec.js similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/tests/test.spec.js rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/tests/test.spec.js diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/tsconfig.json b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/tsconfig.json similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/tsconfig.json rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/tsconfig.json diff --git a/packages/transport-webtransport/examples/fetch-file-from-kubo/vite.config.js b/examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/vite.config.js similarity index 100% rename from packages/transport-webtransport/examples/fetch-file-from-kubo/vite.config.js rename to examples/libp2p-in-the-browser/webtransport/fetch-file-from-kubo/vite.config.js