search close

Node.js Module Install

access_time Updated Sep 21, 2021

Compatibility

This is compatible with Node 0.10 to 12.X. All dependencies are explicitly specified in the npm-shrinkwrap.json file.

Installation

One may install the latest version from npmjs.com using:

npm install sigsci-module-nodejs

For specific releases prior to 1.5.3, installation can be performed from the release archive:

npm install https://dl.signalsciences.net/sigsci-module-nodejs/<VERSION>/sigsci-module-nodejs-<VERSION>.tgz

See the package archive for a list of versions.

Usage For Native Applications

Use the native API if your application invokes http.createServer directly. Adding Signal Sciences involves:

  1. Importing the sigsci module
  2. Creating a SigSci object, adding or overriding any parameters.
  3. Wrapping your native dispatcher
    // Import sigsci module
    var Sigsci = require('sigsci-module-nodejs')
    
    // your code
    
    // 2. Create a SigSci object
    var sigsci = new Sigsci({
     path: '/var/run/sigsci.sock'
     // other parameters here
    })
    
    // 3. Wrap dispatcher with sigsci.wrap
    
    // WAS http.createServer(dispatcher).listen(8085, '127.0.0.1')
    
    http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')
    

Usage For Node.js Express

The Node.js express module is exposed as a express middleware and is typically inserted as the first middleware, right after the var app = express() statement . See the express Using Middleware documentation for more details.

In particular, adding Signal Sciences involves:

  1. Importing the sigsci module
  2. Creating a SigSci object, adding or overriding any parameters.
  3. Inserting the SigSci module
    // Import sigsci module
    var Sigsci = require('sigsci-module-nodejs')
    
    // your code
    
    // 2. Create a SigSci object
    var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
    // other parameters here
    })
    
    // 3. Insert the SigSci module middleware right after the express app is created.
    
    // WAS
    // var app = express()
    //
    // Other routes and middleware
    // app.use(...)
    // app.get('/route', ...)
    
    
    // NEW
    var app = express()
    app.use(sigsci.express())   // NEW
    
    // continue with existing routes and middleware
    app.use(...)
    app.get('/route', ...)
    

Usage For Node.js Restify

Installing the Signal Sciences module for Restify is similar to Node.js, except that 404 errors are handled differently in Restify. For best results, Signal Sciences should hook into the NotFound event. See the Restify node server api for more details.

Usage for Node.js Hapi v14

Add to the top of the file:

var Sigsci = require('sigsci-module-nodejs')

var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
    // see other options below
})
// Creating a Server
const Hapi = require('hapi')
const server = Hapi.Server({
    port: 8085
});
// Add SigSci request lifecycle methods, e.g.
// server.route({
//  method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
//  path: '/dynamic/response',
//  handler: responseHandler
// })

server.ext('onRequest', sigsci.hapi14())
server.on('response', sigsci.hapiEnding())
server.start((err) => {
 if (err) {
   throw err
 }
 console.log('Server running at:', server.info.uri)
})

Usage for Node.js Hapi v17 & v18

Add to the top of the file:

var Sigsci = require('sigsci-module-nodejs')
const Hapi = require('@hapi/hapi')

var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
    // see other options below
})
const init = async() => {
 // Creating a server
 const server = Hapi.Server({
   port: 8085
 });

 server.ext('onRequest', sigsci.hapi17())
 server.events.on('response', sigsci.hapiEnding())
 // Add SigSci request lifecycle methods, e.g.
 // server.route({
 //   method: ['POST', 'PUT', 'PATCH', 'DELETE'],
 //   config: {
 //     payload: {
 //       parse: false,
 //       maxBytes: 10 * 1024 * 1024,
 //       output: 'data'
 //     }
 //   },
 //   path: '/response',
 //   handler: responseHandler
 // })
};
init();

Usage for Node.js KOA

Add to the top of the file:

const Koa = require('koa');
const Router = require('koa-router');
var Sigsci = require('sigsci-module-nodejs')
const server = new Koa();
const router = new Router();
var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
// see other options below
})

// add lifecycle methods here
// var dispatcher = async function (ctx) {
//     let req = ctx.req
//     let res = ctx.res
       // add your code here
// }

// setup your endpoints here
// router.all('/response', dispatcher)

server.use(sigsci.koa())
server.use(router.routes())

server.listen(8085);

Parameters

One can pass various parameters to SigSci object:

var sigsci = new Sigsci({
path: '/var/run/sigsci.sock'
// other parameters here
})

The most important ones are listed here. See the file SigSci.js for more details and default values.

Name Description
port Specifies the port to connect to the agent via TCP.
host Specifies the IP address to connect to the agent via TCP (optional). Default: localhost
path Specifies the Unix Domain Socket to connect to the agent via UDS.
socketTimeout Number of milliseconds to wait for a response from the agent. After this time the module allows the original request to pass (i.e. fail open).
maxPostSize Controls the maximum size in bytes of a POST body that is sent to the agent. If the body is larger than this value, the post body is not sent to the agent. This allows control over performance (larger POST bodies take longer to process) and to prevent DoS attacks.
log The function to use to log error messages. By default it will be something to the effect of: function (msg) { console.log(util.format('SIGSCI %s', msg))

Next Steps

Explore other installation options: