meysamhadeli / booking-microservices

Practical microservices, built with .Net 8, DDD, CQRS, Event Sourcing, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.

The main idea of creating this project is implementing an infrastructure for up and running distributed system with the latest technology and architecture like Vertical Slice Architecture, Event Sourcing, CQRS, DDD, gRpc, MongoDB, RabbitMq, Masstransit in .Net 8, and we will not deal mainly with business. 🚀

Table of Contents

• The Goals of This Project
• Plan
• Technologies - Libraries
• The Domain and Bounded Context - Service Boundary
• Structure of Project
• How to Run
  • Config Certificate
  • Docker Compose
  • Kubernetes
  • Build
  • Run
  • Test
• Documentation Apis
• Support
• Contribution

The Goals of This Project

• ❇️ Using Vertical Slice Architecture for architecture level.
• ❇️ Using Domain Driven Design (DDD) to implement all business processes in microservices.
• ❇️ Using Rabbitmq on top of Masstransit for Event Driven Architecture between our microservices.
• ❇️ Using gRPC for internal communication between our microservices.
• ❇️ Using CQRS implementation with MediatR library.
• ❇️ Using Postgres for write side of some microservices.
• ❇️ Using MongoDB for read side of some microservices.
• ❇️ Using Event Store for write side of Booking-Microservice to store all historical state of aggregate.
• ❇️ Using Inbox Pattern for ensuring message idempotency for receiver and Exactly once Delivery.
• ❇️ Using Outbox Pattern for ensuring no message is lost and there is at At Least One Delivery.
• ❇️ Using Unit Testing for testing small units and mocking our dependencies with Nsubstitute.
• ❇️ Using End-To-End Testing and Integration Testing for testing features with all dependencies using testcontainers.
• ❇️ Using Fluent Validation and a Validation Pipeline Behaviour on top of MediatR.
• ❇️ Using Minimal API for all endpoints.
• ❇️ Using Health Check for reporting the health of app infrastructure components.
• ❇️ Using Docker-Compose and Kubernetes for our deployment mechanism.
• ❇️ Using Kibana on top of Serilog for logging.
• ❇️ Using OpenTelemetry for distributed tracing on top of Jaeger.
• ❇️ Using OpenTelemetry for monitoring on top of Prometheus and Grafana.
• ❇️ Using IdentityServer for authentication and authorization base on OpenID-Connect and OAuth2.
• ❇️ Using Yarp as a microservices gateway.
• ❇️ Using Kubernetes to achieve efficient scaling and ensure high availability for each of our microservices.
• ❇️ Using Nginx Ingress Controller for load balancing between our microservices top of Kubernetes.
• ❇️ Using cert-manager to Configure TLS in kubernetes cluster.

Plan

🌀This project is a work in progress, new features will be added over time.🌀

I will try to register future goals and additions in the Issues section of this repository.

High-level plan is represented in the table

Feature	Status
API Gateway	Completed ✔️
Identity Service	Completed ✔️
Flight Service	Completed ✔️
Passenger Service	Completed ✔️
Booking Service	Completed ✔️
Building Blocks	Completed ✔️

Technologies - Libraries

• ✔️ .NET 7 - .NET Framework and .NET Core, including ASP.NET and ASP.NET Core
• ✔️ MVC Versioning API - Set of libraries which add service API versioning to ASP.NET Web API, OData with ASP.NET Web API, and ASP.NET Core
• ✔️ EF Core - Modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrations
• ✔️ Masstransit - Distributed Application Framework for .NET.
• ✔️ MediatR - Simple, unambitious mediator implementation in .NET.
• ✔️ FluentValidation - Popular .NET validation library for building strongly-typed validation rules
• ✔️ Swagger & Swagger UI - Swagger tools for documenting API's built on ASP.NET Core
• ✔️ Serilog - Simple .NET logging with fully-structured events
• ✔️ Polly - Polly is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner
• ✔️ Scrutor - Assembly scanning and decoration extensions for Microsoft.Extensions.DependencyInjection
• ✔️ Opentelemetry-dotnet - The OpenTelemetry .NET Client
• ✔️ DuendeSoftware IdentityServer - The most flexible and standards-compliant OpenID Connect and OAuth 2.x framework for ASP.NET Core
• ✔️ EasyCaching - Open source caching library that contains basic usages and some advanced usages of caching which can help us to handle caching more easier.
• ✔️ Mapster - Convention-based object-object mapper in .NET.
• ✔️ Hellang.Middleware.ProblemDetails - A middleware for handling exception in .Net Core
• ✔️ NewId - NewId can be used as an embedded unique ID generator that produces 128 bit (16 bytes) sequential IDs
• ✔️ Yarp - Reverse proxy toolkit for building fast proxy servers in .NET
• ✔️ Tye - Developer tool that makes developing, testing, and deploying microservices and distributed applications easier
• ✔️ gRPC-dotnet - gRPC functionality for .NET.
• ✔️ EventStore - The open-source, functional database with Complex Event Processing.
• ✔️ MongoDB.Driver - .NET Driver for MongoDB.
• ✔️ xUnit.net - A free, open source, community-focused unit testing tool for the .NET Framework.
• ✔️ Respawn - Respawn is a small utility to help in resetting test databases to a clean state.
• ✔️ Testcontainers - Testcontainers for .NET is a library to support tests with throwaway instances of Docker containers.
• ✔️ K6 - Modern load testing for developers and testers in the DevOps era.

