• Stars
    star
    4,948
  • Rank 8,433 (Top 0.2 %)
  • Language
    JavaScript
  • License
    Other
  • Created about 11 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An express-based Node.js web application bootstrapping module.

kraken-js

kraken.js

Build Status Greenkeeper badge

Kraken builds upon express and enables environment-aware, dynamic configuration, advanced middleware capabilities, security, and app lifecycle events. For more information and examples check out krakenjs.com

Table of Contents

Basic Usage

'use strict';

var express = require('express'),
    kraken = require('kraken-js');

var app = express();
app.use(kraken());
app.listen(8000);

API

kraken([options])

kraken-js is used just like any normal middleware, however it does more than just return a function; it configures a complete express 4 application. See below for a list of features, but to get started just use it like middleware.

app.use(kraken());
// or to specify a mountpath for your application:
// app.use('/mypath', kraken());

// Note: mountpaths can also be configured using the
// `express:mountpath` config setting, but that setting
// will be overridden if specified in code.

Options

Pass the following options to kraken via a config object such as this:

var options = {
    onconfig: function (config, callback) {
        // do stuff
        callback(null, config);
    }
};

// ...

app.use(kraken(options));

Note: All kraken-js configuration settings are optional.

basedir (String, optional)

The working directory for kraken to use. kraken loads configuration files, routes, and registers middleware so this directory is the path against all relative paths are resolved. The default value is the directory of the file that uses kraken, which is generally index.js (or server.js).

onconfig (Function, optional)

Provides an asynchronous hook for loading additional configuration. When invoked, a confit configuration object containing all loaded configuration value passed as the first argument, and a callback as the second. The signature of this handler is function (config, callback) and the callback is a standard error-back which accepts an error as the first argument and the config object as the second, e.g. callback(null, config).

protocols (Object, optional)

Protocol handler implementations for use when processing configuration. For more information on protocols see shortstop and shortstop-handlers. By default, kraken comes with a set of shortstop protocols which are described in the "Config Protocols" section below, but you can add your own by providing an object with the protocol names as the keys and their implementations as properties, for example:

var options = {
    protocols: {
        file: function file(value, callback) {
            fs.readFile(value, 'utf8', callback);
        }
    }
};

onKrakenMount (Function, optional)

Provides a synchronous hook which executes once kraken mounts. It takes an express app instance as the first argument, and options as the second. The signature of this handler is function (app, options).

uncaughtException (Function, optional)

Handler for uncaughtException errors outside of the middleware chain. See the endgame module for defaults.

For uncaught errors in the middleware chain, see shutdown middleware instead.

confit (Object, optional)

In rare cases, it may be useful to pass options directly to the confit module used within lib/config.js. For example, if confit/shortstop is conflicting with environment variables, you can explicitly ignore those environment variables:

var options = {
    confit: {
        envignore: ['troublesome_environment_variable']
    }
};

Config Protocols

kraken comes with the following shortstop protocol handlers by default:

import:

Merge the contents of the specified file into configuration under a given key.

{
    "foo": "import:./myjsonfile"
}

config:

Replace with the value at a given key. Note that the keys in this case are dot (.) delimited.

{
    "foo": {
        "bar": true
    },
    "foobar": "config:foo.bar"
}

path:

The path handler is documented in the shortstop-handlers repo.

file:

The file handler is documented in the shortstop-handlers repo.

base64:

The base64 handler is documented in the shortstop-handlers repo.

env:

The env handler is documented in the shortstop-handlers repo.

require:

The require handler is documented in the shortstop-handlers repo.

exec:

The exec handler is documented in the shortstop-handlers repo.

glob:

The glob handler is documented in the shortstop-handlers repo.

resolve:

The resolve handler is documented in the shortstop-resolve repo.

Features

Configuration

Environment-aware

Using environment suffixes, configuration files are applied and overridden according to the current environment as set by NODE_ENV. The application looks for a ./config directory relative to the basedir and looks for config.json as the baseline config specification. JSON files matching the current env are processed and loaded. Additionally, JSON configuration files may contain comments.

Valid NODE_ENV values are undefined or dev[elopment] (uses development.json), test[ing] (uses test.json), stag[e|ing] (uses staging.json), prod[uction] (uses config.json). Simply add a config file with the name, to have it read only in that environment, e.g. config/development.json.

Middleware

