uservit
v0.0.4
Published
Small, thin layer, that serves your serverless microservices generically
Downloads
3
Maintainers
Readme
uservit
This library is used throught the switch_paas project to server its microservices through ServerLess. It provides a thin layer over the Lambda API interface for:
- Supporting Promises.
- You can also return a regular value instead of a promise.
- Allows to return custom headers and HTTP status codes from your handlers in a unified way.
- Creates a special case for bad requests (client errors) and returns HTTP status code 400.
- As above, but for unexpected errors, it returns HTTP status code 500.
- Returns the result of your handlers always in the same way by providing
a
result
field in the response. - Adds CORS headers by default.
- Lowercases the header names in the request.
Installing
Add this library to your package.json configuration:
"dependencies": {
"uservit": "latest"
}
Using it
Some examples follow, but more examples can be found in the tests.
Lambda Integration (With Proxy)
Let's say you want to handle a request with the function users.get
(that would
be the function get
inside the module users
), you would write your
ServerLess service handler like this:
'use strict';
var uservit = require('uservit');
var users = require('users');
exports.hello = function (event, context, callback) {
return uservit.handleProxy(event, context, callback, users.get);
};
That's it! In your service (the function users.get
) you can then do:
'use strict';
var promise = require('promise');
exports.get = function (event, context) {
return promise.resolve().
then(function () {
//
}).
then(function () {
//
}).
catch(function (err) {
// ...
});
};
Returning successful responses
Just return a body
field with what you want, like:
{
body: {
success: true
}
}
And the HTTP client will see a payload like:
{
"result": {
"success": true
}
}
Returning custom HTTP status codes and Headers
{
statusCode: 999,
headers: {
'custom-header': 'a value'
}
}
Returning client errors
You can fail your promise and return something like this:
return promise.reject({
clientError: true,
message: 'some_client_error'
});
And the HTTP client will see an HTTP status code of 400 with a payload like:
{
"message": "some_client_error"
}
Unexpected errors
When something in your code fails, your promises will also be rejected and your client will see an HTTP status code 500 with a payload like:
{
"message": "server_error"
}
Lambda (No Proxy integration)
To leverage the available features when using the proxy feature, you have to add a mapping template for the request.
This is based on the one available at https://kennbrodhagen.net/2015/12/06/how-to-create-a-request-object-for-your-lambda-event-from-api-gateway/.
Request template sample
{
"body" : "$util.escapeJavaScript($input.json('$'))",
"headers": {
#foreach($header in $input.params().header.keySet())
"$header.toLowerCase()": "$util.escapeJavaScript($input.params().header.get($header))" #if($foreach.hasNext),#end
#end
},
"method": "$context.httpMethod",
"params": {
#foreach($param in $input.params().path.keySet())
"$param.toLowerCase()": "$util.escapeJavaScript($input.params().path.get($param))" #if($foreach.hasNext),#end
#end
},
"query": {
#foreach($queryParam in $input.params().querystring.keySet())
"$queryParam.toLowerCase()": "$util.escapeJavaScript($input.params().querystring.get($queryParam))" #if($foreach.hasNext),#end
#end
}
}
Response template sample
For the 200 status code we need to return the contents of the body
field as
JSON, so this template mapping is required:
$input.json('$.body')
For errors, this generic template will be used:
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{"message": "$errorMessageObj.body.message","errors": [#foreach( $e in $errorMessageObj.body.errors )"$e"#if($foreach.hasNext),#end#end]}
And to return custom status codes the following mappings should be added too:
400: '.*"message":"client_error".*'
401: '.*"message":"unauthorized".*'
402: '.*"message":"payment_required".*'
403: '.*"message":"forbidden".*'
404: '.*"message":"not_found".*'
429: '.*"message":"throttled".*'
500: '((.*Process exited before completing request.*)|(.*server_error.*))'
Let's say you want to handle a request with the function users.get
(that would
be the function get
inside the module users
), you would write your
ServerLess service handler like this:
'use strict';
var uservit = require('uservit');
var users = require('users');
exports.hello = function (event, context, callback) {
return uservit.handle(event, context, callback, users.get);
};
That's it! In your service (the function users.get
) you can then do:
'use strict';
var promise = require('promise');
exports.get = function (event, context) {
return promise.resolve().
then(function () {
//
}).
then(function () {
//
}).
catch(function (err) {
// ...
});
};
Returning successful responses
Just return a body
field with what you want, like:
{
body: {
success: true
}
}
And the HTTP client will see a payload like:
{
"result": {
"success": true
}
}
Returning custom HTTP status codes and Headers
{
message: 'payment_required',
headers: {
'custom-header': 'a value'
}
}
The pattern for 402
will match and the right HTTP status code will be sent. To
return the custom header, you will need to map the header in the response like
integration.response.body.headers.custom-header
.
Returning client errors
You can fail your promise and return something like this:
return promise.reject({
message: 'client_error',
errors: ['missing_parameter']
});
And the HTTP client will see an HTTP status code of 400 with a payload like:
{
"message": "client_error",
"errors": ['missing_parameter']
}
Unexpected errors
When something in your code fails, your promises will also be rejected and your client will see an HTTP status code 500 with a payload like:
{
"message": "server_error"
}
Developers
This project uses standard npm scripts. Current tasks include:
- test: Runs Mocha tests.
- jsdoc: Runs JSDoc3.
- eslint: Runs ESLint.
- coverage: Runs the tests and then Instanbul to get a coverage report.
- build: This is the default task, and will run all the other tasks.
Running an npm task
To run a task, just do:
npm run build
Contributing
To contribute:
- Make sure you open a concise and short pull request.
- Throw in any needed unit tests to accomodate the new code or the changes involved.
- Run
npm run build
and make sure everything is ok before submitting the pull request (make eslint happy). - Your code must comply with the Javascript Standard Style, ESLint should take care of that.
License
The source code is released under Apache 2 License.
Check LICENSE file for more information.