feat: Expose ipfs utils and add an example on how to run ipfs in the browser #525

interfect · 2016-10-18T04:33:40Z

Trying to use IPFS in a browser, I ran into trouble actually invoking ipfs.files.add, because it wanted me to pass a Buffer, but no implementation of Buffer was available in the browser namespace. This lets the Buffer implementation used internally inside the IPFS class get exposed as a field on instances, so you can invoke ipfs.files.add given only an IPFS object and no other Node globals.

Also, I've included some examples demoing use in a browser, and featuring this new exported Buffer type. It took me a long time to work out the incantations to use, so I feel obliged to put them somewhere prominent.

If there was an official bootstrap libp2p-webrtc-star signaling server, I would use that instead of 127.0.0.1 in my example. If you don't have at least one address on your node, including a signaling server IP, you don't get the transport added to the node and then you can never dial out through any signaling server. So I figured I had to add it in the example, to not confuse people over why they couldn't use the transport.

Closes #523. Also should address #513. Also may help with #509, since I definitely have it loading up in a browser.

heavyk · 2016-10-18T11:23:50Z

nice! the only thing I would do different in the example would be:

const IPFS = typeof Ipfs !== 'undefined' ? Ipfs  // browser global
  : typeof require === 'function' ? require('ipfs') // cjs require
  : throw new Error('could not load IPFS')

to me, the if (!(typeof require === 'undefined')) { logic is a bit weird.

interfect · 2016-10-19T02:08:29Z

@heavyk How about this?

heavyk · 2016-10-19T07:57:35Z

I like it :) it certainly clarifies the docs a bit. it's by no means extensive, but that would have certainly been helpful to me when I began. I ended up looking through a bunch of tests to figure out what was going on, so yea

haadcode · 2016-10-19T12:02:04Z

I would highly recommend to merge this PR asap. It improves our docs 200%.

@diasdavid @dignifiedquire can you verify that the startup sequence code is what is currently needed?

haadcode · 2016-10-19T12:02:17Z

Thanks for the PR @interfect!

interfect · 2016-10-23T05:05:00Z

Is there anything I still ought to do to get this merged in?

daviddias · 2016-10-24T09:44:48Z

README.md