Much like configuration, you shouldn't need to write a lot of code to determine what's in your middleware chain. meddleware is used internally to read, resolve, and register middleware with your express application. You can either specify the middleware in your config.json or {environment}.json, (or) import it from a separate json file using the import protocol mentioned above.

Included Middleware

Kraken comes with common middleware already included in its config.json file. The following is a list of the included middleware and their default configurations which can be overridden in your app's configuration:

  • "shutdown" - internal middleware which handles graceful shutdowns in production environments
    • Priority - 0
    • Enabled - true if not in a development environment
    • Module - "kraken-js/middleware/shutdown"
      • Arguments (Array)
        • Object
          • "timeout" - milliseconds (default: 30000)
          • "template" - template to render (default: null)
          • "shutdownHeaders" - custom headers to write while still disconnecting.
          • "uncaughtException" - custom handler - function (error, req, res, next) - for uncaught errors. Default behavior is to log the error and then trigger shutdown.
  • "compress" - adds compression to server responses
    • Priority - 10
    • Enabled - false (disabled in all environments by default)
    • Module - "compression" (npm)
  • "favicon" - serves the site's favicon
    • Priority - 30
    • Module - "serve-favicon" (npm)
      • Arguments (Array)
        • String - local path to the favicon file (default: "path:./public/favicon.ico")
  • "static" - serves static files from a specific folder
    • Priority - 40
    • Module - "serve-static" (npm)
      • Arguments (Array)
        • String - local path to serve static files from (default: "path:./public")
  • "logger" - logs requests and responses
    • Priority - 50
    • Module - "morgan" (npm)
      • Arguments (Array)
        • String - log format type (default: "combined")
  • "json" - parses JSON request bodies
    • Priority - 60
    • Module - "body-parser" (npm)
      • Method - "json"
  • "urlencoded" - parses URL Encoded request bodies
    • Priority - 70
    • Module - "body-parser" (npm)
      • Method - "urlencoded"
      • Arguments (Array)
        • Object
          • "extended" (Boolean) - parse extended syntax with the qs module (default: true)
  • "multipart" - parses multipart FORM bodies
    • Priority - 80
    • Module - "kraken-js/middleware/multipart" (delegates to formidable)
  • "cookieParser" - parses cookies in request headers
    • Priority - 90
    • Module - "cookie-parser" (npm)
      • Arguments (Array)
        • String - secret used to sign cookies (default: "keyboard cat")
  • "session" - maintains session state
    • Priority - 100
    • Module - "express-session" (npm)
      • Arguments (Array)
        • Object
          • "key" (String) - cookie name (default: "connect.sid")
          • "secret" (String) - secret used to sign session cookie (default: "keyboard cat")
          • "cookie" (Object) - describing options for the session cookie
            • "path" (String) - base path to verify cookie (default: "/")
            • "httpOnly" (Boolean) - value indicating inaccessibility of cookie in the browser (default: true)
            • "maxAge" (Number) - expiration of the session cookie (default: null)
          • "resave" (Boolean) - value indicating whether sessions should be saved even if unmodified (default: true)
          • "saveUninitialized" (Boolean) - value indicating whether to save uninitialized sessions (default: true)
          • "proxy" (Boolean) - value indicating whether to trust the reverse proxy (default: null, inherit from express)
  • "appsec" - secures the application against common vulnerabilities (see Application Security below)
    • Priority - 110
    • Module - "lusca" (github)
      • Arguments (Array)
        • Object
          • "csrf" (Boolean|Object) - value indicating whether to require CSRF tokens for non GET, HEAD, or OPTIONS requests, or an options object to configure CSRF protection (default: true)
          • "xframe" (String) - value for the X-Frame-Options header (default: "SAMEORIGIN")
          • "p3p" (String|Boolean) - the Compact Privacy Policy value or false if not used (default: false)
          • "csp" (Object|Boolean) - options configuring Content Security Policy headers or false if not used (default: false)
  • "router" - routes traffic to the applicable controller
    • Priority - 120
    • Module - "express-enrouten" (npm)
      • Arguments (Array)
        • Object
          • "index" (String) - path to the single file to load (default: "path:./routes")

Additional notes:

  • The session middleware defaults to using the in-memory store. This is not recommended for production applications and the configuration should be updated to use a shared resource (such as Redis or Memcached) for session storage.
  • You can change the routes which are affected by the middleware by providing a top-level option of route. In express deployments, it is common to re-route where static files are served which can be accomplished like so:
// include this in your own config.json and this will merge with the Kraken defaults
// NB: if you use kraken-devtools you must re-route that as well in development.json!
{
    "static": {
        "route": "/static"
    }
}

