add additional machines states to machines show, list, create, and waitfor methods

Author: sanfilip

lib/machines/create.js

@@ -99,6 +99,7 @@ var assign = require('lodash.assign');
  *   "agentType": "WindowsDesktop",
  *   "dtCreated": "2017-02-16T20:26:54.880Z",
  *   "state": "provisioning",
+ *   "updatesPending": false,
  *   "networkId": null,
  *   "privateIpAddress": null,
  *   "publicIpAddress": "169.255.255.254",

lib/machines/list.js

@@ -26,6 +26,7 @@ var assign = require('lodash.assign');
  * @param {string} [filter.agentType] - Optional agentType value to match on
  * @param {string} [filter.dtCreated] - Optional datetime created value to match on
  * @param {string} [filter.state] - Optional state value to match on
+ * @param {boolean} [filter.updatesPending] - Optional updatesPending value to match on
  * @param {string} [filter.networkId] - Optional networkId to match on
  * @param {string} [filter.privateIpAddress] - Optional privateIpAddress to match on
  * @param {string} [filter.publicIpAddress] - Optional publicIpAddress to match on
@@ -69,6 +70,7 @@ var assign = require('lodash.assign');
  *     "agentType": "WindowsDesktop",
  *     "dtCreated": "2016-11-18T05:18:29.533Z",
  *     "state": "ready",
+ *     "updatesPending": false,
  *     "networkId": "n789ghi",
  *     "privateIpAddress": "10.64.21.47",
  *     "publicIpAddress": null,

lib/machines/show.js

@@ -7,6 +7,23 @@ var assign = require('lodash.assign');
  * @memberof machines
  * @method show
  * @description Show machine information for the machine with the given id.
+ *
+ * The state property can take on the follow values:
+ *   - off
+ *   - starting  - machine is in the process of changing to the ready or serviceready state
+ *   - stopping  - machine is in the process of changing to the off state
+ *   - restarting  - combines stopping follow immediately by starting
+ *   - serviceready  - services are running on the machine but the Paperspace agent is not yet available
+ *   - ready  - services are running on machine and the Paperspace agent is ready to stream or accept logins
+ *   - upgrading   - the machine specification are being upgraded, which involves a shutdown and startup sequence
+ *   - provisioning  - the machine is in the process of being created for the first time
+ *
+ * The updatesPending property is either true or false and reflects whether the operating system has scheduled updates
+ * for the next machine state transition, e.g, stopping, starting, restarting or upgrading.
+ *
+ * Note: in some cases the operating system can force installation of critical updates immediately upon a state
+ * transition, or automatically restart a machine to install updates.  In such cases the updatesPending property
+ * may not always be set accurately by the underlying os.
  * @param {object} params - Machine show parameters
  * @param {string} params.machineId - Id of the machine to show
  * @param {function} cb - Node-style error-first callback function
@@ -46,6 +63,7 @@ var assign = require('lodash.assign');
  *   "agentType": "WindowsDesktop",
  *   "dtCreated": "2016-11-18T05:18:29.533Z",
  *   "state": "ready",
+ *   "updatesPending": false,
  *   "networkId": "n789ghi",
  *   "privateIpAddress": "10.64.21.47",
  *   "publicIpAddress": null,

lib/machines/waitfor.js

@@ -8,14 +8,15 @@ var assign = require('lodash.assign');
  * @method waitfor
  * @description Wait for the machine with the given id to enter a certain machine
  * state. This action polls the server and returns only when we detect that the machine
- * has transitioned into the given state. States available are:
+ * has transitioned into the given state. States available to check for are:
  *   - off
- *   - ready
+ *   - serviceready  - services are running on the machine but the Paperspace agent is not yet available
+ *   - ready  - services are running on machine and the Paperspace agent is ready to stream or accept logins
  *
  * When the callback is called, the returned object will be information about the machine.
  * @param {object} params - Machine waitfor parameters
  * @param {string} params.machineId - Id of the machine to wait for
- * @param {string} params.state - Name of the state to wait for
+ * @param {string} params.state - Name of the state to wait for, either 'off', 'serviceready', 'ready'
  * @param {function} cb - Node-style error-first callback function
  * @returns {object} machine - The machine JSON object
  * @example
@@ -53,6 +54,7 @@ var assign = require('lodash.assign');
  *   "agentType": "WindowsDesktop",
  *   "dtCreated": "2016-11-18T05:18:29.533Z",
  *   "state": "ready",
+ *   "updatesPending": false,
  *   "networkId": "n789ghi",
  *   "privateIpAddress": "10.64.21.47",
  *   "publicIpAddress": null,
@@ -74,11 +76,12 @@ function waitfor(params, cb) {
 	var targetState;
 	switch (state) {
 		case 'ready':
+		case 'serviceready':
 		case 'off':
 			targetState = state;
 			break;
 		default:
-			return cb(new Error('state must be either off or ready'));
+			return cb(new Error('state must be either off, serviceready, or ready'));
 	}
 	return method(waitfor, params, function _cb(err, machine) {
 		if (err) {