Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/brunomorency/simple-lambda-router

Small router utility for lambda functions handling HTTP events from multiple resources and methods
https://github.com/brunomorency/simple-lambda-router

aws aws-lambda lambda nodejs router routing serverless serverless-application-model

Last synced: about 1 month ago
JSON representation

Small router utility for lambda functions handling HTTP events from multiple resources and methods

Awesome Lists containing this project

README 

          
# Use Case

When building an serverless application on AWS Lambda driven by events from API Gateway, there are several popular patterns:



1. Every single HTTP endpoint and method gets its own dedicated lambda function implementing it

1. There's a single HTTP endpoint sending all requests to one big lambda function

1. You have a couple resources defined in API gateway which send requests to a set of lambda functions each handling a scope of your logic. For example, there could be a function handling all `GET`/`POST`/`PUT`/`DELETE` requests related to a `users` entity and another to handle requests for a `todos` entity.



For case 2 and 3 above, your lambda function will need to route the incoming request to the appropriate code to respond to it. *This is what I built this little library for*.



## Bonus functionality



In addition to routing requests to the right handler, this package adds a few useful things:



- **Promises**: Uses promises for async logic. Your handler code is expected to return a `Promise` when called.

- **Error handling**: The router catches exceptions from the handler code result in a clean 500 error. The module also exports a `RouteError` class that is useful to reject requests with a specific status code.

- **Response headers**: You can define default headers to be included in responses for all requests (e.g. CORS headers) and add more headers for specific requests in the handler code.

- **Input validation**: You can define body and query parameters validation rules and the router will apply them. If body or query parameters don't match your validation rules, the request is rejected with appropriate error code and your handler code isn't executed. The way validation works allows setting default value for optional input.

- **Request body parsing**: If the incoming request has a `Content-Type` header indicating the body is JSON data. It will be parsed into a JS object before it is passed to you handler code.



## Changes in version 2



The functionality remains pretty much the same but the package has been refactored to work with the ES module syntax rather than CommonJS modules. If you upgrade, make sure you use `import` rather than `require` to get elements from this package and your handler files should also be ES modules.

# How It Works



## Lambda Function Handler

The package exports a `Route` function. It takes routing configuration and its return value is the handler of your lambda function. For example, if you have a Lambda function defined in your SAM template whose index property is set to `index.handler` as exported by code in file `index.mjs`, this is what that `index.mjs` file would look like:



#### Routing based on `request.resource`:

```javascript

import { Route } from 'simple-lambda-router'

export const handler = Route(

  {

    resources: {

      ':': 

    },

    headers: {

      '': ''

    }

  },

  

)

```



#### Routing based on `request.path`:

```javascript

import { Route } from 'simple-lambda-router'

export const handler = Route(

  {

    paths: {

      ':': 

    },

    headers: {

      '': ''

    }

  },

  

)

```



## Route Handler Files

Files defined as handlers as defined in arguments to `Route()` above must export a function called `handler` and may also export a `validate` object as follows:



```javascript

import joi from 'joi'



export function handler(request, context, ) {

  return new Promise((resolve, reject) => {

    resolve({

      statusCode: 200,

      body: {

        someProp: 'the value'

      },

      headers: {

        '': ''

      }

    })

  })

}



export const validate = {

  queryStringParameters: ,

  body: ,

}



```



### `handler`

The `handler` function gets the `request` and `context` arguments as if they were handling the lambda function directly. It also gets all other arguments passed after the config in `Route()` (see first snippet above).



Your handler function must return a Promise. It resolves to an object that must contains a `statusCode` and `body` property, it may also contain a `headers` property:



- If `body` is an object, it will go through `JSON.stringify()` before being sent back as the response body.

- HTTP headers defined in the `headers` property are included in the response in addition to those included in the initial `Route()` call. If the same HTTP header is defined in both places, the value in the promise resolution of the handler has precedence.



If your Promise is rejected or has uncaught exceptions, the router will send a `500 Internal Server Error` response back to lambda. You can reject with a specific HTTP error as follows:



```javascript

import { RouteError } from 'simple-lambda-router'

export function handler(request, context) {

  return new Promise((resolve, reject) => {

    reject(new RouteError({

      statusCode: 403,

      message: 'Check with your admin to get access to this.'

    }))

  })

}

```



### `validate`

The validate object lets you define validation rules for the request body and/or query parameters. Validation is super easy to use with the [Joi Object schema validation library](https://github.com/hapijs/joi) but you can use anything as long as you wrap it in a `validate` method compatible with [the Joi validate method](https://github.com/hapijs/joi/blob/master/API.md#validatevalue-schema-options-callback).



```javascript

import joi from 'joi'



export const handler = (request, context) => {

  ...

}



export const validate = {

  // Validating using Joi library

  queryStringParameters: joi.object({

    status: joi.string().valid('opened','completed').required(),

  }),

  // Custom body validation/augment code

  body: {

    validate: (requestBody) => {

      let error = null

      if (!('requiredProp' in requestBody)) {

        error = {

          details: [

            { message: 'Request body must contain a "requiredProp" property.' }

          ]

        }

      }

      let value = Object.assign({}, { propWithDefaultVal: 'default val' }, requestBody)

      return { error, value }

    }

  }

}



```



## Routing based on `request.path`



If your API gateway has a [proxy resource with a greedy path variable `{proxy+}`](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-set-up-simple-proxy.html), the `request.resource` value will be that greedy path and the `request.path` will be the actual path with no extracted parameters showing in `request.pathParameters`. 



> **Example**:

>    

> Your API declares a `/{proxy+}` resource and receives a `GET /items/34`. Upon receiving that request, API Gateway sends an object to your Lambda function with a `resource` property set to `/{proxy+}` and `path` property set to `/items/34`.



This package allows you to define path-based routing. In other words, the routing logic looks at `/items/34` from the example above, not `/{proxy+}` as it would with resource-based routing. Note that your path route can contain named parameter the same way they are defined in an API Gateway resource path. Those parameters will be extracted and added in the `pathParameters` property of the request object sent to your handler.



> **Example** [ctnd]:

>  

> A path key of `GET:/items/{id}` will match the request from the example and your handler will have `request.pathParameters.id` set to `34`



## Chaining handlers



It is possible to handle requests to a path or resource through a chain of handlers instead of a single handler file. This is useful if many endpoints have common validations (e.g. handlers for `/items/4`, `/items/4/links`, and `/items/4/foo` would all need to check if item 4 actually exist and return a 404 if it doesn't). 



You chain handlers by setting the handlers as an array of files. Each step in the handler chain follows the same structure as a single-file handler (it returns an object with a `handler` function returning a Promise and an optional `validate` object). Validation rules are enforced for each step of the chain and each step gets the value the previous step resolves to as one if its arguments.



See examples under `items-fn` or the `test-07-chained-handlers.js` file for more details.



# Examples

Example in the `examples` directory are for the previous version of this package which followed CommonJS modules syntax. Looking at tests may be more useful.