feat(build): ensure proper AOT compatibility validation and configuration

[j-d-ha]

Description

Implement comprehensive AOT (Ahead-of-Time compilation) compatibility validation across all MinimalLambda packages to ensure reliable native AOT support for optimal Lambda cold start performance.

Problem Statement

While MinimalLambda advertises AOT support and includes a HelloWorldAot example, there's no systematic validation ensuring AOT compatibility across the library packages. This creates risks of:

• Runtime failures when users enable AOT compilation
• Trim warnings that become runtime errors
• Missing type metadata for JSON serialization
• Undiscovered reflection usage that breaks AOT

Proposed Solution

Implement comprehensive AOT validation through:

1. Library package annotations
2. Static analysis with AOT analyzers
3. CI validation of AOT builds
4. Trim annotations where needed
5. Documentation of AOT requirements

Acceptance Criteria

1. Library Package Configuration

• Add <IsAotCompatible>true</IsAotCompatible> to all library projects:
  • MinimalLambda.csproj
  • MinimalLambda.Abstractions.csproj
  • MinimalLambda.OpenTelemetry.csproj
  • All envelope packages (MinimalLambda.Envelopes.*)
• Resolve any AOT analyzer warnings that appear

2. AOT Analyzer Integration

• Enable AOT compatibility analyzers in library projects
• Add to Directory.Build.props or individual project files:

  <EnableAOTAnalyzer>true</EnableAOTAnalyzer>
  <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
  <EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>

• Address all analyzer warnings (ideally zero warnings)

3. Trim Annotations

• Audit codebase for dynamic code usage (reflection, Type.GetType, etc.)
• Add appropriate trim annotations:
  • [DynamicallyAccessedMembers]
  • [RequiresUnreferencedCode]
  • [UnconditionalSuppressMessage] where safe
• Review HostFactoryResolver.cs (identified as using reflection)
• Ensure all reflection is guarded or documented

4. CI Validation

• Add CI workflow step to build HelloWorldAot example with AOT enabled
• Verify AOT builds complete without warnings
• Consider adding AOT build matrix for all envelope examples
• Fail CI if trim or AOT warnings are introduced

5. Documentation Updates

• Document AOT compatibility in main README
• Add AOT troubleshooting guide
• Document any known limitations or requirements
• Update each envelope package README with AOT guidance
• Provide example JsonSerializerContext for common scenarios

6. Testing Validation

• Verify HelloWorldAot example builds and runs
• Add at least one envelope example with AOT enabled
• Test common scenarios (API Gateway, SQS, etc.) with AOT
• Validate package size and cold start improvements

Technical Considerations

Known Reflection Usage

• src/MinimalLambda.Testing/HostFactoryResolver.cs - Uses Activator.CreateInstance, Type.GetType, etc.
  • Testing package may be exempt from AOT requirements
  • Consider adding <IsAotCompatible>false</IsAotCompatible> if necessary
  • Document why testing package isn't AOT-compatible

Dependencies

• Ensure all NuGet dependencies support AOT:
  • Amazon.Lambda.Core
  • Amazon.Lambda.RuntimeSupport
  • Amazon.Lambda.Serialization.SystemTextJson
  • Microsoft.Extensions.Hosting
  • OpenTelemetry packages

Breaking Changes

• Adding IsAotCompatible shouldn't break existing code
• May discover APIs that need [RequiresUnreferencedCode] annotation
• Document any newly discovered limitations

Implementation Tasks

Phase 1: Analysis

• Run AOT analyzers on all library projects
• Document all warnings and errors
• Categorize issues by severity and package

Phase 2: Annotations

• Add IsAotCompatible to project files
• Add trim annotations to problematic code paths
• Add RequiresUnreferencedCode where needed

Phase 3: CI Integration

• Create/update GitHub Actions workflow
• Add AOT build steps
• Configure warning-as-error for AOT builds

Phase 4: Validation

• Test all examples with AOT enabled
• Verify no runtime errors
• Measure package sizes and cold start times

Phase 5: Documentation

• Update main documentation
• Create AOT troubleshooting guide
• Add examples for common scenarios

Success Metrics

• ✅ All library packages marked with IsAotCompatible=true
• ✅ Zero AOT/trim analyzer warnings in library code
• ✅ CI builds validate AOT compatibility
• ✅ At least 2 working AOT examples (HelloWorldAot + one envelope)
• ✅ Documentation clearly explains AOT requirements

References

• .NET Native AOT Deployment
• Prepare .NET Libraries for Trimming
• AWS Lambda .NET Native AOT

Related Issues

None

Type

Story / Enhancement