10. 序列化、Bundle 与网络消息

// 文件：kbe/src/lib/common/memorystream.h（简化）
class MemoryStream : public PoolObject
{
public:
    const static size_t DEFAULT_SIZE = 0x100;
    const static size_t MAX_SIZE = 10000000;

    MemoryStream(): rpos_(0), wpos_(0)
    {
        data_.reserve(DEFAULT_SIZE);   // 默认 256 字节
    }

    // 写入：operator<< 重载
    MemoryStream &operator<<(uint8 value);
    MemoryStream &operator<<(uint16 value);
    MemoryStream &operator<<(uint32 value);
    MemoryStream &operator<<(uint64 value);
    MemoryStream &operator<<(float value);
    MemoryStream &operator<<(const std::string &value);  // null-terminated

    // 读取：operator>> 重载
    MemoryStream &operator>>(uint8 &value);
    MemoryStream &operator>>(uint16 &value);
    // ...

    // 底层操作
    template <typename T> void append(T value)
    {
        EndianConvert(value);       // 字节序转换
        append((uint8 *)&value, sizeof(value));
    }

protected:
    std::vector<uint8> data_;   // 缓冲区
    size_t rpos_;               // 读游标
    size_t wpos_;               // 写游标
};

// 文件：kbe/src/lib/common/memorystream.h（简化）

// PackXZ：float x,z → 3 字节（从 8 字节压缩到 3 字节，省 62.5%）
void appendPackXZ(float x, float z)
{
    PackFloatXType xPackData;
    xPackData.fv = x;
    PackFloatXType zPackData;
    zPackData.fv = z;
    // ... 提取尾数位，打包到 3 字节 ...
    uint8 packs[3];
    packs[0] = (uint8)(data >> 16);
    packs[1] = (uint8)(data >> 8);
    packs[2] = (uint8)data;
    (*this).append(packs, 3);
}

// PackY：float y → 2 字节（从 4 字节压缩到 2 字节，省 50%）
void appendPackY(float y);

