Skip to content
This repository was archived by the owner on Apr 3, 2024. It is now read-only.

Commit 30bd528

Browse files
ofrobotsofrobots
authored
creds accepted in options only now (#200)
1 parent b5b691f commit 30bd528

File tree

9 files changed

+209
-127
lines changed

9 files changed

+209
-127
lines changed

‎README.md‎

Lines changed: 44 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,25 @@ This module provides Stackdriver Debugger support for Node.js applications. [Sta
1919
## Quick Start
2020
```shell
2121
# Install with `npm` or add to your `package.json`.
22-
npm install --save @google/cloud-debug
22+
npm install --save @google-cloud/debug
23+
```
2324

24-
# Require and start the agent at the top of your main script (but after '@google/cloud-trace' if you are also using it).
25-
require('@google/cloud-debug').start();
25+
```js
26+
// Require and start in the startup of your application:
27+
var debug = require('@google-cloud/debug')();
28+
debug.startAgent();
29+
// No config necessary if your code is running on Google Cloud Platform.
30+
31+
// ... or, if you are running elsewhere, you can manually provide credentials:
32+
var debug = require('@google-cloud/debug')({
33+
projectId: 'particular-future-12345',
34+
keyFilename: '/path/to/keyfile.json'
35+
});
36+
debug.startAgent();
2637
```
27-
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.
38+
39+
This starts the automatic Debugger Agent that enables your app to be debuggable using the Stackdriver [Stackdriver Debug view][debug-tab] within
40+
the [Google Cloud Console][dev-console]. You can start adding snapshots and log-points to your application.
2841

2942
## Running on Google Cloud Platform
3043

@@ -50,9 +63,21 @@ Container Engine nodes need to also be created with the `cloud-platform` scope,
5063

5164
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.
5265

53-
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.
66+
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:
5467

68+
```js
69+
// In your app:
70+
var debug = require('@google-cloud/debug')({
71+
projectId: 'particular-future-12345',
72+
keyFilename: '/path/to/keyfile.json'
73+
});
74+
debug.startAgent();
75+
```
76+
77+
```bash
78+
# Or in Bash:
5579
export GCLOUD_PROJECT=<project name>
80+
```
5681

5782
1. You need to provide service account credentials to your application.
5883
* 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
6489

6590
```js
6691
// Require and start the agent with configuration options
67-
require('@google/cloud-debug').start({
92+
require('@google-cloud/debug').start({
6893
// The path to your key file:
6994
keyFilename: '/path/to/keyfile.json',
7095

7196
// Or the contents of the key file:
7297
credentials: require('./path/to/keyfile.json')
7398
});
7499
```
75-
76-
See the [default configuration][config-js] for more details.
100+
101+
See the [configuration object][configuration-object] for more details.
77102

78103
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.
79104

80105
gcloud beta debug source gen-repo-info-file
81106

82-
## Configuration
107+
## Debug Agent Settings
83108

84-
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:
109+
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:
85110

86-
require('@google/cloud-debug').start({
87-
logLevel: 2,
111+
```js
112+
debug.startAgent({
88113
serviceContext: {
89114
service: 'my-service',
90-
version: '1'
91-
}
115+
version: 'version-1'
116+
},
117+
capture: { maxFramesFrames: 20, maxProperties: 100 }
92118
});
119+
```
93120

94121
## Using the Debugger
95122

@@ -123,8 +150,8 @@ As soon as that line of code is reached in any of the running instances of your
123150
[cloud-console-projects]: https://console.cloud.google.com/iam-admin/projects
124151
[app-default-credentials]: https://cloud.google.com/identity/protocols/application-default-credentials
125152
[service-account]: https://console.cloud.google.com/apis/credentials/serviceaccountkey
126-
[npm-image]: https://img.shields.io/npm/v/@google/cloud-debug.svg
127-
[npm-url]: https://npmjs.org/package/@google/cloud-debug
153+
[npm-image]: https://img.shields.io/npm/v/@google-cloud/debug.svg
154+
[npm-url]: https://npmjs.org/package/@google-cloud/debug
128155
[travis-image]: https://travis-ci.org/GoogleCloudPlatform/cloud-debug-nodejs.svg?branch=master
129156
[travis-url]: https://travis-ci.org/GoogleCloudPlatform/cloud-debug-nodejs
130157
[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
136163
[snyk-image]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs/badge.svg
137164
[snyk-url]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs
138165
[config-js]: https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/src/agent/config.js
166+
[configuration-object]: https://googlecloudplatform.github.io/google-cloud-node/#/docs/google-cloud/0.45.0/google-cloud

‎bin/run-test.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ fi
4545

4646
if [ -z "${TRAVIS_PULL_REQUEST}" ] || [ "${TRAVIS_PULL_REQUEST}" = "false" ]
4747
then
48-
if [ -z "${GCLOUD_PROJECT}"]; then
48+
if [ -z "${GCLOUD_PROJECT}" ]; then
4949
echo "============================================================"
5050
echo "Unable to run system and e2e tests. Provide valid project id"
5151
echo "via GCLOUD_PROJECT and ensure auth credentials are available"

‎src/agent/config.js‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -181,18 +181,6 @@ module.exports = {
181181
logDelaySeconds: 1
182182
},
183183

184-
// FIXME(ofrobots): stop accepting this property here
185-
// A path to a key file relative to the current working directory. If this
186-
// field is set, the contents of the pointed file will be used for
187-
// authentication instead of your application default credentials.
188-
keyFilename: null,
189-
190-
// FIXME(ofrobots): stop accepting this property here
191-
// The contents of a key file. If this field is set, its contents will be
192-
// used for authentication instead of your application default credentials.
193-
// If keyFilename is also set, the value of credentials will be ignored.
194-
credentials: null,
195-
196184
/**
197185
* @property {object} These configuration options are for internal
198186
* experimentation only.

‎src/agent/debuglet.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ Debuglet.prototype.start = function() {
154154
}
155155

156156
// We can register as a debuggee now.
157+
that.logger_.debug('Starting debuggee, project', project);
157158
that.running_ = true;
158159
that.project_ = project;
159160
that.debuggee_ = new Debuggee(
@@ -184,7 +185,7 @@ Debuglet.prototype.getProjectId_ = function(callback) {
184185

185186
// We perfer to use the locally available projectId as that is least
186187
// surprising to users.
187-
var project = that.config_.projectId || process.env.GCLOUD_PROJECT ||
188+
var project = that.debug_.options.projectId || process.env.GCLOUD_PROJECT ||
188189
metadataProject;
189190

190191
// We if don't have a projectId by now, we fail with an error.
@@ -506,6 +507,7 @@ Debuglet.prototype.scheduleBreakpointExpiry_ = function(breakpoint) {
506507
* Stops the Debuglet
507508
*/
508509
Debuglet.prototype.stop = function() {
510+
this.logger_.debug('Stopping Debuglet');
509511
this.running_ = false;
510512
this.emit('stopped');
511513
};

‎src/index.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,24 @@ function Debug(options) {
6363
};
6464

6565
common.Service.call(this, config, options);
66+
67+
// FIXME(ofrobots): We need our own copy of options because Service may
68+
// default to '{{projectId}}' when options doesn't contain the `projectId`.
69+
// property. This breaks the SSOT principle. Remove this when
70+
// https://github.com/GoogleCloudPlatform/google-cloud-node/issues/1891
71+
// is resolved.
72+
this.options = options;
6673
}
6774
util.inherits(Debug, common.Service);
6875

6976
var initConfig = function(config_) {
7077
var config = config_ || {};
7178

79+
if (config.keyFilename || config.credentials || config.projectId) {
80+
throw new Error('keyFilename, projectId or credentials should be provided' +
81+
' to the Debug module constructor rather than startAgent');
82+
}
83+
7284
var defaults = require('./agent/config.js');
7385
_.defaultsDeep(config, defaults);
7486
if (process.env.hasOwnProperty('GCLOUD_DEBUG_LOGLEVEL')) {

‎system-test/test-controller.js‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,11 @@ var assert = require('assert');
2020

2121
assert.ok(
2222
process.env.GCLOUD_PROJECT,
23-
'Need to have GCLOUD_PROJECT defined ' +
24-
'along with valid application default credentials to be able to run this ' +
25-
'test');
23+
'Need to have GCLOUD_PROJECT defined to be able to run this test');
24+
assert.ok(
25+
process.env.GOOGLE_APPLICATION_CREDENTIALS,
26+
'Need to have GOOGLE_APPLICATION_CREDENTIALS defined to be able to run ' +
27+
'this test');
2628

2729
var Controller = require('../src/controller.js');
2830
var Debuggee = require('../src/debuggee.js');

‎test/nocks.js‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/**
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
'use strict';
17+
18+
var nock = require('nock');
19+
20+
// In the future _=>true.
21+
function accept() {
22+
return true;
23+
}
24+
25+
function nockOAuth2(validator) {
26+
validator = validator || accept;
27+
return nock('https://accounts.google.com')
28+
.post('/o/oauth2/token', validator)
29+
.reply(200, {
30+
refresh_token: 'hello',
31+
access_token: 'goodbye',
32+
expiry_date: new Date(9999, 1, 1)
33+
});
34+
}
35+
36+
function nockRegister(validator) {
37+
validator = validator || accept;
38+
return nock('https://clouddebugger.googleapis.com')
39+
.post('/v2/controller/debuggees/register', validator)
40+
.reply(200);
41+
}
42+
43+
function nockNumericProjectId(reply) {
44+
return nock('http://metadata.google.internal')
45+
.get('/computeMetadata/v1/project/numeric-project-id')
46+
.reply(reply);
47+
}
48+
49+
module.exports = {
50+
oauth2: nockOAuth2,
51+
numericProjectId: nockNumericProjectId,
52+
register: nockRegister
53+
};

0 commit comments

Comments
 (0)