feat: #220 AWS Lambda Handler

.github/workflows/aws-lambda.yml

@@ -0,0 +1,26 @@
+name: AWS Lambda Handler
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+  pull_request:
+    branches: [ "master", "develop" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        cache: 'npm'
+    # TODO: Remove when no longer using file dependency
+    - run: npm ci
+      working-directory: ./
+    - run: npm ci
+      working-directory: ./aws-lambda
+    - run: npm test
+      working-directory: ./aws-lambda
+    - run: npm run eslint
+      working-directory: ./aws-lambda

.github/workflows/node.js.yml

@@ -51,5 +51,5 @@ jobs:
           # "dry" causes that if any file is modified, the job fails
           dry: True
           # "write" performs changes in place
-          prettier_options: --write lib/*.ts test/*.js examples/**/*.js
+          prettier_options: --write lib/*.ts test/*.js examples/**/*.js aws-lambda/lib/*.ts aws-lambda/test/*.js
           github_token: ${{ secrets.PERSONAL_GITHUB_TOKEN }}

.gitignore

@@ -1,4 +1,4 @@
-/node_modules/
+node_modules/
 .idea/
 yarn.lock
 

aws-lambda/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+- Initial release

aws-lambda/README.md

@@ -0,0 +1,136 @@
+# Raygun AWS Lambda + Node
+
+[![GitHub CI](https://github.com/MindscapeHQ/raygun4node/actions/workflows/aws-lambda.yml/badge.svg)](https://github.com/MindscapeHQ/raygun4node/actions)
+
+Raygun.com package for AWS Lambda + Node, written in TypeScript.
+
+This package improves the experience when using Raygun with AWS Lambda using JavaScript.
+
+Provides two main advantages compared to using Raygun directly:
+
+1. Captures any uncaught error in the AWS Lambda function and reports it to Raygun automatically.
+2. Scopes Breadcrumbs to the current function session.
+
+## Getting Started
+
+Install the module with: `npm install @raygun.io/aws-lambda`
+
+Set up the Raygun client as described in the [Raygun package](https://www.npmjs.com/package/raygun).
+
+Import the `awsHandler` method:
+
+```js
+const { awsHandler } = require("@raygun/aws-lambda");
+```
+
+### Adding Raygun to a AWS Lambda function
+
+To add Raygun to an existing AWS Lambda function, wrap the existing handler implementation with the `awsHandler` function.
+
+Before:
+
+```js
+exports.handler = async function (event, context) {
+    // your code
+}
+```
+
+After:
+
+```js
+// 1. Configure your Raygun client outside the AWS Lambda function
+const client = new Raygun.client().init( ... );
+
+// 2. Wrap the existing function with awsHandler
+// 3. Pass the client as the first parameter
+exports.handler = awsHandler({ client }, async function (event, context) {
+    // your code
+});
+```
+
+### Using AWS Lambda functions with callbacks
+
+Raygun AWS Lambda handler also supports functions with three parameters and callbacks.
+
+```js
+// Wrap the existing function with callback
+exports.handler = awsHandler({ client }, function (event, context, callback) {
+    // your code
+});
+```
+
+### Sending errors to Raygun from an AWS Lambda function
+
+Any errors thrown in code will be automatically captured by the `awsHandler`.
+
+```js
+exports.handler = awsHandler({ client }, async function (event, context) {
+    // Captured by awsHandler and reported to Raygun
+    throw "error";
+});
+```
+
+Errors are also automatically reported when using the callback version.
+
+```js
+exports.handler = awsHandler({ client }, function (event, context, callback) {
+    // Captured by awsHandler and reported to Raygun
+    callback("error", null);
+});
+```
+
+As well, you can keep using the `send()` method.
+
+```js
+exports.handler = awsHandler({ client }, async function (event, context) {
+    await client.send("error");
+});
+```
+
+**Important:** The `awsHandler` will rethrow the error back to AWS once it has been captured.
+
+### Adding breadcrumbs to Raygun error reports
+
+Breadcumbs are included automatically to all error reports sent from the `awsHandler` or when using the `send()` method.
+
+Call to `client.addBreadcrumb()` to add breadcrumbs.
+
+```js
+exports.handler = awsHandler({ client }, async function (event, context) {
+    // Add a breadcrumb
+    client.addBreadcrumb("breadcrumb");
+
+    // Captured error includes the above breadcrumb
+    throw "error";
+});
+```
+
+### AWS Lambda function context in Custom Data
+
+The `awsHandler` also adds automatically the function call context in the "Custom Data" payload of the error report.
+
+This payload can be found in the "Custom" tab in the Raygun Crash Reporting error report page.
+
+```
+context: {
+  callbackWaitsForEmptyEventLoop: true,
+  functionVersion: "$LATEST",
+  functionName: "xyz",
+  memoryLimitInMB: "128",
+  logGroupName: "/aws/lambda/xyz",
+  logStreamName: "2024/05/31/[$LATEST]xyz",
+  invokedFunctionArn: "arn:aws:lambda:xyz",
+  awsRequestId: "xyz"
+}
+```
+
+## Release History
+
+[View the changelog here](CHANGELOG.md)
+
+## License
+
+Copyright (c) 2024 Raygun Limited
+
+Licensed under the MIT license.
+

aws-lambda/eslint.config.mjs

@@ -0,0 +1,4 @@
+// @ts-check
+// Use config from root project
+import config from "../eslint.config.mjs";
+export default config;

aws-lambda/lib/raygun.aws.ts

@@ -0,0 +1,89 @@
+import { Client } from "raygun";
+import { Context, Handler } from "aws-lambda";
+import { runWithBreadcrumbsAsync } from "raygun/build/raygun.breadcrumbs";
+
+export type AwsHandlerConfig = {
+  client: Client;
+};
+
+// Custom async Handler type without callback
+type AsyncHandler<TEvent, TResult> = (
+  event: TEvent,
+  context: Context,
+) => Promise<TResult>;
+
+// Wrap sync (event, context, callback) in Promise to convert to async (event, context)
+function createAsyncHandler<TEvent, TResult>(
+  handler: Handler<TEvent, TResult>,
+): AsyncHandler<TEvent, TResult> {
+  return (event: TEvent, context: Context) =>
+    new Promise((resolve, reject) => {
+      handler(event, context, (error, result) => {
+        if (error) {
+          reject(error);
+        } else if (result) {
+          resolve(result as never);
+        } else {
+          reject();
+        }
+      });
+    });
+}
+
+async function runHandler<TEvent, TResult>(
+  awsHandlerConfig: AwsHandlerConfig,
+  event: TEvent,
+  context: Context,
+  asyncHandler: AsyncHandler<TEvent, TResult>,
+) {
+  awsHandlerConfig.client.addBreadcrumb(
+    `Running AWS Function: ${context.functionName}`,
+  );
+
+  try {
+    // Call to original handler and return value
+    return await asyncHandler(event, context);
+  } catch (e) {
+    // Capture error and send to Raygun
+
+    // Prepare send parameters
+    const customData = {
+      context: context,
+    };
+    const tags = ["AWS Handler"];
+    const sendParams = {
+      customData,
+      tags,
+    };
+
+    if (e instanceof Error || typeof e === "string") {
+      await awsHandlerConfig.client.send(e, sendParams);
+    } else {
+      await awsHandlerConfig.client.send(`AWS Handler error: ${e}`, sendParams);
+    }
+
+    // rethrow exception to AWS
+    throw e;
+  }
+}
+
+export function awsHandler<TEvent, TResult>(
+  awsHandlerConfig: AwsHandlerConfig,
+  handler: Handler<TEvent, TResult>,
+): AsyncHandler<TEvent, TResult> {
+  let asyncHandler: AsyncHandler<TEvent, TResult>;
+  if (handler.length <= 2) {
+    // handler is async (event, context)
+    asyncHandler = handler as AsyncHandler<TEvent, TResult>;
+  } else {
+    // handler is sync (event, context, callback)
+    asyncHandler = createAsyncHandler(handler);
+  }
+
+  return async (event: TEvent, context: Context) => {
+    // Scope breadcrumbs to this handler event
+    return runWithBreadcrumbsAsync(() => {
+      return runHandler(awsHandlerConfig, event, context, asyncHandler);
+    });
+  };
+}