lambda-request-handler

lambda-request-handler

An npm module that allows your Node.js web applications to be deployed as an AWS Lambda function and invoked in response to API Gateway or Application Load Balancer requests.

The list of supported frameworks matches in-process-request

• Express.js v3
• Express.js v4
• Connect v3
• Koa v2

Inspired by aws-serverless-express

It supports nodejs8.10 and nodejs10.x execution environments.

The main differences between this module and aws-serverless-express are

• It's using in-process-request module to execute app handlers in-process without having to start background http server
• Simpler setup as it doesn't require managing the internal http server
• Support for applications that require asynchronous setup (for example reading config from network, or decrypting secrets from KMS)
• It's faster, because it doesn't need to pass the request to the internal server through the unix socket
• It's free from issues caused by limits in Node.js http module such as header size limit

The handler supports events from the following sources:

• API Gateway
• Application Load Balancer

Usage

The default export of lambda-request-handler is a function that takes an application handler (i.e. Express.js app instance) as an argument and returns an AWS Lambda handler function.

$ npm install lambda-request-handler

const express = require('express')
const lambdaRequestHandler = require('lambda-request-handler')

const app = express()

app.get('/user/:id', (req, res) => {
  res.json({
    id: req.params.id,
    name: 'John'
  })
})

const handler = lambdaRequestHandler(app)

module.exports = { handler }

If the above file in your Lambda source was called index.js then the name of the handler in the Lambda configuration is index.handler

Advanced example with asynchronous setup

Sometimes the application needs to read configuration from remote source before it can start processing requests. For example it may need to decrypt some secrets managed by KMS. For this use case a special helper deferred has been provided. It takes a factory function which returns a Promise that resolves to the app instance. The factory function will be called only once.

const lambdaRequestHandler = require('lambda-request-handler')
const AWS = require('aws-sdk')
const express = require('express')

const createApp = (secret) => {
  const app = express();
  app.get('/secret', (req, res) => {
    res.json({
      secret: secret,
    })
  })
}

const myAppPromise = async () => {
  const kms = new AWS.KMS()
  const data = await kms.decrypt({
    CiphertextBlob: Buffer.from(process.env.ENCRYPTED_SECRET, 'base64')
  }).promise()
  const secret = data.Plaintext.toString('ascii')
  return createApp(secret);
};

const handler = lambdaRequestHandler.deferred(myAppPromise);

module.exports = { handler }