diff --git a/Sources/AWSLambdaRuntime/Docs.docc/index.md b/Sources/AWSLambdaRuntime/Docs.docc/index.md index 50920dbd..4d7e1607 100644 --- a/Sources/AWSLambdaRuntime/Docs.docc/index.md +++ b/Sources/AWSLambdaRuntime/Docs.docc/index.md @@ -16,7 +16,7 @@ Swift AWS Lambda Runtime was designed to make building Lambda functions in Swift ## Getting started -If you have never used AWS Lambda or Docker before, check out this [getting started guide](https://fabianfett.de/getting-started-with-swift-aws-lambda-runtime) which helps you with every step from zero to a running Lambda. +If you have never used AWS Lambda or Docker before, check out this [getting started guide](https://swiftpackageindex.com/swift-server/swift-aws-lambda-runtime/1.0.0-alpha.3/tutorials/table-of-content) which helps you with every step from zero to a running Lambda. First, create a SwiftPM project and pull Swift AWS Lambda Runtime as dependency into your project @@ -120,32 +120,6 @@ First, add a dependency on the event packages: Modeling Lambda functions as Closures is both simple and safe. Swift AWS Lambda Runtime will ensure that the user-provided code is offloaded from the network processing thread such that even if the code becomes slow to respond or gets stuck, the underlying process can continue to function. This safety comes at a small performance penalty from context switching between threads. In many cases, the simplicity and safety of using the Closure based API is often preferred over the complexity of the performance-oriented API. -### Using EventLoopLambdaHandler - - Performance sensitive Lambda functions may choose to use a more complex API which allows user code to run on the same thread as the networking handlers. Swift AWS Lambda Runtime uses [SwiftNIO](https://github.com/apple/swift-nio) as its underlying networking engine which means the APIs are based on [SwiftNIO](https://github.com/apple/swift-nio) concurrency primitives like the `EventLoop` and `EventLoopFuture`. For example: - - ```swift - // Import the modules - import AWSLambdaRuntime - import AWSLambdaEvents - import NIO - - // Our Lambda handler, conforms to EventLoopLambdaHandler - struct Handler: EventLoopLambdaHandler { - typealias In = SNS.Message // Request type - typealias Out = Void // Response type - - // In this example we are receiving an SNS Message, with no response (Void). - func handle(context: Lambda.Context, event: In) -> EventLoopFuture { - ... - context.eventLoop.makeSucceededFuture(Void()) - } - } - - Lambda.run(Handler()) - ``` - - Beyond the small cognitive complexity of using the `EventLoopFuture` based APIs, note these APIs should be used with extra care. An [`EventLoopLambdaHandler`][ellh] will execute the user code on the same `EventLoop` (thread) as the library, making processing faster but requiring the user code to never call blocking APIs as it might prevent the underlying process from functioning. ## Deploying to AWS Lambda diff --git a/readme.md b/readme.md index ca8097e8..d437c598 100644 --- a/readme.md +++ b/readme.md @@ -128,6 +128,10 @@ This should print "dlroW olleH" ``` +## Tutorial + +[The Swift AWS Lambda Runtime docc tutorial](https://swiftpackageindex.com/swift-server/swift-aws-lambda-runtime/1.0.0-alpha.3/tutorials/table-of-content) provides developers with detailed step-by-step instructions to develop, build, and deploy a Lambda function. + ## Swift AWS Lambda Runtime Many modern systems have client components like iOS, macOS or watchOS applications as well as server components that those clients interact with. Serverless functions are often the easiest and most efficient way for client application developers to extend their applications into the cloud. @@ -142,15 +146,35 @@ Swift AWS Lambda Runtime was designed to make building Lambda functions in Swift ## Design Principles -tbd + reference to the `v2-api.md` design doc. +The [design document](Sources/AWSLambdaRuntimeCore/Documentation.docc/Proposals/0001-v2-api.md) details the v2 API proposal for the swift-aws-lambda-runtime library, which aims to enhance the developer experience for building serverless functions in Swift. -## Tutorial +The proposal has been reviewed and [incorporated feedback from the community](https://forums.swift.org/t/aws-lambda-v2-api-proposal/73819). The full v2 API design document is available [in this repository](Sources/AWSLambdaRuntimeCore/Documentation.docc/Proposals/0001-v2-api.md). + +**Key Design Principles** + +The v2 API prioritizes the following principles: + +**Readability and Maintainability**: Extensive use of `async`/`await` improves code clarity and simplifies maintenance. + +**Developer Control**: Developers own the `main()` function and have the flexibility to inject dependencies into the `LambdaRuntime`. This allows you to manage service lifecycles efficiently using [Swift Service Lifecycle](https://github.com/swift-server/swift-service-lifecycle) for structured concurrency. -link to [updated docc tutorial](https://swiftpackageindex.com/swift-server/swift-aws-lambda-runtime/1.0.0-alpha.3/tutorials/table-of-content) +**Simplified Codable Support**: The `LambdaCodableAdapter` struct eliminates the need for verbose boilerplate code when encoding and decoding events and responses. + +**New Capabilities** + +The v2 API introduces two new features: + +[Response Streaming](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/]): This functionality is ideal for handling large responses that need to be sent incrementally.   + +[Background Work](https://aws.amazon.com/blogs/compute/running-code-after-returning-a-response-from-an-aws-lambda-function/): Schedule tasks to run after returning a response to the AWS Lambda control plane. + +These new capabilities provide greater flexibility and control when building serverless functions in Swift with the swift-aws-lambda-runtime library. ## AWSLambdaRuntime API -tbd +### Receive and respond with JSON objects + +tbd + link to docc ### Lambda Streaming Response