Documentation
¶
Overview ¶
Package saga provides an implementation for the [SAGA pattern](https://microservices.io/patterns/data/saga.html) for [transaction like distribution processes](https://learn.microsoft.com/en-us/azure/architecture/patterns/saga) across multiple services without relying on a global ACID transaction. The SAGA orchestration pattern breaks a distributed business operation into a sequence of local transactions coordinated by a central orchestrator. Each step executes independently, and if any step fails, the orchestrator triggers compensating transactions in reverse order to undo completed work, following the [Compensating Transaction pattern](https://en.wikipedia.org/wiki/Compensating_transaction?utm_source=chatgpt.com) (https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction). To make sagas safe across retries, failures, or orchestrator crashes, compensating transactions must themselves be designed to be idempotent and retryable. That way if a compensation fails (or the orchestrator crashes mid-rollback), they can be resumed/ retried without risk of double-undo or inconsistent state. For that purpose, idempotency keys are used, ensuring repeated “execute” or “compensate” calls do not duplicate effects, as described in [idempotency practices](https://brandur.org/idempotency-keys)
Index ¶
- type IActionArguments
- type IActionIdentifier
- type ISagaOrchestrator
- type ITransactionStep
- type MinimalSaga
- func (s *MinimalSaga) Clone() parallelisation.IExecutionGroup[ITransactionStep]
- func (s *MinimalSaga) CopyFunctions(g parallelisation.IExecutionGroup[ITransactionStep])
- func (s *MinimalSaga) Execute(ctx context.Context) error
- func (s *MinimalSaga) GetCompensation() parallelisation.IExecutionGroup[ITransactionStep]
- func (s *MinimalSaga) GetTransaction() parallelisation.IExecutionGroup[ITransactionStep]
- func (s *MinimalSaga) Len() int
- func (s *MinimalSaga) NewSaga(args IActionArguments) *MinimalSaga
- func (s *MinimalSaga) RegisterFunction(function ...ITransactionStep)
- func (s *MinimalSaga) RegisterFunctions(function iter.Seq[ITransactionStep])
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type IActionArguments ¶
type IActionArguments interface {
// GetIdemKey return idempotent key to ensure safe
// retries and crash recovery, preventing duplicate side effects.
GetIdemKey() string
GetArguments() map[string]any
}
func NewStepArguments ¶
func NewStepArguments(args map[string]any) IActionArguments
func NewStepArgumentsWithIdempotentKey ¶
func NewStepArgumentsWithIdempotentKey(idemKey string, args map[string]any) IActionArguments
func NoStepArguments ¶
func NoStepArguments() IActionArguments
type IActionIdentifier ¶
func NewStepIdentifier ¶
func NewStepIdentifier(name, namespace string) IActionIdentifier
type ISagaOrchestrator ¶
type ISagaOrchestrator interface {
parallelisation.IExecutionGroup[ITransactionStep]
}
ISagaOrchestrator coordinates a sequence of local transactions (ITransactionStep) to achieve an eventually consistent distributed workflow without relying on a global ACID transaction. Each step has a forward action (Execute) and a compensating action (Compensate). The orchestrator executes steps in order; if any step fails, it triggers compensating actions in reverse order to undo previously completed steps.
This pattern is useful for long-running or cross-service operations where traditional two-phase commit is impractical.
References:
- Saga Pattern: https://en.wikipedia.org/wiki/Long-running_transaction https://learn.microsoft.com/en-us/azure/architecture/patterns/saga
- Compensating Transaction Pattern: https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction
- Saga Pattern (microservices.io): https://microservices.io/patterns/data/saga.html
type ITransactionStep ¶
type ITransactionStep interface {
// GetID returns an identifier of the action
GetID() IActionIdentifier
// Execute performs the forward action.
Execute(ctx context.Context, args IActionArguments) error
// Compensate performs the compensating/rollback action.
Compensate(ctx context.Context, args IActionArguments) error
}
ITransactionStep describes a step in the transaction across a distributed system.
type MinimalSaga ¶
type MinimalSaga struct {
// contains filtered or unexported fields
}
func (*MinimalSaga) Clone ¶
func (s *MinimalSaga) Clone() parallelisation.IExecutionGroup[ITransactionStep]
Clone returns a clone of the orchestrator and its execution state.
func (*MinimalSaga) CopyFunctions ¶
func (s *MinimalSaga) CopyFunctions(g parallelisation.IExecutionGroup[ITransactionStep])
func (*MinimalSaga) GetCompensation ¶
func (s *MinimalSaga) GetCompensation() parallelisation.IExecutionGroup[ITransactionStep]
func (*MinimalSaga) GetTransaction ¶
func (s *MinimalSaga) GetTransaction() parallelisation.IExecutionGroup[ITransactionStep]
func (*MinimalSaga) Len ¶
func (s *MinimalSaga) Len() int
func (*MinimalSaga) NewSaga ¶
func (s *MinimalSaga) NewSaga(args IActionArguments) *MinimalSaga
func (*MinimalSaga) RegisterFunction ¶
func (s *MinimalSaga) RegisterFunction(function ...ITransactionStep)
func (*MinimalSaga) RegisterFunctions ¶
func (s *MinimalSaga) RegisterFunctions(function iter.Seq[ITransactionStep])
Source Files