From 9f12c26d44a0d78f28af25056857b993f80bbd95 Mon Sep 17 00:00:00 2001 From: Dan Date: Thu, 19 Apr 2018 13:08:56 -0230 Subject: Even more documentation for various controllers and libs. --- app/scripts/lib/message-manager.js | 145 ++++++++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 4 deletions(-) (limited to 'app/scripts/lib/message-manager.js') diff --git a/app/scripts/lib/message-manager.js b/app/scripts/lib/message-manager.js index f52e048e0..52b897720 100644 --- a/app/scripts/lib/message-manager.js +++ b/app/scripts/lib/message-manager.js @@ -3,8 +3,45 @@ const ObservableStore = require('obs-store') const ethUtil = require('ethereumjs-util') const createId = require('./random-id') +var msgData = { + id: msgId, + msgParams: msgParams, + time: time, + status: 'unapproved', + type: 'eth_sign', +} + +/** + * Represents, and contains data about, an 'eth_sign' type signature request. These are created when a signature for + * an eth_sign call is requested. + * + * @see {@link https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign} + * + * @typedef {Object} Message + * @property {number} id An id to track and identify the message object + * @property {object} msgParams The parameters to pass to the eth_sign method once the signature request is approved. + * @property {object} msgParams.metamaskId Added to msgParams for tracking and identification within Metamask. + * @property {string} msgParams.data A hex string conversion of the raw buffer data of the signature request + * @property {number} time The epoch time at which the this message was created + * @property {string} status Indicates whether the signature request is 'unapproved', 'approved', 'signed' or 'rejected' + * @property {string} type The json-prc signing method for which a signature request has been made. A 'Message' with + * always have a 'eth_sign' type. + * + */ module.exports = class MessageManager extends EventEmitter { + + /** + * Controller in charge of managing - storing, adding, removing, updating - Messages. + * + * @typedef {Object} MessageManager + * @param {object} opts @deprecated + * @property {object} memStore The observable store where Messages are saved with persistance. + * @property {object} memStore.unapprovedMsgs A collection of all Messages in the 'unapproved' state + * @property {number} memStore.unapprovedMsgCount The count of all Messages in this.memStore.unapprobedMsgs + * @property {array} messages Holds all messages that have been created by this MessageManager + * + */ constructor (opts) { super() this.memStore = new ObservableStore({ @@ -14,15 +51,35 @@ module.exports = class MessageManager extends EventEmitter { this.messages = [] } + /** + * A getter for the number of 'unapproved' Messages in this.messages + * + * @returns {number} The number of 'unapproved' Messages in this.messages + * + */ get unapprovedMsgCount () { return Object.keys(this.getUnapprovedMsgs()).length } + /** + * A getter for the 'unapproved' Messages in this.messages + * + * @returns {object} An index of Message ids to Messages, for all 'unapproved' Messages in this.messages + * + */ getUnapprovedMsgs () { return this.messages.filter(msg => msg.status === 'unapproved') .reduce((result, msg) => { result[msg.id] = msg; return result }, {}) } + /** + * Creates a new Message with an 'unapproved' status using the passed msgParams. this.addMsg is called to add the + * new Message to this.messages, and to save the unapproved Messages from that list to this.memStore. + * + * @param {object} msgParams The params for the eth_sign call to be made after the message is approved. + * @returns {number} The id of the newly created message. + * + */ addUnapprovedMessage (msgParams) { msgParams.data = normalizeMsgData(msgParams.data) // create txData obj with parameters and meta data @@ -42,24 +99,61 @@ module.exports = class MessageManager extends EventEmitter { return msgId } + /** + * Adds a passed Message to this.messages, and calls this._saveMsgList() to save the unapproved Messages from that + * list to this.memStore. + * + * @param {Message} msg The Message to add to this.messages + * + */ addMsg (msg) { this.messages.push(msg) this._saveMsgList() } + /** + * Returns a specified Message. + * + * @param {number} msgId The id of the Message to get + * @returns {Message|undefined} The Message with the id that matches the passed msgId, or undefined if no Message has that id. + * + */ getMsg (msgId) { return this.messages.find(msg => msg.id === msgId) } + /** + * Approves a Message. Sets the message status via a call to this.setMsgStatusApproved, and returns a promise with + * any the message params modified for proper signing. + * + * @param {object} msgParams The msgParams to be used when eth_sign is called, plus data added by Metamask. + * @param {object} msgParams.metamaskId Added to msgParams for tracking and identification within Metamask. + * @returns {Promise} Promises the msgParams object with metamaskId removed. + * + */ approveMessage (msgParams) { this.setMsgStatusApproved(msgParams.metamaskId) return this.prepMsgForSigning(msgParams) } + /** + * Sets a Message status to 'approved' via a call to this._setMsgStatus. + * + * @param {number} msgId The id of the Message to approve. + * + */ setMsgStatusApproved (msgId) { this._setMsgStatus(msgId, 'approved') } + /** + * Sets a Message status to 'signed' via a call to this._setMsgStatus and updates that Message in this.messages by + * adding the raw signature data of the signature request to the Message + * + * @param {number} msgId The id of the Message to sign. + * @param {buffer} rawSig The raw data of the signature request + * + */ setMsgStatusSigned (msgId, rawSig) { const msg = this.getMsg(msgId) msg.rawSig = rawSig @@ -67,19 +161,40 @@ module.exports = class MessageManager extends EventEmitter { this._setMsgStatus(msgId, 'signed') } + /** + * Removes the metamaskId property from passed msgParams and returns a promise which resolves the updated msgParams + * + * @param {object} msgParams The msgParams to modify + * @returns {Promise} Promises the msgParams with the metamaskId property removed + * + */ prepMsgForSigning (msgParams) { delete msgParams.metamaskId return Promise.resolve(msgParams) } + /** + * Sets a Message status to 'rejected' via a call to this._setMsgStatus. + * + * @param {number} msgId The id of the Message to reject. + * + */ rejectMsg (msgId) { this._setMsgStatus(msgId, 'rejected') } - // - // PRIVATE METHODS - // - + /** + * Updates the status of a Message in this.messages via a call to this._updateMsg + * + * @private + * @param {number} msgId The id of the Message to update. + * @param {string} status The new status of the Message. + * @throws A 'MessageManager - Message not found for id: "${msgId}".' if there is no Message in this.messages with an + * id equal to the passed msgId + * @fires An event with a name equal to `${msgId}:${status}`. The Message is also fired. + * @fires If status is 'rejected' or 'signed', an event with a name equal to `${msgId}:finished` is fired along with the message + * + */ _setMsgStatus (msgId, status) { const msg = this.getMsg(msgId) if (!msg) throw new Error('MessageManager - Message not found for id: "${msgId}".') @@ -91,6 +206,14 @@ module.exports = class MessageManager extends EventEmitter { } } + /** + * Sets a Message in this.messages to the passed Message if the ids are equal. Then saves the unapprovedMsg list to + * storage via this._saveMsgList + * + * @private + * @param {msg} Message A Message that will replace an existing Message (with the same id) in this.messages + * + */ _updateMsg (msg) { const index = this.messages.findIndex((message) => message.id === msg.id) if (index !== -1) { @@ -99,6 +222,13 @@ module.exports = class MessageManager extends EventEmitter { this._saveMsgList() } + /** + * Saves the unapproved messages, and their count, to this.memStore + * + * @private + * @fires 'updateBadge' + * + */ _saveMsgList () { const unapprovedMsgs = this.getUnapprovedMsgs() const unapprovedMsgCount = Object.keys(unapprovedMsgs).length @@ -108,6 +238,13 @@ module.exports = class MessageManager extends EventEmitter { } +/** + * A helper function that converts raw buffer data to a hex, or just returns the data if it is already formatted as a hex. + * + * @param {any} data The buffer data to convert to a hex + * @returns {string} A hex string conversion of the buffer data + * + */ function normalizeMsgData (data) { if (data.slice(0, 2) === '0x') { // data is already hex -- cgit v1.2.3 From 69920045e9d2392b01041532a3dfe7f33493a594 Mon Sep 17 00:00:00 2001 From: Dan Date: Fri, 20 Apr 2018 15:48:58 -0230 Subject: Minor fixes in a number of docs. --- app/scripts/lib/message-manager.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'app/scripts/lib/message-manager.js') diff --git a/app/scripts/lib/message-manager.js b/app/scripts/lib/message-manager.js index 52b897720..0756dbaed 100644 --- a/app/scripts/lib/message-manager.js +++ b/app/scripts/lib/message-manager.js @@ -20,7 +20,7 @@ var msgData = { * @typedef {Object} Message * @property {number} id An id to track and identify the message object * @property {object} msgParams The parameters to pass to the eth_sign method once the signature request is approved. - * @property {object} msgParams.metamaskId Added to msgParams for tracking and identification within Metamask. + * @property {object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. * @property {string} msgParams.data A hex string conversion of the raw buffer data of the signature request * @property {number} time The epoch time at which the this message was created * @property {string} status Indicates whether the signature request is 'unapproved', 'approved', 'signed' or 'rejected' @@ -36,7 +36,7 @@ module.exports = class MessageManager extends EventEmitter { * * @typedef {Object} MessageManager * @param {object} opts @deprecated - * @property {object} memStore The observable store where Messages are saved with persistance. + * @property {object} memStore The observable store where Messages are saved. * @property {object} memStore.unapprovedMsgs A collection of all Messages in the 'unapproved' state * @property {number} memStore.unapprovedMsgCount The count of all Messages in this.memStore.unapprobedMsgs * @property {array} messages Holds all messages that have been created by this MessageManager @@ -126,8 +126,8 @@ module.exports = class MessageManager extends EventEmitter { * Approves a Message. Sets the message status via a call to this.setMsgStatusApproved, and returns a promise with * any the message params modified for proper signing. * - * @param {object} msgParams The msgParams to be used when eth_sign is called, plus data added by Metamask. - * @param {object} msgParams.metamaskId Added to msgParams for tracking and identification within Metamask. + * @param {object} msgParams The msgParams to be used when eth_sign is called, plus data added by MetaMask. + * @param {object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. * @returns {Promise} Promises the msgParams object with metamaskId removed. * */ -- cgit v1.2.3 From 0c26df965330a7ad63d4b41bdacb37b1d1b9a673 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 23 Apr 2018 14:11:02 -0230 Subject: Fix nits. --- app/scripts/lib/message-manager.js | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'app/scripts/lib/message-manager.js') diff --git a/app/scripts/lib/message-manager.js b/app/scripts/lib/message-manager.js index 0756dbaed..a1c6d6ac8 100644 --- a/app/scripts/lib/message-manager.js +++ b/app/scripts/lib/message-manager.js @@ -19,8 +19,8 @@ var msgData = { * * @typedef {Object} Message * @property {number} id An id to track and identify the message object - * @property {object} msgParams The parameters to pass to the eth_sign method once the signature request is approved. - * @property {object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. + * @property {Object} msgParams The parameters to pass to the eth_sign method once the signature request is approved. + * @property {Object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. * @property {string} msgParams.data A hex string conversion of the raw buffer data of the signature request * @property {number} time The epoch time at which the this message was created * @property {string} status Indicates whether the signature request is 'unapproved', 'approved', 'signed' or 'rejected' @@ -35,9 +35,9 @@ module.exports = class MessageManager extends EventEmitter { * Controller in charge of managing - storing, adding, removing, updating - Messages. * * @typedef {Object} MessageManager - * @param {object} opts @deprecated - * @property {object} memStore The observable store where Messages are saved. - * @property {object} memStore.unapprovedMsgs A collection of all Messages in the 'unapproved' state + * @param {Object} opts @deprecated + * @property {Object} memStore The observable store where Messages are saved. + * @property {Object} memStore.unapprovedMsgs A collection of all Messages in the 'unapproved' state * @property {number} memStore.unapprovedMsgCount The count of all Messages in this.memStore.unapprobedMsgs * @property {array} messages Holds all messages that have been created by this MessageManager * @@ -64,7 +64,7 @@ module.exports = class MessageManager extends EventEmitter { /** * A getter for the 'unapproved' Messages in this.messages * - * @returns {object} An index of Message ids to Messages, for all 'unapproved' Messages in this.messages + * @returns {Object} An index of Message ids to Messages, for all 'unapproved' Messages in this.messages * */ getUnapprovedMsgs () { @@ -76,7 +76,7 @@ module.exports = class MessageManager extends EventEmitter { * Creates a new Message with an 'unapproved' status using the passed msgParams. this.addMsg is called to add the * new Message to this.messages, and to save the unapproved Messages from that list to this.memStore. * - * @param {object} msgParams The params for the eth_sign call to be made after the message is approved. + * @param {Object} msgParams The params for the eth_sign call to be made after the message is approved. * @returns {number} The id of the newly created message. * */ @@ -126,8 +126,8 @@ module.exports = class MessageManager extends EventEmitter { * Approves a Message. Sets the message status via a call to this.setMsgStatusApproved, and returns a promise with * any the message params modified for proper signing. * - * @param {object} msgParams The msgParams to be used when eth_sign is called, plus data added by MetaMask. - * @param {object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. + * @param {Object} msgParams The msgParams to be used when eth_sign is called, plus data added by MetaMask. + * @param {Object} msgParams.metamaskId Added to msgParams for tracking and identification within MetaMask. * @returns {Promise} Promises the msgParams object with metamaskId removed. * */ @@ -164,7 +164,7 @@ module.exports = class MessageManager extends EventEmitter { /** * Removes the metamaskId property from passed msgParams and returns a promise which resolves the updated msgParams * - * @param {object} msgParams The msgParams to modify + * @param {Object} msgParams The msgParams to modify * @returns {Promise} Promises the msgParams with the metamaskId property removed * */ -- cgit v1.2.3 From 020824f3c79c8c7a17f827b47ff9e54338d2b34a Mon Sep 17 00:00:00 2001 From: Dan Date: Tue, 24 Apr 2018 12:36:26 -0230 Subject: Remove accidentally added code in message-manager. --- app/scripts/lib/message-manager.js | 8 -------- 1 file changed, 8 deletions(-) (limited to 'app/scripts/lib/message-manager.js') diff --git a/app/scripts/lib/message-manager.js b/app/scripts/lib/message-manager.js index a1c6d6ac8..901367f04 100644 --- a/app/scripts/lib/message-manager.js +++ b/app/scripts/lib/message-manager.js @@ -3,14 +3,6 @@ const ObservableStore = require('obs-store') const ethUtil = require('ethereumjs-util') const createId = require('./random-id') -var msgData = { - id: msgId, - msgParams: msgParams, - time: time, - status: 'unapproved', - type: 'eth_sign', -} - /** * Represents, and contains data about, an 'eth_sign' type signature request. These are created when a signature for * an eth_sign call is requested. -- cgit v1.2.3