@haventech/amorphic
v14.0.2
Published
Front to back isomorphic framework for developing applications with node.js and mongoDB
Downloads
591
Keywords
Readme
Amorphic
Description
Front-to-back isomorphic framework for developing applications with Node.js
Installation
To install using npm:
$ npm install amorphic
To get started with a more complex app see the Amorphic Ticket Demo
Usage
Create an app.js
entry point as follows:
require('amorphic').listen(__dirname);
Create a config.json
file top level at least the following options set:
{
"application": "name-of-your-application",
"applications": {
"name-of-your-application": "directory-of-your-application"
}
}
The directory structure for an amorphic application must be the following:
/apps - directory of all amorphic applications (can have multiple applications under this directory)
/your-application - where all your app code lives
/common - where all the code that is common across your applications lives
Create a schema.json
file in your application directory which will contain your data schema information for persistor to persist your data to the database.
Note: The schema.json
file needs at least an opening and a closing curly brace.
Start the application:
$ node app.js --port <available port>
See this blog post for more info on Amorphic and this video that demos the drpatient sample
Validation
The Amorphic server has validation middleware that will validate requests coming into the server based on fields specified in a config.
There are four fields to put in the config.json for the amorphic app. These fields are:
validatorAllowList: characters that are allowed in the request, a white list
validatorDenyList: characters that are not allowed in the request, a black list
validatorLog: boolean for logging whenever a request is blacklisted, whitelisted, or has HTML values escaped
validatorEscapeHTML: boolean for allowing HTML characters to be escaped
The whitelist and blacklist fields follow the format here: https://www.npmjs.com/package/validator
The whitelist field is especially dangerous to use as it will only allow characters that match the format to pass the validator.
The blacklist field also has certain characters that should not be blocked, such as '-', as that will most likely corrupt the amorphic message and cause problems.
The order that this validation is performed is blacklist, escape, whitelist.
The config.json found for the amorphic postgres unit test found here: components/amorphic/test/postgres/apps/test/config.json, contains examples of how these fields should be used.
There is also a counter under statsd for 'amorphic.server.validator.whitelist.counter', 'amorphic.server.validator.blacklist.counter', and 'amorphic.server.validator.escape.counter' that will count the times requests are blacklisted, whitelisted, or escaped.
Changes
This section lists significant changes to the amorphic component.
Version 11.0.0
This version introduces a breaking change to the listen
and startPersistorMode
signatures. In the past, clients passed
sendToLog
function to these functions. They also optionally injected their own logger within the sendToLog
function.
Old listen and startPersistorMode signature:
listen(appDirectory, sessionStore, preSessionInject, postSessionInject, sendToLog, statsdClient, configStore = null)
startPersistorMode(appDirectory, sendToLog, statsdClient, configStore = null)
With this change client would need to pass a logger
object instead of sendToLog
function. We require that the new logger object must atleast have basic bunyan log functions such as 'debug', 'error', 'info', 'warn' and also a child logger create function of 'child'. The sendToLog
function should no longer be used to inject the logger like in the pastas it is being deprecated for external use and is only used internally.
New listen and startPersistorMode signature:
listen(appDirectory, sessionStore, preSessionInject, postSessionInject, logger, statsdClient, configStore = null)
startPersistorMode(appDirectory, logger, statsdClient, configStore = null)
If a client chooses to pass an undefined
instead of logger
object, then amoprhic would use the built in SuperType Logger to log.
Version 11.1.0
This version introduces a way to inject schemas when initializing amorphic apps. In the past, we are only allowed to define table definitions in common folder or app specific folder. Now every module can define their own schemas and apps can consolidate the objects and use it for amorphic initialization. E.g.: OrcaSchema in the following example is imported directly from the module. import { OrcaSchema } from '@hit/orca';
const rootPath = `${__dirname}`;
const appsPath = `${rootPath}/apps`;
const appSchema = JSON.parse(String(fs.readFileSync(`${appsPath}/common/schema.json`)));
Object.assign(appSchema, OrcaSchema);
return require('@haventech/amorphic').listen(__dirname, sessionStore, null, null, log, null, appSchema);
Note that the validations are not included if there are dupes in the definitions.
Version 11.2.0
This version adds enableUILoggerEndpointsWithMiddleware
config. If set to true, this flag may be used to automatically include HavenLogger
UI endpoints (/uiLog
, uiLogConfig
) along with necessary middlewares.
You must pass HavenLogger
to take advantage of this feature.
Testing
Run all the tests:
$ npm test
Run a specific test (in this case, daemon test):
$ npm run test:daemon
License
Amorphic is licensed under the MIT license