AwsLambda.Host.Abstractions 1.0.0-beta.2

AwsLambda.Host.Abstractions

Core interfaces and abstractions for the aws-lambda-host framework.

⚠️ Development Status: This project is actively under development and not yet production-ready. Breaking changes may occur in future versions. Use at your own discretion in production environments.

Overview

Core interfaces and delegates that define the AwsLambda.Host framework contract. This package provides:

• Handler Abstractions: Interfaces for Lambda request and response handling across different event types
• Envelope Abstractions: Contracts for extracting request payloads and packing response payloads
• Middleware Contracts: Abstractions for building and composing middleware components
• Dependency Injection: Service container and lifetime management interfaces
• Extension Points: Contracts for custom integrations and framework extensions

This package is typically used implicitly by AwsLambda.Host, but is essential if you're building custom integrations, middleware components, or extensions to the framework.

Packages

The framework is divided into focused packages:

Package	NuGet	Downloads
AwsLambda.Host
AwsLambda.Host.Abstractions
AwsLambda.Host.OpenTelemetry

Installation

Install via NuGet:

dotnet add package AwsLambda.Host.Abstractions

Or specify a version:

dotnet add package AwsLambda.Host.Abstractions --version <version>

Ensure your project uses C# 11 or later:

<PropertyGroup>
  <LangVersion>11</LangVersion>
  
</PropertyGroup>

Note: This package is typically included automatically when you use AwsLambda.Host. Direct installation is only necessary when building custom integrations or extensions.

Core Abstractions

ILambdaApplication

The main builder interface for configuring a Lambda application using a fluent pattern:

• MapHandler() – Register the Lambda invocation handler
• Use() – Add middleware to the pipeline
• OnInit() – Register initialization handlers
• OnShutdown() – Register shutdown handlers

See AwsLambda.Host for usage examples.

ILambdaHostContext

Encapsulates a single Lambda invocation:

• Event – The deserialized Lambda event
• Response – The handler's response to return
• ServiceProvider – Access to the scoped DI container
• Items – Key/value collection for invocation-scoped data
• CancellationToken – Cancellation signal from Lambda timeout

ILambdaCancellationTokenSourceFactory

Provides a factory for creating cancellation token sources configured for AWS Lambda invocations:

• NewCancellationTokenSource(ILambdaContext) – Creates a CancellationTokenSource that cancels before the Lambda function timeout, allowing time for graceful shutdown

This interface enables custom implementations for managing cancellation tokens with respect to Lambda's remaining execution time. The default implementation applies a configurable buffer duration to ensure operations complete before the Lambda runtime's hard timeout.

Envelope Abstractions

IRequestEnvelope

Defines a contract for extracting and deserializing incoming Lambda event payloads. Implementations extract the inner payload from the outer Lambda event structure and deserialize it for handler processing.

IResponseEnvelope

Defines a contract for serializing and packing handler results into Lambda response structures. Implementations serialize the handler result and place it in the appropriate location within the outer response structure.

These abstractions enable strongly-typed handling of AWS Lambda events (like API Gateway, SQS) with automatic payload extraction and response packing. See the envelope packages for concrete implementations.

Handler Delegates

LambdaInvocationDelegate

Task LambdaInvocationDelegate(ILambdaHostContext context)

Processes a Lambda invocation.

LambdaInitDelegate

Task<bool> LambdaInitDelegate(IServiceProvider services, CancellationToken cancellationToken)

Runs once during initialization. Return true to continue, false to abort.

LambdaShutdownDelegate

Task LambdaShutdownDelegate(IServiceProvider services, CancellationToken cancellationToken)

Runs once during shutdown for cleanup.

Lambda Lifecycle

The abstractions represent three Lambda execution phases:

• Init – LambdaInitDelegate runs once during function initialization
• Invocation – LambdaInvocationDelegate runs for each event
• Shutdown – LambdaShutdownDelegate runs once before termination

For implementation details and examples, see AwsLambda.Host.

Related Packages

• AwsLambda.Host – Core Lambda framework with middleware and DI
• AwsLambda.Host.OpenTelemetry – OpenTelemetry integration for distributed tracing
• Root README – Project overview and examples

Documentation

• Full Project Documentation – Comprehensive guides and patterns
• Examples – Sample Lambda functions demonstrating framework patterns

Contributing

Contributions are welcome! Please check the GitHub repository for contribution guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.