If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/aws/aws-lambda-web-adapter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 18 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live aws/aws-lambda-web-adapter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/aws/aws-lambda-web-adapter.

What it runs against: a local clone of aws/aws-lambda-web-adapter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in aws/aws-lambda-web-adapter | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 43 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aws/aws-lambda-web-adapter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aws/aws-lambda-web-adapter.git
#   cd aws-lambda-web-adapter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of aws/aws-lambda-web-adapter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "aws/aws-lambda-web-adapter(\\.git)?\\b" \\
  && ok "origin remote is aws/aws-lambda-web-adapter" \\
  || miss "origin remote is not aws/aws-lambda-web-adapter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "docs/design.md" \\
  && ok "docs/design.md" \\
  || miss "missing critical file: docs/design.md"
test -f "docs/guide/src/SUMMARY.md" \\
  && ok "docs/guide/src/SUMMARY.md" \\
  || miss "missing critical file: docs/guide/src/SUMMARY.md"
test -f ".github/workflows/pr.yaml" \\
  && ok ".github/workflows/pr.yaml" \\
  || miss "missing critical file: .github/workflows/pr.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 43 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~13d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/aws/aws-lambda-web-adapter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

AWS Lambda Web Adapter is a Rust-based reverse proxy that enables running stateless web applications (Express, Flask, Spring Boot, Laravel, etc.) on AWS Lambda by translating Lambda events (API Gateway, ALB, Function URLs) into HTTP requests and forwarding responses back. It bridges the gap between traditional HTTP frameworks and Lambda's event-driven model, supporting response streaming, compression, graceful shutdown, and multi-tenancy via a single ~5MB binary packaged as a Lambda layer or Docker extension. Single binary Rust project (src/main.rs is the entry point for lambda-adapter binary). Monolithic structure: core adapter logic lives in src/, benchmarks in benches/ (e2e_body_forwarding.rs tests actual forwarding), docs in docs/guide/ (mdBook-based), GitHub workflows in .github/workflows/ for CI/CD, examples likely external. Minimal test/example visibility in file list suggests heavy reliance on integration tests via benches and CI.

AWS Lambda developers and DevOps engineers who want to deploy existing web applications on Lambda without rewriting them to use Lambda-specific SDKs; they benefit from zero code changes, container parity (same Docker image runs on Lambda, EC2, Fargate, local), and support for any HTTP 1.0/1.1 framework.

Production-ready and actively maintained. Version 1.0.0 indicates stable API; extensive CI/CD workflows (pr.yaml, release.yaml, benchmark.yaml, security_audit.yaml) suggest rigorous testing and regular releases. Multi-architecture support (x86_64 and arm64), published Docker images, and documented examples indicate ecosystem integration and real-world usage.

Low risk. Well-scoped dependency tree (hyper, tokio, tower-http, lambda_http are all stable/widely-used AWS/Rust ecosystem projects); no single-maintainer risk visible (CODEOWNERS file suggests multiple maintainers); performance benchmarks and e2e tests present (benches/e2e_body_forwarding.rs). Main caveat: tight coupling to AWS Lambda event shapes (lambda_http features: apigw_http, apigw_rest, alb, pass_through) means breaking Lambda API changes could affect it.

Active development: release.yaml and changelog.yaml suggest regular versioning, benchmark-comment.yaml and benchmark.yaml indicate ongoing performance monitoring. Workflows for security_audit.yaml (dependency scanning), commitlint.yaml (enforced conventional commits), and cn-prod.json/gamma.json (AWS China region support) suggest mature release discipline and geographic expansion efforts.

git clone https://github.com/aws/aws-lambda-web-adapter.git
cd aws-lambda-web-adapter
cargo build --release  # Makefile likely has convenience targets too

Check Makefile for common tasks; development guide at docs/guide/src/development/building.md provides detailed setup.

Daily commands:

make build          # Compile release binary
make test           # Run test suite
make bench          # Run benchmark suite (e2e_body_forwarding)

Or directly: cargo build --release produces binary at target/release/lambda-adapter. For local debugging, see docs/guide/src/development/local-debugging.md.

