feat(commons): add Lambda Metadata Service support (#5106)

Author: svozza

docs/features/metadata.md

@@ -0,0 +1,51 @@
+---
+title: Metadata
+description: Utility to fetch data from the AWS Lambda Metadata endpoint
+status: new
+---
+
+<!-- markdownlint-disable MD043 -->
+The Metadata utility allows you to fetch data from the AWS Lambda Metadata Endpoint (LMDS). This can be useful for retrieving information about the Lambda function, such as the Availability Zone ID.
+
+## Getting started
+
+### Installation
+
+Add the library to your project:
+
+```shell
+npm install @aws-lambda-powertools/commons
+```
+
+### Usage
+
+You can fetch data from the LMDS using the `getMetadata` function. For example, to retrieve the Availability Zone ID:
+
+???+ tip
+    Metadata is cached for the duration of the Lambda execution, so subsequent calls to `getMetadata` will return the cached data.
+
+=== "index.ts"
+
+  ```ts hl_lines="1 5 8"
+  --8<-- "examples/snippets/commons/metadata.ts"
+  ```
+
+### Available metadata
+
+| Property             | Type     | Description                                             |
+| -------------------- | -------- | ------------------------------------------------------- |
+| `AvailabilityZoneId` | `string` | The AZ where the function is running (e.g., `use1-az1`) |
+
+## Testing your code
+
+The metadata endpoint is not available during local development or testing. To ease testing, the `getMetadata` function automatically detects when it's running in a non-Lambda environment and returns an empty object. This allows you to write tests without needing to mock the LMDS responses.
+
+If instead you want to mock specific metadata values for testing purposes, you can do so by setting environment variables that correspond to the metadata endpoint and authentication token, as well as mocking the `fetch` function to return the desired metadata. Here's an example of how to do this:
+
+=== "index.test.ts"
+
+  ```ts hl_lines="11-14 24-26 35"
+  --8<-- "examples/snippets/commons/testingMetadata.ts"
+  ```
+
+We also expose a `clearMetadataCache` function that can be used to clear the cached metadata, allowing you to test different metadata values within the same execution context.

examples/snippets/commons/metadata.ts

@@ -0,0 +1,10 @@
+import { getMetadata } from '@aws-lambda-powertools/commons/utils/metadata';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger({ serviceName: 'serverlessAirline' });
+const metadata = await getMetadata();
+
+export const handler = async () => {
+  const { AvailabilityZoneId: azId } = metadata;
+  logger.appendKeys({ azId });
+};

examples/snippets/commons/testingMetadata.ts

@@ -0,0 +1,52 @@
+import {
+  clearMetadataCache,
+  getMetadata,
+} from '@aws-lambda-powertools/commons/utils/metadata';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('function: getMetadata', async () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    clearMetadataCache();
+    fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+  });
+
+  it('fetches metadata and caches the response', async () => {
+    // Prepare
+    vi.stubEnv('AWS_LAMBDA_INITIALIZATION_TYPE', 'on-demand');
+    vi.stubEnv('AWS_LAMBDA_METADATA_API', '127.0.0.1:1234');
+    vi.stubEnv('AWS_LAMBDA_METADATA_TOKEN', 'test-token');
+
+    const payload = { runtime: 'nodejs20.x' };
+    fetchMock.mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue(payload),
+    });
+
+    // Act
+    const resultA = await getMetadata();
+    const resultB = await getMetadata();
+
+    // Assess
+    expect(resultA).toEqual(payload);
+    expect(resultB).toBe(resultA);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://127.0.0.1:1234/2026-01-15/metadata/execution-environment',
+      expect.objectContaining({
+        headers: {
+          Authorization: 'Bearer test-token',
+        },
+        signal: expect.any(AbortSignal),
+      })
+    );
+  });
+});

mkdocs.yml

@@ -58,6 +58,7 @@ nav:
           - features/parser.md
           - features/validation.md
           - features/kafka.md
+          - features/metadata.md
       - Environment variables: environment-variables.md
       - Upgrade guide: upgrade.md
       - Community Content: we_made_this.md
@@ -193,6 +194,7 @@ plugins:
           - features/parser.md
           - features/validation.md
           - features/kafka.md
+          - features/metadata.md
         Environment variables: 
           - environment-variables.md
         Upgrade guide: 

