GameEvent.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/EventSequence.h"
#include "common/Identity.h"
#include "common/Module.h"
#include "common/Result.h"
#include "common/Revision.h"
#include "common/SchemaVersion.h"
#include "common/Snapshot.h"
#include "common/Time.h"
 
#include <cstdint>
#include <deque>
#include <functional>
#include <memory>
#include <optional>
#include <ostream>
#include <string>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
 
namespace eve::game_event {
 
using EventSequence  = eve::EventSequence;
using SimulationTick = eve::SimulationTick;
using SchemaId       = eve::LogicalId;
using SchemaVersion  = eve::SchemaVersion;
 
using EventId   = eve::EventId;
using CommandId = eve::CommandId;
 
class CorrelationId {
public:
    enum class Kind : uint8_t { None, Id, Legacy };
 
    CorrelationId() = default;
 
    [[nodiscard]] static CorrelationId fromEventId(EventId value) {
        CorrelationId result;
        result.kind_ = value.isNil() ? Kind::None : Kind::Id;
        result.id_   = value;
        return result;
    }
 
    [[nodiscard]] static CorrelationId fromLegacy(std::string value) {
        CorrelationId result;
        result.kind_   = value.empty() ? Kind::None : Kind::Legacy;
        result.legacy_ = std::move(value);
        return result;
    }
 
    [[nodiscard]] Kind kind() const noexcept { return kind_; }
 
    [[nodiscard]] bool isCanonical() const noexcept { return kind_ != Kind::Legacy; }
 
    [[nodiscard]] std::string format() const { return kind_ == Kind::Id ? id_.format() : legacy_; }
 
    friend bool operator==(const CorrelationId&, const CorrelationId&) noexcept = default;
 
private:
    Kind        kind_ = Kind::None;
    EventId     id_;
    std::string legacy_;
};
 
class CausationRef {
public:
    enum class Kind : uint8_t { None, Event, Command, Legacy };
 
    CausationRef() = default;
 
    [[nodiscard]] static CausationRef fromEventId(EventId value) {
        CausationRef result;
        if (!value.isNil()) {
            result.kind_  = Kind::Event;
            result.value_ = std::move(value);
        }
        return result;
    }
 
    [[nodiscard]] static CausationRef fromCommandId(CommandId value) {
        CausationRef result;
        if (!value.isNil()) {
            result.kind_  = Kind::Command;
            result.value_ = std::move(value);
        }
        return result;
    }
 
    [[nodiscard]] static CausationRef fromLegacy(std::string value) {
        CausationRef result;
        result.kind_  = value.empty() ? Kind::None : Kind::Legacy;
        result.value_ = std::move(value);
        return result;
    }
 
    [[nodiscard]] Kind kind() const noexcept { return kind_; }
 
    [[nodiscard]] bool isCanonical() const noexcept { return kind_ != Kind::Legacy; }
 
    [[nodiscard]] std::string format() const {
        if (kind_ == Kind::Event) return std::get<EventId>(value_).format();
        if (kind_ == Kind::Command) return std::get<CommandId>(value_).format();
        if (kind_ == Kind::Legacy) return std::get<std::string>(value_);
        return {};
    }
 
    friend bool operator==(const CausationRef&, const CausationRef&) noexcept = default;
 
private:
    Kind                                                          kind_ = Kind::None;
    std::variant<std::monostate, EventId, CommandId, std::string> value_;
};
 
inline std::ostream& operator<<(std::ostream& stream, CorrelationId::Kind kind) {
    switch (kind) {
        case CorrelationId::Kind::None: return stream << "none";
        case CorrelationId::Kind::Id: return stream << "id";
        case CorrelationId::Kind::Legacy: return stream << "legacy";
    }
    return stream << "unknown";
}
 
inline std::ostream& operator<<(std::ostream& stream, CausationRef::Kind kind) {
    switch (kind) {
        case CausationRef::Kind::None: return stream << "none";
        case CausationRef::Kind::Event: return stream << "event";
        case CausationRef::Kind::Command: return stream << "command";
        case CausationRef::Kind::Legacy: return stream << "legacy";
    }
    return stream << "unknown";
}
 
struct GameEvent {
    EventId eventId = EventId::nil();
    EventSequence sequence = EventSequence::zero();
    std::string type;
    std::string source;
    std::string subject;
    CausationRef causation;
    CorrelationId correlation;
    SchemaId schemaId;
    SchemaVersion schemaVersion = SchemaVersion::zero();
    SimulationTick tick = SimulationTick::zero();
    uint32_t flags = 0;
    std::string payload = "null";
};
 
template <class Payload>
struct TypedEventEnvelope {
    GameEvent metadata;
    Payload   payload;
};
 
class GameEventLog;
 
class EVENGINE_API_FOUNDATION EventConsumer {
public:
    int read(int maxCount);
    int batchCount() const;
    const GameEvent* batchAt(int index) const;
    [[nodiscard]] EventSequence position() const;
    void seek(EventSequence sequence);
    void seek(uint64_t sequence);
 
private:
    friend class GameEventLog;
    EventConsumer(GameEventLog* stream, EventSequence sequence);
 
