# boomcatch A standalone, node.js-based beacon receiver for [boomerang]. [Read more][blog]. ![Build Status](https://github.com/springernature/boomcatch/actions/workflows/test.yml/badge.svg) * **boomcatch version**: *3.2.5* * **node.js versions**: *0.10 and later* ## Installation ### At the system level First you must [install node][node]. You can then install boomcatch via npm: ```sh npm install -g boomcatch ``` ### Local to a node.js project Add boomcatch to the dependencies in your project's `package.json`, then run: ```sh npm install ``` ## Usage ### From the command line To see the list of command line options run: ```sh boomcatch --help ``` Available options are: * `--host `: Host name to accept HTTP connections on. The default is 0.0.0.0 (INADDR_ANY). * `--port `: Port to accept HTTP connections on. Defaults to 80 for HTTP or 443 for HTTPS. * `--https`: Start the server in HTTPS mode. * `--httpsPfx`: PFX/PKCX12 string containing the private key, certificate and CA certs for HTTPS mode. * `--httpsKey`: Path to private key file for HTTPS mode. Ignored if `--httpsPfx` is set. * `--httpsCert`: Path to certificate file for HTTPS mode. Ignored if `--httpsPfx` is set. * `--httpsPass`: Passphrase for `--httpsPfx` or `--httpsKey` options. * `--path `: URL path to accept requests to. The default is /beacon. * `--referer `: HTTP referers to accept requests from. The default is `.*`. * `--origin `: Comma-separated list of URL(s) for the Access-Control-Allow-Origin header. The default is * (any origin), specify 'null' to force same origin. * `--limit `: Minimum elapsed time to allow between requests from the same IP address. The default is 0. * `--maxSize `: Maximum body size to allow for POST requests. The default is -1 (unlimited). * `--silent`: Prevent the command from logging output to the console. * `--syslog `: Use [syslog]-compatible logging, with the specified facility level. * `--workers `: The number of worker processes to spawn. The default is -1 (one worker per CPU). * `--delayRespawn `: The length of time to delay before respawning worker processes. The default is 0. * `--maxRespawn `: The maximum number of times to respawn worker processes. The default is -1 (unlimited). * `--validator `: Validator used to accept or reject request data. The default is permissive (always accept requests). * `--mapper `: Data mapper used to transform data before forwarding, loaded with [require]. The default is statsd. * `--prefix `: Prefix for mapped metric names. The default is the empty string (no prefix). * `--forwarder `: Forwarder used to send data, loaded with require. The default is udp. * `--fwdHost `: Host name to forward mapped data to. The default is 127.0.0.1. This option is only effective with the UDP forwarder. * `--fwdPort `: Port to forward mapped data on. The default is 8125. This option is only effective with the UDP forwarder. * `--fwdSize `: Maximum packet size for forwarded data. The default is 512. This option is only effective with the UDP forwarder. * `--fwdUrl `: URL to forward mapped data to. This option is only effective with the HTTP forwarder. * `--fwdMethod `: Method to forward mapped data with. The default is GET. This option is only effective with the HTTP forwarder. * `--fwdDir `: Directory to write mapped data to. This option is only effective with the file forwarder. ### From a node.js project ```javascript var path = require('path'); var boomcatch = require('boomcatch'); boomcatch.listen({ host: 'rum.example.com', // Defaults to '0.0.0.0' (INADDR_ANY) port: 8080, // Defaults to 80 for HTTP or 443 for HTTPS https: true, // Defaults to false httpsKey: 'foo.key', httpsCert: 'bar.cert', httpsPass: 'baz', path: '/perf', // Defaults to '/beacon' referer: /^\w+\.example\.com$/, // Defaults to /.*/ origin: [ // Defaults to '*' 'http://foo.example.com', 'http://bar.example.com' ], limit: 100, // Defaults to 0 maxSize: 1048576, // Defaults to -1 log: console, // Defaults to object with `info`, `warn` and `error` log functions. workers: require('os').cpus().length, // Defaults to 0 validator: path.resolve('./myvalidator'), // Defaults to 'permissive' mapper: path.resolve('./mymapper'), // Defaults to 'statsd' prefix: 'mystats.rum.', // Defaults to '' forwarder: 'http', // Defaults to 'udp' fwdUrl: 'https://stats.example.com/', // No default fwdMethod: 'POST' // Defaults to 'GET' }); ``` ## Extensions Boomcatch implements four extension points to control how beacon requests are handled: validators, filters, mappers and forwarders. These extension points are invoked as a pipeline when a beacon request is received. ![boomcatch extensions' diagram](https://github.com/springernature/boomcatch/blob/master/doc/boomcatch-extensions.png) Several extensions are shipped as part of Boomcatch, or you can implement your own custom extensions. You can read more details in the [documentation about extensions][extensions]. ## Development Before submitting any pull requests, please ensure that you have adhered to the [contribution guidelines][contrib]. To clone the repository: ```sh git clone git@github.com:nature/boomcatch.git ``` To set up the development environment: ```sh npm install ``` To lint the code: ```sh npm run lint ``` To run the unit tests: ```sh npm test ``` ## Change log [History] ## Support You can have a look at the [Springer Nature Frontend Playbook][support] for an explanation of how we support our open source projects. ## License [GPL 3][license] Copyright © 2014, 2015, 2016 Springer Nature [boomerang]: https://github.com/lognormal/boomerang [blog]: http://cruft.io/posts/introducing-boomcatch/ [node]: http://nodejs.org/download/ [syslog]: http://en.wikipedia.org/wiki/Syslog [require]: http://nodejs.org/api/globals.html#globals_require [extensions]: doc/extensions.md [contrib]: CONTRIBUTING.md [history]: HISTORY.md [support]: https://github.com/springernature/frontend/blob/master/practices/open-source-support.md [license]: COPYING