Skip to content

Commit d7c9e09

Browse files
NinjaRocksNinjaRocks
committed
- Update documentation and projects for release
1 parent 6629ce3 commit d7c9e09

8 files changed

Lines changed: 265 additions & 44 deletions

File tree

‎Images/event-icon.png‎

12.6 KB
Loading

‎README.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# <img src="https://github.com/CodeShayk/SourceFlow.Net/blob/master/Images/complete-logo.png" alt="code-shayk" style="width:30px;"/> SourceFlow.Net
1+
# <img src="https://github.com/CodeShayk/SourceFlow.Net/blob/master/Images/event-icon.png" alt="event" style="width:50px;"/> SourceFlow.Net v2.0.0
22
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/CodeShayk/SourceFlow.Net/blob/master/LICENSE.md)
33
[![GitHub Release](https://img.shields.io/github/v/release/CodeShayk/SourceFlow.Net?logo=github&sort=semver)](https://github.com/CodeShayk/SourceFlow.Net/releases/latest)
44
[![master-build](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-Build.yml/badge.svg)](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-Build.yml)
@@ -91,18 +91,19 @@ Click on **[Architecture](https://github.com/CodeShayk/SourceFlow.Net/blob/maste
9191

9292
| Package | Version | Release Date |Details |.Net Frameworks|
9393
|------|---------|--------------|--------|-----------|
94-
|SourceFlow|v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Net.svg)](https://badge.fury.io/nu/SourceFlow.Net)|(TBC)|Core functionality with integrated cloud abstractions. Cloud.Core consolidated into main package. Breaking changes: namespace updates from SourceFlow.Cloud.Core.* to SourceFlow.Cloud.*|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md) [![.Net Framework 4.6.2](https://img.shields.io/badge/.Net-4.6.2-blue)](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net46)|
94+
|SourceFlow|v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Net.svg)](https://badge.fury.io/nu/SourceFlow.Net)|15th Mar 2026|v1.0.0 Core functionality with integrated cloud abstractions. Cloud.Core consolidated into main package. Breaking changes: namespace updates from SourceFlow.Cloud.Core.* to SourceFlow.Cloud.*|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)|
9595
|SourceFlow|v1.0.0|29th Nov 2025|Initial stable release with event sourcing and CQRS|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md) [![.Net Framework 4.6.2](https://img.shields.io/badge/.Net-4.6.2-blue)](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net46)|
96-
|SourceFlow.Stores.EntityFramework|v1.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework.svg)](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework)|29th Nov 2025|Provides store implementation using EF. Can configure different (types of ) databases for each store.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)|
97-
|SourceFlow.Cloud.AWS|v2.0.0 |(TBC) |Provides support for AWS cloud with cross domain boundary command and Event publishing & subscription. Includes comprehensive testing framework with LocalStack integration, performance benchmarks, security validation, and resilience testing.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)|
96+
|SourceFlow.Stores.EntityFramework|v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework.svg)](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework)|29th Nov 2025|v1.0.0 Core EF store implementations with new cloud idempotency provider implementation. |[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)|
97+
|SourceFlow.Stores.EntityFramework|v1.0.0 |29th Nov 2025|Provides store implementation using EF. Can configure different (types of ) databases for each store.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)|
98+
|SourceFlow.Cloud.AWS|v2.0.0 |15th Mar 2026 |Provides support for AWS cloud with cross domain boundary command and Event publishing & subscription. Includes comprehensive testing framework with LocalStack integration, performance benchmarks, security validation, and resilience testing.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)|
9899
|SourceFlow.Cloud.Azure|v2.0.0 |(TBC) |Provides support for Azure cloud with cross domain boundary command and Event publishing & subscription. Includes comprehensive testing framework with Azurite integration, performance benchmarks, security validation, and resilience testing.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)|
99100

