Settlement.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/Result.h"
#include "common/Identity.h"
#include "common/Snapshot.h"
#include "common/SubjectRef.h"
#include "common/Time.h"
#include "common/Value.h"
#include "game_event/GameEvent.h"
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
namespace eve::settlement {
 
enum class StageKind : std::uint8_t {
    Validate,
    Decision,
    SourceModifiers,
    TargetMitigation,
    ArmorShield,
    Clamp,
    Apply,
    Trigger,
    Event,
};
 
enum class SettlementDisposition : std::uint8_t {
    Applied,
    NoOp,
    Immune,
    Resisted,
    PartiallyApplied,
    Blocked,
    InvalidTarget,
};
 
enum class SettlementTraceLevel : std::uint8_t { Off, Summary, Full };
 
[[nodiscard]] EVENGINE_API_FOUNDATION const char* settlementDispositionName(SettlementDisposition disposition) noexcept;
 
struct EVENGINE_API_FOUNDATION SettlementRandomDecision {
    LogicalId     stream;
    std::uint64_t sequence  = 0;
    double        sample    = 0.0;
    double        threshold = 0.0;
    bool          accepted  = false;
};
 
struct EVENGINE_API_FOUNDATION SettlementChainContext {
    std::uint32_t           depth        = 0;
    std::uint32_t           emittedCount = 0;
    std::vector<std::string> triggerPath;
};
 
[[nodiscard]] EVENGINE_API_FOUNDATION const char* stageKindName(StageKind kind) noexcept;
 
struct EVENGINE_API_FOUNDATION SettlementRequest {
    SubjectRef source;
    SubjectRef target;
    std::string kind;
 
    std::string resource;
 
    double                    magnitude = 0.0;
    std::vector<std::string>  tags;
    std::vector<SettlementRandomDecision> decisions;
    std::string trigger;
    SettlementChainContext chain;
    SettlementTraceLevel trace = SettlementTraceLevel::Full;
    Value                     context = Value(Value::Object{});
    SimulationTick            tick    = SimulationTick::zero();
    game_event::CausationRef  causation;
    game_event::CorrelationId correlation;
};
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<void> validateSettlementRequest(const SettlementRequest& request);
 
struct EVENGINE_API_FOUNDATION SettlementStageResult {
    StageKind       kind = StageKind::Validate;
    std::string     name;
    eve::StatusCode status  = eve::StatusCode::Ok;
    double          before  = 0.0;
    double          after   = 0.0;
    Value           details = Value(Value::Object{});
};
 
struct EVENGINE_API_FOUNDATION SettlementResult {
    double                               requested = 0.0;
    double                               applied   = 0.0;
    double                               absorbed  = 0.0;
    double                               resisted  = 0.0;
    double                               clamped   = 0.0;
    bool                                 critical  = false;
    SettlementDisposition                disposition = SettlementDisposition::NoOp;
    SimulationTick                       tick      = SimulationTick::zero();
    std::vector<SettlementStageResult>   stages;
    std::optional<game_event::GameEvent> event;
    std::vector<SettlementRequest> derived;
 
    [[nodiscard]] bool hasStage(std::string_view name) const noexcept;
 
    [[nodiscard]] std::size_t ruleEvaluationCount() const noexcept;
 
    [[nodiscard]] std::size_t ruleMatchCount() const noexcept;
 
