Skip to content

Commit 1fcef19

Browse files
bnusunnybnusunny
authored
docs: add user guide with GitHub Pages deployment (#639)
Add an mdBook-based user guide covering getting started, configuration, features, examples, development, and architecture reference. Includes a GitHub Actions workflow to build and deploy the guide to GitHub Pages on pushes to main.
1 parent 80d8b2a commit 1fcef19

28 files changed

Lines changed: 959 additions & 1 deletion

‎.github/workflows/docs.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Deploy User Guide to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/guide/**'
8+
- '.github/workflows/docs.yaml'
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: "pages"
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Install mdBook
27+
run: |
28+
mkdir -p $HOME/bin
29+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C $HOME/bin
30+
echo "$HOME/bin" >> $GITHUB_PATH
31+
32+
- name: Build book
33+
run: mdbook build
34+
working-directory: docs/guide
35+
36+
- name: Upload artifact
37+
uses: actions/upload-pages-artifact@v3
38+
with:
39+
path: docs-site
40+
41+
deploy:
42+
environment:
43+
name: github-pages
44+
url: ${{ steps.deployment.outputs.page_url }}
45+
runs-on: ubuntu-latest
46+
needs: build
47+
steps:
48+
- name: Deploy to GitHub Pages
49+
id: deployment
50+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,7 @@ samconfig.toml
1010
**/bin/*
1111
**/.idea/*
1212

13-
.aider.*
13+
.aider.*
14+
15+
# mdBook build output
16+
/docs-site

‎docs/guide/book.toml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[book]
2+
authors = ["AWS Lambda Web Adapter Contributors"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "AWS Lambda Web Adapter User Guide"
7+
8+
[build]
9+
build-dir = "../../docs-site"
10+
11+
[output.html]
12+
default-theme = "light"
13+
preferred-dark-theme = "navy"
14+
git-repository-url = "https://github.com/awslabs/aws-lambda-web-adapter"
15+
git-repository-icon = "fa-github"
16+
site-url = "/aws-lambda-web-adapter/"

‎docs/guide/src/SUMMARY.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Summary
2+
3+
[Introduction](./introduction.md)
4+
5+
# Getting Started
6+
7+
- [Quick Start](./getting-started/quick-start.md)
8+
- [Docker Images](./getting-started/docker-images.md)
9+
- [Zip Packages](./getting-started/zip-packages.md)
10+
11+
# Configuration
12+
13+
- [Environment Variables](./configuration/environment-variables.md)
14+
- [Readiness Check](./configuration/readiness-check.md)
15+
- [Response Streaming](./configuration/response-streaming.md)
16+
- [Response Compression](./configuration/response-compression.md)
17+
- [Async Initialization](./configuration/async-init.md)
18+
- [Logging](./configuration/logging.md)
19+
20+
# Features
21+
22+
- [Request & Lambda Context](./features/request-context.md)
23+
- [Non-HTTP Event Triggers](./features/non-http-events.md)
24+
- [Multi-Tenancy](./features/multi-tenancy.md)
25+
- [Lambda Managed Instances](./features/managed-instances.md)
26+
- [Graceful Shutdown](./features/graceful-shutdown.md)
27+
- [Base Path Removal](./features/base-path-removal.md)
28+
- [Authorization Header](./features/authorization-header.md)
29+
- [Error Status Codes](./features/error-status-codes.md)
30+
- [Request Interception](./features/request-interception.md)
31+
32+
# Examples
33+
34+
- [Examples Overview](./examples/overview.md)
35+
36+
# Development
37+
38+
- [Local Debugging](./development/local-debugging.md)
39+
- [Building from Source](./development/building.md)
40+
41+
# Reference
42+
43+
- [Architecture](./reference/architecture.md)
44+
- [Changelog](./reference/changelog.md)

‎docs/guide/src/configuration/async-init.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Async Initialization
2+
3+
Lambda managed runtimes offer up to 10 seconds for function initialization with burst CPU. If your function can't complete initialization within that window, Lambda restarts it and bills for the init time.
4+
5+
## How It Works
6+
7+
When `AWS_LWA_ASYNC_INIT` is enabled:
8+
9+
1. The adapter performs readiness checks for up to 9.8 seconds
10+
2. If the app isn't ready by then, the adapter signals Lambda that init is complete
11+
3. Readiness checking continues during the first handler invocation
12+
4. This avoids the restart penalty while using the free init CPU burst
13+
14+
## Enabling
15+
16+
```
17+
AWS_LWA_ASYNC_INIT=true
18+
```
19+
20+
## When to Use
21+
22+
Enable this when your application has a long startup time (e.g. loading large ML models, warming caches, establishing connection pools) that might exceed the 10-second init window.

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Environment Variables
2+
3+
All configuration is done through environment variables, set either in your Dockerfile or as Lambda function configuration.
4+
5+
## Reference Table
6+
7+
| Variable | Description | Default |
8+
|----------|-------------|---------|
9+
| `AWS_LWA_PORT` | Traffic port your app listens on (falls back to `PORT`) | `8080` |
10+
| `AWS_LWA_READINESS_CHECK_PORT` | Readiness check port | Same as `AWS_LWA_PORT` |
11+
| `AWS_LWA_READINESS_CHECK_PATH` | Readiness check path | `/` |
12+
| `AWS_LWA_READINESS_CHECK_PROTOCOL` | Readiness check protocol: `http` or `tcp` | `http` |
13+
| `AWS_LWA_READINESS_CHECK_HEALTHY_STATUS` | HTTP status codes considered healthy (e.g. `200-399` or `200,201,204,301-399`) | `100-499` |
14+
| `AWS_LWA_ASYNC_INIT` | Enable asynchronous initialization | `false` |
15+
| `AWS_LWA_REMOVE_BASE_PATH` | Base path to remove from request path | None |
16+
| `AWS_LWA_ENABLE_COMPRESSION` | Enable gzip/br compression (buffered mode only) | `false` |
17+
| `AWS_LWA_INVOKE_MODE` | Invoke mode: `buffered` or `response_stream` | `buffered` |
18+
| `AWS_LWA_PASS_THROUGH_PATH` | Path for non-HTTP event payloads | `/events` |
19+
| `AWS_LWA_AUTHORIZATION_SOURCE` | Header name to replace with `Authorization` | None |
20+
| `AWS_LWA_ERROR_STATUS_CODES` | HTTP status codes that cause Lambda invocation failure (e.g. `500,502-504`) | None |
21+
| `AWS_LWA_LAMBDA_RUNTIME_API_PROXY` | Proxy URL for Lambda Runtime API requests | None |
22+
23+
## Deprecated Variables
24+
25+
The following non-namespaced variables are deprecated and will be removed in v2.0. Migrate to the `AWS_LWA_` prefixed versions.
26+
27+
| Deprecated | Replacement |
28+
|-----------|-------------|
29+
| `HOST` | N/A |
30+
| `READINESS_CHECK_PORT` | `AWS_LWA_READINESS_CHECK_PORT` |
31+
| `READINESS_CHECK_PATH` | `AWS_LWA_READINESS_CHECK_PATH` |
32+
| `READINESS_CHECK_PROTOCOL` | `AWS_LWA_READINESS_CHECK_PROTOCOL` |
33+
| `REMOVE_BASE_PATH` | `AWS_LWA_REMOVE_BASE_PATH` |
34+
| `ASYNC_INIT` | `AWS_LWA_ASYNC_INIT` |
35+
| `AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS` | `AWS_LWA_READINESS_CHECK_HEALTHY_STATUS` |
36+
37+
> `PORT` is **not** deprecated and remains a supported fallback for `AWS_LWA_PORT`.

‎docs/guide/src/configuration/logging.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Logging
2+
3+
Lambda Web Adapter supports [Lambda's Advanced Logging Controls](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-logs.html#monitoring-cloudwatchlogs-advanced). Configure log level and format through the Lambda console, API, or CLI under **Monitoring and operations tools > Logging configuration**.
4+
5+
## Environment Variables
6+
7+
| Variable | Description | Default |
8+
|----------|-------------|---------|
9+
| `AWS_LAMBDA_LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR`. Takes precedence over `RUST_LOG` | `INFO` |
10+
| `AWS_LAMBDA_LOG_FORMAT` | Log format: `JSON` or `TEXT` | `TEXT` |
11+
12+
You can also set `RUST_LOG` as a fallback if `AWS_LAMBDA_LOG_LEVEL` is not configured.
13+
14+
## JSON Logging
15+
16+
When log format is set to `JSON`, log entries are formatted as JSON objects, making them easier to query with CloudWatch Logs Insights.

‎docs/guide/src/configuration/readiness-check.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Readiness Check
2+
3+
When a new Lambda execution environment starts, the adapter boots as a Lambda Extension, followed by your web application. The adapter needs to know when your app is ready to receive traffic.
4+
5+
## How It Works
6+
7+
1. The adapter sends HTTP GET requests to your app at `http://127.0.0.1:8080/`
8+
2. It retries every 10 milliseconds
9+
3. Once it receives an HTTP response with status code >= 100 and < 500, the app is considered ready
10+
4. The adapter then starts the Lambda runtime client and begins forwarding invocations
11+
12+
## Configuration
13+
14+
| Variable | Description | Default |
15+
|----------|-------------|---------|
16+
| `AWS_LWA_READINESS_CHECK_PORT` | Port to check | Same as `AWS_LWA_PORT` |
17+
| `AWS_LWA_READINESS_CHECK_PATH` | Path to check | `/` |
18+
| `AWS_LWA_READINESS_CHECK_PROTOCOL` | `http` or `tcp` | `http` |
19+
| `AWS_LWA_READINESS_CHECK_HEALTHY_STATUS` | Status codes considered healthy | `100-499` |
20+
21+
## TCP Readiness Check
22+
23+
If your app doesn't have an HTTP health endpoint ready at startup, you can use TCP-based readiness checking:
24+
25+
```
26+
AWS_LWA_READINESS_CHECK_PROTOCOL=tcp
27+
```
28+
29+
This checks only that the port is accepting TCP connections.
30+
31+
## Custom Health Status Codes
32+
33+
You can customize which HTTP status codes are considered healthy:
34+
35+
```
36+
# Only 2xx and 3xx are healthy
37+
AWS_LWA_READINESS_CHECK_HEALTHY_STATUS=200-399
38+
39+
# Specific codes
40+
AWS_LWA_READINESS_CHECK_HEALTHY_STATUS=200,201,204,301-399
41+
```

‎docs/guide/src/configuration/response-compression.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Response Compression
2+
3+
Lambda Web Adapter supports gzip and Brotli compression for response bodies in buffered mode.
4+
5+
## Enabling Compression
6+
7+
```
8+
AWS_LWA_ENABLE_COMPRESSION=true
9+
```
10+
11+
## Behavior
12+
13+
When enabled:
14+
15+
- Responses are compressed using gzip or Brotli based on the client's `Accept-Encoding` header
16+
- Responses with `Content-Type` starting with `image` are **not** compressed
17+
- Responses smaller than 32 bytes are **not** compressed
18+
19+
## Limitations
20+
21+
Compression is **not supported** with response streaming (`AWS_LWA_INVOKE_MODE=response_stream`). If both are enabled, compression is automatically disabled and a warning is logged.

‎docs/guide/src/configuration/response-streaming.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Response Streaming
2+
3+
Lambda Web Adapter supports [Lambda response streaming](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/), allowing your app to stream responses back to clients as they are generated.
4+
5+
## Enabling Response Streaming
6+
7+
Set the invoke mode environment variable:
8+
9+
```
10+
AWS_LWA_INVOKE_MODE=response_stream
11+
```
12+
13+
This should match your Lambda Function URL's invoke mode configuration.
14+
15+
## When to Use
16+
17+
Response streaming is useful for:
18+
19+
- Server-sent events (SSE)
20+
- Large file downloads
21+
- Real-time data feeds
22+
- Reducing time-to-first-byte for slow-generating responses
23+
24+
## Limitations
25+
26+
- Compression (`AWS_LWA_ENABLE_COMPRESSION`) is not supported with response streaming. If both are enabled, compression is automatically disabled with a warning.
27+
- Response streaming works with Lambda Function URLs and API Gateway. ALB does not support streaming.
28+
29+
## Examples
30+
31+
- [FastAPI with Response Streaming](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming)
32+
- [FastAPI with Response Streaming in Zip](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming-zip)
33+
- [Next.js Response Streaming](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/nextjs-response-streaming)
34+
- [SpringBoot Response Streaming](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/springboot-response-streaming-zip)
35+
- [FastHTML with Response Streaming](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/fasthtml-response-streaming)

0 commit comments

Comments
 (0)