search close

Node.js Module Install

access_time Updated Jun 29, 2022

Compatibility

The Signal Sciences Node.js module is compatible with Node 0.10 through 12.X. All dependencies are specified in the npm-shrinkwrap.json file.

Installation

Install the latest version from npmjs.com:

npm install sigsci-module-nodejs

For specific releases prior to 1.5.3, installation can be performed from the release archive. Replace <VERSION> with the specific version number:

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

See the package archive for a list of available versions.

Usage

How to incorporate the Signal Sciences Node.js module will depend on your application.

If your application invokes http.createServer directly, use the native API.

  1. Above your application code, import the Signal Sciences Node.js module by adding the following lines:

    var Sigsci = require('sigsci-module-nodejs')
    
    // Your application code
    
  2. Below your application code, create a Sigsci object:

    // Your application code
    
    var sigsci = new Sigsci({
     path: '/var/run/sigsci.sock'
     // Other parameters here
    })
    
  3. Wrap the dispatcher with sigsci.wrap. Replace the http.createServer(dispatcher).listen(8085, '127.0.0.1') line with:

    http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')
    

Example

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

// Your application code

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

http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')

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

  1. Above your application code, import the Signal Sciences Node.js module by adding the following lines:

    var Sigsci = require('sigsci-module-nodejs')
    
    // Your application code
    
  2. Below your application code, create a Sigsci object:

    // Your application code
    
    var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
    // other parameters here
    })
    
  3. Below the var app = express() line, insert the Node.js module middleware:

    var app = express()
    app.use(sigsci.express())
    
    // You can still call other middleware and routes
    app.use(...)
    app.get('/route', ...)
    

Example

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

// Your application code

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

var app = express()
app.use(sigsci.express())

// You can still call other middleware and routes
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 v17 & v18

At the top of your application, add the following:

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();

At the top of your application, add the following:

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 KOA

At the top of your application, add the following:

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);

Configuration

You can module configuration options directly in the Sigsci object:

var sigsci = new Sigsci({
path: '/var/run/sigsci.sock'
...
})
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))

Additional details and default values are available in the SigSci.js file.

Next Steps

Explore other installation options: