Merge branch 'main' into sebsto/shutdown_on_lost_connection

Author: sebsto

.github/workflows/pull_request.yml

@@ -36,7 +36,7 @@ jobs:
       # We pass the list of examples here, but we can't pass an array as argument
       # Instead, we pass a String with a valid JSON array.
       # The workaround is mentioned here https://github.com/orgs/community/discussions/11692
-      examples: "[ 'APIGateway', 'APIGateway+LambdaAuthorizer', 'BackgroundTasks', 'HelloJSON', 'HelloWorld', 'HummingbirdLambda', 'ResourcesPackaging', 'S3EventNotifier', 'S3_AWSSDK', 'S3_Soto', 'Streaming', 'StreamingFromEvent', 'ServiceLifecycle+Postgres', 'Testing', 'Tutorial' ]"
+      examples: "[ 'APIGateway', 'APIGateway+LambdaAuthorizer', 'BackgroundTasks', 'HelloJSON', 'HelloWorld', 'HummingbirdLambda', 'ResourcesPackaging', 'S3EventNotifier', 'S3_AWSSDK', 'S3_Soto', 'Streaming', 'Streaming+Codable', 'ServiceLifecycle+Postgres', 'Testing', 'Tutorial' ]"
       archive_plugin_examples: "[ 'HelloWorld', 'ResourcesPackaging' ]"
       archive_plugin_enabled: true
 

Examples/README.md

