Discussion: Make API SwiftNIOer

[fabianfett]

@fabianfett:

How much do we want to expose SwiftNIO. Currently one can not initialise the Lambda with an EventLoopGroup, and the potential callbacks are sync or async, but there is no EventLoopFuture option. Considering that in lot’s of use cases developers want to make calls to external services (http/databases) and so on, I’m not sure if this should be our default option.

@tomerd:

this is a great question, and one that i have been thinking about too. originally i refrained from it because i wanted it to be dead simple for iOS developers - so they dont need to understand futures and nio to write a lambda backend for their iOS apps. that said, as you mention these days most database client etc are nio based so its a impedance mismatch for someone that wants to make use of such. one option we should consider is to also offer a hander variant that returns a future (or fulfills a promise which would be my choice).

@fabianfett:

That’s why I opted for the SwiftNIO design in my runtime first, because that’s want I wanted to use. In other languages AWS encourages developers to set up as much as possible during cold start and to reuse those setups during invocations. For example an AsyncHTTPClient would be setup before Lambda.run and injected into/captured by the handler. If we don’t expose the EventLoopGroup the LambdaRuntime and AsyncHTTPClient will run on different EventLoopGroups – I don’t think we want that.

@tomerd:

yes, one thing i def want to change is to include the evenloop in the context object so that you can share it with the handlers

[fabianfett]

Expose EventLoop in the Context:

A proposal: https://github.com/tomerd/swift-aws-lambda/pull/8

API Design

/// A processing protocol for a Lambda that takes a `[UInt8]` and returns a `LambdaResult` result type asynchronously.
public protocol LambdaHandler {
    /// Initializes the `LambdaHandler`.
    func initialize(callback: @escaping LambdaInitCallBack)
    func handle(context: LambdaContext, payload: [UInt8], callback: @escaping LambdaCallback)
}

Two things about this:

1. I'm not sure what benefits the initialize function shall provide. As a Swift developer I normally look for chances to create constants within my structure at initialisation. For example: If I need an AsyncHTTPClient I'd rather set this one up in the init than in an initialize function. This would lead to an optional.
2. Do we want to expose the body as [UInt8] or as a NIO.ByteBuffer. Getting the array from the ByteBuffer is at least an extra malloc.
3. We will need to support cases in which the developer doesn't want to return a value (=Void). Lambda functions are often used for reactive programming where a result is not needed. After an SNS or SQS message is consumed by the lambda, no result is expected. I don't know yet, how we can achieve this.
4. Replacing the LambdaCallback with an EventLoopPromise or returning an EventLoopFuture. Normally I wouldn't mind, but having thought about this longer, I think I would like to return an EventLoopFuture better. There are two main reasons: On the one hand for developers unfamiliar with EventLoopPromise and EventLoopFuture, not succeeding/failing the Promise will lead to infinite running Lambdas. On the other hand EventLoopFutures are kind of more compile safe. ;) You must return an EventLoopFuture which is not such an easy miss. Further most server side swift frameworks return EventLoopFutures so results just need to be flatMapped into the response. With a promise we would need an extra call. Lastly we save an object creation, if we are dealing with Futures anyways.

[tomerd]

Two things about this:

4 haha

1. I'm not sure what benefits the initialize function shall provide. As a Swift developer I normally look for chances to create constants within my structure at initialisation. For example: If I need an AsyncHTTPClient I'd rather set this one up in the init than in an initialize function. This would lead to an optional.

in most cases this is not needed, which is why there is a default, empty, implementation. the inspiration came from aws lambda runtime api: https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html#runtimes-api-initerror

from a performance point of view, it would be nice to be able and skip this instead of calling into the default implementation and allocating. one way to do it is to have another protocol eg InitializableLambdaHandlerand do a is check on the hander we get

cc @glbrntt which added the initialize support originally

2. Do we want to expose the body as [UInt8] or as a NIO.ByteBuffer. Getting the array from the ByteBuffer is at least an extra malloc.

I suspect most users would come at the level of LambdaCodableHandler and won't access the bytes directly. need to double check with @weissi but we are using buffer.readBytes which I dont think copies the bytes. happy to explore more options here.

3. We will need to support cases in which the developer doesn't want to return a value (=Void). Lambda functions are often used for reactive programming where a result is not needed. After an SNS or SQS message is consumed by the lambda, no result is expected. I don't know yet, how we can achieve this.

agreed, I think we could create a handler variants that looks something like:

private struct LambdaBlockingClosureWrapper: LambdaHandler {
    typealias Closure = (LambdaContext, String) throws ->  String
    
    private let closure: Closure
    init(_ closure: @escaping Closure) {
        self.closure = closure
    }

    func handle(context: LambdaContext, payload: String, callback: @escaping LambdaStringCallback) {
        do {
            let result = try self.closure(context, payload)
            callback(.success(result))
        } catch {
            callback(.failure(error))
        }
    }
}

