Compute: add operation support. Add operation parameter to callbacks of methods wrapping an asynchronous API (in place of APIresponse).

Author: mziccard

lib/compute/address.js

@@ -69,11 +69,23 @@ function Address(region, name, metadata) {
  * @param {function} callback - The callback function.
  *
  * @example
- * address.delete(function(err) {});
+ * address.delete(function(err, operation) {
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of address deletion.
+ * });
  */
 Address.prototype.delete = function(callback) {
   callback = callback || util.noop;
-  this.makeReq_('DELETE', '', null, true, callback);
+  var region = this.region;
+  this.makeReq_('DELETE', '', null, true, function(err, resp) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    var operation = region.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, operation);
+  });
 };
 
 /**

lib/compute/disk.js

@@ -69,11 +69,23 @@ function Disk(zone, name, metadata) {
  * @param {function} callback - The callback function.
  *
  * @example
- * disk.delete(function(err) {});
+ * disk.delete(function(err, operation) {
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of disk deletion.
+ * });
  */
 Disk.prototype.delete = function(callback) {
   callback = callback || util.noop;
-  this.makeReq_('DELETE', '', null, true, callback);
+  var zone = this.zone;
+  this.makeReq_('DELETE', '', null, true, function(err, resp) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    var operation = zone.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, operation);
+  });
 };
 
 /**
@@ -106,8 +118,10 @@ Disk.prototype.getMetadata = function(callback) {
  * @param {function} callback - The callback function.
  *
  * @example
- * disk.createSnapshot('my-snapshot', function(err, snapshot, apiResponse) {
+ * disk.createSnapshot('my-snapshot', function(err, snapshot, operation) {
  *   // `snapshot` is a Snapshot object.
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of snapshot creation.
  * });
  */
 Disk.prototype.createSnapshot = function(options, callback) {
@@ -122,14 +136,16 @@ Disk.prototype.createSnapshot = function(options, callback) {
     throw new Error('Name must match [a-z]([-a-z0-9]{0,61}[a-z0-9])?');
   }
 
-  var compute = this.zone.compute;
+  var self = this;
   this.makeReq_('POST', '/createSnapshot', null, options, function(err, resp) {
     if (err) {
       callback(err);
       return;
     }
-    var snapshot = compute.snapshot(options.name);
-    callback(null, snapshot, resp);
+    var snapshot = self.zone.compute.snapshot(options.name);
+    var operation = self.zone.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, snapshot, operation);
   });
 };
 

lib/compute/firewall.js

@@ -77,11 +77,23 @@ function Firewall(compute, name, options) {
  * @param {function} callback - The callback function.
  *
  * @example
- * firewall.delete(function(err) {});
+ * firewall.delete(function(err, operation) {
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of firewall rule deletion.
+ * });
  */
 Firewall.prototype.delete = function(callback) {
   callback = callback || util.noop;
-  this.makeReq_('DELETE', '', null, true, callback);
+  var compute = this.compute;
+  this.makeReq_('DELETE', '', null, true, function(err, resp) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    var operation = compute.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, operation);
+  });
 };
 
 /**
@@ -128,8 +140,9 @@ Firewall.prototype.getMetadata = function(callback) {
  * @param {function} callback - The callback function.
  *
  * @example
- * var callback = function(err, apiResponse) {
- *   // ...
+ * var callback = function(err, operation) {
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of firewall rule update.
  * };
  *
  * firewall.setMetadata(
@@ -153,7 +166,9 @@ Firewall.prototype.setMetadata = function(metadata, callback) {
       return;
     }
     self.metadata = metadata;
-    callback(null, resp);
+    var operation = self.compute.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, operation);
   });
 };
 

lib/compute/index.js

@@ -52,6 +52,12 @@ var Snapshot = require('./snapshot.js');
  */
 var Network = require('./network.js');
 