@@ -38,7 +38,7 @@ This directory contains example code for Lambda functions.
 
 - **[Streaming](Streaming/README.md)**: create a Lambda function exposed as an URL. The Lambda function streams its response over time. (requires [AWS SAM](https://aws.amazon.com/serverless/sam/)).
 
-- **[StreamingFromEvent](StreamingFromEvent/README.md)**: a Lambda function that combines JSON input decoding with response streaming capabilities, demonstrating the new streaming codable interface (requires [AWS SAM](https://aws.amazon.com/serverless/sam/) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)).
+- **[Streaming+Codable](Streaming+Codable/README.md)**: a Lambda function that combines JSON input decoding with response streaming capabilities, demonstrating a streaming codable interface (requires [AWS SAM](https://aws.amazon.com/serverless/sam/) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)).
 
 - **[Testing](Testing/README.md)**: a test suite for Lambda functions.
 

Examples/StreamingFromEvent/Package.swift renamed to Examples/Streaming+Codable/Package.swift

@@ -6,19 +6,28 @@ import PackageDescription
 import struct Foundation.URL
 
 let package = Package(
-    name: "StreamingFromEvent",
+    name: "StreamingCodable",
     platforms: [.macOS(.v15)],
     dependencies: [
         // during CI, the dependency on local version of swift-aws-lambda-runtime is added dynamically below
-        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "2.0.0-beta.1")
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "2.0.0-beta.1"),
+        .package(url: "https://github.com/swift-server/swift-aws-lambda-events.git", from: "1.2.0"),
     ],
     targets: [
         .executableTarget(
-            name: "StreamingFromEvent",
+            name: "StreamingCodable",
             dependencies: [
-                .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime")
+                .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+                .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events"),
             ]
-        )
+        ),
+        .testTarget(
+            name: "Streaming+CodableTests",
+            dependencies: [
+                "StreamingCodable",
+                .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
+            ]
+        ),
     ]
 )
 

Examples/StreamingFromEvent/README.md renamed to Examples/Streaming+Codable/README.md

@@ -1,12 +1,33 @@
 # Streaming Codable Lambda function
 
-This example demonstrates how to use the `StreamingLambdaHandlerWithEvent` protocol to create Lambda functions that:
+This example demonstrates how to use a `StreamingLambdaHandlerWithEvent` protocol to create Lambda functions, exposed through a FunctionUrl, that:
 
 1. **Receive JSON input**: Automatically decode JSON events into Swift structs
 2. **Stream responses**: Send data incrementally as it becomes available
 3. **Execute background work**: Perform additional processing after the response is sent
 
-The example uses the streaming codable interface that combines the benefits of:
+## When to Use This Approach
+
+**⚠️ Important Limitations:**
+
+1. **Function URL Only**: This streaming codable approach only works with Lambda functions exposed through [Lambda Function URLs](https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html)
+2. **Limited Request Access**: This approach hides the details of the `FunctionURLRequest` (like HTTP headers, query parameters, etc.) from developers
+
+**Decision Rule:**
+
+- **Use this streaming codable approach when:**
+  - Your function is exposed through a Lambda Function URL
+  - You have a JSON payload that you want automatically decoded
+  - You don't need to inspect HTTP headers, query parameters, or other request details
+  - You prioritize convenience over flexibility
+
+- **Use the ByteBuffer `StreamingLambdaHandler` approach when:**
+  - You need full control over the `FunctionURLRequest` details
+  - You're invoking the Lambda through other means (API Gateway, direct invocation, etc.)
+  - You need access to HTTP headers, query parameters, or request metadata
+  - You require maximum flexibility (requires writing more code)
+
+This example balances convenience and flexibility. The streaming codable interface combines the benefits of:
 - Type-safe JSON input decoding (like regular `LambdaHandler`)
 - Response streaming capabilities (like `StreamingLambdaHandler`)
 - Background work execution after response completion

Sources/AWSLambdaRuntime/LambdaStreaming+Codable.swift renamed to Examples/Streaming+Codable/Sources/LambdaStreaming+Codable.swift

@@ -12,6 +12,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+import AWSLambdaEvents
+import AWSLambdaRuntime
 import Logging
 import NIOCore
 
@@ -71,6 +73,9 @@ public struct StreamingLambdaCodableAdapter<
     }
 
     /// Handles the raw ByteBuffer by decoding it and passing to the underlying handler.
+    /// This function attempts to decode the event as a `FunctionURLRequest` first, which allows for
+    /// handling Function URL requests that may have a base64-encoded body.
+    /// If the decoding fails, it falls back to decoding the event "as-is" with the provided JSON type.
     /// - Parameters:
     ///   - event: The raw ByteBuffer event to decode.
     ///   - responseWriter: The response writer to pass to the underlying handler.
@@ -82,43 +87,20 @@ public struct StreamingLambdaCodableAdapter<
         context: LambdaContext
     ) async throws {
 
-        // try to decode the event as a FunctionURLRequest and extract its body
-        let urlRequestBody = bodyFromFunctionURLRequest(event)
+        var decodedBody: Handler.Event!
 
-        // decode the body or the event as user-provided JSON
-        let decodedEvent = try self.decoder.decode(Handler.Event.self, from: urlRequestBody ?? event)
+        // try to decode the event as a FunctionURLRequest, then fetch its body attribute
+        if let request = try? self.decoder.decode(FunctionURLRequest.self, from: event) {
+            // decode the body as user-provided JSON type
+            // this function handles the base64 decoding when needed
+            decodedBody = try request.decodeBody(Handler.Event.self)
+        } else {
+            // try to decode the event "as-is" with the provided JSON type
+            decodedBody = try self.decoder.decode(Handler.Event.self, from: event)
+        }
 
         // and pass it to the handler
-        try await self.handler.handle(decodedEvent, responseWriter: responseWriter, context: context)
-    }
-
-    /// Extract the body payload from a FunctionURLRequest event.
-    /// This function checks if the event is a valid `FunctionURLRequest` and decodes the body if it is base64 encoded.
-    /// If the event is not a valid `FunctionURLRequest`, it returns nil.
-    /// - Parameter event: The raw ByteBuffer event to check.
-    /// - Returns: The base64 decoded body of the FunctionURLRequest if it is a valid FunctionURLRequest, otherwise nil.
-    @inlinable
-    package func bodyFromFunctionURLRequest(_ event: ByteBuffer) -> ByteBuffer? {
-        do {
-            // try to decode as a FunctionURLRequest
-            let request = try self.decoder.decode(FunctionURLRequest.self, from: event)
-
-            // if the body is encoded in base64, decode it
-            if request.isBase64Encoded,
-                let base64EncodedString = request.body,
-                // this is the minimal way to base64 decode without importing new dependencies
-                let decodedData = Data(base64Encoded: base64EncodedString),
-                let decodedString = String(data: decodedData, encoding: .utf8)
-            {
-
-                return ByteBuffer(string: decodedString)
-            } else {
-                return ByteBuffer(string: request.body ?? "")
-            }
-        } catch {
-            // not a FunctionURLRequest, return nil
-            return nil
-        }
+        try await self.handler.handle(decodedBody, responseWriter: responseWriter, context: context)
     }
 }
 
