Saga: как оркестрировать распределённые процессы

Saga: как оркестрировать распределённые процессы

Когда бизнес-процесс затрагивает несколько сервисов, возникает вопрос: как обеспечить согласованность? В монолите ответ простой - транзакция БД. В микросервисной архитектуре каждый сервис владеет своей базой, и общей транзакции нет. Two-Phase Commit (2PC) технически возможен, но на практике не масштабируется, держит блокировки слишком долго и создаёт single point of failure в координаторе.

Saga - это альтернатива распределённым транзакциям. Вместо одной атомарной операции мы выполняем цепочку локальных транзакций, а для отката определяем компенсирующие действия к каждому шагу.

Анатомия Saga

Saga состоит из шагов. Каждый шаг - это пара: действие (Execute) и компенсация (Compensate). Если шаг N упал, мы последовательно откатываем шаги N-1, N-2, ..., 1, вызывая их компенсации.

Пример - оформление заказа с оплатой и выдачей доступа:

Шаг 1: Создать заказ (status=pending)
  └─ Компенсация: Отменить заказ (status=cancelled)

Шаг 2: Списать оплату
  └─ Компенсация: Вернуть деньги (refund)

Шаг 3: Выдать доступ к курсу
  └─ Компенсация: Отозвать доступ

Если выдача доступа (шаг 3) провалилась - возвращаем деньги (компенсация шага 2) и отменяем заказ (компенсация шага 1).

Saga: happy path - все шаги; failure path - откат назад через компенсации

Orchestration Saga: центральный координатор

В оркестрационной саге один компонент (оркестратор) управляет всеми шагами. Он знает порядок выполнения и запускает компенсации при сбое.

Структура шага и оркестратор

// Step - один шаг саги: действие и его компенсация.
//
// Обе функции получают транзакцию: шаг обязан записывать свой эффект и отметку
// о себе одной командой COMMIT. Иначе «состояние саги в базе» разъезжается
// с реальностью ровно так же, как отметка в inbox с бизнес-операцией.
type Step struct {
	Name       string
	Execute    func(ctx context.Context, tx *sql.Tx) error
	Compensate func(ctx context.Context, tx *sql.Tx) error
}

// Orchestrator выполняет шаги по порядку, при сбое откатывает выполненные.
type Orchestrator struct {
	db    *sql.DB
	log   *slog.Logger
	steps []Step
}

func New(db *sql.DB, log *slog.Logger, steps ...Step) *Orchestrator {
	return &Orchestrator{db: db, log: log, steps: steps}
}

// Run выполняет сагу с идентификатором sagaID.
//
// Идентификатор нужен не для логов: он ключ идемпотентности. Повторный запуск
// той же саги не должен повторять уже выполненные шаги, а восстановление
// после перезапуска процесса - находить их в базе, а не в памяти.
func (o *Orchestrator) Run(ctx context.Context, sagaID string) error {
	// Журнал из базы: какие шаги этой саги уже выполнены прошлым запуском.
	done, err := o.doneSteps(ctx, sagaID)
	if err != nil {
		return err
	}

	for _, step := range o.steps {
		if done[step.Name] {
			continue // шаг уже сделан - повтор дал бы второе списание
		}
		if err := o.runStep(ctx, sagaID, step); err != nil {
			o.log.ErrorContext(ctx, "saga step failed, compensating",
				slog.String("saga_id", sagaID),
				slog.String("step", step.Name),
				slog.String("err", err.Error()),
			)

			// Компенсации идут отдельной операцией и **возвращают** ошибку.
			// Проглотить её значит оставить сагу в промежуточном состоянии
			// молча - «оплачено, но не выдано» без единого сигнала.
			if cErr := o.Compensate(ctx, sagaID); cErr != nil {
				return fmt.Errorf("шаг %q упал (%w), откат не завершён: %w",
					step.Name, err, cErr)
			}
			return fmt.Errorf("сага %s: шаг %q: %w", sagaID, step.Name, err)
		}
	}
	return nil
}

// runStep выполняет один шаг: действие и отметку о нём одной транзакцией.
func (o *Orchestrator) runStep(ctx context.Context, sagaID string, step Step) error {
	tx, err := o.db.BeginTx(ctx, nil)
	if err != nil {
		return fmt.Errorf("begin tx: %w", err)
	}
	defer tx.Rollback()

	if err := step.Execute(ctx, tx); err != nil {
		return err
	}

	// Отметка в том же COMMIT, что и эффект шага. Порядок здесь не важен -
	// важно, что они в одной транзакции: иначе после сбоя журнал скажет
	// «шаг сделан», а эффекта не будет (или наоборот).
	if err := markStep(ctx, tx, sagaID, step.Name, faultsql.StepDone); err != nil {
		return err
	}
	return tx.Commit()
}

// Compensate откатывает все шаги саги, помеченные выполненными.
//
// Отдельный экспортируемый метод, а не приватная часть Run: после
// перезапуска процесса откат должен продолжиться, и запускать его будет
// внешний восстановитель, у которого нет ни `executed`, ни стека вызовов -
// только sagaID и база.
func (o *Orchestrator) Compensate(ctx context.Context, sagaID string) error {
	done, err := o.doneSteps(ctx, sagaID)
	if err != nil {
		return err
	}

	var failed []string
	// Обратный порядок: шаги откатываются от последнего к первому.
	for i := len(o.steps) - 1; i >= 0; i-- {
		step := o.steps[i]
		if !done[step.Name] {
			continue
		}
		if err := o.compensateStep(ctx, sagaID, step); err != nil {
			// Не прекращаем откат: остальные шаги тоже надо попытаться
			// откатить. Но и не забываем - список уйдёт вызывающему.
			o.log.ErrorContext(ctx, "compensation failed",
				slog.String("saga_id", sagaID),
				slog.String("step", step.Name),
				slog.String("err", err.Error()),
			)
			failed = append(failed, step.Name)
		}
	}

	if len(failed) > 0 {
		return fmt.Errorf("%w: шаги %v требуют вмешательства", ErrCompensationFailed, failed)
	}
	return nil
}