The Domain And Bounded Context - Service Boundary

• Identity Service: The Identity Service is a bounded context for the authentication and authorization of users using Identity Server. This service is responsible for creating new users and their corresponding roles and permissions using .Net Core Identity and Jwt authentication and authorization.

• Flight Service: The Flight Service is a bounded context CRUD service to handle flight related operations.

• Passenger Service: The Passenger Service is a bounded context for managing passenger information, tracking activities and subscribing to get notification for out of stock products.

• Booking Service: The Booking Service is a bounded context for managing all operation related to booking ticket.

Structure of Project

In this project I used a mix of clean architecture, vertical slice architecture and I used feature folder structure to structure my files.

I used yarp reverse proxy to route synchronous and asynchronous requests to the corresponding microservice. Each microservice has its dependencies such as databases, files etc. Each microservice is decoupled from other microservices and developed and deployed separately. Microservices talk to each other with Rest or gRPC for synchronous calls and use RabbitMq or Kafka for asynchronous calls.

We have a separate microservice (IdentityServer) for authentication and authorization of each request. Once signed-in users are issued a JWT token. This token is used by other microservices to validate the user, read claims and allow access to authorized/role specific endpoints.

I used RabbitMQ as my MessageBroker for async communication between microservices using the eventual consistency mechanism. Each microservice uses MassTransit to interface with RabbitMQ providing, messaging, availability, reliability, etc.

Microservices are event based which means they can publish and/or subscribe to any events occurring in the setup. By using this approach for communicating between services, each microservice does not need to know about the other services or handle errors occurred in other microservices.

After saving data in write side, I save a Internal Command record in my Persist Messages storage (like something we do in outbox pattern) and after committing transaction in write side, trigger our command handler in read side and this handler could save their read models in our MongoDB database.

I treat each request as a distinct use case or slice, encapsulating and grouping all concerns from front-end to back. When adding or changing a feature in an application in n-tire architecture, we are typically touching many "layers" in an application. We are changing the user interface, adding fields to models, modifying validation, and so on. Instead of coupling across a layer, we couple vertically along a slice. We minimize coupling between slices, and maximize coupling in a slice.

With this approach, each of our vertical slices can decide for itself how to best fulfill the request. New features only add code, we're not changing shared code and worrying about side effects.

Instead of grouping related action methods in one controller, as found in traditional ASP.net controllers, I used the REPR pattern. Each action gets its own small endpoint, consisting of a route, the action, and an IMediator instance (see MediatR). The request is passed to the IMediator instance, routed through a Mediatr pipeline where custom middleware can log, validate and intercept requests. The request is then handled by a request specific IRequestHandler which performs business logic before returning the result.

The use of the mediator pattern in my controllers creates clean and thin controllers. By separating action logic into individual handlers we support the Single Responsibility Principle and Don't Repeat Yourself principles, this is because traditional controllers tend to become bloated with large action methods and several injected Services only being used by a few methods.

I used CQRS to decompose my features into small parts that makes our application:

• Maximize performance, scalability and simplicity.
• Easy to maintain and add features to. Changes only affect one command or query, avoiding breaking changes or creating side effects.
• It gives us better separation of concerns and cross-cutting concern (with help of mediatr behavior pipelines), instead of bloated service classes doing many things.

