From 601d9bc7f57d1607247552b0ce2c1fe5d1cb6071 Mon Sep 17 00:00:00 2001 From: Mark Robert Henderson Date: Sun, 30 Aug 2020 22:43:26 -0400 Subject: [PATCH] README and Doc updates Update README.md Update README.md Update README.md README doc updates --- README.md | 126 ++++++++++++++++++++- docs/PowergateIO.html | 166 ++++++++++++++++++++++++++-- docs/external-IPFS.html | 4 +- docs/external-OrbitDB.html | 4 +- docs/external-ipfs-log.html | 4 +- docs/external-powergate-client.html | 4 +- docs/global.html | 152 +------------------------ docs/index.html | 104 ++++++++++++++++- docs/index.js.html | 14 ++- src/index.js | 10 +- 10 files changed, 409 insertions(+), 179 deletions(-) diff --git a/README.md b/README.md index 2e290e5..2ba177b 100644 --- a/README.md +++ b/README.md @@ -1 +1,125 @@ -# orbit-db-powergate-io \ No newline at end of file +# PowergateIO (orbit-db-powergate-io) + +> A bridge between [OrbitDB](https://github.com/orbitdb/orbit-db) and [Powergate](https://docs.textile.io/powergate/), which is itself a bridge between [Filecoin](https://filecoin.io) and [IPFS](https://ipfs.io/). + +## Install + +`npm install orbit-db-powergate-io` + +### From Source + +```bash +$ git clone https://github.com/orbitdb/orbit-db-powergate-io +$ cd orbit-db-powergate-io +$ npm install +``` + +## Usage + +PowergateIO is designed to work with only one configuration option: the gRPC +endpoint of the Powergate node you want to connect to. Everything else should be handled +"under the hood" for you. See below. + +### Initial Setup + +```JavaScript +const PowergateIO = require('orbit-db-powergate-io') + +const host = 'http://0.0.0.0:6002' // This is the default value +PowergateIO.create(host) + .then((powergateio) => { + console.log(powergateio.wallet) // Will be {} until funded + }) +``` + +### Backing up an OrbitDB Snapshot + +PowergateIO is meant to be used from one IPFS node to another, and to replicate +OrbitDB databases between them. So, let's assume that we have an IPFS node and +OrbitDB running locally, and we're going to interact with a _remote_ Powergate +instance. + +```JavaScript +const IPFS = require('ipfs') +const OrbitDB = require('orbit-db') +const PowergateIO = require('orbit-db-powergate-io') + +;(async () => { + const ipfs = await IPFS.create() + const orbitdb = await OrbitDB.createInstance(ipfs) + powergateio = await PowergateIO.create('https://my.hosted.powergate.node') + + const addresses = (await powergateio.ipfs.id()).addresses + await ipfs.swarm.connect(addresses[0].toString()) + + const db = await orbitdb.eventlog('powergate-test') + for (let i = 0; i < 10; i++) { + await db.add(`entry${i}`) + } + + jobStatus = await powergateio.storeSnapshot(db.address.toString()) + console.log(jobStatus) + + // Wait until wallet is funded + // Can take up to 2 minute on testnet + console.log(powergateio.wallet) + + await powergateio.stop() + await orbitdb.disconnect() + await ipfs.stop() +})() +``` + +### Retrieving an OrbitDB Snapshot + +Once you've stored a snapshot and have made note of the DB address returned, +you can use that db address to retrieve the snapshot! + +```JavaScript +const IPFS = require('ipfs') +const OrbitDB = require('orbit-db') +const PowergateIO = require('orbit-db-powergate-io') + +;(async () => { + const ipfs = await IPFS.create() + const orbitdb = await OrbitDB.createInstance(ipfs) + const powergateio = await PowergateIO.create('https://my.hosted.powergate.node') + + const addresses = (await powergateio.ipfs.id()).addresses + await ipfs.swarm.connect(addresses[0].toString()) + + const dbAddr = '/orbitdb/zdpuAxkdoDum8Nk2VCxKkHZk8TzqAYPm86mVgoy7wagu2UcZB/powergate-test' + const db2 = await orbitdb.open(dbAddr, { create: true }) + const snapshot = await powergateio.retrieveSnapshot(dbAddr) + + await db2._oplog.join(snapshots[0].log) + await db2._updateIndex() +})() +``` + +For more information, see the [API docs](https://orbitdb.github.io/orbit-db-powergate-io/PowergateIO.html). + +## Contributing + +Issues and pull requests accepted. Please note that several issues have "[Help Wanted]" +and "[Good First Issue]" tags! + +[Good First Issue]: (https://github.com/orbitdb/orbit-db-powergate-io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +[Help Wanted]: (https://github.com/orbitdb/orbit-db-powergate-io/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) + +### Developing Locally + +It's highly recommended to install both Docker and Docker compose. From there, `make` is your +best friends. It gives you the following commands: + +- `make up` - Spins up all the necessary docker images for local development +- `make lint` - Lints your JS code vi standard.js +- `make docs` - Compiles the README and JS docstrings into the docs/ folder +- `make down` - Spins down all the docker images +- `make clean` - Removes ephemeral files and folders like node_modules and package-lock.json +- `make test` - Does a whole bunch of the above, in order. *use it!* +- `make rebuild` - runs `make clean` and `make deps` to give you a clean slate. + +## License + +MIT © OrbitDB Community diff --git a/docs/PowergateIO.html b/docs/PowergateIO.html index 3a2856b..47c261c 100644 --- a/docs/PowergateIO.html +++ b/docs/PowergateIO.html @@ -144,6 +144,78 @@

