Compute: add Network support, minor fixes to docs

Author: mziccard

lib/compute/index.js

@@ -46,6 +46,12 @@ var Firewall = require('./firewall.js');
  */
 var Snapshot = require('./snapshot.js');
 
+/**
+ * @type {module:compute/firewall}
+ * @private
+ */
+var Network = require('./network.js');
+
 /**
  * @type {module:common/util}
  * @private
@@ -193,20 +199,37 @@ Compute.prototype.snapshot = function(name) {
   return new Snapshot(this, name);
 };
 
+/**
+ * Get a reference to a Google Compute Engine network.
+ *
+ * @param {string} name - Name of the existing network.
+ * @return {module:compute/network}
+ *
+ * @example
+ * var gcloud = require('gcloud')({
+ *   keyFilename: '/path/to/keyfile.json'
+ * });
+ *
+ * var compute = gcloud.compute();
+ *
+ * var network = compute.network('network-name');
+ */
+Compute.prototype.network = function(name) {
+  return new Network(this, name);
+};
+
 /**
  * Create a firewall rule. For a detailed description of method's options see
  * [API reference](https://goo.gl/kTMHep).
  *
  * @throws {Error} if a firewall name or firewall options are not provided.
  *     If allowed ports, source tags or source ranges are not provided.
  *
- * @param {module:compute} compute - The Google Compute Engine object this
- *     firewall belongs to.
  * @param {string} name - Name of the firewall.
  * @param {object} options - Firewall options.
  * @param {string=} options.description - Description of the firewall.
- * @param {string=} options.network - Network to which the firewall applies.
- *     Default value is 'global/networks/default'.
+ * @param {string=|module:compute/network} options.network - Network to which
+ *     the firewall applies. Default value is 'global/networks/default'.
  * @param {object[]=} options.allowed - List of allowed protocols and ports.
  * @param {string[]=} options.sourceRanges - IP address blocks to which this
  *     rule applies (in CIDR format).
@@ -252,45 +275,84 @@ Compute.prototype.createFirewall = function(name, options, callback) {
     throw new Error('Source ranges or source tags must be provided.');
   }
 
-  var body = {};
-  body.name = name;
-  if (util.is(options.description, 'string')) {
-    body.description = options.description;
-  }
-  if (util.is(options.network, 'string')) {
-    body.network = options.network;
+  if (util.is(options.network, 'object')) {
+    options.network =
+      'projects/' +
+      options.network.compute.projectId +
+      '/global/networks/' +
+      options.network.name;
   } else {
-    body.network = 'global/networks/default';
-  }
-  if (util.is(options.allowed, 'array')) {
-    body.allowed = options.allowed;
-  }
-  if (util.is(options.sourceRanges, 'array')) {
-    body.sourceRanges = options.sourceRanges;
-  }
-  if (util.is(options.sourceTags, 'array')) {
-    body.sourceTags = options.sourceTags;
-  }
-  if (util.is(options.targetTags, 'array')) {
-    body.targetTags = options.targetTags;
+    options.network = options.network || 'global/networks/default';
   }
 
+  options.name = name;
+
   var self = this;
-  this.makeReq_(
-    'POST',
+  this.makeReq_('POST',
     '/global/firewalls',
     null,
-    body, function(err, resp) {
+    options, function(err, resp) {
       if (err) {
         callback(err);
         return;
       }
       var firewall = self.firewall(name);
-      firewall.name = options;
+      firewall.metadata = options;
       callback(null, firewall, resp);
     });
 };
 
+/**
+ * Create a network. For a detailed description of method's options see
+ * [API reference](https://goo.gl/cWYdER).
+ *
+ * @throws {Error} if a network name or an IPv4 range is not provided.
+ *
+ * @param {string} name - Name of the network.
+ * @param {object} options - Network options.
+ * @param {string} options.IPv4Range - CIDR range of addresses that are legal on
+ *     this network.
+ * @param {string=} options.description - Description of the network.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * var callback = function(err, network, apiResponse) {
+ *   // `network` is a Network object.
+ * };
+ *
+ * var compute = gcloud.compute({
+ *   projectId: 'grape-spaceship-123'
+ * });
+ *
+ * var network = compute.createNetwork('network',
+ *   {
+ *     IPv4Range: '192.168.0.0/16'
+ *   }, callback);
+ */
+Compute.prototype.createNetwork = function(name, options, callback) {
+  if (!name) {
+    throw new Error('A name is needed to use a Compute Engine Network.');
+  } else if (!/^(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)$/.test(name)) {
+    throw new Error('Name must match [a-z]([-a-z0-9]{0,61}[a-z0-9])?');
+  }
+  if (!options || !util.is(options.IPv4Range, 'string')) {
+    throw new Error('An IPv4 range must be provided.');
+  }
+
+  options.name = name;
+
+  var self = this;
+  this.makeReq_('POST', '/global/networks', null, options, function(err, resp) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    var network = self.network(name);
+    network.metadata = options;
+    callback(null, network, resp);
+  });
+};
+
 /**
  * Get a list of instances. For a detailed description of method's options see
  * [API reference](https://goo.gl/GeDAwy).
@@ -442,7 +504,7 @@ Compute.prototype.getInstances = function(options, callback) {
  * compute.getDisks()
  *   .on('error', console.error)
  *   .on('data', function(disk) {
- *     // `disk` is an `Disk` object.
+ *     // `disk` is a `Disk` object.
  *   })
  *   .on('end', function() {
  *     // All disks retrieved.
@@ -646,7 +708,7 @@ Compute.prototype.getAddresses = function(options, callback) {
  * compute.getSnapshots()
  *   .on('error', console.error)
  *   .on('data', function(snapshot) {
- *     // `snapshot` is an `Snapshot` object.
+ *     // `snapshot` is a `Snapshot` object.
  *   })
  *   .on('end', function() {
  *     // All snapshots retrieved.
@@ -716,7 +778,6 @@ Compute.prototype.getSnapshots = function(options, callback) {
  *
  * compute.getFirewalls(
  *   {
- *     zone: 'europe-west1-b',
  *     filter: 'name eq firewall-[0-9]'
  *   }, callback);
  *
@@ -736,12 +797,12 @@ Compute.prototype.getSnapshots = function(options, callback) {
  * }, callback);
  *
  * //-
- * // Get the snapshots from your project as a readable object stream.
+ * // Get the firewalls from your project as a readable object stream.
  * //-
- * compute.getSnapshots()
+ * compute.getFirewalls()
  *   .on('error', console.error)
  *   .on('data', function(firewall) {
- *     // `firewall` is an `Firewall` object.
+ *     // `firewall` is a `Firewall` object.
  *   })
  *   .on('end', function() {
  *     // All firewalls retrieved.
@@ -788,6 +849,100 @@ Compute.prototype.getFirewalls = function(options, callback) {
   });
 };
 
+/**
+ * Get a list of networks. For a detailed description of method's options
+ * see [API reference](https://goo.gl/yx70Gc).
+ *
+ * @param {object} options - Network search options.
+ * @param {boolean=} options.autoPaginate - Have pagination handled
+ *     automatically. Default: true.
+ * @param {number=} options.maxResults - Maximum number of networks 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, networks) {
+ *   // `networks` is an array of `Network` objects.
+ * };
+ *
+ * compute.getNetworks(
+ *   {
+ *     filter: 'name eq network-[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, networks, nextQuery, apiResponse) {
+ *   if (nextQuery) {
+ *     // More results exist.
+ *     compute.getNetworks(nextQuery, callback);
+ *   }
+ * };
+ *
+ * compute.getNetworks({
+ *   autoPaginate: false
+ * }, callback);
+ *
+ * //-
+ * // Get the networks from your project as a readable object stream.
+ * //-
+ * compute.getNetworks()
+ *   .on('error', console.error)
+ *   .on('data', function(network) {
+ *     // `network` is a `Network` object.
+ *   })
+ *   .on('end', function() {
+ *     // All networks retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * compute.getNetworks()
+ *   .on('data', function(network) {
+ *     this.end();
+ *   });
+ */
+Compute.prototype.getNetworks = function(options, callback) {
+  if (util.is(options, 'function')) {
+    callback = options;
+    options = {};
+  }
+
+  options = options || {};
+
+  var self = this;
+  this.makeReq_('GET', '/global/networks', options, null, function(err, resp) {
+    if (err) {
+      callback(err);
+      return;
+    }
+
+    var nextQuery = null;
+
+    if (resp.nextPageToken) {
+      nextQuery = extend({}, options, {
+        pageToken: resp.nextPageToken
+      });
+    }
+
+    var networks = (resp.items || []).map(function(networkObject) {
+      var network = self.network(networkObject.name);
+      network.metadata = networkObject;
+      return network;
+    });
+    callback(null, networks, nextQuery, resp);
+  });
+};
+
 /**
  * Make a new request object from the provided arguments and wrap the callback
  * to intercept non-successful responses.
@@ -824,7 +979,8 @@ streamRouter.extend(Compute, [
   'getDisks',
   'getAddresses',
   'getSnapshots',
-  'getFirewalls'
+  'getFirewalls',
+  'getNetworks'
 ]);
 
 module.exports = Compute;