feat(metadata): add Lambda Metadata utility for retrieving execution environment metadata

[hjgraca]

Issue #1158

Description of changes:

• Add new AWS.Lambda.Powertools.Metadata NuGet package with LambdaMetadataClient for accessing Lambda Metadata Service
• Implement LambdaMetadata class to expose AvailabilityZoneId property from LMDS endpoint
• Add LambdaMetadataHttpClient for HTTP communication with automatic token and endpoint handling
• Implement automatic caching of metadata for sandbox lifetime with thread-safe concurrent access
• Add support for both synchronous (Get/Refresh) and asynchronous (GetAsync/RefreshAsync) operations
• Add LambdaMetadataException for error handling with HTTP status code information
• Implement LambdaMetadataSerializerContext for native AOT compatibility using source-generated JSON serialization
• Add documentation with usage examples, error handling, and environment variable reference

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Copilot]

Pull request overview

Adds a new Lambda Metadata utility/package to the Powertools for AWS Lambda (.NET) libraries, exposing execution-environment metadata (starting with Availability Zone ID) fetched from the Lambda Metadata Endpoint (LMDS), along with tests and docs integration.

Changes:

• Introduces AWS.Lambda.Powertools.Metadata library (public LambdaMetadata API, internal fetcher + JSON source-gen, custom exception type).
• Adds a new AWS.Lambda.Powertools.Metadata.Tests test project covering caching, refresh, errors, and concurrency.
• Publishes documentation for the new utility and wires it into MkDocs navigation, plus updates the solution to include the new projects.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
mkdocs.yml	Adds Metadata utility page to nav and plugin config.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/AWS.Lambda.Powertools.Metadata.Tests.csproj	New test project for Metadata utility.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/LambdaMetadataTests.cs	Unit tests for value retrieval, caching, refresh, and error propagation.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/LambdaMetadataConcurrencyTests.cs	Concurrency test validating thread-safe caching behavior.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/LambdaMetadataCollection.cs	xUnit collection to prevent cross-test static interference.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/Internal/MetadataFetcherTests.cs	Tests for missing env-var error paths in MetadataFetcher.
libraries/tests/AWS.Lambda.Powertools.Metadata.Tests/Exceptions/LambdaMetadataExceptionTests.cs	Tests for LambdaMetadataException constructors/status code behavior.
libraries/src/AWS.Lambda.Powertools.Metadata/AWS.Lambda.Powertools.Metadata.csproj	New package project definition.
libraries/src/AWS.Lambda.Powertools.Metadata/LambdaMetadata.cs	Public API surface + cached metadata access + internal MetadataValues model.
libraries/src/AWS.Lambda.Powertools.Metadata/Internal/IMetadataFetcher.cs	Internal abstraction for metadata retrieval.
libraries/src/AWS.Lambda.Powertools.Metadata/Internal/MetadataFetcher.cs	HTTP fetcher that reads LMDS endpoint/token from env vars and deserializes response.
libraries/src/AWS.Lambda.Powertools.Metadata/Internal/LambdaMetadataSerializerContext.cs	Source-generated JSON serializer context for AOT trimming compatibility.
libraries/src/AWS.Lambda.Powertools.Metadata/Exceptions/LambdaMetadataException.cs	Custom exception type for LMDS failures, including status code.
libraries/src/AWS.Lambda.Powertools.Metadata/InternalsVisibleTo.cs	Exposes internals to the new test project and dynamic proxy assembly.
libraries/src/AWS.Lambda.Powertools.Metadata/README.md	Package-level README with install/usage/error-handling examples.
libraries/AWS.Lambda.Powertools.sln	Registers new Metadata library + tests in the solution.
docs/utilities/metadata.md	New MkDocs page documenting the Metadata utility usage and scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.43%. Comparing base (989220b) to head (8555a72).
⚠️ Report is 30 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1157      +/-   ##
===========================================
+ Coverage    79.23%   79.43%   +0.19%     
===========================================
  Files          299      302       +3     
  Lines        12441    12636     +195     
  Branches      1490     1505      +15     
===========================================
+ Hits          9858    10037     +179     
- Misses        2128     2141      +13     
- Partials       455      458       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

@aws-powertools/powertools-lambda-net No related issues found. Please ensure 'pending-release' label is applied before releasing.

[github-actions]

@aws-powertools/powertools-lambda-net No related issues found. Please ensure 'pending-release' label is applied before releasing.