uservit

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.