feat: add Lambda SnapStart support

CHANGELOG.md

@@ -1,3 +1,17 @@
+## 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 (bounded by 10 seconds) before admitting traffic, and
+  it rejects external traffic to the hook paths with 403.
+
+---
+
 ## v1.0.1 - 2026-05-28
 
 ### Bug Fixes

Cargo.toml

@@ -23,7 +23,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",

README.md

@@ -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
@@ -66,6 +67,8 @@ The readiness check port/path and traffic port can be configured using environme
 | 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         |
 
 > **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 +78,36 @@ 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, a connection failure, or taking longer than 60 seconds to
+respond 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.
+
+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. If the application does
+not report ready within 10 seconds of restore, the restore 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.
+
+See the [FastAPI with SnapStart example](examples/fastapi-snapstart-zip) for a complete, deployable application.
+
 ## Examples
 
 - [FastAPI](examples/fastapi)
@@ -84,6 +117,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)

docs/guide/src/SUMMARY.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/configuration/environment-variables.md

@@ -19,6 +19,8 @@ All configuration is done through environment variables, set either in your Dock
 | `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 |
 
 ## Deprecated Variables
 

docs/guide/src/examples/overview.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 |

docs/guide/src/features/snapstart.md

@@ -0,0 +1,66 @@
+# SnapStart
+
+[Lambda SnapStart](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html) snapshots an initialized execution environment and restores it on later cold starts, reducing startup latency. Because the adapter runs your web application as a separate process, the application does not have direct access to the SnapStart lifecycle. The adapter bridges this gap with two optional HTTP hooks.
+
+## Hooks
+
+| Variable | When the adapter calls it | Use it to |
+|----------|---------------------------|-----------|
+| `AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH` | Before the snapshot is taken | Drain or close resources that will not survive the snapshot |
+| `AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH` | After restore, before serving traffic | Reconnect, refresh credentials, reseed randomness, regenerate unique identifiers |
+
+Both hooks are opt-in and independent — each fires only when its variable is set.
+
+## How it works
+
+The adapter always registers for the SnapStart lifecycle; the Lambda runtime invokes the hooks only when your function runs under SnapStart. When it does, the adapter participates as follows:
+
+1. **Before checkpoint** — if `AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH` is set, the adapter sends an empty `POST` to that path on your application, then signals Lambda that it is ready for the snapshot.
+2. **After restore** — Lambda restores the environment. The adapter first refreshes its own HTTP connection to your application (so it never reuses a connection captured in the snapshot); then, if `AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH` is set, sends an empty `POST` to that path; and finally re-runs the readiness check before admitting traffic.
+
+Each hook is an empty `POST`, and your application must respond with a `2xx` status. A non-`2xx` response, a connection failure, or taking longer than 60 seconds to respond fails the SnapStart phase — initialization for the before-checkpoint hook, restore for the after-restore hook — rather than serving traffic against an improperly prepared application. The final readiness check runs on every restore (whether or not an after-restore path is configured); if your application does not report ready within 10 seconds of restore, the restore fails.
+
+## Why you need the hooks
+
+State captured in a snapshot is shared across every restored environment. Two classes of problem follow:
+
+- **Stale connections.** Database connections, cached DNS, and keep-alive HTTP connections captured in the snapshot are dead by the time the environment is restored. Close them in the before-checkpoint hook and re-establish them in the after-restore hook.
+- **Uniqueness and entropy.** Values seeded once at initialization — random number generators, UUID seeds, security tokens — become identical across every restored environment. Reseed them in the after-restore hook.
+
+## Securing the hook paths
+
+The 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. The guard matches the exact configured path, so choose paths your normal application traffic does not use (for example, `/snapstart/before` and `/snapstart/after`).
+
+## Example
+
+```python
+from fastapi import FastAPI, Response
+
+app = FastAPI()
+pool = None  # your database/connection pool
+
+
+@app.post("/snapstart/before")
+async def before_checkpoint():
+    # Close resources that won't survive the snapshot.
+    if pool is not None:
+        await pool.close()
+    return Response(status_code=200)
+
+
+@app.post("/snapstart/after")
+async def after_restore():
+    # Re-establish resources and reseed anything that must be unique.
+    global pool
+    pool = await create_pool()
+    return Response(status_code=200)
+```
+
+Configure the function with:
+
+```
+AWS_LWA_SNAPSTART_BEFORE_CHECKPOINT_PATH=/snapstart/before
+AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH=/snapstart/after
+```
+
+See the [fastapi-snapstart-zip example](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples/fastapi-snapstart-zip) for a complete, deployable application.