Members

+

_jobWatchers :Array.<intervalID>

+ + + + +
+ An array of intervalIDs that watch jobs +
+ + + +
Type:
+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + +

_orbitdb :OrbitDB

@@ -393,7 +465,79 @@

ipfsSource:
+ + + + + + + + + + + + + + + + +

wallet :Object

+ + + + +
+ FIL wallet info on the Powergate node +
+ + + +
Type:
+
    +
  • + +Object + + +
    • +
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
@@ -541,7 +685,7 @@
Parameters:
Source:
@@ -688,7 +832,7 @@
Parameters:
Source:
@@ -844,7 +988,7 @@
Parameters:
Source:
@@ -1005,7 +1149,7 @@
Parameters:
Source:
@@ -1116,7 +1260,7 @@

(async) stopSource:
@@ -1216,7 +1360,7 @@

(async)
Source:
@@ -1261,7 +1405,7 @@

watchJob Creates an interval to periodically check a job status and then updates the jobs database. -Then, adds the interval PowergateIO#_jobWatchers +Then, adds the interval PowergateIO#_jobWatchers @@ -1305,7 +1449,7 @@

watchJobSource:
@@ -1361,13 +1505,13 @@
Returns:

- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/external-IPFS.html b/docs/external-IPFS.html index b114849..0afa29f 100644 --- a/docs/external-IPFS.html +++ b/docs/external-IPFS.html @@ -124,13 +124,13 @@

IPFS


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/external-OrbitDB.html b/docs/external-OrbitDB.html index 8f4202f..d2cc6f1 100644 --- a/docs/external-OrbitDB.html +++ b/docs/external-OrbitDB.html @@ -122,13 +122,13 @@

OrbitDB


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/external-ipfs-log.html b/docs/external-ipfs-log.html index c273387..e9a773a 100644 --- a/docs/external-ipfs-log.html +++ b/docs/external-ipfs-log.html @@ -122,13 +122,13 @@

ipfs-log


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/external-powergate-client.html b/docs/external-powergate-client.html index 3af477e..faca76b 100644 --- a/docs/external-powergate-client.html +++ b/docs/external-powergate-client.html @@ -122,13 +122,13 @@

powergate-client


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/global.html b/docs/global.html index 2188304..a125890 100644 --- a/docs/global.html +++ b/docs/global.html @@ -94,154 +94,6 @@

-

Members

- - - -

an :Array.<intervalID>

- - - - -
- array of intervalIDs that watch jobs -
- - - -
Type:
-
    -
  • - -Array.<intervalID> - - -
    • -
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Source:
-
- - - - - - - -
- - - - - - - - -

FIL :Object

- - - - -
- wallet info for the PowergateIO node -
- - - -
Type:
-
    -
  • - -Object - - -
    • -
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - -
Source:
-
- - - - - - - -
- - - - - - - - @@ -525,13 +377,13 @@
Properties:

- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/index.html b/docs/index.html index abb94e0..1cdbaaf 100644 --- a/docs/index.html +++ b/docs/index.html @@ -43,7 +43,105 @@

-

orbit-db-powergate-io

+

PowergateIO (orbit-db-powergate-io)

+
+

A bridge between OrbitDB and Powergate, which is itself a bridge between Filecoin and IPFS.

+
+

Install

+

npm install orbit-db-powergate-io

+

From Source

+
$ git clone https://github.com/orbitdb/orbit-db-powergate-io
+$ cd orbit-db-powergate-io
+$ npm install
+
+

Usage

+

PowergateIO is designed to work with only one configuration option: the gRPC +endpoint of the Powergate node you want to connect to. Everything else should be handled +"under the hood" for you. See below.

+

Initial Setup

+
const PowergateIO = require('orbit-db-powergate-io')
+
+const host = 'http://0.0.0.0:6002' // This is the default value
+PowergateIO.create(host)
+  .then((powergateio) => {
+    console.log(powergateio.wallet) // Will be {} until funded
+  })
+
+

Backing up an OrbitDB Snapshot

+