@@ -110,7 +110,109 @@ The last published version of the package become [available for download](htt

 ### Examples

-> **Will come soon**
+Below are spome examples of JavaScript IPFS in action.


Add a ToC for the examples provided, so that are easily seekable.

daviddias · 2016-10-24T09:46:19Z

README.md

-> **Will come soon**
+Below are spome examples of JavaScript IPFS in action.
+
+#### Startup (in Node.js or browser)


Let's break the "Creating an instance" into two parts

"Create an IPFS instance - Node.js"
"Create an IPFS instance - Browser"

Just to avoid that 'scary' require in line 121

daviddias · 2016-10-24T09:47:21Z

README.md

+
+#### Startup (in Node.js or browser)
+
+There's still a bit of work required to start up a node in a robust way (i.e. without requiring the user to manually `js-ipfs init`). Here is one way to do it.


This sentence might be confusing to new users. "What is starting a node in a robust way"? Why is doing 'init' not robust?

daviddias · 2016-10-24T09:47:55Z

README.md

+
+// Make an IPFS node
+var ipfs = new IPFS()
+


As said above, let's make the code till here two sections "Node.js and Browser"

daviddias · 2016-10-24T09:48:23Z

README.md

+// Make an IPFS node
+var ipfs = new IPFS()
+
+// Init a repo in the given IPFS node it if hasn't got one already. Calls the


From here down, let's create a section "Init and start the node"

daviddias · 2016-10-24T09:51:51Z

README.md

+    ipfs.config.set('Addresses.Swarm[1]', star_addr, (err) => {
+      if (err) {
+        throw err
+      }


This also requires the signalling server of libp2p-webrtc-star to be up. Which makes me think that maybe we should have one always running for people to do demos that goes with the default config.

@lgierth how does this sound?

We have two options:

a) If we get a signalling server always up, then we should make WebSockets and webrtc-start be the default config values for a browser node (the same way we have the TCP Sockets)

b) If we don't get the signalling server always up. We should set the default addrs to be just websockets for browser and have a separate example that shows how to turn on WebRTC.

daviddias · 2016-10-24T09:53:16Z

README.md

+```javascript
+ipfs.files.cat('QmNRCQWfgze6AbBCaT1rkrkV5tJ2aP4oTNPb5JZcXYywve', 
+  (err, content_stream) => {
+


extra new line

daviddias · 2016-10-24T09:55:04Z

README.md

@@ -187,6 +289,8 @@ IPFS Core is divided into separate subsystems, each of them exist in their own r

 IPFS Core is the entry point module for IPFS. It exposes an interface defined on [IPFS Specs.](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)

+This particular implementation also provides some extensions to assist with usage in a browser, such as the `Buffer` type, required as input for some API methods, being available as `ipfs.Buffer` on every `IPFS` object.


Let's make it more of a disclaimer

#### Need the Buffer class? IPFS exposes the Buffer class in every ipfs instance, so that you can create buffers and add them to IPFS just like if you were using it in Node.js. You can get it at `ipfs.Buffer`

daviddias · 2016-10-24T09:55:48Z

src/core/index.js

+  // Export Buffer to somewhere where API consumers can get at it, for when
+  //  we're running in a browser but still expect Buffer instances to be passed
+  //  in.
+  this.Buffer = Buffer


Just say expose Buffer for browser applications.

daviddias · 2016-10-24T10:00:46Z

@interfect excellent work! Thank you a lot for this, having someone building a tutorial for js-ipfs and seeing all of the hurdles you had to go through to get IPFS running... I'm sorry :(

We can definitely make it better and make this tutorial way simpler, in fact, I want to have it sooner than later, would you like to make this PR a little bit by improving the API to start IPFS?

It should be something like: new IPFS(options) where options can take

{
  init: <default-false>
  repo: <pathOrIPFSRepoInstance>
  online: <default-false>
}

So that a

{
  init: true
  repo: ~/.ipfs
  online: true
}

Would do the init -> load -> goOnline dance :)

daviddias · 2016-11-14T10:58:42Z

beep boop :)

This PR needs a rebase. May I also ask for it to:

Create a util object that exposes things like Buffer, multihash, libp2p-crypto (as crypto), multibase, Stream (Node.js Stream), dagPB and dagCBOR? It seems that our users stump a lot in having to require this modules themselves, both in js-ipfs and js-ipfs-api (so this would have to be added to js-ipfs-api as well).
Add this example to the folder "examples"

Thank you! :)

interfect · 2016-11-15T01:43:22Z

Sorry for kind of vanishing.

I don't think I want to try to take on refactoring the API myself, or at
least not yet, because I don't feel comfortable enough with the internals.

I will rebase this and try to split up the example code into node and
browser sections. I would want to get the tutorial in for the current API,
and then fix the API and the tutorial for the new better API.

On Mon, Nov 14, 2016 at 2:58 AM, David Dias notifications@github.com
wrote:

beep boop :)

This PR needs a rebase. May I also ask for it to:

Create a util object that exposes things like Buffer, multihash,
libp2p-crypto (as crypto), multibase, Stream (Node.js Stream), dagPB and
dagCBOR? It seems that our users stump a lot in having to require this
modules themselves, both in js-ipfs and js-ipfs-api (so this would have to
be added to js-ipfs-api as well).

Add this example to the folder "examples"

Thank you! :)

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#525 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAt5tkrvWAcIwjvUHqH7U4cGIT_H0SChks5q-D7kgaJpZM4KZXhn
.

daviddias · 2016-11-15T05:59:27Z

Sounds good to me @interfect we can conquer this one by parts :)

Also happy to explain you more in depth of how the internals work to get you more comfortable with it, through chat in IRC/Github or a hangout

interfect · 2016-11-23T04:02:21Z

@diasdavid I think I have addressed your comments. I fixed up the comments in the actual code, added an example under examples, and simplified the ugly IPFS-finding logic.

My example in the README is getting pretty big, since I included more of a writeup on why it is like it is. Maybe it wants to move somewhere else? If so, where would that be?

daviddias · 2016-11-23T11:03:47Z

@interfect please move the example to the examples folder so that it is easy to run, making the readme a bit more lean (#525 (comment))

daviddias · 2016-11-23T11:04:59Z

README.md

@@ -39,6 +39,11 @@ Consult the [Roadmap](/ROADMAP.md) for a complete state description of the proje
  - [HTTP-API](#http-api)
  - [IPFS Core examples (use IPFS as a module)](#ipfs-core-examples-use-ipfs-as-a-module)
    - [Create a IPFS node instance](#create-a-ipfs-node-instance)
+    - [Find IPFS in Node.js](#find-ipfs-in-nodejs)


I don't believe this will be needed as with the examples we have right now on https://github.com/ipfs/js-ipfs/tree/master/examples, but feel welcome to complement them.

daviddias · 2016-11-23T11:05:19Z

README.md

@@ -39,6 +39,11 @@ Consult the [Roadmap](/ROADMAP.md) for a complete state description of the proje
  - [HTTP-API](#http-api)
  - [IPFS Core examples (use IPFS as a module)](#ipfs-core-examples-use-ipfs-as-a-module)
    - [Create a IPFS node instance](#create-a-ipfs-node-instance)
+    - [Find IPFS in Node.js](#find-ipfs-in-nodejs)
+    - [Find IPFS in the Browser](#find-ipfs-in-the-browser)


I don't believe this will be needed as with the examples we have right now on https://github.com/ipfs/js-ipfs/tree/master/examples, but feel welcome to complement them.

daviddias · 2016-11-23T11:06:06Z

README.md

@@ -48,6 +53,7 @@ Consult the [Roadmap](/ROADMAP.md) for a complete state description of the proje
      - [Files API](#files-api)
      - [Swarm API](#swarm-api)
      - [libp2p API](#libp2p-api)
+      - [Need the Buffer class?](#need-the-buffer-class)


Maybe replace this by "Domain data types", so that it includes things like multiaddr, multihash, etc.

This lets you construct a Buffer even in browser code that doesn't have access to the Node Buffer global, so that you can pass it back to IPFS API calls that want a Buffer. Add some usage documentation Mentions the `ipfs.Buffer` field you can use to stamp out `Buffer`s so you can actually insert stuff given just an `IPFS` instance and no Node.js APIs in scope. Also add examples for using IPFS in browser with a script tag, and for using libp2p-webrtc-star.

interfect · 2016-12-19T01:18:57Z

OK, I've gone and kicked most of my changes out of the main README and into a couple of examples: one just for IPFS in a browser with script tags, and one for IPFS in a browser with libp2p-webrtc-star.

@diasdavid could you please review this again? I don't know what's up with nodejs 4 in the tests; I changed ~3 lines of actual code.

interfect · 2017-01-04T01:29:06Z

@diasdavid Is there anything else you want changed?

daviddias · 2017-01-09T11:47:24Z

README.md

+IPFS exposes the Buffer class in every ipfs instance, so that you can create buffers and add them to IPFS just like if you were using it in Node.js.
+
+You can get it at `ipfs.Buffer`
+


Since devs will start relying on this, let's make sure it is complete by putting these 'Types' behind, ipfs.types and adding things like multiaddr, multihash and so.

I've added a ipfs.types. at https://github.com/ipfs/js-ipfs/blob/master/src/core/index.js#L25 that you can expand to include all the IPFS types.

daviddias · 2017-01-09T11:48:25Z

README.md

@@ -208,6 +245,12 @@ Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal int
 - [libp2p-ipfs-nodejs](https://github.com/ipfs/js-libp2p-ipfs-nodejs)
 - [libp2p-ipfs-browser](https://github.com/ipfs/js-libp2p-ipfs-browser)

+#### Domain data types
+
+IPFS exposes the Buffer class in every ipfs instance, so that you can create buffers and add them to IPFS just like if you were using it in Node.js.


Rather explain that we expose a set of data types directly from the ipfs instance, so that devs don't have to require/import them again.

daviddias · 2017-01-09T11:48:40Z

README.md

@@ -225,6 +268,8 @@ Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal int

 ### Run Tests

+#### Block Service
+


I believe this was a bad c&p

daviddias · 2017-01-09T11:49:16Z

examples/browser-script/index.html

+  <p>Note that opening two tabs of this page in the same browser won't work well, because they will share node configuration. You'll end up trying to run two instances of the same node, with the same private key and identity, which is a Bad Idea.</p>
+  <div id="status">Node status: offline</div>
+</body>
+</html>


This example is missing loading IPFS from a script tag with spawning a webrtc-star sig server

daviddias · 2017-02-01T16:10:50Z

@interfect will you be looking into finish this PR soon?

interfect · 2017-02-02T02:33:44Z

Honestly with all the rounds of requested changes it's not something I look forward to working on. It's still on my to do list, but I keep putting it off. On Feb 1, 2017 8:10 AM, "David Dias" <notifications@github.com> wrote: @interfect <https://github.com/interfect> will you be looking into finish this PR soon? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#525 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAt5tuXxeCJfDGNGVIFGEHozjxLpOMLfks5rYK6MgaJpZM4KZXhn> .

interfect · 2017-03-14T01:41:52Z

Looks like this has been picked up by some other PRs, so I'm going to close it.

interfect force-pushed the patch-1 branch from 19334c6 to 211b5dd Compare October 19, 2016 02:07

daviddias suggested changes Oct 24, 2016

View reviewed changes

daviddias changed the title ~~Expose Buffer and document browser usage~~ Expose ipfs utils and add an example on how to run ipfs in the browser Nov 14, 2016

daviddias mentioned this pull request Nov 17, 2016

feat: expose Buffer on the dist version #523

Closed

daviddias added the js-ipfs-ready label Nov 21, 2016

interfect force-pushed the patch-1 branch 3 times, most recently from ff978f1 to f84438a Compare November 23, 2016 04:00

daviddias reviewed Nov 23, 2016

View reviewed changes

daviddias suggested changes Nov 23, 2016

View reviewed changes

daviddias added status/ready Ready to be worked and removed js-ipfs-ready labels Dec 5, 2016

interfect force-pushed the patch-1 branch from 9105166 to d95e3a8 Compare December 19, 2016 01:05

interfect force-pushed the patch-1 branch from d95e3a8 to ff2069a Compare December 19, 2016 01:06

daviddias suggested changes Jan 9, 2017

View reviewed changes

daviddias added status/deferred Conscious decision to pause or backlog and removed status/ready Ready to be worked labels Jan 29, 2017

daviddias mentioned this pull request Jan 29, 2017

Provide access to bundled libraries when run in browser ipfs-inactive/js-ipfs-http-client#406

Closed

daviddias changed the title ~~Expose ipfs utils and add an example on how to run ipfs in the browser~~ feat: Expose ipfs utils and add an example on how to run ipfs in the browser Feb 1, 2017

This was referenced Mar 11, 2017

Feat/expose ipfs utils #784

Merged

Example: Add WebRTC star example #786

Closed

interfect closed this Mar 14, 2017

Kubuxu removed the status/deferred Conscious decision to pause or backlog label Mar 14, 2017

This was referenced Apr 4, 2018

feat: Provide access to bundled libraries when in browser ipfs-inactive/js-ipfs-http-client#732

Merged

feat: Provide access to bundled libraries when in browser #1297

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Expose ipfs utils and add an example on how to run ipfs in the browser #525

feat: Expose ipfs utils and add an example on how to run ipfs in the browser #525

interfect commented Oct 18, 2016

heavyk commented Oct 18, 2016

interfect commented Oct 19, 2016

heavyk commented Oct 19, 2016 •

edited

Loading

haadcode commented Oct 19, 2016

haadcode commented Oct 19, 2016

interfect commented Oct 23, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias Oct 24, 2016

daviddias commented Oct 24, 2016

daviddias commented Nov 14, 2016

interfect commented Nov 15, 2016

daviddias commented Nov 15, 2016

interfect commented Nov 23, 2016

daviddias commented Nov 23, 2016

daviddias Nov 23, 2016

daviddias Nov 23, 2016

daviddias Nov 23, 2016

interfect commented Dec 19, 2016

interfect commented Jan 4, 2017

daviddias Jan 9, 2017

daviddias Feb 1, 2017

daviddias Jan 9, 2017

daviddias Jan 9, 2017

daviddias Jan 9, 2017

daviddias commented Feb 1, 2017

interfect commented Feb 2, 2017 via email

interfect commented Mar 14, 2017


		#### Startup (in Node.js or browser)

		There's still a bit of work required to start up a node in a robust way (i.e. without requiring the user to manually `js-ipfs init`). Here is one way to do it.

		@@ -187,6 +289,8 @@ IPFS Core is divided into separate subsystems, each of them exist in their own r

		IPFS Core is the entry point module for IPFS. It exposes an interface defined on [IPFS Specs.](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)

		This particular implementation also provides some extensions to assist with usage in a browser, such as the `Buffer` type, required as input for some API methods, being available as `ipfs.Buffer` on every `IPFS` object.

		IPFS exposes the Buffer class in every ipfs instance, so that you can create buffers and add them to IPFS just like if you were using it in Node.js.

		You can get it at `ipfs.Buffer`

		@@ -225,6 +268,8 @@ Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal int

		### Run Tests

		#### Block Service

feat: Expose ipfs utils and add an example on how to run ipfs in the browser #525

feat: Expose ipfs utils and add an example on how to run ipfs in the browser #525

Conversation

interfect commented Oct 18, 2016

heavyk commented Oct 18, 2016

interfect commented Oct 19, 2016

heavyk commented Oct 19, 2016 • edited Loading

haadcode commented Oct 19, 2016

haadcode commented Oct 19, 2016

interfect commented Oct 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daviddias commented Oct 24, 2016

daviddias commented Nov 14, 2016

interfect commented Nov 15, 2016

daviddias commented Nov 15, 2016

interfect commented Nov 23, 2016

daviddias commented Nov 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

interfect commented Dec 19, 2016

interfect commented Jan 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daviddias commented Feb 1, 2017

interfect commented Feb 2, 2017 via email

interfect commented Mar 14, 2017

heavyk commented Oct 19, 2016 •

edited

Loading