aws-wave

AWS Lambda Microframework

About AWS Wave

AWS Wave is a microframework that makes it easier to develop rest api's using AWS Lambda Functions and API Gateway. It attempts to make the develpment faster by easing common tasks, such as:

• Exception handling
• Request body deserialization
• Response body serialization
• Request validation

Lambda Proxy Integration

In order to use AWS Wave all methods defined in the API Gateway must use Request Integration Type:LAMBDA_PROXY.

A detailed documentation can be found here.

Getting Started

Instalation

npm install aws-wave

Handling Requests

The AWS Wave microframework provides an abstract class called AbstratRequestHandler that handles a Lambda execution call and perform some operations such as request body deserialization, request validation, response body serialization and exception handling.

const AbstractRequestHandler = require('aws-wave').AbstractRequestHandler;

class PostUserHandler extends AbstractRequestHandler {
    
    before(event, context) {
      // perform anything before the execution
      this.cors('*');
    }
        
    execute(body, context, callback) {
      callback({ message: 'Hello from aws-wave' });
    }
}

exports.handler = (event, context, callback) => {
  const handler = new PostUserHandler();
  handler.handleRequest(event, context, callback);
}

The Request / Response Attributes

The AbstractRequestHandler class provides methods to access all the request / response attributes and the Lambda environment context as well:

Attribute | Method -------------------------------- | ----------------------------------------------------- Request Headers | getRequestHeader("headerName") Response Headers | addResponseHeader("headerName") Raw Request Body | getRawRequestBody() Http Method | getHttpMethod() Resource Path | getPath() Stage Variables | getStageVariable("stageVariableName") Path Parameters | getPathParameter("parameterName") Query String Parameters | getQueryStringParameter("parameterName") Request Context Parameter | getRequestContextParameter("parameterName")

Request Validation

AWS Wave uses Joi to validate requests. To validate the incoming request a schema should be defined in the class constructor

Eg.:

const Joi = require('joi');
const AbstractRequestHandler = require('aws-wave').AbstractRequestHandler;

const schema = Joi.object().keys({
  code: Joi.string().required()  
});

class PhoneConfirmationHandler extends AbstractRequestHandler {
    
    constructor() {
      super(schema);
    }
    
    before(event, context) {     
      this.cors('*');
    }
        
    execute(body, context, callback) {
      callback({ message: 'The request body is valid!' });
    }
}

exports.handler = (event, context, callback) => {
  const handler = new PhoneConfirmationHandler();
  handler.handleRequest(event, context, callback);
}

If any constraint violation occurs an UnprocessableEntityException will be thrown and the http response will be serialized with the error details.

Eg.:

curl -X POST http://my-api-gateway-resource/phone-confirmations -d '{"invalidParam": "value"}'

I this particular example the server will respond the above request with a http status code 422 and the following response body:

{
  "message": "Unprocessable entity",
  "errors": [
    {
      "message": "\"code\" is required",
      "path": "code",
      "type": "any.required",
      "context": {
         "key": "code"
      }
    }
  ]
}

A detailed documentation of Joi validations can be found here.

If you want to provide your own request body validation mechanism, the method resolveRequestBodyValidator should be overridden:

const Wave = require('aws-wave');

const RequestBodyValidator         = Wave.RequestBodyValidator;
const UnprocessableEntityException = Wave.UnprocessableEntityException;

class MyCustomValidator extends RequestBodyValidator {
  
  validate(entity, schema) {
    // custom validation here
    // should throw a HttpException if any constraint is violated
    throw new UnprocessableEntityException({message: 'Invalid request body'});
  }
  
}

module.exports = MyCustomValidator;

const MyCustomValidator = require('my-custom-validator');
const AbstractRequestHandler = require('aws-wave').AbstractRequestHandler;

const myCustomSchema = {};

class MyHandler extends AbstractRequestHandler {
    
    constructor() {
      super(myCustomSchema);
    }
    
    before(event, context) {      
      this.cors('*');
    }
        
    execute(body, context, callback) {
      callback({ message: 'The request body is valid!' });
    }
    
    resolveRequestBodyValidator() {
      return new MyCustomValidator();
    }
}

exports.handler = (event, context, callback) => {
  const handler = new MyHandler();
  handler.handleRequest(event, context, callback);
}

Serialization and Deserialization

The current version of AWS Wave supports only JSON serialization/deserialization.

The deserialization and serialization strategies are based on two http headers:

• Content-Type for deserialization
• Accept for serialization

If you want to provide your own request body deserializer, the method resolveRequestBodyDeserializer should be overridden:

const Wave = require('aws-wave');

const BadRequestException             = Wave.BadRequestException;
const RequestBodyDeserializerStrategy = Wave.RequestBodyDeserializerStrategy;

class MyCustomDeserializer extends RequestBodyDeserializerStrategy {
  
  deserialize(body) {
    // custom deserialization here
    // should throw a HttpException if any error occur
    throw new BadRequestException({message: 'Invalid request body'});
  }
  
}

module.exports = MyCustomDeserializer;

If you want to provide your own response body serializer, the method resolveResponseBodySerializer should be overridden:

const Wave = require('aws-wave');

const InternalServerErrorException    = Wave.InternalServerErrorException;
const RequestBodyDeserializerStrategy = Wave.ResponseBodySerializerStrategy;

class MyCustomSerializer extends ResponseBodySerializerStrategy {
  
  serialize(entity) {
    // custom serialization here
    // should throw a HttpException if any error occur
    throw new InternalServerErrorException({message: 'Unable to serialize the response body'});
  }
  
}

module.exports = MyCustomSerializer;

Exception Handling

AWS Wave offers a built in exception handler, any HttpException will be serialized as response body and any exception not handled will be serialized as an Internal Server Error.

E.g.:

const Wave = require('aws-wave');

const AbstractRequestHandler = Wave.AbstractRequestHandler;
const UnauthorizedException  = Wave.UnauthorizedException;

class PostUserHandler extends AbstractRequestHandler {
    
    before(event, context) {      
      this.cors('*');
    }
        
    execute(body, context, callback) {
      // any validation
      if (body.hasPermission)
        return callback(new UnauthorizedException({'The user has no permission'}));
        
      callback({ message: 'The user has permission'});
    }
}

exports.handler = (event, context, callback) => {
  const handler = new PostUserHandler();
  handler.handleRequest(event, context, callback);
}

License

The AWS Wave microframework is open-source software licensed under the MIT license .