feat: support Lambda SnapStart

Bridge the Lambda SnapStart lifecycle to the inner web application. Because the
adapter runs the app as a separate process, the app has no access to the
snapshot boundary; two optional HTTP hooks give it one.

- AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH: POSTed before the snapshot so the app
  can drain resources that will not survive it.
- AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH: POSTed after restore so the app can
  reconnect, refresh credentials, reseed randomness and regenerate per-environment
  identifiers.

Both are opt-in and independent. A non-2xx response or a connection failure fails
the corresponding SnapStart phase rather than serving traffic against an
improperly prepared application. Each hook waits for the readiness check first, so
AWS_LWA_ASYNC_INIT cannot let a hook fire before the app is listening.

After restore the adapter also rebuilds its own HTTP client, so no connection
captured in the snapshot is reused, and re-runs the readiness check before traffic
is admitted.

The hook paths are control-plane routes, so external requests that resolve to one
receive 403. The guard canonicalizes both sides through the same Url::set_path
transformation and compares segment lists, so alternate spellings -- percent
encoding, encoded slashes, matrix parameters, dot segments, case, repeated slashes
-- are blocked too. A hook path the guard cannot cover exactly (not
canonicalizable, decoding to a literal %, collapsing to the app root, or colliding
with AWS_LWA_PASS_THROUGH_PATH) fails initialization instead of running with a
partially protected route.

