RFC: Handler trait

[greenwoodcm]

Background

The Java runtime allows the developer to provide the handler method as either a static method on a class (loosely akin to a Rust module fn) or as a member function on a class (loosely akin to a Rust struct fn handler(&mut self)). In the latter case, the Java runtime will execute the class no-arg constructor to get an instance of the object during the initialization phase, and then use that object through the lifetime of the execution environment. This makes it fairly ergonomic to implement state sharing across invocations - one declares fields on the object and then populates those objects in the constructor.

The Rust runtime only allows the former, providing the handler as a static (non-struct) fn. State sharing is then implemented either as global static state or by using a move to build a closure to do it (example).

Proposal

Support a struct-style programming model. This would be supported in addition to the existing fn model. This would allow for more ergonomic sharing of state like SDK clients or open file descriptors across invocations. A sketch programming model is provided below to illustrate the high-level proposal, though I think a full implementation of this would probably be more complicated because it would need to expose error types and deal with async stuff.

Prototype

Playground link

trait LambdaRuntime {
    type Return;

    fn init() -> Self;
    fn invoke(&mut self) -> Self::Return;
}

struct MyHandler {
    state: String,
}

impl LambdaRuntime for MyHandler {
    type Return = String;

    fn init() -> Self {
        MyHandler {
            state: "abc".into(),
        }
    }
    
    fn invoke(&mut self) -> String {
        let s = self.state.clone();
        let new_s = format!("{s} + invoke");
        self.state = new_s;
        s
    }
}

fn run<R: LambdaRuntime>(n: u32)
where R::Return: std::fmt::Display
{
    let mut handler = R::init();
    
    for _ in 0..n {
        println!("{}", handler.invoke());
    }
}

fn main() {
    run::<MyHandler>(3);
}

[calavera]

You can use any struct that implements the Tower's Service trait. This trait is fairly well known because it's used by frameworks in the ecosystem like Axum. Do we need our own trait? I think this capability is not documented at all, but maybe it'd be enough to have more documentation about it. I've only been able to find an example of this in the repo, so maybe we should have more information about it:

https://github.com/awslabs/aws-lambda-rust-runtime/blob/main/examples/extension-logs-kinesis-firehose/src/main.rs

I do want to acknoledge that Tower's Service trait is not the easiest to implement, but there are many examples online.

[greenwoodcm]

that's interesting. i am sensitive to the part about the Service trait being tricky to implement. do you think the optimal path is for us to have a thin layer on top of the Service trait that improves ergonomics? that would make developer experience clean and leave the runtime to only have to deal with the Service abstraction.

[DavidSouther]

I think this moves the handler (closer?) to the right level of abstraction for Lambda. Tower is powerful, yes, and there are cases to prefer using it explicitly, but it's a different abstraction than I expect we'll see in the common case. Certainly it's easier to document and explain than the tower examples.

