add initialization context

Sources/AWSLambdaRuntimeCore/Lambda.swift

@@ -27,8 +27,8 @@ public enum Lambda {
 
     /// `ByteBufferLambdaHandler` factory.
     ///
-    /// A function that takes a `EventLoop` and returns an `EventLoopFuture` of a `ByteBufferLambdaHandler`
-    public typealias HandlerFactory = (EventLoop) -> EventLoopFuture<Handler>
+    /// 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.
     ///
@@ -58,7 +58,7 @@ public enum Lambda {
     ///     - 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 (EventLoop) throws -> Handler) {
+    public static func run(_ factory: @escaping (InitializationContext) throws -> Handler) {
         self.run(factory: factory)
     }
 
@@ -73,19 +73,19 @@ public enum Lambda {
     // for testing and internal use
     @discardableResult
     internal static func run(configuration: Configuration = .init(), handler: Handler) -> Result<Int, Error> {
-        self.run(configuration: configuration, factory: { $0.makeSucceededFuture(handler) })
+        self.run(configuration: configuration, factory: { $0.eventLoop.makeSucceededFuture(handler) })
     }
 
     // for testing and internal use
     @discardableResult
-    internal static func run(configuration: Configuration = .init(), factory: @escaping (EventLoop) throws -> Handler) -> Result<Int, Error> {
-        self.run(configuration: configuration, factory: { eventloop -> EventLoopFuture<Handler> in
-            let promise = eventloop.makePromise(of: Handler.self)
+    internal static func run(configuration: Configuration = .init(), factory: @escaping (InitializationContext) throws -> Handler) -> Result<Int, Error> {
+        self.run(configuration: configuration, factory: { context -> EventLoopFuture<Handler> in
+            let promise = context.eventLoop.makePromise(of: Handler.self)
             // if we have a callback based handler factory, we offload the creation of the handler
             // onto the default offload queue, to ensure that the eventloop is never blocked.
             Lambda.defaultOffloadQueue.async {
                 do {
-                    promise.succeed(try factory(eventloop))
+                    promise.succeed(try factory(context))
                 } catch {
                     promise.fail(error)
                 }

Sources/AWSLambdaRuntimeCore/LambdaContext.swift

@@ -16,6 +16,33 @@ import Dispatch
 import Logging
 import NIO
 
+// MARK: - InitializationContext
+
+extension Lambda {
+    /// Lambda runtime initialization context.
+    /// The Lambda runtime generates and passes the `InitializationContext` to the Lambda handler as an argument.
+    public final class InitializationContext {
+        /// `Logger` to log with
+        ///
+        /// - note: The `LogLevel` can be configured using the `LOG_LEVEL` environment variable.
+        public let logger: Logger
+
+        /// The `EventLoop` the Lambda is executed on. Use this to schedule work with.
+        /// This is useful when implementing the `EventLoopLambdaHandler` protocol.
+        ///
+        /// - note: The `EventLoop` is shared with the Lambda runtime engine and should be handled with extra care.
+        ///         Most importantly the `EventLoop` must never be blocked.
+        public let eventLoop: EventLoop
+
+        internal init(logger: Logger, eventLoop: EventLoop) {
+            self.eventLoop = eventLoop
+            self.logger = logger
+        }
+    }
+}
+
+// MARK: - Context
+
 extension Lambda {
     /// Lambda runtime context.
     /// The Lambda runtime generates and passes the `Context` to the Lambda handler as an argument.

Sources/AWSLambdaRuntimeCore/LambdaRunner.swift

@@ -36,13 +36,20 @@ extension Lambda {
             logger.debug("initializing lambda")
             // 1. create the handler from the factory
             // 2. report initialization error if one occured
-            return factory(self.eventLoop).hop(to: self.eventLoop).peekError { error in
-                self.runtimeClient.reportInitializationError(logger: logger, error: error).peekError { reportingError in
-                    // We're going to bail out because the init failed, so there's not a lot we can do other than log
-                    // that we couldn't report this error back to the runtime.
-                    logger.error("failed reporting initialization error to lambda runtime engine: \(reportingError)")
+            let context = InitializationContext(logger: logger, eventLoop: self.eventLoop)
+            return factory(context)
+                // Hopping back to "our" EventLoop is importnant in case the factory returns a future
+                // that originiated from a foreign EventLoop/EventLoopGroup.
+                // This can happen if the factory uses a library (lets say a DB client) that manages its own threads/loops
+                // for whatever reason and returns a future that originated from that foreign EventLoop.
+                .hop(to: self.eventLoop)
+                .peekError { error in
+                    self.runtimeClient.reportInitializationError(logger: logger, error: error).peekError { reportingError in
+                        // We're going to bail out because the init failed, so there's not a lot we can do other than log
+                        // that we couldn't report this error back to the runtime.
+                        logger.error("failed reporting initialization error to lambda runtime engine: \(reportingError)")
+                    }
                 }
-            }
         }
 
         func run(logger: Logger, handler: Handler) -> EventLoopFuture<Void> {
@@ -57,6 +64,11 @@ extension Lambda {
                 let context = Context(logger: logger, eventLoop: self.eventLoop, invocation: invocation)
                 logger.debug("sending invocation to lambda handler \(handler)")
                 return handler.handle(context: context, event: event)
+                    // Hopping back to "our" EventLoop is importnant 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
+                    // for whatever reason and returns a future that originated from that foreign EventLoop.
+                    .hop(to: self.eventLoop)
                     .mapResult { result in
                         if case .failure(let error) = result {
                             logger.warning("lambda handler returned an error: \(error)")

Tests/AWSLambdaRuntimeCoreTests/Lambda+StringTest.swift

@@ -185,7 +185,7 @@ class StringLambdaTest: XCTestCase {
             typealias In = String
             typealias Out = String
 
-            init(eventLoop: EventLoop) throws {
+            init(context: Lambda.InitializationContext) throws {
                 throw TestError("kaboom")
             }
 

Tests/AWSLambdaRuntimeCoreTests/LambdaRuntimeClientTest.swift

@@ -30,7 +30,7 @@ class LambdaRuntimeClientTest: XCTestCase {
 
     func testBootstrapFailure() {
         let behavior = Behavior()
-        XCTAssertThrowsError(try runLambda(behavior: behavior, factory: { $0.makeFailedFuture(TestError("boom")) })) { error in
+        XCTAssertThrowsError(try runLambda(behavior: behavior, factory: { $0.eventLoop.makeFailedFuture(TestError("boom")) })) { error in
             XCTAssertEqual(error as? TestError, TestError("boom"))
         }
         XCTAssertEqual(behavior.state, 1)
@@ -186,7 +186,7 @@ class LambdaRuntimeClientTest: XCTestCase {
                 .failure(.internalServerError)
             }
         }
-        XCTAssertThrowsError(try runLambda(behavior: Behavior(), factory: { $0.makeFailedFuture(TestError("boom")) })) { error in
+        XCTAssertThrowsError(try runLambda(behavior: Behavior(), factory: { $0.eventLoop.makeFailedFuture(TestError("boom")) })) { error in
             XCTAssertEqual(error as? TestError, TestError("boom"))
         }
     }

Tests/AWSLambdaRuntimeCoreTests/LambdaTest.swift

@@ -51,7 +51,7 @@ class LambdaTest: XCTestCase {
 
             var initialized = false
 
-            init(eventLoop: EventLoop) {
+            init(context: Lambda.InitializationContext) {
                 XCTAssertFalse(self.initialized)
                 self.initialized = true
             }
@@ -72,7 +72,7 @@ class LambdaTest: XCTestCase {
         XCTAssertNoThrow(try server.start().wait())
         defer { XCTAssertNoThrow(try server.stop().wait()) }
 
-        let result = Lambda.run(factory: { $0.makeFailedFuture(TestError("kaboom")) })
+        let result = Lambda.run(factory: { $0.eventLoop.makeFailedFuture(TestError("kaboom")) })
         assertLambdaLifecycleResult(result, shouldFailWithError: TestError("kaboom"))
     }
 
@@ -85,7 +85,7 @@ class LambdaTest: XCTestCase {
             typealias In = String
             typealias Out = Void
 
-            init(eventLoop: EventLoop) throws {
+            init(context: Lambda.InitializationContext) throws {
                 throw TestError("kaboom")
             }
 
@@ -124,7 +124,7 @@ class LambdaTest: XCTestCase {
         XCTAssertNoThrow(try server.start().wait())
         defer { XCTAssertNoThrow(try server.stop().wait()) }
 
-        let result = Lambda.run(factory: { $0.makeFailedFuture(TestError("kaboom")) })
+        let result = Lambda.run(factory: { $0.eventLoop.makeFailedFuture(TestError("kaboom")) })
         assertLambdaLifecycleResult(result, shouldFailWithError: TestError("kaboom"))
     }
 
@@ -143,7 +143,7 @@ class LambdaTest: XCTestCase {
             usleep(100_000)
             kill(getpid(), signal.rawValue)
         }
-        let result = Lambda.run(configuration: configuration, factory: { $0.makeSucceededFuture(EchoHandler()) })
+        let result = Lambda.run(configuration: configuration, factory: { $0.eventLoop.makeSucceededFuture(EchoHandler()) })
 
         switch result {
         case .success(let invocationCount):

Tests/AWSLambdaRuntimeCoreTests/Utils.swift

@@ -18,7 +18,7 @@ import NIO
 import XCTest
 
 func runLambda(behavior: LambdaServerBehavior, handler: Lambda.Handler) throws {
-    try runLambda(behavior: behavior, factory: { $0.makeSucceededFuture(handler) })
+    try runLambda(behavior: behavior, factory: { $0.eventLoop.makeSucceededFuture(handler) })
 }
 
 func runLambda(behavior: LambdaServerBehavior, factory: @escaping Lambda.HandlerFactory) throws {