refactor(core): refactor lambda application and builder

[j-d-ha]

Summary

This PR represents a major architectural refactoring of the aws-lambda-host framework, replacing the monolithic ILambdaApplication interface with specialized builder interfaces (ILambdaInvocationBuilder, ILambdaOnInitBuilder, ILambdaOnShutdownBuilder) that provide clearer separation of concerns. The refactoring includes comprehensive unit tests, improved feature collection architecture, and enhanced lifecycle management.

Key improvements:

• Clearer API surface with three specialized builder interfaces instead of a single monolithic interface
• Comprehensive unit test coverage across all builder, context, and feature classes
• Enhanced feature collection system for accessing invocation-scoped and shared data
• Improved lifecycle management with dedicated initialization and shutdown builders
• Simplified namespace structure and better internal organization
• Complete documentation updates reflecting the new architecture

Test Coverage: 67 new unit test classes with 2,000+ test cases added, covering:

• Builder factories and composition
• Context and service management
• Feature collection and access patterns
• Lifecycle handlers and orchestration
• Middleware and extension integration

---

Breaking Changes

1. ILambdaApplication Removed (BREAKING)

Removed in: refactor(abstractions): remove ILambdaApplication and update namespaces

The ILambdaApplication interface has been removed from AwsLambda.Host.Abstractions. This interface was the previous monolithic API for all Lambda configuration.

Migration:
Replace ILambdaApplication references with the appropriate specialized builder interface:

• For handler registration → ILambdaInvocationBuilder
• For initialization handlers → ILambdaOnInitBuilder
• For shutdown handlers → ILambdaOnShutdownBuilder

Before:

var app = LambdaApplication.CreateBuilder()
    .ConfigureServices(services => { /* ... */ })
    .Build();

// Single interface for all operations
app.Handle(handler);
app.OnInit(initHandler);
app.OnShutdown(shutdownHandler);

After:

var app = LambdaApplication.CreateBuilder()
    .ConfigureServices(services => { /* ... */ })
    .Build();

// Specialized interfaces for each concern
var invocationBuilder = (ILambdaInvocationBuilder)app;
var initBuilder = (ILambdaOnInitBuilder)app;
var shutdownBuilder = (ILambdaOnShutdownBuilder)app;

invocationBuilder.Handle(handler);
initBuilder.OnInit(initHandler);
shutdownBuilder.OnShutdown(shutdownHandler);

2. Namespace Reorganization (BREAKING)

Affected in: Multiple commits organizing features and builder types into logical namespaces

Core types have been reorganized into dedicated namespaces:

Old Namespace	New Namespace
AwsLambda.Host.*	AwsLambda.Host.Builder.*
AwsLambda.Host.*	AwsLambda.Host.Core.Features.*
AwsLambda.Host.*	AwsLambda.Host.Core.Context.*
AwsLambda.Host.*	AwsLambda.Host.Core.Options.*
AwsLambda.Host.*	AwsLambda.Host.Core.Runtime.*

Global Usings have been added to simplify imports:

• AwsLambda.Host.Abstractions in AwsLambda.Host.Abstractions/GlobalUsings.cs
• AwsLambda.Host.Builder, AwsLambda.Host.Core.* in AwsLambda.Host/GlobalUsings.cs

3. ILambdaCancellationFactory Moved to Core (BREAKING)

Moved in: refactor(core): rename IOnInitBuilderFactorytoILambdaOnInitBuilderFactory``

Moved from AwsLambda.Host.Abstractions → AwsLambda.Host.Abstractions.Core

Update imports:

// Before
using AwsLambda.Host.Abstractions;

// After
using AwsLambda.Host.Abstractions.Core;

4. Handler Delegate Signatures Unchanged

Handler delegates remain compatible:

• LambdaInvocationDelegate(ILambdaHostContext context) : Task
• LambdaInitDelegate(IServiceProvider, CancellationToken) : Task<bool>
• LambdaShutdownDelegate(IServiceProvider, CancellationToken) : Task

5. Builder Factory Interface Renames (BREAKING)

Renamed in: refactor(core): rename interface names for consistency

Factory interfaces now follow a consistent naming pattern:

