Lambda factory as a protocol requirement. (#244)

Author: fabianfett

Examples/Benchmark/main.swift renamed to Examples/Benchmark/BenchmarkHandler.swift

@@ -20,13 +20,16 @@ import NIOCore
 // `EventLoopLambdaHandler` does not offload the Lambda processing to a separate thread
 // while the closure-based handlers do.
 
-struct MyLambda: EventLoopLambdaHandler {
+@main
+struct BenchmarkHandler: EventLoopLambdaHandler {
     typealias Event = String
     typealias Output = String
 
+    static func makeHandler(context: Lambda.InitializationContext) -> EventLoopFuture<Self> {
+        context.eventLoop.makeSucceededFuture(BenchmarkHandler())
+    }
+
     func handle(_ event: String, context: LambdaContext) -> EventLoopFuture<String> {
         context.eventLoop.makeSucceededFuture("hello, world!")
     }
 }
-
-Lambda.run { $0.eventLoop.makeSucceededFuture(MyLambda()) }

Examples/Deployment/Sources/Benchmark/main.swift renamed to Examples/Deployment/Sources/Benchmark/BenchmarkHandler.swift

@@ -20,13 +20,16 @@ import NIO
 // `EventLoopLambdaHandler` does not offload the Lambda processing to a separate thread
 // while the closure-based handlers do.
 
+@main
 struct BenchmarkHandler: EventLoopLambdaHandler {
     typealias Event = String
     typealias Output = String
 
+    static func makeHandler(context: Lambda.InitializationContext) -> EventLoopFuture<Self> {
+        context.eventLoop.makeSucceededFuture(BenchmarkHandler())
+    }
+
     func handle(_ event: String, context: LambdaContext) -> EventLoopFuture<String> {
         context.eventLoop.makeSucceededFuture("hello, world!")
     }
 }
-
-Lambda.run { $0.eventLoop.makeSucceededFuture(BenchmarkHandler()) }

Sources/AWSLambdaRuntimeCore/Lambda.swift

@@ -24,27 +24,6 @@ import NIOCore
 import NIOPosix
 
 public enum Lambda {
-    public typealias Handler = ByteBufferLambdaHandler
-
-    /// `ByteBufferLambdaHandler` factory.
-    ///
-    /// A function that takes a `InitializationContext` and returns an `EventLoopFuture` of a `ByteBufferLambdaHandler`
-    public typealias HandlerFactory = (InitializationContext) -> EventLoopFuture<Handler>
-
-    /// Run a Lambda defined by implementing the `LambdaHandler` protocol provided via a `LambdaHandlerFactory`.
-    /// 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.
-    ///
-    /// - parameters:
-    ///     - factory: A `ByteBufferLambdaHandler` factory.
-    ///
-    /// - note: This is a blocking operation that will run forever, as its lifecycle is managed by the AWS Lambda Runtime Engine.
-    public static func run(_ factory: @escaping HandlerFactory) {
-        if case .failure(let error) = self.run(factory: factory) {
-            fatalError("\(error)")
-        }
-    }
-
     /// Utility to access/read environment variables
     public static func env(_ name: String) -> String? {
         guard let value = getenv(name) else {
@@ -53,30 +32,27 @@ public enum Lambda {
         return String(cString: value)
     }
 
-    #if compiler(>=5.5) && canImport(_Concurrency)
-    // for testing and internal use
-    @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
-    internal static func run<Handler: LambdaHandler>(configuration: Configuration = .init(), handlerType: Handler.Type) -> Result<Int, Error> {
-        self.run(configuration: configuration, factory: { context -> EventLoopFuture<ByteBufferLambdaHandler> in
-            let promise = context.eventLoop.makePromise(of: ByteBufferLambdaHandler.self)
-            promise.completeWithTask {
-                try await Handler(context: context)
-            }
-            return promise.futureResult
-        })
-    }
-    #endif
-
-    // for testing and internal use
-    internal static func run(configuration: Configuration = .init(), factory: @escaping HandlerFactory) -> Result<Int, Error> {
-        let _run = { (configuration: Configuration, factory: @escaping HandlerFactory) -> Result<Int, Error> in
+    /// Run a Lambda defined by implementing the ``ByteBufferLambdaHandler`` protocol.
+    /// The Runtime will manage the Lambdas application lifecycle automatically. It will invoke the
+    /// ``ByteBufferLambdaHandler/makeHandler(context:)`` to create a new Handler.
+    ///
+    /// - parameters:
+    ///     - configuration: A Lambda runtime configuration object
+    ///     - 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: Configuration = .init(),
+        handlerType: Handler.Type
+    ) -> Result<Int, Error> {
+        let _run = { (configuration: Configuration) -> Result<Int, Error> in
             Backtrace.install()
             var logger = Logger(label: "Lambda")
             logger.logLevel = configuration.general.logLevel
 
             var result: Result<Int, Error>!
             MultiThreadedEventLoopGroup.withCurrentThreadAsEventLoop { eventLoop in
-                let runtime = LambdaRuntime(eventLoop: eventLoop, logger: logger, configuration: configuration, factory: factory)
+                let runtime = LambdaRuntime<Handler>(eventLoop: eventLoop, logger: logger, configuration: configuration)
                 #if DEBUG
                 let signalSource = trap(signal: configuration.lifecycle.stopSignal) { signal in
                     logger.info("intercepted signal: \(signal)")
@@ -108,16 +84,16 @@ public enum Lambda {
         if Lambda.env("LOCAL_LAMBDA_SERVER_ENABLED").flatMap(Bool.init) ?? false {
             do {
                 return try Lambda.withLocalServer {
-                    _run(configuration, factory)
+                    _run(configuration)
                 }
             } catch {
                 return .failure(error)
             }
         } else {
-            return _run(configuration, factory)
+            return _run(configuration)
         }
         #else
-        return _run(configuration, factory)
+        return _run(configuration)
         #endif
     }
 }

Sources/AWSLambdaRuntimeCore/LambdaContext.swift

@@ -20,7 +20,9 @@ import NIOCore
 
 extension Lambda {
     /// Lambda runtime initialization context.
-    /// The Lambda runtime generates and passes the `InitializationContext` to the Lambda factory as an argument.
+    /// The Lambda runtime generates and passes the `InitializationContext` to the Handlers
+    /// ``ByteBufferLambdaHandler/makeHandler(context:)`` or ``LambdaHandler/init(context:)``
+    /// as an argument.
     public struct InitializationContext {
         /// `Logger` to log with
         ///

Sources/AWSLambdaRuntimeCore/LambdaHandler.swift

@@ -18,7 +18,13 @@ import NIOCore
 // MARK: - LambdaHandler
 
 #if compiler(>=5.5) && canImport(_Concurrency)
-/// Strongly typed, processing protocol for a Lambda that takes a user defined `Event` and returns a user defined `Output` async.
+/// Strongly typed, processing protocol for a Lambda that takes a user defined
+/// ``EventLoopLambdaHandler/Event`` and returns a user defined
+/// ``EventLoopLambdaHandler/Output`` asynchronously.
+///
+/// - note: Most users should implement this protocol instead of the lower
+///         level protocols ``EventLoopLambdaHandler`` and
+///         ``ByteBufferLambdaHandler``.
 @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
 public protocol LambdaHandler: EventLoopLambdaHandler {
     /// The Lambda initialization method
@@ -42,6 +48,14 @@ public protocol LambdaHandler: EventLoopLambdaHandler {
 
 @available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
 extension LambdaHandler {
+    public static func makeHandler(context: Lambda.InitializationContext) -> EventLoopFuture<Self> {
+        let promise = context.eventLoop.makePromise(of: Self.self)
+        promise.completeWithTask {
+            try await Self(context: context)
+        }
+        return promise.futureResult
+    }
+
     public func handle(_ event: Event, context: LambdaContext) -> EventLoopFuture<Output> {
         let promise = context.eventLoop.makePromise(of: Output.self)
         promise.completeWithTask {
@@ -51,25 +65,30 @@ extension LambdaHandler {
     }
 }
 
-@available(macOS 12, iOS 15, tvOS 15, watchOS 8, *)
-extension LambdaHandler {
-    public static func main() {
-        _ = Lambda.run(handlerType: Self.self)
-    }
-}
 #endif
 
 // MARK: - EventLoopLambdaHandler
 
-/// Strongly typed, `EventLoopFuture` based processing protocol for a Lambda that takes a user defined `Event` and returns a user defined `Output` asynchronously.
-/// `EventLoopLambdaHandler` extends `ByteBufferLambdaHandler`, performing `ByteBuffer` -> `Event` decoding and `Output` -> `ByteBuffer` encoding.
+/// Strongly typed, `EventLoopFuture` based processing protocol for a Lambda that takes a user
+/// defined ``Event`` and returns a user defined ``Output`` asynchronously.
 ///
-/// - note: To implement a Lambda, implement either `LambdaHandler` or the `EventLoopLambdaHandler` protocol.
-///         The `LambdaHandler` will offload the Lambda execution to a `DispatchQueue` making processing safer but slower
-///         The `EventLoopLambdaHandler` will execute the Lambda on the same `EventLoop` as the core runtime engine, making the processing faster but requires
-///         more care from the implementation to never block the `EventLoop`.
+/// ``EventLoopLambdaHandler`` extends ``ByteBufferLambdaHandler``, performing
+/// `ByteBuffer` -> ``Event`` decoding and ``Output`` -> `ByteBuffer` encoding.
+///
+/// - note: To implement a Lambda, implement either ``LambdaHandler`` or the
+///         ``EventLoopLambdaHandler`` protocol. The ``LambdaHandler`` will offload
+///         the Lambda execution to an async Task making processing safer but slower (due to
+///         fewer thread hops).
+///         The ``EventLoopLambdaHandler`` will execute the Lambda on the same `EventLoop`
+///         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 {
+    /// 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 handling method
@@ -135,9 +154,18 @@ extension EventLoopLambdaHandler where Output == Void {
 
 /// An `EventLoopFuture` based processing protocol for a Lambda that takes a `ByteBuffer` and returns a `ByteBuffer?` asynchronously.
 ///
-/// - note: This is a low level protocol designed to power the higher level `EventLoopLambdaHandler` and `LambdaHandler` based APIs.
+/// - note: This is a low level protocol designed to power the higher level ``EventLoopLambdaHandler`` and
+///         ``LambdaHandler`` based APIs.
 ///         Most users are not expected to use this protocol.
 public protocol ByteBufferLambdaHandler {
+    /// Create your 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: Lambda.InitializationContext) -> EventLoopFuture<Self>
+
     /// The Lambda handling method
     /// Concrete Lambda handlers implement this method to provide the Lambda functionality.
     ///
@@ -163,6 +191,20 @@ extension ByteBufferLambdaHandler {
     }
 }
 
+extension ByteBufferLambdaHandler {
+    /// 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)
+    }
+}
+
 @usableFromInline
 enum CodecError: Error {
     case requestDecoding(Error)

Sources/AWSLambdaRuntimeCore/LambdaRunner.swift

@@ -34,14 +34,14 @@ extension Lambda {
         /// Run the user provided initializer. This *must* only be called once.
         ///
         /// - Returns: An `EventLoopFuture<LambdaHandler>` fulfilled with the outcome of the initialization.
-        func initialize(logger: Logger, factory: @escaping HandlerFactory) -> EventLoopFuture<Handler> {
+        func initialize<Handler: ByteBufferLambdaHandler>(logger: Logger, handlerType: Handler.Type) -> EventLoopFuture<Handler> {
             logger.debug("initializing lambda")
             // 1. create the handler from the factory
             // 2. report initialization error if one occured
             let context = InitializationContext(logger: logger,
                                                 eventLoop: self.eventLoop,
                                                 allocator: self.allocator)
-            return factory(context)
+            return Handler.makeHandler(context: 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
@@ -56,7 +56,7 @@ extension Lambda {
                 }
         }
 
-        func run(logger: Logger, handler: Handler) -> EventLoopFuture<Void> {
+        func run<Handler: ByteBufferLambdaHandler>(logger: Logger, handler: Handler) -> EventLoopFuture<Void> {
             logger.debug("lambda invocation sequence starting")
             // 1. request invocation from lambda runtime engine
             self.isGettingNextInvocation = true

Sources/AWSLambdaRuntimeCore/LambdaRuntime.swift

@@ -19,12 +19,11 @@ 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.
-public final class LambdaRuntime {
+public final class LambdaRuntime<Handler: ByteBufferLambdaHandler> {
     private let eventLoop: EventLoop
     private let shutdownPromise: EventLoopPromise<Int>
     private let logger: Logger
     private let configuration: Lambda.Configuration
-    private let factory: Lambda.HandlerFactory
 
     private var state = State.idle {
         willSet {
@@ -38,17 +37,15 @@ public final class LambdaRuntime {
     /// - parameters:
     ///     - eventLoop: An `EventLoop` to run the Lambda on.
     ///     - logger: A `Logger` to log the Lambda events.
-    ///     - factory: A `LambdaHandlerFactory` to create the concrete  Lambda handler.
-    public convenience init(eventLoop: EventLoop, logger: Logger, factory: @escaping Lambda.HandlerFactory) {
-        self.init(eventLoop: eventLoop, logger: logger, configuration: .init(), factory: factory)
+    public convenience init(eventLoop: EventLoop, logger: Logger) {
+        self.init(eventLoop: eventLoop, logger: logger, configuration: .init())
     }
 
-    init(eventLoop: EventLoop, logger: Logger, configuration: Lambda.Configuration, factory: @escaping Lambda.HandlerFactory) {
+    init(eventLoop: EventLoop, logger: Logger, configuration: Lambda.Configuration) {
         self.eventLoop = eventLoop
         self.shutdownPromise = eventLoop.makePromise(of: Int.self)
         self.logger = logger
         self.configuration = configuration
-        self.factory = factory
     }
 
     deinit {
@@ -79,16 +76,16 @@ public final class LambdaRuntime {
         logger[metadataKey: "lifecycleId"] = .string(self.configuration.lifecycle.id)
         let runner = Lambda.Runner(eventLoop: self.eventLoop, configuration: self.configuration)
 
-        let startupFuture = runner.initialize(logger: logger, factory: self.factory)
-        startupFuture.flatMap { handler -> EventLoopFuture<(ByteBufferLambdaHandler, Result<Int, Error>)> in
+        let startupFuture = runner.initialize(logger: logger, handlerType: Handler.self)
+        startupFuture.flatMap { handler -> EventLoopFuture<(Handler, Result<Int, Error>)> in
             // after the startup future has succeeded, we have a handler that we can use
             // to `run` the lambda.
             let finishedPromise = self.eventLoop.makePromise(of: Int.self)
             self.state = .active(runner, handler)
             self.run(promise: finishedPromise)
             return finishedPromise.futureResult.mapResult { (handler, $0) }
         }
-        .flatMap { (handler, runnerResult) -> EventLoopFuture<Int> in
+        .flatMap { handler, runnerResult -> EventLoopFuture<Int> in
             // after the lambda finishPromise has succeeded or failed we need to
             // shutdown the handler
             let shutdownContext = Lambda.ShutdownContext(logger: logger, eventLoop: self.eventLoop)
@@ -97,7 +94,7 @@ public final class LambdaRuntime {
                 // the runner result
                 logger.error("Error shutting down handler: \(error)")
                 throw Lambda.RuntimeError.shutdownError(shutdownError: error, runnerResult: runnerResult)
-            }.flatMapResult { (_) -> Result<Int, Error> in
+            }.flatMapResult { _ -> Result<Int, Error> in
                 // we had no error shutting down the lambda. let's return the runner's result
                 runnerResult
             }
@@ -173,7 +170,7 @@ public final class LambdaRuntime {
     private enum State {
         case idle
         case initializing
-        case active(Lambda.Runner, Lambda.Handler)
+        case active(Lambda.Runner, Handler)
         case shuttingdown
         case shutdown