Research: Explore payload extraction from Lambda events using decorator attributes

[j-d-ha]

Overview

Explore the feasibility of extracting payloads from various Lambda event types using decorator attributes. This approach would require handlers to be decorated with metadata about expected request and response types, enabling the framework to intelligently extract the relevant payload from different Lambda event structures.

Background

AWS Lambda functions can be triggered by various event sources (API Gateway, S3, SNS, SQS, EventBridge, etc.), each with different event structures. Currently, handlers need to know the specific event structure, but this feature would allow automatic payload extraction based on attribute metadata.

Research Objectives

1. Attribute Design

• Design attribute(s) to specify event type and payload extraction logic
• Determine what metadata is needed:
  • Event type (e.g., ApiGatewayProxyRequest, S3Event, SQSEvent)
  • Payload location within the event (e.g., Body, Records[].Body, etc.)
  • Request/response type mappings
  • Serialization/deserialization requirements

Example concept:

[LambdaEvent(EventType.ApiGatewayProxy, RequestType = typeof(MyRequest), ResponseType = typeof(MyResponse))]
public MyResponse Handle(MyRequest request) { }

// or more granular:
[ApiGatewayEvent]
[RequestType<MyRequest>]
[ResponseType<MyResponse>]
public MyResponse Handle(MyRequest request) { }

2. Event Type Coverage

Research common Lambda event sources and their payload structures:

• API Gateway: APIGatewayProxyRequest → extract from Body property
• Application Load Balancer: ApplicationLoadBalancerRequest → extract from Body
• S3: S3Event → extract from Records[].S3.Object
• SQS: SQSEvent → extract from Records[].Body
• SNS: SNSEvent → extract from Records[].Sns.Message
• EventBridge: EventBridgeEvent<T> → extract from Detail
• DynamoDB Streams: DynamoDBEvent → extract from Records[]
• Kinesis: KinesisEvent → extract from Records[].Data

3. Source Generator Integration

Investigate how to generate extraction logic:

• Generate type-safe extraction code based on attributes
• Handle deserialization (JSON → POCO)
• Error handling for malformed events
• Support for custom extraction logic

Example generated code concept:

// Generated handler wrapper
private static async Task<APIGatewayProxyResponse> GeneratedHandler(
    APIGatewayProxyRequest lambdaEvent,
    ILambdaContext context)
{
    // Extract payload from event.Body
    var request = JsonSerializer.Deserialize<MyRequest>(lambdaEvent.Body);
    
    // Invoke user handler
    var response = await userHandler.Handle(request);
    
    // Wrap response
    return new APIGatewayProxyResponse
    {
        StatusCode = 200,
        Body = JsonSerializer.Serialize(response)
    };
}

4. Error Handling and Validation

• What happens when event structure doesn't match expectations?
• How to provide meaningful diagnostics at compile-time?
• Runtime validation and error reporting

5. Performance Considerations

• Impact on cold start times
• Serialization/deserialization overhead
• AOT compatibility (ensure generated code is AOT-safe)

Research Tasks

• Survey AWS Lambda event types and document payload structures
• Design attribute API (syntax, parameters, constraints)
• Prototype source generator logic for 2-3 common event types
• Investigate error handling strategies
• Test with AOT compilation
• Evaluate performance impact vs. current approach
• Identify edge cases and limitations
• Document findings and trade-offs

Potential Challenges

1. Type Safety

• How to ensure event type matches attribute declaration at compile-time?
• Roslyn analysis to validate event parameter types?

2. Complexity

• Some events (S3, SQS, SNS) contain arrays of records - how to handle batching?
• Nested payload structures
• Multiple serialization formats (JSON, Base64, etc.)

3. Flexibility vs. Convention

• Balance between automatic "magic" and explicit control
• Need escape hatches for custom extraction logic

4. Diagnostics

Generator diagnostics needed:

• Mismatched event type and attribute
• Missing required metadata
• Incompatible request/response types
• Multiple event attributes on single handler

Success Criteria

• Clear understanding of feasibility and scope
• Prototype demonstrating extraction for at least 2 event types
• Performance benchmarks showing acceptable overhead
• List of supported event types and limitations documented
• Diagnostic coverage for common misconfigurations
• AOT compatibility verified

Decision Points

After research, decide:

1. Proceed or Defer? Is this feature worth the complexity?
2. Scope: Which event types to support in v1?
3. API Design: Final attribute syntax and semantics
4. Opt-in or Default? Should this be an alternative approach or replace current patterns?

Related Issues

• Add diagnostic to validate only one input parameter uses the input annotation #25 - Input parameter validation (related to parameter handling)
• Add full AOT support with directives and alternative logic #6 - AOT support (must ensure compatibility)

Priority

Research/Exploration - Not blocking other work, but informs future architectural decisions.

Estimated Effort

2-3 days for initial research and prototype

---

Note: This is a research story. The goal is exploration and documentation of findings, not necessarily a complete implementation. Findings will inform whether to proceed with a full implementation story.

[j-d-ha]

Closed with #131