Old Name	New Name
IInvocationBuilderFactory	ILambdaInvocationBuilderFactory
IOnInitBuilderFactory	ILambdaOnInitBuilderFactory
IOnShutdownBuilderFactory	ILambdaOnShutdownBuilderFactory

These are internal interfaces but if you have custom implementations, update references accordingly.

6. Feature Collection Architecture (BREAKING)

Added in: feat(host): implement feature collection factory pattern

The feature collection system has been redesigned:

• IFeatureCollection now requires feature providers
• IEventFeature<T> and IResponseFeature<T> provide strongly-typed access
• Feature providers are registered through IFeatureProvider

Before:

// Limited feature support
var context = await GetContext();

After:

// Rich feature access through feature collection
var context = await GetContext();
var eventFeature = context.Features.Get<IEventFeature<MyEvent>>();
var responseFeature = context.Features.Get<IResponseFeature<MyResponse>>();

// Or use convenience methods
var @event = context.GetRequiredEvent<MyEvent>();
var response = context.GetRequiredResponse<MyResponse>();

7. Context Extension Methods Updated (BREAKING)

Changed in: feat(core): add GetRequiredEvent<T> and GetRequiredResponse<T> to Lambda context extensions

New convenience methods added to ILambdaHostContext:

• GetRequiredEvent<T>() – Get strongly-typed event data
• GetRequiredResponse<T>() – Get strongly-typed response data

These are extensions, so existing context.Items and context.Properties access remain unchanged.

8. OpenTelemetry Namespace Updates (BREAKING)

Changed in: refactor(core): update namespaces in OpenTelemetry extensions

OpenTelemetry extensions now in dedicated namespace:

// Before
using AwsLambda.Host.OpenTelemetry;

// After
using AwsLambda.Host.OpenTelemetry.Extensions;

9. Removed Obsolete Types (BREAKING)

• ILambdaLifecycleOrchestrator – Removed; functionality replaced by builder factories
• LambdaLifecycleOrchestrator – Removed; internal implementation detail
• LambdaApplication (old class) – Replaced with new builder-focused implementation

---

Changes Summary

Builder Architecture

• ✅ Added ILambdaInvocationBuilder for handler and middleware configuration
• ✅ Added ILambdaOnInitBuilder for initialization handler management
• ✅ Added ILambdaOnShutdownBuilder for shutdown handler management
• ✅ Added dedicated factory implementations for each builder type
• ✅ Refactored LambdaApplication to implement all three builder interfaces

Feature Collection System

• ✅ Implemented IFeatureCollection and DefaultFeatureCollection
• ✅ Added IFeatureProvider for pluggable feature management
• ✅ Created DefaultEventFeature<T> and DefaultResponseFeature<T> for strongly-typed data access
• ✅ Added factory pattern with IFeatureCollectionFactory

Context and Lifecycle

• ✅ Enhanced ILambdaHostContext with feature access
• ✅ Added convenience methods GetRequiredEvent<T>() and GetRequiredResponse<T>()
• ✅ Improved DefaultLambdaHostContext implementation
• ✅ Enhanced cancellation handling with DefaultLambdaCancellationFactory

Service Integration

• ✅ Added ServiceCollectionExtensions for fluent service registration
• ✅ Added HostOptionsPostConfiguration for options binding
• ✅ Improved DI integration across builder phases

Code Organization

• ✅ Moved builder types to AwsLambda.Host.Builder namespace
• ✅ Moved context/features to AwsLambda.Host.Core namespace
• ✅ Organized tests into logical folder structure
• ✅ Added global usings for cleaner imports

Test Coverage

• ✅ 67 new unit test classes
• ✅ Comprehensive builder factory tests
• ✅ Context and feature collection tests
• ✅ Lifecycle handler tests
• ✅ Extension method tests
• ✅ Middleware and service integration tests
• ✅ Runtime and bootstrap tests

Documentation

• ✅ Updated CLAUDE.md with testing guidelines
• ✅ Updated abstractions README with new architecture
• ✅ Updated host README with builder API details
• ✅ Enhanced envelope and OpenTelemetry documentation
• ✅ Added XML documentation for public APIs