// compensateStep откатывает шаг и обновляет журнал одной транзакцией.
func (o *Orchestrator) compensateStep(ctx context.Context, sagaID string, step Step) error {
	tx, err := o.db.BeginTx(ctx, nil)
	if err != nil {
		return fmt.Errorf("begin tx: %w", err)
	}
	defer tx.Rollback()

	if err := step.Compensate(ctx, tx); err != nil {
		// Пометку о неудаче пишем **отдельной** транзакцией: та, в которой
		// упала компенсация, откатится и унесёт пометку с собой.
		o.markCompensationFailed(ctx, sagaID, step.Name)
		return err
	}

	if err := markStep(ctx, tx, sagaID, step.Name, faultsql.StepCompensated); err != nil {
		return err
	}
	return tx.Commit()
}

// markCompensationFailed фиксирует, что откат шага не удался.
//
// Ошибку записи здесь только логируем: если и она не прошла, сага уже
// в состоянии, требующем человека, а вернуть мы всё равно должны исходную
// ошибку компенсации - она информативнее.
func (o *Orchestrator) markCompensationFailed(ctx context.Context, sagaID, step string) {
	tx, err := o.db.BeginTx(ctx, nil)
	if err != nil {
		o.log.ErrorContext(ctx, "cannot record compensation failure",
			slog.String("saga_id", sagaID), slog.String("step", step),
			slog.String("err", err.Error()))
		return
	}
	defer tx.Rollback()

	if err := markStep(ctx, tx, sagaID, step, faultsql.StepCompensationFailed); err != nil {
		o.log.ErrorContext(ctx, "cannot record compensation failure",
			slog.String("saga_id", sagaID), slog.String("step", step),
			slog.String("err", err.Error()))
		return
	}
	if err := tx.Commit(); err != nil {
		o.log.ErrorContext(ctx, "cannot commit compensation failure",
			slog.String("saga_id", sagaID), slog.String("step", step),
			slog.String("err", err.Error()))
	}
}

// doneSteps читает из базы шаги, которые выполнены и ещё не откачены.
func (o *Orchestrator) doneSteps(ctx context.Context, sagaID string) (map[string]bool, error) {
	rows, err := o.db.QueryContext(ctx,
		`SELECT step FROM saga_steps WHERE saga_id = $1 AND state = $2`,
		sagaID, string(faultsql.StepDone),
	)
	if err != nil {
		return nil, fmt.Errorf("query saga steps: %w", err)
	}
	defer rows.Close()

	done := map[string]bool{}
	for rows.Next() {
		var step string
		if err := rows.Scan(&step); err != nil {
			return nil, fmt.Errorf("scan step: %w", err)
		}
		done[step] = true
	}
	return done, rows.Err()
}

// markStep пишет состояние шага. UPSERT, потому что шаг может быть записан
// повторно: retry, восстановление после перезапуска, повторная компенсация.
func markStep(ctx context.Context, tx *sql.Tx, sagaID, step string, st faultsql.StepState) error {
	_, err := tx.ExecContext(ctx,
		`INSERT INTO saga_steps (saga_id, step, state) VALUES ($1, $2, $3)
		 ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state`,
		sagaID, step, string(st),
	)
	if err != nil {
		return fmt.Errorf("mark step %q as %s: %w", step, st, err)
	}
	return nil
}

<?php
// src/Application/Saga/SagaStep.php
declare(strict_types=1);

namespace App\Application\Saga;

use Closure;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Throwable;
use RuntimeException;

// Один шаг саги: действие + компенсация. Immutable - readonly properties.
// Обе функции получают соединение с открытой транзакцией: эффект шага
// и отметка о нём коммитятся вместе (как *sql.Tx в Go-версии).
final readonly class SagaStep
{
    /**
     * @param Closure(Connection):void $execute
     * @param Closure(Connection):void $compensate
     */
    public function __construct(
        public string $name,
        public Closure $execute,
        public Closure $compensate,
    ) {}
}

final class SagaFailedException extends RuntimeException {}

// Откат не завершён: часть шагов требует вмешательства оператора.
final class CompensationFailedException extends RuntimeException {}

// src/Application/Saga/SagaOrchestrator.php
// Состояние саги живёт в журнале saga_steps (saga_id, step, state), а не в памяти.
final class SagaOrchestrator
{
    private const DONE = 'done';
    private const COMPENSATED = 'compensated';
    private const COMPENSATION_FAILED = 'compensation_failed';

    /** @param list<SagaStep> $steps */
    public function __construct(
        private readonly Connection $connection,
        private readonly LoggerInterface $logger,
        private readonly array $steps,
    ) {}

