newosp ospgen: YAML 驱动的嵌入式 C++17 零堆分配消息代码生成

namespace: protocol
version: 1
byte_order: native
includes: [cstdint, cstring]

# 类型安全的独立枚举
enums:
  - name: StreamAction
    desc: "Stream control action"
    type: uint8_t
    entries:
      - { name: STOP,  value: 0, desc: "Stop streaming" }
      - { name: START, value: 1, desc: "Start streaming" }

# 事件 ID (uint32_t enum)
events:
  - { name: REGISTER,  id: 1, desc: "Device registration request" }
  - { name: HEARTBEAT, id: 3, desc: "Keepalive heartbeat" }

# 消息结构体
messages:
  - name: RegisterRequest
    desc: "Device registration request sent by client"
    event: REGISTER                    # ← 编译期绑定到 event
    expected_size: 50                  # ← sizeof 断言
    fields:
      - { name: device_id, type: "char[32]", desc: "Unique device ID" }
      - { name: ip,        type: "char[16]", desc: "Device IP address" }
      - { name: port,      type: uint16_t,   desc: "Listening port", range: [1, 65535] }

namespace protocol {

// ① 协议版本
static constexpr uint32_t kVersion = 1;

// ② 类型安全枚举 (enum class, MISRA C++ 合规)
enum class StreamAction : uint8_t {
  kStop = 0,   ///< Stop streaming
  kStart = 1   ///< Start streaming
};

// ③ 事件枚举 (含 Doxygen 注释)
enum ProtocolEvent : uint32_t {
  kProtocolRegister = 1,   ///< Device registration request
  kProtocolHeartbeat = 3,  ///< Keepalive heartbeat
};

// ④ POD 结构体 (Doxygen + 字段描述 + 零初始化构造)
/// Device registration request sent by client
struct RegisterRequest {
  char device_id[32];  ///< Unique device ID
  char ip[16];         ///< Device IP address
  uint16_t port;       ///< Listening port

  RegisterRequest() noexcept : device_id{}, ip{}, port(0) {}

  // ⑤ 字段范围校验
  bool Validate() const noexcept {
    if (port < 1 || port > 65535) return false;
    return true;
  }

  // ⑥ 调试打印 (snprintf, 零堆分配)
  uint32_t Dump(char* buf, uint32_t cap) const noexcept {
    int n = std::snprintf(buf, cap,
        "RegisterRequest{device_id=%s, ip=%s, port=%u}",
        device_id, ip, static_cast<unsigned>(port));
    return (n > 0) ? static_cast<uint32_t>(n) : 0;
  }
};

// ⑦ 类型安全 Payload (std::variant)
using ProtocolPayload = std::variant<RegisterRequest, ...>;

// ⑧ 编译期断言
static_assert(std::is_trivially_copyable<RegisterRequest>::value, "...");
static_assert(sizeof(RegisterRequest) == 50, "size mismatch");

// ⑨ Event ↔ Message 编译期绑定
template <> struct EventMessage<kProtocolRegister> {
  using type = RegisterRequest;
};
template <> struct MessageEvent<RegisterRequest> {
  static constexpr uint32_t value = kProtocolRegister;
};
template <typename MsgT>
constexpr uint32_t EventIdOf() noexcept {
  return MessageEvent<MsgT>::value;
}

}  // namespace protocol

using ProtoBus = osp::AsyncBus<protocol::ProtocolPayload>;
osp::Node<protocol::ProtocolPayload> registrar(kNodeName_registrar, kNodeId_registrar);

registrar.Subscribe<protocol::RegisterRequest>(
    [](const protocol::RegisterRequest& req, const osp::MessageHeader& hdr) {
        if (!req.Validate()) { /* 字段越界 */ }
        char buf[128];
        req.Dump(buf, sizeof(buf));  // 调试输出
    });

// ShmRingBuffer<SlotSize, SlotCount>::TryPush 内部:
std::memcpy(slot_ptr, data, size);  // data 必须是 trivially_copyable

// 发送端
transport.Send(&msg, sizeof(msg));

// 接收端
RegisterRequest msg;
transport.Recv(&msg, sizeof(RegisterRequest));  // sizeof 必须两端一致

// 编译器 padding 导致 sizeof 变化时，立即报错
static_assert(sizeof(RegisterResponse) == 40,
              "RegisterResponse size mismatch (check field alignment/packing)");

