diff --git a/README.md b/README.md index ebb5376f..d59a2c4a 100644 --- a/README.md +++ b/README.md @@ -18,38 +18,15 @@ exports.handler = (event, context) => awsServerlessExpress.proxy(server, event, [Package and create your Lambda function](http://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html), then configure a simple proxy API using Amazon API Gateway and integrate it with your Lambda function. -## Example +## Quick Start/Example -In addition to a basic Lambda function and Express server, the `example` directory includes a [Swagger file](http://swagger.io/specification/), [CloudFormation template](https://aws.amazon.com/cloudformation/aws-cloudformation-templates/) with [Serverless Application Model (SAM)](https://github.com/awslabs/serverless-application-model), and helper scripts to help you set up and manage your application. +Want to get up and running quickly? [Check out our example](example/README.md) which includes: -### Steps for running the example -This guide assumes you have already [set up an AWS account](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/AboutAWSAccounts.html) and have the latest version of the [AWS CLI](https://aws.amazon.com/cli/) installed. - -1. From your preferred project directory: `git clone https://github.com/awslabs/aws-serverless-express.git && cd aws-serverless-express/example`. -2. Run `npm run config -- --account-id="" --bucket-name="" [--region="" --function-name=""]` to configure the example, eg. `npm run config -- --account-id="123456789012" --bucket-name="my-bucket" --region="us-west-2" --function-name="my-function"`. This modifies `package.json`, `simple-proxy-api.yaml` and `cloudformation.yaml` with your account ID, bucket, region and function name (region defaults to `us-east-1` and function name defaults to `AwsServerlessExpressFunction`). If the bucket you specify does not yet exist, the next step will create it for you. This step modifies the existing files in-place; if you wish to make changes to these settings, you will need to modify `package.json`, `simple-proxy-api.yaml` and `cloudformation.yaml` manually. -3. Run `npm run setup` (Windows users: `npm run win-setup`) - this installs the node dependencies, creates an S3 bucket (if it does not already exist), packages and deploys your serverless Express application to AWS Lambda, and creates an API Gateway proxy API. -4. After the setup command completes, open the AWS CloudFormation console https://console.aws.amazon.com/cloudformation/home and switch to the region you specified. Select the `AwsServerlessExpressStack` stack, then click the `ApiUrl` value under the __Outputs__ section - this will open a new page with your running API. The API index lists the resources available in the example Express server (`app.js`), along with example `curl` commands. - -See the sections below for details on how to migrate an existing (or create a new) Node.js project based on this example. If you would prefer to delete AWS assets that were just created, simply run `npm run delete-stack` to delete the CloudFormation Stack, including the API and Lambda Function. If you specified a new bucket in the `config` command for step 1 and want to delete that bucket, run `npm run delete-bucket`. - -### Creating or migrating a Node.js project based on the example - -To use this example as a base for a new Node.js project: - -1. Copy the files in the `example` directory into a new project directory (`cp -r ./example ~/projects/my-new-node-project`). If you have not already done so, follow the [steps for running the example](#steps-for-running-the-example) (you may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). -2. After making updates to `app.js`, simply run `npm run package-deploy` (Windows users: `npm run win-package-deploy`). - -To migrate an existing Node server: - -1. Copy the following files from the `example` directory: `api-gateway-event.json`, `cloudformation.yaml`, `lambda.js`, and `simple-proxy-api.yaml`. Additionally, copy the `scripts` and `config` sections of `example/package.json` into your existing `package.json` - this includes many helpful commands to manage your AWS serverless assets and perform _basic_ local simulation of API Gateway and Lambda. If you have not already done so, follow the [steps for running the example](#steps-for-running-the-example) (be sure to copy over `scripts/configure.js`. You may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). -2. From your existing project directory, run `npm install --save aws-serverless-express`. -3. Modify `lambda.js` to import your own server configuration (eg. change `require('./app')` to `require('./server')`). You will need to ensure you export your app configuration from the necessary file (eg. `module.exports = app`). This library takes your app configuration and listens on a Unix Domain Socket for you, so you can remove your call to `app.listen()` (if you have a `server.listen` callback, you can provide it as the second parameter in the `awsServerlessExpress.createServer` method). -4. Modify the `CodeUri` property of the Lambda function resource in `cloudformation.yaml` to point to your application directory (e.g. `CodeUri: ./src`). If you are using a build tool (e.g. Gulp, Grunt, Webpack, Rollup, etc.), you will instead want to point to your build output directory. -5. Run `npm run package-deploy` (Windows users: `npm run win-package-deploy`) to package and deploy your application. - -To perform a basic, local simulation of API Gateway and Lambda with your Node server, update `api-gateway-event.json` with some values that are valid for your server (`httpMethod`, `path`, `body` etc.) and run `npm run local`. AWS Lambda uses NodeJS 4.3 LTS, and it is recommended to use the same version for testing purposes. - -If you need to make modifications to your API Gateway API, modify `simple-proxy-api.yaml` and run `npm run package-deploy`. If your API requires CORS, be sure to modify the two `options` methods defined in the Swagger file, otherwise you can safely remove them. To modify your other AWS assets, make your changes to `cloudformation.yaml` and run `npm run package-deploy`. Alternatively, you can manage these assets via the AWS console. + - Lambda function + - Express server + [Swagger file](http://swagger.io/specification/) + - [Serverless Application Model (SAM)](https://github.com/awslabs/serverless-application-model)/[CloudFormation](https://aws.amazon.com/cloudformation/aws-cloudformation-templates/) template + - Helper scripts to configure, deploy, and manage your application ### Getting the API Gateway event object This package includes middleware to easily get the event object Lambda receives from API Gateway @@ -57,6 +34,9 @@ This package includes middleware to easily get the event object Lambda receives ```js const awsServerlessExpressMiddleware = require('aws-serverless-express/middleware') app.use(awsServerlessExpressMiddleware.eventContext()) +app.get('/', (req, res) => { + res.json(req.apiGateway.event) +}) ``` ### Is AWS serverless right for my app? @@ -72,12 +52,12 @@ app.use(awsServerlessExpressMiddleware.eventContext()) - [Staging](http://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api.html) - [SDK Generation](http://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-generate-sdk.html) - [API Monitoring](http://docs.aws.amazon.com/apigateway/latest/developerguide/monitoring-cloudwatch.html) + - [Request Validation](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html) + - [Documentation](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-documenting-api.html) #### Cons - - Currently limited to Node.js 4.3 (LTS) - For apps that may not see traffic for several minutes at a time, you could see [cold starts](https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/) - - May be more expensive for high-traffic apps - Cannot use native libraries (aka [Addons](https://nodejs.org/api/addons.html)) unless you package your app on an EC2 machine running Amazon Linux - Stateless only - API Gateway has a timeout of 30 seconds, and Lambda has a maximum execution time of 5 minutes. diff --git a/example/README.md b/example/README.md new file mode 100644 index 00000000..896e0e9a --- /dev/null +++ b/example/README.md @@ -0,0 +1,36 @@ +## Example + +In addition to a basic Lambda function and Express server, the `example` directory includes a [Swagger file](http://swagger.io/specification/), [CloudFormation template](https://aws.amazon.com/cloudformation/aws-cloudformation-templates/) with [Serverless Application Model (SAM)](https://github.com/awslabs/serverless-application-model), and helper scripts to help you set up and manage your application. + +### Steps for running the example +This guide assumes you have already [set up an AWS account](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/AboutAWSAccounts.html) and have the latest version of the [AWS CLI](https://aws.amazon.com/cli/) installed. + +1. From your preferred project directory: `git clone https://github.com/awslabs/aws-serverless-express.git && cd aws-serverless-express/example`. +2. Run `npm run config -- --account-id="" --bucket-name="" [--region="" --function-name=""]` to configure the example, eg. `npm run config -- --account-id="123456789012" --bucket-name="my-unique-bucket"`. This modifies `package.json`, `simple-proxy-api.yaml` and `cloudformation.yaml` with your account ID, bucket, region and function name (region defaults to `us-east-1` and function name defaults to `AwsServerlessExpressFunction`). If the bucket you specify does not yet exist, the next step will create it for you. This step modifies the existing files in-place; if you wish to make changes to these settings, you will need to modify `package.json`, `simple-proxy-api.yaml` and `cloudformation.yaml` manually. +3. Run `npm run setup` (Windows users: `npm run win-setup`) - this installs the node dependencies, creates an S3 bucket (if it does not already exist), packages and deploys your serverless Express application to AWS Lambda, and creates an API Gateway proxy API. +4. After the setup command completes, open the AWS CloudFormation console https://console.aws.amazon.com/cloudformation/home and switch to the region you specified. Select the `AwsServerlessExpressStack` stack, then click the `ApiUrl` value under the __Outputs__ section - this will open a new page with your running API. The API index lists the resources available in the example Express server (`app.js`), along with example `curl` commands. + +See the sections below for details on how to migrate an existing (or create a new) Node.js project based on this example. If you would prefer to delete AWS assets that were just created, simply run `npm run delete-stack` to delete the CloudFormation Stack, including the API and Lambda Function. If you specified a new bucket in the `config` command for step 1 and want to delete that bucket, run `npm run delete-bucket`. + +### Creating or migrating a Node.js project based on the example + +To use this example as a base for a new Node.js project: + +1. Copy the files in the `example` directory into a new project directory (`cp -r ./example ~/projects/my-new-node-project`). If you have not already done so, follow the [steps for running the example](#steps-for-running-the-example) (you may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). +2. After making updates to `app.js`, simply run `npm run package-deploy` (Windows users: `npm run win-package-deploy`). + +To migrate an existing Node server: + +1. Copy the following files from the `example` directory: `api-gateway-event.json`, `cloudformation.yaml`, `lambda.js`, and `simple-proxy-api.yaml`. Additionally, copy the `scripts` and `config` sections of `example/package.json` into your existing `package.json` - this includes many helpful commands to manage your AWS serverless assets and perform _basic_ local simulation of API Gateway and Lambda. If you have not already done so, follow the [steps for running the example](#steps-for-running-the-example) (be sure to copy over `scripts/configure.js`. You may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). +2. From your existing project directory, run `npm install --save aws-serverless-express`. +3. Modify `lambda.js` to import your own server configuration (eg. change `require('./app')` to `require('./server')`). You will need to ensure you export your app configuration from the necessary file (eg. `module.exports = app`). This library takes your app configuration and listens on a Unix Domain Socket for you, so you can remove your call to `app.listen()` (if you have a `server.listen` callback, you can provide it as the second parameter in the `awsServerlessExpress.createServer` method). +4. Modify the `CodeUri` property of the Lambda function resource in `cloudformation.yaml` to point to your application directory (e.g. `CodeUri: ./src`). If you are using a build tool (e.g. Gulp, Grunt, Webpack, Rollup, etc.), you will instead want to point to your build output directory. +5. Run `npm run package-deploy` (Windows users: `npm run win-package-deploy`) to package and deploy your application. + +To perform a basic, local simulation of API Gateway and Lambda with your Node server, update `api-gateway-event.json` with some values that are valid for your server (`httpMethod`, `path`, `body` etc.) and run `npm run local`. AWS Lambda uses NodeJS 4.3 LTS, and it is recommended to use the same version for testing purposes. + +If you need to make modifications to your API Gateway API, modify `simple-proxy-api.yaml` and run `npm run package-deploy`. If your API requires CORS, be sure to modify the two `options` methods defined in the Swagger file, otherwise you can safely remove them. To modify your other AWS assets, make your changes to `cloudformation.yaml` and run `npm run package-deploy`. Alternatively, you can manage these assets via the AWS console. + +## Node.js version + +This example was written against Node.js version 6.10 diff --git a/example/app.js b/example/app.js index 20fab34a..986fe076 100644 --- a/example/app.js +++ b/example/app.js @@ -14,52 +14,52 @@ app.use(bodyParser.urlencoded({ extended: true })) app.use(awsServerlessExpressMiddleware.eventContext()) app.get('/', (req, res) => { - res.render('index', { - apiUrl: `https://${req.apiGateway.event.headers.Host}/${req.apiGateway.event.requestContext.stage}` - }) + res.render('index', { + apiUrl: req.apiGateway ? `https://${req.apiGateway.event.headers.Host}/${req.apiGateway.event.requestContext.stage}` : 'http://localhost:3000' + }) }) app.get('/sam', (req, res) => { - res.sendFile(`${__dirname}/sam-logo.png`) + res.sendFile(`${__dirname}/sam-logo.png`) }) app.get('/users', (req, res) => { - res.json(users) + res.json(users) }) app.get('/users/:userId', (req, res) => { - const user = getUser(req.params.userId) + const user = getUser(req.params.userId) - if (!user) return res.status(404).json({}) + if (!user) return res.status(404).json({}) - return res.json(user) + return res.json(user) }) app.post('/users', (req, res) => { - const user = { - id: ++userIdCounter, - name: req.body.name - } - users.push(user) - res.status(201).json(user) + const user = { + id: ++userIdCounter, + name: req.body.name + } + users.push(user) + res.status(201).json(user) }) app.put('/users/:userId', (req, res) => { - const user = getUser(req.params.userId) + const user = getUser(req.params.userId) - if (!user) return res.status(404).json({}) + if (!user) return res.status(404).json({}) - user.name = req.body.name - res.json(user) + user.name = req.body.name + res.json(user) }) app.delete('/users/:userId', (req, res) => { - const userIndex = getUserIndex(req.params.userId) + const userIndex = getUserIndex(req.params.userId) - if(userIndex === -1) return res.status(404).json({}) + if(userIndex === -1) return res.status(404).json({}) - users.splice(userIndex, 1) - res.json(users) + users.splice(userIndex, 1) + res.json(users) }) const getUser = (userId) => users.find(u => u.id === parseInt(userId)) @@ -67,11 +67,11 @@ const getUserIndex = (userId) => users.findIndex(u => u.id === parseInt(userId)) // Ephemeral in-memory data store const users = [{ - id: 1, - name: 'Joe' + id: 1, + name: 'Joe' }, { - id: 2, - name: 'Jane' + id: 2, + name: 'Jane' }] let userIdCounter = users.length diff --git a/example/app.local.js b/example/app.local.js new file mode 100644 index 00000000..e8d5ba1c --- /dev/null +++ b/example/app.local.js @@ -0,0 +1,5 @@ +const app = require('./app') +const port = 3000 + +app.listen(port) +console.log(`listening on http://localhost:${port}`) diff --git a/example/cloudformation.yaml b/example/cloudformation.yaml index 870f6b33..41f1a607 100644 --- a/example/cloudformation.yaml +++ b/example/cloudformation.yaml @@ -57,7 +57,7 @@ Resources: Handler: lambda.handler MemorySize: 1024 Role: !GetAtt LambdaExecutionRole.Arn - Runtime: nodejs4.3 + Runtime: nodejs6.10 Timeout: 30 Events: ProxyApiRoot: diff --git a/example/lambda.js b/example/lambda.js index 62a4a472..76bbbdf4 100644 --- a/example/lambda.js +++ b/example/lambda.js @@ -1,11 +1,11 @@ 'use strict' const awsServerlessExpress = require('aws-serverless-express') const app = require('./app') + // NOTE: If you get ERR_CONTENT_DECODING_FAILED in your browser, this is likely // due to a compressed response (e.g. gzip) which has not been handled correctly // by aws-serverless-express and/or API Gateway. Add the necessary MIME types to -// binaryMimeTypes, and to the x-amazon-apigateway-binary-media-types array in -// simple-proxy-api.yaml, then redeploy (`npm run package-deploy`) +// binaryMimeTypes below, then redeploy (`npm run package-deploy`) const binaryMimeTypes = [ 'application/javascript', 'application/json', diff --git a/example/simple-proxy-api.yaml b/example/simple-proxy-api.yaml index 46abb437..e828c75f 100644 --- a/example/simple-proxy-api.yaml +++ b/example/simple-proxy-api.yaml @@ -96,23 +96,7 @@ paths: application/json: "{\"statusCode\": 200}" type: mock x-amazon-apigateway-binary-media-types: - - application/javascript - - application/json - - application/octet-stream - - application/xml - - font/eot - - font/opentype - - font/otf - - image/jpeg - - image/png - - image/svg+xml - - text/comma-separated-values - - text/css - - text/html - - text/javascript - - text/plain - - text/text - - text/xml + - '*/*' definitions: Empty: type: object diff --git a/example/views/index.pug b/example/views/index.pug index d964a44a..b2d78bf9 100644 --- a/example/views/index.pug +++ b/example/views/index.pug @@ -4,9 +4,12 @@ html title My Serverless Application style. body { - width: 600px; + width: 650px; margin: auto; } + h1 { + text-align: center; + } .resources > h2 { margin-bottom: 0; } @@ -23,8 +26,23 @@ html white-space: nowrap; overflow-x: auto; } + .sam-logo { + display: block; + width: 10rem; + margin: auto; + } + form { + margin-bottom: 1rem; + } + .form-group { + padding-bottom: 1rem; + } + label { + display: block; + } body h1 My Serverless Application + img.sam-logo(src='sam') p | Welcome to your AWS serverless application. This example application has several resources configured for you to explore. State is stored in memory in a given container, and is therfore ephemeral - see a(href='https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/', target='_blank') Understanding Container Reuse in AWS Lambda @@ -38,14 +56,14 @@ html code | curl span= apiUrl - | /users -H 'accept: text/html' + | /users -H 'accept: application/json' section.resource h3 POST /users p  Creates a new user. code | curl span= apiUrl - | /users -X POST -d '{"name":"Jake"}' -H 'accept: text/html' + | /users -X POST -d '{"name":"Sam"}' -H 'accept: application/json' section.resource h3 a.resource-example-link(href='users/1') GET /users/:userId @@ -53,18 +71,52 @@ html code | curl span= apiUrl - | /users/1 -H 'accept: text/html' + | /users/1 -H 'accept: application/json' section.resource h3 PUT /users/:userId p  Updates an existing user. code | curl span= apiUrl - | /users/1 -X PUT -d '{"name":"Jane"}' -H 'accept: text/html' + | /users/1 -X PUT -d '{"name":"Samantha"}' -H 'accept: application/json' section.resource h3 DELETE /users/:userId p  Deletes an existing user. code | curl span= apiUrl - | /users/1 -X DELETE -H 'accept: text/html' + | /users/1 -X DELETE -H 'accept: application/json' + + section.form + h2 Form + p Experiment with POST and PUT via the form below. Leave the id empty to create a new user (POST) or enter an id to update a user's name (PUT). + form + div.form-group + label(for='idField') user id + input(type='text' name='id' id='idField' placeholder='optional') + div.form-group + label(for='nameField') name + input(type='text' name='name' id='nameField') + input(type='submit') + + + script. + var form = document.querySelector('form') + form.addEventListener('submit', function(event) { + event.preventDefault() + var id = document.getElementById('idField').value + var name = document.getElementById('nameField').value + var endpoint = id ? 'users/' + id : 'users' + + if (!window.fetch) { + alert('Your browser does not have fetch support, which this demo uses. Try again in a modern browser (https://caniuse.com/fetch) or modify the example to use an alternate approach (e.g. XMLHttpRequest or your library of choice.)') + } + + return fetch(endpoint, { + method: id ? 'PUT' : 'POST', + headers: { + 'content-type': 'application/json' + }, + body: JSON.stringify({ name: name }) + }) + }) diff --git a/index.js b/index.js index bf215a67..9ccc061e 100644 --- a/index.js +++ b/index.js @@ -21,6 +21,15 @@ function getPathWithQueryStringParams(event) { return url.format({ pathname: event.path, query: event.queryStringParameters }) } +function getContentType(params) { + // only compare mime type; ignore encoding part + return params.contentTypeHeader ? params.contentTypeHeader.split(';')[0] : '' +} + +function isContentTypeBinaryMimeType(params) { + return params.binaryMimeTypes.indexOf(params.contentType) !== -1 +} + function mapApiGatewayEventToHttpRequest(event, context, socketPath) { const headers = event.headers || {} // NOTE: Mutating event.headers; prefer deep clone of event.headers const eventWithoutBody = Object.assign({}, event) @@ -47,7 +56,7 @@ function forwardResponseToApiGateway(server, response, context) { response .on('data', (chunk) => buf.push(chunk)) .on('end', () => { - let body = Buffer.concat(buf) + const bodyBuffer = Buffer.concat(buf) const statusCode = response.statusCode const headers = response.headers @@ -70,18 +79,9 @@ function forwardResponseToApiGateway(server, response, context) { } }) - // only compare mime type; ignore encoding part - const contentType = headers['content-type'] ? headers['content-type'].split(';')[0] : '' - let isBase64Encoded - - if (server._binaryTypes.indexOf(contentType) !== -1) { - body = body.toString('base64') - isBase64Encoded = true - } else { - body = body.toString('utf8') - isBase64Encoded = false - } - + const contentType = getContentType({ contentTypeHeader: headers['content-type'] }) + const isBase64Encoded = isContentTypeBinaryMimeType({ contentType, binaryMimeTypes: server._binaryTypes }) + const body = bodyBuffer.toString(isBase64Encoded ? 'base64' : 'utf8') const successResponse = {statusCode, body, headers, isBase64Encoded} context.succeed(successResponse) @@ -115,6 +115,12 @@ function forwardRequestToNodeServer(server, event, context) { const req = http.request(requestOptions, (response) => forwardResponseToApiGateway(server, response, context)) if (event.body) { + const contentType = getContentType({ contentTypeHeader: event.headers['content-type'] }) + + if (isContentTypeBinaryMimeType({ contentType, binaryMimeTypes: server._binaryTypes})) { + event.body = new Buffer(event.body, 'base64').toString('utf8') + } + req.write(event.body) }