Revert streaming codable handler change and propose it as an example
instead of an handler API.
**Motivation:**
I made a mistake when submitting this PR
https://github.com/swift-server/swift-aws-lambda-runtime/pull/532
It provides a Streaming+Codable handler that conveniently allows
developers to write handlers with `Codable` events for streaming
functions.
This is a mistake for three reasons:
- This is the only handler that assumes a Lamba Event structure as
input. I added a minimal `FunctionUrlRequest` and `FunctionURLResponse`
to avoid importing the AWS Lambda Events library. It is the first
handler to be event-specific. I don't think the runtime should introduce
event specific code.
- The handler only works when Lambda functions are exposed through
Function URLs. Streaming functions can also be invoke by API or CLI.
- The handler hides `FunctionURLRequest` details (HTTP headers, query
parameters, etc.) from developers
Developers were unaware they were trading flexibility for convenience
The lack of clear documentation about these limitations led to incorrect
usage patterns and frustrated developers who needed full request control
or were using other invocation methods.
**Modifications:**
- Removed the Streaming+Codable API from the library
- Moved the Streaming+Codable code to an example
- Added prominent warning section in the example README explaining the
limitations
- Clarified when to use Streaming+Codable vs ByteBuffer approaches
- Added decision rule framework to help developers choose the right
approach
**Result:**
The only API provided by the library to use Streaming Lambda functions
is exposing the raw `ByteBuffer` as input, there is no more `Codable`
handler for Streaming functions available in the API. I kept the
`Streaming+Codable` code an example.
After this change, developers have clear guidance on when to use each
streaming approach:
- Use streaming codable for Function URL + JSON payload + no request
details needed
- Use ByteBuffer StreamingLambdaHandler for full control, other
invocation methods, or request metadata access
This prevents misuse of the API and sets proper expectations about the
handler's capabilities and limitations, leading to better developer
experience and fewer integration issues.
Add Hummingbird web framework integration example for AWS Lambda
**Motivation:**
Developers using the Hummingbird web framework need a clear example of
how to integrate it with AWS Lambda. The existing examples focus on
basic Lambda handlers, but don't demonstrate how to use popular Swift
web frameworks like Hummingbird in a serverless context.
**Modifications:**
Added a complete Hummingbird Lambda example in Examples/Hummingbird/
including Package.swift with Hummingbird Lambda dependencies, main.swift
demonstrating router setup with API Gateway V2 integration, SAM template
for deployment, and comprehensive README documentation with build,
deploy, and usage instructions.
**Result:**
Developers can now easily create AWS Lambda functions using the
Hummingbird web framework, with a working example that shows router
configuration, API Gateway integration, and complete deployment workflow
using familiar Hummingbird syntax.
Add user-facing API for Streaming Lambda functions that receives JSON
events
### Motivation:
Streaming Lambda functions developed by developers had no choice but to
implement a handler that receives incoming data as a `ByteBuffer`. While
this is useful for low-level development, I assume most developers will
want to receive a JSON event to trigger their streaming Lambda function.
Going efficiently from a `ByteBuffer` to a Swift struct requires some
code implemented in the `JSON+ByteBuffer.swift` file of the librray. We
propose to further help developers by providing them with a new
`handler()` function that directly receives their `Decodable` type.
### Modifications:
This PR adds a public facing API (+ unit test + updated README) allowing
developers to write a handler method accepting any `Decodable` struct as
input.
```swift
import AWSLambdaRuntime
import NIOCore
// Define your input event structure
struct StreamingRequest: Decodable {
let count: Int
let message: String
let delayMs: Int?
}
// Use the new streaming handler with JSON decoding
let runtime = LambdaRuntime { (event: StreamingRequest, responseWriter, context: LambdaContext) in
context.logger.info("Received request to send \(event.count) messages")
// Stream the messages
for i in 1...event.count {
let response = "Message \(i)/\(event.count): \(event.message)\n"
try await responseWriter.write(ByteBuffer(string: response))
// Optional delay between messages
if let delay = event.delayMs, delay > 0 {
try await Task.sleep(for: .milliseconds(delay))
}
}
// Finish the stream
try await responseWriter.finish()
// Optional: Execute background work after response is sent
context.logger.info("Background work: processing completed")
}
try await runtime.run()
```
This interface provides:
- **Type-safe JSON input**: Automatic decoding of JSON events into Swift
structs
- **Streaming responses**: Full control over when and how to stream data
back to clients
- **Background work support**: Ability to execute code after the
response stream is finished
- **Familiar API**: Uses the same closure-based pattern as regular
Lambda handlers
Because streaming Lambda functions can be invoked either directly
through the API or through Lambda Function URL, this PR adds the
decoding logic to support both types, shielding developers from working
with Function URL requests and base64 encoding.
We understand these choice will have an impact on the raw performance
for event handling. Those advanced users that want to get the maximum
might use the existing `handler(_ event: ByteBuffer, writer:
LambaStreamingWriter)` function to implement their own custom decoding
logic.
This PR provides a balance between ease of use for 80% of the users vs
ultimate performance, without closing the door for the 20% who need it.
### Result:
Lambda function developers can now use arbitrary `Decodable` Swift
struct or Lambda events to trigger their streaming functions. 🎉
---------
Co-authored-by: Tim Condon <0xTim@users.noreply.github.com>
Add `S3EventNotifier` example
### Motivation:
There is currently no example regarding an AWS event triggered lambda,
such as a lambda that gets invoked on an S3 object upload. I've had to
look for a while to figure out that the `AWSLambdaEvents` exists and
that it can be used for that (had to find out via a Java example! 😜) so
I think this could be useful and a somewhat common use case
### Modifications:
Added an example of a lambda that gets triggered when an object gets
uploaded to an S3 bucket.
I have not described how to set up the actual S3 event in AWS because I
figured if you needed such a lambda you'd know, but I can describe that
too in the README if needed
---------
Co-authored-by: Sébastien Stormacq <sebastien.stormacq@gmail.com>
Add an example of an APIGateway Lambda Authorizer
### Motivation:
Lambda Authorizers allow developers to write custom logic to validate
HTTP REST requests.
This example shows how to write a Lambda Authorizer in Swift and how to
configure an API Gateway to use a Lambda Authorizer.
This example use a SAM template to deploy the resources.
### Modifications:
- Add `Examples/APIGateway+LambdaAuthorizer` directory with the source
code, a `template.yaml`, and a `README` file.
- Add a reference to the new example in `Examples/README`
- Modify CI to build the new example
### Result:
There is a new example showing how to develop a Lambda authorizer in
Swift and how to attach it to an APIGateway with SAM
This new example project show four testing strategies for Swift Lambda
function
- Unit testing the business logic (not specific to Swift Lambda)
- Integration testing the handler method
- Local invocation with the Swift Lambda Runtime
- Local invocation with SAM
**[IMPORTANT]**
To allow testing the handler, I had to change visibility of a method in
the Runtime project. This method is clearly marked for testing only, so
it should not be a problem. Happy to read feedback and discuss however.
Sébastien Stormacq
Paul ToffoloniandSébastien Stormacq