    // sagaId - ключ идемпотентности: повторный запуск той же саги пропускает
    // шаги, которые журнал уже знает как выполненные.
    public function run(string $sagaId): void
    {
        $done = $this->doneSteps($sagaId);

        foreach ($this->steps as $step) {
            if (isset($done[$step->name])) {
                continue;
            }

            try {
                // Эффект шага и отметка о нём - одна транзакция
                $this->connection->transactional(function (Connection $tx) use ($sagaId, $step): void {
                    ($step->execute)($tx);
                    $this->markStep($tx, $sagaId, $step->name, self::DONE);
                });
            } catch (Throwable $e) {
                $this->logger->error('saga step failed, compensating', [
                    'saga_id' => $sagaId,
                    'step' => $step->name,
                    'err' => $e->getMessage(),
                ]);

                // Сбой компенсации не проглатываем: он уходит вызывающему
                try {
                    $this->compensate($sagaId);
                } catch (CompensationFailedException $c) {
                    throw new SagaFailedException(
                        sprintf('step %s failed (%s), compensation incomplete: %s', $step->name, $e->getMessage(), $c->getMessage()),
                        0,
                        $c,
                    );
                }
                throw new SagaFailedException(sprintf('saga %s failed at step %s', $sagaId, $step->name), 0, $e);
            }
        }
    }

    // Публичный метод, а не приватная часть run: после перезапуска процесса
    // откат продолжает внешний восстановитель, у которого есть только sagaId и база.
    public function compensate(string $sagaId): void
    {
        $done = $this->doneSteps($sagaId);
        $failed = [];

        // Обратный порядок: шаги откатываются от последнего к первому
        foreach (array_reverse($this->steps) as $step) {
            if (!isset($done[$step->name])) {
                continue;
            }

            try {
                $this->connection->transactional(function (Connection $tx) use ($sagaId, $step): void {
                    ($step->compensate)($tx);
                    $this->markStep($tx, $sagaId, $step->name, self::COMPENSATED);
                });
            } catch (Throwable $e) {
                // Транзакция с упавшей компенсацией откатилась вместе с пометкой,
                // поэтому пометку о неудаче пишем отдельной транзакцией.
                $this->markCompensationFailed($sagaId, $step->name);
                $this->logger->error('compensation failed', [
                    'saga_id' => $sagaId,
                    'step' => $step->name,
                    'err' => $e->getMessage(),
                ]);
                // Не прекращаем откат, но и не забываем - список уйдёт вызывающему
                $failed[] = $step->name;
            }
        }

        if ($failed !== []) {
            throw new CompensationFailedException(
                sprintf('steps %s need operator attention', implode(', ', $failed)),
            );
        }
    }

    private function markCompensationFailed(string $sagaId, string $step): void
    {
        try {
            $this->connection->transactional(
                fn (Connection $tx) => $this->markStep($tx, $sagaId, $step, self::COMPENSATION_FAILED),
            );
        } catch (Throwable $e) {
            $this->logger->error('cannot record compensation failure', [
                'saga_id' => $sagaId,
                'step' => $step,
                'err' => $e->getMessage(),
            ]);
        }
    }

    /** @return array<string, true> шаги, которые выполнены и ещё не откачены */
    private function doneSteps(string $sagaId): array
    {
        $names = $this->connection->fetchFirstColumn(
            'SELECT step FROM saga_steps WHERE saga_id = :id AND state = :state',
            ['id' => $sagaId, 'state' => self::DONE],
        );

        return array_fill_keys($names, true);
    }

    // UPSERT: шаг может быть записан повторно (retry, восстановление, повторный откат)
    private function markStep(Connection $tx, string $sagaId, string $step, string $state): void
    {
        $tx->executeStatement(
            'INSERT INTO saga_steps (saga_id, step, state) VALUES (:id, :step, :state)
             ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state',
            ['id' => $sagaId, 'step' => $step, 'state' => $state],
        );
    }
}
# application/saga/step.py
from dataclasses import dataclass
from typing import Callable

from psycopg import Cursor


# Step - один шаг саги: действие и его компенсация.
#
# Обе функции получают курсор открытой транзакции: шаг обязан записывать свой эффект
# и отметку о себе одной командой COMMIT. Иначе «состояние саги в базе» разъезжается
# с реальностью ровно так же, как отметка в inbox с бизнес-операцией.
# Сбой шага - исключение, а не возвращаемая ошибка.
@dataclass(frozen=True, slots=True)
class Step:
    name: str
    execute: Callable[[Cursor], None]
    compensate: Callable[[Cursor], None]
# application/saga/orchestrator.py
import logging
from enum import Enum

from psycopg import Connection, Cursor


class StepState(str, Enum):
    DONE = "done"
    COMPENSATED = "compensated"
    COMPENSATION_FAILED = "compensation_failed"


class CompensationFailedError(Exception):
    """Откат не завершён: часть шагов требует вмешательства оператора."""


class SagaError(Exception):
    """Сага упала и откатилась (или откатилась не до конца - см. __cause__)."""


