Skip to content

Commit

Permalink
docs(readme): add documentation to all middleware included in boar-se…
Browse files Browse the repository at this point in the history 
…rver
  • Loading branch information
Adam Brunner committed Jul 8, 2016
1 parent b74e3e6 commit 2b9ccb6
Showing 1 changed file with 137 additions and 52 deletions.
189 changes: 137 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -20,54 +20,142 @@ 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');
var app = new App(koaApp);
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'"],
Expand All @@ -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

0 comments on commit 2b9ccb6

Please sign in to comment.