u-minor/aglex

API Gateway + Lambda + Express development tool

Aglex is a support tool for building serverless web applications using Amazon API Gateway, AWS Lambda and Express.

No more new frameworks for Lambda + API Gateway!

Express is the most famous web framework for Node.js. Now you can use the same way to develop your API Gateway-Lambda web app.

UPDATE: now 2.x uses aws-serverless-express and new config yaml.

Installation

Global install

$ npm install aglex -g

or install and add to current package.

$ npm install aglex --save-dev

Features

Aglex is not a web framework, just a small CLI tool which provides following features.

• Generate a small lambda handler code
• Create, update lambda function
• Add execute-api permission to the function
• Create, update and deploy API

Quick start

1. Start your app with express-generator.

$ npm install express-generator -g
$ express myapp
$ cd myapp && npm install

2. Modify routes/users.js to respond JSON data.

@@ -3,7 +3,7 @@

 /* GET users listing. */
 router.get('/', function(req, res, next) {
-  res.send('respond with a resource');
+  res.json({message: 'respond with a resource'});
 });

 module.exports = router;

3. Generate config yaml

$ aglex generate config > aglex.yml

Edit it to match your environment.

@@ -18,14 +18,14 @@
   Runtime: nodejs4.3
   MemorySize: 128
   Timeout: 60
-  FunctionName: YOUR_LAMBDA_FUNCTION_NAME
-  Description: YOUR_LAMBDA_DESCRIPTION
-  RoleName: YOUR_LAMBDA_EXECUTION_ROLE # Role ARN will generate from RoleName automatically
+  FunctionName: myapp
+  Description: myapp
+  RoleName: lambda-myapp # Role ARN will generate from RoleName automatically

 ## API Gateway configuration
 apiGateway:
   swagger: 2.0
   info:
-    title: YOUR_API_NAME
-    description: YOUR_API_DESCRIPTION
+    title: myapp
+    description: myapp
   basePath: /prod
   schemes:
     - https

4. Generate lambda handler code and install aws-serverless-express

$ aglex generate lambda-handler > lambda.js
$ npm install -S aws-serverless-express

5. Create lambda zip

$ zip -r lambda.zip app.js lambda.js routes views node_modules

Use Gulp/Grunt if you want to do more tasks.

6. Create/update your lambda function

$ aglex --config aglex.yml lambda update --zip lambda.zip

Create IAM Role for Lambda function lambda-myapp before execution.

7. Add execute permission to your lambda function (first time only)

$ aglex --config aglex.yml lambda add-permission

8. Create/update API

$ aglex --config aglex.yml apigateway update

9. Create stage and deploy API

$ aglex --config aglex.yml apigateway deploy --stage dev

For more information, please see wiki docs.

See Also

• aws-serverless-express is developed by AWS to make it easy to run Express apps on Lambda.

aglex's Issues

`req.url` not being set

I figured out how to deploy and update the API Gateway using this tool. However, when I try to access a resource, I get this failure:

{
errorMessage: "Cannot call method 'indexOf' of undefined",
errorType: "TypeError",
stackTrace: [
"Function.handle (/var/task/node_modules/express/lib/router/index.js:140:28)",
"EventEmitter.handle (/var/task/node_modules/express/lib/application.js:173:10)",
"app (/var/task/node_modules/express/lib/express.js:38:9)",
"exports.handler (/var/task/lambda.js:61:5)"
]
}

In looked in the express source code, and it's failing because req.url is undefined, but Express expects that not to be the case.

I looked in API Gateway and found that a reasonable looking body mapping template was defined:

{
  "method": "$context.httpMethod",
  "remoteAddr": "$context.identity.sourceIp",
  "stage": "$context.stage",
  "path": "$context.resourcePath",
  "headers": {
#foreach ($key in $input.params().header.keySet())
    "$key": "$util.escapeJavaScript($input.params().header.get($key))",
#end
    "User-Agent": "$context.identity.userAgent"
  },
  "pathParams": {
#foreach ($key in $input.params().path.keySet())
    "$key": "$util.escapeJavaScript($input.params().path.get($key))"#if ($foreach.hasNext),#end
#end
  },
  "queryParams": {
#foreach ($key in $input.params().querystring.keySet())
    "$key": "$util.escapeJavaScript($input.params().querystring.get($key))"#if ($foreach.hasNext),#end
#end
  },
  "body": $input.json('$')
}

I also looked in lambda.js, and it does appear to set req.url based on event.path so I'm not yet clear where the bug is.

I'll look some more.

Following Quick start guide throws: "Error: Cannot find module './apiGateway/restApi'"

Thank your this module.

It looks useful and I would like to try it.

However, I get this error in the Quick Start steps:

$ aglex generate config >aglex.yml
module.js:327
    throw err;
    ^

Error: Cannot find module './apiGateway/restApi'
    at Function.Module._resolveFilename (module.js:325:15)
    at Function.Module._load (module.js:276:25)
    at Module.require (module.js:353:17)
    at require (internal/module.js:12:17)
    at Object.<anonymous> (/home/mark/.nvm/versions/node/v4.4.1/lib/node_modules/aglex/lib/apiGateway.js:3:15)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Module.require (module.js:353:17)

Wish: default to Node 4.3 environment

Currently the Lambda is being set to run in the Node 0.10 environment. Setting the default to Node 4.3 would be preferred to take advantage of newer syntax. Having a runtime config option in the YAML file could be useful.

Wish: Add docs for API Gateway stage and deploy commands

Version 0.2.0 added support 'stages' and 'deploy' subcommands for apigateway. It would be helpful if these were documented in the quick guide in the README.

Thank you.

wish: document the IAM minimal permissions need to deploy to Lambda and update API Gateway.

A great user experience might be to expect that setup is done with a "Power User" account.

At this stage an IAM user would be created for the purpose of deploying to this API and a policy would be attached to it that restricts it to managing just the functions.

Publishing a sample IAM policy for others to use would also be helpful.

wish: compare to express-on-serverless

Since this project started, AWS has added the new "proxy" feature to "AWS Gateway" and the serverless project has appeared as well. There's even a project called express on serverless that focuses on making Express easy on serverless.

With aglex there are several steps and a fair bit of syntax to remember for a basic deploy flow:

• zip -r lambda.zip app.js lambda.js routes views node_modules
• aglex --config aglex.yml lambda update --zip lambda.zip
• aglex --config aglex.yml apigateway update
• aglex --config aglex.yml apigateway deploy --stage dev

With express-on-serverless, it's just one easy to remember command:

• serverless deploy

Also, the README says that JSON must always be returned here, while express-on-serverless does not have that restriction. It would be helpful if the docs clarified the benefits of using aglex over serverless.