class Orchestrator:
    """Выполняет шаги по порядку, при сбое откатывает выполненные."""

    def __init__(self, conn: Connection, log: logging.Logger, *steps: Step) -> None:
        self._conn = conn
        self._log = log
        self._steps = steps

    # run выполняет сагу с идентификатором saga_id.
    #
    # Идентификатор нужен не для логов: он ключ идемпотентности. Повторный запуск
    # той же саги не должен повторять уже выполненные шаги, а восстановление
    # после перезапуска процесса - находить их в базе, а не в памяти.
    def run(self, saga_id: str) -> None:
        done = self._done_steps(saga_id)
        for step in self._steps:
            if step.name in done:
                continue  # шаг уже выполнен прошлым запуском - не повторяем
            try:
                self._run_step(saga_id, step)
            except Exception as err:
                self._log.error(
                    "saga step failed, compensating",
                    extra={"saga_id": saga_id, "step": step.name, "err": str(err)},
                )

                # Компенсации идут отдельной операцией и пробрасывают ошибку.
                # Проглотить её значит оставить сагу в промежуточном состоянии
                # молча - «оплачено, но не выдано» без единого сигнала.
                try:
                    self.compensate(saga_id)
                except Exception as c_err:
                    raise SagaError(
                        f"шаг {step.name!r} упал ({err}), откат не завершён: {c_err}"
                    ) from c_err
                raise SagaError(f"сага {saga_id}: шаг {step.name!r}: {err}") from err

    def _run_step(self, saga_id: str, step: Step) -> None:
        """Выполняет один шаг: действие и отметку о нём одной транзакцией."""
        # Выход из with без исключения - COMMIT, с исключением - ROLLBACK.
        with self._conn.transaction(), self._conn.cursor() as cur:
            step.execute(cur)

            # Отметка в том же COMMIT, что и эффект шага. Порядок здесь не важен -
            # важно, что они в одной транзакции: иначе после сбоя журнал скажет
            # «шаг сделан», а эффекта не будет (или наоборот).
            _mark_step(cur, saga_id, step.name, StepState.DONE)

    # compensate откатывает все шаги саги, помеченные выполненными.
    #
    # Отдельный публичный метод, а не приватная часть run: после
    # перезапуска процесса откат должен продолжиться, и запускать его будет
    # внешний восстановитель, у которого нет ни списка executed, ни стека вызовов -
    # только saga_id и база.
    def compensate(self, saga_id: str) -> None:
        done = self._done_steps(saga_id)

        failed: list[str] = []
        # Обратный порядок: шаги откатываются от последнего к первому.
        for step in reversed(self._steps):
            if step.name not in done:
                continue
            try:
                self._compensate_step(saga_id, step)
            except Exception as err:
                # Не прекращаем откат: остальные шаги тоже надо попытаться
                # откатить. Но и не забываем - список уйдёт вызывающему.
                self._log.error(
                    "compensation failed",
                    extra={"saga_id": saga_id, "step": step.name, "err": str(err)},
                )
                failed.append(step.name)

        if failed:
            raise CompensationFailedError(f"шаги {failed} требуют вмешательства")

    def _compensate_step(self, saga_id: str, step: Step) -> None:
        """Откатывает шаг и обновляет журнал одной транзакцией."""
        try:
            with self._conn.transaction(), self._conn.cursor() as cur:
                step.compensate(cur)
                _mark_step(cur, saga_id, step.name, StepState.COMPENSATED)
        except Exception:
            # Транзакция с упавшей компенсацией уже откатилась и унесла бы пометку
            # с собой - поэтому пометку о неудаче пишем отдельной транзакцией.
            self._mark_compensation_failed(saga_id, step.name)
            raise

    # _mark_compensation_failed фиксирует, что откат шага не удался.
    #
    # Ошибку записи здесь только логируем: если и она не прошла, сага уже
    # в состоянии, требующем человека, а пробросить мы всё равно должны исходную
    # ошибку компенсации - она информативнее.
    def _mark_compensation_failed(self, saga_id: str, step: str) -> None:
        try:
            with self._conn.transaction(), self._conn.cursor() as cur:
                _mark_step(cur, saga_id, step, StepState.COMPENSATION_FAILED)
        except Exception as err:
            self._log.error(
                "cannot record compensation failure",
                extra={"saga_id": saga_id, "step": step, "err": str(err)},
            )

    def _done_steps(self, saga_id: str) -> set[str]:
        """Читает из базы шаги, которые выполнены и ещё не откачены."""
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                "SELECT step FROM saga_steps WHERE saga_id = %s AND state = %s",
                (saga_id, StepState.DONE.value),
            )
            return {step for (step,) in cur.fetchall()}


def _mark_step(cur: Cursor, saga_id: str, step: str, state: StepState) -> None:
    """Пишет состояние шага. UPSERT, потому что шаг может быть записан
    повторно: retry, восстановление после перезапуска, повторная компенсация.
    """
    cur.execute(
        """INSERT INTO saga_steps (saga_id, step, state) VALUES (%s, %s, %s)
           ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state""",
        (saga_id, step, state.value),
    )

Реальный пример - CreateOrder Saga

// CreateOrderSaga оформляет заказ: создаёт его, списывает оплату, выдаёт доступ.
//
// Данные для компенсаций не живут в замыканиях: ID заказа задаётся снаружи
// и совпадает с ID саги. Поэтому откат после перезапуска процесса
// (Compensate(ctx, orderID)) знает, что отменять, без состояния в памяти.
// req после рестарта восстанавливается из saga_states.payload (раздел Persistence ниже).
// Сервисы здесь - модули того же монолита и пишут в транзакцию шага tx.
func CreateOrderSaga(
    db *sql.DB,
    log *slog.Logger,
    orderSvc OrderService,
    paymentSvc PaymentService,
    accessSvc AccessService,
    orderID string,
    req CreateOrderRequest,
) *Orchestrator {
    return New(db, log,
        Step{
            Name: "create_order",
            Execute: func(ctx context.Context, tx *sql.Tx) error {
                return orderSvc.Create(ctx, tx, orderID, req.UserID, req.CourseID)
            },
            Compensate: func(ctx context.Context, tx *sql.Tx) error {
                return orderSvc.Cancel(ctx, tx, orderID)
            },
        },
        Step{
            Name: "charge_payment",
            Execute: func(ctx context.Context, tx *sql.Tx) error {
                return paymentSvc.Charge(ctx, tx, req.UserID, req.Amount, orderID)
            },
            Compensate: func(ctx context.Context, tx *sql.Tx) error {
                return paymentSvc.Refund(ctx, tx, orderID)
            },
        },
        Step{
            Name: "grant_access",
            Execute: func(ctx context.Context, tx *sql.Tx) error {
                return accessSvc.GrantCourseAccess(ctx, tx, req.UserID, req.CourseID)
            },
            Compensate: func(ctx context.Context, tx *sql.Tx) error {
                return accessSvc.RevokeCourseAccess(ctx, tx, req.UserID, req.CourseID)
            },
        },
    )
}

