Add Google Cloud DNS

Author: stephenplusplus

CONTRIBUTING.md

@@ -21,6 +21,7 @@ To run the system tests, first create and configure a project in the Google Deve
 
 - **GCLOUD_TESTS_PROJECT_ID**: Developers Console project's ID (e.g. bamboo-shift-455)
 - **GCLOUD_TESTS_KEY**: The path to the JSON key file.
+- ***GCLOUD_TESTS_DNS_DOMAIN*** (*optional*): A domain you own managed by Google Cloud DNS (expected format: `'gcloud-node.com.'`).
 
 Install the [gcloud command-line tool][gcloudcli] to your machine and use it to create the indexes used in the datastore system tests with indexes found in `system-test/data/index/yaml`:
 

test/search.index.js docs/json/master/dns/.gitkeeptest/search.index.js renamed to docs/json/master/dns/.gitkeep

@@ -73,6 +73,25 @@ angular.module('gcloud.docs')
       ]
     },
 
+    dns: {
+      title: 'DNS',
+      _url: '{baseUrl}/dns',
+      pages: [
+        {
+          title: 'Zone',
+          url: '/zone'
+        },
+        {
+          title: 'Record',
+          url: '/record'
+        },
+        {
+          title: 'Change',
+          url: '/change'
+        }
+      ]
+    },
+
     pubsub: {
       title: 'PubSub',
       _url: '{baseUrl}/pubsub',
@@ -158,6 +177,9 @@ angular.module('gcloud.docs')
       '>=0.10.0': ['bigquery'],
 
       // introduce search api.
-      '>=0.16.0': ['search']
+      '>=0.16.0': ['search'],
+
+      // introduce dns api.
+      '>=0.17.0': ['dns']
     }
   });

docs/site/components/docs/docs-values.js

@@ -256,6 +256,20 @@ function getType(value) {
   return Object.prototype.toString.call(value).match(/\s(\w+)\]/)[1];
 }
 
+function exec(name) {
+  var initialArguments = [].slice.call(arguments, 1);
+
+  return function(item) {
+    if (util.is(item[name], 'function')) {
+      var invokedArguments = [].slice.call(arguments, 1);
+      return item[name].apply(item, initialArguments.concat(invokedArguments));
+    }
+    return item[name];
+  };
+}
+
+util.exec = exec;
+
 /**
  * Used in an Array iterator usually, this will return the value of a property
  * in an object by its name.

lib/common/util.js

@@ -0,0 +1,62 @@
+/*!
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * @module dns/change
+ */
+
+'use strict';
+
+/**
+ * @constructor
+ * @alias module:dns/change
+ *
+ * @param {module:dns/zone} zone - The parent zone object.
+ * @param {string} id - ID of the change.
+ */
+function Change(zone, id) {
+  this.zoneName = zone.name;
+  this.id = id;
+
+  this.metadata = {};
+  this.makeReq_ = zone.dns.makeReq_.bind(zone.dns);
+}
+
+/**
+ * Get the metadata for the change in the zone.
+ *
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An API error.
+ * @param {?object} callback.metadata - Metadata of the change from the API.
+ * @param {object} callback.apiResponse - Raw API response.
+ */
+Change.prototype.getMetadata = function(callback) {
+  var self = this;
+  var path = '/managedZones/' + this.zoneName + '/changes/' + this.id;
+
+  this.makeReq_('GET', path, null, null, function(err, resp) {
+    if (err) {
+      callback(err, null, resp);
+      return;
+    }
+
+    self.metadata = resp;
+
+    callback(null, self.metadata, resp);
+  });
+};
+
+module.exports = Change;

lib/dns/change.js

