Merge pull request #34 from ipfs/pinning-api

pinning API

API/pin/README.md

@@ -0,0 +1,90 @@
+Pin API
+=======
+
+#### `add`
+
+> Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able).
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.pin.add(hash, [options, callback])
+
+Where:
+
+- `hash` is an IPFS multihash.
+- `options` is an object that can contain the following keys
+  - 'recursive' - Recursively pin the object linked. Type: bool. Default: `false`
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` is an array of objects that represent the files that were pinned. Example:
+
+```JavaScript
+{
+  hash: 'QmHash'
+}
+``` 
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.pin.add(hash, function (err) {})
+```
+
+#### `ls`
+
+> List all the objects pinned to local storage or under a specific hash.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.pin.ls([hash, options, callback])
+
+Where:
+
+- `hash` is an IPFS multihash.
+- `options` is an object that can contain the following keys:
+  - 'type' - Return also the type of pin (direct, indirect or recursive)
+
+`callback` must follow `function (err, pinset) {}` signature, where `err` is an error if the operation was not successful. `pinset` is an array of objects with keys `hash` and `type`.
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.pin.ls(function (err, pinset) {
+  if (err) {
+    throw err
+  }
+  console.log(pinset)
+})
+```
+
+
+#### `rm`
+
+> Remove a hash from the pinset
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.pin.rm(hash, [options, callback])
+
+Where:
+- `hash` is a multihash.
+- `options` is an object that can contain the following keys
+  - 'recursive' - Recursively unpin the object linked. Type: bool. Default: `false`
+
+`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful. 
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.pin.rm(hash, function (err, pinset) {
+  if (err) {
+    throw err
+  }
+  console.log(pinset) prints the hashes that were unpinned
+})
+```

package.json

@@ -47,4 +47,4 @@
     "greenkeeperio-bot <support@greenkeeper.io>",
     "nginnever <ginneversource@gmail.com>"
   ]
-}
+}

src/index.js

@@ -3,3 +3,4 @@
 exports.object = require('./object')
 exports.files = require('./files')
 exports.config = require('./config')
+exports.pin = require('./pin')

src/pin.js

@@ -0,0 +1,158 @@
+/* eslint-env mocha */
+/* eslint max-nested-callbacks: ["error", 8] */
+
+'use strict'
+
+const expect = require('chai').expect
+const fs = require('fs')
+const path = require('path')
+
+const testfile = fs.readFileSync(path.join(__dirname, './data/testfile.txt'))
+
+module.exports = (common) => {
+  describe('.pin', () => {
+    let ipfs
+
+    before(function (done) {
+      // CI takes longer to instantiate the daemon,
+      // so we need to increase the timeout for the
+      // before step
+      this.timeout(20 * 1000)
+
+      common.setup((err, factory) => {
+        expect(err).to.not.exist
+        factory.spawnNode((err, node) => {
+          expect(err).to.not.exist
+          ipfs = node
+          populate()
+        })
+      })
+
+      function populate () {
+        const expectedMultihash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.files.add(testfile, (err, res) => {
+          expect(err).to.not.exist
+
+          expect(res).to.have.length(1)
+          expect(res[0].hash).to.equal(expectedMultihash)
+          expect(res[0].path).to.equal(expectedMultihash)
+          done()
+        })
+      }
+    })
+
+    after((done) => {
+      common.teardown(done)
+    })
+
+    describe('callback API', () => {
+      // 1st, because ipfs.files.add pins automatically
+      it('.rm', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.rm(hash, { recursive: true }, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.exist
+          ipfs.pin.ls({ type: 'direct' }, (err, pinset) => {
+            expect(err).to.not.exist
+            expect(pinset).to.be.empty
+            done()
+          })
+        })
+      })
+
+      it('.add', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.add(hash, { recursive: false }, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset[0]).to.be.equal(hash)
+          done()
+        })
+      })
+
+      it('.ls', (done) => {
+        ipfs.pin.ls((err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.not.be.empty
+          done()
+        })
+      })
+
+      it('.ls type direct', (done) => {
+        ipfs.pin.ls({ type: 'direct' }, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.not.be.empty
+          done()
+        })
+      })
+
+      it('.ls type indirect', (done) => {
+        ipfs.pin.ls({ type: 'indirect' }, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.not.be.empty
+          done()
+        })
+      })
+
+      it('.ls type recursive', (done) => {
+        ipfs.pin.ls({ type: 'recursive' }, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.not.be.empty
+          done()
+        })
+      })
+
+      it('.ls for a specific hash', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.ls(hash, (err, pinset) => {
+          expect(err).to.not.exist
+          expect(pinset).to.exist
+          done()
+        })
+      })
+    })
+
+    describe('promise API', () => {
+      it('.add', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.add(hash, { recursive: false })
+          .then((pinset) => {
+            expect(pinset[0]).to.be.equal(hash)
+          })
+      })
+
+      it('.ls', () => {
+        return ipfs.pin.ls()
+          .then((pinset) => {
+            expect(pinset).to.exist
+            expect(pinset).to.not.be.empty
+          })
+      })
+
+      it('.ls hash', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.ls(hash)
+          .then((pinset) => {
+            expect(pinset).to.exist
+          })
+      })
+
+      it('.rm', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.rm(hash, { recursive: false })
+          .then((pinset) => {
+            return ipfs.pin.ls({ type: 'direct' })
+          })
+          .then((pinset) => {
+            expect(pinset).to.be.empty
+          })
+      })
+    })
+  })
+}