// Использование:
// orderID := uuid.NewString() // он же ID саги
// saga := CreateOrderSaga(db, log, orderSvc, paymentSvc, accessSvc, orderID, req)
// if err := saga.Run(ctx, orderID); err != nil {
//     // Сага откатилась; если откат не завершён - err оборачивает ErrCompensationFailed
//     return fmt.Errorf("order creation failed: %w", err)
// }
<?php
// src/Application/Saga/CreateOrderSaga.php
declare(strict_types=1);

namespace App\Application\Saga;

use App\Application\Port\AccessService;
use App\Application\Port\OrderService;
use App\Application\Port\PaymentService;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;

final class CreateOrderSaga
{
    public function __construct(
        private readonly Connection $connection,
        private readonly LoggerInterface $logger,
        private readonly OrderService $orders,
        private readonly PaymentService $payments,
        private readonly AccessService $access,
    ) {}

    // orderId задаётся снаружи и служит ID саги: компенсации знают, что отменять,
    // даже после перезапуска процесса - без состояния в замыканиях.
    public function orchestrator(string $orderId, CreateOrderRequest $req): SagaOrchestrator
    {
        return new SagaOrchestrator($this->connection, $this->logger, [
            new SagaStep(
                name: 'create_order',
                execute: fn (Connection $tx) => $this->orders->create($tx, $orderId, $req->userId, $req->courseId),
                compensate: fn (Connection $tx) => $this->orders->cancel($tx, $orderId),
            ),
            new SagaStep(
                name: 'charge_payment',
                execute: fn (Connection $tx) => $this->payments->charge($tx, $req->userId, $req->amount, $orderId),
                compensate: fn (Connection $tx) => $this->payments->refund($tx, $orderId),
            ),
            new SagaStep(
                name: 'grant_access',
                execute: fn (Connection $tx) => $this->access->grantCourseAccess($tx, $req->userId, $req->courseId),
                compensate: fn (Connection $tx) => $this->access->revokeCourseAccess($tx, $req->userId, $req->courseId),
            ),
        ]);
    }

    public function run(string $orderId, CreateOrderRequest $req): void
    {
        $this->orchestrator($orderId, $req)->run(sagaId: $orderId);
    }
}
# application/saga/create_order_saga.py
import logging

from psycopg import Connection, Cursor


def create_order_saga(
    conn: Connection,
    log: logging.Logger,
    order_svc: OrderService,
    payment_svc: PaymentService,
    access_svc: AccessService,
    order_id: str,
    req: CreateOrderRequest,
) -> Orchestrator:
    """Оформляет заказ: создаёт его, списывает оплату, выдаёт доступ.

    order_id задаётся снаружи и служит ID саги: компенсации знают, что отменять,
    даже после перезапуска процесса - без состояния в замыканиях.
    Сервисы получают курсор открытой транзакции шага - их эффект коммитится
    вместе с отметкой о шаге (см. Step выше).
    """

    def create_order(cur: Cursor) -> None:
        order_svc.create(cur, order_id, req.user_id, req.course_id)

    def cancel_order(cur: Cursor) -> None:
        order_svc.cancel(cur, order_id)

    def charge_payment(cur: Cursor) -> None:
        payment_svc.charge(cur, req.user_id, req.amount, order_id)

    def refund_payment(cur: Cursor) -> None:
        payment_svc.refund(cur, order_id)

    def grant_access(cur: Cursor) -> None:
        access_svc.grant_course_access(cur, req.user_id, req.course_id)

    def revoke_access(cur: Cursor) -> None:
        access_svc.revoke_course_access(cur, req.user_id, req.course_id)

    return Orchestrator(
        conn,
        log,
        Step(name="create_order", execute=create_order, compensate=cancel_order),
        Step(name="charge_payment", execute=charge_payment, compensate=refund_payment),
        Step(name="grant_access", execute=grant_access, compensate=revoke_access),
    )


# Использование:
# order_id = str(uuid.uuid4())  # он же ID саги
# saga = create_order_saga(conn, log, order_svc, payment_svc, access_svc, order_id, req)
# try:
#     saga.run(saga_id=order_id)
# except SagaError as err:
#     # Saga откатилась, все компенсации выполнены (или в err.__cause__ - какие нет)
#     raise OrderCreationFailed("order creation failed") from err

⚠️ Три вещи, которых не было в первой версии этого кода

Оркестратор в этом уроке раньше был короче - и нарушал два правила, записанных в самом уроке разделами ниже. Оба дефекта проявляются только под сбоем, поэтому и прожили долго.

