[SUP-1281] AWS Lambda example app

examples/aws-lambda/simple-app/.gitignore

@@ -0,0 +1 @@
+.aws-sam

examples/aws-lambda/simple-app/README.md

@@ -0,0 +1,72 @@
+# AWS Lambda
+
+This is an example project showing how to use `@bugsnag/js` with AWS Lambda.
+
+This project was initialized with [`sam init`](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-init.html).
+
+## Prerequsities
+- [SAM CLI tools](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+- [Docker](https://docs.docker.com/get-docker/) is installed and running on your machine (only if testing locally)
+
+## Usage
+
+Clone the repo and `cd` into the directory of this example:
+
+```
+git clone [email protected]:bugsnag/bugsnag-js.git
+cd bugsnag-js/examples/aws-lambda/simple-app
+```
+- Bugsnag is started for each Lambda function with `Bugsnag.start` and the `@bugsnag/plugin-aws-lambda` plugin
+- Errors in your Lambda are handled by wrapping your Lambda handler inside Bugsnag's handler
+- Both async and callback handlers are supported, with examples given for both inside this app
+
+Replace `<YOUR_BUGSNAG_API_KEY>` in `template.yaml` with your own.
+
+### Install dependencies
+A Lambda layer is used to share dependencies (Bugsnag) across the functions. From the project root, install the dependecies before invoking the functions:
+```
+cd dependecies-layer
+npm install
+```
+### Build
+```
+sam build
+```
+
+### Run all functions locally
+To run all the functions on a local server:
+```
+sam local start-api --host '127.0.0.1' -p '3000'
+```
+To avoid building the dependency layer image on each invocation, you can use the `--warm-containers [EAGER | LAZY]` option. `EAGER` loads the layer containers for all functions at startup + persists them between invocations. `LAZY` only loads the layer containers when each function is first invoked, and then persists them for further invocations.
+
+
+Hit a function endpoint:
+```
+curl -X GET 'http://127.0.0.1:3000/async/handled-exception'
+```
+### Testing a single function
+To test a single function using a sample [Event](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html#gettingstarted-concepts-event):
+```
+sam local invoke "<RESOURCE_NAME>" -e <path/to/event.json>
+```
+e.g. to run the `CallbackHandledException` function:
+```
+sam local invoke "CallbackHandledException" -e events/callback/handled-exception.json
+```
+
+### Available functions
+
+Bugsnag's `createHandler` supports both [`async`](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html#nodejs-handler-async) and [`callback`](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html#nodejs-handler-sync) handlers. Examples are given for both types of handler.
+Function Name | Expected Response Code & Message | Purpose
+--- | --- | ---
+ `AsyncUnhandledException`| 502 - Internal server error | Error returned from the handler
+ `AsyncHandledException` | 200 - Did not crash! | Call to `Bugsnag.notify` inside the handler, successful response
+ `AsyncPromiseRejection` | 502 - Internal server error | Promise rejected inside handler
+ `AsyncTimeout` | 502 - Internal server error | Function times out - Bugsnag notifies [`lambdaTimeoutNotifyMs`](https://docs.bugsnag.com/platforms/javascript/aws-lambda/#lambdatimeoutnotifyms) before timeout
+ `CallbackUnhandledException` | 502 - Internal server error |  Error returned using handler's callback function
+ `CallbackThrownUnhandledException` | 502 - Internal server error | Error thrown inside the handler
+ `CallbackHandledException` | 200 - Did not crash! | Call to `Bugsnag.notify` inside the handler, successful response
+ `CallbackPromiseRejection` | 502 - Internal server error | Promise rejected inside handler
+ `CallbackTimeout` | 502 - Internal server error | Function times out - Bugsnag notifies [`lambdaTimeoutNotifyMs`](https://docs.bugsnag.com/platforms/javascript/aws-lambda/#lambdatimeoutnotifyms) before timeout
+

examples/aws-lambda/simple-app/async/handled-exception/async-handled-exception.js

@@ -0,0 +1,25 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = async (event, _context) => {
+  Bugsnag.notify(new Error('Bad thing!'), (e) => {
+    e.context = "Don't worry - I handled it"
+  })
+  console.log('a handled error was sent to our dashboard!')
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      route: event.path,
+      message: 'Did not crash!'
+    })
+  }
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/async/handled-exception/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "async-handled-exception",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/async/promise-rejection/async-promise-rejection.js

@@ -0,0 +1,20 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = async (_event, _context) => {
+  Promise.reject(new Error('yikes - a rejected promise!'))
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ message: 'Did not crash!' })
+  }
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/async/promise-rejection/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "async-promise-rejection",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/async/timeout/async-timeout.js

@@ -0,0 +1,23 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
+  lambdaTimeoutNotifyMs: 2000 // set to notify 2000ms before timeout  (default)
+})
+
+// due to a bug in AWS lambda this will not notify when running with SAM CLI: https://github.com/aws/aws-sam-cli/issues/2519
+const handler = async (_event, _context) => {
+  await new Promise((resolve) => setTimeout(resolve, 4000)) // function timeout is 3000ms as per template.yaml
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ message: 'Did not crash!' })
+  }
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/async/timeout/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "async-timeout",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/async/unhandled-exception/async-unhandled-exception.js

