Transaction.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/Module.h"
#include "common/Result.h"
#include "common/Snapshot.h"
 
#include <cstddef>
#include <cstdint>
#include <deque>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
namespace eve::transaction {
 
class TransactionContext {
public:
    TransactionContext(std::string transactionId, std::string correlationId = {}, std::string causationId = {})
        : transactionId_(std::move(transactionId)),
          correlationId_(std::move(correlationId)),
          causationId_(std::move(causationId)) {}
 
    explicit TransactionContext(eve::TransactionId transactionId, std::string correlationId = {},
                                std::string causationId = {})
        : identity_(transactionId),
          transactionId_(transactionId.isNil() ? std::string{} : transactionId.format()),
          correlationId_(std::move(correlationId)),
          causationId_(std::move(causationId)) {}
 
    [[nodiscard]] const eve::TransactionId& identity() const noexcept { return identity_; }
    const std::string& transactionId() const noexcept { return transactionId_; }
    const std::string& correlationId() const noexcept { return correlationId_; }
    const std::string& causationId() const noexcept { return causationId_; }
 
private:
    eve::TransactionId identity_;
    std::string        transactionId_;
    std::string        correlationId_;
    std::string        causationId_;
};
 
enum class CoordinatorState {
    Committed,
    Compensated,
    CompensationFailed,
    RolledBack,
    RollbackFailed,
    PartiallyCommitted,
};
 
struct TransactionReceipt {
    eve::TransactionId identity;
    std::string        transactionId;
    std::string        correlationId;
    std::string        causationId;
    CoordinatorState   state            = CoordinatorState::Committed;
    std::size_t        participantCount = 0;
    std::size_t        preparedCount    = 0;
    std::size_t        committedCount   = 0;
    std::size_t        rolledBackCount  = 0;
    std::size_t        compensatedCount = 0;
};
 
class ITransactionParticipant {
public:
    virtual ~ITransactionParticipant() = default;
 
    virtual std::string_view name() const noexcept { return "transaction-participant"; }
 
    [[nodiscard]] virtual Result<void> prepare(const TransactionContext& context) = 0;
 
    [[nodiscard]] virtual Result<void> commit(const TransactionContext& context) = 0;
 
    [[nodiscard]] virtual Result<void> rollback(const TransactionContext& context) = 0;
 
    [[nodiscard]] virtual Result<void> compensate(const TransactionContext& context) = 0;
};
 
class EVENGINE_API_FOUNDATION Coordinator {
public:
    [[nodiscard]] Result<TransactionReceipt> execute(const TransactionContext&           context,
                                                     std::span<ITransactionParticipant*> participants) const;
 
    [[nodiscard]] Result<TransactionReceipt> compensate(const TransactionContext&           context,
                                                        std::span<ITransactionParticipant*> participants) const;
};
 
enum class State { Open, Validated, Committed, RolledBack, Failed };
 
struct Operation {
    std::string id;
    std::string kind;
    std::string target;
    std::string payload = "null";
    bool        valid   = false;
    bool        checked = false;
    std::string error;
    eve::OperationId identity;
};
 
struct Event {
    uint64_t    sequence = 0;
    std::string transactionId;
    std::string operationId;
    std::string type;
    std::string detail;
    eve::TransactionId transactionIdentity;
    eve::OperationId operationIdentity;
};
 
class EVENGINE_API_FOUNDATION Plan {
public:
    const std::string& id() const;
    [[nodiscard]] const eve::TransactionId& identity() const noexcept;
    State state() const;
    const std::string& correlation() const;
    const std::string& causation() const;
    [[nodiscard]] eve::Result<eve::OperationId> stage(const std::string& kind, const std::string& target,
                                                      const std::string& payloadJson = "null",
                                                      eve::OperationId   operationId = {});
    [[nodiscard]] eve::Result<void> markValid(const std::string& operationId);
    [[nodiscard]] eve::Result<void> markValid(eve::OperationId operationId);
    [[nodiscard]] eve::Result<void> markInvalid(const std::string& operationId, const std::string& error);
    [[nodiscard]] eve::Result<void> markInvalid(eve::OperationId operationId, const std::string& error);
    [[nodiscard]] eve::Result<void> validate();
    [[nodiscard]] eve::Result<void> commit();
    [[nodiscard]] eve::Result<void> rollback(const std::string& reason = {});
    [[nodiscard]] eve::Result<void> fail(const std::string& error);
    const std::string& error() const;
    int operationCount() const;
    [[nodiscard]] const Operation* operationAt(int index) const;
    [[nodiscard]] const Operation* findOperation(const std::string& operationId) const;
    [[nodiscard]] const Operation* findOperation(eve::OperationId operationId) const;
    int eventCount() const;
    [[nodiscard]] const Event* eventAt(int index) const;
    std::string snapshotJson() const;
 
private:
    friend class Ledger;
    Plan(std::string id, std::string correlation, std::string causation, eve::TransactionId identity = {},
         eve::UuidEntropySource operationEntropy = {}, eve::UuidClock operationClock = {});
    void emit(const std::string& type, const std::string& operationId = {}, const std::string& detail = {});
 
