feat: add SnapStart support via SnapStartResource trait

Implement the SnapStart restore lifecycle so Rust Lambda functions can
participate in SnapStart optimizations when deployed as container images
with custom base images.

Custom logic around the snapshot/restore boundary is expressed by
implementing the CRaC-style `SnapStartResource` trait and registering
instances on the runtime. The trait methods return `BoxFuture` (no
`async-trait` dependency) so the trait stays object-safe as
`dyn SnapStartResource`. The runtime drives the lifecycle internally:

  before_snapshot hooks (LIFO) -> GET /restore/next (blocks until restore)
  -> rebuild RAPID connection pool -> after_restore hooks (FIFO)

Resources use stack ordering: register foundations first; before_snapshot
runs in reverse registration order and after_restore in registration order.

Error handling: a before-snapshot/`/restore/next` failure is reported to
Lambda via POST /init/error; an after_restore failure via POST
/restore/error. Both are propagated outward so the runtime exits via the
normal Result path (no process::exit, so graceful-shutdown handlers still
run). Failures to send the report are logged. When SnapStart is not enabled
the hooks are never invoked.

Connection-pool reset after restore is non-breaking: rather than mutating the
existing `Client`, a new `PooledClient` (with lock-free `OnceLock`-based
`reset_pool()`) and a `RuntimeApiClient` trait are added to the api-client
crate. `lambda_runtime`'s service layer takes a defaulted generic
`C = Client` bounded by the trait and uses `PooledClient` internally; the old
`Client` is frozen at its 1.0.3 shape and deprecated. cargo-semver-checks
confirms all three crates stay non-breaking (api-client is a 1.1.0 minor bump
for the deprecation + additive API).

Changes:
- lambda-runtime-api-client: add `PooledClient` + `RuntimeApiClient` trait +
  `ClientBuilder::build_pooled`; deprecate `Client`/`build`; bump to 1.1.0
- lambda-runtime: add `SnapStartResource` trait, Init/Restore error requests,
  `Runtime::is_snapstart()` and `register_snapstart_resource()`; run the
  restore lifecycle from run()/run_concurrent(); defaulted-generic service
  layer using `PooledClient`; re-export `SnapStartResource` and `BoxFuture`
- lambda-http: add runtime()/runtime_concurrent() and streaming_runtime()
  helpers; re-export `SnapStartResource` and `BoxFuture`
- lambda-extension: use `PooledClient`
- examples: add basic-snapstart and http-snapstart
- tests: request serialization, full restore lifecycle, LIFO/FIFO ordering,
  no-op when not SnapStart, and before/after/restore-next failure paths

Author: bnusunny

examples/basic-snapstart/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "basic-snapstart"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+lambda_runtime = { path = "../../lambda-runtime" }
+serde = "1.0.219"
+serde_json = "1.0"
+tokio = { version = "1", features = ["macros"] }

examples/basic-snapstart/Dockerfile

@@ -0,0 +1,38 @@
+# Container image for the basic-snapstart example.
+#
+# SnapStart for functions packaged as OCI images requires a custom base image
+# whose runtime implements the restore lifecycle — which `lambda_runtime` now
+# does. This image builds the example as the Lambda `bootstrap` on top of the
+# AWS-provided base (`provided:al2023`), which supports SnapStart.
+#
+# Build from the REPOSITORY ROOT (the example uses path dependencies on the
+# workspace crates, so the build context must include them):
+#
+#   docker build -f examples/basic-snapstart/Dockerfile -t basic-snapstart .
+#
+# Then push to ECR and create the function with SnapStart enabled
+# (PublishedVersions) and the architecture matching your build host.
+
+# ---- build stage ----
+FROM public.ecr.aws/lambda/provided:al2023 AS builder
+
+RUN dnf install -y gcc && \
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Copy only the workspace crates this example depends on via path, then the
+# example itself: lambda_runtime -> lambda_runtime_api_client.
+COPY Cargo.* /build/
+COPY lambda-runtime /build/lambda-runtime
+COPY lambda-runtime-api-client /build/lambda-runtime-api-client
+COPY examples/basic-snapstart /build/examples/basic-snapstart
+
+WORKDIR /build/examples/basic-snapstart
+RUN cargo build --release
+
+# ---- runtime stage ----
+FROM public.ecr.aws/lambda/provided:al2023
+
+COPY --from=builder /build/examples/basic-snapstart/target/release/basic-snapstart ${LAMBDA_RUNTIME_DIR}/bootstrap
+
+ENTRYPOINT [ "/var/runtime/bootstrap" ]

