nng-ruby 0.1.1 → 0.1.2

data/examples/protobuf_advanced.rb

@@ -0,0 +1,322 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# NNG + Protocol Buffers 高级示例
+# 使用 .proto 文件和复杂的消息嵌套
+
+require 'nng'
+require 'google/protobuf'
+
+puts "=" * 70
+puts "NNG + Protocol Buffers 高级示例"
+puts "使用 .proto 文件和消息嵌套"
+puts "=" * 70
+puts
+
+# ============================================================================
+# 1. 从 .proto 文件生成 Ruby 代码 (编译时)
+# ============================================================================
+
+puts "说明: 使用 .proto 文件"
+puts "-" * 70
+puts
+puts "实际项目中应该使用 protoc 编译 .proto 文件:"
+puts "  $ protoc --ruby_out=. proto/message.proto"
+puts
+puts "本示例直接在 Ruby 中定义消息 (等效于编译后的代码)"
+puts
+
+# 定义消息 (等效于从 message.proto 编译生成)
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("message.proto", syntax: :proto3) do
+    # RPC 请求
+    add_message "RpcRequest" do
+      optional :func_code, :int32, 1
+      optional :data, :bytes, 2
+      optional :timestamp, :int64, 3
+      optional :request_id, :string, 4
+    end
+
+    # RPC 响应
+    add_message "RpcResponse" do
+      optional :status, :int32, 1
+      optional :data, :bytes, 2
+      optional :error_msg, :string, 3
+      optional :request_id, :string, 4
+    end
+
+    # 用户
+    add_message "User" do
+      optional :id, :int32, 1
+      optional :name, :string, 2
+      optional :email, :string, 3
+      repeated :tags, :string, 4
+    end
+
+    # 联系人
+    add_message "Contact" do
+      optional :wxid, :string, 1
+      optional :name, :string, 2
+      optional :remark, :string, 3
+      optional :contact_type, :int32, 4
+    end
+
+    # 联系人列表
+    add_message "ContactList" do
+      repeated :contacts, :message, 1, "Contact"
+    end
+
+    # 文本消息
+    add_message "TextMessage" do
+      optional :receiver, :string, 1
+      optional :content, :string, 2
+      optional :aters, :string, 3
+    end
+  end
+end
+
+# 获取消息类
+RpcRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("RpcRequest").msgclass
+RpcResponse = Google::Protobuf::DescriptorPool.generated_pool.lookup("RpcResponse").msgclass
+User = Google::Protobuf::DescriptorPool.generated_pool.lookup("User").msgclass
+Contact = Google::Protobuf::DescriptorPool.generated_pool.lookup("Contact").msgclass
+ContactList = Google::Protobuf::DescriptorPool.generated_pool.lookup("ContactList").msgclass
+TextMessage = Google::Protobuf::DescriptorPool.generated_pool.lookup("TextMessage").msgclass
+
+puts "✅ Protobuf 消息类加载完成"
+puts
+
+# ============================================================================
+# 2. 示例 1: 嵌套消息 - 获取联系人列表
+# ============================================================================
+
+puts "示例 1: 嵌套消息 - 获取联系人列表"
+puts "=" * 70
+puts
+
+url1 = "tcp://127.0.0.1:15560"
+
+# 服务器进程
+server1_pid = fork do
+  server = NNG::Socket.new(:pair1)
+  server.listen(url1)
+  puts "[服务器] 监听: #{url1}"
+
+  # 接收 RPC 请求
+  request_data = server.recv
+  rpc_request = RpcRequest.decode(request_data)
+
+  puts "[服务器] 收到 RPC 调用:"
+  puts "[服务器]   Function: 0x#{rpc_request.func_code.to_s(16)}"
+  puts "[服务器]   Request ID: #{rpc_request.request_id}"
+  puts "[服务器]   Timestamp: #{Time.at(rpc_request.timestamp)}"
+
+  # 构建联系人列表
+  contacts = ContactList.new(
+    contacts: [
+      Contact.new(wxid: "wxid_001", name: "张三", remark: "老同学", contact_type: 1),
+      Contact.new(wxid: "wxid_002", name: "李四", remark: "同事", contact_type: 1),
+      Contact.new(wxid: "chatroom_001", name: "技术交流群", remark: "", contact_type: 2)
+    ]
+  )
+
+  puts "[服务器] 构建响应: #{contacts.contacts.size} 个联系人"
+
+  # 编码嵌套消息
+  contacts_data = ContactList.encode(contacts)
+
+  # 构建 RPC 响应
+  rpc_response = RpcResponse.new(
+    status: 0,
+    data: contacts_data,
+    error_msg: "",
+    request_id: rpc_request.request_id
+  )
+
+  # 发送响应
+  server.send(RpcResponse.encode(rpc_response))
+  puts "[服务器] 响应已发送"
+
+  server.close
+end
+
+sleep 0.5
+
+# 客户端
+client1 = NNG::Socket.new(:pair1)
+client1.dial(url1)
+puts "[客户端] 连接: #{url1}"
+
+# 构建 RPC 请求
+rpc_request = RpcRequest.new(
+  func_code: 0x12,  # FUNC_GET_CONTACTS
+  data: "",
+  timestamp: Time.now.to_i,
+  request_id: "req_#{Time.now.to_i}_001"
+)
+
+puts "[客户端] 发送 RPC 请求:"
+puts "[客户端]   Function: 0x#{rpc_request.func_code.to_s(16)}"
+puts "[客户端]   Request ID: #{rpc_request.request_id}"
+
+# 发送请求
+client1.send(RpcRequest.encode(rpc_request))
+
+# 接收响应
+response_data = client1.recv
+rpc_response = RpcResponse.decode(response_data)
+
+puts "[客户端] 收到 RPC 响应:"
+puts "[客户端]   Status: #{rpc_response.status}"
+puts "[客户端]   Request ID: #{rpc_response.request_id}"
+
+if rpc_response.status == 0
+  # 解析嵌套的联系人列表
+  contacts = ContactList.decode(rpc_response.data)
+  puts "[客户端] 解析联系人列表 (#{contacts.contacts.size} 个):"
+
+  contacts.contacts.each_with_index do |contact, i|
+    puts "[客户端]   #{i + 1}. #{contact.name} (#{contact.wxid})"
+    puts "[客户端]      备注: #{contact.remark}" unless contact.remark.empty?
+    puts "[客户端]      类型: #{contact.contact_type == 1 ? '好友' : '群聊'}"
+  end
+else
+  puts "[客户端] 错误: #{rpc_response.error_msg}"
+end
+
+client1.close
+Process.wait(server1_pid)
+
+puts
+puts
+
+# ============================================================================
+# 3. 示例 2: 发送文本消息
+# ============================================================================
+
+puts "示例 2: 发送文本消息"
+puts "=" * 70
+puts
+
+url2 = "tcp://127.0.0.1:15561"
+
+# 服务器进程
+server2_pid = fork do
+  server = NNG::Socket.new(:pair1)
+  server.listen(url2)
+  puts "[服务器] 监听: #{url2}"
+
+  # 接收 RPC 请求
+  request_data = server.recv
+  rpc_request = RpcRequest.decode(request_data)
+
+  puts "[服务器] 收到 RPC 调用:"
+  puts "[服务器]   Function: 0x#{rpc_request.func_code.to_s(16)}"
+
+  # 解析文本消息参数
+  text_msg = TextMessage.decode(rpc_request.data)
+  puts "[服务器] 解析文本消息:"
+  puts "[服务器]   接收者: #{text_msg.receiver}"
+  puts "[服务器]   内容: #{text_msg.content}"
+  puts "[服务器]   @的人: #{text_msg.aters}" unless text_msg.aters.empty?
+
+  # 模拟发送消息
+  puts "[服务器] 发送消息..."
+  sleep 0.1
+  puts "[服务器] 消息发送成功"
+
+  # 构建响应
+  rpc_response = RpcResponse.new(
+    status: 0,
+    data: [1].pack('C'),  # 返回 1 表示成功
+    error_msg: "",
+    request_id: rpc_request.request_id
+  )
+
+  server.send(RpcResponse.encode(rpc_response))
+  server.close
+end
+
+sleep 0.5
+
+# 客户端
+client2 = NNG::Socket.new(:pair1)
+client2.dial(url2)
+puts "[客户端] 连接: #{url2}"
+
+# 构建文本消息
+text_msg = TextMessage.new(
+  receiver: "wxid_001",
+  content: "Hello from NNG + Protobuf!",
+  aters: ""
+)
+
+# 编码为字节
+text_msg_data = TextMessage.encode(text_msg)
+
+# 构建 RPC 请求
+rpc_request = RpcRequest.new(
+  func_code: 0x20,  # FUNC_SEND_TXT
+  data: text_msg_data,
+  timestamp: Time.now.to_i,
+  request_id: "req_#{Time.now.to_i}_002"
+)
+
+puts "[客户端] 发送文本消息:"
+puts "[客户端]   接收者: #{text_msg.receiver}"
+puts "[客户端]   内容: #{text_msg.content}"
+
+# 发送请求
+client2.send(RpcRequest.encode(rpc_request))
+
+# 接收响应
+response_data = client2.recv
+rpc_response = RpcResponse.decode(response_data)
+
+puts "[客户端] 收到响应:"
+if rpc_response.status == 0
+  puts "[客户端]   ✅ 消息发送成功"
+else
+  puts "[客户端]   ❌ 发送失败: #{rpc_response.error_msg}"
+end
+
+client2.close
+Process.wait(server2_pid)
+
+puts
+puts
+
+# ============================================================================
+# 总结
+# ============================================================================
+
+puts "=" * 70
+puts "✅ 示例完成"
+puts "=" * 70
+puts
+puts "关键技术点:"
+puts
+puts "1. 消息嵌套:"
+puts "   RpcRequest { data: ContactList { contacts: [Contact, ...] } }"
+puts
+puts "2. 序列化链:"
+puts "   内层: ContactList.encode(contacts) → bytes"
+puts "   外层: RpcRequest.encode(request) → bytes"
+puts
+puts "3. 反序列化链:"
+puts "   外层: RpcRequest.decode(bytes) → request"
+puts "   内层: ContactList.decode(request.data) → contacts"
+puts
+puts "4. 实际应用场景:"
+puts "   • RPC 框架 (如本例)"
+puts "   • 微服务通信"
+puts "   • 消息队列"
+puts "   • 分布式系统数据交换"
+puts
+puts "5. 优势:"
+puts "   ✅ 强类型约束"
+puts "   ✅ 自动编解码"
+puts "   ✅ 跨语言兼容"
+puts "   ✅ 高效序列化"
+puts "   ✅ 版本向后兼容"
+puts

