From fab6d32f6958162723f752496a3c1ed6845cc53e Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Tue, 19 Jun 2018 11:33:34 -0700 Subject: [PATCH 1/4] Separate MFS from other files APIs. This is in line with how the TOC is written on https://github.com/ipfs/js-ipfs-api/blob/master/README.md and makes it much clearer which APIs are for MFS. --- SPEC/FILES.md | 250 +++++++++++++++++++++++++------------------------- 1 file changed, 126 insertions(+), 124 deletions(-) diff --git a/SPEC/FILES.md b/SPEC/FILES.md index 7427701de..ec1fc84cd 100644 --- a/SPEC/FILES.md +++ b/SPEC/FILES.md @@ -2,29 +2,132 @@ > The files API enables users to use the File System abstraction of IPFS. -* [files.add](#filesadd) -* [files.addReadableStream](#filesaddreadablestream) -* [files.addPullStream](#filesaddpullstream) -* [files.cat](#filescat) -* [files.catReadableStream](#filescatreadablestream) -* [files.catPullStream](#filescatpullstream) -* [files.get](#filesget) -* [files.getReadableStream](#filesgetreadablestream) -* [files.getPullStream](#filesgetpullstream) -* [ls](#ls) -* [lsReadableStream](#lsreadablestream) -* [lsPullStream](#lspullstream) -* [files.cp](#filescp) -* [files.mkdir](#filesmkdir) -* [files.stat](#filesstat) -* [files.rm](#filesrm) -* [files.read](#filesread) -* [files.readReadableStream](#filesreadreadablestream) -* [files.readPullStream](#filesreadpullstream) -* [files.write](#fileswrite) -* [files.mv](#filesmv) -* [files.flush](#filesflush) -* [files.ls](#filesls) +- [ls](#ls) +- [lsReadableStream](#lsreadablestream) +- [lsPullStream](#lspullstream) +- files + - [files.add](#filesadd) + - [files.addReadableStream](#filesaddreadablestream) + - [files.addPullStream](#filesaddpullstream) + - [files.cat](#filescat) + - [files.catReadableStream](#filescatreadablestream) + - [files.catPullStream](#filescatpullstream) + - [files.get](#filesget) + - [files.getReadableStream](#filesgetreadablestream) + - [files.getPullStream](#filesgetpullstream) + - MFS (mutable file system) + - [files.cp](#filescp) + - [files.flush](#filesflush) + - [files.ls](#filesls) + - [files.mkdir](#filesmkdir) + - [files.mv](#filesmv) + - [files.read](#filesread) + - [files.readPullStream](#filesreadpullstream) + - [files.readReadableStream](#filesreadreadablestream) + - [files.rm](#filesrm) + - [files.stat](#filesstat) + - [files.write](#fileswrite) + +#### `ls` + +> Lists a directory from IPFS that is addressed by a valid IPFS Path. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.ls(ipfsPath, [callback]) + +> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. + +ipfsPath can be of type: + +- [`cid`][cid] of type: + - [Buffer][b], the raw Buffer of the cid + - String, the base58 encoded version of the cid +- String, including the ipfs handler, a cid and a path to traverse to, ie: + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + +`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form: + +```js +{ + depth: 1, + name: 'alice.txt', + path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', + size: 11696, + hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', + type: 'file' +} +``` + +If no `callback` is passed, a promise is returned. + +**Example:** + +```JavaScript +const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' + +ipfs.ls(validCID, function (err, files) { + files.forEach((file) => { + console.log(file.path) + }) +}) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `lsReadableStream` + +> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs] + +> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. + +ipfsPath can be of type: + +- [`cid`][cid] of type: + - [Buffer][b], the raw Buffer of the cid + - String, the base58 encoded version of the cid +- String, including the ipfs handler, a cid and a path to traverse to, ie: + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + +It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form: + +```js +{ + depth: 1, + name: 'alice.txt', + path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', + size: 11696, + hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', + type: 'file' +} +``` + +**Example:** + +```JavaScript +const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' + +const stream = ipfs.lsReadableStream(validCID) + +stream.on('data', (file) => { + // write the file's path and contents to standard out + console.log(file.path) +}) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `lsPullStream` + +> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream. #### `files.add` @@ -435,107 +538,6 @@ pull( A great source of [examples][] can be found in the tests for this API. -#### `ls` - -> Lists a directory from IPFS that is addressed by a valid IPFS Path. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.ls(ipfsPath, [callback]) - -> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. - -ipfsPath can be of type: - -- [`cid`][cid] of type: - - [Buffer][b], the raw Buffer of the cid - - String, the base58 encoded version of the cid -- String, including the ipfs handler, a cid and a path to traverse to, ie: - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - -`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form: - -```js -{ - depth: 1, - name: 'alice.txt', - path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', - size: 11696, - hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', - type: 'file' -} -``` - -If no `callback` is passed, a promise is returned. - -**Example:** - -```JavaScript -const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' - -ipfs.ls(validCID, function (err, files) { - files.forEach((file) => { - console.log(file.path) - }) -}) -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `lsReadableStream` - -> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs] - -> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. - -ipfsPath can be of type: - -- [`cid`][cid] of type: - - [Buffer][b], the raw Buffer of the cid - - String, the base58 encoded version of the cid -- String, including the ipfs handler, a cid and a path to traverse to, ie: - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - -It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form: - -```js -{ - depth: 1, - name: 'alice.txt', - path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', - size: 11696, - hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', - type: 'file' -} -``` - -**Example:** - -```JavaScript -const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' - -const stream = ipfs.lsReadableStream(validCID) - -stream.on('data', (file) => { - // write the file's path and contents to standard out - console.log(file.path) -}) -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `lsPullStream` - -> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream. - ##### `Go` **WIP** ##### `JavaScript` - ipfs.lsPullStream(ipfsPath) -> [Pull Stream][ps] From 588644513a503b1431a0fe17cceed6c24159ab0d Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Tue, 19 Jun 2018 22:16:17 +0100 Subject: [PATCH 2/4] fix: increase bitswap setup timeout for CI License: MIT Signed-off-by: Alan Shaw --- js/src/bitswap.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/src/bitswap.js b/js/src/bitswap.js index 51a6c00a2..46febe6d7 100644 --- a/js/src/bitswap.js +++ b/js/src/bitswap.js @@ -21,7 +21,7 @@ module.exports = (common) => { before(function (done) { // CI takes longer to instantiate the daemon, so we need to increase the // timeout for the before step - this.timeout(60 * 250) + this.timeout(60 * 1000) common.setup((err, factory) => { expect(err).to.not.exist() From 68e7bd8c93dac74fce651253dc170036f42f7ddf Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Tue, 19 Jun 2018 22:42:58 +0100 Subject: [PATCH 3/4] chore: update contributors --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index bbd00fb15..e6a09628e 100644 --- a/package.json +++ b/package.json @@ -75,6 +75,7 @@ "Matt Zumwalt ", "Michael Garvin ", "Michael Muré ", + "Mikeal Rogers ", "Nicolás Santángelo ", "Oli Evans ", "Pedro Teixeira ", From 66c0efd5fe24babaf99563c615736e46b4a7f03b Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Tue, 19 Jun 2018 22:42:58 +0100 Subject: [PATCH 4/4] chore: release version v0.68.2 --- CHANGELOG.md | 10 ++++++++++ package.json | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5cd6b86d..98ada02ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,13 @@ + +## [0.68.2](https://github.com/ipfs/interface-ipfs-core/compare/v0.68.1...v0.68.2) (2018-06-19) + + +### Bug Fixes + +* increase bitswap setup timeout for CI ([5886445](https://github.com/ipfs/interface-ipfs-core/commit/5886445)) + + + ## [0.68.1](https://github.com/ipfs/interface-ipfs-core/compare/v0.68.0...v0.68.1) (2018-06-18) diff --git a/package.json b/package.json index e6a09628e..2ac06d07b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "interface-ipfs-core", - "version": "0.68.1", + "version": "0.68.2", "description": "A test suite and interface you can use to implement a IPFS core interface.", "leadMaintainer": "Alan Shaw ", "main": "js/src/index.js",