examples/basic-snapstart/README.md

@@ -0,0 +1,58 @@
+# AWS Lambda SnapStart example (lambda_runtime)
+
+This example shows how to use AWS Lambda **SnapStart** with the `lambda_runtime`
+crate. It implements the [`SnapStartResource`] trait on an `AppState` and
+registers it on the runtime, so the runtime runs the resource's `before_snapshot`
+hook before the VM snapshot and its `after_restore` hook after each restore.
+
+SnapStart reduces cold-start latency by snapshotting the initialized execution
+environment and restoring from it. Resources created during init (connections,
+credentials, unique values) may be invalid after restore — `before_snapshot` /
+`after_restore` are where you release and re-establish them. When SnapStart is
+not enabled, the hooks are never called and the function behaves normally.
+
+## Why a container image?
+
+SnapStart for functions packaged as OCI images requires a custom base image
+whose runtime implements the restore lifecycle — which `lambda_runtime` now does.
+This example ships a `Dockerfile` that builds the binary as the Lambda
+`bootstrap` on top of `public.ecr.aws/lambda/provided:al2023`, which supports
+SnapStart.
+
+## Build & Deploy
+
+Build the image from the **repository root** (the example depends on the
+workspace crates via path, so the build context must include them):
+
+```sh
+docker build -f examples/basic-snapstart/Dockerfile -t basic-snapstart .
+```
+
+Push it to ECR and create the function from the image:
+
+```sh
+aws ecr create-repository --repository-name basic-snapstart
+docker tag basic-snapstart:latest <ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/basic-snapstart:latest
+docker push <ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/basic-snapstart:latest
+
+aws lambda create-function \
+  --function-name basic-snapstart \
+  --package-type Image \
+  --code ImageUri=<ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/basic-snapstart:latest \
+  --role <YOUR_EXECUTION_ROLE_ARN> \
+  --snap-start ApplyOn=PublishedVersions
+```
+
+SnapStart applies to **published versions**, so publish a version to trigger
+snapshot creation, then invoke that version (or an alias pointing at it):
+
+```sh
+aws lambda publish-version --function-name basic-snapstart
+aws lambda invoke --function-name basic-snapstart:1 --payload '{"name":"world"}' out.json
+```
+
+## Architecture
+
+The compiled `bootstrap` is architecture-specific. Build on (or for) the same
+architecture as the target function — `provided:al2023` is available for both
+`x86_64` and `arm64`.

examples/basic-snapstart/src/main.rs

@@ -0,0 +1,85 @@
+// This example demonstrates using SnapStart with the lambda_runtime crate.
+//
+// Implement the `SnapStartResource` trait on the types that hold
+// snapshot-sensitive state (connections, credentials, cached values) and
+// register them on the runtime. When deployed with SnapStart enabled, the
+// runtime will:
+// 1. Initialize and create resources (e.g., database connections)
+// 2. Run each resource's `before_snapshot` hook (reverse registration order)
+//    before the VM snapshot
+// 3. Call `/restore/next`, which blocks until the VM is restored
+// 4. Run each resource's `after_restore` hook (registration order) after restore
+// 5. Enter the normal invocation loop
+//
+// When SnapStart is NOT enabled, the hooks are never called and the runtime
+// behaves exactly as before.
+
+use lambda_runtime::{service_fn, tracing, BoxFuture, Error, LambdaEvent, Runtime, SnapStartResource};
+use serde::{Deserialize, Serialize};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+#[derive(Deserialize)]
+struct Request {
+    name: String,
+}
+
+#[derive(Serialize)]
+struct Response {
+    message: String,
+    invocation_count: u64,
+}
+
+struct AppState {
+    counter: AtomicU64,
+}
+
+impl AppState {
+    fn new() -> Self {
+        Self {
+            counter: AtomicU64::new(0),
+        }
+    }
+}
+
+impl SnapStartResource for AppState {
+    fn before_snapshot(&self) -> BoxFuture<'_, Result<(), Error>> {
+        Box::pin(async move {
+            tracing::info!("Releasing resources before snapshot");
+            self.counter.store(0, Ordering::Relaxed);
+            Ok(())
+        })
+    }
+
+    fn after_restore(&self) -> BoxFuture<'_, Result<(), Error>> {
+        Box::pin(async move {
+            tracing::info!("Re-establishing resources after restore");
+            Ok(())
+        })
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing::init_default_subscriber();
+
+    let state = Arc::new(AppState::new());
+
+    let state_ref = state.clone();
+    let handler = service_fn(move |event: LambdaEvent<Request>| {
+        let state = state_ref.clone();
+        async move {
+            let count = state.counter.fetch_add(1, Ordering::Relaxed) + 1;
+            Ok::<_, Error>(Response {
+                message: format!("Hello, {}!", event.payload.name),
+                invocation_count: count,
+            })
+        }
+    });
+
+    Runtime::new(handler)
+        .register_snapstart_resource(state.clone())
+        .run()
+        .await?;
+    Ok(())
+}

