Framer.hpp

// SPDX-FileCopyrightText: 2026 Vincent Leroy
// SPDX-License-Identifier: MIT
//
// This file is part of dfx.
//
// Licensed under the MIT License. See the LICENSE file in the project root
// for full license information.
 
#pragma once
 
// Standard includes
#include <array>
#include <chrono>
#include <cstdint>
#include <ctime>
#include <mutex>
#include <optional>
#include <span>
#include <sys/socket.h>
#include <unordered_map>
#include <vector>
 
// Project includes
#include <dfx-utilities/CompilerSupport.hpp>
 
/*
 * 0                   1                   2                   3
 * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |      Magic (0x5348)           |    Version    |     Flags     |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |            Reserved           |          Frame size           |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |                       Message ID (UID)                        |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |                             Offset                            |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |                      Total Payload size                       |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 * |                   Header + Payload CRC32C                     |
 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 */
 
namespace dfx::Core::details
{
class Framer
{
public:
    static constexpr uint16_t frameMagic = 0x5348; // "SH"
    static constexpr uint8_t currentVersion = 1;
 
    enum Flag : uint8_t
    {
        None = 0x00,
    };
 
    struct DFX_PACKED Header
    {
        uint16_t magic = frameMagic;
        uint8_t  version = currentVersion;
        Flag     flags = None;
        uint16_t reserved = 0;
        uint16_t frameSize = 0;
        uint32_t messageId = 0;
        uint32_t offset = 0;
        uint32_t totalPayloadSize = 0;
        uint32_t crc32c = 0;
    };
 
    static_assert(sizeof(Header) % 4 == 0);
 
    struct Frame
    {
        Header header;
        std::span<uint8_t const> payload;
 
        std::array<iovec, 2> toIovec() const noexcept;
    };
 
private:
    struct ReassemblyBuffer
    {
        std::vector<uint8_t> data;
        uint32_t totalPayloadSize;
        uint32_t payloadSizeReceived;
        timespec lastUpdatedAt;
    };
 
public:
    static std::vector<Frame> frameAll(uint32_t payloadId,
                                       std::span<uint8_t const> payload,
                                       size_t maxFrameSize);
 
    static Frame frameNext(uint32_t payloadId,
                           std::span<uint8_t const> fullPayload,
                           size_t maxFrameSize,
                           size_t & offset);
 
    static constexpr std::size_t maxFrameSize() noexcept { return std::numeric_limits<decltype(Header::frameSize)>::max(); }
 
public:
    std::optional<std::vector<uint8_t>> push(std::span<uint8_t const> frame, timespec const & time);
    void gc(std::chrono::milliseconds maxAge);
 
    bool hasPendingData() const noexcept { return !_pending.empty(); }
 
private:
    std::mutex _mutex;
    std::unordered_map<uint32_t, ReassemblyBuffer> _pending;
};
} // !namespace dfx::Core::details