100101
## Getting Started
101102
### Installation
102103
add nuget packages for SourceFlow.Net
103104
> - dotnet add package SourceFlow.Net
104105
> - dotnet add package SourceFlow.Stores.EntityFramework
105-
> - dotnet add package SourceFlow.Cloud.Aws (to be released)
106+
> - dotnet add package SourceFlow.Cloud.AWS
106107
> - add custom implementation for stores, and extend for your cloud.
107108
108109
### Cloud Integration with Idempotency
@@ -151,9 +152,9 @@ services.UseSourceFlowAws(
151152
- ✅ Supports SQL Server, PostgreSQL, MySQL, SQLite
152153

153154
For more details, see:
154-
- [AWS Cloud Integration](src/SourceFlow.Cloud.AWS/README.md)
155-
- [Azure Cloud Integration](src/SourceFlow.Cloud.Azure/README.md)
155+
- [AWS Cloud Integration](docs/aws-integration.md.md)
156156
- [SQL-Based Idempotency Service](docs/SQL-Based-Idempotency-Service.md)
157+
- [Cloud Integration Testing guide](docs/Cloud-Integration-Testing.md)
157158

158159
### Developer Guide
159160
This comprehensive guide provides detailed information about the SourceFlow.Net framework, covering everything from basic concepts to advanced implementation patterns and troubleshooting guidelines.

‎docs/SourceFlow.Cloud.AWS-README.md‎

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -767,14 +767,27 @@ services.UseSourceFlowAws(
767767

768768
LocalStack provides local AWS service emulation for development and testing.
769769

770-
#### Setup
770+
#### Setup with Script (Recommended)
771771

772772
```bash
773-
# Install LocalStack
774-
pip install localstack
773+
# PowerShell (Windows)
774+
./tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.ps1
775775

776-
# Start LocalStack
777-
localstack start
776+
# Bash (Linux/macOS/WSL)
777+
./tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.sh
778+
```
779+
780+
The scripts automatically start a LocalStack Docker container, wait for services, set environment variables, and run the integration tests. Use `--keep` / `-KeepRunning` to leave the container running after tests.
781+
782+
#### Manual Setup
783+
784+
```bash
785+
# Start LocalStack via Docker
786+
docker run -d --name sourceflow-localstack \
787+
-p 4566:4566 \
788+
-e SERVICES=sqs,sns,kms \
789+
-e EAGER_SERVICE_LOADING=1 \
790+
localstack/localstack:latest
778791
```
779792

780793
#### Configuration
@@ -826,7 +839,11 @@ public class AwsIntegrationTests : LocalStackRequiredTestBase
826839
# Unit tests only
827840
dotnet test --filter "Category=Unit"
828841

829-
# Integration tests with LocalStack
842+
# Integration tests with LocalStack (using script)
843+
./tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.ps1 # PowerShell
844+
./tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.sh # Bash
845+
846+
# Integration tests manually (LocalStack must be running)
830847
dotnet test --filter "Category=Integration&Category=RequiresLocalStack"
831848
```
832849

@@ -1141,9 +1158,9 @@ Aggregates/Views Handle Event
11411158

11421159
## Support
11431160

1144-
- **Documentation**: [GitHub Wiki](https://github.com/sourceflow/sourceflow.net/wiki)
1145-
- **Issues**: [GitHub Issues](https://github.com/sourceflow/sourceflow.net/issues)
1146-
- **Discussions**: [GitHub Discussions](https://github.com/sourceflow/sourceflow.net/discussions)
1161+
- **Documentation**: [GitHub Wiki](https://github.com/CodeShayk/SourceFlow.Net/wiki)
1162+
- **Issues**: [GitHub Issues](https://github.com/CodeShayk/SourceFlow.Net/issues)
1163+
- **Discussions**: [GitHub Discussions](https://github.com/CodeShayk/SourceFlow.Net/discussions)
11471164

11481165
---
11491166

@@ -1154,5 +1171,5 @@ MIT License - see [LICENSE](../LICENSE) file for details.
11541171
---
11551172

11561173
**Package Version**: 2.0.0
1157-
**Last Updated**: 2026-03-04
1174+
**Last Updated**: 2026-03-15
11581175
**Status**: Production Ready

‎docs/SourceFlow.Net-README.md‎

Lines changed: 81 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ SourceFlow.Net is a comprehensive event sourcing and CQRS framework that empower
1515
- ⚡ **CQRS Implementation** - Command/Query separation for optimized read and write operations
1616
- 📊 **Event-First Design** - Foundation built on event sourcing with complete audit trails
1717
- 🧱 **Clean Architecture** - Separation of concerns with clear architectural boundaries
18-
- 🔒 **Resilience Ready** - Built-in retry policies and circuit breakers
19-
- 📈 **Observability** - Integrated OpenTelemetry support for monitoring and tracing
20-
- 🔧 **Extensible** - Pluggable persistence and messaging layers
18+
- ☁️ **Cloud-Native Messaging** - Built-in bus configuration with fluent API for distributed command/event routing
19+
- 🔒 **Security** - Message encryption (KMS), sensitive data masking, and dead letter queue processing
20+
- 🔄 **Resilience** - Circuit breakers, retry policies, and idempotency for duplicate message detection
21+
- 📈 **Observability** - Integrated OpenTelemetry support for monitoring and tracing across cloud operations
22+
- 🔧 **Extensible** - Pluggable persistence, messaging, and cloud provider layers (AWS, Azure)
2123

2224
### 🎯 Core Architecture
2325

@@ -61,12 +63,52 @@ dotnet add package SourceFlow.Net
6163

6264
# Entity Framework persistence (optional but recommended)
6365
dotnet add package SourceFlow.Stores.EntityFramework
66+
67+
# AWS Cloud Provider (optional)
68+
dotnet add package SourceFlow.Cloud.AWS
6469
```
6570

6671
### .NET Framework Support
67-
- .NET Framework 4.6.2
6872
- .NET Standard 2.0 / 2.1
69-
- .NET 9.0 / 10.0
73+
- .NET 8.0 / 9.0 / 10.0
74+
75+
---
76+
77+
## ☁️ What's New in v2.0.0 — Cloud-Native Architecture
78+
79+
Version 2.0.0 consolidates all cloud abstractions into the core SourceFlow.Net package, eliminating the need for a separate `SourceFlow.Cloud.Core` dependency. Cloud provider packages (e.g., `SourceFlow.Cloud.AWS`) now depend only on the core package.
80+
81+
### Cloud Abstractions in Core
82+
83+
The following are now part of `SourceFlow.Net`:
84+
85+
| Feature | Namespace | Description |
86+
|---------|-----------|-------------|
87+
| **Bus Configuration** | `SourceFlow.Cloud.Configuration` | Fluent API for command/event routing (`.Send.Command`, `.Raise.Event`, `.Listen.To`, `.Subscribe.To`) |
88+
| **Circuit Breaker** | `SourceFlow.Cloud.Resilience` | Configurable failure thresholds, half-open recovery, and state change events |
89+
| **Message Encryption** | `SourceFlow.Cloud.Security` | Envelope encryption with pluggable key providers (e.g., AWS KMS) |
90+
| **Sensitive Data Masker** | `SourceFlow.Cloud.Security` | Automatic PII/credential masking in logs and diagnostics |
91+
| **Dead Letter Processing** | `SourceFlow.Cloud.DeadLetterProcessing` | Failed message inspection, replay, and purge |
92+
| **Idempotency** | `SourceFlow.Cloud.Idempotency` | Duplicate message detection with in-memory or EF-backed stores |
93+
| **Cloud Observability** | `SourceFlow.Cloud.Observability` | OpenTelemetry spans for command dispatch, event publish, and message processing |
94+
| **Health Checks** | `SourceFlow.Cloud.HealthChecks` | IHealthCheck implementations for cloud service endpoints |
95+
96+
### Migration from v1.x
97+
98+
If you previously used `SourceFlow.Cloud.Core`:
99+
100+
```diff
101+
- using SourceFlow.Cloud.Core.Configuration;
102+
+ using SourceFlow.Cloud.Configuration;
103+
104+
- using SourceFlow.Cloud.Core.Resilience;
105+
+ using SourceFlow.Cloud.Resilience;
106+
107+
- using SourceFlow.Cloud.Core.Security;
108+
+ using SourceFlow.Cloud.Security;
109+
```
110+
111+
Remove the `SourceFlow.Cloud.Core` package reference — everything is now in `SourceFlow.Net`.
70112

71113
---
72114

@@ -1071,10 +1113,39 @@ Use the `.fifo` suffix to enable ordered message processing:
10711113
- Check entity ID is properly set in commands
10721114
- Ensure message grouping is configured
10731115

1116+
### Message Security
1117+
1118+
SourceFlow.Net v2.0.0 includes built-in security infrastructure for cloud messaging:
1119+
1120+
**Message Encryption** — Envelope encryption for sensitive message payloads:
1121+
```csharp
1122+
services.UseSourceFlowAws(options =>
1123+
{
1124+
options.EnableEncryption = true;
1125+
options.KmsKeyId = "alias/sourceflow-key";
1126+
}, bus => ...);
1127+
```
1128+
1129+
**Sensitive Data Masking** — Automatic PII detection and masking in logs:
1130+
```csharp
1131+
// Automatically masks credit card numbers, emails, SSNs, etc.
1132+
// in diagnostic output and exception messages
1133+
var masker = new SensitiveDataMasker();
1134+
var safe = masker.Mask(rawLogMessage);
1135+
```
1136+
1137+
**Dead Letter Queue Processing** — Inspect, replay, or purge failed messages:
1138+
```csharp
1139+
// Failed messages are automatically routed to DLQs
1140+
// Use the DLQ processor to investigate and replay
1141+
await dlqProcessor.ReplayMessagesAsync(queueUrl, maxMessages: 10);
1142+
```
1143+
10741144
### Cloud-Specific Documentation
10751145

10761146
For detailed cloud-specific information:
1077-
- **AWS**: See [AWS Cloud Architecture](Architecture/07-AWS-Cloud-Architecture.md)
1147+
- **AWS**: See [SourceFlow.Cloud.AWS README](SourceFlow.Cloud.AWS-README.md) and [AWS Cloud Architecture](Architecture/07-AWS-Cloud-Architecture.md)
1148+
- **Idempotency**: See [Cloud Message Idempotency Guide](Cloud-Message-Idempotency-Guide.md)
10781149
- **Testing**: See [Cloud Integration Testing](Cloud-Integration-Testing.md)
10791150

10801151
---
@@ -1086,6 +1157,7 @@ SourceFlow.Net supports pluggable persistence through store interfaces:
10861157
- `ICommandStore` - Stores command history for audit trails and replay
10871158
- `IEntityStore` - Stores current state of domain entities
10881159
- `IViewModelStore` - Stores optimized read models for queries
1160+
- `IIdempotencyService` - Duplicate message detection for cloud messaging
10891161

10901162
### Entity Framework Provider
10911163

@@ -1094,6 +1166,7 @@ The Entity Framework provider offers:
10941166
- Resilience policies with automatic retry and circuit breaker
10951167
- OpenTelemetry integration for database operations
10961168
- Configurable connection strings per store type
1169+
- **Cloud Idempotency**: EF-backed `IdempotencyService` with `IdempotencyDbContext` and automatic cleanup via `IdempotencyCleanupService` for multi-instance deployments
10971170
- **Enhanced Return Types**: Store operations return the persisted entity for additional processing
10981171

10991172
Install with:
@@ -1175,4 +1248,6 @@ We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md
11751248
This project is licensed under the [MIT License](../LICENSE).
11761249

11771250
---
1251+
**Package Version**: 2.0.0 | **Last Updated**: 2026-03-15
1252+
11781253
Made with ❤️ by the SourceFlow.Net team to empower developers building event-sourced applications

0 commit comments

Comments
 (0)