Design Doc: Lambda Annotation

[normj]

The AWS .NET team is working on a new library for constructing .NET Lambda functions. The design doc can be viewed and commented on in this PR https://github.com/aws/aws-lambda-dotnet/pull/961.

The high level overview of the new library is to use .NET source generator support to translating from the low level single event object programming model of Lambda to an experience similar to ASP.NET Core but with minimal overhead. The initial work is focused on REST API Lambda functions but the technology is applicable for other Lambda event types.

For example developers will be able to write a Lambda function like the following with the ICalculator service being injected by dependency injection and and the LambdaFunction and HttpApi attributes directing the source generator to generator the compatible Lambda boiler plate code and sync with the CloudFormation template.

public class Functions
{
	ICalculator _calulator;

	public Functions(ICalculator calculator)
	{
		_calulator = calculator;
	}

	[LambdaFunction]
	[HttpApi(HttpMethod.Get, HttpApiVersion.V2, "/add/{x}/{y}")]
	public int Add(int x, int y)
	{
		return _calulator.Add(x, y);
	}
}

We would appreciate feedback on the design. What use cases what you like this library to help solve and what boiler plate code can we remove from your applications to make it simple to write Lambda functions.

---

Update 12/21/2021

We are excited to announce that Lambda Annotations first preview is here. Developers using the preview version of Amazon.Lambda.Annotations NuGet package can start using the simplified programming model to write REST and HTTP API Lambda functions on .NET 6. (Only Image package type is supported as of now)

Example (sample project)

[LambdaFunction(Name = "CalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/Calculator/Add/{x}/{y}")]
public int Add(int x, int y, [FromServices]ICalculatorService calculatorService)
{
    return calculatorService.Add(x, y);
}

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<ICalculatorService, CalculatorService>();
    }
}

Learn more about the Lambda Annotations and supported feature set here.

We cannot overstate how critical your feedback is as we move forward in the development. Let us know your experience working with Lambda Annotations in GitHub issues.

[CalvinAllen]

Dependency Injection is a huge plus, to me. I've had to roll that myself to support it - same with logging and configuration / environmental configuration.

EDIT: Why confused, @normj ?

[Lanayx]

Source generators is not dotnet, but csharp technology, so will be applicable only to csharp, with fsharp it won't be usable.

[mtschneiders]

Would it also generate the code needed for manual invocation via Lambda Test Tool?

 public static async Task Main()
  {
      var func = new Startup().FunctionHandler;
      using var handlerWrapper = HandlerWrapper.GetHandlerWrapper(func, new DefaultLambdaJsonSerializer());
      using var bootstrap = new LambdaBootstrap(handlerWrapper);
      await bootstrap.RunAsync();
  }

[normj]

Dependency Injection is a huge plus, to me. I've had to roll that myself to support it - same with logging and configuration / environmental configuration.

EDIT: Why confused, @normj ?

@CalvinAllen Sorry clicked the wrong emoji

[CalvinAllen]

@normj Ha, okay. I was a little confused myself, trying to figure out what I said, lol.

[Kralizek]

It would be great to see more of the plumbing, which happened to be the weakest point of Lambda development.

As @CalvinAllen wrote, logging, configuration and service registration are all concerns that required some time to work in a vanilla function.

But I generally love the idea of seeing multi-function packages becoming first class citizen of the new toolkit.

[petarrepac]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

[normj]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

@petarrepac Are you saying these questions are not answered in the design doc?

[Dreamescaper]

It would be great to design DI container setup in such a way so it would be possible to replace some dependencies for testing after initial container setup. I mean not unit tests, but more like functional tests, similar to ASP.NET Core's WebApplicationFactory. https://docs.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-6.0

[Dreamescaper]

Would it be possible to customize parsing the request somehow? For example, if I have not a JSON body, but application/x-www-form-urlencoded ?

Another question - would it be possible to add [From...] attributes not on method parameters, but on type properties? So I'd be able to have single MyEndpointRequest parameter, and add [FromQuery], [FromHeader], etc on corresponding properties in MyEndpointRequest type?

[petarrepac]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

@petarrepac Are you saying these questions are not answered in the design doc?

took a look at one of our latest projects. Found this:

public async Task FunctionHandlerAsync(Stream stream, ILambdaContext context)

and also this

namespace MyProject.Api.Http
{
    public class LambdaEntryPoint : ApplicationLoadBalancerFunction
    {
        protected override void Init(IWebHostBuilder builder)
        {
            builder.ConfigureLogging((hostingContext, logging) =>
                {
                    logging.SetMinimumLevel(LogLevel.Warning);
                })
                .UseStartup<Startup>();
        }
    }
}

This are the entry points to 2 different lambdas. The 2nd one being a full REST API with many endpoints.

The nice thing is that only this code is "lambda specific". Everything else is the same code as you would have when running as a standalone app. So, you can run it locally, run integration tests, and so on.

The new approach seems more opinionated (for example CloudFormation and ApiGateway are mentioned, we use CDK and ALB instead). So, in REST API case what is the benefit? The amount of code is already very small. Is it faster with cold starts? Will the current way still work or it will be left behind going forward?

[ganeshnj]

Would it be possible to customize parsing the request somehow? For example, if I have not a JSON body, but application/x-www-form-urlencoded ?

Another question - would it be possible to add [From...] attributes not on method parameters, but on type properties? So I'd be able to have single MyEndpointRequest parameter, and add [FromQuery], [FromHeader], etc on corresponding properties in MyEndpointRequest type?

That's a cool idea, thanks for the feedback.

[normj]

@petarrepac The approach of running ASP.NET Core application's as Lambda functions will still be fully supported. I even did some work to support ASP.NET Core .NET 6 minimal style although that will be more useful once we get the .NET 6 managed runtime out. The ASP.NET Core approach does make development more familiar and keeps your code abstracted from Lambda.

