creds accepted in options only now (#200)

README.md

@@ -19,12 +19,25 @@ This module provides Stackdriver Debugger support for Node.js applications. [Sta
 ## Quick Start
 ```shell
 # Install with `npm` or add to your `package.json`.
-npm install --save @google/cloud-debug
+npm install --save @google-cloud/debug
+```
 
-# Require and start the agent at the top of your main script (but after '@google/cloud-trace' if you are also using it).
-require('@google/cloud-debug').start();
+```js
+// Require and start in the startup of your application:
+var debug = require('@google-cloud/debug')();
+debug.startAgent();
+// No config necessary if your code is running on Google Cloud Platform.
+
+// ... or, if you are running elsewhere, you can manually provide credentials:
+var debug = require('@google-cloud/debug')({
+  projectId: 'particular-future-12345',
+  keyFilename: '/path/to/keyfile.json'
+});
+debug.startAgent();
 ```
-Deploy your application, and navigate to the [Stackdriver Debug view][debug-tab] within the [Google Cloud Console][dev-console] to set snapshots and start debugging.
+
+This starts the automatic Debugger Agent that enables your app to be debuggable using the Stackdriver [Stackdriver Debug view][debug-tab] within
+the [Google Cloud Console][dev-console]. You can start adding snapshots and log-points to your application.
 
 ## Running on Google Cloud Platform
 
@@ -50,9 +63,21 @@ Container Engine nodes need to also be created with the `cloud-platform` scope,
 
 If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Debugger.
 
-1. You will need to specify your project name. Your project name is visible in the [Google Cloud Console][cloud-console-projects], it may be something like `particular-future-12345`. If your application is [running on Google Cloud Platform](running-on-google-cloud-platform), you don't need to specify the project name.
+1. You will need to specify your project name. Your project name is visible in the [Google Cloud Console][cloud-console-projects], it may be something like `particular-future-12345`. If your application is [running on Google Cloud Platform](running-on-google-cloud-platform), you don't need to specify the project name. You can specify this either in the module options, or through an environment variable:
 
+        ```js
+        // In your app:
+        var debug = require('@google-cloud/debug')({
+          projectId: 'particular-future-12345',
+          keyFilename: '/path/to/keyfile.json'
+        });
+        debug.startAgent();
+        ```
+
+        ```bash
+        # Or in Bash:
         export GCLOUD_PROJECT=<project name>
+        ```
 
 1. You need to provide service account credentials to your application.
   * The recommended way is via [Application Default Credentials][app-default-credentials].
@@ -64,32 +89,34 @@ If your application is running outside of Google Cloud Platform, such as locally
 
     ```js
     // Require and start the agent with configuration options
-    require('@google/cloud-debug').start({
+    require('@google-cloud/debug').start({
       // The path to your key file:
       keyFilename: '/path/to/keyfile.json',
 
       // Or the contents of the key file:
       credentials: require('./path/to/keyfile.json')
     });
     ```
-    
-   See the [default configuration][config-js] for more details.
+
+   See the [configuration object][configuration-object] for more details.
 
 1. Generate a `source-context.json` file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information in this file to display the correct version of the source.
 
         gcloud beta debug source gen-repo-info-file
 
-## Configuration
+## Debug Agent Settings
 
-See [the default configuration][config-js] for a list of possible configuration options. These options can be passed to the agent through the object argument to the start command as shown below:
+You can customize the behaviour of the automatic debugger agent. See [the agent configuration][config-js] for a list of possible configuration options. These options can be passed to the agent through the object argument to the startAgent method as shown below:
 
-        require('@google/cloud-debug').start({
-          logLevel: 2,
+        ```js
+        debug.startAgent({
           serviceContext: {
               service: 'my-service',
-              version: '1'
-            }
+              version: 'version-1'
+          },
+          capture: { maxFramesFrames: 20, maxProperties: 100 }
         });
+        ```
 
 ## Using the Debugger
 
@@ -123,8 +150,8 @@ As soon as that line of code is reached in any of the running instances of your
 [cloud-console-projects]: https://console.cloud.google.com/iam-admin/projects
 [app-default-credentials]: https://cloud.google.com/identity/protocols/application-default-credentials
 [service-account]: https://console.cloud.google.com/apis/credentials/serviceaccountkey
-[npm-image]: https://img.shields.io/npm/v/@google/cloud-debug.svg
-[npm-url]: https://npmjs.org/package/@google/cloud-debug
+[npm-image]: https://img.shields.io/npm/v/@google-cloud/debug.svg
+[npm-url]: https://npmjs.org/package/@google-cloud/debug
 [travis-image]: https://travis-ci.org/GoogleCloudPlatform/cloud-debug-nodejs.svg?branch=master
 [travis-url]: https://travis-ci.org/GoogleCloudPlatform/cloud-debug-nodejs
 [coveralls-image]: https://img.shields.io/coveralls/GoogleCloudPlatform/cloud-debug-nodejs/master.svg
@@ -136,3 +163,4 @@ As soon as that line of code is reached in any of the running instances of your
 [snyk-image]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs/badge.svg
 [snyk-url]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs
 [config-js]: https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/src/agent/config.js
+[configuration-object]: https://googlecloudplatform.github.io/google-cloud-node/#/docs/google-cloud/0.45.0/google-cloud

bin/run-test.sh

@@ -45,7 +45,7 @@ fi
 
 if [ -z "${TRAVIS_PULL_REQUEST}" ] || [ "${TRAVIS_PULL_REQUEST}" = "false" ]
 then
-  if [ -z "${GCLOUD_PROJECT}"]; then
+  if [ -z "${GCLOUD_PROJECT}" ]; then
     echo "============================================================"
     echo "Unable to run system and e2e tests. Provide valid project id"
     echo "via GCLOUD_PROJECT and ensure auth credentials are available"

src/agent/config.js

@@ -181,18 +181,6 @@ module.exports = {
     logDelaySeconds: 1
   },
 
-  // FIXME(ofrobots): stop accepting this property here
-  // A path to a key file relative to the current working directory. If this
-  // field is set, the contents of the pointed file will be used for
-  // authentication instead of your application default credentials.
-  keyFilename: null,
-
-  // FIXME(ofrobots): stop accepting this property here
-  // The contents of a key file. If this field is set, its contents will be
-  // used for authentication instead of your application default credentials.
-  // If keyFilename is also set, the value of credentials will be ignored.
-  credentials: null,
-
   /**
    * @property {object} These configuration options are for internal
    * experimentation only.

src/agent/debuglet.js

@@ -154,6 +154,7 @@ Debuglet.prototype.start = function() {
             }
 
             // We can register as a debuggee now.
+            that.logger_.debug('Starting debuggee, project', project);
             that.running_ = true;
             that.project_ = project;
             that.debuggee_ = new Debuggee(
@@ -184,7 +185,7 @@ Debuglet.prototype.getProjectId_ = function(callback) {
 
     // We perfer to use the locally available projectId as that is least
     // surprising to users.
-    var project = that.config_.projectId || process.env.GCLOUD_PROJECT ||
+    var project = that.debug_.options.projectId || process.env.GCLOUD_PROJECT ||
                   metadataProject;
 
     // We if don't have a projectId by now, we fail with an error.
@@ -506,6 +507,7 @@ Debuglet.prototype.scheduleBreakpointExpiry_ = function(breakpoint) {
  * Stops the Debuglet
  */
 Debuglet.prototype.stop = function() {
+  this.logger_.debug('Stopping Debuglet');
   this.running_ = false;
   this.emit('stopped');
 };

src/index.js

@@ -63,12 +63,24 @@ function Debug(options) {
   };
 
   common.Service.call(this, config, options);
+
+  // FIXME(ofrobots): We need our own copy of options because Service may
+  // default to '{{projectId}}' when options doesn't contain the `projectId`.
+  // property. This breaks the SSOT principle. Remove this when
+  // https://github.com/GoogleCloudPlatform/google-cloud-node/issues/1891
+  // is resolved.
+  this.options = options;
 }
 util.inherits(Debug, common.Service);
 
 var initConfig = function(config_) {
   var config = config_ || {};
 
+  if (config.keyFilename || config.credentials || config.projectId) {
+    throw new Error('keyFilename, projectId or credentials should be provided' + 
+                    ' to the Debug module constructor rather than startAgent');
+  }
+
   var defaults = require('./agent/config.js');
   _.defaultsDeep(config, defaults);
   if (process.env.hasOwnProperty('GCLOUD_DEBUG_LOGLEVEL')) {

system-test/test-controller.js

@@ -20,9 +20,11 @@ var assert = require('assert');
 
 assert.ok(
     process.env.GCLOUD_PROJECT,
-    'Need to have GCLOUD_PROJECT defined ' +
-        'along with valid application default credentials to be able to run this ' +
-        'test');
+    'Need to have GCLOUD_PROJECT defined to be able to run this test');
+assert.ok(
+    process.env.GOOGLE_APPLICATION_CREDENTIALS,
+    'Need to have GOOGLE_APPLICATION_CREDENTIALS defined to be able to run ' +
+    'this test');
 
 var Controller = require('../src/controller.js');
 var Debuggee = require('../src/debuggee.js');

test/nocks.js

@@ -0,0 +1,53 @@
+/**
+ * Copyright 2016 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.
+ */
+'use strict';
+
+var nock = require('nock');
+
+// In the future _=>true.
+function accept() {
+  return true;
+}
+
+function nockOAuth2(validator) {
+  validator = validator || accept;
+  return nock('https://accounts.google.com')
+      .post('/o/oauth2/token', validator)
+      .reply(200, {
+        refresh_token: 'hello',
+        access_token: 'goodbye',
+        expiry_date: new Date(9999, 1, 1)
+      });
+}
+
+function nockRegister(validator) {
+  validator = validator || accept;
+  return nock('https://clouddebugger.googleapis.com')
+      .post('/v2/controller/debuggees/register', validator)
+      .reply(200);
+}
+
+function nockNumericProjectId(reply) {
+  return nock('http://metadata.google.internal')
+    .get('/computeMetadata/v1/project/numeric-project-id')
+    .reply(reply);
+}
+
+module.exports = {
+  oauth2: nockOAuth2,
+  numericProjectId: nockNumericProjectId,
+  register: nockRegister
+};