@@ -0,0 +1,15 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = async (_event, _context) => {
+  throw new Error('Bad thing!')
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/async/unhandled-exception/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "async-unhandled-exception",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/callback/handled-exception/callback-handled-exception.js

@@ -0,0 +1,25 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = (event, _context, callback) => {
+  Bugsnag.notify(new Error('Bad thing!'), (e) => {
+    e.context = "Don't worry - I handled it"
+  })
+  console.log('a handled error was sent to our dashboard!')
+  callback(null, {
+    statusCode: 200,
+    body: JSON.stringify({
+      route: event.path,
+      message: 'Did not crash!'
+    })
+  })
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/callback/handled-exception/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "callback-handled-exception",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/callback/promise-rejection/callback-promise-rejection.js

@@ -0,0 +1,20 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = (_event, _context, callback) => {
+  Promise.reject(new Error('yikes - a rejected promise!'))
+
+  callback(null, {
+    statusCode: 200,
+    body: JSON.stringify({ message: 'Did not crash!' })
+  })
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/callback/promise-rejection/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "callback-promise-rejection",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/callback/thrown-unhandled-exception/callback-thrown-unhandled-exception.js

@@ -0,0 +1,15 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = (_event, _context, _callback) => {
+  throw new Error('Oh no!')
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/callback/thrown-unhandled-exception/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "callback-thrown-unhandled-exception",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/callback/timeout/callback-timeout.js

@@ -0,0 +1,23 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
+  lambdaTimeoutNotifyMs: 2000 // set to notify 2000ms before timeout
+})
+
+// due to a bug in AWS lambda this will not notify when running with SAM CLI: https://github.com/aws/aws-sam-cli/issues/2519
+const handler = async (_event, _context, callback) => {
+  await new Promise((resolve) => setTimeout(resolve, 4000)) // function timeout is 3000ms as per template.yaml
+
+  callback(null, {
+    statusCode: 200,
+    body: JSON.stringify({ message: 'Did not crash!' })
+  })
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/callback/timeout/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "callback-timeout",
+    "version": "1.0.0"
+}

examples/aws-lambda/simple-app/callback/unhandled-exception/callback-unhandled-exception.js

@@ -0,0 +1,15 @@
+const Bugsnag = require('@bugsnag/js')
+const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
+
+Bugsnag.start({
+  apiKey: process.env.BUGSNAG_API_KEY,
+  plugins: [BugsnagPluginAwsLambda]
+})
+
+const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()
+
+const handler = (event, context, callback) => {
+  callback(new Error('Oh no!'))
+}
+
+module.exports.lambdaHandler = bugsnagHandler(handler)

examples/aws-lambda/simple-app/callback/unhandled-exception/package.json

@@ -0,0 +1,4 @@
+{
+    "name": "callback-unhandled-exception",
+    "version": "1.0.0"
+}