1. Состояние саги жило в памяти. Список выполненных шагов был локальной переменной executed. Процесс перезапустился на середине - и знания «что надо откатить» не осталось нигде. Раздел типичных ошибок требует «сохраняй состояние саги в БД после каждого шага», код этого не делал. Теперь Compensate - отдельный метод, которому нужен только sagaID: он читает журнал из базы, поэтому откат может продолжить любой другой процесс.

2. Сбой компенсации проглатывался. compensate логировала ошибку и шла дальше, ничего не возвращая. Снаружи это выглядело как «сага откатилась», хотя средний шаг застрял в «оплачено, но не выдано». Тот же урок пишет: «Каждый сбой компенсации = алёрт оператора, не просто запись в лог». Теперь ошибка возвращается вызывающему вместе со списком застрявших шагов, а сами шаги помечаются в журнале - по этой пометке оператор их и находит.

3. Шаг и отметка о нём - в одной транзакции, если шаг локальный. Отсюда *sql.Tx в сигнатуре Execute и Compensate. Запиши отметку отдельно, и сбой между ней и эффектом оставит журнал и реальность в разных состояниях: откат либо пропустит шаг, либо попытается откатить не сделанное. Это тот же класс ошибки, что в inbox.

Это работает, только пока эффект шага пишется в ту же базу, что и журнал (модули одного монолита). Для шага во внешнем сервисе со своей базой одной транзакции не бывает: перед вызовом записываем «шаг начат» с ключом идемпотентности (sagaID + имя шага), передаём этот ключ внешнему API, а после ответа отмечаем «done». При восстановлении шаг в состоянии «начат» повторяем с тем же ключом или компенсируем - внешний сервис по ключу распознает повтор и не спишет деньги второй раз.

Choreography Saga: сервисы реагируют на события

В хореографической саге нет центрального координатора. Каждый сервис слушает события и реагирует на них, публикуя новые события:

Choreography saga: три сервиса обмениваются событиями; happy path - OrderCreated и PaymentCharged идут вперёд, failure path - AccessFailed и PaymentRefunded возвращаются обратно как компенсации

Каждый сервис знает только о своих событиях и о том, на какие чужие события реагировать. Нет единой точки, которая видит весь процесс.

Orchestration vs Choreography

КритерийOrchestrationChoreography
Видимость процессаВесь flow в одном местеРазбросан по сервисам
СвязанностьОркестратор знает обо всехСервисы знают только о соседних событиях
ОтладкаПроще: смотришь оркестраторСложнее: восстанавливаешь по логам
МасштабированиеОркестратор может стать bottleneckЛучше масштабируется
ОтказоустойчивостьОркестратор - единая точка отказа: пока он лежит, ни шаги, ни компенсации не идут. Смягчают состоянием в БД и несколькими экземплярамиНет центра, но сбой одного сервиса тоже стопорит свою часть цепочки
Новый шагДобавляется в одном месте - в оркестратореКажется дешёвым (подписал сервис на событие), но обычно приходится менять публикацию и компенсации у соседей
Когда использовать3-7 шагов, сложная логика2-3 шага, простые реакции

Для большинства проектов начинайте с оркестрации. Переходите к хореографии, когда оркестратор становится bottleneck или когда сервисы принадлежат разным командам.

Persistence: сохранение состояния саги

Если оркестратор упадёт между шагами, нужно знать, на каком шаге остановились. Для этого состояние саги сохраняется в БД.

Оркестратор выше уже хранит состояние в saga_steps (по строке на шаг). Таблица saga_states ниже - уровень саги целиком: тип, статус, входной payload (из него после рестарта восстанавливается req для компенсаций) и время. Вместе они позволяют при старте найти незавершённые саги и продолжить их или откатить:

// SagaState хранит текущее состояние саги в БД.
type SagaState struct {
    ID            string    `json:"id"`
    Type          string    `json:"type"`            // "create_order"
    CurrentStep   int       `json:"current_step"`    // индекс текущего шага
    Status        string    `json:"status"`          // running, completed, compensating, failed
    Payload       []byte    `json:"payload"`         // входные данные саги
    CompletedSteps []string `json:"completed_steps"` // имена выполненных шагов
    CreatedAt     time.Time `json:"created_at"`
    UpdatedAt     time.Time `json:"updated_at"`
}

// SaveState сохраняет состояние саги после каждого шага.
func (r *SagaRepo) SaveState(ctx context.Context, state SagaState) error {
    _, err := r.db.ExecContext(ctx,
        `INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
         ON CONFLICT (id) DO UPDATE SET
            current_step = EXCLUDED.current_step,
            status = EXCLUDED.status,
            completed_steps = EXCLUDED.completed_steps,
            updated_at = EXCLUDED.updated_at`,
        state.ID, state.Type, state.CurrentStep, state.Status,
        state.Payload, pq.Array(state.CompletedSteps),
        state.CreatedAt, time.Now(),
    )
    return err
}
<?php
// src/Infrastructure/Saga/SagaState.php
declare(strict_types=1);

namespace App\Infrastructure\Saga;

// Snapshot состояния саги. Immutable - вместо мутации создаём новую версию.
final readonly class SagaState
{
    /** @param list<string> $completedSteps */
    public function __construct(
        public string $id,
        public string $type,            // 'create_order'
        public int $currentStep,        // индекс текущего шага
        public string $status,          // running, completed, compensating, failed
        public string $payload,         // JSON-строка - входные данные саги
        public array $completedSteps,
        public DateTimeImmutable $createdAt,
        public DateTimeImmutable $updatedAt,
    ) {}
}

// src/Infrastructure/Saga/SagaRepository.php
namespace App\Infrastructure\Saga;