private struct LambdaBlockingVoidClosureWrapper: LambdaHandler {
    typealias Closure = (LambdaContext, String) throws -> Void
    
    private let closure: Closure
    init(_ closure: @escaping Closure) {
        self.closure = closure
    }

    func handle(context: LambdaContext, payload: String, callback: @escaping LambdaStringCallback) {
        do {
            try self.closure(context, payload)
            callback(.success("")) // meh, we can maybe make the API return optional
        } catch {
            callback(.failure(error))
        }
    }
}

4. Replacing the LambdaCallback with an EventLoopPromise or returning an EventLoopFuture. Normally I wouldn't mind, but having thought about this longer, I think I would like to return an EventLoopFuture better. There are two main reasons: On the one hand for developers unfamiliar with EventLoopPromise and EventLoopFuture, not succeeding/failing the Promise will lead to infinite running Lambdas. On the other hand EventLoopFutures are kind of more compile safe. ;) You must return an EventLoopFuture which is not such an easy miss. Further most server side swift frameworks return EventLoopFutures so results just need to be flatMapped into the response. With a promise we would need an extra call. Lastly we save an object creation, if we are dealing with Futures anyways.

I feel pretty strongly that we must offer a super-simple handlers that so not expose Future or Promise, looking at the various examples highlighted in https://github.com/theam/aws-lambda-benchmark/blob/master/examples/hello-world/setup.md we can see that even in languages that support and encourage Future/Promise APIs, the handler API is super simple. Large portion of the target audience for Swift based Lambda is iOS developers that are not familiar with Future/Promise or NIO so making a NIO Future/Promise based API our main user-facing API will make their life pretty difficult.

With that said, I do agree we should offer a variant of a handler that take a Promise or returns a Future. This will enable power users to chain nicely using tools that are familiar with with less performance overhead. on the question of Promise vs Future, the advantage of passing in a Promise is that the caller (the lambda library in this case) can potentially decide on the execution context of the promise since it generates it from an event loop it controls, while when you receive a Future back, you are not sure what thread it may run on. in order to offer a variant that exposes Future/Promise we would need to refactor LambdaHandler API to be based on this, then re-platform the rest on top it as demonstrated in #18

/cc @weissi

[Lukasa]

need to double check with @weissi but we are using buffer.readBytes which I dont think copies the bytes.

readBytes absolutely does copy the bytes.

[tomerd]

thanks for confirming @Lukasa. is there an API that does not? perhaps the buffer view?

[fabianfett]

I think we should first settle on an absolute base handler and then try to see if we can derive all wanted variants from this.

From #18 I can see an approach like this:

/// A processing protocol for a Lambda that takes a `[UInt8]` and returns a `LambdaResult` result type asynchronously.
public protocol LambdaHandler {
    func handle(context: LambdaContext, payload: ByteBuffer, promise: EventLoopPromise<ByteBuffer>)
}

I'm a huge fan of this given my own callback looks like this

  public typealias Handler = (NIO.ByteBuffer, Context) -> EventLoopFuture<NIO.ByteBuffer?>

For this reason I would go for two changes:

1. First make ByteBuffer optional, to allow deriving Void handlers. Then we can build up on this with Codable handlers like this: https://github.com/fabianfett/swift-lambda-runtime/blob/e85dac1496c35c557a595eeb117c728f7dc5e1d6/Sources/LambdaRuntime/Runtime%2BCodable.swift#L5

2. Future vs. Promise

on the question of Promise vs Future, the advantage of passing in a Promise is that the caller (the lambda library in this case) can potentially decide on the execution context of the promise since it generates it from an event loop it controls, while when you receive a Future back, you are not sure what thread it may run on.

That's right for sure, but we could also just .hop(to: self.eventLoop) in LambdaRunner.run to ensure that we are back on the correct eventLoop. Question is if we want to give developers the "burden" of for-filling the given promise, or if the package just ensures the correct eventLoop with a hop.

https://github.com/fabianfett/swift-lambda-runtime/blob/e85dac1496c35c557a595eeb117c728f7dc5e1d6/Sources/LambdaRuntime/Runtime.swift#L115

As you can see I'm in favour of the hop. 😉

[Lukasa]

Either ByteBuffer or ByteBufferView would not copy, but the two types are essentially arbitrarily interchangeable. So the “most basic” type is one of those two. Helpers in terms of other types can always ben made available for convenience, of course.

[tomerd]

thanks @Lukasa, the question was more about exposing the underlying bytes to the user, ie going from ByteBuffer to [UInt8]. is there a way to access that (readonly) without copying?

[fabianfett]

@weissi encouraged me to go [UInt8](buffer) in my json parser:

https://github.com/fabianfett/pure-swift-json/blob/9298cdac14e5bbdb8bc92be082411335313e1284/Sources/PureSwiftJSONParsing/DocumentReader.swift#L15