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 {