@@ -149,8 +131,6 @@ public struct StreamingFromEventClosureHandler<Event: Decodable>: StreamingLambd
     }
 }
 
-#if FoundationJSONSupport
-
 extension StreamingLambdaCodableAdapter {
     /// Initialize with a JSON decoder and handler.
     /// - Parameters:
@@ -203,4 +183,3 @@ extension LambdaRuntime {
         self.init(handler: adapter, logger: logger)
     }
 }
-#endif  // FoundationJSONSupport

Examples/StreamingFromEvent/Sources/main.swift renamed to Examples/Streaming+Codable/Sources/main.swift

@@ -18,6 +18,7 @@ import Synchronization
 import Testing
 
 @testable import AWSLambdaRuntime
+@testable import StreamingCodable
 
 #if canImport(FoundationEssentials)
 import FoundationEssentials

Tests/AWSLambdaRuntimeTests/LambdaStreamingCodableTests.swift renamed to Examples/Streaming+Codable/Tests/LambdaStreamingCodableTests.swift

@@ -4,10 +4,10 @@ Description: SAM Template for StreamingfromEvent Example
 
 Resources:
   # Lambda function
-  StreamingFromEvent:
+  StreamingCodable:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/StreamingFromEvent/StreamingFromEvent.zip
+      CodeUri: .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/StreamingCodable/StreamingCodable.zip
       Timeout: 15
       Handler: swift.bootstrap  # ignored by the Swift runtime
       Runtime: provided.al2
@@ -22,4 +22,4 @@ Outputs:
   # print Lambda function URL
   LambdaURL:
     Description: Lambda URL
-    Value: !GetAtt StreamingFromEventUrl.FunctionUrl
+    Value: !GetAtt StreamingCodableUrl.FunctionUrl

Examples/StreamingFromEvent/events/sample-request.json renamed to Examples/Streaming+Codable/events/sample-request.json

@@ -1,6 +1,6 @@
 # Streaming Lambda function
 
-You can configure your Lambda function to stream response payloads back to clients. Response streaming can benefit latency sensitive applications by improving time to first byte (TTFB) performance. This is because you can send partial responses back to the client as they become available. Additionally, you can use response streaming to build functions that return larger payloads. Response stream payloads have a soft limit of 20 MB as compared to the 6 MB limit for buffered responses. Streaming a response also means that your function doesn’t need to fit the entire response in memory. For very large responses, this can reduce the amount of memory you need to configure for your function.
+You can configure your Lambda function to stream response payloads back to clients. Response streaming can benefit latency sensitive applications by improving time to first byte (TTFB) performance. This is because you can send partial responses back to the client as they become available. Additionally, you can use response streaming to build functions that return larger payloads. Response stream payloads have a soft limit of 200 MB as compared to the 6 MB limit for buffered responses. Streaming a response also means that your function doesn’t need to fit the entire response in memory. For very large responses, this can reduce the amount of memory you need to configure for your function.
 
 Streaming responses incurs a cost. For more information, see [AWS Lambda Pricing](https://aws.amazon.com/lambda/pricing/).