From 2b9ccb6dd2ad6d10c72dfa438da28ad0b271458c Mon Sep 17 00:00:00 2001 From: Adam Brunner Date: Fri, 8 Jul 2016 15:39:08 +0200 Subject: [PATCH] docs(readme): add documentation to all middleware included in boar-server --- README.md | 189 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 137 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 72a109b..dd9cd3c 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ put these lines in your server.js var path = require('path'); var koaApp = module.exports = koa(); var config = require('./config'); - var App = require('js-stack').app; + var App = require('boar-server').app; var app = new App(koaApp); app.connectToMongoose(config.mongooseUri); @@ -20,6 +20,7 @@ put these lines in your server.js if (!module.parent) { app.listen(config.port); } ``` + ## Add middleware for your app ``` javascript var cors = require('koa-cors'); @@ -27,47 +28,134 @@ put these lines in your server.js app.addMiddleware(cors()); ``` -## Lib +## HTTPS support +To enable HTTPS support, simple create `SERVE_HTTPS` environment variable with value `true`. +The port for https will be the port of the application increased with 10000 (10k). + +If you want to serve the requests with your own SSL certification, create `HTTPS_KEY` and `HTTPS_CERT` +environment variables with path of the files as values. + +### Example +``` +export SERVE_HTTPS=true +export HTTPS_KEY="path/to/cert.key" +export HTTPS_CERT="path/to/cert.crt" + +node server.js +``` + +## Build-in Middlewares + +### Cors Support ([koa-cors](https://github.com/evert0n/koa-cors)) -### Mask email address ``` javascript + app.addCorsSupportMiddleware(); +``` + +### Static Content ([koa-static](https://github.com/koajs/static)) - var masEmailAddress = require('js-stack').lib.maskEmailAddress; - masEmailAddress('test@gmail.com'); - +| Param | Type | Description | +| ----- | ----- | ----------- | +| __path__ | `String` | Path to the static content's folder | + +``` javascript + app.addStaticContentMiddleware(path); ``` -### Real ip address (in heroku) + +### Dynamic View + +This middleware is a wrapper for [koa-jade](https://github.com/chrisyip/koa-jade). + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __path__ | `String` | Path to the jade files | + ``` javascript - var realIpAddress = require('js-stack').lib.realIpAddress; - realIpAddress(request); + app.addDynamicViewMiddleware(path); ``` -### ControllerFactory + +### Method Override ([koa-methodoverwrite](https://github.com/koa-modules/methodoverride)) + ``` javascript - var ControllerFactory = require('js-stack.lib.controllerFactory'); + app.addMethodOverrideMiddleware(); +``` - module.exports = ControllerFactory.create(function(router) { - router.get('/', ControllerFactory.load('main/actions/get')); - router.get('/healthcheck', ControllerFactory.load('main/actions/healthcheck/get')); - router.get('/list', ControllerFactory.loadByAcceptType('main/actions/list/get')); - }); +### Error Handler + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __path__ | `String` | Path to error page jade template | + +``` javascript + app.addErrorHandlerMiddleware(path); ``` -### SecurityMiddlewareFactory -Provides middlewares for setting up various security related HTTP headers. +### Body Parse ([koa-bodyparser](https://github.com/koajs/body-parser)) + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __options__ | `Object` | [More info.](https://github.com/koajs/bodyparser#options) | ``` javascript - var app = new App(koaApp); + app.addBodyParseMiddleware(options); +``` + +### Request Id ([koa-requestid](https://github.com/seegno/koa-requestid)) + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __options__ | `Object` | _optional_ | +| ↳header | `String` | The name of the header to read the id on the request, `false` to disable. | +| ↳query | `String` | The name of the header to read the id on the query string, `false` to disable. | +| ↳expose | `String` | The name of the header to expose the id on the response, `false` to disable. | - app.addSecurityMiddlewares(); +``` javascript + app.addRequestIdmiddleware(options); ``` -#### Configuration -Sample configuration with default values: +### Enforce SSL ([koa-ssl](https://github.com/jclem/koa-ssl)) + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __options__ | `Object` | [More info.](https://github.com/jclem/koa-ssl#use) | + +``` javascript + app.addEnforceSSLMiddleware(); +``` +If your application is running behind reverse proxy you should set the trustProxy configiration option for detecting the x-forwarded-proto header. ``` javascript var app = new App(koaApp); + app.addEnforceSSLMiddleware({ trustProxy: true }); +``` + +__Note__: if you use this middleware EnforceSSL middleware should be the first you add. + + +### Hook + +``` javascript + app.addHookMiddleware(); +``` - app.addSecurityMiddlewares({ +### Security +Provides middlewares for setting up various security related HTTP headers. + +| Param | Type | Description | +| ----- | ----- | ----------- | +| __options__ | `Object` | | +| ↳csp | `Object` | [More info.](https://github.com/helmetjs/csp) Learn more: [CSP quick reference](http://content-security-policy.com/) | +| ↳hsts | `Object` | [More info.](https://github.com/helmetjs/hsts) Learn more: [OWASP HSTS page](https://www.owasp.org/index.php/HTTP_Strict_Transport_Security) | +| ↳useXssFilter | `Boolean` | If `true`, [x-xss-protection](https://github.com/helmetjs/x-xss-protection) middleware will be included. Default: `true` | +| ↳useNoSniff | `Boolean` | If `true`, [dont-sniff-mimetype](https://github.com/helmetjs/dont-sniff-mimetype) middleware will be included. Default: `true` | + +``` javascript + app.addSecurityMiddlewares(options); +``` + +#### Default configuration +``` javascript + { csp: { directives: { defaultSrc: ["'self'"], @@ -86,44 +174,41 @@ Sample configuration with default values: }, useXssFilter: true, useNoSniff: true - }); + } ``` -#### Middlewares -1. csp: See [helmetjs CSP middleware](https://github.com/helmetjs/csp), [CSP quick reference](http://content-security-policy.com/) -2. hsts: See [helmetjs HSTS middleware](https://github.com/helmetjs/hsts), [OWASP HSTS page](https://www.owasp.org/index.php/HTTP_Strict_Transport_Security) -3. xss: See [helmetjs X-XSS-Protection middleware](https://github.com/helmetjs/x-xss-protection) -4. noSniff: See [helmetjs "Don't infer the MIME type" middleware](https://github.com/helmetjs/dont-sniff-mimetype) +## Libraries -## HTTPS support -To enable HTTPS support, simple create `SERVE_HTTPS` environment variable with value `true`. -The port for https will be the port of the application increased with 10000 (10k). - -If you want to serve the requests with your own SSL certification, create `HTTPS_KEY` and `HTTPS_CERT` -environment variables with path of the files as values. - -### Example +### Mask email address +``` javascript + var maskEmailAddress = require('boar-server').lib.maskEmailAddress; + maskEmailAddress('test@gmail.com'); ``` -export SERVE_HTTPS=true -export HTTPS_KEY="path/to/cert.key" -export HTTPS_CERT="path/to/cert.crt" -node server.js +### Real ip address (in heroku) +``` javascript + var realIpAddress = require('boar-server').lib.realIpAddress; + realIpAddress(request); ``` -### Enforce HTTPS +### ControllerFactory +``` javascript + var ControllerFactory = require('boar-server.lib.controllerFactory'); -Add the [koa-ssl](https://github.com/jclem/koa-ssl) middlware: -``` - var app = new App(koaApp); - app.addEnforceSSLMiddleware(); + module.exports = ControllerFactory.create(function(router) { + router.get('/', ControllerFactory.load('main/actions/get')); + router.get('/healthcheck', ControllerFactory.load('main/actions/healthcheck/get')); + router.get('/list', ControllerFactory.loadByAcceptType('main/actions/list/get')); + }); ``` -If your application is running behind reverse proxy you should set the trustProxy configiration option for detecting the x-forwarded-proto header. -``` - var app = new App(koaApp); - app.addEnforceSSLMiddleware({ trustProxy: true }); -``` +### ClearCollection + +### ClearGridfs + +### Database + +Wrapper for mongoose connection. -If you use this middleware this middleware should be the first you add. +### ExceptionHandler