@@ -0,0 +1,250 @@
+/*!
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * @module dns
+ */
+
+'use strict';
+
+var extend = require('extend');
+
+/**
+ * @type {module:common/streamrouter}
+ * @private
+ */
+var streamRouter = require('../common/stream-router.js');
+
+/**
+ * @type {module:common/util}
+ * @private
+ */
+var util = require('../common/util.js');
+
+/**
+ * @type {module:dns/zone}
+ * @private
+ */
+var Zone = require('./zone.js');
+
+/**
+ * @const {string} Base URL for DNS API.
+ * @private
+ */
+var DNS_BASE_URL = 'https://www.googleapis.com/dns/v1/projects/';
+
+/**
+ * @const {array} Required scopes for the DNS API.
+ * @private
+ */
+var SCOPES = [
+  'https://www.googleapis.com/auth/ndev.clouddns.readwrite',
+  'https://www.googleapis.com/auth/cloud-platform'
+];
+
+/**
+ * [Google Cloud DNS](https://cloud.google.com/dns) is a reliable, resilient,
+ * low-latency DNS serving from Google’s worldwide network of Anycast DNS
+ * servers.
+ *
+ * @constructor
+ * @alias module:dns
+ *
+ * @param {object} options - [Configuration object](#/docs/?method=gcloud).
+ *
+ * @example
+ * var gcloud = require('gcloud')({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'grape-spaceship-123'
+ * });
+ *
+ * var dns = gcloud.dns();
+ */
+function DNS(options) {
+  if (!(this instanceof DNS)) {
+    return new DNS(options);
+  }
+
+  options = options || {};
+
+  if (!options.projectId) {
+    throw util.missingProjectIdError;
+  }
+
+  this.makeAuthorizedRequest_ = util.makeAuthorizedRequestFactory({
+    credentials: options.credentials,
+    keyFile: options.keyFilename,
+    scopes: SCOPES,
+    email: options.email
+  });
+
+  this.projectId_ = options.projectId;
+}
+
+/**
+ * Create a managed zone.
+ *
+ * @throws {error} If a zone name is not provided.
+ * @throws {error} If a zone dnsName is not provided.
+ *
+ * @param {string} name - Unique name for the zone. E.g. "my-zone"
+ * @param {object} config - Configuration object.
+ * @param {string} config.dnsName - DNS name for the zone. E.g. "example.com."
+ * @param {string=} config.description - Description text for the zone.
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An API error.
+ * @param {?module:dns/zone} callback.zone - A new {module:dns/zone} object.
+ * @param {object} callback.apiResponse - Raw API response.
+ *
+ * @example
+ * dns.createZone('my-awesome-zone', {
+ *   dnsName: 'example.com.', // note the period at the end of the domain.
+ *   description: 'This zone is awesome!'
+ * }, function(err, zone, apiResponse) {
+ *   if (!err) {
+ *     // The zone was created successfully.
+ *   }
+ * });
+ */
+DNS.prototype.createZone = function(name, config, callback) {
+  var self = this;
+
+  if (!name) {
+    throw new Error('A zone name is required.');
+  }
+
+  if (!config || !config.dnsName) {
+    throw new Error('A zone dnsName is required.');
+  }
+
+  config.name = name;
+
+  // Required by the API.
+  config.description = config.description || '';
+
+  this.makeReq_('POST', '/managedZones', null, config, function(err, resp) {
+    if (err) {
+      callback(err, null, resp);
+      return;
+    }
+
+    var zone = self.zone(resp.name);
+    zone.metadata = resp;
+
+    callback(null, zone, resp);
+  });
+};
+
+/**
+ * Gets a list of managed zones for the project.
+ *
+ * @param {object=} query - Query object.
+ * @param {number} query.maxResults - Maximum number of results to return.
+ * @param {string} query.pageToken - Page token.
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An API error.
+ * @param {?module:dns/zone[]} callback.zones - An array of {module:dns/zone}
+ *     objects.
+ * @param {object} callback.apiResponse - Raw API response.
+ *
+ * @example
+ * dns.getZones(function(err, zones, apiResponse) {});
+ */
+DNS.prototype.getZones = function(query, callback) {
+  var self = this;
+
+  if (util.is(query, 'function')) {
+    callback = query;
+    query = {};
+  }
+
+  this.makeReq_('GET', '/managedZones', query, null, function(err, resp) {
+    if (err) {
+      callback(err, null, null, resp);
+      return;
+    }
+
+    var zones = (resp.managedZones || []).map(function(zone) {
+      var zoneInstance = self.zone(zone.name);
+      zoneInstance.metadata = zone;
+      return zoneInstance;
+    });
+
+    var nextQuery = null;
+
+    if (resp.nextPageToken) {
+      nextQuery = extend({}, query, {
+        pageToken: resp.nextPageToken
+      });
+    }
+
+    callback(null, zones, nextQuery, resp);
+  });
+};
+
+/**
+ * Create a zone object representing an existing managed zone.
+ *
+ * @throws {error} If a zone name is not provided.
+ *
+ * @param  {string} name - The unique name of the zone.
+ * @return {module:dns/zone}
+ *
+ * @example
+ * var zone = dns.zone('my-zone');
+ */
+DNS.prototype.zone = function(name) {
+  if (!name) {
+    throw new Error('A zone name is required.');
+  }
+
+  return new Zone(this, name);
+};
+
+/**
+ * Make a new request object from the provided arguments and wrap the callback
+ * to intercept non-successful responses.
+ *
+ * @private
+ *
+ * @param {string} method - Action.
+ * @param {string} path - Request path.
+ * @param {*} query - Request query object.
+ * @param {*} body - Request body contents.
+ * @param {function} callback - The callback function.
+ */
+DNS.prototype.makeReq_ = function(method, path, query, body, callback) {
+  var reqOpts = {
+    method: method,
+    qs: query,
+    uri:  DNS_BASE_URL + this.projectId_ + path
+  };
+
+  if (body) {
+    reqOpts.json = body;
+  }
+
+  this.makeAuthorizedRequest_(reqOpts, callback);
+};
+
+/*! Developer Documentation
+ *
+ * These methods can be used with either a callback or as a readable object
+ * stream. `streamRouter` is used to add this dual behavior.
+ */
+streamRouter.extend(DNS, 'getZones');
+
+module.exports = DNS;