From c09d77fcbf3d819146b9b330ce531571062e58b2 Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Tue, 22 May 2018 23:28:11 +0100 Subject: [PATCH 1/2] docs: add missing ping spec License: MIT Signed-off-by: Alan Shaw --- SPEC/MISCELLANEOUS.md | 139 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/SPEC/MISCELLANEOUS.md b/SPEC/MISCELLANEOUS.md index df9be32d6..b0b924159 100644 --- a/SPEC/MISCELLANEOUS.md +++ b/SPEC/MISCELLANEOUS.md @@ -4,6 +4,9 @@ * [version](#version) * [dns](#dns) * [stop](#stop) +* [ping](#ping) +* [pingPullStream](#pingpullstream) +* [pingReadableStream](#pingreadablestream) #### `id` @@ -105,4 +108,140 @@ ipfs.stop((err) => { A great source of [examples][] can be found in the tests for this API. +#### `ping` + +> Send echo request packets to IPFS hosts + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.ping(peerId, [options], [callback]) + +Where: + +- `peerId` (string) ID of the peer to be pinged. +- `options` is an optional object argument that might include the following properties: + - `count` (integer, default 10): the number of ping messages to send +- `callback` must follow `function (err, responses) {}` signature, where `err` is an error if the operation was not successful. `responses` is an Array of ping response objects of the form: + + ```js + { + success: true, + time: 1234, + text: '' + } + ``` + + Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. + + If no `callback` is passed, a promise is returned. + +**Example:** + +```JavaScript +ipfs.ping('Qmhash', function (err, responses) { + if (err) { + throw err + } + + responses.forEach((res) => { + if (res.time) { + console.log(`Pong received: time=${res.time} ms`) + } else { + console.log(res.text) + } + }) +}) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `pingPullStream` + +> Stream echo request packets to IPFS hosts + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.pingPullStream(peerId, [options], [callback]) + +Where: + +- `peerId` (string) ID of the peer to be pinged. +- `options` is an optional object argument that might include the following properties: + - `count` (integer, default 10): the number of ping messages to send + +Returns a [`PullStream`][ps] of ping response objects of the form: + +```js +{ + success: true, + time: 1234, + text: '' +} +``` + +Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. + +**Example:** + +```JavaScript +const pull = require('pull-stream') + +pull( + ipfs.pingPullStream('Qmhash'), + pull.drain((res) => { + if (res.time) { + console.log(`Pong received: time=${res.time} ms`) + } else { + console.log(res.text) + } + }) +) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `pingReadableStream` + +> Stream echo request packets to IPFS hosts + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.pingReadableStream(peerId, [options], [callback]) + +Where: + +- `peerId` (string) ID of the peer to be pinged. +- `options` is an optional object argument that might include the following properties: + - `count` (integer, default 10): the number of ping messages to send + +Returns a [`ReadableStream`][rs] of ping response objects of the form: + +```js +{ + success: true, + time: 1234, + text: '' +} +``` + +Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. + +**Example:** + +```JavaScript +const stream = ipfs.pingReadableStream('Qmhash') + +stream.on('data', (res) => { + if (res.time) { + console.log(`Pong received: time=${res.time} ms`) + } else { + console.log(res.text) + } +}) +``` + +A great source of [examples][] can be found in the tests for this API. + [examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/js/src/miscellaneous.js +[rs]: https://www.npmjs.com/package/readable-stream +[ps]: https://www.npmjs.com/package/pull-stream From 29f4e845c6167e773fd7113cffc068202b3ef69a Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Thu, 24 May 2018 20:02:01 +0100 Subject: [PATCH 2/2] docs: fixes definition of pong License: MIT Signed-off-by: Alan Shaw --- SPEC/MISCELLANEOUS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/SPEC/MISCELLANEOUS.md b/SPEC/MISCELLANEOUS.md index b0b924159..03cd145a0 100644 --- a/SPEC/MISCELLANEOUS.md +++ b/SPEC/MISCELLANEOUS.md @@ -131,7 +131,7 @@ Where: } ``` - Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. + Note that not all ping response objects are "pongs". A "pong" message can be identified by a truthy `success` property and an empty `text` property. Other ping responses are failures or status updates. If no `callback` is passed, a promise is returned. @@ -179,7 +179,7 @@ Returns a [`PullStream`][ps] of ping response objects of the form: } ``` -Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. +Note that not all ping response objects are "pongs". A "pong" message can be identified by a truthy `success` property and an empty `text` property. Other ping responses are failures or status updates. **Example:** @@ -224,7 +224,7 @@ Returns a [`ReadableStream`][rs] of ping response objects of the form: } ``` -Note that ping response objects aren't all "pongs". A "pong" message can be identified by a truthy `success` property and a `time` property greater than 0. Other ping responses are failures or status updates. +Note that not all ping response objects are "pongs". A "pong" message can be identified by a truthy `success` property and an empty `text` property. Other ping responses are failures or status updates. **Example:**