Skip to content

Commit c7a5f6c

Browse files
j-d-haj-d-ha
committed
feat(docs): expand MkDocs configuration and enhance documentation content
- Fixed repository URL in MkDocs configuration. - Enabled advanced Material theme features like code copy, tabs, and footer navigation. - Added extensive Markdown and PyMdown extensions for enhanced content formatting. - Updated navigation structure, renaming "Home" to "Homepage" for improved clarity. - Revamped `docs/index.md` with detailed introduction, key features, quick start guide, and examples.
1 parent e34a557 commit c7a5f6c

2 files changed

Lines changed: 327 additions & 19 deletions

File tree

‎docs/index.md‎

Lines changed: 294 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,299 @@
1-
# Welcome to MkDocs
1+
# Build AWS Lambda Functions with .NET Hosting Patterns
22

3-
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
3+
[![Main Build](https://github.com/j-d-ha/aws-lambda-host/actions/workflows/main-build.yaml/badge.svg)](https://github.com/j-d-ha/aws-lambda-host/actions/workflows/main-build.yaml)
4+
[![codecov](https://codecov.io/gh/j-d-ha/aws-lambda-host/graph/badge.svg?token=BWORPTQ0UK)](https://codecov.io/gh/j-d-ha/aws-lambda-host)
5+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=j-d-ha_aws-lambda-host&metric=alert_status&token=9fb519975d91379dcfbc6c13a4bd4207131af6e3)](https://sonarcloud.io/summary/new_code?id=j-d-ha_aws-lambda-host)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/j-d-ha/aws-lambda-host/blob/main/LICENSE)
47

5-
## Commands
8+
A modern .NET framework that brings familiar ASP.NET Core patterns to AWS Lambda - middleware, dependency injection, and async-first design.
69

7-
* `mkdocs new [dir-name]` - Create a new project.
8-
* `mkdocs serve` - Start the live-reloading docs server.
9-
* `mkdocs build` - Build the documentation site.
10-
* `mkdocs -h` - Print help message and exit.
10+
[Get Started](getting-started/){ .md-button .md-button--primary }
11+
[View Examples](examples/){ .md-button }
1112

12-
## Project layout
13+
---
1314

14-
mkdocs.yml # The configuration file.
15-
docs/
16-
index.md # The documentation homepage.
17-
... # Other markdown pages, images and other files.
15+
## Why aws-lambda-host?
16+
17+
Stop writing boilerplate Lambda code. Start building features with patterns you already know.
18+
19+
=== "Traditional Lambda"
20+
21+
```csharp
22+
using Amazon.Lambda.RuntimeSupport;
23+
using Amazon.Lambda.Serialization.SystemTextJson;
24+
using Microsoft.Extensions.DependencyInjection;
25+
26+
// Manual DI container setup - must be done ONCE at startup
27+
var services = new ServiceCollection();
28+
services.AddScoped<IGreetingService, GreetingService>();
29+
var rootProvider = services.BuildServiceProvider();
30+
31+
// Capture service provider outside handler
32+
// ⚠️ Problem: Can't create scopes per invocation easily
33+
var service = rootProvider.GetRequiredService<IGreetingService>();
34+
35+
// Manual bootstrap initialization
36+
await LambdaBootstrapBuilder
37+
.Create<GreetingRequest, GreetingResponse>(
38+
async (request, context) =>
39+
{
40+
// ⚠️ Manual cancellation token creation from context
41+
using var cts = new CancellationTokenSource(
42+
context.RemainingTime - TimeSpan.FromMilliseconds(500)
43+
);
44+
45+
// ⚠️ Using singleton-scoped service for all invocations
46+
// No proper scoped lifetime per invocation!
47+
var greeting = await service.GreetAsync(request.Name, cts.Token);
48+
49+
return new GreetingResponse(greeting, DateTime.UtcNow);
50+
},
51+
new DefaultLambdaJsonSerializer()
52+
)
53+
.Build()
54+
.RunAsync();
55+
56+
// Models
57+
public record GreetingRequest(string Name);
58+
59+
public record GreetingResponse(string Message, DateTime Timestamp);
60+
61+
// Service interface and implementation
62+
public interface IGreetingService
63+
{
64+
Task<string> GreetAsync(string name, CancellationToken cancellationToken);
65+
}
66+
67+
public class GreetingService : IGreetingService
68+
{
69+
public async Task<string> GreetAsync(string name, CancellationToken cancellationToken)
70+
{
71+
await Task.Delay(10, cancellationToken); // Simulate async work
72+
return $"Hello {name}!";
73+
}
74+
}
75+
```
76+
77+
=== "aws-lambda-host"
78+
79+
```csharp
80+
using AwsLambda.Host.Builder;
81+
using Microsoft.Extensions.DependencyInjection;
82+
using Microsoft.Extensions.Hosting;
83+
84+
var builder = LambdaApplication.CreateBuilder();
85+
86+
// Register services with DI
87+
builder.Services.AddScoped<IGreetingService, GreetingService>();
88+
89+
var lambda = builder.Build();
90+
91+
// ✅ Clean handler with automatic DI and cancellation token injection
92+
lambda.MapHandler(
93+
async (
94+
[Event] GreetingRequest request,
95+
IGreetingService service,
96+
CancellationToken cancellationToken
97+
) =>
98+
{
99+
// ✅ Cancellation token automatically provided by the framework
100+
var greeting = await service.GreetAsync(request.Name, cancellationToken);
101+
return new GreetingResponse(greeting, DateTime.UtcNow);
102+
}
103+
);
104+
105+
await lambda.RunAsync();
106+
107+
// Models
108+
public record GreetingRequest(string Name);
109+
110+
public record GreetingResponse(string Message, DateTime Timestamp);
111+
112+
// Service interface and implementation
113+
public interface IGreetingService
114+
{
115+
Task<string> GreetAsync(string name, CancellationToken cancellationToken);
116+
}
117+
118+
public class GreetingService : IGreetingService
119+
{
120+
public async Task<string> GreetAsync(string name, CancellationToken cancellationToken)
121+
{
122+
await Task.Delay(10, cancellationToken); // Simulate async work
123+
return $"Hello {name}!";
124+
}
125+
}
126+
```
127+
128+
---
129+
130+
## Key Features
131+
132+
### :material-view-dashboard-outline: .NET Hosting Patterns
133+
134+
Use middleware, builder pattern, and dependency injection similar to ASP.NET Core, with proper scoped lifetime management per invocation.
135+
136+
[Learn about DI](guides/dependency-injection.md){ .md-button }
137+
138+
### :material-lightning-bolt-outline: Async-First Design
139+
140+
Native support for async/await with proper Lambda timeout and cancellation handling built-in.
141+
142+
[See lifecycle management](guides/lifecycle-management.md){ .md-button }
143+
144+
### :material-code-braces: Source Generators & Interceptors
145+
146+
Compile-time code generation and method interception for optimal performance with zero runtime reflection.
147+
148+
[Explore advanced topics](advanced/source-generators.md){ .md-button }
149+
150+
### :material-rocket-launch-outline: AOT Ready
151+
152+
Full support for Ahead-of-Time compilation for faster cold starts and reduced memory footprint.
153+
154+
[AOT compilation guide](advanced/aot-compilation.md){ .md-button }
155+
156+
### :material-chart-line: Built-in Observability
157+
158+
OpenTelemetry integration for distributed tracing with automatic root span creation and custom instrumentation.
159+
160+
[OpenTelemetry setup](features/opentelemetry.md){ .md-button }
161+
162+
### :material-code-json: Flexible Handler Registration
163+
164+
Simple, declarative API for mapping Lambda event types to handlers with compile-time type safety.
165+
166+
[Handler registration](guides/handler-registration.md){ .md-button }
167+
168+
### :material-speedometer: Minimal Runtime Overhead
169+
170+
No unnecessary abstractions - efficient use of Lambda resources with optimized execution paths.
171+
172+
[Performance optimization](advanced/performance-optimization.md){ .md-button }
173+
174+
---
175+
176+
## Quick Start
177+
178+
Install the NuGet package:
179+
180+
```bash
181+
dotnet add package AwsLambda.Host
182+
```
183+
184+
Create your first Lambda handler:
185+
186+
```csharp
187+
using AwsLambda.Host.Builder;
188+
using Microsoft.Extensions.DependencyInjection;
189+
190+
// Create the application builder
191+
var builder = LambdaApplication.CreateBuilder();
192+
193+
// Register your services
194+
builder.Services.AddScoped<IGreetingService, GreetingService>();
195+
196+
// Build the Lambda application
197+
var lambda = builder.Build();
198+
199+
// Map your handler - services are automatically injected
200+
lambda.MapHandler(([Event] string input, IGreetingService greeting)
201+
=> greeting.Greet(input));
202+
203+
// Run the Lambda
204+
await lambda.RunAsync();
205+
206+
// Define your service
207+
public interface IGreetingService
208+
{
209+
string Greet(string name);
210+
}
211+
212+
public class GreetingService : IGreetingService
213+
{
214+
public string Greet(string name) => $"Hello {name}!";
215+
}
216+
```
217+
218+
!!! tip "Next Steps"
219+
Ready to dive deeper? Check out the [Getting Started Guide](getting-started/) for a complete tutorial, or explore the [Examples](examples/) to see real-world applications.
220+
221+
---
222+
223+
## Packages
224+
225+
### Core Packages
226+
227+
The core packages provide the fundamental hosting framework, abstractions, and observability support for building AWS Lambda functions.
228+
229+
| Package | Description | NuGet | Downloads |
230+
|---------|-------------|-------|-----------|
231+
| [**AwsLambda.Host**](api-reference/host.md) | Core hosting framework with middleware and DI | [![NuGet](https://img.shields.io/nuget/v/AwsLambda.Host.svg)](https://www.nuget.org/packages/AwsLambda.Host) | [![Downloads](https://img.shields.io/nuget/dt/AwsLambda.Host.svg)](https://www.nuget.org/packages/AwsLambda.Host/) |
232+
| [**AwsLambda.Host.Abstractions**](api-reference/abstractions.md) | Core interfaces and contracts | [![NuGet](https://img.shields.io/nuget/v/AwsLambda.Host.Abstractions.svg)](https://www.nuget.org/packages/AwsLambda.Host.Abstractions) | [![Downloads](https://img.shields.io/nuget/dt/AwsLambda.Host.Abstractions.svg)](https://www.nuget.org/packages/AwsLambda.Host.Abstractions/) |
233+
| [**AwsLambda.Host.OpenTelemetry**](features/opentelemetry.md) | Distributed tracing and observability | [![NuGet](https://img.shields.io/nuget/v/AwsLambda.Host.OpenTelemetry.svg)](https://www.nuget.org/packages/AwsLambda.Host.OpenTelemetry) | [![Downloads](https://img.shields.io/nuget/dt/AwsLambda.Host.OpenTelemetry.svg)](https://www.nuget.org/packages/AwsLambda.Host.OpenTelemetry/) |
234+
235+
### Envelope Packages
236+
237+
Envelope packages provide type-safe handling of AWS Lambda event sources with automatic payload deserialization.
238+
239+
!!! info "What are Envelopes?"
240+
Envelopes wrap AWS Lambda events with strongly-typed payload handling, giving you compile-time type safety and automatic deserialization of message bodies from SQS, SNS, Kinesis, and other event sources.
241+
242+
[Learn more about envelopes](features/envelopes/){ .md-button }
243+
244+
Available envelope packages:
245+
246+
- [**SQS**](features/envelopes/sqs.md) - Simple Queue Service events with typed message bodies
247+
- [**SNS**](features/envelopes/sns.md) - Simple Notification Service messages
248+
- [**API Gateway**](features/envelopes/api-gateway.md) - REST, HTTP, and WebSocket APIs
249+
- [**Kinesis**](features/envelopes/kinesis.md) - Data Streams with typed records
250+
- [**Kinesis Firehose**](features/envelopes/kinesis-firehose.md) - Data transformation
251+
- [**Kafka**](features/envelopes/kafka.md) - MSK and self-managed Kafka
252+
- [**CloudWatch Logs**](features/envelopes/cloudwatch-logs.md) - Log subscriptions
253+
- [**ALB**](features/envelopes/alb.md) - Application Load Balancer requests
254+
255+
[Browse all envelope packages](features/envelopes/){ .md-button }
256+
257+
---
258+
259+
## Examples & Use Cases
260+
261+
Explore complete example projects demonstrating real-world Lambda patterns:
262+
263+
- **[Hello World](examples/hello-world.md)** - Basic Lambda with dependency injection and middleware
264+
- **[REST API](examples/api-rest.md)** - API Gateway integration with request/response handling
265+
- **[SQS Processing](examples/sqs-processing.md)** - Event-driven message processing
266+
- **[OpenTelemetry](examples/opentelemetry-example.md)** - Full observability with distributed tracing
267+
- **[AOT Compilation](examples/aot-example.md)** - Native AOT for optimal cold start performance
268+
269+
[View all examples](examples/){ .md-button }
270+
271+
---
272+
273+
## Community & Resources
274+
275+
### Get Involved
276+
277+
- **[GitHub Repository](https://github.com/j-d-ha/aws-lambda-host)** - Source code, issues, and discussions
278+
- **[Changelog](resources/changelog.md)** - Version history and release notes
279+
- **[License](https://github.com/j-d-ha/aws-lambda-host/blob/main/LICENSE)** - MIT License
280+
281+
### Documentation
282+
283+
- **[Getting Started](getting-started/)** - Installation and first Lambda tutorial
284+
- **[Guides](guides/)** - Comprehensive feature documentation
285+
- **[Features](features/)** - Envelopes and OpenTelemetry integration
286+
- **[API Reference](api-reference/)** - Detailed API documentation
287+
- **[Advanced Topics](advanced/)** - AOT, source generators, and performance
288+
289+
### Support
290+
291+
Need help or want to contribute?
292+
293+
- Browse the [FAQ](resources/faq.md) for common questions
294+
- Check the [Troubleshooting Guide](resources/troubleshooting.md) for solutions
295+
- Visit the [Community Page](resources/community.md) for support channels
296+
297+
---
298+
299+
**Ready to modernize your Lambda development?** [Get started now](getting-started/){ .md-button .md-button--primary }

‎mkdocs.yml‎

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,44 @@ site_url: https://j-d-ha.github.io/aws-lambda-host/
88
site_author: Jonas Ha
99

1010
repo_name: j-d-ha/aws-lambda-host
11-
repo_url: hhttps://github.com/j-d-ha/aws-lambda-host
11+
repo_url: https://github.com/j-d-ha/aws-lambda-host
1212
edit_uri: edit/main/docs/
1313

1414
theme:
1515
name: material
16-
16+
features:
17+
- content.code.copy
18+
- content.tabs.link
19+
- navigation.footer
20+
- navigation.top
21+
22+
markdown_extensions:
23+
# Python Markdown extensions
24+
- attr_list
25+
- md_in_html
26+
- tables
27+
28+
# PyMdown Extensions
29+
- pymdownx.emoji:
30+
emoji_index: !!python/name:material.extensions.emoji.twemoji
31+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
32+
- pymdownx.highlight:
33+
anchor_linenums: true
34+
line_spans: __span
35+
pygments_lang_class: true
36+
- pymdownx.inlinehilite
37+
- pymdownx.snippets
38+
- pymdownx.superfences
39+
- pymdownx.tabbed:
40+
alternate_style: true
41+
- pymdownx.details
42+
- admonition
43+
1744
watch:
18-
- docs
19-
- mkdocs.yml
20-
45+
- ./docs/
46+
2147
nav:
22-
- Home: index.md
23-
48+
- Homepage : index.md
49+
2450
plugins:
2551
- search

0 commit comments

Comments
 (0)