SLA4OAI is an open source library for applying SLA in your node application.
SLA4OAI is Express-compatible SLA Checking and Monitoring middleware for Node.js.
SLA4OAI is based on SLA for Open API Initiative Specification. And follows the Basic SLA Management Service proposal.
$ npm install sla4oai-tools --save
You can simply use the library by registering it with the Express app with your plans file as local:
var sla4oaiTools = require('sla4oai-tools'); //import
var slaManager = new sla4oaiTools(); //create a instance of slaManager
var app = express();
var configObj = {
sla4oai: __dirname + "/petstore-plans.yaml"
};
slaManager.initialize(app, configObj, function(slaManager, error){
//any callback actions
if(!error){
app.listen(9000);
}else{
console.log(error.toString());
}
});
Initialize all library components as express middlewares. Called once when the server getting up.
Name | Type | Description |
---|---|---|
app | Express |
Required - The express app. |
configObj | ConfigurationObject |
Required - The configuration details for each components. |
callback | Function |
Required - The callback function to be execute, it will recive two parameters: slaManager for post-configuration and error if it exists. |
Name | Type | Description |
---|---|---|
sla4oai | string |
Required The URL or file path to the sla4oai document |
sla4oaiUI | Sla4oaiUIObject |
Optional Object which contains the Sla4oaiUI component configuration |
supervisorConnection | ConnectionObject |
Optional The connection details for Supervisor and ScopeResolver. By default it get the connection from Sla4oai document |
monitorConnection | ConnectionObject |
Optional The connection details for Monitor component. By default it get the connection from Sla4oai document |
Name | Type | Description |
---|---|---|
url | string |
Host url. |
Name | Type | Description |
---|---|---|
path | string |
Optional Middleware will be allocated on this path. By default /plans . |
portalSuccessRedirect | string |
Optional URL where UI will redirect when result is successful. /docs by default. |
portalURL | string |
Optional In case you have a own portal that is served in other server, URL where portal is served. |
Example:
var sla4oaiTools = require('sla4oai-tools'); //import
var slaManager = new sla4oaiTools(); //create a instance of slaManager
var app = express();
var configObj = {
sla4oai: __dirname + "/petstore-plans.yaml",
sla4oaiUI: {
path: "/plans",
portalSuccessRedirect: "/pets",
portalUrl: null
},
supervisorConnection: {
url: 'http://supervisor.oai.governify.io/api/v2'
},
monitorConnection: {
url: 'http://monitor.oai.governify.io/api/v1'
}
}
slaManager.initialize(app, configObj, function(slaManager, error){
//any callback actions
if(!error){
app.listen(9000);
}else{
console.log(error.toString());
}
});
Use this method to set the configuration parameters of the Scope Resolver.
Name | Type | Description |
---|---|---|
notCheckByDefault | boolean |
Decides if it uses a list of default paths that don't need checking. By default true and ["/docs", "/api-docs"] |
defaultOAuthProvider | string |
The default provider when oauthprovider is missing in the request header. |
config | <provider, OAuthConfigObject> |
OAuth provider configurations. |
Name | Type | Description |
---|---|---|
clientId | string |
The provider application id. |
clientSecret | string |
The provider application secret. |
callbackURL | string |
The callback registered in the provider application. |
Example:
var options = {
defaultOAuthProvider: 'google',
config: {
google: {
clientId: '6076-d1m.apps.googleusercontent.com',
clientSecret: '1lWx9DDDaPo9kxF4yu6t_loJ',
callbackURL: 'https://app.myservice.com/google/callback'
}
}
};
slaManager.scopeResolver.configure(options);
Use this method to get the account name from the OAuth provider by the specified token.
Example:
slaManager.scopeResolver.getAccountName(oauthProvider, token, function (err, accountName) {
// get accountName
});
Using this method to get the scope object from the supervisor by the specifying the apikey or the account name.
Example:
slaManager.scopeResolver.getAccountScope('apikey', 'NbfiS7wjwjwb=', function (err, result) {
// get result.scope
});
//or
slaManager.scopeResolver.getAccountScope('account', 'john@tenant.com', function (err, result) {
// get result.scope
});
Using the powerful PassportJS framework and family of plugins SLA4OAI can be configured to support the following providers:
Use this method to set the configuration parameters of the Bouncer.
Name | Type | Description |
---|---|---|
environment | string |
The deploying environment (devel, qa, or production). |
notCheckByDefault | boolean |
Decides if it uses a list of default paths that don't need checking. By default true and ["/docs", "/api-docs"] |
Example: |
var options = {
environment: 'qa'
};
slaManager.bouncer.configure(options);
By default, all incoming requests are verified by SLA Check, but you can customize this behaviour and specify which requests need checking in both bouncer and scopeResolver components.
Example:
slaManager.bouncer.needChecking = function(req) {
if (req.originalUrl.startsWith('/api/')) {
return true;
}
return false;
}
slaManager.scopeResolver.needChecking = function(req) {
if (req.originalUrl.startsWith('/api/')) {
return true;
}
return false;
}
By default, bouncer declines all not accepted requested with status code 403
and the body that comes from the Supervisor. But you can customize the decline response message.
Example:
slaManager.bouncer.decline = function(req, res, next, supervisorPayload) {
if(supervisorPayload.reason === 'Too many requests') {
res.status(429).json(supervisorPayload.reason).end();
}
else {
res.status(403).json(supervisorPayload).end();
}
}
In order to resolve the required metrics for the check API, you need to define resolveMetrics
function and return all metrics in single object.
Example:
slaManager.bouncer.resolveMetrics = function (requestedMetrics, req) {
return {
nameLegth: 12
};
};
Use this method to set the configuration parameters of the Reporter.
Name | Type | Description |
---|---|---|
autoReport | boolean |
In case of true , all API calls will be reported one by one, else the developer can aggregate multiple API calls in one report (default = true). |
aggregate | boolean |
Aggregate multiple measures in one report, this aggregated measures will be frequently sended based on the aggregationPeriod (default = false). This features is disabled if the autoReport = false. |
aggregationPeriod | double |
All requests during this period will be aggregated in one report. It is calculated in milliseconds. |
cluster | string |
The cluster that process this API. |
environment | string |
The deploying environment (devel, qa, or production). |
Example:
var options = {
autoReport: true,
aggregate: true,
aggregationPeriod: 100,
cluster: 'cl1.acme.com',
environment: 'qa'
};
slaManager.reporter.configure(options);
In case of autoReport=false
, the developer will have the responsibility to call this method to report the aggregated metrics.
Example:
slaManager.reporter.reportMetrics();
At any stage of the API logic, the developer can set a custom metric by simply passing its name and value.
Example:
slaManager.reporter.setMetric(req, 'animalTypes', records.length);
This method enables the developer to set the metrics that need to be calculated before the API logic.
Example:
slaManager.reporter.preCalculateMetrics = function(requestedMetrics, req, next) {
req.sla.metrics['x-origin'] = req.headers['origin'];
next();
};
This method enables the developer to set the metrics that need to be calculated after the API logic.
Example:
slaManager.reporter.postCalculateMetrics = function(requestedMetrics, req, res, next) {
req.sla.metrics['x-animalType'] = getAnimalTypes(res.Body);
next();
};
- responseTime: The API processing time.
- requestBody: The body of the request.
- responseHeaders: The headers of the request.
- responseBody: The body of the response.
- userAgent: Some information about the browser and operating system of the API consumer.
This component makes UI where plans.yaml
document is represented on an user interface way.
Example
var configObj = {
sla4oai: __dirname + "/petstore-plans.yaml",
sla4oaiUI: {
portalSuccessRedirect: "/pets"
}
}
slaManager.initialize(app, configObj, function(slaManager, error){
//any callback actions
if(!error){
app.listen(9000);
}else{
console.log(error.toString());
}
});
SLA4OAI uses Winston to log all SLA connection activities.
You can customize the Winston logging behaviour by accessing slaManager.winston
object.
Example: In the following example we change the logging from the Console to the file system:
slaManager.winston.add(slaManager.winston.transports.File, { filename: 'somefile.log' });
slaManager.winston.remove(slaManager.winston.transports.Console);