Chapter 10: Saga coordination mechanisms
Introduces what saga coordination must accomplish and distinguishes choreography’s event-driven control from orchestration’s dedicated orchestrator.
After this chapter you will be able to
- Saga coordination responsibility. Explain how a coordination mechanism advances a saga and handles success or failure.
- Choreography and orchestration control. Distinguish how choreography and orchestration decide which saga participant acts next.
- Event-driven saga progression. Trace how a system command starts a choreography-based saga and how events move it from one forward transaction to the next.
- Event-triggered compensation chain. Explain how a choreography-based saga initiates and continues compensating transactions when a forward transaction fails.
- Event-driven saga progression. Trace how the Order Service starts the Create Order Saga and how published events trigger subsequent steps in the Customer Service and Order Service.
- Credit outcome branches. Describe the three credit-reservation outcomes and the Order Service’s response to each.
- Choreography event flow. Describe how participants exchange events through publisher-owned channels, using outbound adapters to publish and inbound adapters to handle them.
- Dual purpose of saga events. Explain how an event type reports a service operation’s outcome while the event also carries data needed by other saga participants.
- Integration versus domain events. Distinguish saga coordination events from domain events, including why their contents or timing can differ.
- Integration event publisher choice. Explain when domain logic should publish an integration event and when the incoming event handler should publish it instead.
- Pass-through coupling and fan-out. Explain how passing productSpecification through the Customer Service creates design-time coupling, and how fan-out choreography removes that dependency.
- Concurrent outcome coordination. Describe why concurrently triggered reservations require extra Order states and careful handling of success and failure events.
- Compensation after mixed outcomes. Explain how a successful reservation is compensated when the other reservation fails, and why each service checks its reservation state.
- Simple event-based coordination. Explain why choreography is relatively straightforward to implement, especially for simple sagas.
- Loose runtime coupling. Explain how asynchronous messaging reduces runtime coupling in a choreography-based saga and what broker delivery contributes when a participant is temporarily unavailable.
- Distributed saga logic. Explain why a choreography-based saga becomes harder to understand as participants or interactions increase.
- Undesirable design-time dependencies. Describe the potentially undesirable design-time dependency between the Customer Service and Order Service in the Create Order Saga.
- Centralized saga coordination. Explain how an orchestrator directs saga participants, chooses the next operation from the previous outcome, and handles a failed forward transaction.
- Create Order orchestrator role. Explain how the CreateOrderSagaOrchestrator coordinates participants: it runs in the Order Service, tracks saga state, performs local Order Service operations, and uses asynchronous commands and replies to decide what happens next.
- Successful order creation sequence. Trace the happy path from the Order Service starting the orchestrator through local Order creation, credit reservation, inventory reservation, and local Order approval.
- Saga state machine model. Explain how an orchestrator represents a saga as a state machine, using the Create Order Saga to distinguish in-progress states, outcome-driven transitions, and final states.
- Durable orchestrator state. Describe what the orchestrator stores as saga state, how that state changes, and why the framework persists it.
- Participant driven execution. Trace how the framework starts the state machine and advances it in response to participants until it reaches an end state.
- Separate orchestration service trade-offs. Explain how a separate orchestration service acts as the system command’s entry point and why separating coordination simplifies participants but adds architectural and runtime costs.
- Embedded orchestrator trade-offs. Explain how embedding the orchestrator in a participant changes the command’s entry point, service count, response dependency, and design-time responsibilities.
- Asynchronous orchestration components. Describe how the orchestrator, participant command handlers, adapters, and message channels fit together in the Create Order Saga.
- Command and channel design. Explain what command and reply messages contain, which channels carry them, and which team owns the participant-facing API.
- Participant interaction style choice. Distinguish when an orchestrator must use request/asynchronous-response from when it can use a one-way notification.
- Reply-driven state machine execution. Trace how a saga starts and advances through transactional state-machine steps using commands, replies, persisted state, and messaging reliability patterns.
- HTTP state transitions and retries. Trace how an HTTP-based saga state advances on a response and what it does when no response arrives. Explain why the orchestrator needs its own retry logic.
- Persisted execution and recovery. Trace the saga execution loop, distinguishing database work from HTTP requests, and describe how failed or abandoned instances resume.
- Participant coupling and responsibilities. Explain how orchestration reduces design-time coupling between participants and keeps saga coordination logic out of their business logic.
- Orchestration costs and boundary. Describe orchestration’s added complexity relative to choreography and the risk of moving participant business logic into the orchestrator.
What it builds on
- Overview of saga coordination (chapter 9) · Introduces saga coordination.
- The structure of a saga (chapter 9) · The structure of a saga introduces forward and compensating transactions.
- An example saga: The Create Order saga (chapter 9) · The Create Order Saga introduced in the previous chapter.
- Designing loosely design-time coupled software (chapter 4) · designing to reduce design-time coupling
- Pattern: Idempotent consumer pattern (chapter 8) · the Idempotent Consumer pattern
- Pattern: Transaction outbox (chapter 8) · the Transaction outbox pattern
- Synchronously invoking an asynchronous implementation (chapter 8) · Uses publish/asynchronous-response for an HTTP-facing operation.
- Overview of messaging (chapter 8) · Introduces asynchronous messaging.
Section by section
Introduction
Introduces what saga coordination must accomplish and distinguishes choreography’s event-driven control from orchestration’s dedicated orchestrator.
- Saga coordination responsibility: Explain how a coordination mechanism advances a saga and handles success or failure.
Why it matters: This is the job that either coordination style must perform. - Choreography and orchestration control: Distinguish how choreography and orchestration decide which saga participant acts next.
Why it matters: The difference is where control over the saga’s next step resides.
Key terms: coordination mechanism, participant, forward transactions, compensating transactions, choreography, orchestration, event, saga orchestrator
10.1 Choreography-based sagas
Introduces choreography-based saga coordination by showing how participants use events to advance steps and trigger compensation after a failure.
- Event-driven saga progression: Trace how a system command starts a choreography-based saga and how events move it from one forward transaction to the next.
Why it matters: This event chain is the basic way a choreography-based saga moves forward. - Event-triggered compensation chain: Explain how a choreography-based saga initiates and continues compensating transactions when a forward transaction fails.
Why it matters: The same event-driven coordination also carries the saga through compensation after a failure.
Key terms: choreography-based saga, participant, event handler, forward transaction, system command, failure event, compensating transaction
10.1.1 The choreography-based version of the Create Order Saga
This section traces how events coordinate the choreography-based Create Order Saga from order creation through credit reservation to approval or rejection.
- Event-driven saga progression: Trace how the Order Service starts the Create Order Saga and how published events trigger subsequent steps in the Customer Service and Order Service.
Why it matters: It shows how the services coordinate the saga without describing a central controller. - Credit outcome branches: Describe the three credit-reservation outcomes and the Order Service’s response to each.
Why it matters: The outcome event determines whether the order is approved or rejected.
Key terms: choreography-based saga, Order Service, Customer Service, OrderCreated, publish/subscribe, Credit Reserved, Customer Lookup Failed, Credit Limit Exceeded, approveOrder(), rejectOrder()
10.1.2 Design elements: events, channels, publishers and handlers
This section explains the events, channels, publishers, and handlers that coordinate a choreography-based saga, and the design choices involved.
- Choreography event flow: Describe how participants exchange events through publisher-owned channels, using outbound adapters to publish and inbound adapters to handle them.
Why it matters: This is the basic arrangement that lets participants coordinate without a central orchestrator. - Dual purpose of saga events: Explain how an event type reports a service operation’s outcome while the event also carries data needed by other saga participants.
Why it matters: Participants need both the result of a step and the data required to perform later steps. - Integration versus domain events: Distinguish saga coordination events from domain events, including why their contents or timing can differ.
Why it matters: Treating every coordination event as a domain event would obscure why it may carry extra data or report no state change. - Integration event publisher choice: Explain when domain logic should publish an integration event and when the incoming event handler should publish it instead.
Why it matters: The publisher choice determines whether coordination-only data leaks into business logic. - Messaging API support: Describe the section’s stated benefits of using a high-level API rather than broker client APIs for event publishing and handling.
Why it matters: The choice of messaging API affects implementation effort and can supply useful publishing and duplicate-handling patterns.
Key terms: choreography-based saga, publish-subscribe channel, inbound adapter, outbound adapter, event handler, event type, service operation, system command, pass-through design-time coupling, integration events
10.1.3 Using fan-out choreography
This section shows how fan-out choreography reduces pass-through coupling in a Create Order saga, while making concurrent outcomes and compensation harder to coordinate.
- Pass-through coupling and fan-out: Explain how passing productSpecification through the Customer Service creates design-time coupling, and how fan-out choreography removes that dependency.
Why it matters: Fan-out can keep changes to request data from forcing unrelated services to change. - Concurrent outcome coordination: Describe why concurrently triggered reservations require extra Order states and careful handling of success and failure events.
Why it matters: The coupling benefit of fan-out comes with more complicated outcome handling. - Compensation after mixed outcomes: Explain how a successful reservation is compensated when the other reservation fails, and why each service checks its reservation state.
Why it matters: Compensation must work even when one forward reservation failed and there is nothing to undo. - API Gateway saga initiation: Describe how the API Gateway can start fan-out choreography, reduce pass-through coupling, and correlate an inventory reservation without an orderId.
Why it matters: Starting fan-out at the gateway can spare even the Order Service from forwarding request details it does not use.
Key terms: pass-through design-time coupling, fan-out choreography, linear choreography, productSpecification, Credit Reserved, Inventory Reserved, PENDING* states, failure events, compensating transactions, Order Rejected event
10.1.4 Benefits and drawbacks of choreography-based saga coordination
This section weighs the simplicity and loose coupling of choreography-based saga coordination against its distributed logic and potentially undesirable service dependencies.
- Simple event-based coordination: Explain why choreography is relatively straightforward to implement, especially for simple sagas.
Why it matters: Implementation simplicity is a principal reason to choose choreography for a simple saga. - Loose runtime coupling: Explain how asynchronous messaging reduces runtime coupling in a choreography-based saga and what broker delivery contributes when a participant is temporarily unavailable.
Why it matters: This explains a runtime benefit that is distinct from the design-time dependencies discussed later. - Fan-out and data flow: Explain how fan-out choreography can reduce pass-through design-time coupling.
Why it matters: Fan-out avoids making intermediary participants carry data solely for other services. - Distributed saga logic: Explain why a choreography-based saga becomes harder to understand as participants or interactions increase.
Why it matters: The ease of implementing individual event handlers can come at the cost of understanding the overall saga. - Undesirable design-time dependencies: Describe the potentially undesirable design-time dependency between the Customer Service and Order Service in the Create Order Saga.
Why it matters: Asynchronous runtime communication does not eliminate design-time dependencies between services. - Cyclic participant dependencies: Describe how choreography can create cyclic service dependencies, particularly when transactions are compensatable.
Why it matters: Event subscriptions can create two-way service dependencies even in an asynchronous design.
Key terms: choreography, publish and consume events, message broker client library, loose runtime coupling, asynchronous messages, at least once delivery guarantee, fan-out choreography, pass-through design-time coupling, API Gateway, choreography-based sagas
10.2 Orchestration-based sagas
Introduces orchestration as centralized saga coordination and identifies the main choices for placing and invoking the orchestrator.
- Centralized saga coordination: Explain how an orchestrator directs saga participants, chooses the next operation from the previous outcome, and handles a failed forward transaction.
Why it matters: This explains who directs the saga and how its progress responds to success or failure. - Orchestration design choices: Describe the alternatives this section identifies for participant invocation, orchestrator location, and step execution.
Why it matters: Orchestration describes a coordination approach, not one fixed placement or execution style.
Key terms: orchestrator, saga participants, forward transaction, compensating transactions, synchronously, asynchronously, sequentially, concurrently
10.2.1 Example orchestration-based Create Order Saga
This section traces how the Order Service orchestrates a Create Order Saga through credit and inventory reservations, including an out-of-stock failure path.
- Create Order orchestrator role: Explain how the CreateOrderSagaOrchestrator coordinates participants: it runs in the Order Service, tracks saga state, performs local Order Service operations, and uses asynchronous commands and replies to decide what happens next.
Why it matters: This explains who directs the saga and how participant replies affect its progress. - Successful order creation sequence: Trace the happy path from the Order Service starting the orchestrator through local Order creation, credit reservation, inventory reservation, and local Order approval.
Why it matters: The sequence shows how the orchestrator advances the Order only after the requested reservations succeed. - Out-of-stock failure path: Describe what the orchestrator does if the product is out of stock after credit has been reserved.
Why it matters: The failure path shows how the orchestrator reverses the earlier credit reservation before rejecting the Order.
Key terms: CreateOrderSagaOrchestrator, saga participants, asynchronous request/response, reply channel, Reserve Credit, Credit Reserved, Reserve Inventory, Inventory Reserved, Release Credit, reject the Order
10.2.2 Implementing the saga orchestrator
Explains how a saga orchestration framework models, persists, and executes an orchestrator’s state machine, and why reliable execution is more complex than the basic flow suggests.
- Saga state machine model: Explain how an orchestrator represents a saga as a state machine, using the Create Order Saga to distinguish in-progress states, outcome-driven transitions, and final states.
Why it matters: The model makes the orchestrator’s possible paths explicit enough to design and test. - Durable orchestrator state: Describe what the orchestrator stores as saga state, how that state changes, and why the framework persists it.
Why it matters: Persisted state lets the orchestrator retain both its place in the saga and the data it needs after a failure. - Participant driven execution: Trace how the framework starts the state machine and advances it in response to participants until it reaches an end state.
Why it matters: This sequence explains how the orchestrator turns a state-machine design into participant calls. - Reliable execution concerns: Explain why executing this apparently simple flow requires careful transaction and failure handling, distinguishing the concerns named for asynchronous and synchronous exchanges.
Why it matters: Calling participants is only part of execution; the framework must also preserve consistent progress through failures.
Key terms: state machine, 'ING_' states, entry action, transitions, final states, orchestrator state, application data, system command parameters, unique ID, database
10.2.3 Location of orchestrator
This section compares two locations for a saga orchestrator and the coupling and complexity trade-offs of each.
- Separate orchestration service trade-offs: Explain how a separate orchestration service acts as the system command’s entry point and why separating coordination simplifies participants but adds architectural and runtime costs.
Why it matters: The location of coordination changes both how independently participants can be designed and what must be available to answer a command. - Embedded orchestrator trade-offs: Explain how embedding the orchestrator in a participant changes the command’s entry point, service count, response dependency, and design-time responsibilities.
Why it matters: Embedding coordination can simplify the service architecture, but it moves coordination work and dependencies into a participant.
Key terms: separate orchestration service, system command’s entry point, participants, design-time coupling, runtime coupling, embedded in participant, entry point service, dual responsibilities
10.2.4 Implementing orchestration using asynchronous messaging
This section explains how an orchestration-based saga coordinates participants through asynchronous commands and replies, including message design, state-machine execution, and variations for local operations and one-way notifications.
- Asynchronous orchestration components: Describe how the orchestrator, participant command handlers, adapters, and message channels fit together in the Create Order Saga.
Why it matters: These components show where coordination and participant business logic run. - Command and channel design: Explain what command and reply messages contain, which channels carry them, and which team owns the participant-facing API.
Why it matters: The messages and channels form the contract that lets the orchestrator invoke participants and receive outcomes. - Participant interaction style choice: Distinguish when an orchestrator must use request/asynchronous-response from when it can use a one-way notification.
Why it matters: Choosing whether to wait for a reply affects both which operations are suitable and how quickly the saga can proceed. - Reply-driven state machine execution: Trace how a saga starts and advances through transactional state-machine steps using commands, replies, persisted state, and messaging reliability patterns.
Why it matters: This sequence explains how an asynchronous reply advances the right persisted saga instance without processing duplicate replies. - Local and notification state actions: Explain how state-machine execution differs for an embedded orchestrator’s local operations and for one-way notifications.
Why it matters: Not every saga step waits for a participant reply, so these cases need different state actions.
Key terms: saga orchestrator, command handler, inbound adapter, outbound adapter, reply handler, command message, reply message, command channel, reply channel, point-to-point channels
10.2.5 Implementing orchestration using synchronous request/response
This section explains how a saga orchestrator can invoke participants over HTTP, handle duplicate requests, and persist and retry execution when communication fails.
- HTTP orchestration design: Describe how the orchestrator invokes saga participants using synchronous request/response and where the REST endpoints and HTTP client reside in the Create Order Saga.
Why it matters: The adapters show how the orchestrator reaches each participant without using messages. - Idempotent participant requests: Explain how participants recognize a retried HTTP command and respond to it.
Why it matters: A retry can repeat a request, so participants need a way to recognize that they have already handled it. - HTTP state transitions and retries: Trace how an HTTP-based saga state advances on a response and what it does when no response arrives. Explain why the orchestrator needs its own retry logic.
Why it matters: An unanswered HTTP request must not be mistaken for a completed saga step. - Persisted execution and recovery: Trace the saga execution loop, distinguishing database work from HTTP requests, and describe how failed or abandoned instances resume.
Why it matters: Persisted state lets the orchestrator resume work after an HTTP error or its own crash.
Key terms: synchronous request/response, outbound adapter, inbound adapter, REST endpoint, idempotency key, Idempotency-Key, idempotency token, duplicate request, state entry action, HTTP response
10.2.6 Benefits and drawbacks of orchestration-based sagas
This section weighs the benefits of orchestration-based sagas against their added complexity and the risk of putting participant business logic in the orchestrator.
- Centralized and trackable saga: Explain how a centralized saga definition and persistent saga state make an orchestration-based saga easier to understand and track.
Why it matters: These benefits make it easier to see what a saga is and inspect its state. - Participant coupling and responsibilities: Explain how orchestration reduces design-time coupling between participants and keeps saga coordination logic out of their business logic.
Why it matters: This division of responsibilities is a principal reason to choose orchestration. - Orchestration costs and boundary: Describe orchestration’s added complexity relative to choreography and the risk of moving participant business logic into the orchestrator.
Why it matters: The trade-off is not just framework complexity: the orchestrator must also respect participants’ business responsibilities.
Key terms: saga orchestrator, centralized definition, persistent, design-time coupling, saga coordination logic, participants, saga orchestration framework, Insider trading code smell, smart orchestrator and dumb participants
10.3 Summary
Where this is used later
- The Create Order Saga's orchestrators design (chapter 11) · Introduces orchestration-based sagas.
- The Eventuate Platform’s Tram Saga framework (chapter 11) · The orchestration-based Create Order Saga example.
- The FTGO Create Order Saga definition (chapter 11) · The FTGO Create Order Saga definition develops the example’s sequence.
- The CreateOrderSaga orchestrator class (chapter 11) · The orchestration-based Create Order saga’s interactions with participants.
- The CreateOrderSagaState class (chapter 11) · Applies the idea of application-specific saga state to the CreateOrderSagaState class.
- The saga participant command handlers (chapter 11) · The saga participant command handlers are designed in detail.
Concepts explained in this chapter
- saga orchestratorA saga orchestrator coordinates saga steps by invoking participants, maintaining saga state, and determining what to do based on their outcomes.
- choreography-based sagaLinear choreography is a saga coordination pattern in which events trigger saga participants sequentially.
- finite-state machineA state machine is a computational model consisting of states and defined transitions between them in response to events or conditions.
- saga participantA service or component that performs one or more local transactions as part of a saga.
- orchestration serviceAn orchestration service is a service that executes saga orchestration by persisting saga state, making participant requests, and retrying failed executions.
- fan-out choreographyA choreography arrangement in which a request or event is published to multiple participants that independently consume the data they need.
- retryA retry mechanism is logic that repeats a failed operation to recover from transient failures.
- saga stateSaga state is the durable data recording a saga instance's execution position and information needed to continue it.
- orchestration-based saga coordinationA saga whose steps are coordinated by a centralized orchestrator.
- domain eventAn event representing a business-significant state change of a domain entity or aggregate.
- event channelAn event channel is a named communication path that transports events published by a saga participant.
- event publisherAn event publisher is a component that emits integration events after a service operation or event handler has processed an input.
- handlerAn event handler is a software component that receives an event and performs the associated processing.
- integration eventAn integration event is an event exchanged between services that communicates an operation result or transports data needed by another service.
- channelA communication path through which messages are sent and received.
- command channelA command channel is a message channel through which a participant receives command messages.
- command producer outbound adapterA command producer outbound adapter is an outbound adapter that creates and sends command messages to saga participants.
- inbound reply handler adapterAn inbound reply handler adapter is an inbound adapter that receives participant reply messages and invokes saga orchestration logic.
- saga instanceA saga instance is a runtime record representing one execution of a saga, including its request data and current state.
- pass-through design-time couplingA dependency caused when intermediate services must carry data that their own business logic does not use.
- synchronous callSynchronous code performs operations in a sequence that waits for each operation to complete before continuing.
- sagaA distributed transaction pattern that coordinates a sequence of local transactions and, when necessary, compensating actions across services.
- publish-subscribe patternA messaging channel that distributes each published message to subscribing consumers.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
