Opt-in hooks and signal by default

This changes the default action on require('nodereport') to opt-in
to the exception and fatal-error hooks, and to enable the signal
handler. So 'node -r nodereport application.js' will get all the
nodereport functionality without any application code changes.

For users programming to the API, a separate api-only entry point,
require('nodereport/api') is provided. This does not enable the
hooks and signal unless and until .setEvents() is called.

PR-URL: #33
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Author: rnchamberlain

.npmignore

@@ -1,3 +1,4 @@
 *
 !src/**
 !binding.gyp
+!index.js

README.md

@@ -15,15 +15,26 @@ Supports Node.js v4, v6 and v7 on Linux, MacOS, Windows and AIX.
 
 ```bash
 npm install nodereport
+node -r nodereport app.js
 ```
+A NodeReport will be triggered automatically on unhandled exceptions and fatal
+error events (for example out of memory errors), and can also be triggered
+by sending a USR2 signal to a Node.js process (Linux/MacOS only).
 
-This will allow a NodeReport to be triggered via an API
-call from a JavaScript application.
+A NodeReport can also be triggered via an API call from a JavaScript
+application.
 
 ```js
 var nodereport = require('nodereport');
 nodereport.triggerReport();
 ```
+The API can be used without adding the automatic exception and fatal error
+hooks and the signal handler, as follows:
+
+```js
+var nodereport = require('nodereport/api');
+nodereport.triggerReport();
+```
 
 Content of the NodeReport consists of a header section containing the event
 type, date, time, PID and Node version, sections containing JavaScript and
@@ -50,19 +61,12 @@ can be specified as a parameter on the `triggerReport()` call.
 nodereport.triggerReport("myReportName");
 ```
 
-A NodeReport can also be triggered automatically on unhandled exceptions, fatal
-error events (for example out of memory errors), and signals (Linux/MacOS only).
-Triggering on these events can be enabled using the following API call:
-
-```js
-nodereport.setEvents("exception+fatalerror+signal+apicall");
-```
-
 ## Configuration
 
 Additional configuration is available using the following APIs:
 
 ```js
+nodereport.setEvents("exception+fatalerror+signal+apicall");
 nodereport.setSignal("SIGUSR2|SIGQUIT");
 nodereport.setFileName("stdout|stderr|<filename>");
 nodereport.setDirectory("<full path>");

binding.gyp

@@ -1,7 +1,7 @@
 {
   "targets": [
     {
-      "target_name": "nodereport",
+      "target_name": "api",
       "sources": [ "src/node_report.cc", "src/module.cc" ],
       "include_dirs": [ '<!(node -e "require(\'nan\')")' ],
       "conditions": [
@@ -27,11 +27,11 @@
     {
       "target_name": "install",
       "type":"none",
-      "dependencies" : [ "nodereport" ],
+      "dependencies" : [ "api" ],
       "copies": [
         {
           "destination": "<(module_root_dir)",
-          "files": ["<(module_root_dir)/build/Release/nodereport.node"]
+          "files": ["<(module_root_dir)/build/Release/api.node"]
         }]
     },
   ],

index.js

@@ -0,0 +1,15 @@
+// Main module entry point for nodereport
+
+const api = require('./api');
+
+// NODEREPORT_EVENTS env var overrides the defaults
+const options = process.env.NODEREPORT_EVENTS || 'exception+fatalerror+signal+apicall';
+api.setEvents(options);
+
+exports.triggerReport = api.triggerReport;
+exports.setEvents = api.setEvents;
+exports.setCoreDump = api.setCoreDump;
+exports.setSignal = api.setSignal;
+exports.setFileName = api.setFileName;
+exports.setDirectory = api.setDirectory;
+exports.setVerbose = api.setVerbose;

package.json

@@ -1,6 +1,5 @@
 {
   "name": "nodereport",
-  "main": "nodereport.node",
   "version": "1.0.7",
   "description": "Diagnostic NodeReport",
   "homepage": "https://github.com/nodejs/nodereport#readme",

test/test-api-nohooks.js

@@ -0,0 +1,22 @@
+'use strict';
+
+// Testcase to produce NodeReport via API call, using the no-hooks/no-signal
+// interface - i.e. require('nodereport/api')
+if (process.argv[2] === 'child') {
+  const nodereport = require('../api');
+  nodereport.triggerReport();
+} else {
+  const common = require('./common.js');
+  const spawn = require('child_process').spawn;
+  const tap = require('tap');
+
+  const child = spawn(process.execPath, [__filename, 'child']);
+  child.on('exit', (code) => {
+    tap.plan(3);
+    tap.equal(code, 0, 'Process exited cleanly');
+    const reports = common.findReports(child.pid);
+    tap.equal(reports.length, 1, 'Found reports ' + reports);
+    const report = reports[0];
+    common.validate(tap, report, {pid: child.pid});
+  });
+}

test/test-exception.js

@@ -2,7 +2,7 @@
 
 // Testcase to produce NodeReport on uncaught exception
 if (process.argv[2] === 'child') {
-  require('../').setEvents('exception');
+  require('../');
 
   function myException(request, response) {
     const m = '*** exception.js: testcase exception thrown from myException()';

test/test-fatal-error.js

@@ -2,7 +2,7 @@
 
 // Testcase to produce NodeReport on fatal error (javascript heap OOM)
 if (process.argv[2] === 'child') {
-  require('../').setEvents('fatalerror');
+  require('../');
 
   const list = [];
   while (true) {

test/test-signal.js

@@ -3,7 +3,7 @@
 // Testcase to produce NodeReport on signal interrupting a js busy-loop,
 // showing it is interruptible.
 if (process.argv[2] === 'child') {
-  require('../').setEvents('signal');
+  require('../');
 
   // Exit on loss of parent process
   process.on('disconnect', () => process.exit(2));