Stacksaga-Framework (Synchronous)

It’s recommended to read StackSaga execution coordinator. (SEC) to have a better common understanding of orchestration engine in Stacksaga.

Stacksaga-Sync Engine is a reactive Saga orchestration engine framework built on top of Spring Boot.

It enables developers to design and manage complex workflows by coordinating primary executions and their compensating actions, effectively addressing eventual consistency challenges in distributed systems through the Saga design pattern.

The Stacksaga-Sync Engine architecture supports implementing any synchronous communication style you choose — such as REST (over HTTP), gRPC (over HTTP/2), or GraphQL (over HTTP) — giving you the flexibility to integrate microservices using the most appropriate approach for your system’s needs.

And also you can see here some of the major features that StackSaga provides.

Even though Stacksaga-Sync Engine runs reactively under the hood, it is fully compatible with both reactive and non-reactive Spring environments.

  • Saga Orchestration engine for managing primary and compensating work flows.

  • Transaction Coordination

  • Idempotency (Ensures that repeating the same operation multiple times has the same effect as performing it once, which is crucial for reliability.)

  • Transactions Asynchronous-Retrying

  • Event sourcing (State Management)

  • Monitoring Distributed transaction tracing via the StackSaga Trace-Window.

  • Concurrency Control and, many more…

Stacksaga-Components (High-Level Overview)

In the StackSaga ecosystem, few components are working together. It can be divided as below based on the usage.

Here you can see the relationship between them and how they are used in the StackSaga ecosystem.

stacksaga components overview

Description

  • stacksaga-spring-boot-starter provides the core features of the StackSaga framework like managing the saga work flows, transaction coordination, idempotency, event sourcing, and so on.

  • stacksaga-db-support provides the event-store supportive implementation for the StackSaga framework and rest APIs for accessing the tracing details from the StackSaga Trace-Window.

  • stacksaga-env-support provides the environment related geographical (region, zone, instance ID, etc.) data to the SEC in the cloud environment.

  • Agent service provides the transaction retrying management for the Orchestration service as a separate application.

  • StackSaga Trace-Window provides the monitoring facilities of the transactions. (no need to implement due to its hosted in the cloud for you)

See the individual sections for more details.

Stacksaga is configured based on the target service that you want to make the service as the Orchestration service. For instance if you want to configure stacksaga into the order service, you have to add the Orchestration service related components into the order service.

stacksaga-spring-boot-starter Dependency

stacksaga-spring-boot-starter is the core of the framework, and it can be added as a dependency into your project like below.

<dependency>
  <groupId>org.stacksaga</groupId>
  <artifactId>stacksaga-spring-boot-starter</artifactId>
  <version>${org.stacksaga.version}</version>
</dependency>

stacksaga-spring-boot-starter works with the following major components.

stacksaga-db-support Dependency

StackSaga works with the help of the event-store. So it requires a one of database implementations for connecting with the target database. The database implementation is based on your target Orchestration service’s database. For instance, if you want to configure stacksaga into the order-service, and the Mysql database is used as the primary database in the order-service, you have to add the stacksaga database support mysql implementation called stacksaga-mysql-support dependency into the order service.

Currently, the following database implementations are available.

stacksaga-env-support Dependency

stacksaga-env-support Dependency provides the environment related geographical (region, zone, instance ID, etc.) data to the SEC. Based on where your applications are deployed the stacksaga-env-support should be changed. For instance, if you deploy your order-service application in the eureka environment(Eureka based service discovery and load balancing), you have to add the stacksaga-eureka-support dependency into the order service. And if you want to migrate your order-service application to the kubernetes environment, you can change the stacksaga-eureka-support dependency to the stacksaga-k8s-support dependency in the order service.

Currently, StackSaga supports for the following environments.

To manage the transaction retrying, you have to build the agent application for the target Orchestration service. To create an agent-service, you have to choose one of stacksaga-agent dependencies based on the target Orchestration service’s database. For instance, if you have configured StackSaga on the order-service with the stacksaga-mysql-support database, you have to create a stacksaga-agent application for the order-service by adding the stacksaga-mysql-agent dependency.

No need to worry about the environment that your agent-application is deployed. Because all the stacksaga-agent implementations supports for all the environments. You can adjust the agent-application by changing the profile to your target environment. For instance, if you want to deploy the agent-application in the kubernetes environment, you can mention the profile as k8s in the property file in your application.

The following stacksaga-agent dependencies are available for the specific databases.

StackSaga Trace-Window

Stacksaga Trace-Window is the platform that you can see the transaction tracing details of the transaction that you made in graphically. there is nothing to be implemented regarding this component. you can visit live.stacksaga.org and use it.

Low-Level Digram (LLD)

Here you can see how the StackSaga Execution Coordinator (SEC) fits into the overall Stacksaga architecture.

StackSaga StackSaga Execution Coordinator (SEC) in Stacksaga framework

  1. The request comes to the orchestration service, and it is handed off to SEC with the SEC to process them asynchronously.

  2. SEC will pick up the request and start the execution from the configured starting point.

  3. Each step will be executed one by one based on the programmatic navigation by keeping the state in the event-store in case of retrying and tracing. with the help of the stacksaga-database-support module and stacksaga-env-support module(to get the instance’s metadata(optional)).

  4. If there is any primary execution failure, SEC will trigger the compensation executions in reverse order.

  5. If there is any failure in the compensation execution due to any resource unavailability, the SEC will keep the transaction in retry mode and retry the transaction based on the configured retry policy.

  6. Configured agent-service frequently checks for the transactions that are in retry mode and retry them by calling the orchestration service’s built-in retrying endpoint that is provided by the stacksaga-database-support module.

  7. Again, the SEC will pick up the request and start the execution from the failed point by restoring the previous state from the event-store.

  8. Each update of the transaction is saved in the event-store, and the SEC will publish the events to the configured listeners for each transaction state change.

  9. The administrators can see the tracing details of the transaction graphically by accessing the StackSaga Trace-Window via the in-built endpoints that are provided by the stacksaga-database-support module.