machines/show.js

'use strict';

var method = require('./../method');
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
 * @returns {object} machine - The machine JSON object
 * @example
 * paperspace.machines.show({
 *   machineId: 'ps123abc',
 * }, function(err, res) {
 *   // handle error or result
 * });
 * @example
 * $ paperspace machines show \
 *     --machineId "ps123abc"
 * @example
 * # HTTP request:
 * https://api.paperspace.io
 * GET /machines/getMachinePublic?machineId=ps123abc
 * x-api-key: 1ba4f98e7c0...
 * # Returns 200 on success
 * @example
 * //Example return value:
 * {
 *   "id": "ps123abc",
 *   "name": "My Machine",
 *   "os": "Microsoft Windows Server 2016 Datacenter",
 *   "ram": "8589938688",
 *   "cpus": 4,
 *   "gpu": "GRID K160Q (2GB)",
 *   "storageTotal": "53687091200",
 *   "storageUsed": "110080",
 *   "usageRate": "Air monthly",
 *   "shutdownTimeoutInHours": 168,
 *   "shutdownTimeoutForces": false,
 *   "performAutoSnapshot": false,
 *   "autoSnapshotFrequency": null,
 *   "autoSnapshotSaveCount": null,
 *   "agentType": "WindowsDesktop",
 *   "dtCreated": "2016-11-18T05:18:29.533Z",
 *   "state": "ready",
 *   "updatesPending": false,
 *   "networkId": "n789ghi",
 *   "privateIpAddress": "10.64.21.47",
 *   "publicIpAddress": null,
 *   "region": "East Coast (NY2)",
 *   "userId": "u123abc",
 *   "teamId": "te456def",
 *   "scriptId": "sc123abc",
 *   "dtLastRun": "2017-06-30T07:22:49.763Z",
 *   "dynamicPublicIp": null,
 *   "events": [
 *     {
 *       "name": "start",
 *       "state": "done",
 *       "errorMsg": "",
 *       "handle": "8ebe43dd-57c8-4bd4-b770-86b7fd0202e4",
 *       "dtModified": "2017-08-16T14:36:24.802Z",
 *       "dtFinished": null,
 *       "dtCreated": "2017-08-16T14:36:18.373Z"
 *     },
 *     {
 *       "name": "start",
 *       "state": "error",
 *       "errorMsg": "Uh oh. This machine type can't start due to insufficient capacity or higher than normal demand. Please try again later.",
 *       "handle": "f6adb486-f5ae-4ab3-9a1a-51c19df5b337",
 *       "dtModified": "2017-06-09T15:32:38.115Z",
 *       "dtFinished": "2017-06-09T15:32:38.115Z",
 *       "dtCreated": "2017-06-09T15:32:37.019Z"
 *     },
 *     {
 *       "name": "stop",
 *       "state": "done",
 *       "errorMsg": "",
 *       "handle": "e352ad96-734f-4a26-8829-007c2f1d89f2",
 *       "dtModified": "2017-06-03T04:14:01.327Z",
 *       "dtFinished": null,
 *       "dtCreated": "2017-06-03T04:13:47.885Z"
 *     }
 *   ]
 * }
 */

function show(params, cb) {
	return method(show, params, cb);
}

assign(show, {
	auth: true,
	group: 'machines',
	name: 'show',
	method: 'get',
	route: '/machines/getMachinePublic',
	requires: {
		machineId: 'string',
	},
	returns: {},
});

module.exports = show;