Using the CQRS pattern, we cut each business functionality into vertical slices, for each of these slices we group classes (see technical folders structure) specific to that feature together (command, handlers, infrastructure, repository, controllers, etc). In our CQRS pattern each command/query handler is a separate slice. This is where you can reduce coupling between layers. Each handler can be a separated code unit, even copy/pasted. Thanks to that, we can tune down the specific method to not follow general conventions (e.g. use custom SQL query or even different storage). In a traditional layered architecture, when we change the core generic mechanism in one layer, it can impact all methods.

How to Run

Config Certificate

Run the following commands to Config SSL in your system:

Windows using Linux containers

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p password
dotnet dev-certs https --trust

Note: for running this command in powershell use $env:USERPROFILE instead of %USERPROFILE%

macOS or Linux

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p $CREDENTIAL_PLACEHOLDER$
dotnet dev-certs https --trust

Docker Compose

To run this app in Docker, use the docker-compose.yaml and execute the below command at the root of the application:

docker-compose -f ./deployments/docker-compose/docker-compose.yaml up -d

Kubernetes

To configure TLS in the Kubernetes cluster, we need to install cert-manager based on the docs and run the following commands to apply TLS in our application. Here, we use Let's Encrypt to encrypt our certificate.

kubectl apply -f ./deployments/kubernetes/booking-cert-manager.yml

To apply all necessary deployments, pods, services, ingress, and config maps, please run the following command:

kubectl apply -f ./deployments/kubernetes/booking-microservices.yml

Build

To build all microservices, run this command in the root of the project:

dotnet build

Run

To run each microservice, run this command in the root of the Api folder of each microservice where the csproj file is located:

dotnet run

Test

To test all microservices, run this command in the root of the project:

dotnet test

Documentation Apis

Each microservice has a Swagger OpenAPI. Browse to /swagger for a list of endpoints.

As part of API testing, I created the booking.rest file which can be run with the REST Client VSCode plugin.

Support

If you like my work, feel free to:

• ⭐ this repository. And we will be happy together :)

Thanks a bunch for supporting me!

Contribution

Thanks to all contributors, you're awesome and this wouldn't be possible without you! The goal is to build a categorized, community-driven collection of very well-known resources.

Please follow this contribution guideline to submit a pull request or create the issue.

Project References & Credits

• https://github.com/jbogard/ContosoUniversityDotNetCore-Pages
• https://github.com/kgrzybek/modular-monolith-with-ddd
• https://github.com/oskardudycz/EventSourcing.NetCore
• https://github.com/thangchung/clean-architecture-dotnet
• https://github.com/pdevito3/MessageBusTestingInMemHarness

License

This project is made available under the MIT license. See LICENSE for details.

booking-microservices's Issues

Add Vault

https://github.com/rajanadar/VaultSharp

System.Security.Cryptography.CryptographicException

When i run the docker compose i get the error below

09:41:18 [INFO] Background worker stopped
2023-10-04 09:41:18 09:41:18 [INFO] Subscription to all '"default"'
2023-10-04 09:41:19 09:41:18 [EROR] Hosting failed to start
2023-10-04 09:41:19 System.Security.Cryptography.CryptographicException: The certificate data cannot
2023-10-04 09:41:19 be read with the provided password, the password may be incorrect.
2023-10-04 09:41:19 System.Security.Cryptography.CryptographicException: The certificate data
2023-10-04 09:41:19 cannot be read with the provided password, the password may be incorrect.
2023-10-04 09:41:19 at void System.Security.Cryptography.X509Certificates.UnixPkcs12Reader.
2023-10-04 09:41:19 VerifyAndDecrypt(ReadOnlySpan password, ReadOnlyMemory
2023-10-04 09:41:19 authSafeContents)
2023-10-04 09:41:19 at void System.Security.Cryptography.X509Certificates.UnixPkcs12Reader.
2023-10-04 09:41:19 Decrypt(SafePasswordHandle password, bool ephemeralSpecified)
2023-10-04 09:41:19 at void System.Security.Cryptography.X509Certificates.UnixPkcs12Reader.Decrypt
2023-10-04 09:41:19 (SafePasswordHandle password, bool ephemeralSpecified)
2023-10-04 09:17:21 Unhandled exception. System.Security.Cryptography.CryptographicException: The certificate data cannot be read with the provided password, the password may be incorrect.
2023-10-04 09:17:21 ---> System.Security.Cryptography.CryptographicException: The certificate data cannot be read with the provided password, the password may be incorrect.
2023-10-04 09:17:21 at System.Security.Cryptography.X509Certificates.UnixPkcs12Reader.VerifyAndDecrypt(ReadOnlySpan1 password, ReadOnlyMemory1 authSafeContents)