PowergateIO is meant to be used from one IPFS node to another, and to replicate +OrbitDB databases between them. So, let's assume that we have an IPFS node and +OrbitDB running locally, and we're going to interact with a remote Powergate +instance.

+
const IPFS = require('ipfs')
+const OrbitDB = require('orbit-db')
+const PowergateIO = require('orbit-db-powergate-io')
+
+;(async () => {
+  const ipfs = await IPFS.create()
+  const orbitdb = await OrbitDB.createInstance(ipfs)
+  powergateio = await PowergateIO.create('https://my.hosted.powergate.node')
+
+  const addresses = (await powergateio.ipfs.id()).addresses
+  await ipfs.swarm.connect(addresses[0].toString())
+
+  const db = await orbitdb.eventlog('powergate-test')
+  for (let i = 0; i < 10; i++) {
+    await db.add(`entry${i}`)
+  }
+
+  jobStatus = await powergateio.storeSnapshot(db.address.toString())
+  console.log(jobStatus)
+
+  // Wait until wallet is funded
+  // Can take up to 2 minute on testnet
+  console.log(powergateio.wallet)
+
+  await powergateio.stop()
+  await orbitdb.disconnect()
+  await ipfs.stop()
+})()
+
+

Retrieving an OrbitDB Snapshot

+

Once you've stored a snapshot and have made note of the DB address returned, +you can use that db address to retrieve the snapshot!

+
const IPFS = require('ipfs')
+const OrbitDB = require('orbit-db')
+const PowergateIO = require('orbit-db-powergate-io')
+
+;(async () => {
+  const ipfs = await IPFS.create()
+  const orbitdb = await OrbitDB.createInstance(ipfs)
+  const powergateio = await PowergateIO.create('https://my.hosted.powergate.node')
+
+  const addresses = (await powergateio.ipfs.id()).addresses
+  await ipfs.swarm.connect(addresses[0].toString())
+
+  const dbAddr = '/orbitdb/zdpuAxkdoDum8Nk2VCxKkHZk8TzqAYPm86mVgoy7wagu2UcZB/powergate-test'
+  const db2 = await orbitdb.open(dbAddr, { create: true })
+  const snapshot = await powergateio.retrieveSnapshot(dbAddr)
+
+  await db2._oplog.join(snapshots[0].log)
+  await db2._updateIndex()
+})()
+
+

For more information, see the API docs.

+

Contributing

+

Issues and pull requests accepted. Please note that several issues have "Help Wanted" +and "Good First Issue" tags!

+

Developing Locally

+

It's highly recommended to install both Docker and Docker compose. From there, make is your +best friends. It gives you the following commands:

+
    +
  • make up - Spins up all the necessary docker images for local development
    • +
  • make lint - Lints your JS code vi standard.js
    • +
  • make docs - Compiles the README and JS docstrings into the docs/ folder
    • +
  • make down - Spins down all the docker images
    • +
  • make clean - Removes ephemeral files and folders like node_modules and package-lock.json
    • +
  • make test - Does a whole bunch of the above, in order. use it!
    • +
  • make rebuild - runs make clean and make deps to give you a clean slate.
    • +
+

License

+

MIT © OrbitDB Community

@@ -54,13 +152,13 @@


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/docs/index.js.html b/docs/index.js.html index 76195cf..9bb5c86 100644 --- a/docs/index.js.html +++ b/docs/index.js.html @@ -86,13 +86,19 @@

Source: index.js

/** @member { powergate-client } */ this._pow = pow - /** @member { Object } FIL wallet info for the PowergateIO node */ + /** + * FIL wallet info on the Powergate node + * @member { Object } + */ this.wallet = {} waitForBalance(pow.ffs, addr, 0).then((info) => { this.wallet = info }) - /** @member { intervalID[] } an array of intervalIDs that watch jobs*/ + /** + * An array of intervalIDs that watch jobs + * @member { intervalID[] } + */ this._jobWatchers = [] } @@ -288,13 +294,13 @@

Source: index.js


- Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 12:32:20 GMT-0400 (Eastern Daylight Time) + Documentation generated by JSDoc 3.6.6 on Tue Sep 22 2020 14:42:39 GMT-0400 (Eastern Daylight Time)
diff --git a/src/index.js b/src/index.js index 50442d2..bb2c024 100644 --- a/src/index.js +++ b/src/index.js @@ -58,13 +58,19 @@ class PowergateIO { /** @member { powergate-client } */ this._pow = pow - /** @member { Object } FIL wallet info for the PowergateIO node */ + /** + * FIL wallet info on the Powergate node + * @member { Object } + */ this.wallet = {} waitForBalance(pow.ffs, addr, 0).then((info) => { this.wallet = info }) - /** @member { intervalID[] } an array of intervalIDs that watch jobs*/ + /** + * An array of intervalIDs that watch jobs + * @member { intervalID[] } + */ this._jobWatchers = [] }