• Cargo.toml — Root workspace manifest defining all Rust dependencies, package metadata, and build configuration for the lambda web adapter binary
• src/main.rs — Entry point of the adapter binary that handles Lambda event marshalling, HTTP forwarding, and response encoding—core runtime logic
• docs/design.md — Architecture and design decisions document explaining how the adapter bridges Lambda events to HTTP and handles various event sources
• docs/guide/src/SUMMARY.md — Complete user guide outline covering all features, configuration, examples, and troubleshooting paths
• .github/workflows/pr.yaml — Pull request CI pipeline defining test matrix, build targets, and quality gates for all contributions
• examples — Working examples across multiple languages (Node.js, Python, .NET, Java, PHP, Go) demonstrating real-world integration patterns
• Makefile — Build automation for local development, testing, and artifact generation across all supported Lambda runtimes

Add Support for a New Lambda Event Source

1. Create new event type struct in src/events/your_source.rs with deserialization logic matching AWS event schema (src/events/your_source.rs)
2. Add match arm in main event handler (src/main.rs) to pattern-match your event type (src/main.rs)
3. Extract HTTP method, path, headers, and body from the event type (src/main.rs)
4. Add integration test in tests/integration_tests.rs with sample event JSON (tests/integration_tests.rs)
5. Document the new source in docs/guide/src/features/ with configuration examples (docs/guide/src/features/your_event_source.md)

Add a New Configuration Option

1. Define environment variable name and parsing logic in src/config.rs (src/config.rs)
2. Read the variable in main() and pass it through the handler pipeline (src/main.rs)
3. Document the option with allowed values and default behavior (docs/guide/src/configuration/environment-variables.md)
4. Add test case covering both set and unset states (tests/config_tests.rs)

Add a Working Example in a New Language

1. Create examples/myframework-zip directory structure matching existing examples (examples/myframework-zip/)
2. Create minimal HTTP server using your framework (same as examples/aspnet-mvc-zip/src/Program.cs pattern) (examples/myframework-zip/src/main)
3. Add build instructions and Dockerfile if using Docker (examples/myframework-zip/README.md)
4. Register example in .github/workflows/examples.yaml to test on PR (.github/workflows/examples.yaml)

Enhance Response Encoding or Compression

1. Add compression algorithm or encoding logic to src/encoding.rs (src/encoding.rs)
2. Update Content-Encoding header selection based on Accept-Encoding request header (src/encoding.rs)
3. Add benchmark in benches/ to measure compression overhead (benches/compression_bench.rs)
4. Document feature and performance impact in docs/guide/src/configuration/response-compression.md (docs/guide/src/configuration/response-compression.md)

• Rust — Compiled binary, minimal overhead, fast startup time, and safe concurrency—critical for Lambda's cold-start and resource constraints
• Hyper HTTP client/server — Async-first, high-performance HTTP library with excellent Lambda compatibility and minimal dependencies
• Lambda Runtime API — Custom runtime foundation allows adapter to intercept and transform Lambda events before passing to application
• Docker OCI images — Containerization enables single artifact to run on Lambda, EC2, Fargate, and local—eliminating platform-specific packaging

• Single-threaded event loop with local HTTP server per Lambda instance

  • Why: Simplifies state management and avoids concurrent request complexity; matches Lambda's single-invocation-at-a-time execution model
  • Consequence: Lambda Managed Instances required for true multi-concurrent request handling; cannot utilize multiple CPU cores in standard Lambda

• Adapter runs as thin proxy between Lambda Runtime API and application HTTP server

  • Why: Maximizes framework compatibility—works with any HTTP 1.0/1.1 server, zero code changes required
  • Consequence: Cannot optimize application-specific protocols; adds latency overhead (~5–10ms per request) vs direct Lambda handlers

• Environment variable configuration rather than config files

  • Why: Fits Lambda's stateless, immutable container paradigm; avoids file system I/O during startup
  • Consequence: Limited to flat key-value configuration; complex scenarios require custom application logic

• Response streaming via chunked transfer encoding

  • Why: Supports long-running responses and real-time data; reduces memory footprint vs buffering entire response
  • Consequence: Requires API Gateway HTTP API (not REST API); Lambda response payload limit still applies to total size

• Does not handle Lambda authentication/authorization—relies on API Gateway, ALB, or Function URL security
• Does not support HTTP/2 or HTTP/3—limited to HTTP/1.0/1.1 (Lambda event source limitation)
• Does not provide built-in database or cache—applications must implement their own persistence
• Does not offer language-specific optimizations—treats all frameworks identically as HTTP servers
• Does not manage Lambda function versioning or traffic shifting—infrastructure concern outside adapter scope