Going from Fn -> Tower is a big step, especially for users who are newer to Rust and want to focus on happy path & easy wins. Adding a level of abstraction in the middle will help them make that step. Using Tower under the hoods sounds good, but asking people to understand

    fn poll_ready(&mut self, _cx: &mut core::task::Context<'_>) -> core::task::Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }

is going to make a lot of eyes glaze over.

[calavera]

for users who are newer to Rust and want to focus on happy path & easy wins

those users don't need advanced features then, functions are probably good enough for them.

[DavidSouther]

Adding a level of abstraction in the middle will help them make that step.

Hi, it's me. I'm the user who is telling you that I am beyond functions, but don't want to deal with Tower.

[LucioFranco]

FYI Tower's trait will be reaching a 1.0 this year and will be massively changed and simplified. Removing things like poll_ready and moving to async fn in traits. I think its worth a longer discussion on that and to coordinate. In the end, it will likely look similar to what will happen here.

[calavera]

I found two more examples here:

https://github.com/awslabs/aws-lambda-rust-runtime/blob/3fce312eb77f7ec1722e1c4605b11f770e286ed9/lambda-integration-tests/src/bin/runtime-trait.rs
https://github.com/awslabs/aws-lambda-rust-runtime/blob/3fce312eb77f7ec1722e1c4605b11f770e286ed9/lambda-integration-tests/src/bin/http-trait.rs

[timClicks]

One downside of Tower's Service is that it doesn't have an explicit init/setup hook, which users of a Lambda runtime might expect. Although perhaps that's not necessary because of the associated types.

[calavera]

why do you need an explicit init/setup hook in the trait? it's very common for Rust structs to implement new functions that initialize the struct. It's a well defined pattern, why do we need our own?

[DavidSouther]

new isn't typically async, while I often do want to do async in this hypothetical init phase. async fn new() -> Self feels like a code smell to me? While async fn init() -> Self doesn't? Maybe that's a me thing. There's also the terminology mismatch - in Lambda, we talk about the init phase, and mirroring that in the runtime library continues to seem (to me) like a good facade.

[calavera]

Sure, you can call this function whatever you want, that's fine, why does it need to be explicit in the trait? what's the benefit? not having that function in the trait is not stopping anyone from initializing a struct with whatever they want, so what's the point of enforcing this at the trait level?

[DavidSouther]

The abstraction provided by an explicitly named init function reduces mental overhead. It makes it very clear "this is where you do initialization things". It makes it straightforward to say "initialization things that are expensive should be done here and you'll get these benefits."

Yes, you can do it elsewhere. Having a name for it is powerful and useful.

[timClicks]

In our case, we want the ability to initialize global resources that are independent from a specific request. I suppose that it's not necessary to encode that in the type system, but I was thinking that it might be useful to create some space that's explicit.

[beard-programmer]

Why is it not good enough to use a closure for passing dependencies as it is right now?

[yerke]

@greenwoodcm Are you trying to add a way to define non-async way to using runtime? Currently we can't use async functions in traits on stable channel AFAIK, so in your example we are throwing out the async functionality. Or did you want to start tokio inside invoke function in your example?

[greenwoodcm]

No, sorry for the confusion. The prototype code provided is just an illustration of the high-level idea. Implementing this for real would involve taking that interface and async-ing it, and also probably involve plumbing some error handling through the interface. So treat that as pseudocode.

[jeastham1993]

To add my 2 cents to this discussion as someone very new to Rust, coming from the .NET world. I like the proposed implementation, as it feels much more familiar with the way functions are defined in other compiled languages.

It wasn't a heavy lift to rethink how I build Lambdas from .NET to Rust, as you have to do similar things when building native binaries with .NET. But @greenwoodcm proposed programming model would definitely have eased my adoption.

[calavera]

I think we need to go back to the problem that we're trying to solve here. I think this is a good gist for it:

People don't know how to initialize shared resources that will be reused in multiple Lambda invocations

That's a valid concern. I've answered that question a few times, and we have evidence in this repo that it's not intuitive for people:

#581
#616

What's interesting for me about those discussions is that as soon as you explain it, people don't seem to have any problem understanding how to do it and following the pattern. To me, this tells me that the current semantics are not complicated per-se, they are hard to find. If you look at the readme, there is no information about it at all. The new AWS docs mention this, but they were just published a few days ago.

Before jumping into a new mechanism to initialize functions, we should improve how people discover those kinds of features. Adding more docs, or addressing these kinds of questions in the existent ones right away, requires very low effort, and it can yield in a high reward for our users.

The same applies to the Tower integration. The two examples of Axum integrations are very interesting, but nobody knows that you can use anything that implements Service as a Lambda function, because it's documented nowhere. Making more visible that you can use the full possibilities that Tower offers, can offer interesting possibilities for our users. Writing those docs requires very low effort.

Going back to @beard-programmer's question. Are the current mechanisms not good enough? Before adding a new one, maybe we should look at whether the way people learn about the current features is good enough first.

[forficate]

As a beginner Rust user and aws-lambda-rust-runtime user, I agree the issue is a lack of documentation to help with my lack of familiarity; however, the current state of documentation is to be expected, given the age/maturity of the project, as it's still young, and my lack of familiarity isn't a fault of the library, that's on me to learn the language, look at examples and the source code as I'm using a young library while learning a new language.

I had some "learner" issues finding out how to initialise the state so it could be shared. After looking at the examples and finding the issues you linked, it was straightforward/easy. As I learnt, I appreciated the simplicity and flexibility of the library, especially using Tower. It makes local dev easy as it can run locally or in lambda by toggling an environment variable. I develop my apps pretending it's not a Lambda using Axum etc, and plug in aws-lambda-rust-runtime at the end as a shim.

Reading these comments, it comes across as "I know language X", "I want this to work like language X because I know language X", mostly making the implementation look like an OOP design rather than the current function based design. It's not a technical issue but a person's style preference and language experience issue which are not library issues.

Today you can initialize shared state trivially. The integration with Tower is relatively straightforward (once you have read up on Tower) while powerful. lambda_runtime::run taking a function as an argument is trivially simple if you understand passing functions which are common in a lot of languages i.e. Javascript or functional languages.

I guess what I'm trying to say is it took me a while to understand the library, but that was because I was new to both Rust and the library, and the library is so new there's no/limited existing documentation. It wasn't a technical design issue, and now I understand the language and library more, I find the technical design to be better / higher quality than the other AWS language SDK's and I prefer the function style instead of trying to make this look like OOP Java for the sake of someone new to Rust wanting to program like OOP Java as that's what they know instead of programming in idiomatic Rust and just passing a function. Java/C# also has lambda's support so passing functions around shouldn't be a new concept.

[beard-programmer]

making the implementation look like an OOP design rather than the current function based design

I was having the same impression, I was wondering if anyone thought the same.
Though I did not mention it to avoid OOP vs FP conversation, but rather wanted to know what specifically people are bothered with.
Besides the fact that it's not very similar to Java/C#.
Rust is not the easiest language to do FP, but this specific use case works just fine with me - it gets the job done without creating any additional and maybe unnecessary abstractions.

[jeastham1993]

I think you are both absolutely on point with these comments, my biggest challenge was moving away from the mindset of OOP and embracing the different style of writing apps in Rust. Whilst I do see that there is a bias there for me, particularly a familiarity bias, the programming model for Rust Lambda functions differs to both Python & Node as well as .NET/Java. I don't think we get rid of the more idiomatic way of using the Rust runtime, now that I'm familiar with it I'm a fan. Good documentation would start to address that. However, if there was an alternative programming model that was more familiar, that would lower the barrier of entry to get started.