Home

Awesome


page_type: sample languages:


Orchestration-based Saga on Serverless

saga-build

Contoso Bank is building a new payment platform leveraging the development of microservices to rapidly offer new features in the market, where legacy and new applications coexist. Operations are now distributed across applications and databases, and Contoso needs a new architecture and implementation design to ensure data consistency on financial transactions.

The traditional ACID approach is not suited anymore for Contoso Bank as the data of operations are now spanned into isolated databases. Instead of ACID transactions, a Saga addresses the challenge by coordinating a workflow through a message-driven sequence of local transactions to ensure data consistency.

About the solution

The solution simulates a money transfer scenario, where an amount is transferred between bank accounts through credit/debit operations and an operation receipt is generated for the requester. It is a Saga pattern implementation reference through an orchestration approach in a serverless architecture on Azure. The solution leverages Azure Functions for the implementation of Saga participants, Azure Durable Functions for the implementation of the Saga orchestrator, Azure Event Hubs as the data streaming platform and Azure Cosmos DB as the database service.

The implementation reference addresses the following challenges and concerns from Contoso Bank:

Potential use cases

These other uses cases have similar design patterns:

Architecture

Architecture Overview

Check the following sections about the core components of the solution, workflows and design decisions:

Maturity Level

These are the top skills required for Solution Architects and Developer Leads that will reuse the proposed solution or parts of the implementation as reference:

Repository Structure

Outline the file contents of the repository. It helps users navigate the codebase, build configuration and any related assets.

File/folderDescription
docsContains the project docs and images
srcContains the sample source code
.gitignoreDefines what files to be igored at commit time
CODE_OF_CONDUCT.mdMicrosoft Open Source Code of Conduct
CONTRIBUTING.mdGuidelines for contributing to the sample
LICENSEThe license defined for the sample
README.mdProject wiki
SECURITYSecurity guidelines for the sample

The src folder contains a set of .NET Core solutions:

ProjectDescription
Saga.CommonSolution that contains a set of reusable abstractions, models, commands and events objects and utilities
Saga.Common.TestsSolution that contains all unit tests for common utilities and processors
Saga.FunctionsSolution that contains all Azure Functions
Saga.Functions.TestsSolution that contains all Azure Functions unit tests
Saga.OrchestrationSolution that contains domain models and the coordination logic for the Saga Orchestrator
Saga.Orchestration.TestsSolution that contains unit tests for the Saga Orchestrator
Saga.ParticipantsSolution that contains domain models and business logic of all Saga participants
Saga.Participants.TestsSolution that contains unit tests of all Saga participants

Prerequisites

If Visual Studio Code is your platform preference for development:

If Visual Studio is your platform preference for development:

Getting Started

1. Create the infrastructure

Follow the instructions on Create Infrastructure as Code to create a new GitHub Actions pipeline that creates the required infrastructure on Azure through Terraform.

2. Creating the application settings

The solution requires a set of environment variables to be configured on Saga.Functions solution for running the project locally. Follow the Configuring the Azure Functions Application Settings instructions to create a local.settings.json. Make sure the settings are configured before proceeding to the next step.

4. Running unit tests

Run the following command on test projects:

dotnet test

5. Running the solution

For running the solution through command line, make sure you're on the src/Saga.Functions directory then run the following command:

func host start

The solution provides a Swagger UI on http://localhost:<port>/api/swagger/ui.

Swagger UI

You can start a new HTTP request on /api/saga/start route by providing the following json as part of the body content:

{
    "accountFromId": "<random ID>",
    "accountToId": "<random ID>",
    "amount": 100.00
}

After executing the request, it's expected to receive the transaction ID as part of the HTTP response.

Saga Starter request

You can check the documents created on Cosmos DB. It is expected to have the following document structure on the orchestrator collection:

{
  "accountFromId": "<random bank account ID>",
  "accountToId": "<random bank account ID>",
  "amount": 100,
  "id": "<random transaction ID>",
  "type": "Default",
  "state": "Success",
  ...
}

For observability, check the saga collection that contains all events processed by the orchestrator. It is expected to have the following structure:

{
  "transactionId": "<random transaction ID>",
  "source": "<Validator, Transfer or Receipt>",
  "messageType": "<event name>",
  "creationDate": "<event creation date>",
  ...
}

Next Steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.