    std::string           id_;
    eve::TransactionId                  identity_;
    State                 state_ = State::Open;
    std::string           correlation_;
    std::string           causation_;
    std::string           error_;
    uint64_t              nextOperation_ = 1;
    uint64_t              nextEvent_     = 1;
    std::deque<Operation> operations_;
    std::deque<Event>     events_;
    std::optional<eve::UuidV7Generator> operationIdGenerator_;
};
 
class EVENGINE_API_FOUNDATION Ledger {
public:
    explicit Ledger(eve::PersistentId instanceId = {}, eve::UuidEntropySource transactionEntropy = {},
                    eve::UuidClock transactionClock = {});
 
    // std::vector<std::unique_ptr<Plan>> makes the implicit copy operations
    // ill-formed (C2280) as soon as a class-level dllexport instantiates them;
    // spell the four out so the export surface stays defined. Semantics unchanged:
    // the ledger was never copyable in practice.
    Ledger(const Ledger&)            = delete;
    Ledger& operator=(const Ledger&) = delete;
    Ledger(Ledger&&)                 = default;
    Ledger& operator=(Ledger&&)      = default;
    [[nodiscard]] eve::Result<Plan*> create(const std::string& correlation = {}, const std::string& causation = {},
                                            eve::TransactionId identity = {});
    [[nodiscard]] Plan* find(const std::string& transactionId);
    [[nodiscard]] Plan* find(eve::TransactionId transactionId);
    int count() const;
    [[nodiscard]] Plan* at(int index);
    std::string snapshotJson() const;
    [[nodiscard]] eve::Result<void> restore(std::string_view json);
 
    [[nodiscard]] eve::Result<eve::SnapshotEnvelope> snapshot(const eve::SnapshotHashProvider& hashProvider) const;
    [[nodiscard]] eve::Result<void> restoreSnapshot(const eve::SnapshotEnvelope&     snapshot,
                                                    const eve::SnapshotHashProvider& hashProvider);
    [[nodiscard]] eve::Result<std::string> snapshotEnvelopeJson(const eve::SnapshotHashProvider& hashProvider) const;
    [[nodiscard]] eve::Result<void> restoreSnapshotJson(std::string_view                 json,
                                                        const eve::SnapshotHashProvider& hashProvider);
 
private:
    uint64_t                           nextTransaction_ = 1;
    std::vector<std::unique_ptr<Plan>> plans_;
    eve::PersistentId                   instanceId_;
    eve::Revision                       revision_;
    eve::SimulationTick                 tick_;
    eve::UuidEntropySource              transactionEntropy_;
    eve::UuidClock                      transactionClock_;
    std::optional<eve::UuidV7Generator> transactionIdGenerator_;
};
 
EVENGINE_API_FOUNDATION std::string stateName(State state);
 
class EVENGINE_API_FOUNDATION Transaction : public Module {
public:
    Module_REG(Transaction);
    Transaction()           = default;
    ~Transaction() override = default;
 
    // std::vector<std::unique_ptr<Ledger>> makes the implicit copy operations
    // ill-formed (C2280) as soon as a class-level dllexport instantiates them;
    // spell the four out so the export surface stays defined. Semantics unchanged:
    // a module instance was never copyable in practice.
    Transaction(const Transaction&)            = delete;
    Transaction& operator=(const Transaction&) = delete;
    Transaction(Transaction&&)                 = default;
    Transaction& operator=(Transaction&&)      = default;
 
    [[nodiscard("transaction ledger ownership must be retained or explicitly handled")]] static Ledger* newLedger();
 
private:
    std::vector<std::unique_ptr<Ledger>> ledgers_;
};
 
}  // namespace eve::transaction