    [[nodiscard]] const SettlementStageResult* stage(std::string_view name) const noexcept;
};
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<std::string> settlementResultCanonicalJson(
    const SettlementResult& result);
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<eve::ContentId> settlementResultDigest(
    const SettlementResult& result, const eve::SnapshotHashProvider& hashProvider);
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<std::vector<std::string>> verifySettlementResult(
    const SettlementResult& expected, const SettlementResult& actual);
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<std::string> createSettlementReplayRecord(
    const SettlementRequest& request, eve::ContentId ruleDigest, const SettlementResult& result,
    const eve::SnapshotHashProvider& hashProvider);
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<SettlementRequest> settlementReplayRequest(
    std::string_view recordJson);
 
[[nodiscard]] EVENGINE_API_FOUNDATION eve::Result<std::vector<std::string>> verifySettlementReplayRecord(
    std::string_view recordJson, eve::ContentId ruleDigest, const SettlementResult& actual,
    const eve::SnapshotHashProvider& hashProvider);
 
struct EVENGINE_API_FOUNDATION SettlementBatchItemResult {
    std::size_t                     index = 0;
    SettlementRequest               request;
    eve::Status                     status;
    std::optional<SettlementResult> result;
};
 
class EVENGINE_API_FOUNDATION PreparedApply {
public:
    using CommitFunction   = std::function<eve::Result<void>()>;
    using RollbackFunction = std::function<void()>;
 
    PreparedApply() = default;
 
    PreparedApply(CommitFunction commit, RollbackFunction rollback);
 
    PreparedApply(const PreparedApply&)            = delete;
    PreparedApply& operator=(const PreparedApply&) = delete;
    PreparedApply(PreparedApply&& other) noexcept;
    PreparedApply& operator=(PreparedApply&& other) noexcept;
    ~PreparedApply();
 
    [[nodiscard]] bool isValid() const noexcept;
 
    [[nodiscard]] eve::Result<void> commit();
 
    void rollback() noexcept;
 
    [[nodiscard]] bool isCommitted() const noexcept { return committed_; }
 
private:
    CommitFunction   commit_;
    RollbackFunction rollback_;
    bool             committed_  = false;
    bool             rolledBack_ = false;
};
 
class ISettlementPolicy;
 
class EVENGINE_API_FOUNDATION SettlementContext {
public:
    [[nodiscard]] const SettlementRequest& request() const noexcept { return request_; }
 
    [[nodiscard]] ISettlementPolicy& policy() const noexcept { return policy_; }
 
    [[nodiscard]] double magnitude() const noexcept { return magnitude_; }
 
    [[nodiscard]] double absorbed() const noexcept { return absorbed_; }
 
    [[nodiscard]] double resisted() const noexcept { return resisted_; }
 
    [[nodiscard]] double clamped() const noexcept { return clamped_; }
 
    [[nodiscard]] eve::Result<void> setMagnitude(double value);
 
    [[nodiscard]] eve::Result<void> addAbsorbed(double value);
 
    [[nodiscard]] eve::Result<void> addResisted(double value);
 
    [[nodiscard]] eve::Result<void> addClamped(double value);
 
    void setCritical(bool value) noexcept {
        if (applyPrepared_) {
            recordMutationViolation("settlement critical flag cannot change after apply preparation", "critical");
            return;
        }
        critical_ = value;
    }
 
    [[nodiscard]] bool critical() const noexcept { return critical_; }
 
    [[nodiscard]] eve::Result<void> setDisposition(SettlementDisposition disposition);
 
    [[nodiscard]] SettlementDisposition disposition() const noexcept { return disposition_; }
 
    [[nodiscard]] eve::Result<void> setClampMax(std::optional<double> value);
 
    void setStageDetail(std::string key, Value value);
 
    [[nodiscard]] const eve::Diagnostic* mutationViolation() const noexcept {
        return mutationViolation_ ? &*mutationViolation_ : nullptr;
    }
 
    [[nodiscard]] const Value::Object& stageDetails() const noexcept { return stageDetails_; }
 
    [[nodiscard]] const SettlementResult& projectedResult() const noexcept { return result_; }
 
    [[nodiscard]] eve::Result<void> applyClamp();
 
    [[nodiscard]] eve::Result<void> prepareApply();
 
    [[nodiscard]] eve::Result<void> prepareEvent();
 
    [[nodiscard]] PreparedApply* pendingApply() noexcept { return pendingApply_ ? &*pendingApply_ : nullptr; }
 
    [[nodiscard]] const game_event::GameEvent* pendingEvent() const noexcept {
        return pendingEvent_ ? &*pendingEvent_ : nullptr;
    }
 