examples/http-snapstart/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "http-snapstart"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+lambda_http = { path = "../../lambda-http" }
+tokio = { version = "1", features = ["macros"] }

examples/http-snapstart/Dockerfile

@@ -0,0 +1,41 @@
+# Container image for the http-snapstart example.
+#
+# SnapStart for functions packaged as OCI images requires a custom base image
+# whose runtime implements the restore lifecycle — which `lambda_runtime` now
+# does. This image builds the example as the Lambda `bootstrap` on top of the
+# AWS-provided base (`provided:al2023`), which supports SnapStart.
+#
+# Build from the REPOSITORY ROOT (the example uses path dependencies on the
+# workspace crates, so the build context must include them):
+#
+#   docker build -f examples/http-snapstart/Dockerfile -t http-snapstart .
+#
+# Then push to ECR and create the function with SnapStart enabled
+# (PublishedVersions) and the architecture matching your build host.
+
+# ---- build stage ----
+FROM public.ecr.aws/lambda/provided:al2023 AS builder
+
+RUN dnf install -y gcc && \
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Copy only the workspace crates this example depends on via path, then the
+# example itself: lambda_http -> lambda_runtime -> lambda_runtime_api_client,
+# plus lambda-events (the aws_lambda_events crate used by lambda_http).
+COPY Cargo.* /build/
+COPY lambda-http /build/lambda-http
+COPY lambda-runtime /build/lambda-runtime
+COPY lambda-runtime-api-client /build/lambda-runtime-api-client
+COPY lambda-events /build/lambda-events
+COPY examples/http-snapstart /build/examples/http-snapstart
+
+WORKDIR /build/examples/http-snapstart
+RUN cargo build --release
+
+# ---- runtime stage ----
+FROM public.ecr.aws/lambda/provided:al2023
+
+COPY --from=builder /build/examples/http-snapstart/target/release/http-snapstart ${LAMBDA_RUNTIME_DIR}/bootstrap
+
+ENTRYPOINT [ "/var/runtime/bootstrap" ]

examples/http-snapstart/README.md

@@ -0,0 +1,59 @@
+# AWS Lambda SnapStart example (lambda_http)
+
+This example shows how to use AWS Lambda **SnapStart** with the `lambda_http`
+crate. It wraps a shared connection pool in a `SnapStartResource` and registers
+it via the [`lambda_http::runtime`] helper, so the runtime drains the pool before
+the VM snapshot and reconnects it after each restore. The HTTP handler keeps the
+usual `lambda_http` request/response ergonomics.
+
+SnapStart reduces cold-start latency by snapshotting the initialized execution
+environment and restoring from it. Resources created during init (connections,
+credentials, unique values) may be invalid after restore — `before_snapshot` /
+`after_restore` are where you release and re-establish them. When SnapStart is
+not enabled, the hooks are never called and the function behaves normally.
+
+If you don't need custom hooks, plain `lambda_http::run(...)` already gets
+SnapStart support for free: the runtime calls `/restore/next` and rebuilds its
+internal RAPID connection pool on restore without any extra code.
+
+## Why a container image?
+
+SnapStart for functions packaged as OCI images requires a custom base image
+whose runtime implements the restore lifecycle — which `lambda_runtime` (used by
+`lambda_http`) now does. This example ships a `Dockerfile` that builds the binary
+as the Lambda `bootstrap` on top of `public.ecr.aws/lambda/provided:al2023`,
+which supports SnapStart.
+
+## Build & Deploy
+
+Build the image from the **repository root** (the example depends on the
+workspace crates via path, so the build context must include them):
+
+```sh
+docker build -f examples/http-snapstart/Dockerfile -t http-snapstart .
+```
+
+Push it to ECR and create the function from the image:
+
+```sh
+aws ecr create-repository --repository-name http-snapstart
+docker tag http-snapstart:latest <ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/http-snapstart:latest
+docker push <ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/http-snapstart:latest
+
+aws lambda create-function \
+  --function-name http-snapstart \
+  --package-type Image \
+  --code ImageUri=<ACCOUNT>.dkr.ecr.<REGION>.amazonaws.com/http-snapstart:latest \
+  --role <YOUR_EXECUTION_ROLE_ARN> \
+  --snap-start ApplyOn=PublishedVersions
+```
+
+SnapStart applies to **published versions**, so publish a version to trigger
+snapshot creation, then expose it behind a function URL or API Gateway and invoke
+it (e.g. `?name=world`).
+
+## Architecture
+
+The compiled `bootstrap` is architecture-specific. Build on (or for) the same
+architecture as the target function — `provided:al2023` is available for both
+`x86_64` and `arm64`.

