Add support for Lambda functions exposed behind an Application Load Balancer (ALB)

[sebsto]

This PR adds support for exposing Swift OpenAPI Lambda functions behind an Application Load Balancer (ALB), providing an alternative to API Gateway for HTTP routing to Lambda functions.

Changes

New ALB Support

• OpenAPILambdaALB Protocol: New protocol for ALB integration alongside existing API Gateway support
• ALB Event Handling: Added ALBTargetGroupRequest and ALBTargetGroupResponse support
• HTTP Request Conversion: Extension methods to convert ALB events to/from HTTP requests/responses

Core Library Updates

• ALB-related source files: New /Sources/ALB/ directory with ALB-specific implementations
• Event Type Support: Support for ALBTargetGroupRequest events from Elastic Load Balancing
• Response Mapping: Proper mapping from OpenAPI responses to ALB target group responses

Complete ALB Example

• QuoteAPI ALB Example: Full working example in Examples/quoteapi-alb/
• Infrastructure as Code: Complete SAM template with VPC, subnets, security groups, and ALB
• Build System: Makefile and Docker build support for ALB deployment
• Documentation: Comprehensive README with ALB-specific deployment instructions

Key Files Added

Sources/ALB/
├── OpenAPILambdaALB.swift
└── ALBTargetGroup+HTTPRequest.swift

Examples/quoteapi-alb/
├── Package.swift
├── template.yaml
├── Makefile
├── README.md
├── Sources/QuoteAPI/QuoteService.swift
├── Sources/QuoteAPI/openapi.yaml
├── Sources/QuoteAPI/openapi-generator-config.yaml
└── events/GetQuote.json

Usage

Simple ALB Integration

@main
struct QuoteServiceALBImpl: APIProtocol, OpenAPILambdaALB {
    func register(transport: OpenAPILambdaTransport) throws {
        try self.registerHandlers(on: transport)
    }
    
    static func main() async throws {
        let service = QuoteServiceALBImpl()
        try await service.run()
    }
    
    // Your OpenAPI implementation...
}

Key Differences from API Gateway

• Uses OpenAPILambdaALB instead of OpenAPILambdaHttpApi
• Handles ALBTargetGroupRequest events instead of APIGatewayV2Request
• Returns ALBTargetGroupResponse instead of APIGatewayV2Response
• Requires VPC infrastructure (included in SAM template)
• No built-in authorization (implement via custom middleware if needed)

Benefits

• Cost Optimization: ALB can be more cost-effective for high-traffic applications
• VPC Integration: Native VPC support for private network access
• Load Balancing: Advanced load balancing features and health checks
• WebSocket Support: Future WebSocket support through ALB
• Flexibility: Choice between API Gateway and ALB based on use case

Testing

• ✅ ALB example builds successfully with sam build
• ✅ Local testing with sam local invoke
• ✅ Complete infrastructure deployment via SAM
• ✅ HTTP requests properly routed through ALB to Lambda
• ✅ OpenAPI specification compatibility maintained

Deployment

Deploy the ALB example:

cd Examples/quoteapi-alb
sam build && sam deploy --guided

Test the deployed endpoint:

curl http://[alb-dns-name]/stocks/AAPL

Backward Compatibility

This is a purely additive change:

• Existing API Gateway implementations continue to work unchanged
• No breaking changes to existing APIs
• New ALB support is opt-in via protocol conformance

[sebsto]

Thank you @tkrajacic for the review. I updated the code based on your review.
The multiValueHeader property was not properly handled (already for APIGatewayV2) I fixed this and add unit tests.

If time permits, I would love another round of review and / or test it on your project code before merging.

[tkrajacic]

I now incorporated your branch and kicked out my custom code. Works like a charm.