Merge branch 'main' into feature/packaging-plugin

Author: fabianfett

.swiftformat

@@ -1,6 +1,6 @@
 # file options
 
---swiftversion 5.2
+--swiftversion 5.4
 --exclude .build
 
 # format options

Package.swift

@@ -35,7 +35,12 @@ let package = Package(
         ]),
         .plugin(
             name: "AWSLambdaPackager",
-            capability: .command(intent: .custom(verb: "archive", description: "Archive the Lambda binary and prepare it for uploading to AWS. Requires docker on macOS."))
+            capability: .command(
+                intent: .custom(
+                    verb: "archive", 
+                    description: "Archive the Lambda binary and prepare it for uploading to AWS. Requires docker on macOS."
+                )
+            )
         ),
         .testTarget(name: "AWSLambdaRuntimeCoreTests", dependencies: [
             .byName(name: "AWSLambdaRuntimeCore"),

Sources/AWSLambdaRuntimeCore/LambdaContext.swift

@@ -43,7 +43,7 @@ public struct LambdaInitializationContext: _AWSLambdaSendable {
     /// `ByteBufferAllocator` to allocate `ByteBuffer`
     public let allocator: ByteBufferAllocator
 
-    /// `Terminator` to register shutdown operations
+    /// ``LambdaTerminator`` to register shutdown operations
     public let terminator: LambdaTerminator
 
     init(logger: Logger, eventLoop: EventLoop, allocator: ByteBufferAllocator, terminator: LambdaTerminator) {

Sources/AWSLambdaRuntimeCore/LambdaHandler.swift

@@ -119,7 +119,7 @@ public protocol EventLoopLambdaHandler: ByteBufferLambdaHandler {
     ///            The `EventLoopFuture` should be completed with either a response of type `Output` or an `Error`
     func handle(_ event: Event, context: LambdaContext) -> EventLoopFuture<Output>
 
-    /// Encode a response of type `Output` to `ByteBuffer`
+    /// Encode a response of type ``Output`` to `ByteBuffer`
     /// Concrete Lambda handlers implement this method to provide coding functionality.
     /// - parameters:
     ///     - allocator: A `ByteBufferAllocator` to help allocate the `ByteBuffer`.
@@ -128,7 +128,7 @@ public protocol EventLoopLambdaHandler: ByteBufferLambdaHandler {
     /// - Returns: A `ByteBuffer` with the encoded version of the `value`.
     func encode(allocator: ByteBufferAllocator, value: Output) throws -> ByteBuffer?
 
-    /// Decode a`ByteBuffer` to a request or event of type `Event`
+    /// Decode a `ByteBuffer` to a request or event of type ``Event``
     /// Concrete Lambda handlers implement this method to provide coding functionality.
     ///
     /// - parameters:
@@ -139,7 +139,7 @@ public protocol EventLoopLambdaHandler: ByteBufferLambdaHandler {
 }
 
 extension EventLoopLambdaHandler {
-    /// Driver for `ByteBuffer` -> `Event` decoding and `Output` -> `ByteBuffer` encoding
+    /// Driver for `ByteBuffer` -> ``Event`` decoding and ``Output`` -> `ByteBuffer` encoding
     @inlinable
     public func handle(_ event: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?> {
         let input: Event
@@ -169,7 +169,8 @@ extension EventLoopLambdaHandler where Output == Void {
 
 // MARK: - ByteBufferLambdaHandler
 
-/// An `EventLoopFuture` based processing protocol for a Lambda that takes a `ByteBuffer` and returns a `ByteBuffer?` asynchronously.
+/// An `EventLoopFuture` based processing protocol for a Lambda that takes a `ByteBuffer` and returns
+/// an optional `ByteBuffer` asynchronously.
 ///
 /// - note: This is a low level protocol designed to power the higher level ``EventLoopLambdaHandler`` and
 ///         ``LambdaHandler`` based APIs.

Sources/AWSLambdaRuntimeCore/LambdaRuntime.swift

@@ -18,7 +18,7 @@ import NIOCore
 
 /// `LambdaRuntime` manages the Lambda process lifecycle.
 ///
-/// - note: It is intended to be used within a single `EventLoop`. For this reason this class is not thread safe.
+/// Use this API, if you build a higher level web framework which shall be able to run inside the Lambda environment.
 public final class LambdaRuntime<Handler: ByteBufferLambdaHandler> {
     private let eventLoop: EventLoop
     private let shutdownPromise: EventLoopPromise<Int>
@@ -35,9 +35,10 @@ public final class LambdaRuntime<Handler: ByteBufferLambdaHandler> {
     /// Create a new `LambdaRuntime`.
     ///
     /// - parameters:
+    ///     - handlerType: The ``ByteBufferLambdaHandler`` type the `LambdaRuntime` shall create and manage
     ///     - eventLoop: An `EventLoop` to run the Lambda on.
     ///     - logger: A `Logger` to log the Lambda events.
-    public convenience init(eventLoop: EventLoop, logger: Logger) {
+    public convenience init(_ handlerType: Handler.Type, eventLoop: EventLoop, logger: Logger) {
         self.init(eventLoop: eventLoop, logger: logger, configuration: .init())
     }
 
@@ -114,8 +115,7 @@ public final class LambdaRuntime<Handler: ByteBufferLambdaHandler> {
 
     // MARK: -  Private
 
-    #if DEBUG
-    /// Begin the `LambdaRuntime` shutdown. Only needed for debugging purposes, hence behind a `DEBUG` flag.
+    /// Begin the `LambdaRuntime` shutdown.
     public func shutdown() {
         // make this method thread safe by dispatching onto the eventloop
         self.eventLoop.execute {
@@ -126,7 +126,6 @@ public final class LambdaRuntime<Handler: ByteBufferLambdaHandler> {
             }
         }
     }
-    #endif
 
     private func markShutdown() {
         self.state = .shutdown

Tests/AWSLambdaRuntimeCoreTests/LambdaRuntimeTest.swift

@@ -29,7 +29,7 @@ class LambdaRuntimeTest: XCTestCase {
 
         let eventLoop = eventLoopGroup.next()
         let logger = Logger(label: "TestLogger")
-        let runtime = LambdaRuntime<StartupErrorHandler>(eventLoop: eventLoop, logger: logger)
+        let runtime = LambdaRuntime(StartupErrorHandler.self, eventLoop: eventLoop, logger: logger)
 
         // eventLoop.submit in this case returns an EventLoopFuture<EventLoopFuture<ByteBufferHandler>>
         // which is why we need `wait().wait()`
@@ -51,7 +51,7 @@ class LambdaRuntimeTest: XCTestCase {
 
         let eventLoop = eventLoopGroup.next()
         let logger = Logger(label: "TestLogger")
-        let runtime = LambdaRuntime<EchoHandler>(eventLoop: eventLoop, logger: logger)
+        let runtime = LambdaRuntime(EchoHandler.self, eventLoop: eventLoop, logger: logger)
 
         XCTAssertNoThrow(_ = try eventLoop.flatSubmit { runtime.start() }.wait())
         XCTAssertThrowsError(_ = try runtime.shutdownFuture.wait()) {
@@ -101,7 +101,7 @@ class LambdaRuntimeTest: XCTestCase {
 
         let eventLoop = eventLoopGroup.next()
         let logger = Logger(label: "TestLogger")
-        let runtime = LambdaRuntime<ShutdownErrorHandler>(eventLoop: eventLoop, logger: logger)
+        let runtime = LambdaRuntime(ShutdownErrorHandler.self, eventLoop: eventLoop, logger: logger)
 
         XCTAssertNoThrow(try eventLoop.flatSubmit { runtime.start() }.wait())
         XCTAssertThrowsError(try runtime.shutdownFuture.wait()) { error in

docker/Dockerfile

@@ -1,5 +1,4 @@
-ARG swift_version=5.2
-# FIXME when 5.2 images are available
+ARG swift_version=5.4
 ARG base_image=swift:$swift_version-amazonlinux2
 FROM $base_image
 # needed to do again after FROM due to docker limitation

docker/Dockerfile.ubuntu

@@ -17,7 +17,7 @@ If you have never used AWS Lambda or Docker before, check out this [getting star
 First, create a SwiftPM project and pull Swift AWS Lambda Runtime as dependency into your project
 
  ```swift
- // swift-tools-version:5.2
+ // swift-tools-version:5.6
 
  import PackageDescription
 
@@ -80,7 +80,7 @@ Next, create a `main.swift` and implement your Lambda.
 First, add a dependency on the event packages:
 
  ```swift
- // swift-tools-version:5.2
+ // swift-tools-version:5.6
 
  import PackageDescription