examples/http-snapstart/src/main.rs

@@ -0,0 +1,77 @@
+// This example demonstrates using SnapStart with the lambda_http crate.
+//
+// Use lambda_http::runtime() to get a Runtime on which you can register
+// `SnapStartResource`s. This gives you access to the SnapStart lifecycle while
+// keeping the lambda_http request/response ergonomics.
+//
+// For the simple case where no custom hooks are needed, just use
+// lambda_http::run() — SnapStart works automatically.
+
+use lambda_http::{
+    service_fn, tracing, BoxFuture, Body, Error, IntoResponse, Request, RequestExt, Response, SnapStartResource,
+};
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+struct DbPool {
+    connected: bool,
+}
+
+impl DbPool {
+    async fn connect() -> Self {
+        tracing::info!("Establishing database connection pool");
+        Self { connected: true }
+    }
+}
+
+/// A `SnapStartResource` wrapper around the shared connection pool. The handler
+/// and the resource share the same `Arc<RwLock<DbPool>>`, so draining before the
+/// snapshot and reconnecting after restore are visible to invocations.
+struct PoolResource(Arc<RwLock<DbPool>>);
+
+impl SnapStartResource for PoolResource {
+    fn before_snapshot(&self) -> BoxFuture<'_, Result<(), Error>> {
+        Box::pin(async move {
+            tracing::info!("Draining database connections before snapshot");
+            self.0.write().await.connected = false;
+            Ok(())
+        })
+    }
+
+    fn after_restore(&self) -> BoxFuture<'_, Result<(), Error>> {
+        Box::pin(async move {
+            tracing::info!("Re-establishing database connections after restore");
+            self.0.write().await.connected = true;
+            Ok(())
+        })
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing::init_default_subscriber();
+
+    let pool = Arc::new(RwLock::new(DbPool::connect().await));
+
+    let pool_ref = pool.clone();
+    let handler = service_fn(move |req: Request| {
+        let pool = pool_ref.clone();
+        async move {
+            let pool = pool.read().await;
+            assert!(pool.connected, "Pool should be connected during invocation");
+
+            let name = req
+                .query_string_parameters_ref()
+                .and_then(|params| params.first("name"))
+                .unwrap_or("world");
+
+            Ok::<Response<Body>, Error>(format!("Hello, {name}!").into_response().await)
+        }
+    });
+
+    lambda_http::runtime(handler)
+        .register_snapstart_resource(Arc::new(PoolResource(pool.clone())))
+        .run()
+        .await?;
+    Ok(())
+}

lambda-extension/Cargo.toml

@@ -25,7 +25,7 @@ http = { workspace = true }
 http-body-util = { workspace = true }
 hyper = { workspace = true, features = ["http1", "client", "server"] }
 hyper-util = { workspace = true }
-lambda_runtime_api_client = { version = "1.0.3", path = "../lambda-runtime-api-client" }
+lambda_runtime_api_client = { version = "1.1.0", path = "../lambda-runtime-api-client" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "^1"
 tokio = { version = "1.0", features = [