Connection pooling is disabled for the pre-snapshot client because CLOCK_MONOTONIC
does not advance across the snapshot gap, which makes hyper's idle accounting
unreliable for entries pooled before it (hyper#3810, rust-lang/rust#79462). The
client rebuilt after restore pools normally, since it holds no pre-boundary
entries -- that is what makes the new AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS effective
on the invocations that serve traffic.

Also adds AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS to bound the readiness wait at
cold start and after restore, bumps lambda_http to 1.3.0 for the SnapStart
lifecycle APIs, fixes AWS_LWA_REMOVE_BASE_PATH to strip exactly one leading
occurrence on a segment boundary, and ships deployable FastAPI examples for both
zip and container packaging.

Validated on a deployed SnapStart container function: both hooks fire, the 403
guard blocks the full equivalence class through API Gateway while distinct routes
still 404, post-restore idle reuse works, the after-restore reseed yields distinct
per-environment identifiers, and graceful-shutdown SIGTERM still arrives on
restored environments.

Author: bnusunny

CHANGELOG.md

@@ -1,3 +1,67 @@
+## Unreleased
+
+### Features
+
+- Add SnapStart support. The adapter notifies your web application at the SnapStart
+  boundary via two opt-in HTTP hooks — `AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH`
+  (before checkpoint) and `AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH` (after restore) —
+  so it can drain and re-establish connections. Each hook call is bounded by a
+  60-second timeout. After restore the adapter refreshes its own HTTP client and
+  re-runs the readiness check before admitting traffic, and it rejects external
+  traffic to the hook paths with 403.
+  - The crate now stops publishing to crates.io (`publish = false`): Lambda Web
+    Adapter ships as the `lambda-adapter` binary (a Lambda layer / copied
+    extension), not as a library, so the `lib` target has no external
+    API-stability contract. The internal changes SnapStart required — the
+    `tower::Service` impl's `Response` is now `Response<BoxBody<Bytes, Error>>`
+    (was `Response<Incoming>`) and `check_init_health` now returns `Result` —
+    therefore do not affect any published API. `Bytes` and `BoxBody` are
+    re-exported for convenience of in-repo `Service` users. Existing crates.io
+    consumers keep the last published release (`1.0.0-rc1`) unchanged.
+- Add `AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS` to configure the idle keep-alive
+  (fractional seconds allowed, e.g. `0.5`) of the adapter's HTTP connection to your
+  app. Default: 4 seconds. A value that is set but unusable falls back to the
+  default and logs a warning.
+- Add `AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS` to bound the readiness check
+  (fractional seconds allowed, e.g. `0.5`), applied to both the initial cold-start
+  readiness wait and the
+  post-SnapStart-restore readiness check. When set and the app does not become
+  ready within it, the adapter **refuses to serve**: cold-start init fails (the
+  runtime never starts) and a restore fails, rather than admitting traffic to an
+  app that never reported ready. When unset (the default) the wait is
+  **unbounded**, matching the previous behavior, so existing slow-cold-start apps
+  are unaffected unless they opt in. The `async_init` initial-readiness path keeps
+  its own fixed ~9.8s bound (non-fatal) and is not affected by this variable.
+
+### Bug Fixes
+
+- Fix `AWS_LWA_REMOVE_BASE_PATH` stripping to remove exactly one leading occurrence
+  on a path-segment boundary. Previously it used `trim_start_matches`, which stripped
+  the prefix repeatedly and byte-wise: with `AWS_LWA_REMOVE_BASE_PATH=/api`,
+  `/api/api/order` became `/order` (both copies removed) and `/apiorder` became
+  `/order` (a partial segment stripped). Now `/api/api/order` → `/api/order` and
+  `/apiorder` is passed through unchanged, and a configured trailing slash (`/api/`)
+  is normalized so it behaves like `/api`. **Upgrade note:** this changes the path
+  forwarded to your app for those inputs — deployments that relied on the old
+  repeated/partial stripping should verify their routes.
+- Fix the before-checkpoint hook firing before the application is ready. With
+  `AWS_LWA_ASYNC_INIT=true` the adapter finishes initialization after 9.8 seconds
+  even if the app has not bound its port yet; the hook `POST` then failed
+  immediately with a connection error and failed the SnapStart initialization phase.
+  Both hooks now wait for the readiness check first, bounded by
+  `AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS` when it is set.
+
+### Dependencies
+
+- Bump `lambda_http` to 1.3.0 (from 1.1.1) for the SnapStart lifecycle APIs.
+  **Note:** this changes the `Cookie` header the inner application receives on
+  every deployment, SnapStart or not — a multi-entry API Gateway v2 `cookies` array
+  is now joined with `"; "` instead of `";"`, so your app sees `a=1; b=2` rather
+  than `a=1;b=2`. That is the RFC 6265 form and frameworks accept both, but code
+  that splits on a bare `;` without trimming will see leading spaces.
+
+---
+
 ## v1.0.1 - 2026-05-28
 
 ### Bug Fixes

Cargo.lock

@@ -11,10 +11,18 @@ keywords = ["AWS", "Lambda", "APIGateway", "ALB", "API"]
 license = "Apache-2.0"
 homepage = "https://github.com/aws/aws-lambda-web-adapter"
 repository = "https://github.com/aws/aws-lambda-web-adapter"
-documentation = "https://docs.rs/lambda_web_adapter"
 categories = ["web-programming::http-server"]
 readme = "README.md"
 exclude = ["examples"]
+# Lambda Web Adapter ships as the `lambda-adapter` binary (packaged as a Lambda
+# layer / container-copied extension), not as a library. This stops publishing the
+# crate to crates.io: the `lib` target is an internal implementation detail of the
+# binary and tests, with no external API-stability contract.
+#
+# Note for crates.io consumers: earlier `0.x` / `1.0.0-rc1` releases remain
+# available and unchanged; they are simply the last published versions. New
+# development ships only as the binary/layer.
+publish = false
 
 [dependencies]
 bytes = "1.9.0"
@@ -23,7 +31,7 @@ http-body = "1.0.1"
 http-body-util = "0.1.0"
 hyper = { version = "1.5.2", features = ["client"] }
 hyper-util = "0.1.10"
-lambda_http = { version = "1.1.1", default-features = false, features = [
+lambda_http = { version = "1.3.0", default-features = false, features = [
     "apigw_http",
     "apigw_rest",
     "alb",

Cargo.toml

@@ -15,6 +15,7 @@ The same docker image can run on AWS Lambda, Amazon EC2, AWS Fargate, and local
 - Supports Amazon API Gateway Rest API and Http API endpoints, Lambda Function URLs, and Application Load Balancer
 - Supports Lambda managed runtimes, custom runtimes and docker OCI images
 - Supports Lambda Managed Instances for multi-concurrent request handling
+- Supports Lambda SnapStart with before-checkpoint and after-restore hooks
 - Supports any web frameworks and languages, no new code dependency to include
 - Automatic encode binary response
 - Enables graceful shutdown
@@ -59,13 +60,17 @@ The readiness check port/path and traffic port can be configured using environme
 | AWS_LWA_READINESS_CHECK_PROTOCOL        | readiness check protocol: "http" or "tcp"                                       | "http"       |
 | AWS_LWA_READINESS_CHECK_HEALTHY_STATUS  | HTTP status codes considered healthy (e.g., "200-399")                          | "100-499"    |
 | AWS_LWA_ASYNC_INIT                      | enable asynchronous initialization for long initialization functions             | "false"      |
-| AWS_LWA_REMOVE_BASE_PATH               | the base path to be removed from request path                                   | None         |
+| AWS_LWA_REMOVE_BASE_PATH               | base path to remove from the request path; strips exactly one leading occurrence on a segment boundary (with `/api`: `/api/api/order`->`/api/order`, `/apiorder` unchanged; trailing slash normalized) | None         |
 | AWS_LWA_ENABLE_COMPRESSION             | enable gzip/br compression for response body (buffered mode only)               | "false"      |
 | AWS_LWA_INVOKE_MODE                    | Lambda function invoke mode: "buffered" or "response_stream"                    | "buffered"   |
 | AWS_LWA_PASS_THROUGH_PATH             | the path for receiving event payloads from non-http triggers                    | "/events"    |
 | AWS_LWA_AUTHORIZATION_SOURCE          | a header name to be replaced to `Authorization`                                 | None         |
 | AWS_LWA_ERROR_STATUS_CODES            | HTTP status codes that will cause Lambda invocations to fail (e.g. "500,502-504") | None       |
 | AWS_LWA_LAMBDA_RUNTIME_API_PROXY      | overwrites `AWS_LAMBDA_RUNTIME_API` to allow proxying request                   | None         |
+| AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH | inner-app path the adapter POSTs to before a SnapStart snapshot (drain resources) | None         |
+| AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH     | inner-app path the adapter POSTs to after a SnapStart restore (reconnect/reseed)  | None         |
+| AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS        | idle keep-alive (seconds) for the adapter's connection to your app                | "4"          |
+| AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS  | seconds (fractional allowed, e.g. 0.5) to wait for the app to report ready (cold-start init and after a SnapStart restore); on expiry the adapter FAILS (init fails and the runtime never starts; a restore fails) rather than serving. Unset, 0, or negative all mean wait indefinitely (a set-but-<=0 or malformed value is ignored with a warning). async_init keeps its own ~9.8s bound | unset / <=0 (unbounded) |
 
 > **Deprecation Notice:** The following non-namespaced environment variables are deprecated and will be removed in version 2.0:
 > `HOST`, `READINESS_CHECK_PORT`, `READINESS_CHECK_PATH`, `READINESS_CHECK_PROTOCOL`, `REMOVE_BASE_PATH`, `ASYNC_INIT`.
@@ -75,6 +80,46 @@ The readiness check port/path and traffic port can be configured using environme
 
 👉 [Detailed configuration docs](https://aws.github.io/aws-lambda-web-adapter/configuration/environment-variables.html)
 
+### SnapStart support
+
+When your function uses [Lambda SnapStart](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html),
+the adapter can notify your web application at the snapshot boundary so it can
+drain and re-establish state (database connections, cached DNS, PRNG seeds,
+unique identifiers). Both hooks are opt-in and independent.
+
+| Variable | When the adapter calls it | Use it to |
+|---|---|---|
+| `AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH` | Before the snapshot is taken | Drain/close resources that won't survive the snapshot |
+| `AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH`     | After restore, before serving traffic | Reconnect, refresh credentials, reseed randomness, regenerate unique IDs |
+
+Each hook is an empty `POST`; your application must respond with a `2xx` status.
+A non-`2xx` response or a connection failure fails the SnapStart phase
+(initialization for the before-checkpoint hook, restore for the after-restore hook)
+instead of serving traffic against an improperly prepared application. The adapter
+does not impose its own deadline on a hook — Lambda bounds both phases, and the
+after-restore hook in particular must finish within your function timeout.
+
+After restore, the adapter also automatically refreshes its own HTTP connection
+to your application, so it never reuses a connection captured in the snapshot, and
+then re-runs the readiness check before admitting traffic. By default this wait is
+unbounded; set `AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS` (fractional seconds allowed)
+to bound it, in which case a restore whose application does not report ready within
+that timeout fails.
+
+> These hook paths are control-plane operations. External requests (via API
+> Gateway or ALB) that target a configured hook path receive `403 Forbidden` and
+> are never forwarded to your application, so choose paths your normal traffic
+> does not use.
+>
+> **Warning:** that guard exists only while the adapter is in the request path —
+> that is, when your application runs on Lambda behind the adapter. The hook routes
+> are ordinary application routes that mutate state, so if you run the same image
+> or application **without** the adapter (Amazon ECS, Amazon EKS, a local Docker
+> host), they are reachable and unauthenticated. Don't expose them publicly in
+> those deployments, or protect them yourself.
+
+See the [FastAPI with SnapStart example](examples/fastapi-snapstart-zip) for a complete, deployable application.
+
 ## Examples
 
 - [FastAPI](examples/fastapi)
@@ -84,6 +129,8 @@ The readiness check port/path and traffic port can be configured using environme
 - [FastAPI with Response Streaming in Zip](examples/fastapi-response-streaming-zip)
 - [FastAPI with Response Streaming on Lambda Managed Instances](examples/fastapi-response-streaming-lmi)
 - [FastAPI Response Streaming Backend with IAM Auth](examples/fastapi-backend-only-response-streaming/)
+- [FastAPI with SnapStart](examples/fastapi-snapstart)
+- [FastAPI with SnapStart in Zip](examples/fastapi-snapstart-zip)
 - [Flask](examples/flask)
 - [Flask in Zip](examples/flask-zip)
 - [Serverless Django](https://github.com/aws-hebrew-book/serverless-django)  by [@efi-mk](https://github.com/efi-mk)

README.md

@@ -23,6 +23,7 @@
 - [Non-HTTP Event Triggers](./features/non-http-events.md)
 - [Multi-Tenancy](./features/multi-tenancy.md)
 - [Lambda Managed Instances](./features/managed-instances.md)
+- [SnapStart](./features/snapstart.md)
 - [Graceful Shutdown](./features/graceful-shutdown.md)
 - [Base Path Removal](./features/base-path-removal.md)
 - [Authorization Header](./features/authorization-header.md)

docs/guide/src/SUMMARY.md

@@ -12,13 +12,17 @@ All configuration is done through environment variables, set either in your Dock
 | `AWS_LWA_READINESS_CHECK_PROTOCOL` | Readiness check protocol: `http` or `tcp` | `http` |
 | `AWS_LWA_READINESS_CHECK_HEALTHY_STATUS` | HTTP status codes considered healthy (e.g. `200-399` or `200,201,204,301-399`) | `100-499` |
 | `AWS_LWA_ASYNC_INIT` | Enable asynchronous initialization | `false` |
-| `AWS_LWA_REMOVE_BASE_PATH` | Base path to remove from request path | None |
+| `AWS_LWA_REMOVE_BASE_PATH` | Base path to remove from the request path. Strips **exactly one** leading occurrence and only on a path-segment boundary: with `/api`, `/api/api/order` → `/api/order` and `/apiorder` is passed through unchanged; a configured trailing slash (`/api/`) is normalized. | None |
 | `AWS_LWA_ENABLE_COMPRESSION` | Enable gzip/br compression (buffered mode only) | `false` |
 | `AWS_LWA_INVOKE_MODE` | Invoke mode: `buffered` or `response_stream` | `buffered` |
 | `AWS_LWA_PASS_THROUGH_PATH` | Path for non-HTTP event payloads | `/events` |
 | `AWS_LWA_AUTHORIZATION_SOURCE` | Header name to replace with `Authorization` | None |
 | `AWS_LWA_ERROR_STATUS_CODES` | HTTP status codes that cause Lambda invocation failure (e.g. `500,502-504`) | None |
 | `AWS_LWA_LAMBDA_RUNTIME_API_PROXY` | Proxy URL for Lambda Runtime API requests | None |
+| `AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH` | Inner-app path the adapter POSTs to before a SnapStart snapshot | None |
+| `AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH` | Inner-app path the adapter POSTs to after a SnapStart restore | None |
+| `AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS` | Idle keep-alive (seconds) for the adapter's connection to your app | `4` |
+| `AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS` | Seconds (fractional allowed, e.g. `0.5`) the adapter waits for the app to report ready (cold-start init **and** after a SnapStart restore). On expiry the adapter **fails** rather than serving: cold-start init fails (the runtime never starts) and a restore fails. Unset, `0`, or a negative value all mean **wait indefinitely** (no bound); a set-but-`<= 0` or malformed value is ignored with a `warn!`. The `async_init` path keeps its own ~9.8s bound (non-fatal) and is unaffected. | unset / `<= 0` (unbounded) |
 
 ## Deprecated Variables
 

docs/guide/src/configuration/environment-variables.md

@@ -8,6 +8,8 @@ The repository includes working examples for many popular web frameworks, packag
 |---------|-----------|-----------|
 | [FastAPI](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi) | Docker | No |
 | [FastAPI in Zip](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-zip) | Zip | No |
+| [FastAPI SnapStart](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-snapstart) | Docker | No |
+| [FastAPI SnapStart Zip](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-snapstart-zip) | Zip | No |
 | [FastAPI Background Tasks](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-background-tasks) | Docker | No |
 | [FastAPI Response Streaming](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming) | Docker | Yes |
 | [FastAPI Response Streaming Zip](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming-zip) | Zip | Yes |