// PackXYZ：3 个 float → 4 字节（从 12 字节压缩到 4 字节，省 66.7%）
void appendPackXYZ(float x, float y, float z, float minf = -256.f)
{
    x -= minf;
    y -= minf / 2.f;
    z -= minf;
    uint32 packed = 0;
    packed |= ((int)(x / 0.25f) & 0x7FF);          // X: 11 位
    packed |= ((int)(z / 0.25f) & 0x7FF) << 11;     // Z: 11 位
    packed |= ((int)(y / 0.25f) & 0x3FF) << 22;     // Y: 10 位
    *this << packed;
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/cstdmf/binary_stream.hpp（简化）
class BinaryOStream
{
public:
    virtual ~BinaryOStream() {};
    virtual void* reserve(int nBytes) = 0;  // 纯虚：预留空间
    virtual int size() const { return -1; }
    virtual void addBlob(const void* pBlob, int size);

    template <class TYPE>
    void insertRaw(const TYPE& t);           // 模板写入

    void writePackedInt(int len);            // 变长整数编码
    void writeStringLength(int len) { this->writePackedInt(len); }
};

class BinaryIStream
{
public:
    virtual const void* retrieve(int nBytes) = 0;  // 纯虚：取出数据
    virtual int remainingLength() const = 0;
    virtual char peek() = 0;

    int readPackedInt();
    int readStringLength() { return this->readPackedInt(); }
    bool error() const;
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/cstdmf/memory_stream.hpp（简化）
class MemoryOStream : public BinaryOStream, public BinaryIStream,
    public SafeAllocatable
{
public:
    MemoryOStream(int size = 64);

    // BinaryOStream overrides
    virtual void* reserve(int nBytes);
    virtual int size() const;

    // BinaryIStream overrides
    virtual const void* retrieve(int nBytes);
    virtual int remainingLength() const;

protected:
    char* pBegin_;    // 缓冲区起始
    char* pCurr_;     // 当前写入位置
    char* pEnd_;      // 缓冲区末尾
    char* pRead_;     // 当前读取位置
};

// 文件：kbe/src/lib/network/bundle.h（简化）
class Bundle : public PoolObject
{
public:
    typedef std::vector<Packet*> Packets;

    Bundle(Channel* pChannel = NULL, ProtocolType pt = PROTOCOL_TCP);

    // 消息边界管理
    void newMessage(const MessageHandler& msgHandler);  // 开始新消息
    void finiMessage(bool isSend = true);               // 结束当前消息

    // 数据写入（自动分包）
    Bundle& operator<<(uint8 value)
    {
        onPacketAppend(sizeof(uint8));     // 检查是否需要新 Packet
        (*pCurrPacket_) << value;          // 写入当前 Packet
        return *this;
    }
    // ... 所有基本类型的 operator<< 重载

    Packet* newPacket();
    int32 packetsLength(bool calccurr = true);

protected:
    int32 onPacketAppend(int32 addsize, bool inseparable = true);

    Packets packets_;               // 已完成的 Packet 列表
    Packet* pCurrPacket_;           // 正在写入的 Packet
    Channel* pChannel_;             // 关联的 Channel
    const MessageHandler* pCurrMsgHandler_;

    MessageID currMsgID_;           // 当前消息 ID
    MessageLength1 currMsgLength_;  // 当前消息长度
    size_t currMsgLengthPos_;       // 长度字段在流中的位置（变长消息用）
    int32 numMessages_;             // Bundle 内消息数
    int32 packetMaxSize_;           // 单 Packet 最大大小
};

// 文件：kbe/src/lib/network/bundle.cpp:273（简化）
void Bundle::newMessage(const MessageHandler& msgHandler)
{
    pCurrMsgHandler_ = &msgHandler;

    // 如果没有当前 Packet，尝试复用上一个 Packet 的剩余空间
    if (pCurrPacket_ == NULL)
    {
        if (packets_.size() > 0 && packetHaveSpace())
        {
            pCurrPacket_ = packets_.back();    // 复用
            packets_.pop_back();
        }
        else
        {
            this->newPacket();                  // 新建
        }
    }

    finiMessage(false);  // 结束上一条消息（如果有的话）

    // 写入消息 ID
    (*this) << msgHandler.msgID;
    pCurrPacket_->messageID(msgHandler.msgID);

    // 变长消息：预留长度字段
    if (msgHandler.msgLen == NETWORK_VARIABLE_MESSAGE)
    {
        MessageLength msglen = 0;
        currMsgLengthPos_ = pCurrPacket_->wpos();  // 记住位置，finiMessage 时回填
        (*this) << msglen;
    }

    ++numMessages_;
    currMsgID_ = msgHandler.msgID;
}

// 文件：kbe/src/lib/network/bundle.cpp:177（简化）
int32 Bundle::onPacketAppend(int32 addsize, bool inseparable)
{
    if (pCurrPacket_ == NULL)
        newPacket();

    int32 totalsize = (int32)pCurrPacket_->length();
    int32 fwpos = (int32)pCurrPacket_->wpos();

    if (inseparable)
        fwpos += addsize;        // 不可分割的数据，确保完整放入

    // 当前 Packet 放不下了
    if (fwpos >= packetMaxSize_)
    {
        packets_.push_back(pCurrPacket_);   // 当前 Packet 完成
        currMsgPacketCount_++;
        newPacket();                         // 创建新 Packet
        totalsize = 0;
    }

    int32 remainsize = packetMaxSize_ - totalsize;
    int32 taddsize = addsize;

    // 剩余空间不够，先填满当前 Packet
    if (remainsize < addsize)
        taddsize = remainsize;

    currMsgLength_ += taddsize;             // 累加消息长度
    return taddsize;
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/bundle.hpp（简化）
enum ReliableTypeEnum
{
    RELIABLE_NO       = 0,   // 完全不可靠（位置更新）
    RELIABLE_DRIVER   = 1,   // 可靠驱动消息
    RELIABLE_PASSENGER = 2,  // 搭便车（随驱动消息一起可靠传输）
    RELIABLE_CRITICAL  = 3   // 关键消息（必须可靠）
};

class Bundle : public BinaryOStream
{
public:
    // 三种消息启动方式
    virtual void startMessage(const InterfaceElement& ie,
        ReliableType reliable = RELIABLE_DRIVER) = 0;

    virtual void startRequest(const InterfaceElement& ie,
        ReplyMessageHandler* handler,
        void* arg = NULL,
        int timeout = DEFAULT_REQUEST_TIMEOUT,
        ReliableType reliable = RELIABLE_DRIVER) = 0;

    virtual void startReply(ReplyID id,
        ReliableType reliable = RELIABLE_DRIVER) = 0;

    void finalise();   // 定稿：写 footer、checksum 等

    // 取消请求
    void cancelRequests(RequestManager* pRequestManager, Reason reason);

protected:
    Channel* pChannel_;
    bool isFinalised_;
    int numMessages_;
    ReplyOrders replyOrders_;   // 请求-回复的回调队列
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/udp_bundle.hpp（简化）
class UDPBundle : public Bundle
{
public:
    UDPBundle(uint8 spareSize = 0, UDPChannel* pChannel = NULL);

    // Bundle overrides
    virtual void startMessage(const InterfaceElement& ie,
        ReliableType reliable = RELIABLE_DRIVER);
    virtual void startRequest(const InterfaceElement& ie,
        ReplyMessageHandler* handler, void* arg = NULL,
        int timeout = DEFAULT_REQUEST_TIMEOUT,
        ReliableType reliable = RELIABLE_DRIVER);
    virtual void startReply(ReplyID id, ReliableType reliable = RELIABLE_DRIVER);

    // BinaryOStream overrides
    virtual void* reserve(int nBytes);
    virtual void addBlob(const void* pBlob, int size);

    virtual void doFinalise();   // 写 UDP footer
};

// 文件：kbe/src/lib/network/packet.h（简化）
class Packet : public MemoryStream, public RefCountable
{
public:
    Packet(MessageID msgID = 0, bool isTCPPacket = true, size_t res = 200):
        MemoryStream(res),
        msgID_(msgID),
        isTCPPacket_(isTCPPacket),
        encrypted_(false),
        pBundle_(NULL),
        sentSize(0)
    {}

    virtual void onReclaimObject()    // 对象池回收时重置
    {
        MemoryStream::onReclaimObject();
        resetPacket();
    }

    virtual int recvFromEndPoint(EndPoint& ep, Address* pAddr = NULL) = 0;

protected:
    MessageID msgID_;
    bool isTCPPacket_;
    bool encrypted_;
    Bundle* pBundle_;     // 所属的 Bundle

public:
    uint32 sentSize;      // 已发送字节数
};

typedef SmartPointer<Packet> PacketPtr;

// TCPPacket 和 UDPPacket 主要区别在 recvFromEndPoint 实现
// TCP：从 socket 读取到缓冲区
// UDP：recvfrom 获取一个完整数据报

// 文件：kbe/src/lib/network/common.h
PACKET_MAX_SIZE_TCP = 1460;    // TCP MSS 1500 - 40(IP+TCP header)
PACKET_MAX_SIZE_UDP = 1472;    // UDP 1500 - 28(IP+UDP header)

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/packet.hpp（简化）
typedef uint16 Flags;

enum
{
    FLAG_HAS_REQUESTS         = 0x0001,
    FLAG_HAS_PIGGYBACKS       = 0x0002,
    FLAG_HAS_ACKS             = 0x0004,
    FLAG_ON_CHANNEL           = 0x0008,
    FLAG_IS_RELIABLE          = 0x0010,
    FLAG_IS_FRAGMENT          = 0x0020,
    FLAG_HAS_SEQUENCE_NUMBER  = 0x0040,
    FLAG_INDEXED_CHANNEL      = 0x0080,
    FLAG_HAS_CHECKSUM         = 0x0100,
    FLAG_CREATE_CHANNEL       = 0x0200,
    FLAG_HAS_CUMULATIVE_ACK   = 0x0400,
};

class Packet : public ReferenceCount
{
public:
    static const int HEADER_SIZE = sizeof(Flags);  // 2 字节 flags 头
    static const int RESERVED_FOOTER_SIZE = 27;    // 预留 footer 空间
    static const int MAX_SIZE = 1472;              // UDP MTU

    char* data() { return data_; }
    const char* body() const { return data_ + HEADER_SIZE; }

    Flags flags() const { return BW_NTOHS(*(Flags*)data_); }
    void setFlags(Flags flags) { *(Flags*)data_ = BW_HTONS(flags); }

    void chain(Packet* pPacket) { next_ = pPacket; }  // 链表连接（分片）
    int freeSpace() const
    {
        return MAX_SIZE - RESERVED_FOOTER_SIZE
            - msgEndOffset_ - footerSize_ - extraFilterSize_;
    }

private:
    char data_[MAX_SIZE];        // 固定大小缓冲区
    PacketPtr next_;             // 链表下一个（分片）
    int msgEndOffset_;           // 消息数据末尾
    int footerSize_;             // footer 大小
    int extraFilterSize_;        // 过滤器预留
    bool isPiggyback_;           // 是否搭便车
    AckCount nAcks_;             // ACK 数量
    SeqNum seq_;                 // 序列号
};

// 文件：kbe/src/lib/network/packet_reader.h（简化）
class PacketReader
{
public:
    PacketReader(Channel* pChannel);
    virtual void processMessages(MessageHandlers* pMsgHandlers, Packet* pPacket);

protected:
    // 半包状态的 5 种类型
    enum FragmentDataTypes
    {
        FRAGMENT_DATA_UNKNOW,           // 未知（初始状态）
        FRAGMENT_DATA_MESSAGE_ID,       // 正在接收消息 ID
        FRAGMENT_DATA_MESSAGE_LENGTH,   // 正在接收消息长度
        FRAGMENT_DATA_MESSAGE_LENGTH1,  // 扩展长度（4 字节）
        FRAGMENT_DATA_MESSAGE_BODY      // 正在接收消息体
    };

    virtual void writeFragmentMessage(FragmentDataTypes flag,
        Packet* pPacket, uint32 datasize);
    virtual void mergeFragmentMessage(Packet* pPacket);

    uint8* pFragmentDatas_;           // 半包数据缓冲区
    uint32 pFragmentDatasWpos_;
    uint32 pFragmentDatasRemain_;
    FragmentDataTypes fragmentDatasFlag_;  // 当前半包状态
    MemoryStream* pFragmentStream_;

    MessageID currMsgID_;
    MessageLength1 currMsgLen_;
    Channel* pChannel_;
};

// 文件：kbe/src/lib/network/packet_reader.cpp:48（简化）
void PacketReader::processMessages(MessageHandlers* pMsgHandlers, Packet* pPacket)
{
    while (pPacket->length() > 0 || pFragmentStream_ != NULL)
    {
        if (fragmentDatasFlag_ == FRAGMENT_DATA_UNKNOW)
        {
            // 状态 1：读取消息 ID
            if (currMsgID_ == 0)
            {
                if (pPacket->length() < NETWORK_MESSAGE_ID_SIZE)
                {
                    // 半包：ID 都不完整，等下一个 Packet
                    writeFragmentMessage(FRAGMENT_DATA_MESSAGE_ID,
                        pPacket, NETWORK_MESSAGE_ID_SIZE);
                    break;
                }
                (*pPacket) >> currMsgID_;
            }

            // 查找消息处理器
            MessageHandler* pMsgHandler = pMsgHandlers->find(currMsgID_);

            if (pMsgHandler == NULL)
            {
                // 未知消息 ID → condemn（谴责）通道
                pChannel_->condemn("not found msgID");
                break;
            }

            // 状态 2：读取消息长度
            if (currMsgLen_ == 0)
            {
                if (pMsgHandler->msgLen == NETWORK_VARIABLE_MESSAGE)
                {
                    // 变长消息：从流中读长度字段
                    if (pPacket->length() < NETWORK_MESSAGE_LENGTH_SIZE)
                    {
                        writeFragmentMessage(FRAGMENT_DATA_MESSAGE_LENGTH,
                            pPacket, NETWORK_MESSAGE_LENGTH_SIZE);
                        break;
                    }
                    (*pPacket) >> currMsgLen_;
                }
                else
                {
                    // 定长消息：长度从 handler 获取
                    currMsgLen_ = pMsgHandler->msgLen;
                }
            }

            // 状态 3：读取消息体
            if (pPacket->length() < currMsgLen_)
            {
                // 半包：消息体不完整
                writeFragmentMessage(FRAGMENT_DATA_MESSAGE_BODY,
                    pPacket, currMsgLen_);
                break;
            }

            // 完整消息，交给 handler 处理
            pMsgHandler->handle(pChannel_, *pPacket);

            // 重置状态，处理下一条消息
            currMsgID_ = 0;
            currMsgLen_ = 0;
        }
        else
        {
            // 有未完成的半包，先合并
            mergeFragmentMessage(pPacket);
        }
    }
}

// 文件：kbe/src/lib/network/message_handler.h（简化）
class MessageHandler
{
public:
    std::string name;
    MessageID msgID;
    MessageArgs* pArgs;
    int32 msgLen;                    // -1 = 变长消息
    bool exposed;                    // 是否客户端可调用
    MessageHandlers* pMessageHandlers;

    // 统计
    volatile mutable uint32 send_size, send_count;
    volatile mutable uint32 recv_size, recv_count;

    virtual void handle(Channel* pChannel, MemoryStream& s)
    {
        pArgs->createFromStream(s);  // 反序列化参数
    }
};

class MessageHandlers
{
public:
    typedef std::map<MessageID, MessageHandler*> MessageHandlerMap;

    MessageHandler* find(MessageID msgID);   // msgID → handler 查找

private:
    MessageHandlerMap msgHandlers_;          // map 存储
    MessageID msgID_;                        // 下一个可分配的 msgID
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/interface_element.hpp（简化）
const char FIXED_LENGTH_MESSAGE    = 0;   // 定长消息
const char VARIABLE_LENGTH_MESSAGE = 1;   // 变长消息
const char CALLBACK_LENGTH_MESSAGE = 2;   // 回调决定长度

class InterfaceElement
{
public:
    InterfaceElement(const char* name = "", MessageID id = 0,
        int8 lengthStyle = INVALID_MESSAGE, int lengthParam = 0,
        InputMessageHandler* pHandler = NULL);

    int headerSize() const;
    int nominalBodySize() const;
    int compressLength(void* header, int length,
        UDPBundle* pBundle, bool isRequest) const;
    int expandLength(void* header, Packet* pPacket, bool isRequest) const;

    MessageID id() const { return id_; }
    int8 lengthStyle() const { return lengthStyle_; }

protected:
    MessageID id_;
    int8 lengthStyle_;
    int32 lengthParam_;
    const char* name_;
    InputMessageHandler* pHandler_;
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/interface_table.hpp（简化）
class InterfaceTable : public TimerHandler
{
public:
    InterfaceTable(EventDispatcher& dispatcher);

    void serve(const InterfaceElement& ie, InputMessageHandler* pHandler);
    InterfaceElementWithStats& operator[](int id);

    const char* msgName(MessageID msgID) const { return table_[msgID].name(); }

private:
    typedef BW::vector<InterfaceElementWithStats> Table;
    Table table_;    // vector，msgID 直接作为索引
};

// 文件：kbe/src/lib/network/fixed_messages.h（简化）
class FixedMessages : public Singleton<FixedMessages>
{
public:
    struct MSGInfo
    {
        MessageID msgid;
        std::string msgname;
    };

    bool loadConfig(std::string fileName, bool notFoundError = true);
    MSGInfo* isFixed(const char* msgName);

private:
    typedef KBEUnordered_map<std::string, MSGInfo> MSGINFO_MAP;
    MSGINFO_MAP _infomap;
};