Move the plugin installatin logic to the configuration

* Enable console and patternMatcher plugins by default
* Keep old way to extend the frontend (via plugins/index.js) for BC
* Rewrite the plugin documentation

Author: fzaninotto

CHANGELOG.md

@@ -4,6 +4,8 @@ Uptime Changelog
 To be released
 --------------
 
+* Update the README about the plugin system
+* Update plugins system to make it easier to enable new plugins, just by adding a line in the configuration
 * Add pollerCollections to allow the addition of custom pollers
 * Update HTTP and HTTPS pollers (they now specialize a BaseHttpPoller, to reduce code duplication)
 * Fix monitor crash when poller is badly set
@@ -15,7 +17,6 @@ To be released
 * Add new events to Monitor and dashboard app
 * Add more plugins extension points: they can now add details to checks, abilities to pollers, and store additional details about pings
 * Move Pattern Matcher logic to a plugin
-* Update the README accordingly
 * Fix warnings in production by using cookie store for sessions
 * Add mention of external plugins in README
 * Add pattern detection in response body

README.md

@@ -12,17 +12,20 @@ Features
 --------
 
 * Monitor thousands of websites (powered by [Node.js asynchronous programming](http://dotheweb.posterous.com/nodejs-for-php-programmers-1-event-driven-pro))
-* Check the presence of a pattern in the response body
 * Tweak frequency of monitoring on a per-check basis, up to the second
-* Receive on screen notifications whenever a check goes down (powered by [socket.io](http://socket.io/))
-* Receive email notifications whenever a check goes down
+* Check the presence of a pattern in the response body
+* Receive notifications whenever a check goes down
+  * On screen (powered by [socket.io](http://socket.io/))
+  * By email
+  * On the console
 * Record availability statistics for further reporting (powered by [MongoDB](http://www.mongodb.org/))
 * Detailed uptime reports with animated charts (powered by [Flotr2](http://www.humblesoftware.com/flotr2/))
 * Monitor availability, responsiveness, average response time, and total uptime/downtime
 * Get details about failed checks (HTTP error code, etc.)
 * Group checks by tags and get reports by tag
 * Familiar web interface (powered by [Twitter Bootstrap 2.0](http://twitter.github.com/bootstrap/index.html))
 * Complete API for integration with third-party monitoring services
+* Powerful plugin system to ease extension and customization
 * Easy installation and zero administration
 
 Installing Uptime
@@ -91,6 +94,11 @@ autoStartMonitor: true
 
 server:
   port:     8082
+
+plugins:
+  - ./plugins/console
+  - ./plugins/patternMatcher
+  # - ./plugins/email
 ```
 
 To modify this configuration, create a `development.yaml` or a `production.yaml` file in the same directory, and override just the settings you need. For instance, to run Uptime on port 80 in production, create a `production.yaml` file as follows:
@@ -100,7 +108,7 @@ server:
   port:     80
 ```
 
-Node that Uptime works great behind a proxy - it uses the http_proxy environment variable transparently.
+Node that Uptime works great behind a proxy - it uses the `http_proxy` environment variable transparently.
 
 Architecture
 ------------
@@ -128,37 +136,55 @@ You can even run several monitor servers in several datacenters to get average r
 Using Plugins
 -------------
 
-Uptime provides plugins that you can enable to add more functionality. Plugins can add more notification types, more poller types, new routes to the webapp, etc. To enable plugins, create a `plugins/index.js` module. Uptime automatically requires this module when starting the webapp and the monitor, and tries to call the two following functions:
+Plugins can add more notification types, more poller types, new routes to the webapp, etc. Uptime currently bundles three plugins:
 
-* `initWebApp()` when starting the webapp
-* `initMonitor()` when starting the monitor
+ * [`console`](https://github.com/fzaninotto/uptime/blob/master/plugins/console/index.js): log pings and events in the console in real time
+ * [`email`](https://github.com/fzaninotto/uptime/blob/master/plugins/email/index.js): notify events (up, down pause) by email
+ * [`patternMatcher`](https://github.com/fzaninotto/uptime/blob/master/plugins/patternMatcher/index.js): allow HTTP & HTTPS pollers to test the response body against a pattern
 
-For instance, to enable the `console` plugin:
+To enable plugins, just add a line to the `plugins:` section of the configuration file.
+Two of the bundled plugins are already enabled by default:
 
-```js
-// in plugins/index.js
-exports.initWebApp = function() {
-  require('./console').init();
-};
+```yaml
+# in config/default.yaml
+plugins:
+  - ./plugins/console
+  - ./plugins/patternMatcher
+  # - ./plugins/email
 ```
 
-Uptime currently bundles three plugins. Check their documentation for installation/configuration instructions:
+You can override these settings in your environment configuration, for instance:
 
- * [`console`](https://github.com/fzaninotto/uptime/blob/master/plugins/console/index.js): log pings and events in the console in real time
- * [`email`](https://github.com/fzaninotto/uptime/blob/master/plugins/email/index.js): notify events (up, down pause) by email
- * [`patternMatcher`](https://github.com/fzaninotto/uptime/blob/master/plugins/patternMatcher/index.js): allow HTTP & HTTPS pollers to test the response body against a pattern
+```yaml
+# in config/production.yaml
+# disable the console plugin and enable the email plugin
+plugins:
+  # - ./plugins/console
+  - ./plugins/patternMatcher
+  - ./plugins/email
+```
 
 Third-party plugins:
 
  * [`webhooks`](https://github.com/mintbridge/uptime-webhooks): notify events to an URL by sending an HTTP POST request 
  * [`campfire`](https://gist.github.com/dmathieu/5592418): notify events to Campfire
 
-You can also create your own plugins. For instance, if you had to recreate a simple version of the `console` plugin, you could write it as follows:
+Writing Plugins
+---------------
+
+A plugin is a simple Node.js module which hooks into predefined extension points. Uptime automatically requires plugin modules when starting the webapp and the monitor, and tries to call the two following functions:
+
+* `initWebApp(options)` when starting the webapp
+* `initMonitor(options)` when starting the monitor
+
+Check the [app.js](https://github.com/fzaninotto/uptime/blob/master/app.js#L97) and [monitor.js](https://github.com/fzaninotto/uptime/blob/master/monitor.js#L8) to see a detail of the options passed to each hook. Also, check the code of existing plugins to understand how they can add new pollers, new notification types, etc.
+
+For instance, if you had to recreate a simple version of the `console` plugin, you could write it as follows:
 
 ```js
 // in plugins/console/index.js
 var CheckEvent = require('../../models/checkEvent');
-exports.init = function() {
+exports.initWebapp = function() {
   CheckEvent.on('afterInsert', function(checkEvent) {
     checkEvent.findCheck(function(err, check) {
       console.log(new Date() + check.name + checkEvent.isGoDown ? ' goes down' : ' goes back up');

app.js

@@ -95,6 +95,20 @@ io.sockets.on('connection', function(socket) {
 });
 
 // load plugins
+config.plugins.forEach(function(pluginName) {
+  var plugin = require(pluginName);
+  if (typeof plugin.initWebApp !== 'function') return;
+  console.log('loading plugin %s on app', pluginName);
+  plugin.initWebApp({
+    app:       app,
+    api:       apiApp,       // mounted into app, but required for events
+    dashboard: dashboardApp, // mounted into app, but required for events
+    io:        io,
+    config:    config,
+    mongoose:  mongoose
+  });
+});
+// old way to load plugins, kept for BC
 fs.exists('./plugins/index.js', function(exists) {
   if (exists) {
     var pluginIndex = require('./plugins');

config/default.yaml

@@ -22,6 +22,11 @@ autoStartMonitor: true
 server:
   port:     8082
 
+plugins:
+  - ./plugins/console
+  - ./plugins/patternMatcher
+  # - ./plugins/email
+
 email:
   method:      SMTP  # possible methods are SMTP, SES, or Sendmail
   transport:         # see https://github.com/andris9/nodemailer for transport options

monitor.js

@@ -6,16 +6,14 @@ var Monitor = require('./lib/monitor');
 monitor = Monitor.createMonitor(config.monitor);
 
 // load plugins
-fs.exists('./plugins/index.js', function(exists) {
-  if (exists) {
-    var pluginIndex = require('./plugins');
-    if (typeof pluginIndex.initMonitor === 'function') {
-      pluginIndex.initMonitor({
-        monitor: monitor,
-        config:  config
-      });
-    }
-  }
+config.plugins.forEach(function(pluginName) {
+  var plugin = require(pluginName);
+  if (typeof plugin.initMonitor !== 'function') return;
+  console.log('loading plugin %s on monitor', pluginName);
+  plugin.initMonitor({
+    monitor: monitor,
+    config:  config
+  });
 });
 
 monitor.start();

plugins/console/index.js

@@ -3,16 +3,19 @@
  *
  * Logs all pings and events (up, down, paused, restarted) on the console
  *
- * To enable the plugin, call init() in the webapp hook in plugins/index.js
- *   exports.initWebApp = function() {
- *     require('./console').init();
- *   }
- * 
+ * Installation
+ * ------------
+ * This plugin is enabled by default. To disable it, remove its entry 
+ * from the `plugins` key of the configuration:
+ *
+ *   // in config/production.yaml
+ *   plugins:
+ *     # - ./plugins/console
  */
 var Ping = require('../../models/ping');
 var CheckEvent = require('../../models/checkEvent');
 
-exports.init = function(enableNewEvents, enableNewPings) {
+exports.initWebApp = function(enableNewEvents, enableNewPings) {
   if (typeof enableNewEvents == 'undefined') enableNewEvents = true;
   if (typeof enableNewPings == 'undefined') enableNewPings = true;
   if (enableNewEvents) registerNewEventsLogger();

plugins/email/index.js

@@ -3,12 +3,35 @@
  *
  * Notifies all events (up, down, paused, restarted) by email
  *
- * To enable the plugin, call init() in the webapp hook in plugins/index.js
- *   exports.initWebApp = function() {
- *     require('./email').init();
- *   }
+ * Installation
+ * ------------
+ * This plugin is disabled by default. To enable it, add its entry 
+ * to the `plugins` key of the configuration:
  *
- * Example configuration
+ *   // in config/production.yaml
+ *   plugins:
+ *     - ./plugins/email
+ *
+ * Usage
+ * -----
+ * This plugin sends an email each time a check is started, goes down, or goes back up. 
+ * When the check goes down, the email contains the error details:
+ *
+ *   Object: [Down] Check "FooBar" just went down
+ *   On Thursday, September 4th 1986 8:30 PM,
+ *   a test on URL "http://foobar.com" failed with the following error:
+ *
+ *     Error 500
+ *
+ *   Uptime won't send anymore emails about this check until it goes back up.
+ *   ---------------------------------------------------------------------
+ *   This is an automated email sent from Uptime. Please don't reply to it.
+ *
+ * Configuration
+ * -------------
+ * Here is an example configuration:
+ *
+ *   // in config/production.yaml
  *   email:
  *     method:      SMTP  # possible methods are SMTP, SES, or Sendmail
  *     transport:         # see https://github.com/andris9/nodemailer for transport options
@@ -32,32 +55,32 @@ var moment     = require('moment');
 var config     = require('config').email;
 var CheckEvent = require('../../models/checkEvent');
 var ejs        = require('ejs');
- 
-exports.init = function() {
+
+exports.initWebApp = function() {
   var mailer = nodemailer.createTransport(config.method, config.transport);
   var templateDir = __dirname + '/views/';
   CheckEvent.on('afterInsert', function(checkEvent) {
     if (!config.event[checkEvent.message]) return;
     checkEvent.findCheck(function(err, check) {
       if (err) return console.error(err);
       var filename = templateDir + checkEvent.message + '.ejs';
-      var renderOptions = { 
-        check: check, 
-        checkEvent: checkEvent, 
-        url: config.dashboardUrl, 
-        moment: moment, 
+      var renderOptions = {
+        check: check,
+        checkEvent: checkEvent,
+        url: config.dashboardUrl,
+        moment: moment,
         filename: filename
       };
       var lines = ejs.render(fs.readFileSync(filename, 'utf8'), renderOptions).split('\n');
       var mailOptions = {
         from:    config.message.from,
         to:      config.message.to,
         subject: lines.shift(),
-        text:    lines.join('\n'),
+        text:    lines.join('\n')
       };
       mailer.sendMail(mailOptions, function(err2, response) {
-        if (err2) return console.error(err2);
-        console.log('Notified event by email: Check ' + check.name + ' ' + checkEvent.message);      
+        if (err2) return console.error('Email plugin error: %s', err2);
+        console.log('Notified event by email: Check ' + check.name + ' ' + checkEvent.message);
       });
     });
   });

plugins/patternMatcher/index.js

@@ -3,22 +3,18 @@
  *
  * Adds the ability to HTTP & HTTPS pollers to test the response body against a pattern
  *
- * The plugin must be enabled both in the monitor and in the webapp:
+ * Installation
+ * ------------
+ * This plugin is enabled by default. To disable it, remove its entry 
+ * from the `plugins` key of the configuration:
  *
- *   // in plugins/index.js
- *   var patternMatcherPlugin = require('./patternMatcher');
+ *   // in config/production.yaml
+ *   plugins:
+ *     # - ./plugins/patternMatcher
  *
- *   exports.initWebApp = function(options) {
- *     // enable patternMatcher for the webapp
- *     patternMatcherPlugin.initWebApp(options);
- *   };
- *
- *   exports.initMonitor = function(options) {
- *     // enable patternMatcher for the monitor
- *     patternMatcherPlugin.initMonitor(options);
- *   };
- *
- * Then, restart Uptime, and add a pattern to http checks in the dashboard UI.
+ * Usage
+ * -----
+ * Add a pattern to http checks in the dashboard UI.
  * Patterns are regexp, for instance '/hello/i'.
  *
  * When Uptime polls a check with a pattern, it tests the pattern against the