// 编译期验证: RegisterRequest 必须对应 REGISTER 事件
static_assert(protocol::EventIdOf<protocol::RegisterRequest>() ==
              protocol::kProtocolRegister, "binding mismatch");

// 编译期类型获取: 知道 event ID，推导 message type
using MsgType = protocol::EventMessage<protocol::kProtocolRegister>::type;
// MsgType == RegisterRequest，零运行时开销

version: 2                           # 协议版本升级
messages:
  - name: RegisterRequestV1
    deprecated: "use RegisterRequestV2"  # 标记废弃
    expected_size: 50
    # ...
  - name: RegisterRequestV2
    event: REGISTER
    expected_size: 54                 # 新版本多了 4 字节
    fields:
      - { name: device_id, type: "char[32]" }
      - { name: ip,        type: "char[16]" }
      - { name: port,      type: uint16_t }
      - { name: capabilities, type: uint32_t, desc: "Feature flags" }  # 新字段

/// @deprecated use RegisterRequestV2
struct [[deprecated("use RegisterRequestV2")]] RegisterRequestV1 { ... };
struct RegisterRequestV2 { ... };

// messages.hpp (44 行手写代码)
struct RegisterRequest {
  char device_id[32];
  char ip[16];
  uint16_t port;
};
struct RegisterResponse { ... };
struct HeartbeatMsg { ... };
struct StreamCommand {
  uint32_t session_id;
  uint8_t action;       // 0 = stop, 1 = start   ← 魔数
  uint8_t media_type;   // 0 = video, 1 = audio   ← 魔数
};
struct StreamData { ... };

using Payload = std::variant<RegisterRequest, RegisterResponse,
                             HeartbeatMsg, StreamCommand, StreamData>;

static constexpr uint32_t kRegistrarId = 1;     // 手动定义，与拓扑无关
static constexpr uint32_t kHeartbeatId = 2;

const char* action = (cmd.action == 1) ? "START" : "STOP";  // 魔数
const char* media = (cmd.media_type == 0) ? "video"          // 魔数
                  : (cmd.media_type == 1) ? "audio" : "A/V";

#include "osp/protocol_messages.hpp"   // ospgen 生成
#include "osp/topology.hpp"            // ospgen 生成

using Payload = protocol::ProtocolPayload;  // 生成的 variant

struct RegistrarHandler {
  void operator()(const protocol::RegisterRequest& req, ...) {
    // ① Validate: 端口范围 [1, 65535] 自动检查
    if (!req.Validate()) {
      OSP_LOG_WARN("Registrar", "rejected: port out of range");
      return;
    }
    // ② Dump: 结构化调试输出，无需手写格式串
    char dump[256];
    req.Dump(dump, sizeof(dump));
    OSP_LOG_INFO("Registrar", "recv: %s", dump);
    // ...
    bus->Publish(Payload(resp), kNodeId_registrar);  // ③ 拓扑常量
  }
};

struct StreamHandler {
  void operator()(const protocol::StreamCommand& cmd, ...) {
    if (!cmd.Validate()) { ... }  // action 范围 [0, 1] 自动检查
    // ④ 类型安全枚举替代魔数
    const char* action =
        (cmd.action == static_cast<uint8_t>(protocol::StreamAction::kStart))
            ? "START" : "STOP";
    const char* media =
        (cmd.media_type == static_cast<uint8_t>(protocol::MediaType::kAv))
            ? "A/V" : ...;
  }
};

// 编译期: event-message 绑定正确性
static_assert(protocol::EventIdOf<protocol::RegisterRequest>() ==
                  protocol::kProtocolRegister, "binding mismatch");

// 编译期: 跨平台 sizeof 一致性
static_assert(sizeof(protocol::RegisterRequest) == 50, "");
static_assert(sizeof(protocol::StreamCommand) == 8, "");

// 运行时: 拓扑信息
OSP_LOG_INFO("Proto", "protocol version=%u, node count=%u",
             protocol::kVersion, kNodeCount);

// 节点创建: 使用拓扑常量
RegistrarNode registrar(kNodeName_registrar, kNodeId_registrar, ...);
osp::Node<Payload> client(kNodeName_client, kNodeId_client);

if (!msg.Validate()) {
    OSP_LOG_WARN("proto", "invalid message, dropping");
    return;  // 而不是 try-catch
}