Improve error handling, comprehensive documentation, and API improvements by bnusunny · Pull Request #628 · aws/aws-lambda-web-adapter

bnusunny · 2026-02-05T05:39:44Z

Summary

This PR significantly improves the Lambda Web Adapter's production readiness through better error handling, comprehensive API documentation, and several developer experience improvements.

Changes

Error Handling Improvements

Replace all unwrap() calls with proper error handling using ? operator and expect() with descriptive messages
Extract extension registration logic into register_extension_internal() with proper error propagation
Use std::process::exit(1) instead of panic! for cleaner termination on registration failures
Adapter::new() now returns Result<Adapter, Error> for proper error handling at construction time
Add validation for TCP protocol requirements (host/port) at construction time

Thread Safety Fix

Fix unsafe env::set_var usage in multi-threaded context by introducing Adapter::apply_runtime_proxy_config()
Refactor main() to manually build tokio runtime, ensuring env vars are set before any threads spawn
Prepares codebase for Rust 2024 edition where env::set_var will be marked unsafe

New Features

Add AWS_LWA_READINESS_CHECK_HEALTHY_STATUS env var for flexible health check status code configuration
- Supports ranges (200-399) and lists (200,201,204,301-399)
- Default: 100-499 (maintains backward compatibility)
Add Lambda Advanced Logging Controls support via lambda_http::tracing::init_default_subscriber()
- Supports AWS_LAMBDA_LOG_LEVEL and AWS_LAMBDA_LOG_FORMAT environment variables
- Enables JSON log format for CloudWatch Logs Insights integration

Deprecations

Deprecate non-namespaced environment variables with warnings (will be removed in v2.0):
- PORT → AWS_LWA_PORT
- HOST → AWS_LWA_HOST
- READINESS_CHECK_PORT → AWS_LWA_READINESS_CHECK_PORT
- READINESS_CHECK_PATH → AWS_LWA_READINESS_CHECK_PATH
- READINESS_CHECK_PROTOCOL → AWS_LWA_READINESS_CHECK_PROTOCOL
- REMOVE_BASE_PATH → AWS_LWA_REMOVE_BASE_PATH
- ASYNC_INIT → AWS_LWA_ASYNC_INIT
Deprecate AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS in favor of AWS_LWA_READINESS_CHECK_HEALTHY_STATUS

Documentation

Add comprehensive rustdoc documentation for all public types and methods
Module-level documentation with overview, quick start example, and configuration table
Document Protocol, LambdaInvokeMode, AdapterOptions, and Adapter structs
Add new "Logging" section to README explaining Lambda Advanced Logging Controls

Testing

Update all integration tests and benchmarks for Adapter::new() returning Result
Fix clippy warnings (derive macro for Default, unnecessary to_owned())
All 25 tests pass

- Extract extension registration logic into register_extension_internal() - Replace all unwrap() calls with proper error handling using ? operator - Use std::process::exit(1) instead of panic! for cleaner termination - Add proper error logging before exit - Handle missing Lambda-Extension-Identifier header gracefully This provides better error messages and cleaner process termination while still ensuring the extension exits immediately on registration failure.

- Replace unwrap() with expect() for URL parsing in Adapter::new() - Add validation for TCP protocol requirements at construction time - Use expect() with 'BUG:' prefix for invariants that should never fail - Prevents wasteful retry loops on configuration errors - Ensures fast failure with clear error messages on misconfiguration This ensures: - Configuration errors fail immediately at startup - No wasted CPU cycles retrying unrecoverable errors - Clear distinction between config errors and runtime errors - Runtime retries only happen for transient network conditions

- Move env::set_var call to before tokio runtime starts - Add Adapter::apply_runtime_proxy_config() to be called from main() - Refactor main() to manually build tokio runtime for proper ordering - Document safety requirements and future Rust compatibility This prevents race conditions and prepares for Rust 2024 edition where env::set_var will be marked as unsafe. The environment variable is now set before any threads are spawned, making it safe. Fixes critical blocker for GA release.

- Add .expect() calls to all Adapter::new() invocations in tests - Apply cargo fmt formatting fixes All 25 tests pass.

- Use derive macro for Default impl on LambdaEventType enum - Replace unnecessary to_owned() with reference in mock body

- Add .expect() calls to Adapter::new() in benchmark functions

Instead of removing support for non-namespaced env vars, emit deprecation warnings when they are used. This provides a migration path for users. Deprecated variables (will be removed in 2.0): - PORT -> use AWS_LWA_PORT - HOST -> use AWS_LWA_HOST - READINESS_CHECK_PORT -> use AWS_LWA_READINESS_CHECK_PORT - READINESS_CHECK_PATH -> use AWS_LWA_READINESS_CHECK_PATH - READINESS_CHECK_PROTOCOL -> use AWS_LWA_READINESS_CHECK_PROTOCOL - REMOVE_BASE_PATH -> use AWS_LWA_REMOVE_BASE_PATH - ASYNC_INIT -> use AWS_LWA_ASYNC_INIT When deprecated vars are used, a warning is logged: 'Environment variable X is deprecated and will be removed in version 2.0. Please use Y instead.' This is less disruptive than an immediate breaking change and gives users time to update their configurations.