---

Checklist

• My changes build cleanly
• I've added/updated relevant tests (67 new unit test classes)
• I've added/updated documentation or README
• I've followed the coding style for this project
• I've tested the changes locally

---

Related Issues

Closes #99

---

Migration Guide

For a complete migration guide from the old API to the new builder-based architecture, see:

• AwsLambda.Host README – Updated examples and patterns
• AwsLambda.Host.Abstractions README – New architecture details
• CLAUDE.md – Testing guidelines and conventions

---

Notes for Reviewers

Key areas to review:

1. Builder Pattern Implementation – Verify the three builder interfaces provide clear separation of concerns
2. Feature Collection System – Review the feature provider architecture and access patterns
3. Test Coverage – Examine the new unit tests, especially around lifecycle and context management
4. Namespace Organization – Confirm the new structure is logical and follows conventions
5. Backward Compatibility – Note this is a major refactoring with breaking changes documented above
6. Documentation – Ensure READMEs accurately reflect the new APIs and migration path

Known considerations:

• This refactoring removes the monolithic ILambdaApplication in favor of specialized builder interfaces
• All three packages are versioned together, so this will be a major version bump
• Example projects have been updated to demonstrate the new API patterns
• Source generators have been updated to work with the new builder factories

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 33 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...SyntaxProviders/Extractors/HandlerInfoExtractor.cs	80.00%	3 Missing and 7 partials ⚠️
...st/Builder/Middleware/RequestEnvelopeMiddleware.cs	23.07%	10 Missing ⚠️
...c/AwsLambda.Host/Runtime/LambdaBootstrapAdapter.cs	0.00%	4 Missing ⚠️
...ers/LambdaApplicationBuilderBuildSyntaxProvider.cs	93.93%	1 Missing and 1 partial ⚠️
...bda.Host/Core/Features/DefaultFeatureCollection.cs	88.88%	1 Missing and 1 partial ⚠️
...rc/AwsLambda.Host/Runtime/LambdaHandlerComposer.cs	94.73%	1 Missing and 1 partial ⚠️
...a.Host.SourceGenerators/Models/SimpleMethodInfo.cs	0.00%	1 Missing ⚠️
src/AwsLambda.Host/Builder/LambdaApplication.cs	97.50%	0 Missing and 1 partial ⚠️
src/AwsLambda.Host/Runtime/LambdaHostedService.cs	96.55%	0 Missing and 1 partial ⚠️

@@             Coverage Diff             @@
##             main     #163       +/-   ##
===========================================
+ Coverage   80.26%   90.70%   +10.43%     
===========================================
  Files          60       74       +14     
  Lines        1728     1990      +262     
  Branches      202      226       +24     
===========================================
+ Hits         1387     1805      +418     
+ Misses        254       95      -159     
- Partials       87       90        +3     

Files with missing lines	Coverage Δ
...Lambda.Host.Abstractions/Core/RawInvocationData.cs	100.00% <100.00%> (ø)
...ambda.Host.Abstractions/Options/EnvelopeOptions.cs	100.00% <ø> (ø)
....Host.OpenTelemetry/LambdaOpenTelemetryAdapters.cs	100.00% <100.00%> (ø)
...OpenTelemetry/OnShutdownOpenTelemetryExtensions.cs	100.00% <100.00%> (ø)
...SourceGenerators/MapHandlerIncrementalGenerator.cs	95.83% <100.00%> (-4.17%)	⬇️
...da.Host.SourceGenerators/Models/CompilationInfo.cs	100.00% <100.00%> (ø)
...ambda.Host.SourceGenerators/Models/DelegateInfo.cs	93.75% <100.00%> (ø)
...nerators/OutputGenerators/GenericHandlerSources.cs	98.01% <100.00%> (+0.01%)	⬆️
...tors/OutputGenerators/LambdaHostOutputGenerator.cs	100.00% <100.00%> (ø)
...ceGenerators/OutputGenerators/MapHandlerSources.cs	97.29% <100.00%> (+0.23%)	⬆️
... and 44 more

... and 2 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 44f989d...cfe5f90. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
4 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud