feat(host): add ILambdaLifecycleContext for lifecycle handlers

[j-d-ha]

🚀 Pull Request

📋 Summary

This PR introduces ILambdaLifecycleContext to provide rich context and dependency injection capabilities for OnInit and OnShutdown lifecycle handlers. This replaces the previous (IServiceProvider, CancellationToken) delegate pattern with a more extensible, source-generated DI approach that mirrors the invocation handler pattern.

Key Changes

1. New ILambdaLifecycleContext Interface

• Provides AWS environment metadata (function name, region, memory, initialization type, etc.)
• Includes a thread-safe Properties dictionary for sharing state between handlers
• Exposes scoped ServiceProvider and CancellationToken
• Located in MinimalLambda.Abstractions for broad accessibility

2. Updated Handler Signatures

// Before
lambda.OnInit(async (IServiceProvider services, CancellationToken ct) => { ... });

// After - Direct DI (recommended)
lambda.OnInit(async (ICache cache, ILogger logger, CancellationToken ct) => { ... });

// After - With context for AWS metadata
lambda.OnInit(async (ILambdaLifecycleContext context, ICache cache) => { ... });

3. Source-Generated Dependency Injection

• OnInit and OnShutdown handlers now support the same DI patterns as invocation handlers
• Direct service injection without manual IServiceProvider resolution
• Keyed services via [FromKeyedServices("key")] attribute
• Mixed patterns combining context and services

4. Comprehensive Documentation

• Updated lifecycle management guide with ILambdaLifecycleContext usage patterns
• Enhanced dependency injection guide with lifecycle handler examples
• Added context access section to core concepts
• Documented all 13 context properties with descriptions

5. Extensive Test Coverage

• Added unit tests for ILambdaLifecycleContext and factory
• Updated all lifecycle handler tests to use new signatures
• Source generator snapshot tests updated

---

✅ Checklist

• My changes build cleanly
• I've added/updated relevant tests
• I've added/updated documentation or README
• I've followed the coding style for this project
• I've tested the changes locally (if applicable)

---

🧪 Related Issues or PRs

Closes #236

---

💬 Notes for Reviewers

Breaking Changes

This is a breaking change for existing OnInit/OnShutdown handlers:

• Handler signatures changed from (IServiceProvider, CancellationToken) to source-generated DI
• Migration is straightforward: replace services.GetRequiredService<T>() with direct parameter injection

Key Files to Review

Core Implementation:

• src/MinimalLambda.Abstractions/Core/ILambdaLifecycleContext.cs - New interface definition
• src/MinimalLambda/Core/Context/LambdaLifecycleContext.cs - Implementation with AWS env var reading
• src/MinimalLambda/Core/Context/LambdaLifecycleContextFactory.cs - Factory for creating contexts

Builder Updates:

• src/MinimalLambda/Builder/LambdaOnInitBuilder.cs - Updated to use context factory
• src/MinimalLambda/Builder/LambdaOnShutdownBuilder.cs - Updated to use context factory
• Both builders now expose Properties dictionary for state sharing

Source Generators:

• src/MinimalLambda.SourceGenerators/SyntaxProviders/OnInitSyntaxProvider.cs
• src/MinimalLambda.SourceGenerators/SyntaxProviders/OnShutdownSyntaxProvider.cs
• Updated to support ILambdaLifecycleContext and new parameter sources

Documentation:

• docs/guides/lifecycle-management.md - Comprehensive guide with examples
• docs/guides/dependency-injection.md - DI patterns for lifecycle handlers
• docs/getting-started/core-concepts.md - Introductory overview

AWS Environment Properties

All AWS environment metadata is read from standard Lambda environment variables:

• Nullable types used because not all variables are available in all scenarios (e.g., SnapStart)
• Properties are read lazily on first access
• Thread-safe implementation for concurrent handler execution

Properties Dictionary

The Properties dictionary enables:

• Data sharing between OnInit handlers (runs concurrently)
• Passing initialization data to invocation handlers via ILambdaHostContext.Properties
• Thread-safe ConcurrentDictionary backing

Migration Path

Existing code using old pattern:

lambda.OnInit(async (IServiceProvider services, CancellationToken ct) =>
{
    var cache = services.GetRequiredService<ICache>();
    await cache.WarmUpAsync(ct);
    return true;
});

Migrates to:

lambda.OnInit(async (ICache cache, CancellationToken ct) =>
{
    await cache.WarmUpAsync(ct);
    return true;
});

For advanced scenarios needing AWS metadata:

lambda.OnInit(async (ILambdaLifecycleContext context, ICache cache) =>
{
    var logger = context.ServiceProvider.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Init type: {Type}, Memory: {MB}MB", 
        context.InitializationType, context.FunctionMemorySize);
    await cache.WarmUpAsync(context.CancellationToken);
    return true;
});

[sonarqubecloud]

Quality Gate passed

Issues
12 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../MinimalLambda/Builder/LambdaApplicationBuilder.cs	33.33%	2 Missing and 2 partials ⚠️
src/MinimalLambda/Builder/LambdaOnInitBuilder.cs	81.81%	4 Missing ⚠️
...nerators/OutputGenerators/GenericHandlerSources.cs	70.00%	1 Missing and 2 partials ⚠️

@@            Coverage Diff             @@
##             main     #252      +/-   ##
==========================================
+ Coverage   88.23%   88.37%   +0.13%     
==========================================
  Files         127      130       +3     
  Lines        2993     3115     +122     
  Branches      337      344       +7     
==========================================
+ Hits         2641     2753     +112     
- Misses        219      229      +10     
  Partials      133      133              

Files with missing lines	Coverage Δ
...OpenTelemetry/OnShutdownOpenTelemetryExtensions.cs	100.00% <100.00%> (ø)
...rceGenerators/Extensions/DelegateInfoExtensions.cs	100.00% <100.00%> (ø)
...malLambda.SourceGenerators/Models/ParameterInfo.cs	97.87% <100.00%> (+2.22%)	⬆️
...ceGenerators/OutputGenerators/MapHandlerSources.cs	97.93% <100.00%> (ø)
...Generators/SyntaxProviders/OnInitSyntaxProvider.cs	100.00% <100.00%> (ø)
...rators/SyntaxProviders/OnShutdownSyntaxProvider.cs	100.00% <100.00%> (ø)
...ambda/Builder/DefaultLambdaOnInitBuilderFactory.cs	100.00% <100.00%> (ø)
...a/Builder/DefaultLambdaOnShutdownBuilderFactory.cs	100.00% <100.00%> (ø)
.../Builder/Extensions/ServiceCollectionExtensions.cs	100.00% <100.00%> (ø)
src/MinimalLambda/Builder/LambdaApplication.cs	97.61% <100.00%> (+0.11%)	⬆️
... and 9 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 80eaff3...e6894de. 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.