|
1 | 1 | # Rust Runtime for AWS Lambda |
2 | 2 |
|
3 | | -[](https://github.com/awslabs/aws-lambda-rust-runtime/actions) |
| 3 | +[](https://github.com/awslabs/aws-lambda-rust-runtime/actions) |
4 | 4 |
|
5 | 5 | This package makes it easy to run AWS Lambda Functions written in Rust. This workspace includes multiple crates: |
6 | 6 |
|
@@ -82,7 +82,7 @@ when a function invocation fails, AWS Lambda expects you to return an object tha |
82 | 82 | } |
83 | 83 | ``` |
84 | 84 |
|
85 | | -The Rust Runtime for Lambda uses a struct called `Diagnostic` to represent function errors internally. The runtime implements the converstion of several general errors types, like `std::error::Error`, into `Diagnostic`. For these general implementations, the `error_type` is the name of the value type returned by your function. For example, if your function returns `lambda_runtime::Error`, the `error_type` will be something like `alloc::boxed::Box<dyn core::error::Error + core::marker::Send + core::marker::Sync>`, which is not very descriptive. |
| 85 | +The Rust Runtime for Lambda uses a struct called `Diagnostic` to represent function errors internally. The runtime implements the conversion of several general error types, like `std::error::Error`, into `Diagnostic`. For these general implementations, the `error_type` is the name of the value type returned by your function. For example, if your function returns `lambda_runtime::Error`, the `error_type` will be something like `alloc::boxed::Box<dyn core::error::Error + core::marker::Send + core::marker::Sync>`, which is not very descriptive. |
86 | 86 |
|
87 | 87 | ### Implement your own Diagnostic |
88 | 88 |
|
@@ -126,6 +126,52 @@ async fn handler(_event: LambdaEvent<Request>) -> Result<(), Diagnostic> { |
126 | 126 |
|
127 | 127 | You can see more examples on how to use these error crates in our [example repository](https://github.com/awslabs/aws-lambda-rust-runtime/tree/main/examples/basic-error-error-crates-integration). |
128 | 128 |
|
| 129 | +### Graceful shutdown |
| 130 | + |
| 131 | +`lambda_runtime` offers a helper to simplify configuring graceful shutdown signal handling, `spawn_graceful_shutdown_handler()`. This requires the `graceful-shutdown` feature flag and only supports Unix systems. |
| 132 | + |
| 133 | +You can use it by passing a `FnOnce` closure that returns an async block. That async block will be executed |
| 134 | +when the function receives a `SIGTERM` or `SIGKILL`. |
| 135 | + |
| 136 | +Note that this helper is opinionated in a number of ways. Most notably: |
| 137 | +1. It spawns a task to drive your signal handlers |
| 138 | +2. It registers a 'no-op' extension in order to enable graceful shutdown signals |
| 139 | +3. It panics on unrecoverable errors |
| 140 | + |
| 141 | +If you prefer to fine-tune the behavior, refer to the implementation of `spawn_graceful_shutdown_handler()` as a starting point for your own. |
| 142 | + |
| 143 | +For more information on graceful shutdown handling in AWS Lambda, see: [aws-samples/graceful-shutdown-with-aws-lambda](https://github.com/aws-samples/graceful-shutdown-with-aws-lambda). |
| 144 | + |
| 145 | +Complete example (cleaning up a non-blocking tracing writer): |
| 146 | + |
| 147 | +```rust,no_run |
| 148 | +use lambda_runtime::{service_fn, LambdaEvent, Error}; |
| 149 | +use serde_json::{json, Value}; |
| 150 | +
|
| 151 | +#[tokio::main] |
| 152 | +async fn main() -> Result<(), Error> { |
| 153 | + let func = service_fn(func); |
| 154 | +
|
| 155 | + let (writer, log_guard) = tracing_appender::non_blocking(std::io::stdout()); |
| 156 | + lambda_runtime::tracing::init_default_subscriber_with_writer(writer); |
| 157 | +
|
| 158 | + let shutdown_hook = || async move { |
| 159 | + std::mem::drop(log_guard); |
| 160 | + }; |
| 161 | + lambda_runtime::spawn_graceful_shutdown_handler(shutdown_hook).await; |
| 162 | +
|
| 163 | + lambda_runtime::run(func).await?; |
| 164 | + Ok(()) |
| 165 | +} |
| 166 | +
|
| 167 | +async fn func(event: LambdaEvent<Value>) -> Result<Value, Error> { |
| 168 | + let (event, _context) = event.into_parts(); |
| 169 | + let first_name = event["firstName"].as_str().unwrap_or("world"); |
| 170 | +
|
| 171 | + Ok(json!({ "message": format!("Hello, {}!", first_name) })) |
| 172 | +} |
| 173 | +``` |
| 174 | + |
129 | 175 | ## Building and deploying your Lambda functions |
130 | 176 |
|
131 | 177 | If you already have Cargo Lambda installed in your machine, run the next command to build your function: |
@@ -409,7 +455,7 @@ fn main() -> Result<(), Box<Error>> { |
409 | 455 |
|
410 | 456 | ## Supported Rust Versions (MSRV) |
411 | 457 |
|
412 | | -The AWS Lambda Rust Runtime requires a minimum of Rust 1.71.1, and is not guaranteed to build on compiler versions earlier than that. |
| 458 | +The AWS Lambda Rust Runtime requires a minimum of Rust 1.81.0, and is not guaranteed to build on compiler versions earlier than that. |
413 | 459 |
|
414 | 460 | ## Security |
415 | 461 |
|
|
0 commit comments