    GameEventLog*                 stream_       = nullptr;
    EventSequence                 nextSequence_ = EventSequence(1);
    std::vector<const GameEvent*> batch_;
};
 
class EVENGINE_API_FOUNDATION GameEventLog {
public:
    // The stream owns move-only members (std::vector<std::unique_ptr<EventConsumer>>),
    // so it is not copyable; dllexport must not instantiate the implicitly declared
    // copy operations, whose bodies cannot compile. Deleting the copies is a no-op and
    // the defaulted moves keep the previous implicit behaviour.
    GameEventLog(const GameEventLog&)            = delete;
    GameEventLog& operator=(const GameEventLog&) = delete;
    GameEventLog(GameEventLog&&)                 = default;
    GameEventLog& operator=(GameEventLog&&)      = default;
 
    GameEventLog() = default;
 
    explicit GameEventLog(eve::PersistentId instanceId) : instanceId_(instanceId) {}
 
    explicit GameEventLog(eve::UuidEntropySource entropy, eve::UuidClock clock = {});
 
    [[nodiscard]] eve::Result<EventSequence> append(GameEvent envelope);
 
    template <class Payload>
    [[nodiscard]] eve::Result<EventSequence> appendTyped(
        GameEvent envelope, const Payload& payload,
        const std::function<eve::Result<std::string>(const Payload&)>& encode) {
        if (!encode) {
            return eve::Result<EventSequence>::failure(eve::Diagnostic::error(
                eve::DiagnosticCode::InvalidArgument, "event payload encoder must not be empty"));
        }
        auto encoded = encode(payload);
        if (!encoded) return eve::Result<EventSequence>::failure(encoded.status());
        envelope.payload = std::move(encoded).takeValue();
        return append(std::move(envelope));
    }
 
    [[nodiscard]] const GameEvent* find(EventSequence sequence) const;
    [[nodiscard]] const GameEvent* find(uint64_t sequence) const;
    int queryType(const std::string& type);
    int querySource(const std::string& source);
    int querySubject(const std::string& subject);
    int querySequence(EventSequence firstSequence);
    int querySequence(uint64_t firstSequence);
    const GameEvent* queryAt(int index) const;
    int size() const;
    const GameEvent* at(int index) const;
    [[nodiscard]] EventConsumer* newConsumer(EventSequence firstSequence = EventSequence(1));
    [[nodiscard]] EventConsumer* newConsumer(uint64_t firstSequence);
    void clearBefore(EventSequence firstSequence);
    void clearBefore(uint64_t firstSequence);
    void clear();
    void reset();
    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:
    friend class EventConsumer;
    [[nodiscard]] EventSequence oldestSequence() const;
 
    std::optional<eve::UuidV7Generator>         eventIdGenerator_;
    eve::PersistentId                           instanceId_;
    eve::Revision                               revision_     = eve::Revision::zero();
    eve::SimulationTick                         snapshotTick_ = eve::SimulationTick::zero();
    EventSequence                               nextSequence_ = EventSequence(1);
    std::deque<GameEvent>                       events_;
    std::vector<const GameEvent*>               query_;
    std::vector<std::unique_ptr<EventConsumer>> consumers_;
};
 
class GameEventModule : public Module {
public:
    Module_REG(GameEventModule);
    GameEventModule()           = default;
    ~GameEventModule() override = default;
 
    [[nodiscard("event stream ownership must be retained or explicitly handled")]] static GameEventLog* newLog();
 
private:
    std::vector<std::unique_ptr<GameEventLog>> streams_;
};
 
}  // namespace eve::game_event