This repository has been archived by the owner on Feb 12, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Expose Buffer on ipfs objects, add examples
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.
- Loading branch information
Showing
6 changed files
with
259 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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.) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters