Add a new ESM lambda wrapper (#319)

Author: bizob2828

.github/workflows/publish-node.yml

@@ -31,7 +31,7 @@ jobs:
         env:
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        run: make publish-nodejs${{ matrix.node-version }}x-ci
+        run: make publish-nodejs${{ matrix.node-version }}-ci
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
         with:
@@ -43,7 +43,7 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         run: |
           cd nodejs
-          ./publish-layers.sh build-publish-nodejs${{ matrix.node-version }}x-ecr-image
+          ./publish-layers.sh build-publish-{{ matrix.node-version }}-ecr-image
       - name: Upload Unit Test Coverage
         if: steps.node-check-tag.outputs.match == 'true'
         uses: codecov/[email protected]

Makefile

@@ -74,62 +74,62 @@ publish-java21-local: build-java21
 		-v "${HOME}/.aws:/home/newrelic-lambda-layers/.aws" \
 		newrelic-lambda-layers-java21
 
-build-nodejs18x:
+build-nodejs18:
 	docker build \
 		--no-cache \
-		-t newrelic-lambda-layers-nodejs18x \
-		-f ./dockerfiles/Dockerfile.nodejs18x \
+		-t newrelic-lambda-layers-nodejs18 \
+		-f ./dockerfiles/Dockerfile.nodejs18 \
 		.
 
-publish-nodejs18x-ci: build-nodejs18x
+publish-nodejs18-ci: build-nodejs18
 	docker run \
 		-e AWS_ACCESS_KEY_ID \
 		-e AWS_SECRET_ACCESS_KEY \
-		newrelic-lambda-layers-nodejs18x
+		newrelic-lambda-layers-nodejs18
 
-publish-nodejs18x-local: build-nodejs18x
+publish-nodejs18-local: build-nodejs18
 	docker run \
 		-e AWS_PROFILE \
 		-v "${HOME}/.aws:/home/newrelic-lambda-layers/.aws" \
-		newrelic-lambda-layers-nodejs18x
+		newrelic-lambda-layers-nodejs18
 
-build-nodejs20x:
+build-nodejs20:
 	docker build \
 		--no-cache \
-		-t newrelic-lambda-layers-nodejs20x \
-		-f ./dockerfiles/Dockerfile.nodejs20x \
+		-t newrelic-lambda-layers-nodejs20 \
+		-f ./dockerfiles/Dockerfile.nodejs20 \
 		.
 
-publish-nodejs20x-ci: build-nodejs20x
+publish-nodejs20-ci: build-nodejs20
 	docker run \
 		-e AWS_ACCESS_KEY_ID \
 		-e AWS_SECRET_ACCESS_KEY \
-		newrelic-lambda-layers-nodejs20x
+		newrelic-lambda-layers-nodejs20
 
-publish-nodejs20x-local: build-nodejs20x
+publish-nodejs20-local: build-nodejs20
 	docker run \
 		-e AWS_PROFILE \
 		-v "${HOME}/.aws:/home/newrelic-lambda-layers/.aws" \
-		newrelic-lambda-layers-nodejs20x
+		newrelic-lambda-layers-nodejs20
 
-build-nodejs22x:
+build-nodejs22:
 	docker build \
 		--no-cache \
-		-t newrelic-lambda-layers-nodejs22x \
-		-f ./dockerfiles/Dockerfile.nodejs22x \
+		-t newrelic-lambda-layers-nodejs22 \
+		-f ./dockerfiles/Dockerfile.nodejs22 \
 		.
 
-publish-nodejs22x-ci: build-nodejs22x
+publish-nodejs22-ci: build-nodejs22
 	docker run \
 		-e AWS_ACCESS_KEY_ID \
 		-e AWS_SECRET_ACCESS_KEY \
-		newrelic-lambda-layers-nodejs22x
+		newrelic-lambda-layers-nodejs22
 
-publish-nodejs22x-local: build-nodejs22x
+publish-nodejs22-local: build-nodejs22
 	docker run \
 		-e AWS_PROFILE \
 		-v "${HOME}/.aws:/home/newrelic-lambda-layers/.aws" \
-		newrelic-lambda-layers-nodejs22x
+		newrelic-lambda-layers-nodejs22
 
 build-ruby32:
 	docker build \

README.md

@@ -26,7 +26,7 @@ cd ..
 
 ```
 cd nodejs
-./publish-layers.sh nodejs20x 
+./publish-layers.sh nodejs20 
 cd ..
 ```
 
@@ -78,7 +78,9 @@ These steps will help you configure the layers correctly:
   * Using Cloudformation, this refers to adding your layer arn to the Layers property of a [AWS::Lambda::Function resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html).
 3. Update your functions handler to point to the newly attached layer in the console for your function:
   * Python: `newrelic_lambda_wrapper.handler`
-  * Node: `newrelic-lambda-wrapper.handler`
+  * Node: 
+    * CommonJS: `newrelic-lambda-wrapper.handler`
+    * ESM: `/opt/nodejs/node_modules/newrelic-esm-lambda-wrapper/index.handler` - You must specify the full path to the wrapper in the layer because the AWS Lambda Runtime doesn't support importing from a layer.
   * Ruby: `newrelic_lambda_wrapper.handler`
   * Java:
     * RequestHandler implementation: `com.newrelic.java.HandlerWrapper::handleRequest`
@@ -97,42 +99,14 @@ Refer to the [New Relic AWS Lambda Monitoring Documentation](https://docs.newrel
 
 ## Support for ES Modules (Node.js)
 
-AWS announced support for Node 18 as a Lambda runtime in late 2022, introducing `aws-sdk` version 3 for Node 18 only. This version of `aws-sdk` patches `NODE_PATH`, so ESM-supporting functions using `import` and top-level `await` should work as expected with Lambda Layer releases `v9.8.1.1` and above (Numerical layer versions vary by region and runtime). To configure the layer to leverage `import`, add the environment variable `NEW_RELIC_USE_ESM: true`, and add this environment variable to use our ESM loader: `NODE_OPTIONS: --experimental-loader newrelic/esm-loader.mjs`.
+AWS announced support for Node 18 as a Lambda runtime in late 2022, introducing `aws-sdk` version 3 for Node 18 only. This version of `aws-sdk` patches `NODE_PATH`, so ESM-supporting functions using `import` and top-level `await` should work as expected with Lambda Layer releases `v9.8.1.1` and above (Numerical layer versions vary by region and runtime). To configure the layer to leverage `import`, add this environment variable to use our ESM loader: `NODE_OPTIONS: --experimental-loader newrelic/esm-loader.mjs`. **Note**: The function handler should also use `newrelic-esm-lambda-wrapper.handler`.
 
-Note that if you use layer-installed instrumentation with the `NEW_RELIC_USE_ESM` environment variable, your function must use promises or async/await; callback based functions are not supported. The Node wrapper uses a [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) to attach to your function, which is an asynchronous operation. If you still need support for callback based functions, you will have to use the CommonJS based wrapper, which can be done by removing the `NEW_RELIC_USE_ESM` environment variable.
+### Note on performance for ES Module functions
 
-You may see some warnings from the Extension in CloudWatch logs referring to a non-standard handler; these warnings may be ignored.
+If you are using the legacy `NEW_RELIC_USE_ESM` flag on the `newrelic-lambda-wrapper.handler`, and your ESM function depends on a large number of dependency and file imports, you may see long cold start times as a result. As a workaround, we recommend  using the ESM wrapper. Set your handler to `/opt/nodejs/node_modules/newrelic-esm-lambda-wrapper/index.handler`.
 
-If your Node functions use `import` and top-level `await` in Node 16 or Node 14 runtimes, layer-installed instrumentation will be unable to find imported modules, as [`import` specifiers don't resolve with `NODE_PATH`](https://nodejs.org/docs/latest-v16.x/api/esm.html#no-node_path). You can still instrument your functions with New Relic, but you will need to do the following:
-
-1. [instrument your function manually](#manual-instrumentation-for-es-modules) using our [Node Agent](https://github.com/newrelic/node-newrelic/) 
-2. On deploying your function, don't set the function handler to our Node wrapper; instead, use your regular handler function, which you've wrapped with `newrelic.setLambdaHandler()`.
-3. If you're using Node 18 or above, apply the latest Lambda Layer for your runtime. It will install both the Node agent and our Lambda Extension.
-4. If you're using Node 14 or Node 16, you will have to deploy our agent with your function code, but you could use our Extension-only Lambda Layer for delivering telemetry. Use our [layer discovery website](https://layers.newrelic-external.com/) to find the ARN for your region. Look for either NewRelicLambdaExtension or NewRelicLambdaExtensionARM64 (depending on your function's architecture).
-4. Add your `NEW_RELIC_LICENSE_KEY` as an environment variable.
-
-## Note on performance for ES Module functions
-
-In order to wrap ESM functions without a code change, our wrapper awaits the completion of a dynamic import. If your ESM function depends on a large number of dependency and file imports, you may see long cold start times as a result. As a workaround, we recommend instrumenting manually, following the instructions below.
-
-## Manual instrumentation for ES Modules
-
-First import the New Relic Node agent into your handler file:
-
-```javascript
-import newrelic from 'newrelic'
-```
-
-Then wrap your handler function using the `.setLambdaHandler` method: 
-```javascript
-export const handler = newrelic.setLambdaHandler(async (event, context) => {
-    // TODO implement
-    return {
-        statusCode: 200,
-        body: JSON.stringify('Hello from Lambda!')
-    }
-})
-```
+### Note on legacy `NEW_RELIC_USE_ESM` environment variable
+Prior to Lambda Layer releases `v12.16.0`, the wrapper for CommonJS and ESM were the same. If you wanted to wrap a ESM lambda handler you had to set `NEW_RELIC_USE_ESM` to `true`. This functionality still exists but has been deprecated.  If you have a ESM lambda handler set the function handler to point to `newrelic-esm-lambda-wrapper.handler`.  We will be removing `NEW_RELIC_USE_ESM` at a future date. 
 
 ## Support
 

dockerfiles/Dockerfile.nodejs18x renamed to dockerfiles/Dockerfile.nodejs18

@@ -11,7 +11,7 @@ COPY --chown=newrelic-lambda-layers libBuild.sh .
 COPY --chown=newrelic-lambda-layers nodejs nodejs/
 
 WORKDIR nodejs
-RUN ./publish-layers.sh build-nodejs18x
+RUN ./publish-layers.sh build-18
 
 FROM python:3.8
 
@@ -26,4 +26,4 @@ COPY nodejs nodejs/
 COPY --from=builder /home/newrelic-lambda-layers/nodejs/dist nodejs/dist
 
 WORKDIR nodejs
-CMD ./publish-layers.sh publish-nodejs18x
+CMD ./publish-layers.sh publish-18

dockerfiles/Dockerfile.nodejs20x renamed to dockerfiles/Dockerfile.nodejs20

@@ -11,7 +11,7 @@ COPY --chown=newrelic-lambda-layers libBuild.sh .
 COPY --chown=newrelic-lambda-layers nodejs nodejs/
 
 WORKDIR nodejs
-RUN ./publish-layers.sh build-nodejs20x
+RUN ./publish-layers.sh build-20
 
 FROM python:3.8
 
@@ -26,4 +26,4 @@ COPY nodejs nodejs/
 COPY --from=builder /home/newrelic-lambda-layers/nodejs/dist nodejs/dist
 
 WORKDIR nodejs
-CMD ./publish-layers.sh publish-nodejs20x
+CMD ./publish-layers.sh publish-20

dockerfiles/Dockerfile.nodejs22x renamed to dockerfiles/Dockerfile.nodejs22

@@ -11,7 +11,7 @@ COPY --chown=newrelic-lambda-layers libBuild.sh .
 COPY --chown=newrelic-lambda-layers nodejs nodejs/
 
 WORKDIR nodejs
-RUN ./publish-layers.sh build-nodejs22x
+RUN ./publish-layers.sh build-22
 
 FROM python:3.8
 
@@ -26,4 +26,4 @@ COPY nodejs nodejs/
 COPY --from=builder /home/newrelic-lambda-layers/nodejs/dist nodejs/dist
 
 WORKDIR nodejs
-CMD ./publish-layers.sh publish-nodejs22x
+CMD ./publish-layers.sh publish-22

nodejs/esm.mjs

@@ -0,0 +1,105 @@
+import newrelic from 'newrelic'
+import fs from 'node:fs'
+import path from 'node:path'
+
+process.env.NEW_RELIC_APP_NAME = process.env.NEW_RELIC_APP_NAME || process.env.AWS_LAMBDA_FUNCTION_NAME
+process.env.NEW_RELIC_DISTRIBUTED_TRACING_ENABLED = process.env.NEW_RELIC_DISTRIBUTED_TRACING_ENABLED || 'true'
+process.env.NEW_RELIC_NO_CONFIG_FILE = process.env.NEW_RELIC_NO_CONFIG_FILE || 'true'
+process.env.NEW_RELIC_TRUSTED_ACCOUNT_KEY =
+  process.env.NEW_RELIC_TRUSTED_ACCOUNT_KEY || process.env.NEW_RELIC_ACCOUNT_ID
+
+if (process.env.LAMBDA_TASK_ROOT && typeof process.env.NEW_RELIC_SERVERLESS_MODE_ENABLED !== 'undefined') {
+  delete process.env.NEW_RELIC_SERVERLESS_MODE_ENABLED
+}
+
+function getHandlerPath() {
+  let handler
+  const { NEW_RELIC_LAMBDA_HANDLER } = process.env
+
+  if (!NEW_RELIC_LAMBDA_HANDLER) {
+    throw new Error('No NEW_RELIC_LAMBDA_HANDLER environment variable set.')
+  } else {
+    handler = NEW_RELIC_LAMBDA_HANDLER
+  }
+
+  const parts = handler.split('.')
+
+  if (parts.length < 2) {
+    throw new Error(
+      `Improperly formatted handler environment variable: ${handler}`
+    )
+  }
+
+  const handlerToWrap = parts[parts.length - 1]
+  const moduleToImport = handler.slice(0, handler.lastIndexOf('.'))
+  return { moduleToImport, handlerToWrap }
+}
+
+function handleRequireImportError(e, moduleToImport) {
+  if (e.code === 'MODULE_NOT_FOUND') {
+    return new Error(`Unable to import module '${moduleToImport}'`)
+  }
+  return e
+}
+
+function getFullyQualifiedModulePath(modulePath, extensions) {
+  let fullModulePath
+
+  extensions.forEach((extension) => {
+    const filePath = modulePath + extension
+    if (fs.existsSync(filePath)) {
+      fullModulePath = filePath
+      return
+    }
+  })
+
+  if (!fullModulePath) {
+    throw new Error(
+      `Unable to resolve module file at ${modulePath} with the following extensions: ${extensions.join(',')}`
+    )
+  }
+
+  return fullModulePath
+}
+
+async function getModuleWithImport(appRoot, moduleToImport) {
+  const modulePath = path.resolve(appRoot, moduleToImport)
+  const validExtensions = ['.mjs', '.js']
+  const fullModulePath = getFullyQualifiedModulePath(modulePath, validExtensions)
+
+  try {
+    return await import(fullModulePath)
+  } catch (err) {
+    throw handleRequireImportError(err, moduleToImport)
+  }
+}
+
+function validateHandlerDefinition(userHandler, handlerName, moduleName) {
+  if (typeof userHandler === 'undefined') {
+    throw new Error(
+      `Handler '${handlerName}' missing on module '${moduleName}'`
+    )
+  }
+
+  if (typeof userHandler !== 'function') {
+    throw new Error(
+      `Handler '${handlerName}' from '${moduleName}' is not a function`
+    )
+  }
+}
+
+const { LAMBDA_TASK_ROOT = '.' } = process.env
+const { moduleToImport, handlerToWrap } = getHandlerPath()
+
+const userHandler  = await getHandler() 
+const handler = newrelic.setLambdaHandler(userHandler)
+
+async function getHandler() {
+  const userHandler = (await getModuleWithImport(LAMBDA_TASK_ROOT, moduleToImport))[handlerToWrap]
+  validateHandlerDefinition(userHandler, handlerToWrap, moduleToImport)
+
+  return userHandler
+}
+  
+export { handler, getHandlerPath }
+

nodejs/index.js

@@ -135,12 +135,17 @@ async function patchHandler() {
   return patchedHandlerPromise
     .then(_wrappedHandler => _wrappedHandler.apply(this, args))
 }
-function patchHandlerSync() {
-  const args = Array.prototype.slice.call(arguments)
-  return wrappedHandler.apply(this, args)
+
+let handler 
+
+if (process.env.NEW_RELIC_USE_ESM === 'true') {
+  handler = patchHandler
+} else {
+  handler = wrappedHandler
 }
 
+
 module.exports = {
-  handler: process.env.NEW_RELIC_USE_ESM === 'true' ? patchHandler : patchHandlerSync,
+  handler,
   getHandlerPath
 }