docs: update custom repo example

remove ability to add repoOptions in favor of just supplying a repo

Author: jacobheun

examples/custom-ipfs-repo/README.md

@@ -1,6 +1,12 @@
 # Customizing the IPFS Repo
 
-> This example shows you how to customize your repository, including where your data is stored and how the repo locking is managed.
+This example shows you how to customize your repository, including where your data is stored and how the repo locking is managed. Customizing your repo makes it easier to extend IPFS for your particular needs. You may want to customize your repo if:
+
+* If you want to store data somewhere that’s not on your local disk, like S3, a Redis instance, a different machine on your local network, or in your own database system, like MongoDB or Postgres, you might use a custom datastore.
+* If you have multiple browser windows or workers sharing the same IPFS storage, you might want to use a custom lock to coordinate between them. (Locking is currently only used to ensure a single IPFS instance can access a repo at a time. This check is done on `repo.open()`. A more complex lock, coupled with a custom datastore, could allow for safe writes to a single datastore from multiple IPFS nodes.)
+
+
+You can find full details on customization in the [IPFS Repo Docs](https://github.com/ipfs/js-ipfs-repo#setup).
 
 ## Run this example
 
@@ -12,13 +18,13 @@
 ## Other Options
 
 ### Custom Repo Lock
-> This example sets the repo locker to `false`, preventing any locking from happening. If you would like to control how locking happens, such as with a centralized S3 ipfs repo, you can pass in your own custom locker. See [custom-locker.js](./custom-locker.js) for an example of a custom locker that can be used for [datastore-s3](https://github.com/ipfs/js-datastore-s3).
+This example sets the repo locker to `false`, preventing any locking from happening. If you would like to control how locking happens, such as with a centralized S3 IPFS Repo, you can pass in your own custom lock. See [custom-lock.js](./custom-lock.js) for an example of a custom lock that can be used for [datastore-s3](https://github.com/ipfs/js-datastore-s3).
 
 ```js
-const S3Locker = require('./custom-locker')
+const S3Lock = require('./custom-lock')
 
 const repo = new Repo('/tmp/.ipfs', {
   ...
-  locker: new S3Locker(s3DatastoreInstance)
+  lock: new S3Lock(s3DatastoreInstance)
 })
 ```

examples/custom-ipfs-repo/custom-lock.js

@@ -0,0 +1,99 @@
+'use strict'
+
+const PATH = require('path')
+
+/**
+ * Uses an object in an S3 bucket as a lock to signal that an IPFS repo is in use.
+ * When the object exists, the repo is in use. You would normally use this to make
+ * sure multiple IPFS nodes don’t use the same S3 bucket as a datastore at the same time.
+ */
+class S3Lock {
+  constructor (s3Datastore) {
+    this.s3 = s3Datastore
+  }
+
+  /**
+   * Returns the location of the lock file given the path it should be located at
+   *
+   * @private
+   * @param {string} dir
+   * @returns {string}
+   */
+  getLockfilePath (dir) {
+    return PATH.join(dir, 'repo.lock')
+  }
+
+  /**
+   * Creates the lock. This can be overriden to customize where the lock should be created
+   *
+   * @param {string} dir
+   * @param {function(Error, LockCloser)} callback
+   * @returns {void}
+   */
+  lock (dir, callback) {
+    const lockPath = this.getLockfilePath(dir)
+
+    this.locked(dir, (err, alreadyLocked) => {
+      if (err || alreadyLocked) {
+        return callback(new Error('The repo is already locked'))
+      }
+
+      // There's no lock yet, create one
+      this.s3.put(lockPath, Buffer.from(''), (err, data) => {
+        if (err) {
+          return callback(err, null)
+        }
+
+        callback(null, this.getCloser(lockPath))
+      })
+    })
+  }
+
+  /**
+   * Returns a LockCloser, which has a `close` method for removing the lock located at `lockPath`
+   *
+   * @param {string} lockPath
+   * @returns {LockCloser}
+   */
+  getCloser (lockPath) {
+    return {
+      /**
+       * Removes the lock. This can be overriden to customize how the lock is removed. This
+       * is important for removing any created locks.
+       *
+       * @param {function(Error)} callback
+       * @returns {void}
+       */
+      close: (callback) => {
+        this.s3.delete(lockPath, (err) => {
+          if (err && err.statusCode !== 404) {
+            return callback(err)
+          }
+
+          callback(null)
+        })
+      }
+    }
+  }
+
+  /**
+   * Calls back on whether or not a lock exists. Override this method to customize how the check is made.
+   *
+   * @param {string} dir
+   * @param {function(Error, boolean)} callback
+   * @returns {void}
+   */
+  locked (dir, callback) {
+    this.s3.get(this.getLockfilePath(), (err, data) => {
+      if (err && err.message.match(/not found/)) {
+        return callback(err, false)
+      } else if (err) {
+        return callback(err)
+      }
+
+      callback(null, true)
+    })
+  }
+}
+
+module.exports = S3Lock

examples/custom-ipfs-repo/custom-locker.js

@@ -1,15 +1,17 @@
 'use strict'
 
-const series = require('async/series')
 const IPFS = require('ipfs')
+const Repo = require('ipfs-repo')
+const fsLock = require('ipfs-repo/src/lock')
 
 // Create our custom options
 const customRepositoryOptions = {
 
   /**
-   * Storage Backends are fully customizable. Each backend can be stored in seperate services,
-   * or in a single service. Options can be passed into the datastores via the storageBackendOptions
-   * property shown below.
+   * IPFS nodes store different information in separate storageBackends, or datastores.
+   * Each storage backend can use the same type of datastore or a different one — you
+   * could store your keys in a levelDB database while everything else is in files,
+   * for example. (See https://github.com/ipfs/interface-datastore for more about datastores.)
    */
   storageBackends: {
     root: require('datastore-fs'), // version and config data will be saved here
@@ -20,58 +22,72 @@ const customRepositoryOptions = {
 
   /**
    * Storage Backend Options will get passed into the instantiation of their counterpart
-   * in Storage Backends. If you create a custom datastore, this is where you can pass in
-   * custom insantiation. You can see an S3 datastore example at:
+   * in `storageBackends`. If you create a custom datastore, this is where you can pass in
+   * custom constructor arguments. You can see an S3 datastore example at:
    * https://github.com/ipfs/js-datastore-s3/tree/master/examples/full-s3-repo
    */
   storageBackendOptions: {
+    root: {
+      extension: '.ipfsroot', // Used by datastore-fs; Appended to all files
+      errorIfExists: false, // Used by datastore-fs; If the datastore exists, don't throw an error
+      createIfMissing: true // Used by datastore-fs; If the datastore doesn't exist yet, create it
+    },
     blocks: {
-      sharding: true,
-      extension: '.data'
+      sharding: false, // Used by IPFSRepo Blockstore to determine sharding; Ignored by datastore-fs
+      extension: '.ipfsblock',
+      errorIfExists: false,
+      createIfMissing: true
+    },
+    keys: {
+      extension: '.ipfskey',
+      errorIfExists: false,
+      createIfMissing: true
+    },
+    datastore: {
+      extension: '.ipfsds',
+      errorIfExists: false,
+      createIfMissing: true
     }
   },
 
-  // false will disable locking, you can also pass in a custom locker
-  locker: false
+  /**
+   * A custom lock can be added here. Or the build in Repo `fs` or `memory` locks can be used.
+   * See https://github.com/ipfs/js-ipfs-repo for more details on setting the lock.
+   */
+  lock: fsLock
 }
 
 // Initialize our IPFS node with the custom repo options
 const node = new IPFS({
-  repo: '/tmp/custom-repo/.ipfs',
-  repoOptions: customRepositoryOptions
+  repo: new Repo('/tmp/custom-repo/.ipfs', customRepositoryOptions)
 })
 
 // Test the new repo by adding and fetching some data
-let fileMultihash
-series([
-  (cb) => node.on('ready', cb),
-  (cb) => node.version((err, version) => {
-    if (err) {
-      return cb(err)
-    }
-
-    console.log('Version:', version.version)
-    cb()
-  }),
-  (cb) => node.files.add({
-    path: 'test-data.txt',
-    content: Buffer.from('We are using a customized repo!')
-  }, (err, filesAdded) => {
-    if (err) {
-      return cb(err)
-    }
-
-    console.log('\nAdded file:', filesAdded[0].path, filesAdded[0].hash)
-    fileMultihash = filesAdded[0].hash
-    cb()
-  }),
-  (cb) => node.files.cat(fileMultihash, (err, data) => {
-    if (err) {
-      return cb(err)
-    }
-
-    console.log('\nFetched file content:')
-    process.stdout.write(data)
-    cb()
-  })
-])
+node.on('ready', () => {
+  console.log('Ready')
+  node.version()
+    .then((version) => {
+      console.log('Version:', version.version)
+    })
+    // Once we have the version, let's add a file to IPFS
+    .then(() => {
+      return node.files.add({
+        path: 'test-data.txt',
+        content: Buffer.from('We are using a customized repo!')
+      })
+    })
+    // Log out the added files metadata and cat the file from IPFS
+    .then((filesAdded) => {
+      console.log('\nAdded file:', filesAdded[0].path, filesAdded[0].hash)
+      return node.files.cat(filesAdded[0].hash)
+    })
+    // Print out the files contents to console
+    .then((data) => {
+      console.log('\nFetched file content:')
+      process.stdout.write(data)
+    })
+    // Log out the error, if there is one
+    .catch((err) => {
+      console.log('File Processing Error:', err)
+    })
+})

examples/custom-ipfs-repo/index.js

@@ -9,8 +9,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "async": "^2.6.0",
     "datastore-fs": "~0.4.2",
-    "ipfs": "file:../../"
+    "ipfs": "file:../../",
+    "ipfs-repo": "~0.19.0"
   }
 }

examples/custom-ipfs-repo/package.json

@@ -43,7 +43,7 @@ class IPFS extends EventEmitter {
 
     if (typeof options.repo === 'string' ||
         options.repo === undefined) {
-      this._repo = defaultRepo(options.repo, options.repoPath)
+      this._repo = defaultRepo(options.repo)
     } else {
       this._repo = options.repo
     }