@noggin/elastic-noggin-utils v1.0.8
Elastic Noggin Utils
This repo contains handy utilities for Elastic Noggin microservices.
Getting started
Elastic Noggin microservices are based on the Express (https://expressjs.com/) framework, but there is a lot of boiler plate to get AWS XRay and HTTPs operating properly. Using the Service class helps us.
In your index.ts have something like the following. It will process the command-line options, set up xray, helmet, error handling, and start the web server.
import { Service } from './service/Service';
const service = new Service({
serviceName: 'Elastic Noggin Example Service';
routes: (app, basePath) => {
// Define your Express routes here
}
});
service.start();
You can configure more of the service in the options passed to the Service constructor
Property | Type | Description |
---|---|---|
serviceName | string | The name of the service (required) |
cliOptions | OptionDefinition[] | An array of additional options that can be passed on the command line for use within your service |
helmetOptions | IHelmetConfiguration | Configuration passed to Helmet |
health | (req: Request, res: Response) => void | A more detailed heath check beyond the default just returning 200 OK |
Logger
Winston is used for logging. Add NODE_ENV=dev to your start script, for pretty printed objects.
"start": "NODE_ENV=dev nodemon --http-port=8080 --ensrv-url=https://http-ap-southeast-2.showcase.elasticnoggin.com/ensrv --encloud-service-prefix=https://services.dev.elasticnoggin.com/",
Middlewares
The following common Express middlewares are available for use.
CORS
Some routes need to be accessible by the browser via NogginApps. Using the CORS middleware will add the appropriate CORS headers to the response for the NogginApps domains.
app.get(basePath + '/my-route', cors(), doMyRoute);
Namespace
Retrieves the EnSrv namespace defined in the request's en-namespace header and sets it in to the Express application's local object. If there is already a different namespace detected by other means then the response will be sent with a 400. A 400 will also be responded if there is no en-namespace header.
app.get(basePath + '/my-route', namespace(), doMyRoute);
Session
Looks for an EnSrv session token in the request as a Bearer authorization header. Responds with a 401 if the token isn't there or if it isn't a valid JWT token. Otherwise it stores the token's decoded information and a constructed EnSrv class in the Express application's local object. It does NOT check the validity of the session itself.
app.get(basePath + '/my-route', session(), doMyRoute);
Trusted origin
When a request originates from outside the EN Cloud area of trust (i.e. not another service in the cluster) it contains a header encloud-origin: Untrusted
.
This middlewhere will respond with a 403 if the request is untrusted.
app.get(basePath + '/my-route', trustedOrigin(), doMyRoute);
User
The user middleware will use the session middlware to obtain the user's EnSrv session, but will also contact EnSrv to check it's validity and whether or not they are a user or administrator. If it is invalid or isn't a user or administrator it responds with a 401.
app.get(basePath + '/my-route', isUser(), doMyRoute);
app.get(basePath + '/my-route', isAdministrator(), doMyRoute);