Use NewId or Ulid instead of Snowflake ID (IdGen)

Base on suggestion in PR #200

Add this feature in PR: #242

Ref:

IdGen

https://github.com/RobThree/IdGen

Ulid

https://github.com/Cysharp/Ulid

NewId

https://github.com/phatboyg/NewId

R&D:

IdGen is 64-bit (8 bytes) and Ulid, Ulid are 128-bit (16 bytes) Id's. Also, IdGen is long and Ulid, Ulid are uniqueidentifier, so we have better performance in the end with IdGen.

For getting a unique Id in all of distributed system is better we use NewId or Ulid. Because we always get a valid unique sequential Id in whole distributed system.

Note: We can handle it with IdGen for get unique Id in whole distributed system. But it's a little tricky and must find a good way to implement it to handle it to scale up in Kubernetes.

Add unit test

Add some ASP MVC views

Hello can you please add some views to let user see/book

Add End-to-End Testing

Add this feature in PR: #67-#68

Fix Test Issue Masstransit with Upgrade to .Net 7

Fix bug in Masstransit test after update to .Net 7.

Fix in PR : #65

Upgrade to .Net 7

Add in PR: #59

Use VerifyTests instead of assertion

https://github.com/VerifyTests

User Required keyword for Entities (.Net 7)

Base on Suggestion #200

Add this feature in PR: #244

