diff --git a/CHANGELOG.md b/CHANGELOG.md index 443bc3728..765c9ef2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ + +# [0.38.0](https://github.com/ipfs/interface-ipfs-core/compare/v0.37.0...v0.38.0) (2018-01-05) + + +### Features + +* normalize KEY API ([#192](https://github.com/ipfs/interface-ipfs-core/issues/192)) ([5a21d6c](https://github.com/ipfs/interface-ipfs-core/commit/5a21d6c)) +* normalize NAME API ([#190](https://github.com/ipfs/interface-ipfs-core/issues/190)) ([9670c1a](https://github.com/ipfs/interface-ipfs-core/commit/9670c1a)) + + + # [0.37.0](https://github.com/ipfs/interface-ipfs-core/compare/v0.36.16...v0.37.0) (2017-12-28) diff --git a/SPEC/KEY.md b/SPEC/KEY.md index 2cd784456..f0342f1d4 100644 --- a/SPEC/KEY.md +++ b/SPEC/KEY.md @@ -23,16 +23,13 @@ If no `callback` is passed, a promise is returned. **Example:** ```JavaScript -ipfs.key.add( - 'my-key', - { type: 'rsa', size: 2048 }, - (err, key) => console.log(key)) +ipfs.key.gen('my-key', { + type: 'rsa', + size: 2048 +}, (err, key) => console.log(key)) - -{ - Name: 'my-key', - Id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg' -} +// { id: 'QmYWqAFvLWb2G5A69JGXui2JJXzaHXiUEmQkQgor6kNNcJ', +// name: 'my-key' } ``` #### `list` @@ -43,7 +40,14 @@ ipfs.key.add( ##### `JavaScript` - ipfs.key.list([callback]) -`callback` must follow `function (err, keys) {}` signature, where `err` is an Error if the operation was not successful. `keys` is an object with the property `Keys` that is an array of `KeyInfo` (`name` and `id`) +`callback` must follow `function (err, keys) {}` signature, where `err` is an Error if the operation was not successful. `keys` is an array of: + +``` +{ + id: 'hash', // string - the hash of the key + name: 'self' // string - the name of the key +} +``` If no `callback` is passed, a promise is returned. @@ -52,14 +56,12 @@ If no `callback` is passed, a promise is returned. ```JavaScript ipfs.key.list((err, keys) => console.log(keys)) -{ - Keys: [ - { Name: 'self', - Id: 'QmRT6i9wXVSmxKi3MxVRduZqF3Wvv8DuV5utMXPN3BxPML' }, - { Name: 'my-key', - Id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg' } - ] -} +// [ +// { id: 'QmTe4tuceM2sAmuZiFsJ9tmAopA8au71NabBDdpPYDjxAb', +// name: 'self' }, +// { id: 'QmWETF5QvzGnP7jKq5sPDiRjSM2fzwzNsna4wSBEzRzK6W', +// name: 'my-key' } +// ] ``` #### `rm` @@ -73,7 +75,14 @@ ipfs.key.list((err, keys) => console.log(keys)) Where: - `name` is the local name for the key -`callback` must follow `function (err, key) {}` signature, where `err` is an Error if the operation was not successful. `key` is an object that describes the removed key. +`callback` must follow `function (err, key) {}` signature, where `err` is an Error if the operation was not successful. `key` is an object that describes the removed key: + +``` +{ + id: 'hash', // string - the hash of the key + name: 'self' // string - the name of the key +} +``` If no `callback` is passed, a promise is returned. @@ -82,12 +91,8 @@ If no `callback` is passed, a promise is returned. ```JavaScript ipfs.key.rm('my-key', (err, key) => console.log(key)) -{ - Keys: [ - { Name: 'my-key', - Id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg' } - ] -} +// { id: 'QmWETF5QvzGnP7jKq5sPDiRjSM2fzwzNsna4wSBEzRzK6W', +// name: 'my-key' } ``` #### `rename` @@ -109,17 +114,12 @@ If no `callback` is passed, a promise is returned. **Example:** ```JavaScript -ipfs.key.rename( - 'my-key', - 'my-new-key', - (err, key) => console.log(key)) - -{ - Was: 'my-key', - Now: 'my-new-key', - Id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg', - Overwrite: false -} +ipfs.key.rename('my-key', 'my-new-key', (err, key) => console.log(key)) + +// { id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg', +// was: 'my-key', +// now: 'my-new-key', +// overwrite: false } ``` #### `export` @@ -134,7 +134,7 @@ Where: - `name` is the local name for the key - `password` is the password to protect the key -`callback` must follow `function (err, pem) {}` signature, where `err` is an Error if the operation was not successful. `pem` is the string representation of the key +`callback` must follow `function (err, pem) {}` signature, where `err` is an Error if the operation was not successful. `pem` is the string representation of the key. If no `callback` is passed, a promise is returned. @@ -143,12 +143,11 @@ If no `callback` is passed, a promise is returned. ```JavaScript ipfs.key.export('self', 'password', (err, pem) => console.log(pem)) ------BEGIN ENCRYPTED PRIVATE KEY----- -MIIFDTA/BgkqhkiG9w0BBQ0wMjAaBgkqhkiG9w0BBQwwDQQIpdO40RVyBwACAWQw -... -YA== ------END ENCRYPTED PRIVATE KEY----- - +// -----BEGIN ENCRYPTED PRIVATE KEY----- +// MIIFDTA/BgkqhkiG9w0BBQ0wMjAaBgkqhkiG9w0BBQwwDQQIpdO40RVyBwACAWQw +// ... +// YA== +// -----END ENCRYPTED PRIVATE KEY----- ``` #### `import` @@ -173,7 +172,6 @@ If no `callback` is passed, a promise is returned. ```JavaScript ipfs.key.import('clone', 'password', (err, key) => console.log(key)) -{ Name: 'clone', - Id: 'QmQRiays958UM7norGRQUG3tmrLq8pJdmJarwYSk2eLthQ' -} +// { id: 'QmQRiays958UM7norGRQUG3tmrLq8pJdmJarwYSk2eLthQ', +// name: 'clone' } ``` diff --git a/SPEC/NAME.md b/SPEC/NAME.md index 050509a88..cf1a7ef3a 100644 --- a/SPEC/NAME.md +++ b/SPEC/NAME.md @@ -1,4 +1,4 @@ -name API +Name API ======== #### `publish` @@ -15,9 +15,10 @@ name API ```JavaScript { - resolve: // bool - Resolve given path before publishing. Default: true. + resolve: // bool - Resolve given path before publishing. Default: true lifetime: // string - Time duration of the record. Default: 24h - ttl: // string - Time duration this record should be cached + ttl: // string - Time duration this record should be cached + key: // string - Name of the key to be used or Peer ID. Default: 'self' } ``` @@ -32,19 +33,35 @@ name API If no `callback` is passed, a promise is returned. -Example: +**Example:** + +Imagine you want to publish your website under IPFS. You can use the [Files API](./FILES.md) to publish your static website and then you'll get a multihash you can link to. But when you need to make a change, a problem arises: you get a new multihash because you now have a different content. And it is not possible for you to be always giving others the new address. + +Here's where the Name API comes in handy. With it, you can use one static multihash for your website under IPNS (InterPlanetary Name Service). This way, you can have one single multihash poiting to the newest version of your website. ```JavaScript -// TODO +// The address of your files. +const addr = '/ipfs/QmbezGequPwcsWo8UL4wDF6a8hYwM1hmbzYv2mnKkEWaUp' + +ipfs.name.publish(addr, function (err, res) { + // You now receive a res which contains two fields: + // - name: the name under which the content was published. + // - value: the "real" address to which Name points. + console.log(`https://gateway.ipfs.io/ipns/${res.name}`) +}) ``` +This way, you can republish a new version of your website under the same address. By default, `ipfs.name.publish` will use the Peer ID. If you want to have multiple websites (for example) under the same IPFS module, you can always check the [key API](./KEY.md). + #### `resolve` > Resolve an IPNS name. ##### `Go` **WIP** -##### `JavaScript` - ipfs.name.resolve([options, callback]) +##### `JavaScript` - ipfs.name.resolve(value, [options, callback]) + +`value` is a IPNS address, such as: `/ipns/ipfs.io`. `options` is an object that may contain: @@ -55,19 +72,18 @@ Example: } ``` -`callback` must follow `function (err, name) {}` signature, where `err` is an error if the operation was not successful. `name` is an object that contains the IPNS hash and the IPFS hash, such as: - -```JavaScript -{ - name: "/ipns/QmHash.." - value: "/ipfs/QmHash.." -} -``` +`callback` must follow `function (err, name) {}` signature, where `err` is an error if the operation was not successful. `name` is a string that contains the IPFS hash. If no `callback` is passed, a promise is returned. -Example: +**Example:** ```JavaScript -// TODO +// The IPNS address you want to resolve. +const addr = '/ipns/ipfs.io' + +ipfs.name.resolve(addr, function (err, name) { + console.log(name) + // /ipfs/QmQrX8hka2BtNHa8N8arAq16TCVx5qHcb46c5yPewRycLm +}) ``` diff --git a/package.json b/package.json index 3f6d0a6a2..2235991ab 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "interface-ipfs-core", - "version": "0.37.0", + "version": "0.38.0", "description": "A test suite and interface you can use to implement a IPFS core interface.", "main": "src/index.js", "scripts": { @@ -51,11 +51,13 @@ }, "devDependencies": {}, "contributors": [ + "Alan Shaw ", "David Dias ", "Dmitriy Ryajov ", "Enrico Marino ", "Friedel Ziegelmayer ", "Haad ", + "Henrique Dias ", "Jason Papakostas ", "Kevin Simper ", "Marius Darila ", diff --git a/src/files.js b/src/files.js index 55a06fdee..417251566 100644 --- a/src/files.js +++ b/src/files.js @@ -97,10 +97,10 @@ module.exports = (common) => { }) it('a BIG buffer with progress enabled', (done) => { - let progCount = 0 + let progCalled = false let accumProgress = 0 function handler (p) { - progCount += 1 + progCalled = true accumProgress = p } @@ -112,7 +112,7 @@ module.exports = (common) => { expect(file.hash).to.equal(bigFile.cid) expect(file.path).to.equal(bigFile.cid) - expect(progCount).to.equal(58) + expect(progCalled).to.be.true() expect(accumProgress).to.equal(bigFile.data.length) done() }) @@ -223,10 +223,10 @@ module.exports = (common) => { return i + (entry.content ? entry.content.length : 0) }, 0) - let progCount = 0 + let progCalled = false let accumProgress = 0 const handler = (p) => { - progCount += 1 + progCalled = true accumProgress += p } @@ -234,7 +234,7 @@ module.exports = (common) => { expect(err).to.not.exist() const root = filesAdded[filesAdded.length - 1] - expect(progCount).to.equal(8) + expect(progCalled).to.be.true() expect(accumProgress).to.be.at.least(total) expect(root.path).to.equal('test-folder') expect(root.hash).to.equal(directory.cid) diff --git a/src/key.js b/src/key.js index 48daa2d7f..4e60f72e3 100644 --- a/src/key.js +++ b/src/key.js @@ -47,8 +47,8 @@ module.exports = (common) => { ipfs.key.gen(name, kt, (err, key) => { expect(err).to.not.exist() expect(key).to.exist() - expect(key).to.have.property('Name', name) - expect(key).to.have.property('Id') + expect(key).to.have.property('name', name) + expect(key).to.have.property('id') keys.push(key) done() }) @@ -62,16 +62,16 @@ module.exports = (common) => { ipfs.key.list((err, res) => { expect(err).to.not.exist() expect(res).to.exist() - expect(res.Keys).to.exist() - expect(res.Keys.length).to.be.above(keys.length - 1) - listedKeys = res.Keys + expect(res).to.be.an('array') + expect(res.length).to.be.above(keys.length - 1) + listedKeys = res done() }) }) it('contains the created keys', () => { keys.forEach(ki => { - const found = listedKeys.filter(lk => ki.Name === lk.Name && ki.Id === lk.Id) + const found = listedKeys.filter(lk => ki.name === lk.name && ki.id === lk.id) expect(found).to.have.length(1) }) }) @@ -82,7 +82,7 @@ module.exports = (common) => { let newName before(() => { - oldName = keys[0].Name + oldName = keys[0].name newName = 'x' + oldName }) @@ -90,10 +90,10 @@ module.exports = (common) => { ipfs.key.rename(oldName, newName, (err, res) => { expect(err).to.not.exist() expect(res).to.exist() - expect(res).to.have.property('Was', oldName) - expect(res).to.have.property('Now', newName) - expect(res).to.have.property('Id', keys[0].Id) - keys[0].Name = newName + expect(res).to.have.property('was', oldName) + expect(res).to.have.property('now', newName) + expect(res).to.have.property('id', keys[0].id) + keys[0].name = newName done() }) }) @@ -101,7 +101,7 @@ module.exports = (common) => { it('contains the new name', (done) => { ipfs.key.list((err, res) => { expect(err).to.not.exist() - const found = res.Keys.filter(k => k.Name === newName) + const found = res.filter(k => k.name === newName) expect(found).to.have.length(1) done() }) @@ -110,7 +110,7 @@ module.exports = (common) => { it('does not contain the old name', (done) => { ipfs.key.list((err, res) => { expect(err).to.not.exist() - const found = res.Keys.filter(k => k.Name === oldName) + const found = res.filter(k => k.name === oldName) expect(found).to.have.length(0) done() }) @@ -124,13 +124,11 @@ module.exports = (common) => { }) it('removes a key', function (done) { - ipfs.key.rm(key.Name, (err, res) => { + ipfs.key.rm(key.name, (err, res) => { expect(err).to.not.exist() expect(res).to.exist() - expect(res).to.have.property('Keys') - expect(res.Keys).to.have.length(1) - expect(res.Keys[0]).to.have.property('Name', key.Name) - expect(res.Keys[0]).to.have.property('Id', key.Id) + expect(res).to.have.property('name', key.name) + expect(res).to.have.property('id', key.id) done() }) }) @@ -138,7 +136,7 @@ module.exports = (common) => { it('does not contain the removed name', (done) => { ipfs.key.list((err, res) => { expect(err).to.not.exist() - const found = res.Keys.filter(k => k.Name === key.Name) + const found = res.filter(k => k.name === key.name) expect(found).to.have.length(0) done() }) @@ -170,8 +168,8 @@ module.exports = (common) => { ipfs.key.import('clone', selfPem, passwordPem, (err, key) => { expect(err).to.not.exist() expect(key).to.exist() - expect(key).to.have.property('Name', 'clone') - expect(key).to.have.property('Id') + expect(key).to.have.property('name', 'clone') + expect(key).to.have.property('id') done() }) })