Extending Default Middleware

In any non-trivial Kraken deployment you will likely need to extend the included middleware. Common middleware which need extension include cookie parsing and session handling. In those particular cases, the secrets used should be updated:

{
    // include this in your own config.json and this will merge with the Kraken defaults
    "middleware": {

        "cookieParser": {
            "module": {
                "arguments": [ "your better secret value" ]
            }
        },

        "session": {
            "module": {
                // NB: arrays like 'arguments' are not merged but rather replaced, so you must
                //     include all required configuration options here.
                "arguments": [
                    {
                        "secret": "a much better secret",
                        "cookie": {
                            "path": "/",
                            "httpOnly": true,
                            "maxAge": null
                        },
                        "resave": true,
                        "saveUninitialized": true,
                        "proxy": null
                    }
                ]
            }
        }

    }
}

Another common update is to pass options to middleware which is configured only with the defaults, such as the compression middleware:

{
    "middleware": {
        "compress": {
            "enabled": true,    // response compression is disabled by default
            "module": {
                "arguments": [
                    {
                        // 512 byte minimum before compressing output
                        "threshold": 512
                    }
                ]
            }
        }
    }
}

More complicated examples include configuring the session middleware to use a shared resource, such as connect-redis. This requires a few extra steps, most notably creating your own middleware to handle the registration (see totherik/redis-example for a complete example):

  1. Overlay the existing session middleware in your configuration:
{
    // in your config.json
    "middleware": {
        "session": {
            "module": {
                // use your own module instead
                "name": "path:./lib/middleware/redis-session",
                "arguments": [
                    // express-session configuration
                    {
                        "secret": "a much better secret",
                        "cookie": {
                            "path": "/",
                            "httpOnly": true,
                            "maxAge": null
                        },
                        "resave": true,
                        "saveUninitialized": true,
                        "store": null    // NB: this will be overlaid in our module
                    },
                    // connect-redis configuration
                    {
                        "host": "localhost",
                        "port": 6379,
                        "prefix": "session:"
                    }
                ]
            }
        }
    }
}
  1. Add your custom middleware for Kraken to configure:
// ./lib/middleware/redis-session.js
'use strict';

var session = require('express-session'),
    RedisStore = require('connect-redis')(session);

/** Creates a REDIS-backed session store.
 *
 * @param {Object} [sessionConfig] Configuration options for express-session
 * @param {Object} [redisConfig] Configuration options for connect-redis
 * @returns {Object} Returns a session middleware which is backed by REDIS
 */
module.exports = function (sessionConfig, redisConfig) {

    // add the 'store' property to our session configuration
    sessionConfig.store = new RedisStore(redisConfig);

    // create the actual middleware
    return session(sessionConfig);
};

Application Security

Kraken uses lusca to secure your applications, so that you don't need to think about it. Techniques like CSRF, XFRAMES, and CSP are enabled automatically while others can be opted into. All are customizable through configuration.

Lifecycle Events

Kraken adds support for additional events to your express app instance:

  • start - the application has safely started and is ready to accept requests
  • shutdown - the application is shutting down, no longer accepting requests
  • stop - the http server is no longer connected or the shutdown timeout has expired

Configuration-based express Settings

Since express instances are themselves config objects, the convention is to set values on the app instance for use by express internally as well as other code across the application. kraken-js allows you to configure express via JSON. Any properties are supported, but kraken-js defaults include:

{
    "express": {
        "env": "", // NOTE: `env` is managed by the framework. This value will be overwritten.
        "x-powered-by": false,
        "trust proxy": false,
        "jsonp callback name": null,
        "json replacer": null,
        "json spaces": 0,
        "case sensitive routing": false,
        "strict routing": false,
        "view cache": true,
        "view engine": null,
        "views": "path:./views",
        "route": "/"
    }
}

Additional notes:

  • The env setting will be set to the environment value as derived by kraken-js, so what is put here will be overwritten at runtime.
  • Set the view engine property to the one of the view engines property names (see the section View Engine Configuration) to enable it for template rendering.
  • The optional view property is a special case in which you can set a path to a module which exports a constructor implementing the view API as defined by the module express/lib/view. If set, kraken-js will attempt to load the specified module and configure express to use it for resolving views.

For example:

{
    "express": {
        "view": "path:./lib/MyCustomViewResolver"
    }
}

View Engine Configuration