Ref:
(Why I won’t need constructors anymore in C# 11)[https://www.youtube.com/watch?v=9CDgPgWF9IY]

Add Rate Limit in .Net 7

https://blog.maartenballiauw.be/post/2022/09/26/aspnet-core-rate-limiting-middleware.html

Add this feature in PR: #63

Add Performance Test

Add this feature in PR: #248

Ref

https://k6.io/blog/load-testing-your-api-with-swagger-openapi-and-k6/

unauthorized exception

Hi I am trying to run this project on local machine using docker compose. The command fails with following message:

unauthorized: authentication required

this happens somewhere at pulling eventstore. I closed the terminal already, forgetting to copy the full log geenrated on running the command: docker-compose -f ./deployments/docker-compose/docker-compose.yaml up -d

I found this while digging out: EventStore/EventStore#2706

Any insights please?

Thanks

Add Kubernetes

Added this feature in this PR: #208

Domain model refactoring

Use Value Objects to handle more business complexity.

• PR: #262 (Part 1)
• PR: #266 (Part 2)
• PR: #269 (Part 3)

Merge command, query, result into single file

Ref:

https://ojdevelops.com/2018/07/the-tyranny-of-horizontal-architectures2.html

Add This feature in PR: #234, #236

Use minimal api instead of controller

Add this feature in PR: #60

Merge request response into endpoint

Base on suggestion in PR #200

Add this Feature in PR: #234, #236

Add BDD

https://event-driven.io/en/ogooreck_sneaky_bdd_testing_framework/

Add Some Unit Tests For Domain Models

Add this feature in this PR: #96

Change Integration Test fixture to testcontainers-dotnet

https://github.com/testcontainers/testcontainers-dotnet

Add this feature in PR: #58

Save Problem

Brother,
I am facing a problem when saving data. Though I have commented savechanges method, data saves in database.
In my scenario on this table there is no domain events.
var newAircraft = await _flightDbContext.Aircraft.AddAsync(aircraftEntity, cancellationToken);
//await _flightDbContext.SaveChangesAsync(cancellationToken);

Helpful Features

It's Awesome project.
Thanks for making this repository.

I think if you add more feature that would be helpful, like

1. Login , Authorization & Security.
2. Complex query 2 or All microservices.
3. Pagination.
4. Audit Log
5. SignalR

@ if you have any plan to add UI then Add React

Thanks.
May Allah live long

Add Health Checks

Use built in problem details in .Net 7 instead of Hellang Middleware ProblemDetails

Base on suggestion in PR #200

Add this feature in PR: #241

Ref

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-7.0#pds7
https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-7.0#pds7

Add Monitoring

Add this feature in PR: #272 - #273

Ref:

https://github.com/JamesNK/aspnetcore-grafana
https://www.youtube.com/watch?v=A2pKhNQoQUU

Add Outbox and Internal Command

Add integration test

Suggestions in .net7

Here are some suggestions from .net 7. Please take this as they are, suggestions, I'm not saying it's better or worse just some alternatives. Congratulations for this awesome sample!

• Use TypedResults and Multiple Results.
• In theory Hellang.Middleware.ProblemDetails is not needed anymore since the ProblemDetails are now easy configurable in .net 7
• Is SnowFlakIdGenerator since MassTransit already uses NewId with same purposes?
• Use required on props of records to simplify/omit some rules.
• Question: Should booking service have any reference to a CurrentUser? Will this be called always in a context of a user?

Lately we've been merging the the request, validator, handler in the same class. Since adding or removing the request will almost always involve changing the validator. F12 (Go to definition is magical). We do not use any auto discovery plain old container registration so navigation and find usages work.

public static class Endpoint
{
    public static void MapRoute(IEndpointRouteBuilder route) => route.MapGet("/account/{id:int}", Handle);

    public record Request
    {
        public required int Id { get; init; }
    }

    public class Validator : AbstractValidator<Request>
    {
        public Validator() => RuleFor(x => x.Id).GreaterThan(2);
    }

    public record Response(string Desc);

    public static async Task<Results<Ok<Response>, NotFound>> Handle(
        [AsParameters] Request request,
        ILogger<Request> logger,
        ApiDbContext context,
        CancellationToken cancellationToken)
    {
        if (request.Id == 10)
        {
            return NotFound();
        }

        var entity = await context.Students.FirstOrDefaultAsync(cancellationToken: cancellationToken);

        return Ok(new Response($"everything went fine for: {request.Id}"));
    }
}

In case you want to do unit tests instead of acceptance tests of your endpoints you can inject Queries and Commands instead of db context so you can easily mock.
We've tried TestContainers with server instance per session and each tests gets a new database + migration. It takes 10 sec to start sql server (azure sql edge) and 4ms to create a random new db with 2 tables. Running an acceptance test which: 1. generates new db. 2. creates the tables. 3. starts the api with test server. 4. makes a http get 5. make a query in db. 5. returns response. Takes 1 sec on average. This way ALL tests are insolated and run in parallel (even in the same (implicit) collection).
I'm planning a PoC for TestContainers with RabbitMq where only one instance of rabbitmq is started for a test session (per assembly fixutre) and all tests will use a separate vhost.

We've also dropped MediatR since we have very few truly cross concerns for it's pipeline and the number of request.

• OpenTelemetry adds logging to http and mass transit so tracebility is convered by that
• Caching at the api level. Since queries/command are never re-used between features they are tailed for each feature need. We add caching explicitly in the handler.
• Transactions when need are controlled at the handler level with transient dbcontext. A handler might create multiple transactions or call saves changes multiple times. In case of concurrency issues there are some chances to recover.
• Validation happens at the api/endpoint level at least the shallow one anything more complicated is handled directly in the handler

The principles we've been guiding ourselves:

• adhere to SOLID principles
• everything is an http api. Even cron jobs, background daemons. Use health-checks and probes
• vertical slices architecture
• invest a lot in identifying the correct bounded context
• duplication is far cheaper than wrong/premature abstractization
• we do not write applications to have tests, we write tests to build reliable applications. Refactoring should be done no matter how many tests need to be changed. Corollary prefer bdd, acceptance, integration and e2e tests which test business requirements instead of unit tests, especially when the MS are very small. Do sprinkle unit tests when business logic is complex.
• observability and traceability through OpenTelemetry are primordial
• easy to onboard new developers by self browsing since technical documentation is almost never written/updated.
  • drive developers into the pit of success with composable extensions framework.
  • limit magic behaviors: auto mappers, auto registration reflection. Prefer source generators instead.
• YAGNI
  • We will not swap databases without effort
  • We will not change transport protocols from grpc/http to anything else without effort
  • We will not switch from an http api to a console app or daemon service without effort.

An event has multiple consumer then what will be happen ?

Handle Outbox with Postgres Outbox Pattern with CDC and .NET

Ref

https://github.com/oskardudycz/PostgresOutboxPatternWithCDC.NET
https://event-driven.io/en/push_based_outbox_pattern_with_postgres_logical_replication/?utm_source=github_outbox_cdc
https://event-driven.io/en/how_to_get_all_messages_through_postgres_logical_replication/?utm_source=github_outbox_cdc
https://www.infoq.com/articles/wonders-of-postgres-logical-decoding-messages/

stored procs

Hi Guys
how would you execute a stored proc, can you please give a guide

Add Inbox Pattern

Add optimistic concurrency