data/examples/protobuf_demo.rb

@@ -0,0 +1,340 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# NNG + Protocol Buffers 集成演示
+# 展示如何将 Protobuf 消息通过 NNG 发送和接收
+
+require 'google/protobuf'
+
+puts "=" * 70
+puts "NNG + Protocol Buffers 集成演示"
+puts "=" * 70
+puts
+
+# ============================================================================
+# 1. 定义 Protobuf 消息结构
+# ============================================================================
+
+puts "步骤 1: 定义 Protobuf 消息结构"
+puts "-" * 70
+puts
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("wcf_rpc.proto", syntax: :proto3) do
+    # RPC 请求消息
+    add_message "RpcRequest" do
+      optional :func_code, :int32, 1      # 功能码
+      optional :data, :bytes, 2           # 业务数据
+      optional :request_id, :string, 3    # 请求 ID
+    end
+
+    # RPC 响应消息
+    add_message "RpcResponse" do
+      optional :status, :int32, 1         # 状态码
+      optional :data, :bytes, 2           # 响应数据
+      optional :error_msg, :string, 3     # 错误消息
+    end
+
+    # 联系人信息
+    add_message "Contact" do
+      optional :wxid, :string, 1
+      optional :name, :string, 2
+      optional :remark, :string, 3
+    end
+
+    # 联系人列表
+    add_message "ContactList" do
+      repeated :contacts, :message, 1, "Contact"
+    end
+
+    # 文本消息
+    add_message "TextMessage" do
+      optional :receiver, :string, 1
+      optional :content, :string, 2
+      optional :aters, :string, 3
+    end
+  end
+end
+
+# 获取消息类
+RpcRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("RpcRequest").msgclass
+RpcResponse = Google::Protobuf::DescriptorPool.generated_pool.lookup("RpcResponse").msgclass
+Contact = Google::Protobuf::DescriptorPool.generated_pool.lookup("Contact").msgclass
+ContactList = Google::Protobuf::DescriptorPool.generated_pool.lookup("ContactList").msgclass
+TextMessage = Google::Protobuf::DescriptorPool.generated_pool.lookup("TextMessage").msgclass
+
+puts "✅ 消息定义完成:"
+puts "   - RpcRequest (func_code, data, request_id)"
+puts "   - RpcResponse (status, data, error_msg)"
+puts "   - Contact (wxid, name, remark)"
+puts "   - ContactList (contacts[])"
+puts "   - TextMessage (receiver, content, aters)"
+puts
+
+# ============================================================================
+# 2. 示例 1: 简单的请求-响应
+# ============================================================================
+
+puts "示例 1: 简单的 RPC 请求-响应"
+puts "=" * 70
+puts
+
+# 客户端: 构建请求
+request = RpcRequest.new(
+  func_code: 0x01,        # FUNC_IS_LOGIN
+  data: "",
+  request_id: "req_001"
+)
+
+puts "📤 客户端构建请求:"
+puts "   Function Code: 0x#{request.func_code.to_s(16)}"
+puts "   Request ID: #{request.request_id}"
+puts
+
+# 序列化为二进制
+request_binary = RpcRequest.encode(request)
+puts "📦 序列化结果:"
+puts "   大小: #{request_binary.bytesize} bytes"
+puts "   十六进制: #{request_binary.unpack('H*').first[0, 40]}..."
+puts
+
+# 模拟通过 NNG 发送 (实际代码: socket.send(request_binary))
+puts "🌐 通过 NNG 发送: socket.send(request_binary)"
+puts
+
+# 服务器: 接收并反序列化
+# 模拟从 NNG 接收 (实际代码: response_binary = socket.recv)
+puts "📥 服务器接收并解析:"
+received_request = RpcRequest.decode(request_binary)
+puts "   Function Code: 0x#{received_request.func_code.to_s(16)}"
+puts "   Request ID: #{received_request.request_id}"
+puts
+
+# 服务器: 构建响应
+response = RpcResponse.new(
+  status: 0,
+  data: [1].pack('C'),    # 返回 1 表示已登录
+  error_msg: ""
+)
+
+puts "📤 服务器构建响应:"
+puts "   Status: #{response.status} (成功)"
+puts
+
+# 序列化响应
+response_binary = RpcResponse.encode(response)
+puts "📦 序列化响应: #{response_binary.bytesize} bytes"
+puts
+
+# 模拟通过 NNG 发送响应
+puts "🌐 通过 NNG 发送响应: socket.send(response_binary)"
+puts
+
+# 客户端: 接收并解析响应
+received_response = RpcResponse.decode(response_binary)
+puts "📥 客户端接收响应:"
+puts "   Status: #{received_response.status}"
+puts "   Is Login: #{received_response.data.unpack('C').first == 1}"
+puts
+puts
+
+# ============================================================================
+# 3. 示例 2: 嵌套消息 - 获取联系人列表
+# ============================================================================
+
+puts "示例 2: 嵌套消息 - 获取联系人列表"
+puts "=" * 70
+puts
+
+# 客户端: 发送获取联系人请求
+get_contacts_request = RpcRequest.new(
+  func_code: 0x12,        # FUNC_GET_CONTACTS
+  data: "",
+  request_id: "req_002"
+)
+
+request_binary = RpcRequest.encode(get_contacts_request)
+puts "📤 客户端发送请求: FUNC_GET_CONTACTS (#{request_binary.bytesize} bytes)"
+puts
+
+# 服务器: 构建联系人列表
+contacts = ContactList.new(
+  contacts: [
+    Contact.new(wxid: "wxid_001", name: "张三", remark: "老同学"),
+    Contact.new(wxid: "wxid_002", name: "李四", remark: "同事"),
+    Contact.new(wxid: "wxid_003", name: "王五", remark: ""),
+    Contact.new(wxid: "chatroom_001", name: "技术交流群", remark: "")
+  ]
+)
+
+puts "🏗️  服务器构建联系人列表:"
+contacts.contacts.each_with_index do |contact, i|
+  puts "   #{i + 1}. #{contact.name} (#{contact.wxid})"
+  puts "      备注: #{contact.remark}" unless contact.remark.empty?
+end
+puts
+
+# 序列化联系人列表 (内层消息)
+contacts_binary = ContactList.encode(contacts)
+puts "📦 序列化联系人列表: #{contacts_binary.bytesize} bytes"
+puts
+
+# 构建 RPC 响应 (外层消息，包含内层数据)
+contacts_response = RpcResponse.new(
+  status: 0,
+  data: contacts_binary,    # 嵌套的联系人列表
+  error_msg: ""
+)
+
+response_binary = RpcResponse.encode(contacts_response)
+puts "📦 序列化 RPC 响应: #{response_binary.bytesize} bytes"
+puts "   (包含嵌套的联系人列表)"
+puts
+
+# 客户端: 接收并解析
+puts "📥 客户端接收并解析:"
+
+# 第一层: 解析 RPC 响应
+rpc_resp = RpcResponse.decode(response_binary)
+puts "   RPC Status: #{rpc_resp.status}"
+
+# 第二层: 解析嵌套的联系人列表
+contact_list = ContactList.decode(rpc_resp.data)
+puts "   联系人数量: #{contact_list.contacts.size}"
+puts
+
+puts "📋 解析结果:"
+contact_list.contacts.each_with_index do |contact, i|
+  puts "   #{i + 1}. #{contact.name}"
+  puts "      WXID: #{contact.wxid}"
+  puts "      备注: #{contact.remark}" unless contact.remark.empty?
+end
+puts
+puts
+
+# ============================================================================
+# 4. 示例 3: 发送文本消息
+# ============================================================================
+
+puts "示例 3: 发送文本消息"
+puts "=" * 70
+puts
+
+# 客户端: 构建文本消息
+text_msg = TextMessage.new(
+  receiver: "wxid_001",
+  content: "Hello from NNG + Protobuf!",
+  aters: ""
+)
+
+puts "📝 客户端构建文本消息:"
+puts "   接收者: #{text_msg.receiver}"
+puts "   内容: #{text_msg.content}"
+puts
+
+# 序列化文本消息
+text_msg_binary = TextMessage.encode(text_msg)
+puts "📦 序列化文本消息: #{text_msg_binary.bytesize} bytes"
+puts
+
+# 构建 RPC 请求 (包含文本消息)
+send_text_request = RpcRequest.new(
+  func_code: 0x20,        # FUNC_SEND_TXT
+  data: text_msg_binary,
+  request_id: "req_003"
+)
+
+request_binary = RpcRequest.encode(send_text_request)
+puts "📦 序列化 RPC 请求: #{request_binary.bytesize} bytes"
+puts "🌐 通过 NNG 发送: socket.send(request_binary)"
+puts
+
+# 服务器: 接收并解析
+puts "📥 服务器接收并解析:"
+recv_request = RpcRequest.decode(request_binary)
+puts "   Function Code: 0x#{recv_request.func_code.to_s(16)}"
+
+# 解析嵌套的文本消息
+recv_text_msg = TextMessage.decode(recv_request.data)
+puts "   接收者: #{recv_text_msg.receiver}"
+puts "   内容: #{recv_text_msg.content}"
+puts
+
+# 服务器: 发送消息并响应
+puts "📨 服务器发送消息..."
+send_response = RpcResponse.new(
+  status: 0,
+  data: [1].pack('C'),    # 1 = 发送成功
+  error_msg: ""
+)
+
+response_binary = RpcResponse.encode(send_response)
+puts "📤 服务器响应: 发送成功"
+puts
+
+# 客户端: 接收响应
+final_response = RpcResponse.decode(response_binary)
+puts "📥 客户端收到响应:"
+if final_response.status == 0
+  puts "   ✅ 消息发送成功"
+else
+  puts "   ❌ 发送失败: #{final_response.error_msg}"
+end
+puts
+puts
+
+# ============================================================================
+# 5. 总结
+# ============================================================================
+
+puts "=" * 70
+puts "✅ 演示完成"
+puts "=" * 70
+puts
+puts "实际使用 NNG 的代码示例:"
+puts
+puts "  require 'nng'"
+puts "  require 'google/protobuf'"
+puts
+puts "  # 客户端"
+puts "  client = NNG::Socket.new(:pair1)"
+puts "  client.dial('tcp://127.0.0.1:10086')"
+puts
+puts "  # 构建并发送 Protobuf 请求"
+puts "  request = RpcRequest.new(func_code: 0x12, data: '', request_id: 'req_001')"
+puts "  request_binary = RpcRequest.encode(request)"
+puts "  client.send(request_binary)"
+puts
+puts "  # 接收并解析 Protobuf 响应"
+puts "  response_binary = client.recv"
+puts "  response = RpcResponse.decode(response_binary)"
+puts
+puts "  # 解析嵌套的业务数据"
+puts "  contacts = ContactList.decode(response.data)"
+puts
+puts "  client.close"
+puts
+puts "关键技术点:"
+puts
+puts "1. 消息嵌套:"
+puts "   RpcRequest/Response.data 字段 (bytes 类型) 可存储任意 Protobuf 消息"
+puts
+puts "2. 序列化链:"
+puts "   业务消息 → encode → bytes → RPC 消息 → encode → bytes → NNG 发送"
+puts
+puts "3. 反序列化链:"
+puts "   NNG 接收 → bytes → decode → RPC 消息 → bytes → decode → 业务消息"
+puts
+puts "4. 优势:"
+puts "   ✅ 类型安全 - 编译时检查"
+puts "   ✅ 高效编码 - 比 JSON 小 50%+"
+puts "   ✅ 跨语言 - 与 Python/Java/Go/C++ 互通"
+puts "   ✅ 版本兼容 - 可安全添加/删除字段"
+puts "   ✅ 自动验证 - 自动检查必填字段"
+puts
+puts "5. 实际应用场景:"
+puts "   • WeChatFerry RPC 通信"
+puts "   • 微服务间调用"
+puts "   • 分布式系统消息传递"
+puts "   • 客户端-服务器协议"
+puts