Saga Coordinator

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendix

Introduction

This technical document focuses on the Saga coordinator implementation in the repository, systematically explains how Saga pattern is implemented in this codebase, including:

• Transaction step orchestration and execution
• Compensation transaction mechanism and rollback strategy
• Distributed transaction coordination ideas and state persistence
• Long transaction decomposition, transaction boundary definition and state management
• Parallel execution, conditional execution and exception handling
• Applicable scenarios, design principles and performance optimization suggestions

This implementation adopts clean architecture layering, coordinator is located at adapter layer, service layer is responsible for core business logic, repository layer is responsible for state persistence, task scheduler provides concurrent/sequential execution capabilities (complementary to Saga coordinator).

Project Structure

Key modules around Saga coordinator are as follows:

• Adapter Layer: Exposes simplified coordinator interface to outside, encapsulates service layer and repository layer
• Use Case Layer: Implements core business logic of Saga transaction (register handlers, execute steps, compensate)
• Entity Layer: Defines data structures and state constants for transactions and steps
• Repository Layer: Provides generic repository interface and memory repository implementation
• Task Scheduler: Provides concurrent/sequential execution capabilities (can be used with Saga coordinator)

Core Components

Coordinator (Adapter Layer)

• Responsibilities: Provides simplified registration and execution interface to outside; uses memory repository by default; maintains backward compatible type aliases and status constants.
• Key Points:
  • Register handlers and compensators: Registers step names and corresponding handler functions through service layer.
  • Execute transaction: Delegates to service layer for execution, returns transaction entity and error.
  • Query transaction: Delegates to service layer to query transaction status by ID.

SagaService

• Responsibilities: Core business logic, responsible for transaction lifecycle management, step execution, compensation rollback and state persistence.
• Key Processes:
  • Create transaction entity and save initial state
  • Set state to running and save
  • Execute each step sequentially: Find registered handler and execute; update progress and save on success; trigger compensation on failure
  • Compensation: Execute compensator handlers in reverse order from failed step (if exists), finally mark as compensated and save
  • Success: Set state to completed and save
  • Query: Read transaction from repository by ID

Transaction/Step

• Transaction: Transaction entity, contains ID, name, step list, current progress, status, creation/update time.
• Step: Step entity, contains name, handler name, payload, compensator handler name.
• Status Constants: pending, running, completed, failed, compensated.

MemoryRepository

• BaseRepository: Defines generic repository interface and default implementation skeleton (throws "not implemented" error), for specific repository implementations to override.
• MemoryRepository: Memory-based complete implementation, supports save, update, query, batch operations, pagination, conditional query, existence check, etc.; automatically maintains timestamp fields during save/update.

TaskScheduler

• Concurrent Scheduler: Supports max concurrent count control, task timeout, retry, expiration cleanup, cancellation and status query.
• Sequential Scheduler: Ensures only one task executes at a time, supports scheduled and periodic tasks, exponential backoff retry, expiration cleanup.
• Task Interface and TaskInfo: Unified task abstraction, contains ID, type, status, schedule time, retry count, error information, TTL, etc.

Architecture Overview

The following sequence diagram shows the call chain from coordinator to service layer to repository layer, as well as compensation flow.

Detailed Component Analysis

SagaService Execution Flow

Entity Model

Repository Implementation

Task Scheduler

Dependency Analysis

• Coordinator depends on service layer; service layer depends on repository interface and entity model; repository layer provides memory implementation.
• Task scheduler is independent of Saga coordinator, but both can be used together: Saga is responsible for long transaction orchestration and compensation, task scheduler is responsible for task-level concurrent/sequential execution and retry.

Performance Considerations

Transaction Persistence

• Each step success will save progress, frequent writes may become bottleneck. Recommendations:
  • Introduce asynchronous batch processing or background refresh strategy in high throughput scenarios (requires extending repository layer)
  • Evaluate whether more persistent storage (such as database/cache) is needed to replace memory repository

Compensation Overhead

• Compensation executes in reverse order from failed step, if compensation is complex or has many external dependencies, should be as idempotent and fail-fast as possible

Concurrency and Sequence

• For subtasks within long transactions, can combine with task scheduler to use concurrent/sequential mode, avoid blocking main transaction flow

Timeout and Retry

• Task scheduler has built-in timeout and retry mechanism, reasonably set timeout and max retry count, avoid avalanche

Troubleshooting Guide

Transaction Status Abnormal

• Check if repository save is successful (save/update errors will be wrapped as repository errors)
• Confirm transaction status flow: pending -> running -> completed/failed -> compensated

Step Handler Missing

• If registered handler name is inconsistent with step configuration, "unregistered handler" error will be reported during execution phase

Compensation Not Effective

• Confirm step has configured compensator handler name
• Compensation execution ignores errors (only logs), please check compensator handler implementation

Task Scheduling Issues

• Concurrent/sequential scheduler supports cancellation, status query, expiration cleanup and retry; check task TTL, max concurrent count, retry count and next retry time

Conclusion

This implementation implements Saga pattern in a concise way: through step orchestration, handler registration, state persistence and compensation rollback, achieves reliable execution of long transactions. Combined with task scheduler, can achieve concurrent/sequential execution and retry at more granular task level. Recommendations for production environment:

• Replace memory repository with persistent storage
• Provide idempotency and observability for compensator handlers
• Clarify transaction boundaries and step granularity, avoid overly long transactions
• Combine with task scheduler for concurrent/sequential control of subtasks

Appendix

Design Principles and Best Practices

• Clear Transaction Boundaries: Each Saga transaction focuses on single business goal, step count and granularity are moderate
• Idempotency First: Compensator handlers and step handlers should have idempotent capabilities
• Exception Means Compensation: Failure triggers compensation, compensation should be as fast and recoverable as possible
• State Visibility: Persist state through repository, convenient for monitoring and replay
• Observability: Provide logs and metrics for key steps and compensation

Applicable Scenarios

• Cross-service long transaction orchestration (such as order-inventory-payment)
• Distributed operations requiring compensation rollback
• Business processes that can be decomposed into clear step sequences

Key Flow Chart (Code Level)