Creating a new module

This document describes the steps required to create a new example module mod_test for Breach.

Create a public github repository

First, we create a new public github repository for our module. In our case: breach/mod_test. We'll then initialize the content of the repository with a package.json file at the root of the module:

{                                                                               
  "name": "mod_test",                                                          
  "version": "0.1.0",                                                           
  "main": "./index.js",                                                         
  "dependencies": {                                                             
    "breach_module": "0.3.x",                                                   
    "async": "0.9.x",                                                           
    "request": "2.36.x"                                                         
  }                                                                             
}        

The package.json describes the module using nodeJS npm's conventions. Breach module management is based on npm for dependency management. What characterize a Breach module compared to any other npm module is the presence of the breach_module dependency which works only when run from within Breach as a module and exposes its API to the module.

Initialization and Destruction

Now we'll create the main script index.js. A Breach module must expose a init and kill function for initialization and destruction. The module is in charge of killing its own process when kill is called (otherwise Breach will attempt to kill it 5s after calling the kill method):

/*
 * Breach: [mod_test] index.js
 *
 * Copyright (c) 2014, Stanislas Polu. All rights reserved.
 *
 * @author: spolu
 *
 * @log:
 * - 2014-06-26 spolu   Creation
 */
'use strict';

var breach = require('breach_module');

breach.init(function() {
  breach.expose('init', function(src, args, cb_) {
    console.log('Initialization');
    return cb_();
  });
  
  breach.expose('kill', function(args, cb_) {
    common.exit(0);
  });
});

process.on('uncaughtException', function (err) {
  common.fatal(err);
});

This module does not serve any purpose, but it is already fully functional and able to run within Breach.

The init and kill methods must be exposed within the breach.init function callback so that the core_module can properly synchronize the call to your init procedure and let you time to do some work before if needed. Basically the call to breach.init will send a message to the core_module which will then call your init procedure if defined.

Running the module for the first time

Open Breach, and navigate to the module manager (breach://modules). This is more or less what you should be seing:

From there you can install and run the local version of your module by entering a local path in the install input bar (local:~/path/to/your/module)

Click install and your module should be running!

You can now access the output of your module directly from the module manager. To do so, click on the out action next to your module name. There, you check that your module init function was indeed called:

This module output page is very useful for debugging modules. You can also directly access the file containing all the module logs from the path displayed at the top of the page.

Debugging the module

If you restart the module from the output page, you ought to notice that it dumps a stack trace caused by a reference to a missing file, common.js. To fix the bug, first download a copy of the common.js library into the lib folder.

$ mkdir lib
$ wget -P ./lib https://raw.githubusercontent.com/breach/mod_strip/master/lib/common.js

Then, add the line var common = require("./lib/common.js") to index.js. Now, after you reload the module it should be able to be restarted without raising an error.

Adding functionalities

You can now add functionalities to the module. To do so, please refer to:

• Breach Modular Architecture

Publishing the module

Publishing the module is as easy as pushing your code to your GitHub repository. Once this is done, the module will be publicly available from the module manager under the path: github:{author}/{repository} (in our case: github:breach/mod_test)