kraken-js looks to the view engines config property to understand how to load and initialize renderers. The value of the view engines property is an object mapping the desired file extension to engine config settings. For example:

{
    "view engines": {
        "jade": {
            "module": "consolidate"
        },
        "html": {
            "name": "ejs",
            "module": "ejs",
            "renderer": "renderFile"
        },
        "dust": {
            "module": "adaro",
            "renderer": {
                "method": "dust",
                "arguments": [{
                    "cache": false,
                    "helpers": ["dust-helpers-whatevermodule"]
                }]
            }
        },
        "js": {
            "module": "adaro",
            "renderer": {
                "method": "js",
                "arguments": [{ "cache": false }]
            }
        }
    }
}

The available engine configuration options are:

  • module (String) - This is the node module that provides the renderer implementation. The value can be the name of a module installed via npm, or it can be a module in your project referred to via file path, for example "module": "path:./lib/renderer".
  • name (String, optional) - Set this if the name of the rendering engine is different from the desired file extension. For example, you chose to use ejs, but want to use the "html" file extension for your templates. Additionally, if the renderer function exported by the module is not the file extension and a "renderer" property is not defined, this value will be used.
  • renderer (String|Object, optional) - The renderer property allows you to explicitly identify the property or the factory method exported by the module that should be used when settings the renderer. Set the value to a String to identify that the renderer is exported by that name, or an object with the properties "method" and "arguments" to identify a factory method. For example, using ejs you could set this property to "renderFile" or "__express" as the ejs module exports a renderer directly.

Tests

$ npm test

Coverage

$ npm run-script cover && open coverage/lcov-report/index.html

Reading app configs from within the kraken app

There are two different ways. You can

  • Read it in your onconfig handler as mentioned above.
function (config, callback) {
    var value = config.get('<key>');
    ...
    ...
    callback(null, config);
}
  • Read it off the req object by doing req.app.kraken.get('<config-key>'). So it would look like:
router.get('/', function (req, res) {
    var value = req.app.kraken.get('<key>');
    ...
    ...
});

More Repositories

1

zoid

Cross domain components
JavaScript
2,008
star
2

lusca

Application security for express apps.
JavaScript
1,787
star
3

post-robot

Cross domain post-messaging on the client side using a simple listener/client pattern.
JavaScript
734
star
4

kappa

A hierarchical npm-registry proxy
JavaScript
557
star
5

swaggerize-express

Design-driven apis with swagger 2.0 and express.
JavaScript
354
star
6

grumbler

A template for writing distributable front-end javascript modules.
JavaScript
292
star
7

beaver-logger

Client-side logging w/ super powers
JavaScript
252
star
8

hapi-openapi

Build design-driven apis with OpenAPI (formerly swagger) 2.0 and hapi.
JavaScript
210
star
9

jsx-pragmatic

Build JSX structures, then decide at runtime which pragma you want to use to render them.
JavaScript
188
star
10

express-enrouten

An express route initialization and configuration module.
JavaScript
172
star
11

levee

A circuit-breaker pattern implementation with fallback support.
JavaScript
171
star
12

fetch-robot

Proxy fetch through an iframe
JavaScript
157
star
13

makara

An internationalization module for kraken and express
JavaScript
135
star
14

cross-domain-utils

Cross Domain utilities
JavaScript
131
star
15

adaro

A Dust.js view renderer for express
JavaScript
127
star
16

kraken-example-with-shoppingcart

An example Kraken app showing off a shopping cart
JavaScript
116
star
17

generator-kraken

Yeoman generator for kraken.js apps
JavaScript
110
star
18

jwt-csrf

Stateless CSRF protection using jsonwebtoken (JWT)
JavaScript
108
star
19

shush

A simple module for reading JSON files that may have comments.
JavaScript
92
star
20

meddleware

Middleware configuration for express.
JavaScript
88
star
21

generator-swaggerize

Yeoman generator for design-driven apis with swagger 2.0 and krakenjs/swaggerize tools.
JavaScript
70
star
22

confit

Environment-aware configuration.
JavaScript
61
star
23

zoid-demo

A clonable demo project for xcomponent
JavaScript
61
star
24

swaggerize-routes

Swagger document driven route builder.
JavaScript
58
star
25

zalgo-promise

Release zalgo with synchronous promises
JavaScript
57
star
26

shortstop

Enables use of protocols in configuration.
JavaScript
55
star
27

kraken-example-with-passport

An example integrating kraken with passport authentication
JavaScript
53
star
28