use Doctrine\DBAL\Connection;
use DateTimeImmutable;

final class SagaRepository
{
    public function __construct(
        private readonly Connection $connection,
    ) {}

    public function saveState(SagaState $state): void
    {
        // jsonb[]/text[] для completedSteps в Postgres - удобно для запросов.
        $this->connection->executeStatement(
            'INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
             VALUES (:id, :type, :step, :status, :payload, :completed, :created, :updated)
             ON CONFLICT (id) DO UPDATE SET
                current_step = EXCLUDED.current_step,
                status = EXCLUDED.status,
                completed_steps = EXCLUDED.completed_steps,
                updated_at = EXCLUDED.updated_at',
            [
                'id' => $state->id,
                'type' => $state->type,
                'step' => $state->currentStep,
                'status' => $state->status,
                'payload' => $state->payload,
                'completed' => '{' . implode(',', $state->completedSteps) . '}',
                'created' => $state->createdAt->format('Y-m-d H:i:s'),
                'updated' => $state->updatedAt->format('Y-m-d H:i:s'),
            ],
        );
    }
}
# infrastructure/saga/saga_repo.py
from dataclasses import dataclass, field
from datetime import datetime, timezone

from psycopg import Connection


@dataclass(slots=True)
class SagaState:
    """Хранит текущее состояние саги в БД."""

    saga_id: str
    saga_type: str                  # "create_order"; в БД - колонка type
    current_step: int               # индекс текущего шага
    status: str                     # running, completed, compensating, failed
    payload: bytes                  # входные данные саги (JSON)
    completed_steps: list[str] = field(default_factory=list)  # имена выполненных шагов
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))


class SagaRepo:
    def __init__(self, conn: Connection) -> None:
        self._conn = conn

    def save_state(self, state: SagaState) -> None:
        """Сохраняет состояние саги после каждого шага."""
        # list[str] psycopg сам передаёт как text[] - аналог pq.Array в Go.
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                """INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
                   VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
                   ON CONFLICT (id) DO UPDATE SET
                      current_step = EXCLUDED.current_step,
                      status = EXCLUDED.status,
                      completed_steps = EXCLUDED.completed_steps,
                      updated_at = EXCLUDED.updated_at""",
                (
                    state.saga_id, state.saga_type, state.current_step, state.status,
                    state.payload, state.completed_steps,
                    state.created_at, datetime.now(timezone.utc),
                ),
            )

При старте приложения - находим саги в статусе running или compensating и возобновляем их с нужного шага.

Timeout: что если шаг не отвечает

В распределённой системе шаг может зависнуть. Каждый шаг должен иметь таймаут:

// executeWithTimeout выполняет шаг с таймаутом.
func executeWithTimeout(ctx context.Context, tx *sql.Tx, step Step, timeout time.Duration) error {
    ctx, cancel := context.WithTimeout(ctx, timeout)
    defer cancel()

    done := make(chan error, 1)
    go func() {
        done <- step.Execute(ctx, tx)
    }()

    select {
    case err := <-done:
        return err
    case <-ctx.Done():
        return fmt.Errorf("step %q timed out after %v", step.Name, timeout)
    }
}
<?php
// src/Application/Saga/TimeoutExecutor.php
declare(strict_types=1);

namespace App\Application\Saga;

use Doctrine\DBAL\Connection;
use Throwable;

// В PHP нет goroutines, и таймаут принудительно из основного потока выставить
// нельзя. Реальный таймаут прокидывается внутрь HTTP/DB-клиента шага.
// На уровне саги - проверка длительности через Stopwatch + бросок исключения.
final class TimeoutExecutor
{
    public function __construct(
        private readonly int $timeoutSeconds,
    ) {}

    public function execute(SagaStep $step, Connection $tx): void
    {
        $startedAt = hrtime(true);

        try {
            ($step->execute)($tx);
        } catch (Throwable $e) {
            // Прокидываем как есть - external client уже бросает на своём deadline
            throw $e;
        }

        $elapsedSeconds = (hrtime(true) - $startedAt) / 1_000_000_000;
        if ($elapsedSeconds > $this->timeoutSeconds) {
            // Шаг завершился, но за пределами SLA - бросаем для откатов выше.
            // Реальная отмена должна быть прокинута в каждый внешний вызов:
            // - Symfony HttpClient: ['timeout' => 30]
            // - Doctrine: statement_timeout в Postgres
            // - Symfony Lock: ttl
            throw new SagaStepTimedOutException(sprintf(
                'step %s exceeded SLA: %.2fs > %ds',
                $step->name,
                $elapsedSeconds,
                $this->timeoutSeconds,
            ));
        }
    }
}
# application/saga/timeout.py
from concurrent.futures import ThreadPoolExecutor
from concurrent.futures import TimeoutError as FutureTimeoutError

from psycopg import Cursor


class StepTimedOutError(Exception):
    pass


# execute_with_timeout выполняет шаг с таймаутом.
#
# Аналог goroutine + select: шаг - блокирующий I/O, поэтому threading
# (ThreadPoolExecutor), а не asyncio; в асинхронном коде это asyncio.wait_for.
# Как и в Go, поток с шагом не убивается по таймауту - реальную отмену нужно
# пробросить внутрь шага: timeout у HTTP-клиента, statement_timeout у Postgres.
def execute_with_timeout(step: Step, cur: Cursor, timeout: float) -> None:
    # Не через with: контекстный менеджер пула дождался бы зависший поток
    # и таймаут потерял бы смысл. shutdown(wait=False) отпускает его в фон.
    pool = ThreadPoolExecutor(max_workers=1)
    try:
        future = pool.submit(step.execute, cur)
        try:
            future.result(timeout=timeout)  # исключение шага пробросится как есть
        except FutureTimeoutError:
            raise StepTimedOutError(f"step {step.name!r} timed out after {timeout}s") from None
    finally:
        pool.shutdown(wait=False)

