Revise README changes and add example web page

Author: interfect

README.md

@@ -39,9 +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)
-    - [Startup (in Node.js or browser)](#startup-in-node.js-or-browser)
-    - [Adding a file](#adding-a-file)
-    - [Retrieving a file](#retrieving-a-file)
+    - [Find IPFS in Node.js](#find-ipfs-in-nodejs)
+    - [Find IPFS in the Browser](#find-ipfs-in-the-browser)
+    - [Robust Initialization and libp2p-webrtc-star Signaling](#robust-initialization-and-libp2p-webrtc-star-signaling)
+    - [Add a file](#add-a-file)
+    - [Retrieve a file](#retrieve-a-file)
     - [More to come](#more-to-come)
   - [API](#api)
       - [Generic API](#generic-api)
@@ -146,6 +148,8 @@ The HTTP-API exposed by the js-ipfs daemon follows the [`http-api-spec`](https:/
 
 #### Create a IPFS node instance
 
+The basic startup flow involves (optionally) creating a Repo, creating an IPFS node, `init`-ing it so it can generate its keys, `load`-ing its configuration, and putting it online with `goOnline`. Here is a structural example:
+
 ```JavaScript
 // IPFS will need a repo, it can create one for you or you can pass
 // it a repo instance of the type IPFS Repo
@@ -179,18 +183,42 @@ node.init({ emptyRepo: true, bits: 2048 }, (err) => {
 
 Below are some more examples of JavaScript IPFS in action.
 
-#### Startup (in Node.js or browser)
+#### Find IPFS in Node.js
 
-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.
+If you are working in Node.js and did `npm install ipfs`, or if you are working in a browser environment that exposes Node builtins like `require`, you should get an IPFS node like this:
 
 ```javascript
-// Find the IPFS implementation
-const IPFS = typeof Ipfs !== 'undefined' ? Ipfs  // browser global
-  : typeof require === 'function' ? require('ipfs') // cjs require
-  : throw new Error('could not load IPFS')
-
-// Make an IPFS node
+const IPFS = require('ipfs')
 var ipfs = new IPFS()
+```
+
+#### Find IPFS in the Browser
+
+If you are in a normal browser Javascript environment, and loaded IPFS via the minified build or the [unpkg CDN](#use-in-a-browser-using-a-script-tag), you should get an IPFS node like this:
+
+```javascript
+var ipfs = new Ipfs()
+```
+
+Make sure your script loads after the IPFS library, so that the `Ipfs` global will be defined.
+
+#### Robust Initialization and libp2p-webrtc-star Signaling
+
+There's still a bit of work required to start up an in-browser node in a robust way, so that it will work whether or not there is an existing initialized IPFS repo in the user's browser. If there isn't one, you need to call `init` as above, but if there is one, calling `init` will fail. Moreover, there's currently no good way to check if you need to call `init` or not.
+
+Also, an in-browser node isn't able to call up normal IPFS nodes over raw TCP; it can only communicate over Websockets and WebRTC. Currently, there are no Websockets or WebRTC bootstrap nodes run by the IPFS maintainers. You will probably want to set up a [libp2p-webrtc-star signaling server](https://github.com./libp2p/js-libp2p-webrtc-star) so nodes used in your application can find each other:
+
+```bash
+npm i libp2p-webrtc-star -g
+star-sig
+```
+
+You will then want to point IPFS nodes used in your application at your signaling server, so they can connect to each other. This is accomplished by adding an address to the node's configuration referencing the signaling server, of the form `/libp2p-webrtc-star/ip4/<server-ip>/tcp/<server-port>/ws/ipfs/<peer-id>`, where `<peer-id>` is the peer ID of the node that the address is being added to. This causes the node to think of itself as being contactable through the signaling server. It will then initializes its libp2p-webrtc-star implementation and automatically peer with other nodes using the same server.
+
+Below is an example which initializes an IPFS node in a browser safely, whether a node has already been initialized by the current domain or not. It also configures `libp2p-webrtc-star` communication, using a signaling server running on the local host. (Note that since IPFS node configuration information is stored in IndexedDB in browsers, opening two tabs of this code from a local file in the same browser won't work, because they'll share the same node keys and identity. Either run the code from multiple domains, or run it in two different browsers, like Chrome and Firefox.)
+
+```javascript
+// We assume you already have your IPFS node in `ipfs`, as in the two examples above.
 
 // Init a repo in the given IPFS node it if hasn't got one already. Calls the
 // setup callback, passing the normal callback, after first initialization.
@@ -218,7 +246,7 @@ initIfNeeded(ipfs, (callback) => {
     if (err) {
       throw err
     }
-    // Add at least one libp2p-webrtc-star address. Without an address like this
+    // Add at least one libp2p-webrtc-star address. Without an address like this
     // the libp2p-webrtc-star transport won't be installed, and the resulting
     // node won't be able to dial out to libp2p-webrtc-star addresses.
     var star_addr = ('/libp2p-webrtc-star/ip4/127.0.0.1/tcp/9090/ws/ipfs/' +
@@ -250,7 +278,7 @@ initIfNeeded(ipfs, (callback) => {
 })
 ```
 
-#### Adding a file
+#### Add a file
 
 Once you have an IPFS node up and running, you can add files to it from `Buffer`s, `Readable` streams, or [arrays of objects of a certain form](https://github.com./ipfs/interface-ipfs-core/tree/master/API/files#add). If you don't have `Buffer` conveniently available (say, because you're in a browser without the Node API handy), it's available as a property of the IPFS node.
 
@@ -264,14 +292,13 @@ ipfs.files.add(ipfs.Buffer.from('Hello world'), (err, returned) => {
 })
 ```
 
-#### Retrieving a file
+#### Retrieve a file
 
 To retrieve the contents of a file, you can use the [cat method](https://github.com./ipfs/interface-ipfs-core/tree/master/API/files#cat), which will call your callback with a Node.js-style `Readable` stream.
 
 ```javascript
 ipfs.files.cat('QmNRCQWfgze6AbBCaT1rkrkV5tJ2aP4oTNPb5JZcXYywve', 
   (err, content_stream) => {
-
   if (err) {
     throw err
   }

examples/in-browser/index.html

@@ -0,0 +1,87 @@
+<!doctype html>
+<html>
+<head>
+  <title>IPFS in the Browser</title>
+  <script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
+  <script type="text/javascript">
+    // Set this if you have a libp2p-webrtc-star server
+    // Something like
+    // const SIGNALING_SERVER = '/libp2p-webrtc-star/ip4/127.0.0.1/tcp/9090/ws/ipfs/'
+    const SIGNALING_SERVER = null
+  
+    // 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
+    // setup callback, passing the normal callback, after first initialization.
+    // Calls the normal callback directly after subsequent initializations. Calls
+    // the normal callback with an error parameter if there is an error.
+    function initIfNeeded (ipfs, setup, callback) {
+      ipfs.init((err) => {
+        if (!err) {
+          // This is the first time we have started a node
+          setup(callback)
+        } else if (err.message == 'repo already exists') {
+          // The node already exists
+          callback()
+        } else {
+          callback(err)
+        }
+      })
+    }
+
+    // Init the node
+    initIfNeeded(ipfs, (callback) => {
+      // On first initialization, do some setup
+      // Get the node config we just init-ed
+      ipfs.config.get((err, config) => {
+        if (err) {
+          throw err
+        }
+        
+        if (SIGNALING_SERVER) {
+        
+          // Add at least one libp2p-webrtc-star address. Without an address like this
+          // the libp2p-webrtc-star transport won't be installed, and the resulting
+          // node won't be able to dial out to libp2p-webrtc-star addresses.
+          var star_addr = (SIGNALING_SERVER + config.Identity.PeerID)
+          ipfs.config.set('Addresses.Swarm[1]', star_addr, (err) => {
+            if (err) {
+              throw err
+            }
+            // Continue down the already-initialized code path
+            callback()
+          })
+        } else {
+          // No signaling server is known. Just cointinue without it.
+          // We don't want to spam the console in our demo
+          callback()
+        }
+      })
+    }, (err) => {
+      // If the repo was already initialized, or after the first-time initialization
+      // code is run, we'll do this.
+      if (err) {
+        throw err
+      }
+      // Have the node set itself up
+      ipfs.load(() => {
+        // Go online and connect to things
+        ipfs.goOnline(() => {
+          console.log('Online status: ', ipfs.isOnline() ? 'online' : 'offline')
+          document.getElementById("status").innerHTML= 'Node status: ' + (ipfs.isOnline() ? 'online' : 'offline')
+          // TODO: Write your code here!
+          // Use methods like ipfs.files.add, ipfs.files.get, and so on in here
+          // Methods requiring buffers can use ipfs.Buffer
+        })
+      })
+    })
+  </script>
+</head>
+<body>
+  <h1>IPFS in the Browser</h1>
+  <p>This page creates an IPFS node in your browser and drops it into the global Javascript namespace as <em>ipfs</em>. Open the console to play around with it.</p>
+  <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>