The con of using that approach is there is a slower cold start due to initializing ASP.NET Core and you kind of miss out some of the API Gateway features because you are relying on ASP.NET Core to do the work. That isn't an issue for you because you are using ALB. We also want this new library to support more than just REST API scenarios even through that is our initial focus.

So if you are happy with ASP.NET Core approach keeping doing and we will continue to support you with it. This library is for developers that want something lighter and covers more scenarios than REST API.

[petarrepac]

Thanks. I'm more clear on this development now.

[BoundedChenn31]

Would it be possible to provide a fallback to reflection to make this API available for any .NET language? As described in design doc performance isn't the only goal. Experience of writing Lambda functions would still be improved though at cost of worse cold start.

[normj]

@Lanayx You are right. We are using a C# specific technology. I'll update the doc to reflect that. I have wondered if F# type providers could provide a similar experience.

@BoundedChenn31 I'm not sure how reflection would help. The Lambda programming model isn't changing. Lambda is still executing a parameterless constructor, it an instance method, and then invoking the method that takes in the event object. If we don't have the source generator to generate the translation layer from the Lambda programming model to this libraries programming model at compile time then both the Lambda programming model and the this library programming model have to be coded. Also at compile time is the syncing with CloudFormation that couldn't be done at runtime with reflection. Is F# your main concern when it comes to other .NET languages?

[BoundedChenn31]

@normj Ah, sorry, I overlooked these implementation details. In this case reflection doesn't really make sense. And yes, I'm mostly worried about F#. Well, in worst scenario F#-community can come up with alternative implementation using it's own source generation tool — Myriad 😊

[RichiCoder1]

Would it also generate the code needed for manual invocation via Lambda Test Tool?

 public static async Task Main()
  {
      var func = new Startup().FunctionHandler;
      using var handlerWrapper = HandlerWrapper.GetHandlerWrapper(func, new DefaultLambdaJsonSerializer());
      using var bootstrap = new LambdaBootstrap(handlerWrapper);
      await bootstrap.RunAsync();
  }

Was this question answered? I'm extremely bullish on this, but would want to make sure there's still some way to locally invoke and/or E2E test functions.

Edit: on the note of minimal apis, is there a world where you can do something like the below? Pardon if should be a separate discussion or thread.

var lambda = AwsLambdaBuilder.Create(args);

lambda.HandleApiGatewayV2(async (event) => {
  // do function stuff
 return obj;
});

lambda.Run();

Would be a neat way to have sorta parity with JavaScript while not having to opt too deeply into the CDK.

[DerekBeattieCG]

This is interesting, I thought about doing something similar, generating pulumi C# apigateway code based on attributes on a function.

[normj]

@RichiCoder1 The CloudFormation template will still have the correct function handler value for the source generated method. So SAM and the .NET Lambda Test Tool would work just as they do today.

[ganeshnj]

We are excited to announce that Lambda Annotations first preview is here. Developers using the preview version of Amazon.Lambda.Annotations NuGet package can start using the simplified programming model to write REST and HTTP API Lambda functions on .NET 6. (Only Image package type is supported as of now)

Example (sample project)

[LambdaFunction(Name = "CalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/Calculator/Add/{x}/{y}")]
public int Add(int x, int y, [FromServices]ICalculatorService calculatorService)
{
    return calculatorService.Add(x, y);
}

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<ICalculatorService, CalculatorService>();
    }
}

Learn more about the Lambda Annotations and supported feature set here.

We cannot overstate how critical your feedback is as we move forward in the development. Let us know your experience working with Lambda Annotations in GitHub issues.

[genifycom]

For many of our current workloads, we run the same code locally and in Lambda. Our clients can then run either on an on-premise machine or in the cloud (e.g. via a tablet).

Is this going to run in both environments or Lambda only?

Thanks

[ganeshnj]

It depends on the how you are calling the target method in your local environment.

For example an attributed Lambda Function

[LambdaFunction(Name = "SimpleCalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/SimpleCalculator/Add")]
public int Add([FromQuery]int x, [FromQuery]int y)
{
    return _simpleCalculatorService.Add(x, y);
}

The generated code is https://github.com/aws/aws-lambda-dotnet/blob/master/Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Snapshots/SimpleCalculator_Add_Generated.g.cs

In short, you can write tests, local debug using Lambda Test Tool or instantiate (your class or generated class) & call the target method.

In short, yes assuming your local environment have ability to instantiate and call.

[Kralizek]

Will there be a way to customize the Configuration section like it seems to be possible to customize the services?

[lukeemery]

@ganeshnj I see you've been working on the lambda annotations to build the serverless.template. Trying to figure out where we'd be able to inject environment variables for which stage it is in (i.e. prod, staging, dev) so that we can control which dynamodb tables we connect to.

Any guidance here?

[ganeshnj]

@Kralizek If understood it correctly, we plan to support Startup.Configure method which will be used to configure the request pipeline.

[ganeshnj]

@lukeemery serverless.template writer only updates the configuration that are updatable from C# code, rest of the of the configuration is not altered. Anything added outside the scope, will stay as part of template.

You can setup environment variable using existing Environment property

"Environment": {
  "Variables": {
    "Foo": "Bar"
  }
}

[Kralizek]

That's great to hear but I was referring to the steps necessary to customize the IConfigurationBuilder.

Use case:

• I want to pick up values from the parameter store and/or secrets manager
• I want to load some values from a file stored in S3

[ganeshnj]

I see what you mean. I have not tested it myself but this should still work. It can go to Startup.ConfigureServices method.

[Kralizek]

I'm not sure I can see how I would be able to customize the IConfigurationBuilder from the ConfigureServices method you suggest.