caller

A node module for enabling a module to determine its caller.
JavaScript
47
star
29

nemo

node.js selenium-webdriver/mocha based combined testing framework
JavaScript
43
star
30

kraken-devtools

Development-time tools for kraken.js applications.
JavaScript
40
star
31

cross-domain-safe-weakmap

Cross-domain safe WeakMap shim
JavaScript
33
star
32

grabthar

Hot install and activation of npm modules
JavaScript
23
star
33

karka

A simple rule parser
JavaScript
21
star
34

belter

Miscellaneous browser utilities
JavaScript
17
star
35

good-influxdb

HapiJS good-reporter for use with InfluxDb
JavaScript
16
star
36

angular-remove-di-loaders

Webpack loaders to remove Angular DI (Dependency Injection)
JavaScript
16
star
37

freshy

An (admittedly naïve) node module (un|re)loader/refreshener.
JavaScript
15
star
38

endgame

A tiny module for ensuring uncaught exceptions are handled in Node.js
JavaScript
15
star
39

shortstop-handlers

Common protocol handlers for use with the shortstop node module.
JavaScript
15
star
40

passport-saml-encrypted

A strategy for Passport authentication that supports encrypted SAML responses
JavaScript
14
star
41

pine

A logging wrapper for winston.
JavaScript
14
star
42

react-redux-krakenjs-swaggerize-express

React client app, redux stage management, passport oauth2, paypal rest api and swagger based krakenjs node.js server
JavaScript
14
star
43

spud

A content store parser, reading a java .properties-like format
JavaScript
14
star
44

kraken-example-with-i18n

An example Kraken app showing off internationalization support
JavaScript
11
star
45

kraken-example-with-specialization

An example Kraken app showing off template specialization features.
JavaScript
11
star
46

bundalo

Manage localized sets of content files (be they property/json/etc) which may require rendering with data models
JavaScript
10
star
47

engine-munger

A helper module to insert specialization and i18n in the render workflow
JavaScript
10
star
48

memcookies

Persist cookies on the client-side, useful for supporting cookies disabled browsers
JavaScript
9
star
49

subprocess-robot

Create processes, process pools, and message between processes
JavaScript
8
star
50

grumbler-scripts

Build scripts for grumbler modules
JavaScript
6
star
51

universal-serialize

Universal serializer allowing for custom types
JavaScript
5
star
52

reverend

DEPRECATED: Merge an express-style path string with data to create a valid path.
JavaScript
5
star
53

sync-browser-mocks

Synchronous browser mocks for testing
JavaScript
4
star
54

webpack-mem-compile

Compile webpack to and from memory
TypeScript
3
star
55

hotware

JavaScript
3
star
56

localizr

A library and tool to apply localization to dust templates before rendering
JavaScript
3
star
57

neff

nconf & express based feature flags
JavaScript
3
star
58

krakenjs.github.io

Source for the kraken website
JavaScript
3
star
59

construx

Compile-on-the-fly and other development tools for use when building express applications.
JavaScript
2
star
60

spundle

command line tool and library to package localization files as json
JavaScript
2
star
61

dust-makara-helpers

Server-side configuration of helpers for makara
JavaScript
2
star
62

nodejs_deployment

Design and architecture details of node.js deployment solutions
JavaScript
2
star
63

node-benchmarker

Runs benchmarks and publishes results
JavaScript
2
star
64

grabthar-release

Release scripts for grabthar modules
JavaScript
2
star
65

express-promisified

Express with promises
JavaScript
2
star
66

webpack-promise-shim-plugin

Plugin to shim in Promise polyfill into webpack core
JavaScript
2
star
67

file-resolver

Used in kraken based projects for resolving files given the locale , file name, and the file extension.
JavaScript
2
star
68

beaver-logger-ios

Beaver Logger client for iOS
Swift
2
star
69

anemone-machina

express view engine and browser renderer for React and react-router
JavaScript
1
star
70

findatag

A specialized tokenizer for finding dust-style tags ({@tagname [attributes]})
JavaScript
1
star
71

construx-webpack

web pack dev middleware for krakenjs
JavaScript
1
star
72

express-bcp47

Locale handling middleware for Express
JavaScript
1
star
73

dustjacket

Loader middleware for dustjs
JavaScript
1
star
74

strict-merge

Strict deep merge of objects
JavaScript
1
star
75

makara-languagepackpath

Middleware for exposing the path to a language pack to templates
JavaScript
1
star