Таймаут по умолчанию - 30 секунд на шаг. Для внешних платёжных систем может быть больше. Главное - не ждать бесконечно: застрявшая сага блокирует ресурсы.

⚠️ Саги не гарантируют изоляцию - используй идемпотентность в каждом шаге

Между шагами саги другие процессы могут читать промежуточное состояние (заказ создан, но не оплачен). Это нормально - saga обеспечивает eventual consistency, а не ACID. Каждый шаг и каждая компенсация должны быть идемпотентными, потому что при восстановлении после сбоя они могут быть вызваны повторно.

Компенсации: правила проектирования

Компенсация - это не просто DELETE или undo. Несколько правил:

  1. Компенсация должна быть идемпотентной. Она может быть вызвана несколько раз: оркестратор перезапустился, retry сработал дважды - и refund не должен вернуть деньги два раза. Механика та же, что у подписчиков: дедупликация по идентификатору операции, UPSERT вместо инкремента - см. идемпотентность.
  2. Сбой компенсации не должен останавливать откат остальных шагов. Если компенсация упала - помечаем шаг compensation_failed, продолжаем откатывать остальные, а в конце возвращаем ошибку со списком застрявших шагов и поднимаем алерт оператору.
  3. Компенсация - это семантический откат. Не обязательно удалять данные. Можно пометить заказ как cancelled, вместо удаления строки.
  4. Не все шаги требуют компенсации. Если шаг только читает данные (валидация) - компенсировать нечего.

Как это проверено

examples/reliability/saga (go test ./...) проверяет утверждения этого урока прогоном:

  • сбой на каждом шаге - по очереди падает первый, второй, третий. После любого сбоя журнал эффектов должен свернуться в ноль: сага либо прошла целиком, либо откатилась целиком;
  • сбой на каждой операции базы, включая COMMIT и запись в журнал шагов. Инвариант: число непогашенных эффектов равно числу шагов в состоянии done. Расхождение означает, что откат пропустит шаг или попробует откатить не сделанное;
  • идемпотентность компенсации - три вызова Compensate подряд дают один откат на шаг, а не три;
  • откат после «перезапуска» - оркестратор создаётся заново, без списка выполненных шагов, и находит их в базе;
  • сбой компенсации виден вызывающему - ошибка содержит имя застрявшего шага, а сам шаг помечен в журнале.

Рядом лежит BrokenOrchestrator - версия из первой редакции урока. Тесты на ней фиксируют оба дефекта: сбой отката не виден снаружи, а после перезапуска откатывать нечего. Без сломанной версии тесты выше ничего не доказывали бы - проверка имеет смысл, только если известно, что она способна упасть.

Типичные ошибки

  • Saga вместо распределённой транзакции «на всякий» - для простого случая (БД + Redis) часто хватает Outbox + idempotency без оркестратора. Saga нужна когда 3+ шага, каждый с побочным эффектом во внешней системе.
  • Компенсация = DELETE строк - другие подписчики уже прочитали данные, ссылаются на них. Лучше - пометка status: cancelled, событие OrderCancelled. Логический откат, не физический.
  • Состояние саги только в памяти - процесс перезапустился на середине, нет ни данных «где мы», ни компенсаций. Сохраняй состояние саги в БД после каждого шага + при старте находи незавершённые и продолжай.
  • Компенсации падают тихо - compensate() поймала ошибку, залогировала и пошла дальше; средний шаг застрял в «оплачено, но не выдано». Каждый сбой компенсации = алёрт оператора, не просто запись в лог; какие сигналы и пороги для этого заводить - в уроке про наблюдаемость.
  • Choreography с цепочкой длиннее 3 событий - OrderCreated → InventoryReserved → PaymentProcessed → AccessGranted → ... Без центрального state почти невозможно понять, на каком шаге saga застряла. Длинные потоки лучше делать Orchestration.
  • Шаг не идемпотентный - Saga при retry повторяет шаг, который начисляет деньги - двойное списание. Каждый шаг (как и компенсация) обязан быть идемпотентным.
  • Timeout не пробрасывается во внешний вызов - select { case <-ctx.Done() } сработал, но HTTP-запрос в платёжку всё равно сидит в сокете. Compensation вызвана, но платёж мог пройти. Передавай ctx в HTTP-клиент, чтобы запрос реально отменился.
  • Saga + долгий шаг ожидания (SleepUntil несколько дней) - оркестратор держит горутину/коннект к БД сутками. Используй durable scheduler (Temporal/Cadence) или persisted Saga с wake-up через cron.

Мини-задание

  • Реализуй SagaOrchestrator с методами Run и compensate по примеру из урока
  • Опиши процесс из 3 шагов (создание заказа, оплата, выдача доступа) и компенсацию к каждому шагу
  • Добавь таймаут 10 секунд на каждый шаг с помощью context.WithTimeout
  • Напиши unit-тест: при сбое на шаге 3 компенсации шагов 2 и 1 должны быть вызваны в обратном порядке
  • Добавь сохранение состояния саги в таблицу saga_states после каждого шага

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.