wip

Author: tomerd

Sources/AWSLambdaRuntime/Lambda+Codable.swift

@@ -19,7 +19,47 @@ import class Foundation.JSONEncoder
 import NIOCore
 import NIOFoundationCompat
 
-// MARK: - Codable support
+// MARK: - LambdaHandler Codable support
+
+#if compiler(>=5.5) && canImport(_Concurrency)
+/// Implementation of  a`ByteBuffer` to `Event` decoding.
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Event: Decodable {
+    @inlinable
+    public func decode(buffer: ByteBuffer) throws -> Event {
+        try self.decoder.decode(Event.self, from: buffer)
+    }
+}
+
+/// Implementation of  `Output` to `ByteBuffer` encoding.
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Output: Encodable {
+    @inlinable
+    public func encode(allocator: ByteBufferAllocator, value: Output) throws -> ByteBuffer? {
+        try self.encoder.encode(value, using: allocator)
+    }
+}
+
+/// Default `ByteBuffer` to `Event` decoder using Foundation's `JSONDecoder`.
+/// Advanced users that want to inject their own codec can do it by overriding these functions.
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Event: Decodable {
+    public var decoder: LambdaCodableDecoder {
+        Lambda.defaultJSONDecoder
+    }
+}
+
+/// Default `Output` to `ByteBuffer` encoder using Foundation's `JSONEncoder`.
+/// Advanced users that want to inject their own codec can do it by overriding these functions.
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Output: Encodable {
+    public var encoder: LambdaCodableEncoder {
+        Lambda.defaultJSONEncoder
+    }
+}
+#endif
+
+// MARK: - EventLoopLambdaHandler Codable support
 
 /// Implementation of  a`ByteBuffer` to `Event` decoding.
 extension EventLoopLambdaHandler where Event: Decodable {

Sources/AWSLambdaRuntimeCore/Lambda.swift

@@ -33,9 +33,32 @@ public enum Lambda {
     ///     - handlerType: The Handler to create and invoke.
     ///
     /// - note: This is a blocking operation that will run forever, as its lifecycle is managed by the AWS Lambda Runtime Engine.
+
     internal static func run<Handler: ByteBufferLambdaHandler>(
         configuration: LambdaConfiguration = .init(),
         handlerType: Handler.Type
+    ) -> Result<Int, Error> {
+        Self.run(configuration: configuration, initializationHandler: Handler.makeHandler(context:))
+    }
+
+    internal static func run<Handler: EventLoopLambdaHandler>(
+        configuration: LambdaConfiguration = .init(),
+        handlerType: Handler.Type
+    ) -> Result<Int, Error> {
+        Self.run(configuration: configuration, initializationHandler: Handler.makeHandler(context:))
+    }
+
+    @available(macOS 12, *)
+    internal static func run<Handler: LambdaHandler>(
+        configuration: LambdaConfiguration = .init(),
+        handlerType: Handler.Type
+    ) -> Result<Int, Error> {
+        Self.run(configuration: configuration, initializationHandler: Handler.makeHandler(context:))
+
+    }
+    private static func run(
+        configuration: LambdaConfiguration = .init(),
+        initializationHandler: @escaping (LambdaInitializationContext) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>>
     ) -> Result<Int, Error> {
         let _run = { (configuration: LambdaConfiguration) -> Result<Int, Error> in
             Backtrace.install()
@@ -44,7 +67,7 @@ public enum Lambda {
 
             var result: Result<Int, Error>!
             MultiThreadedEventLoopGroup.withCurrentThreadAsEventLoop { eventLoop in
-                let runtime = LambdaRuntime<Handler>(eventLoop: eventLoop, logger: logger, configuration: configuration)
+                let runtime = LambdaRuntime(eventLoop: eventLoop, logger: logger, configuration: configuration, initializationHandler: initializationHandler)
                 #if DEBUG
                 let signalSource = trap(signal: configuration.lifecycle.stopSignal) { signal in
                     logger.info("intercepted signal: \(signal)")

Sources/AWSLambdaRuntimeCore/LambdaHandler.swift

@@ -26,7 +26,14 @@ import NIOCore
 ///         level protocols ``EventLoopLambdaHandler`` and
 ///         ``ByteBufferLambdaHandler``.
 @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
-public protocol LambdaHandler: EventLoopLambdaHandler {
+public protocol LambdaHandler {
+    /// The lambda functions input. In most cases this should be `Codable`. If your event originates from an
+    /// AWS service, have a look at [AWSLambdaEvents](https://github.com/swift-server/swift-aws-lambda-events),
+    /// which provides a number of commonly used AWS Event implementations.
+    associatedtype Event
+    /// The lambda functions output. Can be `Void`.
+    associatedtype Output
+
     /// The Lambda initialization method.
     /// Use this method to initialize resources that will be used in every request.
     ///
@@ -44,18 +51,38 @@ public protocol LambdaHandler: EventLoopLambdaHandler {
     ///
     /// - Returns: A Lambda result ot type `Output`.
     func handle(_ event: Event, context: LambdaContext) async throws -> Output
+
+    /// 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`.
+    ///     - value: Response of type ``Output``.
+    ///
+    /// - 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``.
+    /// Concrete Lambda handlers implement this method to provide coding functionality.
+    ///
+    /// - parameters:
+    ///     - buffer: The `ByteBuffer` to decode.
+    ///
+    /// - Returns: A request or event of type ``Event``.
+    func decode(buffer: ByteBuffer) throws -> Event
 }
 
 @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
 extension LambdaHandler {
-    public static func makeHandler(context: LambdaInitializationContext) -> EventLoopFuture<Self> {
+    // FIXME: why public?
+    public static func makeHandler(context: LambdaInitializationContext) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>> {
         let promise = context.eventLoop.makePromise(of: Self.self)
         promise.completeWithTask {
             try await Self(context: context)
         }
-        return promise.futureResult
+        return promise.futureResult.map{ $0.handle(buffer:context:) }
     }
 
+    // FIXME: why public?
     public func handle(_ event: Event, context: LambdaContext) -> EventLoopFuture<Output> {
         let promise = context.eventLoop.makePromise(of: Output.self)
         // using an unchecked sendable wrapper for the handler
@@ -66,6 +93,68 @@ extension LambdaHandler {
         }
         return promise.futureResult
     }
+
+    /// Driver for `ByteBuffer` -> ``Event`` decoding and ``Output`` -> `ByteBuffer` encoding
+    @inlinable
+    internal func handle(buffer: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?> {
+        let input: Event
+        do {
+            input = try self.decode(buffer: buffer)
+        } catch {
+            return context.eventLoop.makeFailedFuture(CodecError.requestDecoding(error))
+        }
+
+        return self.handle(input, context: context).flatMapThrowing { output in
+            do {
+                return try self.encode(allocator: context.allocator, value: output)
+            } catch {
+                throw CodecError.responseEncoding(error)
+            }
+        }
+    }
+}
+
+/// Implementation of  `ByteBuffer` to `Void` decoding.
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Output == Void {
+    @inlinable
+    public func encode(allocator: ByteBufferAllocator, value: Void) throws -> ByteBuffer? {
+        nil
+    }
+}
+
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Event == String {
+    @inlinable
+    public func decode(buffer: ByteBuffer) throws -> String {
+        guard let value = buffer.getString(at: buffer.readerIndex, length: buffer.readableBytes) else {
+            throw CodecError.invalidString
+        }
+        return value
+    }
+}
+
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler where Output == String {
+    @inlinable
+    public func encode(allocator: ByteBufferAllocator, value: String) throws -> ByteBuffer? {
+        allocator.buffer(string: value)
+    }
+}
+
+@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
+extension LambdaHandler {
+    /// Initializes and runs the Lambda function.
+    ///
+    /// If you precede your ``ByteBufferLambdaHandler`` conformer's declaration with the
+    /// [@main](https://docs.swift.org/swift-book/ReferenceManual/Attributes.html#ID626)
+    /// attribute, the system calls the conformer's `main()` method to launch the lambda function.
+    ///
+    /// The lambda runtime provides a default implementation of the method that manages the launch
+    /// process.
+    public static func main() {
+        _ = Lambda.run(configuration: .init(), handlerType: Self.self)
+    }
 }
 
 /// unchecked sendable wrapper for the handler
@@ -100,14 +189,22 @@ fileprivate struct UncheckedSendableHandler<Underlying: LambdaHandler, Event, Ou
 ///         as the core runtime engine, making the processing faster but requires more care from the
 ///         implementation to never block the `EventLoop`. Implement this protocol only in performance
 ///         critical situations and implement ``LambdaHandler`` in all other circumstances.
-public protocol EventLoopLambdaHandler: ByteBufferLambdaHandler {
+public protocol EventLoopLambdaHandler {
     /// The lambda functions input. In most cases this should be `Codable`. If your event originates from an
     /// AWS service, have a look at [AWSLambdaEvents](https://github.com/swift-server/swift-aws-lambda-events),
     /// which provides a number of commonly used AWS Event implementations.
     associatedtype Event
     /// The lambda functions output. Can be `Void`.
     associatedtype Output
 
+    /// Create a Lambda handler for the runtime.
+    ///
+    /// Use this to initialize all your resources that you want to cache between invocations. This could be database
+    /// connections and HTTP clients for example. It is encouraged to use the given `EventLoop`'s conformance
+    /// to `EventLoopGroup` when initializing NIO dependencies. This will improve overall performance, as it
+    /// minimizes thread hopping.
+    static func makeHandler(context: LambdaInitializationContext) -> EventLoopFuture<Self>
+
     /// The Lambda handling method.
     /// Concrete Lambda handlers implement this method to provide the Lambda functionality.
     ///
@@ -139,12 +236,17 @@ public protocol EventLoopLambdaHandler: ByteBufferLambdaHandler {
 }
 
 extension EventLoopLambdaHandler {
+    @inlinable
+    internal static func makeHandler(context: LambdaInitializationContext) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>> {
+        Self.makeHandler(context: context).map{ $0.handle(buffer:context:) }
+    }
+
     /// Driver for `ByteBuffer` -> ``Event`` decoding and ``Output`` -> `ByteBuffer` encoding
     @inlinable
-    public func handle(_ event: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?> {
+    internal func handle(buffer: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?> {
         let input: Event
         do {
-            input = try self.decode(buffer: event)
+            input = try self.decode(buffer: buffer)
         } catch {
             return context.eventLoop.makeFailedFuture(CodecError.requestDecoding(error))
         }
@@ -167,6 +269,20 @@ extension EventLoopLambdaHandler where Output == Void {
     }
 }
 
+extension EventLoopLambdaHandler {
+    /// Initializes and runs the Lambda function.
+    ///
+    /// If you precede your ``ByteBufferLambdaHandler`` conformer's declaration with the
+    /// [@main](https://docs.swift.org/swift-book/ReferenceManual/Attributes.html#ID626)
+    /// attribute, the system calls the conformer's `main()` method to launch the lambda function.
+    ///
+    /// The lambda runtime provides a default implementation of the method that manages the launch
+    /// process.
+    public static func main() {
+        _ = Lambda.run(configuration: .init(), handlerType: Self.self)
+    }
+}
+
 // MARK: - ByteBufferLambdaHandler
 
 /// An `EventLoopFuture` based processing protocol for a Lambda that takes a `ByteBuffer` and returns
@@ -176,7 +292,7 @@ extension EventLoopLambdaHandler where Output == Void {
 ///         ``LambdaHandler`` based APIs.
 ///         Most users are not expected to use this protocol.
 public protocol ByteBufferLambdaHandler {
-    /// Create your Lambda handler for the runtime.
+    /// Create a Lambda handler for the runtime.
     ///
     /// Use this to initialize all your resources that you want to cache between invocations. This could be database
     /// connections and HTTP clients for example. It is encouraged to use the given `EventLoop`'s conformance
@@ -193,7 +309,14 @@ public protocol ByteBufferLambdaHandler {
     ///
     /// - Returns: An `EventLoopFuture` to report the result of the Lambda back to the runtime engine.
     ///            The `EventLoopFuture` should be completed with either a response encoded as `ByteBuffer` or an `Error`.
-    func handle(_ event: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?>
+    func handle(_ buffer: ByteBuffer, context: LambdaContext) -> EventLoopFuture<ByteBuffer?>
+}
+
+extension ByteBufferLambdaHandler {
+    @inlinable
+    internal static func makeHandler(context: LambdaInitializationContext) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>> {
+        Self.makeHandler(context: context).map{ $0.handle(_:context:)}
+    }
 }
 
 extension ByteBufferLambdaHandler {
@@ -210,8 +333,12 @@ extension ByteBufferLambdaHandler {
     }
 }
 
+// MARK: - Other
+
 @usableFromInline
 enum CodecError: Error {
     case requestDecoding(Error)
     case responseEncoding(Error)
+    case invalidString
 }
+

Sources/AWSLambdaRuntimeCore/LambdaRunner.swift

@@ -33,7 +33,7 @@ internal final class LambdaRunner {
     /// Run the user provided initializer. This *must* only be called once.
     ///
     /// - Returns: An `EventLoopFuture<LambdaHandler>` fulfilled with the outcome of the initialization.
-    func initialize<Handler: ByteBufferLambdaHandler>(logger: Logger, terminator: LambdaTerminator, handlerType: Handler.Type) -> EventLoopFuture<Handler> {
+    func initialize(logger: Logger, terminator: LambdaTerminator, initializationHandler: (LambdaInitializationContext) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>>) -> EventLoopFuture<(ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>> {
         logger.debug("initializing lambda")
         // 1. create the handler from the factory
         // 2. report initialization error if one occurred
@@ -43,7 +43,7 @@ internal final class LambdaRunner {
             allocator: self.allocator,
             terminator: terminator
         )
-        return Handler.makeHandler(context: context)
+        return initializationHandler(context)
             // Hopping back to "our" EventLoop is important in case the factory returns a future
             // that originated from a foreign EventLoop/EventLoopGroup.
             // This can happen if the factory uses a library (let's say a database client) that manages its own threads/loops
@@ -58,7 +58,7 @@ internal final class LambdaRunner {
             }
     }
 
-    func run<Handler: ByteBufferLambdaHandler>(logger: Logger, handler: Handler) -> EventLoopFuture<Void> {
+    func run(logger: Logger, handler: @escaping (ByteBuffer, LambdaContext) -> EventLoopFuture<ByteBuffer?>) -> EventLoopFuture<Void> {
         logger.debug("lambda invocation sequence starting")
         // 1. request invocation from lambda runtime engine
         self.isGettingNextInvocation = true
@@ -73,8 +73,8 @@ internal final class LambdaRunner {
                 allocator: self.allocator,
                 invocation: invocation
             )
-            logger.debug("sending invocation to lambda handler \(handler)")
-            return handler.handle(bytes, context: context)
+            logger.debug("sending invocation to lambda handler")
+            return handler(bytes, context)
                 // Hopping back to "our" EventLoop is important in case the handler returns a future that
                 // originiated from a foreign EventLoop/EventLoopGroup.
                 // This can happen if the handler uses a library (lets say a DB client) that manages its own threads/loops