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

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

Closed
wants to merge 1 commit into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ 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)
- [Add a file](#add-a-file)
- [Retrieve a file](#retrieve-a-file)
- [More to come](#more-to-come)
- [API](#api)
- [Generic API](#generic-api)
Expand All @@ -48,6 +50,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)
- [Domain data types](#domain-data-types)
- [Development](#development)
- [Clone](#clone)
- [Install Dependencies](#install-dependencies)
Expand Down Expand Up @@ -148,6 +151,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,6 +184,38 @@ node.init({ emptyRepo: true, bits: 2048 }, (err) => {

> We are working on making this init process better, see https://github.com/ipfs/js-ipfs/issues/556 for the discussion.

Below are some more examples of JavaScript IPFS in action.

#### 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.

```javascript
// Add a single file
node.files.add(node.Buffer.from('Hello world'), (err, returned) => {
if (err) {
throw err
}
console.log('IPFS hash: ', returned[0].hash)
})
```

#### 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
node.files.cat('QmNRCQWfgze6AbBCaT1rkrkV5tJ2aP4oTNPb5JZcXYywve',
(err, content_stream) => {
if (err) {
throw err
}
content_stream.on('data', (buffer) => {
console.log('File contents:', buffer.toString('ascii'))
})
})
```

#### More to come

> If you have built an example, please share it with the community by submitting a Pull Request to this repo!.
Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


You can get it at `ipfs.Buffer`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

## Development

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

### Run Tests

#### Block Service

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this was a bad c&p

```sh
> npm test

Expand Down
13 changes: 13 additions & 0 deletions examples/browser-script/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Use IPFS in the browser with `<script>` tags

You can use IPFS in your in-browser JavaScript code with just a `<script>` tag.

```
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
```

This exposes a global `Ipfs`; you can get a node by making a `new Ipfs()`.

See `index.html` for a working example.


85 changes: 85 additions & 0 deletions examples/browser-script/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
<!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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

14 changes: 14 additions & 0 deletions examples/libp2p-webrtc-star/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# 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.

The `index.html` page in this directory 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.)
99 changes: 99 additions & 0 deletions examples/libp2p-webrtc-star/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<!doctype html>
<html>
<head>
<title>IPFS in the Browser with WebRTC</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/'

// Make an IPFS node
var ipfs = new Ipfs("webrtc-demo")

// 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)
}
})
}

function showPeers () {
ipfs.swarm.peers(function (err, peerInfos) {
document.getElementById("peers").innerHTML= ''
for (var i = 0; i < peerInfos.length; i++) {
document.getElementById("peers").innerHTML += peerInfos[i].addr + '<br/>'
}

setTimeout(showPeers, 1000)
})
}

// 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')
setTimeout(showPeers, 1000)
// 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 with WebRTC</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>
<p>Run a libp2p-webrtc-star signaling server! Peers detected through the server will be displayed below:</p>
<p>Peers:</p>
<div id="peers"></div>
</body>
</html>
3 changes: 3 additions & 0 deletions src/core/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,4 +67,7 @@ function IPFS (repoInstance) {
this.files = files(this)
this.bitswap = bitswap(this)
this.ping = ping(this)

// expose Buffer for browser applications
this.Buffer = Buffer
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just say expose Buffer for browser applications.

}