docs: add s3 lock to the example

License: MIT
Signed-off-by: Jacob Heun <[email protected]>

Author: jacobheun

examples/full-s3-repo/index.js

@@ -5,8 +5,9 @@ const IPFS = require('ipfs')
 const Repo = require('ipfs-repo')
 const S3 = require('aws-sdk').S3
 const S3Store = require('../../src')
+const S3Lock = require('./s3-lock')
 
-let fileMultihash
+// Initialize the AWS S3 instance
 const s3 = new S3({
   params: {
     Bucket: 'my-bucket'
@@ -15,6 +16,11 @@ const s3 = new S3({
   secretAccessKey: 'mysecretkey'
 })
 
+// Create our custom lock
+const s3Store = new S3Store('/tmp/test/.ipfs', { s3 })
+const s3Lock = new S3Lock(s3Store)
+
+// Create the IPFS Repo, full backed by S3
 const repo = new Repo('/tmp/test/.ipfs', {
   storageBackends: {
     root: S3Store,
@@ -28,34 +34,46 @@ const repo = new Repo('/tmp/test/.ipfs', {
     keys: { s3 },
     datastore: { s3 }
   },
-  lock: 'memory'
+  lock: s3Lock
 })
 
+// Create a new IPFS node with our S3 backed Repo
 let node = new IPFS({
-  repo: repo
+  repo
 })
 
-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: 'hello.txt',
-    content: Buffer.from('Hello World 101')
-  }, (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('\nFile content:')
-    process.stdout.write(data)
-  })
-])
+// Test out the repo by sending and fetching some data
+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: 'hello.txt',
+        content: Buffer.from('Hello World 101')
+      })
+    })
+    // 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)
+    })
+    // After everything is done, shut the node down
+    // We don't need to worry about catching errors here
+    .then(() => {
+      console.log('\n\nStopping the node')
+      return node.stop()
+    })
+})

examples/full-s3-repo/package.json

@@ -13,6 +13,6 @@
     "async": "^2.6.0",
     "aws-sdk": "^2.220.1",
     "ipfs": "^0.28.2",
-    "ipfs-repo": "^0.18.7"
+    "ipfs-repo": "^0.20.0"
   }
 }

examples/full-s3-repo/s3-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(dir), (err, data) => {
+      if (err && err.message.match(/not found/)) {
+        return callback(null, false)
+      } else if (err) {
+        return callback(err)
+      }
+
+      callback(null, true)
+    })
+  }
+}
+
+module.exports = S3Lock