CX-24943: add support for NodeJS 24 (#73)

Adapted the `instrumentation.ts` and `cx-wrapper` to handle some changes
introduced in `contrib`:
- For Node 24 (and any runtime where callbacks are absent by default)
still accept a user-provided callback.
- Added support for promise-only handlers so cold-start failures surface
consistently.
- Improve module path resolution (newer NodeJS versions no longer append
`js` variants). This avoids issues like:
```json
{ "errorType": "Runtime.ImportModuleError", "errorMessage": "Error: Cannot find module 'UserFunction.js'\nRequire stack:\n- /opt/nodejs/node_modules/cx-wrapper/loader.js\n- /opt/nodejs/node_modules/cx-wrapper/index.js\n- /var/runtime/index.mjs", "trace": [ "Runtime.ImportModuleError: Error: Cannot find module 'UserFunction.js'", "Require stack:", "- /opt/nodejs/node_modules/cx-wrapper/loader.js", "- /opt/nodejs/node_modules/cx-wrapper/index.js", "- /var/runtime/index.mjs", " at loadModule (file:///var/runtime/index.mjs:573:13)", " at async UserFunctionLoader.load (file:///var/runtime/index.mjs:504:20)", " at async createRuntime (file:///var/runtime/index.mjs:1217:52)", " at async ignition (file:///var/runtime/index.mjs:1633:21)" ] }
```


Tested manually for Node JS 18 and 24. Tested if the times increased due to the new changes. Nothing found.

Author: iblancasa

.github/workflows/publish-nodejs.yml

@@ -104,5 +104,5 @@ jobs:
     - name: Publish layer
       env:
         LAYER_NAME: "coralogix-opentelemetry-nodejs-wrapper"
-        COMPATIBLE_RUNTIMES: "nodejs18.x nodejs20.x nodejs22.x"
+        COMPATIBLE_RUNTIMES: "nodejs18.x nodejs20.x nodejs22.x nodejs24.x"
       run: ./ci-scripts/publish_${{ inputs.environment }}.sh

dev/deploy-nodejs.sh

@@ -23,7 +23,7 @@ fi
 output=$(aws lambda publish-layer-version \
   --layer-name "$LAMBDA_LAYER_PREFIX-coralogix-opentelemetry-nodejs-wrapper-development" \
   --compatible-architectures x86_64 arm64 \
-  --compatible-runtimes nodejs18.x nodejs20.x nodejs22.x \
+  --compatible-runtimes nodejs18.x nodejs20.x nodejs22.x nodejs24.x \
   --zip-file fileb://nodejs/packages/layer/build/layer.zip \
   --region eu-west-1 \
   --profile "$AWS_PROFILE" \

nodejs/packages/cx-wrapper/index.ts

@@ -5,7 +5,7 @@ import { getEnv } from '@opentelemetry/core';
 diag.setLogger(new DiagConsoleLogger(), getEnv().OTEL_LOG_LEVEL);
 
 import { Callback, Context } from 'aws-lambda';
-import { Handler } from "aws-lambda/handler.js";
+import { Handler } from 'aws-lambda/handler.js';
 import { load } from './loader.js';
 import { initializeInstrumentations } from './instrumentation-init.js';
 import { initializeProvider } from './provider-init.js';
@@ -50,28 +50,83 @@ if (parseBooleanEnvvar("OTEL_WARM_UP_EXPORTER") ?? true) {
   } catch (e) {}
 }
 
-export const handler = (event: any, context: Context, callback: Callback) => {
-  diag.debug(`Loading original handler ${process.env.CX_ORIGINAL_HANDLER}`);
-  load(
-    process.env.LAMBDA_TASK_ROOT,
-    process.env.CX_ORIGINAL_HANDLER
-  ).then(
-    (originalHandler) => {
-      try {
-        diag.debug(`Instrumenting handler`);
-        const patchedHandler = lambdaInstrumentation.getPatchHandler(originalHandler) as any as Handler;
-        diag.debug(`Running CX handler and redirecting to ${process.env.CX_ORIGINAL_HANDLER}`)
-        patchedHandler(event, context, callback);
-      } catch (err: any) {
-        context.callbackWaitsForEmptyEventLoop = false;
-        callback(err, null);
+async function invokePatchedHandler(
+  patchedHandler: Handler,
+  event: any,
+  context: Context
+) {
+  // Handlers that declare a callback parameter should only resolve via that callback;
+  // short‑circuiting their returned promise causes API Gateway to receive `undefined`.
+  const expectsCallback = patchedHandler.length >= 3;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const wrappedCallback: Callback = (err, result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (err) {
+        reject(err);
+      } else {
+        resolve(result);
+      }
+    };
+
+    try {
+      const maybePromise = patchedHandler(event, context, wrappedCallback);
+      if (
+        maybePromise &&
+        typeof (maybePromise as Promise<unknown>).then === 'function'
+      ) {
+        (maybePromise as Promise<unknown>).then(
+          value => {
+            if (!settled && !expectsCallback) {
+              settled = true;
+              resolve(value);
+            }
+          },
+          err => {
+            if (!settled) {
+              settled = true;
+              reject(err);
+            }
+          }
+        );
+      } else if (!expectsCallback) {
+        settled = true;
+        resolve(maybePromise);
+      }
+    } catch (err) {
+      if (!settled) {
+        settled = true;
+        reject(err);
       }
-    },
-    (err: Error | string) => {
-      context.callbackWaitsForEmptyEventLoop = false;
-      callback(err, null)
     }
-  );
+  });
 }
 
-diag.debug('OpenTelemetry instrumentation is ready');
+export const handler = async (event: any, context: Context) => {
+  diag.debug(`Loading original handler ${process.env.CX_ORIGINAL_HANDLER}`);
+  try {
+    const originalHandler = await load(
+      process.env.LAMBDA_TASK_ROOT,
+      process.env.CX_ORIGINAL_HANDLER
+    );
+
+    diag.debug(`Instrumenting handler`);
+    const patchedHandler = lambdaInstrumentation.getPatchHandler(
+      originalHandler
+    ) as unknown as Handler;
+    diag.debug(
+      `Running CX handler and redirecting to ${process.env.CX_ORIGINAL_HANDLER}`
+    );
+    return await invokePatchedHandler(patchedHandler, event, context);
+  } catch (err) {
+    context.callbackWaitsForEmptyEventLoop = false;
+    diag.error('CX handler failed to execute', err as Error);
+    throw err;
+  }
+};
+
+diag.debug('OpenTelemetry instrumentation is ready');

nodejs/packages/cx-wrapper/loader.js

@@ -1,3 +1,107 @@
-const { load } = require('UserFunction.js'); // https://github.com/aws/aws-lambda-nodejs-runtime-interface-client/blob/main/src/UserFunction.js
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
 
-module.exports.load = load
+const DEBUG = process.env.CX_DEBUG_USER_FUNCTION_RESOLUTION === 'true';
+
+function logDebug(message) {
+  if (DEBUG) {
+    // eslint-disable-next-line no-console
+    console.debug(`[cx-wrapper] ${message}`);
+  }
+}
+
+// Break "module.sub.handler" into the module path and exported symbol chain.
+function splitHandlerString(handler) {
+  const lastDot = handler.lastIndexOf('.');
+  if (lastDot === -1 || lastDot === handler.length - 1) {
+    throw new Error(
+      `CX handler "${handler}" must be in "module.submodule.handler" format.`
+    );
+  }
+  return [handler.slice(0, lastDot), handler.slice(lastDot + 1)];
+}
+
+// Walk the export tree (foo.bar.baz) to grab the final handler reference.
+function resolveHandler(userApp, handlerPath) {
+  return handlerPath.split('.').reduce((acc, key) => {
+    if (acc == null) {
+      return undefined;
+    }
+    return acc[key];
+  }, userApp);
+}
+
+// Resolve the handler module even if Node's default lookup no longer includes it.
+function resolveModuleFile(modulePath) {
+  try {
+    const resolved = require.resolve(modulePath);
+    logDebug(`Resolved handler module via require.resolve: ${resolved}`);
+    return resolved;
+  } catch (err) {
+    if (err?.code !== 'MODULE_NOT_FOUND') {
+      throw err;
+    }
+  }
+
+  const extensions = ['', '.js', '.cjs', '.mjs'];
+  for (const ext of extensions) {
+    const candidate = modulePath + ext;
+    if (fs.existsSync(candidate)) {
+      logDebug(`Resolved handler module via fs lookup: ${candidate}`);
+      return candidate;
+    }
+  }
+
+  logDebug(`Falling back to unresolved handler module path: ${modulePath}`);
+  return modulePath;
+}
+
+// Require the user module, retrying via dynamic import when the file is ESM-only.
+async function loadUserModule(resolvedPath) {
+  try {
+    logDebug(`Attempting to require handler module: ${resolvedPath}`);
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(resolvedPath);
+  } catch (err) {
+    if (err?.code === 'ERR_REQUIRE_ESM') {
+      const url = pathToFileURL(resolvedPath).href;
+      logDebug(
+        `Handler module is ESM. Retrying with dynamic import: ${url} (${err.message})`
+      );
+      return import(url);
+    }
+    logDebug(
+      `Failed to require handler module (${resolvedPath}): ${err?.message}`
+    );
+    throw err;
+  }
+}
+
+// Resolve and return the original Lambda handler function.
+async function load(appRoot = process.env.LAMBDA_TASK_ROOT, handlerString) {
+  const finalHandler = handlerString ?? process.env.CX_ORIGINAL_HANDLER;
+  if (!appRoot) {
+    throw new Error('LAMBDA_TASK_ROOT is not defined');
+  }
+  if (!finalHandler) {
+    throw new Error('CX_ORIGINAL_HANDLER is not defined');
+  }
+
+  const [modulePath, handlerPath] = splitHandlerString(finalHandler);
+  const absoluteModulePath = path.resolve(appRoot, modulePath);
+  const resolvedModulePath = resolveModuleFile(absoluteModulePath);
+  const userApp = await loadUserModule(resolvedModulePath);
+  const handler = resolveHandler(userApp, handlerPath);
+
+  if (typeof handler !== 'function') {
+    throw new Error(
+      `Handler "${finalHandler}" resolved to "${handler}" instead of a function`
+    );
+  }
+
+  logDebug(`Successfully loaded handler ${finalHandler}`);
+  return handler;
+}
+
+module.exports = { load };

nodejs/packages/cx-wrapper/package-lock.json

@@ -36,7 +36,7 @@
     "@opentelemetry/exporter-metrics-otlp-proto": "0.57.2",
     "@opentelemetry/exporter-trace-otlp-proto": "0.57.2",
     "@opentelemetry/instrumentation": "file:../../../opentelemetry-js/experimental/packages/opentelemetry-instrumentation/opentelemetry-instrumentation-0.207.0.tgz",
-    "@opentelemetry/instrumentation-aws-lambda": "file:../../../opentelemetry-js-contrib-cx/packages/instrumentation-aws-lambda/opentelemetry-instrumentation-aws-lambda-0.60.1.tgz",
+    "@opentelemetry/instrumentation-aws-lambda": "file:../../../opentelemetry-js-contrib-cx/packages/instrumentation-aws-lambda/opentelemetry-instrumentation-aws-lambda-0.61.0.tgz",
     "@opentelemetry/instrumentation-aws-sdk": "file:../../../opentelemetry-js-contrib-cx/packages/instrumentation-aws-sdk/opentelemetry-instrumentation-aws-sdk-0.64.0.tgz",
     "@opentelemetry/instrumentation-dns": "0.43.1",
     "@opentelemetry/instrumentation-express": "0.47.1",