No obvious service dependencies in .github/workflows, but benches/common/mod.rs likely mocks downstream servers. Multi-arch concern: .cargo/config.toml may require specific compiler targets; release profile (strip=true, lto=true, panic=abort) is aggressive for size — failures require careful binary inspection. Environment variables: AWS_LWA_PORT, AWS_LAMBDA_EXEC_WRAPPER mentioned in README; environment-variables.md config doc is critical for operator gotchas. Event shape assumptions: lambda_http features (apigw_rest vs apigw_http vs alb) are mutually exclusive concerns; wrong feature flag breaks a deployment model. Graceful shutdown: tokio signal handling in src/main.rs likely has OS-specific behavior (Unix SIGTERM vs Windows); CONTRIBUTING.md should clarify test environment expectations.

• Event-to-HTTP translation (Adapter Pattern) — Core responsibility: Lambda events (JSON structures from API Gateway/ALB) must be parsed and translated to HTTP requests; understanding this bidirectional mapping is essential for debugging integration failures
• Reverse proxy / HTTP forwarding — This project IS a reverse proxy; it intercepts Lambda events and forwards them as HTTP to a background web server process; knowing proxy semantics (header forwarding, chunked encoding, keep-alive) explains both design and limitations
• Async/await with Tokio runtime — Lambda's concurrent request model and hyper's async HTTP client both rely on Tokio; code changes require understanding Rust async semantics, Future composition, and tokio task spawning
• Tower middleware ecosystem — Compression (gzip/brotli), retries, and request/response shaping all plug in via tower-http; adding features means composing layers in the right order
• Graceful shutdown and signal handling — Lambda freezes containers after request processing; adapter must drain in-flight requests and shut down cleanly; tokio signal handling and timeout logic prevent data loss
• Lambda extensions (vs layers vs custom runtimes) — Web-adapter can deploy as a Lambda extension (/opt/extensions/), layer (/opt/bootstrap), or custom runtime; each deployment model has different constraints and startup overhead implications
• HTTP chunked transfer encoding and streaming responses — Response streaming (docs/guide/src/configuration/response-streaming.md) leverages HTTP chunked encoding; adapter must avoid buffering and forward chunks immediately; critical for real-time and large-payload responses

• awslabs/aws-lambda-python-runtime — Official AWS Lambda Python Runtime; complementary — shows how to build Lambda-aware runtimes vs. this adapter's approach of making Lambda transparent to existing web frameworks
• aws/aws-lambda-go-runtime — Official AWS Lambda Go Runtime; same-ecosystem contrast showing language-specific vs. language-agnostic approaches to Lambda adaptation
• aws-samples/aws-lambda-web-adapter-examples — Companion repository of runnable examples (Express, Flask, Spring Boot, etc.) using aws-lambda-web-adapter; critical for understanding real deployment patterns
• serverless-stack/sst — Infrastructure-as-Code framework for Lambda/serverless apps on AWS; commonly paired with this adapter for deployment orchestration
• zappa/Zappa — Python WSGI packaging for Lambda (pre-dates web-adapter); legacy inspiration showing the problem this project solves in a more general, language-agnostic way

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for response compression features

The codebase has tower-http compression support (gzip, brotli) configured in Cargo.toml and docs/guide/src/configuration/response-compression.md exists, but there are no visible integration tests validating compression behavior. The e2e_body_forwarding.rs benchmark exists but doesn't cover compression. This is critical for ensuring responses are properly compressed across different content types and configurations.

• [ ] Create tests/compression_integration.rs with test cases for gzip and brotli compression
• [ ] Add test cases for Content-Type negotiation (which types should be compressed)
• [ ] Add test case verifying compressed responses include correct Content-Encoding headers
• [ ] Add test case for disabling compression via environment variables
• [ ] Run tests locally with: cargo test --test compression_integration

Add GitHub Actions workflow for MSRV (Minimum Supported Rust Version) validation

The Cargo.toml specifies edition = '2021' but there's no CI workflow validating against a minimum Rust version. This is important for users relying on older toolchains. Looking at .github/workflows/, there are pr.yaml, release.yaml, and security_audit.yaml, but no MSRV validation. This prevents breaking changes that silently require newer Rust versions.