…Y_STATUS New environment variable AWS_LWA_READINESS_CHECK_HEALTHY_STATUS allows users to specify which HTTP status codes are considered healthy for readiness checks. Format: Supports ranges and lists (e.g., '200-399', '200,201,204,301-399') Default: '100-499' (same behavior as previous min_unhealthy=500) Deprecated: AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - Still works but emits a deprecation warning - Will be removed in version 2.0 This provides more flexibility for users who need fine-grained control over which status codes indicate a healthy application.

- Add module-level documentation with overview, quick start, and configuration table - Document Protocol enum with usage examples - Document LambdaInvokeMode enum with response streaming guidance - Document AdapterOptions struct with all fields and environment variable mappings - Document Adapter struct with lifecycle explanation - Add detailed documentation for all public methods - Document internal helper functions - All documentation builds successfully with cargo doc

- Use lambda_http::tracing::init_default_subscriber() for logging setup - Enable 'tracing' feature in lambda_http dependency - Supports AWS_LAMBDA_LOG_LEVEL environment variable (takes precedence) - Falls back to RUST_LOG if AWS_LAMBDA_LOG_LEVEL is not set - Supports JSON log format via AWS_LAMBDA_LOG_FORMAT=JSON - Removes manual tracing-subscriber setup in favor of Lambda-native solution

- Add new Logging section explaining Lambda's Advanced Logging Controls support - Clarify that AWS_LAMBDA_LOG_LEVEL and AWS_LAMBDA_LOG_FORMAT are reserved env vars set by Lambda - Document RUST_LOG as user-configurable fallback - Explain JSON log format for CloudWatch Logs Insights integration

Replace non-existent --filter-by-regression flag with awk-based parsing of critcmp CSV output to detect regressions > 10%.

github-actions · 2026-02-06T02:16:01Z

📊 Benchmark Comparison

Benchmark Details

Baseline: main branch
Comparison: This PR
Threshold: 10% regression triggers warning

- TCP readiness checks (success and failure) - Protocol and LambdaInvokeMode From<&str> edge cases - Adapter::new() error path (invalid host) - apply_runtime_proxy_config env var behavior - parse_status_codes additional edge cases - Base path stripping (match, no-match, strip-to-root) - Deprecated env var fallback and namespaced override - Authorization source with missing header - Error status codes non-matching passthrough - Async init with readiness at init time - TCP readiness check end-to-end with request forwarding

Clients can now use lambda_web_adapter::tracing instead of importing lambda_http directly for tracing initialization.

AWS_LWA_PORT now falls back to PORT env var without emitting a deprecation warning, since PORT is a widely used convention across cloud platforms and frameworks. The fallback chain is: AWS_LWA_PORT -> PORT -> 8080 Readiness check port behavior is unchanged.

seshubaws · 2026-02-06T22:15:11Z

I see only 5 tests ran, should we run some of the skipped ones too?

bnusunny · 2026-02-06T22:54:42Z

I see only 5 tests ran, should we run some of the skipped ones too?

The first check runs linting check, unit tests, and integration tests. The later steps are for releasing the changes.

bnusunny added 12 commits February 5, 2026 02:02

Update integration tests for Adapter::new() returning Result

565783e

- Add .expect() calls to all Adapter::new() invocations in tests - Apply cargo fmt formatting fixes All 25 tests pass.

Fix clippy warnings in tests

66ad580

- Use derive macro for Default impl on LambdaEventType enum - Replace unnecessary to_owned() with reference in mock body

Fix benchmark code for Adapter::new() returning Result

0df9ab6

- Add .expect() calls to Adapter::new() in benchmark functions

Fix critcmp invalid argument in benchmark workflow

5752360

Replace non-existent --filter-by-regression flag with awk-based parsing of critcmp CSV output to detect regressions > 10%.

aws deleted a comment from github-actions Bot Feb 5, 2026

roger-zhangg reviewed Feb 6, 2026

View reviewed changes

Comment thread README.md

roger-zhangg reviewed Feb 6, 2026

View reviewed changes

Comment thread src/lib.rs Outdated

refactor: extract environment variable names into constants

72fb0c6

bnusunny added 5 commits February 6, 2026 02:19

style: fix formatting in AdapterOptions default

a70613d

Re-export lambda_http::tracing from lib.rs

b6409e6

Clients can now use lambda_web_adapter::tracing instead of importing lambda_http directly for tracing initialization.

Apply rustfmt formatting fixes

34d90b7

bnusunny force-pushed the improve_error_handling branch from 8cbf8c0 to 6202a1b Compare February 6, 2026 17:55

seshubaws approved these changes Feb 6, 2026

View reviewed changes

roger-zhangg approved these changes Feb 6, 2026

View reviewed changes

bnusunny merged commit 22530f5 into main Feb 6, 2026
26 checks passed

bnusunny deleted the improve_error_handling branch February 6, 2026 23:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve error handling, comprehensive documentation, and API improvements#628

Improve error handling, comprehensive documentation, and API improvements#628
bnusunny merged 18 commits into
mainfrom
improve_error_handling

bnusunny commented Feb 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 6, 2026 •

edited

Loading

Uh oh!

seshubaws commented Feb 6, 2026

Uh oh!

bnusunny commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bnusunny commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Error Handling Improvements

Thread Safety Fix

New Features

Deprecations

Documentation

Testing

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Benchmark Comparison

Uh oh!

seshubaws commented Feb 6, 2026

Uh oh!

bnusunny commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bnusunny commented Feb 5, 2026 •

edited

Loading

github-actions Bot commented Feb 6, 2026 •

edited

Loading