    void synchronizeResult() noexcept;
 
    [[nodiscard]] eve::Result<void> emitDerived(SettlementRequest request);
 
private:
    friend class SettlementPipeline;
 
    SettlementContext(const SettlementRequest& request, SettlementResult& result, ISettlementPolicy& policy);
    void beginStage() noexcept {
        stageDetails_.clear();
        mutationViolation_.reset();
    }
    void clearPendingApply() noexcept { pendingApply_.reset(); }
    void clearPendingEvent() noexcept { pendingEvent_.reset(); }
    void recordMutationViolation(std::string message, std::string path) noexcept;
 
    const SettlementRequest&             request_;
    SettlementResult&                    result_;
    ISettlementPolicy&                   policy_;
    double                               magnitude_ = 0.0;
    double                               absorbed_  = 0.0;
    double                               resisted_  = 0.0;
    double                               clamped_   = 0.0;
    bool                                 critical_  = false;
    SettlementDisposition                disposition_ = SettlementDisposition::NoOp;
    bool                                 dispositionExplicit_ = false;
    std::optional<double>                clampMax_;
    Value::Object                        stageDetails_;
    std::optional<PreparedApply>         pendingApply_;
    std::optional<game_event::GameEvent> pendingEvent_;
    std::optional<eve::Diagnostic>       mutationViolation_;
    bool                                 applyPrepared_ = false;
    bool                                 eventPrepared_ = false;
};
 
class EVENGINE_API_FOUNDATION ISettlementPolicy {
public:
    virtual ~ISettlementPolicy() = default;
 
    [[nodiscard]] virtual eve::Result<void> validate(SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<void> decide(SettlementContext& context);
 
    [[nodiscard]] virtual eve::Result<void> sourceModifiers(SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<void> targetMitigation(SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<void> armorShield(SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<void> clamp(SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<PreparedApply> prepareApply(const SettlementContext& context) = 0;
 
    [[nodiscard]] virtual eve::Result<std::vector<SettlementRequest>> prepareTrigger(
        const SettlementContext& context, const SettlementResult& result);
};
 
class EVENGINE_API_FOUNDATION SettlementPipeline {
public:
    using StageFunction = std::function<eve::Result<void>(SettlementContext&)>;
    using RequestExecutor = std::function<eve::Result<SettlementResult>(const SettlementRequest&)>;
 
    SettlementPipeline();
 
    [[nodiscard]] eve::Result<void> addStage(StageKind kind, std::string name, int priority, StageFunction function);
 
    [[nodiscard]] eve::Result<SettlementResult> settle(const SettlementRequest& request, ISettlementPolicy& policy,
                                                       game_event::GameEventLog* events = nullptr) const;
 
    [[nodiscard]] eve::Result<std::vector<SettlementResult>> settleAtomic(
        std::span<const SettlementRequest> requests, std::span<ISettlementPolicy*> policies,
        game_event::GameEventLog* events = nullptr) const;
 
    [[nodiscard]] eve::Result<std::vector<SettlementBatchItemResult>> settleIndependent(
        std::span<const SettlementRequest> requests, std::span<ISettlementPolicy*> policies,
        game_event::GameEventLog* events = nullptr) const;
 
    [[nodiscard]] eve::Result<std::vector<SettlementBatchItemResult>> settleChain(
        const SettlementRequest& root, const RequestExecutor& execute, std::uint32_t maxDepth,
        std::uint32_t maxSettlements) const;
 
private:
    struct StageEntry {
        StageKind     kind = StageKind::Validate;
        std::string   name;
        int           priority     = 0;
        std::uint64_t registration = 0;
        bool          canonical    = false;
        bool          terminal     = false;
        StageFunction function;
    };
 
    std::vector<StageEntry> stages_;
    std::uint64_t           nextRegistration_ = 1;
 
    [[nodiscard]] eve::Result<void> prepare(SettlementContext& context, SettlementResult& result) const;
};
 
}  // namespace eve::settlement