• [ ] Create .github/workflows/msrv.yaml workflow file
• [ ] Configure job to test against Rust 1.70 (reasonable MSRV for 2021 edition dependencies)
• [ ] Add step: cargo +1.70 test --all to validate compilation and tests pass
• [ ] Add step: cargo +1.70 check --all-targets for comprehensive check
• [ ] Document the MSRV policy in CONTRIBUTING.md if not present

Add unit tests for graceful shutdown logic

docs/guide/src/features/graceful-shutdown.md documents graceful shutdown as a feature, but scanning the src/ files doesn't show explicit graceful shutdown tests. This is a critical feature for production workloads and deserves dedicated test coverage to prevent regressions when handling SIGTERM, timeout configurations, and in-flight request handling.

• [ ] Create tests/graceful_shutdown.rs test module
• [ ] Add test case for SIGTERM signal handling and server shutdown sequence
• [ ] Add test case for request timeout configuration during shutdown
• [ ] Add test case validating in-flight requests are completed before adapter exits
• [ ] Add test case for shutdown-timeout environment variable behavior per docs/guide/src/configuration/
• [ ] Verify tests with: cargo test --test graceful_shutdown -- --nocapture

• Add integration test for response streaming with chunked Transfer-Encoding (docs/guide/src/configuration/response-streaming.md exists but benches/ only shows e2e_body_forwarding.rs). Create benches/e2e_response_streaming.rs to validate chunked responses aren't buffered.: Documentation exists, feature exists, but no visible benchmark/test validates it; low risk, high impact for correctness.
• Expand docs/guide/src/development/local-debugging.md with concrete example: run a simple Node.js Express server locally, invoke it via lambda-adapter with a mock Lambda event from docs/guide examples/. Include docker-compose.yml for reproducibility.: Development guide exists but is likely thin; benchmarks exist but are micro-focused; a local e2e walkthrough unblocks new contributors and validates setup docs.
• Add environment variable validation tests in src/main.rs coverage. Currently, no visible test validates AWS_LWA_PORT vs PORT fallback behavior, or AWS_LAMBDA_EXEC_WRAPPER parsing. Create unit tests in src/ that verify all configuration knobs from docs/guide/src/configuration/.: Configuration surface is documented but untested; operators will break if defaults change silently; easy tests catch regressions.

The codebase demonstrates a solid security posture with proper use of Rust's memory safety guarantees, adherence to security reporting guidelines (SECURITY.md), and secure CI/CD workflows (GitHub Actions with security audits). However, there are opportunities for improvement in dependency version pinning precision, security header guidance, and documentation of release build optimizations. No critical vulnerabilities, hardcoded secrets, or obvious injection risks were detected. The project follows AWS security best practices and maintains active security support for version 1.x.

• Medium · Dependency Version Pinning Not Strictly Enforced — Cargo.toml - [dependencies] section. While the Cargo.toml uses specific versions for most dependencies, some critical dependencies like 'tokio' and 'hyper' use flexible version constraints (e.g., '1.48.0' and '1.5.2'). This could allow patch versions with potential vulnerabilities to be pulled in during builds. Fix: Consider using exact version constraints (=1.48.0) for critical security-sensitive dependencies, or implement automated dependency scanning in CI/CD pipeline via 'cargo-audit' or 'cargo-deny'.
• Low · Missing Security Headers Configuration Guidance — Documentation and src/ directory. While the project handles HTTP request/response forwarding, there is no explicit documentation or built-in mechanism visible for enforcing security headers (Content-Security-Policy, X-Frame-Options, etc.) in the adapter layer. Fix: Add documentation on how to configure security headers through the web application or adapter configuration. Consider adding optional security header middleware.
• Low · Panic Configuration in Release Build — Cargo.toml - [profile.release] section. The Cargo.toml sets 'panic = "abort"' in release profile, which prevents unwinding and could mask certain error conditions. While this optimizes for size, it may reduce debuggability of production issues. Fix: Consider documenting the rationale for abort panic behavior. Ensure comprehensive error handling and logging is in place throughout the codebase to compensate for reduced unwinding visibility.
• Low · Dev Dependencies Include Cryptographic Libraries — Cargo.toml - [dev-dependencies] section. The dev-dependencies include 'aws-sigv4' and 'aws-credential-types' for testing purposes. While appropriate for testing, ensure these are not accidentally exposed in production builds. Fix: Verify that dev-dependencies are properly excluded from release builds. The current configuration appears correct, but document this for maintainers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.