You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+41-29Lines changed: 41 additions & 29 deletions
Original file line number
Diff line number
Diff line change
@@ -66,71 +66,81 @@ For details, please check out [the example nodejs application](examples/expressj
66
66
67
67
When a new Lambda Execution Environment starts up, Lambda Web Adapter will boot up as a Lambda Extension, followed by the web application.
68
68
69
-
By default, Lambda Web Adapter will send HTTP GET requests to the web application at `http://127.0.0.1:8080/`. The port and path can be customized with two environment variables: `READINESS_CHECK_PORT` and `READINESS_CHECK_PATH`.
69
+
By default, Lambda Web Adapter will send HTTP GET requests to the web application at `http://127.0.0.1:8080/`. The port and path can be customized with two environment variables: `AWS_LWA_READINESS_CHECK_PORT` and `AWS_LWA_READINESS_CHECK_PATH`.
70
70
71
-
Lambda Web Adapter will retry this request every 10 milliseconds until the web application returns an HTTP response (any status code) or the function times out.
71
+
Lambda Web Adapter will retry this request every 10 milliseconds until the web application returns an HTTP response (**status code >= 100 and < 500**) or the function times out.
72
72
73
-
In addition, you can configure the adapter to preform readiness check with TCP connect, by setting `READINESS_CHECK_PROTOCOL` to `tcp`.
73
+
In addition, you can configure the adapter to preform readiness check with TCP connect, by setting `AWS_LWA_READINESS_CHECK_PROTOCOL` to `tcp`.
74
74
75
75
After passing readiness check, Lambda Web Adapter will start Lambda Runtime and forward the invokes to the web application.
76
76
77
77
## Configurations
78
78
79
79
The readiness check port/path and traffic port can be configured using environment variables. These environment variables can be defined either within docker file or as Lambda function configuration.
| AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL*| readiness check protocol: "http" or "tcp", default is "http" | "http" |
87
+
| AWS_LWA_ASYNC_INIT / ASYNC_INIT*| enable asynchronous initialization for long initialization functions | "false" |
88
+
| AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH*| the base path to be removed from request path | None |
89
+
| AWS_LWA_ENABLE_COMPRESSION | enable gzip compression for response body | "false" |
90
+
| AWS_LWA_ENABLE_TLS | enable TLS/HTTPS support for the web application | "false" |
91
+
| AWS_LWA_TLS_SERVER_NAME | override server name for TLS SNI | "localhost" |
92
+
| AWS_LWA_TLS_CERT_FILE | override server certificate file | None |
93
+
| AWS_LWA_INVOKE_MODE | Lambda function invoke mode: "buffered" or "response_stream", default is "buffered" | "buffered" |
94
+
95
+
> **Note:**
96
+
> We use "AWS_LWA_" prefix to namespacing all environment variables used by Lambda Web Adapter. The original ones will be supported until we reach version 1.0.
97
+
98
+
**AWS_LWA_PORT / PORT** - Lambda Web Adapter will send traffic to this port. This is the port your web application listening on. Inside Lambda execution environment,
95
99
the web application runs as a non-root user, and not allowed to listen on ports lower than 1024. Please also avoid port 9001 and 3000.
96
100
Lambda Runtime API is on port 9001. CloudWatch Lambda Insight extension uses port 3000.
97
101
98
-
99
-
**ASYNC_INIT** - Lambda managed runtimes offer up to 10 seconds for function initialization. During this period of time, Lambda functions have burst of CPU to accelerate initialization, and it is free.
102
+
**AWS_LWA_ASYNC_INIT / ASYNC_INIT** - Lambda managed runtimes offer up to 10 seconds for function initialization. During this period of time, Lambda functions have burst of CPU to accelerate initialization, and it is free.
100
103
If a lambda function couldn't complete the initialization within 10 seconds, Lambda will restart the function, and bill for the initialization.
101
104
To help functions to use this 10 seconds free initialization time and avoid the restart, Lambda Web Adapter supports asynchronous initialization.
102
105
When this feature is enabled, Lambda Web Adapter performs readiness check up to 9.8 seconds. If the web app is not ready by then,
103
106
Lambda Web Adapter signals to Lambda service that the init is completed, and continues readiness check in the handler.
104
107
This feature is disabled by default. Enable it by setting environment variable `ASYNC_INIT` to `true`.
105
108
106
-
**AWS_LWA_ENABLE_COMPRESSION** - Lambda Web Adapter supports gzip compression for response body. This feature is disabled by default. Enable it by setting environment variable `AWS_LWA_ENABLE_COMPRESSION` to `true`.
107
-
When enabled, Lambda Web Adapter will check the `Accept-Encoding` header in the request, and compress the response body if the header contains `gzip`, if the response body is not already compressed, and if the `Content-Type` starts with `text/` or is `application/javascript`, `application/json`, `application/json+ld`, `application/xml`, `application/xhtml+xml`, `application/x-javascript`, or `image/svg+xml`.
108
-
Note that the `Content-Length` header will be set to the compressed size, not the original size.
109
-
110
-
**REMOVE_BASE_PATH** - The value of this environment variable tells the adapter whether the application is running under a base path.
109
+
**AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH** - The value of this environment variable tells the adapter whether the application is running under a base path.
111
110
For example, you could have configured your API Gateway to have a /orders/{proxy+} and a /catalog/{proxy+} resource.
112
111
Each resource is handled by a separate Lambda functions. For this reason, the application inside Lambda may not be aware of the fact that the /orders path exists.
113
112
Use REMOVE_BASE_PATH to remove the /orders prefix when routing requests to the application. Defaults to empty string. Checkout [SpringBoot](examples/springboot) example.
114
113
114
+
**AWS_LWA_ENABLE_COMPRESSION** - Lambda Web Adapter supports gzip compression for response body. This feature is disabled by default. Enable it by setting environment variable `AWS_LWA_ENABLE_COMPRESSION` to `true`.
115
+
When enabled, this will compress responses unless it's an image as determined by the content-type starting with `image` or the response is less than 32 bytes. This will also compress HTTP/1.1 chunked streaming response.
116
+
115
117
**AWS_LWA_ENABLE_TLS** - With TLS support enabled, Lambda Web Adapter uses HTTPS to communicate with the web application. Lambda Web Adapter use
116
118
[hyper-rustls](https://crates.io/crates/hyper-rustls) with [rustls-native-certs](https://crates.io/crates/rustls-native-certs) to implement TLS support.
117
119
It supports TLS1.2 and TLS1.3 with safe defaults. To see the supported TLS features, please check out [rustls](https://docs.rs/rustls/latest/rustls/).
118
120
119
121
**AWS_LWA_TLS_SERVER_NAME** - allows you to override the server name for TLS Server Name Indication. This should match one of the SAN names on the server certificate. The default is "localhost".
120
122
121
123
**AWS_LWA_TLS_CERT_FILE** - Lambda Web Adapter uses the platform's native certificate store to find trusted certificates. You can configure this environment variable to use your own certificate.
122
-
Please check out [FastAPI with Https](examples/fastapi-https/) example for more details.
124
+
Please check out [FastAPI with HTTPS](examples/fastapi-https) example for more details.
123
125
126
+
**AWS_LWA_INVOKE_MODE** - Lambda function invoke mode, this should match Function Url invoke mode. The default is "buffered". When configured as "response_stream", Lambda Web Adapter will stream response to Lambda service [blog](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/).
127
+
Please check out [FastAPI with Response Streaming](examples/fastapi-response-streaming) example.
124
128
125
129
## Request Context
126
130
127
131
**Request Context** is metadata API Gateway sends to Lambda for a request. It usually contains requestId, requestTime, apiId, identity, and authorizer. Identity and authorizer are useful to get client identity for authorization. API Gateway Developer Guide contains more details [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format).
128
132
129
133
Lambda Web Adapter forwards this information to the web application in a Http Header named "x-amzn-request-context". In the web application, you can retrieve the value of this http header and deserialize it into a JSON object. Check out [Express.js in Zip](examples/expressjs-zip) on how to use it.
130
134
135
+
## Graceful Shutdown
136
+
137
+
For a function with Lambda Extensions registered, Lambda enables shutdown phase for the function. When Lambda service is about to shut down a Lambda execution environment,
138
+
it sends a SIGTERM signal to the runtime and then a SHUTDOWN event to each registered external extensions. Developers could catch the SIGTERM signal in the lambda functions and perform graceful shutdown tasks.
139
+
The [Express.js](examples/expressjs) gives a simple example. More details in [this repo](https://github.com/aws-samples/graceful-shutdown-with-aws-lambda).
140
+
131
141
## Local Debugging
132
142
133
-
Lambda Web Adapter allows developers to develop web applications locally with familiar tools and debuggers. If you want to simulate Lambda Runtime environment locally, you can use AWS SAM CLI. The following command starts a local api gateway endpoint and simulate the Lambda runtime execution environment.
143
+
Lambda Web Adapter allows developers to develop web applications locally with familiar tools and debuggers: just run the web app locally and test it. If you want to simulate Lambda Runtime environment locally, you can use AWS SAM CLI. The following command starts a local api gateway endpoint and simulate the Lambda runtime execution environment.
134
144
135
145
```bash
136
146
sam local start-api
@@ -140,11 +150,13 @@ Please note that `sam local` starts a Lambda Runtime Interface Emulator on port
140
150
141
151
## Examples
142
152
143
-
-[FastAPI](examples/fastapi/)
144
-
-[FastAPI with Https](examples/fastapi-https/)
145
-
-[FastAPI in Zip](examples/fastapi-zip/)
153
+
-[FastAPI](examples/fastapi)
154
+
-[FastAPI with HTTPS](examples/fastapi-https)
155
+
-[FastAPI with Response Streaming](examples/fastapi-response-streaming)
156
+
-[FastAPI in Zip](examples/fastapi-zip)
146
157
-[Flask](examples/flask)
147
158
-[Flask in Zip](examples/flask-zip)
159
+
-[Serverless Django by @efi-mk](https://github.com/aws-hebrew-book/serverless-django)
0 commit comments