Github Pages Warp Lambda Starter

🚀 SAM Rust + Warp + Diesel on Lambda

This project demonstrates a fully serverless Rust backend architecture running on AWS Lambda, powered by:

• 🌐 Warp — ergonomic, high-performance HTTP server
• 🛢️ Diesel — production-ready ORM for PostgreSQL
• 🔌 warp_lambda — seamlessly adapt Warp filters for Lambda
• 🧱 AWS SAM — serverless framework to define and deploy the stack
• 📦 libpq Lambda layer — compiled from source to support Diesel's PostgreSQL backend on Lambda

---

🔧 Prerequisites

Ensure the following tools are installed:

• Rust
• Cargo Lambda
• AWS CLI
• AWS SAM CLI
• Docker
• Docker Compose
• act (optional, for running GitHub Actions locally)

---

📁 Project Structure

.
├── rust_app/                # Rust source (Cargo.toml, main.rs, handlers, etc.)
├── libpq_layer/            # Compiled libpq.so + headers for Lambda
├── libpq_layer.zip         # Zipped Lambda layer (optional manual upload)
├── build_libpq_layer.sh    # Script to compile the layer inside Amazon Linux 2
├── docker-compose.yaml     # Local PostgreSQL with pgvector extension
├── env.json                # SAM local environment config
├── template.yaml           # AWS SAM template defining function and layer
├── Makefile                # Helper tasks for build, test, deploy

---

✅ Features

• GET /Prod/hello: healthcheck endpoint
• Executes SELECT 1 on PostgreSQL via Diesel
• Async server using tokio, with spawn_blocking for Diesel
• Connection pooling with r2d2
• Robust tracing logs for full request lifecycle

---

🛠️ Setup & Local Development

1. Build the libpq Lambda Layer

./build_libpq_layer.sh

This script:

• Uses Docker (Amazon Linux 2) to compile PostgreSQL’s client library (libpq)
• Extracts headers and .so files
• Produces a ready-to-use Lambda layer structure under libpq_layer/
• Zips it as libpq_layer.zip (optional)

2. Start PostgreSQL Locally

docker-compose up -d

• Exposes postgres://root:password@test-db:5432/test
• Includes pgvector extension
• Waits for readiness with pg_isready

3. Build the Lambda Function

make sam-build

This runs sam build with the correct Rust target and environment configuration.

4. Run Locally

make sam-run

Then visit:

http://127.0.0.1:3000/Prod/hello

Expected response:

{ "message": "Hello World with DB!" }

On failure, a descriptive error is returned with full logs via tracing.

---

🧪 Testing

The /Prod/hello route performs:

• A pooled DB connection
• A SELECT 1 SQL query
• Full logging of success/failure with tokio::timeout handling

---

🌐 API Gateway Routing

SAM uses a /{proxy+} path in template.yaml:

Path: /{proxy+}
Method: ANY

This allows Warp to handle all routing. Example route in main.rs:

warp::path!("Prod" / "hello")

SAM adds the Prod stage automatically — always include it in local or deployed endpoints.

---

📦 Dependencies

Highlights from Cargo.toml:

• warp + warp_lambda — web + Lambda adapter
• diesel + r2d2 — DB access + connection pooling
• tokio — async runtime
• openssl — bundled with vendored for static compatibility
• serde, serde_json — JSON serialization
• tracing, tracing-subscriber — structured logging

---

🚀 Deployment

Deploy to AWS with:

sam deploy --guided

Follow prompts to configure the stack name, region, and IAM roles. The Lambda function and the libpq layer will be deployed together.

---

🧼 Cleanup

To stop local Docker containers:

docker-compose down

---

✅ CI/CD

GitHub Actions (ci.yaml) supports:

• Caching for Rust + Docker layers
• libpq layer build
• Lambda binary compilation via cargo lambda
• sam build validation

To test locally:

act -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

See: ./.github/workflows/ci.yaml

---

✨ Credits

Special thanks to the maintainers of:

• warp
• warp_lambda
• cargo-lambda
• aws-lambda-rust-runtime

---

cargo install cross --git https://github.com/cross-rs/cross --branch main --force export CROSS_CONTAINER_ENGINE=docker