+/**
+ * @type {module:compute/operation}
+ * @private
+ */
+var Operation = require('./operation.js');
+
 /**
  * @type {module:common/util}
  * @private
@@ -218,6 +224,25 @@ Compute.prototype.network = function(name) {
   return new Network(this, name);
 };
 
+/**
+ * Get a reference to a Google Compute Engine operation.
+ *
+ * @param {string} name - Name of the existing operation.
+ * @return {module:compute/operation}
+ *
+ * @example
+ * var gcloud = require('gcloud')({
+ *   keyFilename: '/path/to/keyfile.json'
+ * });
+ *
+ * var compute = gcloud.compute();
+ *
+ * var operation = compute.operation('operation-name');
+ */
+Compute.prototype.operation = function(name) {
+  return new Operation(this, name);
+};
+
 /**
  * Create a firewall rule. For a detailed description of method's options see
  * [API reference](https://goo.gl/kTMHep).
@@ -242,8 +267,10 @@ Compute.prototype.network = function(name) {
  * @param {function} callback - The callback function.
  *
  * @example
- * var callback = function(err, firewall, apiResponse) {
+ * var callback = function(err, firewall, operation) {
  *   // `firewall` is a Firewall object.
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of firewall rule creation.
  * };
  *
  * var compute = gcloud.compute({
@@ -298,7 +325,9 @@ Compute.prototype.createFirewall = function(name, options, callback) {
       }
       var firewall = self.firewall(name);
       firewall.metadata = options;
-      callback(null, firewall, resp);
+      var operation = self.operation(resp.name);
+      operation.metadata = resp;
+      callback(null, firewall, operation);
     });
 };
 
@@ -316,8 +345,10 @@ Compute.prototype.createFirewall = function(name, options, callback) {
  * @param {function} callback - The callback function.
  *
  * @example
- * var callback = function(err, network, apiResponse) {
+ * var callback = function(err, network, operation) {
  *   // `network` is a Network object.
+ *   // `operation` is an Operation object and can be used to check the status
+ *   // of network creation.
  * };
  *
  * var compute = gcloud.compute({
@@ -349,7 +380,9 @@ Compute.prototype.createNetwork = function(name, options, callback) {
     }
     var network = self.network(name);
     network.metadata = options;
-    callback(null, network, resp);
+    var operation = self.operation(resp.name);
+    operation.metadata = resp;
+    callback(null, network, operation);
   });
 };
 
@@ -943,6 +976,104 @@ Compute.prototype.getNetworks = function(options, callback) {
   });
 };
 
+/**
+ * Get a list of global operations. For a detailed description of method's
+ * options see [API reference](https://goo.gl/gX4C1u).
+ *
+ * @param {object} options - Operation search options.
+ * @param {boolean=} options.autoPaginate - Have pagination handled
+ *     automatically. Default: true.
+ * @param {number=} options.maxResults - Maximum number of operations to return.
+ * @param {string=} options.filter - Search filter. The filter must contain:
+ *     `FIELD_NAME COMPARISON_STRING LITERAL_STRING`. `FIELD_NAME` is the name
+ *     of the field to compare. `COMPARISON` is the comparison operator that can
+ *     be either `eq` or `ne`. `LITERAL_STRING` is the string to filter to.
+ *     For string fields `LITERAL_STRING` can be a regular expression.
+ * @param {string=} pageToken - Page identifier used in paginated search.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * var callback = function(err, operations) {
+ *   // `operations` is an array of `Operation` objects.
+ * };
+ *
+ * compute.getOperations(
+ *   {
+ *     filter: 'name eq operation-[0-9]'
+ *   }, callback);
+ *
+ * //-
+ * // To control how many API requests are made and page through the results
+ * // manually, set `autoPaginate` to `false`.
+ * //-
+ * var callback = function(err, operations, nextQuery, apiResponse) {
+ *   if (nextQuery) {
+ *     // More results exist.
+ *     compute.getOperations(nextQuery, callback);
+ *   }
+ * };
+ *
+ * compute.getOperations({
+ *   autoPaginate: false
+ * }, callback);
+ *
+ * //-
+ * // Get the operations from your project as a readable object stream.
+ * //-
+ * compute.getOperations()
+ *   .on('error', console.error)
+ *   .on('data', function(operation) {
+ *     // `operation` is a `Operation` object.
+ *   })
+ *   .on('end', function() {
+ *     // All operations retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * compute.getOperations()
+ *   .on('data', function(operation) {
+ *     this.end();
+ *   });
+ */
+Compute.prototype.getOperations = function(options, callback) {
+  if (util.is(options, 'function')) {
+    callback = options;
+    options = {};
+  }
+
+  options = options || {};
+
+  var self = this;
+  this.makeReq_(
+    'GET',
+    '/global/operations',
+    options,
+    null, function(err, resp) {
+      if (err) {
+        callback(err);
+        return;
+      }
+
+      var nextQuery = null;
+
+      if (resp.nextPageToken) {
+        nextQuery = extend({}, options, {
+          pageToken: resp.nextPageToken
+        });
+      }
+
+      var operations = (resp.items || []).map(function(operationObject) {
+        var operation = self.operation(operationObject.name);
+        operation.metadata = operationObject;
+        return operation;
+      });
+      callback(null, operations, nextQuery, resp);
+    });
+};
+
 /**
  * Make a new request object from the provided arguments and wrap the callback
  * to intercept non-successful responses.
@@ -980,7 +1111,8 @@ streamRouter.extend(Compute, [
   'getAddresses',
   'getSnapshots',
   'getFirewalls',
-  'getNetworks'
+  'getNetworks',
+  'getOperations'
 ]);
 
 module.exports = Compute;