From 50ab2c2d10bd365514ff41ccf52dbf09362c7d8d Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Mon, 26 Aug 2019 07:45:04 +0530 Subject: [PATCH 01/19] Add document for running JS IPFS in the browser --- doc/using-js-ipfs-in-the-browser.md | 70 +++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 doc/using-js-ipfs-in-the-browser.md diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md new file mode 100644 index 0000000000..dc3c8ff920 --- /dev/null +++ b/doc/using-js-ipfs-in-the-browser.md @@ -0,0 +1,70 @@ +Using JS IPFS in The Browser +---------------------------- + +The document describes how you can use JS IPFS in the browser. JS IPFS is the +implementation of the IPFS protocal for browser. JS IPFS runs in a browser as a +service worked, a web extenstion and node.js. The document describes how you can +boost the speed and reduce the errors you face often because of limitation of +js-ipfs. + +There are few different components for implementing JS IPFS in the browser. These +are webrtc and websocket-star which will make it easier for implemented JS IPFS +in the browser and boost the speed and reduce the errors. + +You can find the information present for enabling webRTC support for js-ipfs in +the browser [here](https://github.com/ipfs/js-ipfs#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) and a different one is +implementing with webrtc-star, you can find information [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). + +You can find information about running IPFS in the broswer [here](https://github.com/ipfs/js-ipfs#table-of-contents). + +Getting Data From IPFS +----------------------- + +Using Javascript in the browser + +```js +const node = new IPFS() + +node.once('ready', () => { + node.pipe('QmPChd2hVbrJ6bfo3WBcTW4iZnpHm8TEzWkLHmLpXhF68A', (err, data) => { + if (err) return console.error(err) + + // convert Buffer back to string + console.log(data.toString()) + }) +}) +``` + +JS IPFS Restriction in Web Browser +------------------------------------------ + +- There is no DHT in js-ipfs. + + In browser a JS IPFS node is more restricted because of the same origin policy + that decrease the discover/connect with peers, external peers without rendezvous + and relay servers, delegating peer/content routing and preload servers for content + discoverablilty hard and erroneous even with swarm peers. + +- Unable in opening TCP connections even if one sets up delegating routing the +issue will persist for connecting most of peers in the swarm as described a +little above. + +- Connection with websocket ports should be adhering with [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) limitations. + +JS IPFS Best Practices +---------------------- + +- Run in fedrated model. +- Configure nodes for using webrtc or websocket-star. +- Run independant instance as default one are under high load and YMMV. +- Make sure content you are implementing is cached in go-ipfs + - manually `pin` or preload CIDs of interest with `refs -r` beforehand. + - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or + configuring [delgated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). + Here you will be using go-ipfs's API + nginx. + +JS IPFS Examples +---------------- + +We have documented a lot of examples for implemented JS IPFS in the browser, you +can find them [here](https://github.com/ipfs/js-ipfs-http-client/tree/master/examples). From 60756b728e3cc3335543e914b30cb100fff3c8d7 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 00:32:10 +0530 Subject: [PATCH 02/19] dht information line fixes --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index dc3c8ff920..1be3163de1 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -38,7 +38,7 @@ node.once('ready', () => { JS IPFS Restriction in Web Browser ------------------------------------------ -- There is no DHT in js-ipfs. +- DHT in js-ipfs is not by default. In browser a JS IPFS node is more restricted because of the same origin policy that decrease the discover/connect with peers, external peers without rendezvous From f4abde31af3ac340ad060af08872b6b491932425 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 00:33:39 +0530 Subject: [PATCH 03/19] remove whitespaces --- doc/using-js-ipfs-in-the-browser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 1be3163de1..f23e2e29a1 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -45,7 +45,7 @@ JS IPFS Restriction in Web Browser and relay servers, delegating peer/content routing and preload servers for content discoverablilty hard and erroneous even with swarm peers. -- Unable in opening TCP connections even if one sets up delegating routing the +- Unable in opening TCP connections even if one sets up delegating routing the issue will persist for connecting most of peers in the swarm as described a little above. @@ -59,7 +59,7 @@ JS IPFS Best Practices - Run independant instance as default one are under high load and YMMV. - Make sure content you are implementing is cached in go-ipfs - manually `pin` or preload CIDs of interest with `refs -r` beforehand. - - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or + - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or configuring [delgated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). Here you will be using go-ipfs's API + nginx. From 7ae4d9699b8534b7d00cc373a91873cbadd4dfd5 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 00:39:13 +0530 Subject: [PATCH 04/19] js-ipfs introductory line fixes --- doc/using-js-ipfs-in-the-browser.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index f23e2e29a1..e2d0d88370 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -1,10 +1,11 @@ Using JS IPFS in The Browser ---------------------------- -The document describes how you can use JS IPFS in the browser. JS IPFS is the -implementation of the IPFS protocal for browser. JS IPFS runs in a browser as a -service worked, a web extenstion and node.js. The document describes how you can -boost the speed and reduce the errors you face often because of limitation of +JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any +evergreen browser, inside a service or web worker, as a web extention and in Node.js. + +The documentation details more information about running JS IPFS in the browser and +boosting the speed with reducing the errors you face often because of limitation of js-ipfs. There are few different components for implementing JS IPFS in the browser. These From 42b41fdca200c31854c482c2f7fe3e1c94bc1759 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 00:41:28 +0530 Subject: [PATCH 05/19] i don't remember now --- doc/using-js-ipfs-in-the-browser.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index e2d0d88370..5f95bbc4ba 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -55,7 +55,6 @@ little above. JS IPFS Best Practices ---------------------- -- Run in fedrated model. - Configure nodes for using webrtc or websocket-star. - Run independant instance as default one are under high load and YMMV. - Make sure content you are implementing is cached in go-ipfs From 579f01d42a0a2bf9a22ca7cd9b95db9cc55b979b Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 01:10:56 +0530 Subject: [PATCH 06/19] separate tcp and delegated routing? --- doc/using-js-ipfs-in-the-browser.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 5f95bbc4ba..e2ce758302 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -46,9 +46,8 @@ JS IPFS Restriction in Web Browser and relay servers, delegating peer/content routing and preload servers for content discoverablilty hard and erroneous even with swarm peers. -- Unable in opening TCP connections even if one sets up delegating routing the -issue will persist for connecting most of peers in the swarm as described a -little above. +- If the browser lacks TCP, you can set up delegating routing. The issue might still + persist for connecting most of peers in the swarm as described above. - Connection with websocket ports should be adhering with [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) limitations. From ba212053cf81e89c8001e530871cee44ce3a5855 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 05:27:49 +0530 Subject: [PATCH 07/19] Update doc/using-js-ipfs-in-the-browser.md Co-Authored-By: David Dias --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index e2ce758302..bb1f4a0350 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -39,7 +39,7 @@ node.once('ready', () => { JS IPFS Restriction in Web Browser ------------------------------------------ -- DHT in js-ipfs is not by default. +- DHT in js-ipfs is not enabled by default. In browser a JS IPFS node is more restricted because of the same origin policy that decrease the discover/connect with peers, external peers without rendezvous From 7dc45244bc46aaad1c76a2212446392558193496 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 05:28:01 +0530 Subject: [PATCH 08/19] Update doc/using-js-ipfs-in-the-browser.md Co-Authored-By: David Dias --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index bb1f4a0350..4f08338452 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -59,7 +59,7 @@ JS IPFS Best Practices - Make sure content you are implementing is cached in go-ipfs - manually `pin` or preload CIDs of interest with `refs -r` beforehand. - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or - configuring [delgated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). + configuring [delegated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). Here you will be using go-ipfs's API + nginx. JS IPFS Examples From 3bbed60b9b12c6652450c572de7502bb84c8aa27 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 18:51:51 +0530 Subject: [PATCH 09/19] Update doc/using-js-ipfs-in-the-browser.md Co-Authored-By: Marcin Rataj --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 4f08338452..42090bf696 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -2,7 +2,7 @@ Using JS IPFS in The Browser ---------------------------- JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any -evergreen browser, inside a service or web worker, as a web extention and in Node.js. +evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js. The documentation details more information about running JS IPFS in the browser and boosting the speed with reducing the errors you face often because of limitation of From 4e9b016f7e9e0f3b13724777730c5ab1eb591c8c Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 18:53:49 +0530 Subject: [PATCH 10/19] line item fixes --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index e2ce758302..91236e5ce6 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -8,7 +8,7 @@ The documentation details more information about running JS IPFS in the browser boosting the speed with reducing the errors you face often because of limitation of js-ipfs. -There are few different components for implementing JS IPFS in the browser. These +There are a few additional components required for running JS IPFS in the browser. These are webrtc and websocket-star which will make it easier for implemented JS IPFS in the browser and boost the speed and reduce the errors. From 873d147a8eae196cfeb67ba1f04a492758bbe534 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 18:56:57 +0530 Subject: [PATCH 11/19] english grammer fixes --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 20f53b2cbd..52fffc211c 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -9,7 +9,7 @@ boosting the speed with reducing the errors you face often because of limitation js-ipfs. There are a few additional components required for running JS IPFS in the browser. These -are webrtc and websocket-star which will make it easier for implemented JS IPFS +are webrtc and websocket transports which enables connectivity for implementing JS IPFS in the browser and boost the speed and reduce the errors. You can find the information present for enabling webRTC support for js-ipfs in From 0251e1458f430d760c155ec2c614adea1ed2504f Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:00:22 +0530 Subject: [PATCH 12/19] Update doc/using-js-ipfs-in-the-browser.md Co-Authored-By: Marcin Rataj --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 52fffc211c..d4c2fcc9d2 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -14,7 +14,7 @@ in the browser and boost the speed and reduce the errors. You can find the information present for enabling webRTC support for js-ipfs in the browser [here](https://github.com/ipfs/js-ipfs#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) and a different one is -implementing with webrtc-star, you can find information [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). +providing signaling and transport over websockets, you can find information [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). You can find information about running IPFS in the broswer [here](https://github.com/ipfs/js-ipfs#table-of-contents). From 8216eaa6765d2b1ae76d4dac96347d239e443ee9 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:00:47 +0530 Subject: [PATCH 13/19] Update doc/using-js-ipfs-in-the-browser.md Co-Authored-By: Marcin Rataj --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index d4c2fcc9d2..f22c0f9bd6 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -16,7 +16,7 @@ You can find the information present for enabling webRTC support for js-ipfs in the browser [here](https://github.com/ipfs/js-ipfs#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) and a different one is providing signaling and transport over websockets, you can find information [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). -You can find information about running IPFS in the broswer [here](https://github.com/ipfs/js-ipfs#table-of-contents). +You can find detailed information about running js-ipfs [here](https://github.com/ipfs/js-ipfs#table-of-contents). Getting Data From IPFS ----------------------- From 141127a44fb25fafbea498c97f1769e40a441896 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:08:09 +0530 Subject: [PATCH 14/19] add example --- doc/using-js-ipfs-in-the-browser.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index f22c0f9bd6..337b7c35c2 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -24,16 +24,14 @@ Getting Data From IPFS Using Javascript in the browser ```js -const node = new IPFS() - -node.once('ready', () => { - node.pipe('QmPChd2hVbrJ6bfo3WBcTW4iZnpHm8TEzWkLHmLpXhF68A', (err, data) => { - if (err) return console.error(err) - - // convert Buffer back to string - console.log(data.toString()) - }) + + ``` JS IPFS Restriction in Web Browser From 015ea67a0f824b4bf52b62804331ce26be0dbc25 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:10:46 +0530 Subject: [PATCH 15/19] revert per the initial statement Co-Authored-By: Marcin Rataj --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 337b7c35c2..24372c6efc 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -37,7 +37,7 @@ document.addEventListener('DOMContentLoaded', async () => { JS IPFS Restriction in Web Browser ------------------------------------------ -- DHT in js-ipfs is not enabled by default. +- DHT in js-ipfs is not available yet. In browser a JS IPFS node is more restricted because of the same origin policy that decrease the discover/connect with peers, external peers without rendezvous From 1929d46610ff2841753abc119686b28e811c5ab6 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:21:57 +0530 Subject: [PATCH 16/19] technical behavioral line item fixes Co-Authored-By: Marcin Rataj --- doc/using-js-ipfs-in-the-browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 24372c6efc..584e319590 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -53,7 +53,7 @@ JS IPFS Best Practices ---------------------- - Configure nodes for using webrtc or websocket-star. -- Run independant instance as default one are under high load and YMMV. +- Run your own instance of `*-star` signaling service. The default ones are under high load and YMMV. - Make sure content you are implementing is cached in go-ipfs - manually `pin` or preload CIDs of interest with `refs -r` beforehand. - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or From 62e38c92328f84d6243427c33499d7df2d88dece Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Wed, 16 Oct 2019 19:29:51 +0530 Subject: [PATCH 17/19] fix few more statements --- doc/using-js-ipfs-in-the-browser.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 337b7c35c2..464429fb4e 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -39,10 +39,10 @@ JS IPFS Restriction in Web Browser - DHT in js-ipfs is not enabled by default. - In browser a JS IPFS node is more restricted because of the same origin policy - that decrease the discover/connect with peers, external peers without rendezvous - and relay servers, delegating peer/content routing and preload servers for content - discoverablilty hard and erroneous even with swarm peers. + This means js-ipfs running in the browser is limited to Web APIs available on a web page. + There is no raw TCP sockets nor low level UDP, only WebRTC and Websockets. + Discovery and connectivity to other peers is achieved with a mix of rendezvous and + relay servers, delegated peer/content routing and preload servers. - If the browser lacks TCP, you can set up delegating routing. The issue might still persist for connecting most of peers in the swarm as described above. @@ -53,7 +53,7 @@ JS IPFS Best Practices ---------------------- - Configure nodes for using webrtc or websocket-star. -- Run independant instance as default one are under high load and YMMV. +- Run independant instance as de - Make sure content you are implementing is cached in go-ipfs - manually `pin` or preload CIDs of interest with `refs -r` beforehand. - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or From 256d900238f0c9b57ebe865fd8e108117a78dbe1 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 18 Oct 2019 13:52:27 +0200 Subject: [PATCH 18/19] Update using-js-ipfs-in-the-browser.md Reorganized the content a bit and added references. --- doc/using-js-ipfs-in-the-browser.md | 103 +++++++++++++++------------- 1 file changed, 55 insertions(+), 48 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 180daaa9e1..9686e77e09 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -1,67 +1,74 @@ -Using JS IPFS in The Browser ----------------------------- +# Using JS IPFS in the Browser JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js. -The documentation details more information about running JS IPFS in the browser and -boosting the speed with reducing the errors you face often because of limitation of -js-ipfs. +**This document provides key information about running JS IPFS in the browser to +improve developer productivity. We lists most common caveats and limitations of the browser context.** -There are a few additional components required for running JS IPFS in the browser. These -are webrtc and websocket transports which enables connectivity for implementing JS IPFS -in the browser and boost the speed and reduce the errors. +## Limitations of the Browser Context -You can find the information present for enabling webRTC support for js-ipfs in -the browser [here](https://github.com/ipfs/js-ipfs#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) and a different one is -providing signaling and transport over websockets, you can find information [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). +- Transport options are limited to [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) and [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API). -You can find detailed information about running js-ipfs [here](https://github.com/ipfs/js-ipfs#table-of-contents). + This means JS IPFS running in the browser is limited to Web APIs available on a web page. + There is no access to raw TCP sockets nor low level UDP, only WebSockets and WebRTC. + +- Key [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) require or are restricted by [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) policies. -Getting Data From IPFS ------------------------ + This means JS IPFS needs to run within Secure Context (HTTPS or localhost). + JS IPFS running on HTTPS website requires Secure WebSockets (TLS) and won't work with unencrypted one. + [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) not being available at all. + +- [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table) is not available in JS IPFS yet. -Using Javascript in the browser + [We are working on it](https://github.com/ipfs/js-ipfs/pull/1994). For now, the discovery and connectivity to other peers is achieved with a mix of rendezvous and + relay servers, delegated peer/content routing and preload servers. -```js - - -``` -JS IPFS Restriction in Web Browser ------------------------------------------- +## Addressing Limitations -- DHT in js-ipfs is not available yet. +We provide a few additional components useful for running JS IPFS in the browser: - This means js-ipfs running in the browser is limited to Web APIs available on a web page. - There is no raw TCP sockets nor low level UDP, only WebRTC and Websockets. - Discovery and connectivity to other peers is achieved with a mix of rendezvous and - relay servers, delegated peer/content routing and preload servers. +- [libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star/) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo. + - Instructions on enabling `websocket-star` in js-ipfs config can be found [here](https://github.com/ipfs/js-ipfs#is-there-a-more-stable-alternative-to-webrtc-star-that-offers-a-similar-functionality). + - Make sure to [run your own rendezvous server](https://github.com/libp2p/js-libp2p-websocket-star/#usage-1). +- [libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo + - Instructions on enabling `webrtc-star` in js-ipfs config can be found [here](https://github.com/ipfs/js-ipfs#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser). + - Make sure to [run your own rendezvous server](https://github.com/libp2p/js-libp2p-webrtc-star#rendezvous-server-aka-signalling-server). +- [libp2p-webrtc-direct](https://github.com/libp2p/js-libp2p-webrtc-direct) - a WebRTC transport that doesn't require the set up a signalling server. + - Caveat: you can only establish Browser to Node.js and Node.js to Node.js connections. -- If the browser lacks TCP, you can set up delegating routing. The issue might still - persist for connecting most of peers in the swarm as described above. +**Note:** those are semi-centralized solutions. We are working towards replacing `*-star` with and ambient relays and [libp2p-rendezvous](https://github.com/libp2p/js-libp2p-rendezvous). Details and progress can be found [here](https://github.com/libp2p/js-libp2p/issues/385). -- Connection with websocket ports should be adhering with [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) limitations. +You can find detailed information about running js-ipfs [here](https://github.com/ipfs/js-ipfs#table-of-contents). + +## Best Practices + +- Configure nodes for using self-hosted `*-star` signaling and transport service. When in doubt, use WebSockets ones. +- Run your own instance of `*-star` signaling service. + The default ones are under high load and should be used only for tests and development. +- Make sure content added to js-ipfs running in the browser is persisted/cached somewhere on regular IPFS daemon + - Manually `pin` or preload CIDs of interest with `refs -r` beforehand. + - Preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) feature and/or + configure [delegated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). + - Avoid public instances in production environment. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of go-ipfs APIs via reverse proxy such as Nginx). -JS IPFS Best Practices ----------------------- +## Code Examples -- Configure nodes for using webrtc or websocket-star. -- Run your own instance of `*-star` signaling service. The default ones are under high load and YMMV. -- Make sure content you are implementing is cached in go-ipfs - - manually `pin` or preload CIDs of interest with `refs -r` beforehand. - - preload content on the fly using [preload](https://github.com/ipfs/js-ipfs#optionspreload) or - configuring [delegated routing](https://github.com/ipfs/js-ipfs#configuring-delegate-routers). - Here you will be using go-ipfs's API + nginx. +Prebuilt bundles are available, using JS IPFS in the browser is as simple as: -JS IPFS Examples ----------------- +```js + + +``` -We have documented a lot of examples for implemented JS IPFS in the browser, you -can find them [here](https://github.com/ipfs/js-ipfs-http-client/tree/master/examples). +More advanced examples and tutorials can be found in [`/examples`](https://github.com/ipfs/js-ipfs/tree/master/examples#js-ipfs-examples-and-tutorials) From b603f187667732d5303a23ff89b4fb85a45cdc1a Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 18 Oct 2019 13:54:20 +0200 Subject: [PATCH 19/19] Update using-js-ipfs-in-the-browser.md --- doc/using-js-ipfs-in-the-browser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/using-js-ipfs-in-the-browser.md b/doc/using-js-ipfs-in-the-browser.md index 9686e77e09..c70c8524b6 100644 --- a/doc/using-js-ipfs-in-the-browser.md +++ b/doc/using-js-ipfs-in-the-browser.md @@ -3,8 +3,8 @@ JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js. -**This document provides key information about running JS IPFS in the browser to -improve developer productivity. We lists most common caveats and limitations of the browser context.** +**This document provides key information about running JS IPFS in the browser. +Save time and get familiar with common caveats and limitations of the browser context.** ## Limitations of the Browser Context