MinimalLambda.Envelopes.Alb 2.2.0

MinimalLambda.Envelopes.Alb

Strongly-typed Application Load Balancer event handling for the MinimalLambda framework.

Overview

This package provides strongly-typed envelopes for handling Application Load Balancer (ALB) events in Lambda functions. It contains classes that can be used as input and output types for Lambda functions that process requests from an AWS Application Load Balancer.

The envelopes extend the base ApplicationLoadBalancerRequest and ApplicationLoadBalancerResponse with strongly-typed BodyContent properties for easier request/response serialization:

Quick Start

Define your request and response types, then create a handler:

using System;
using System.Collections.Generic;
using MinimalLambda.Builder;
using MinimalLambda.Envelopes.Alb;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = LambdaApplication.CreateBuilder();
var lambda = builder.Build();

// AlbRequestEnvelope<Request> provides the ALB event with deserialized request body
// AlbResponseEnvelope<Response> wraps the response and serializes it to the body
lambda.MapHandler(
    ([FromEvent] AlbRequestEnvelope<Request> request, ILogger<Program> logger) =>
    {
        logger.LogInformation("Request: {Name}", request.BodyContent?.Name);

        return new AlbResponseEnvelope<Response>
        {
            BodyContent = new Response($"Hello {request.BodyContent?.Name}!", DateTime.UtcNow),
            StatusCode = 200,
            Headers = new Dictionary<string, string> { ["Content-Type"] = "application/json" },
        };
    }
);

await lambda.RunAsync();

// Your request and response payloads
internal record Request(string Name);

internal record Response(string Message, DateTime TimestampUtc);

Response Builder API

The AlbResult class provides a fluent API for building HTTP responses. Key benefit: Return multiple strongly typed models from the same handler (e.g., success vs. error responses with different types).

lambda.MapHandler(([FromEvent] AlbRequestEnvelope<Request> request) =>
{
    if (string.IsNullOrEmpty(request.BodyContent?.Name))
        return AlbResult.BadRequest(new ErrorResponse("Name is required"));

    return AlbResult.Ok(new SuccessResponse($"Hello {request.BodyContent.Name}!"));
});

Available methods: Ok(), Created(), NoContent(), BadRequest(), Unauthorized(), NotFound(), Conflict(), UnprocessableEntity(), InternalServerError(), StatusCode(int), Text(int, string), Json<T>(int, T).

All methods have overloads with and without body content. Use .Customize() for fluent header customization.

Choosing Between Envelopes and Results

Use AlbResult when you need to return multiple strongly typed models from the same handler (e.g., different success and error types). Provides convenient methods for common HTTP status codes.

Use AlbResponseEnvelope<T> directly when you need custom serialization (e.g., XML) or want to extend envelope base classes for custom behavior.

Custom Envelopes

To implement custom deserialization logic, extend the appropriate base class and override the payload handling method:

// Example: Custom XML deserialization for requests
public sealed class XmlAlbRequestEnvelope<T> : AlbRequestEnvelopeBase<T>
{
    public override void ExtractPayload(EnvelopeOptions options)
    {
        using var stringReader = new StringReader(Body);
        using var xmlReader = XmlReader.Create(stringReader, options.XmlReaderSettings);
        var serializer = new XmlSerializer(typeof(T));
        BodyContent = (T)serializer.Deserialize(xmlReader)!;
    }
}

// Example: Custom XML serialization for responses
public sealed class XmlAlbResponseEnvelope<T> : AlbResponseEnvelopeBase<T>
{
    public override void PackPayload(EnvelopeOptions options)
    {
        using var stringWriter = new StringWriter();
        using var xmlWriter = XmlWriter.Create(stringWriter, options.XmlWriterSettings);
        var serializer = new XmlSerializer(typeof(T));
        serializer.Serialize(xmlWriter, BodyContent);
        Body = stringWriter.ToString();
    }
}

This pattern allows you to support multiple serialization formats while maintaining the same envelope interface.

AOT Support

When using .NET Native AOT, register all envelope and payload types in your JsonSerializerContext:

[JsonSerializable(typeof(AlbRequestEnvelope<Request>))]
[JsonSerializable(typeof(AlbResponseEnvelope<Response>))]
[JsonSerializable(typeof(Request))]
[JsonSerializable(typeof(Response))]
internal partial class SerializerContext : JsonSerializerContext;

When using AlbResult with multiple return types, register each type separately:

[JsonSerializable(typeof(AlbRequestEnvelope<Request>))]
[JsonSerializable(typeof(AlbResult))]
[JsonSerializable(typeof(Request))]
[JsonSerializable(typeof(SuccessResponse))]
[JsonSerializable(typeof(ErrorResponse))]
internal partial class SerializerContext : JsonSerializerContext;

Register the serializer and configure envelope options to use the context:

builder.Services.AddLambdaSerializerWithContext<SerializerContext>();

builder.Services.ConfigureEnvelopeOptions(options =>
{
    options.JsonOptions.TypeInfoResolver = SerializerContext.Default;
});

Other Packages

Additional packages in the minimal-lambda framework for abstractions, observability, and event source handling.

Package	NuGet	Downloads
MinimalLambda
MinimalLambda.Abstractions
MinimalLambda.OpenTelemetry
MinimalLambda.Envelopes
MinimalLambda.Envelopes.Sqs
MinimalLambda.Envelopes.ApiGateway
MinimalLambda.Envelopes.Sns
MinimalLambda.Envelopes.Kinesis
MinimalLambda.Envelopes.KinesisFirehose
MinimalLambda.Envelopes.Kafka
MinimalLambda.Envelopes.CloudWatchLogs
MinimalLambda.Envelopes.Alb

License

This project is licensed under the MIT License. See LICENSE for details.