packages/commons/package.json

@@ -6,6 +6,7 @@
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com"
   },
+  "license": "MIT-0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,7 +26,31 @@
     "prepack": "node ../../.github/scripts/release_patch_package_json.js ."
   },
   "homepage": "https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/packages/commons#readme",
-  "license": "MIT-0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aws-powertools/powertools-lambda-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues"
+  },
+  "keywords": [
+    "aws",
+    "lambda",
+    "powertools",
+    "serverless",
+    "nodejs"
+  ],
+  "dependencies": {
+    "@aws/lambda-invoke-store": "0.2.4"
+  },
+  "devDependencies": {
+    "@aws-lambda-powertools/testing-utils": "file:../testing"
+  },
+  "main": "./lib/cjs/index.js",
+  "types": "./lib/cjs/index.d.ts",
+  "files": [
+    "lib"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -58,6 +83,10 @@
       "import": "./lib/esm/envUtils.js",
       "require": "./lib/cjs/envUtils.js"
     },
+    "./utils/metadata": {
+      "import": "./lib/esm/metadata.js",
+      "require": "./lib/cjs/metadata.js"
+    },
     "./types": {
       "import": "./lib/esm/types/index.js",
       "require": "./lib/cjs/types/index.js"
@@ -89,6 +118,10 @@
         "lib/cjs/envUtils.d.ts",
         "lib/esm/envUtils.d.ts"
       ],
+      "utils/metadata": [
+        "lib/cjs/metadata.d.ts",
+        "lib/esm/metadata.d.ts"
+      ],
       "types": [
         "lib/cjs/types/index.d.ts",
         "lib/esm/types/index.d.ts"
@@ -98,30 +131,5 @@
         "lib/esm/deepMerge.d.ts"
       ]
     }
-  },
-  "types": "./lib/cjs/index.d.ts",
-  "main": "./lib/cjs/index.js",
-  "files": [
-    "lib"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aws-powertools/powertools-lambda-typescript.git"
-  },
-  "bugs": {
-    "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues"
-  },
-  "keywords": [
-    "aws",
-    "lambda",
-    "powertools",
-    "serverless",
-    "nodejs"
-  ],
-  "dependencies": {
-    "@aws/lambda-invoke-store": "0.2.4"
-  },
-  "devDependencies": {
-    "@aws-lambda-powertools/testing-utils": "file:../testing"
   }
 }

packages/commons/src/metadata.ts

@@ -0,0 +1,56 @@
+import { getStringFromEnv, isDevMode } from './envUtils.js';
+
+const metadataCache: Record<string, unknown> = {};
+
+const clearMetadataCache = () => {
+  for (const key of Object.keys(metadataCache)) {
+    delete metadataCache[key];
+  }
+};
+
+/**
+ * Fetches metadata from the AWS Lambda Metadata endpoint.
+ *
+ * When not running in a Lambda environment (e.g., during local development), it returns an empty object.
+ */
+type GetMetadataOptions = {
+  timeout?: number;
+};
+
+const getMetadata = async (options?: GetMetadataOptions) => {
+  const initType = getStringFromEnv({
+    key: 'AWS_LAMBDA_INITIALIZATION_TYPE',
+    defaultValue: 'unknown',
+  });
+
+  if (isDevMode() || initType === 'unknown') {
+    return {};
+  }
+
+  if (Object.keys(metadataCache).length > 0) {
+    return metadataCache;
+  }
+
+  const metadataBaseUrl = getStringFromEnv({ key: 'AWS_LAMBDA_METADATA_API' });
+  const metadataToken = getStringFromEnv({ key: 'AWS_LAMBDA_METADATA_TOKEN' });
+
+  const res = await fetch(
+    `http://${metadataBaseUrl}/2026-01-15/metadata/execution-environment`,
+    {
+      headers: {
+        Authorization: `Bearer ${metadataToken}`,
+      },
+      signal: AbortSignal.timeout(options?.timeout ?? 1000),
+    }
+  );
+  if (!res.ok) {
+    throw new Error(
+      `Failed to fetch execution environment metadata: ${res.status} ${res.statusText}`
+    );
+  }
+  const data = await res.json();
+  Object.assign(metadataCache, data);
+  return metadataCache;
+};
+
+export { clearMetadataCache, getMetadata, type GetMetadataOptions };