Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

Commit

Permalink
Revise README changes and add example web page
Browse files Browse the repository at this point in the history
  • Loading branch information
interfect committed Nov 23, 2016
1 parent 7b0921e commit ff978f1
Show file tree
Hide file tree
Showing 2 changed files with 129 additions and 15 deletions.
57 changes: 42 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-node.js)
- [Find IPFS in the Browser](#find-ipfs-in-the-browser)
- [Robust Initialization and libp2p-webrtc-star Signaling](#robust-initialization-and-libp2p-webrtc-star-signaling)
- [Adda file](#add-a-file)
- [Retrieve a file](#retrieve-a-file)
- [More to come](#more-to-come)
- [API](#api)
- [Generic API](#generic-api)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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/' +
Expand Down Expand Up @@ -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.
Expand All @@ -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
}
Expand Down
87 changes: 87 additions & 0 deletions examples/in-browser/index.html
Original file line number Diff line number Diff line change
@@ -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>

0 comments on commit ff978f1

Please sign in to comment.