Merge branch 'main' of https://106.52.207.92:9103/limingjie/OmniSocketGo

AGENTS.md

@@ -0,0 +1,43 @@
+
+
+
+# 代码库指南 (Repository Guidelines)
+
+## 项目结构与模块组织 (Project Structure & Module Organization)
+`OmniSocketGo` 是一个基于 Go 1.22 的小型模块，在 `cmd/` 目录下有三个命令行（CLI）入口点：`cmd/server`、`cmd/peer` 和 `cmd/latencysummary`。共享代码存放于 `cmd/internal/` 目录下：
+
+- `protocol` 用于消息的编码/解码
+- `server` 用于连接中心（hub）逻辑
+- `peer` 用于客户端的发送/接收与持久化
+- `transport` 用于 TCP 传输和 Linux 时间戳处理
+- `latencylog` 用于 JSONL 日志记录和摘要生成
+
+请将测试文件与它们覆盖的代码放在一起（即 `*_test.go`）。使用 `bin/` 目录存放本地构建输出，使用 `inbox/` 目录存放接收到的负载数据；这两个目录均已被忽略（不在版本控制内），不应提交到代码库中。
+
+## 构建、测试与开发命令 (Build, Test, and Development Commands)
+显式构建主要的二进制文件：
+
+- `go build -o bin/server ./cmd/server`
+- `go build -o bin/peer ./cmd/peer`
+- `go build -o bin/latencysummary ./cmd/latencysummary`
+
+在 Linux 上运行完整的测试套件：
+
+- `go test ./...`
+
+需要部署时进行交叉编译：
+
+- `CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/server-linux-amd64 ./cmd/server`
+
+在代码审查前格式化已编辑的文件：
+
+- `gofmt -w cmd/peer/main.go`
+
+## 编码风格与命名规范 (Coding Style & Naming Conventions)
+遵循标准的 Go 代码风格，让 `gofmt` 控制代码格式；请勿手动对齐代码。保持包名小写，导出的标识符使用大驼峰命名法（`CamelCase`），未导出的辅助函数/变量使用小驼峰命名法（`mixedCase`）。与现有的 CLI 标志（flag）命名保持一致，使用小写且带连字符的选项，例如 `-bind-device` 和 `-latency-log`。优先编写功能聚焦的包和简短的函数，而不是随意添加新的顶层二进制文件或包含过多杂项的通用工具文件。
+
+## 测试指南 (Testing Guidelines)
+使用 Go 内置的 `testing` 包。优先编写结合 `t.Run` 的表格驱动测试（table-driven tests），参考类似 `cmd/peer/interactive_test.go` 的文件。测试的命名应基于可观察到的行为，而不是内部实现细节。Linux 特有的行为测试应放在 `*_linux_test.go` 文件中。本项目未配置代码覆盖率门禁限制，但新增的协议、传输或持久化逻辑应当包含单元测试，并在相关的地方提供错误路径（error-path）的覆盖测试。
+
+## 平台与配置说明 (Platform & Configuration Notes)
+本项目以 Linux 为目标平台。传输层依赖于 Linux 特有的时间戳代码，因此完整构建和 `go test ./...` 应视为仅限 Linux 平台的验证操作。

doc/project-guide.md

@@ -0,0 +1,571 @@
+# OmniSocketGo 项目导读
+
+本文面向第一次接手 `OmniSocketGo` 的开发者，目标是帮助你在阅读源码之前先建立整体认知。它不替代根目录的 `README.md`；`README.md` 仍然适合作为快速构建和运行说明，这份文档更偏向项目结构、模块职责、消息流转和源码阅读导航。
+
+## 1. 项目定位
+
+`OmniSocketGo` 是一个 Linux-only 的 Go 1.22 项目，核心模型是：
+
+- 一个中心 `server`
+- 多个连接到 `server` 的 `peer`
+- 一个独立的时延日志汇总工具 `latencysummary`
+
+从职责上看：
+
+- `server` 负责接收 TCP 连接、校验 `peer` 注册、维护在线连接表，并在不同 `peer` 之间转发业务消息。
+- `peer` 负责连接 `server`、完成注册、发送文本或文件、接收转发消息，并将接收到的内容持久化到本地目录。
+- `latencysummary` 负责读取原始时延 JSONL 日志，按消息维度聚合为摘要结果，并额外生成一个 HTML 图表，方便观察端到端时延。
+
+这个项目不是点对点直连通信，而是典型的“中心转发”模式。`peer-a` 想发给 `peer-b` 时，消息路径是：
+
+`peer-a -> server -> peer-b`
+
+## 2. 顶层结构
+
+当前仓库的核心内容可以按下面理解：
+
+```text
+OmniSocketGo/
+├─ README.md
+├─ go.mod
+├─ doc/
+│  └─ project-guide.md
+├─ cmd/
+│  ├─ server/
+│  │  └─ main.go
+│  ├─ peer/
+│  │  ├─ main.go
+│  │  ├─ interactive.go
+│  │  └─ interactive_test.go
+│  ├─ latencysummary/
+│  │  └─ main.go
+│  └─ internal/
+│     ├─ protocol/
+│     ├─ transport/
+│     ├─ server/
+│     ├─ peer/
+│     └─ latencylog/
+└─ latencysummary
+```
+
+其中：
+
+- `cmd/server`、`cmd/peer`、`cmd/latencysummary` 是 3 个可执行程序入口。
+- `cmd/internal/*` 是这些入口依赖的内部包，真正的核心逻辑都在这里。
+- 根目录中还存在一个名为 `latencysummary` 的文件；本文聚焦源码结构，因此不把它作为主要源码入口展开。
+
+## 3. 分层视角看项目
+
+如果从“分层”而不是“目录”来看，项目可以分成 5 层：
+
+1. 命令入口层
+2. 业务层
+3. 协议层
+4. 传输层
+5. 观测与分析层
+
+对应关系如下：
+
+| 层次 | 目录/包 | 主要职责 |
+| --- | --- | --- |
+| 命令入口层 | `cmd/server` `cmd/peer` `cmd/latencysummary` | 解析参数，组装对象，启动主循环 |
+| 业务层 | `cmd/internal/server` `cmd/internal/peer` | 注册、转发、发送、接收、持久化 |
+| 协议层 | `cmd/internal/protocol` | 定义消息类型、编码解码、消息合法性校验 |
+| 传输层 | `cmd/internal/transport` | 基于 TCP 发送/接收完整消息，处理并发写和 Linux 时间戳 |
+| 观测与分析层 | `cmd/internal/latencylog` | 记录时延事件、汇总 JSONL、生成图表 |
+
+推荐把它理解为：
+
+- `protocol` 决定“消息长什么样”
+- `transport` 决定“消息怎么在 TCP 上被完整收发”
+- `server` 和 `peer` 决定“业务如何使用这些消息”
+- `latencylog` 决定“如何观察一次消息从发送到落盘经历了什么”
+
+## 4. 三个可执行程序分别做什么
+
+### 4.1 `server`
+
+入口在 `cmd/server/main.go`。
+
+它做的事情很直接：
+
+1. 解析命令行参数，比如 `-listen` 和 `-latency-log`
+2. 创建 `Hub`
+3. 监听 TCP 地址
+4. 每接受一个连接，就交给 `Hub.ServeConn` 处理
+
+`server` 自身不理解“聊天”“文件同步”之类的上层业务语义，它只知道：
+
+- 首条消息必须是 `register`
+- 已注册 `peer` 只能发送 `text` 或 `file`
+- 如果目标 `peer` 不存在，要回一个 `error`
+- 如果目标连接失效，要清理连接并回一个 `error`
+
+可以把 `server` 看成一个中心路由器。
+
+### 4.2 `peer`
+
+入口在 `cmd/peer/main.go`。
+
+它负责：
+
+1. 用 `Dial` 连接 `server`
+2. 连接建立后立刻发送 `register`
+3. 根据参数决定是否发送一条初始消息
+4. 启动接收循环
+5. 把收到的文本或文件落盘到 `inbox-dir`
+6. 如果启用了交互模式，在同一条长连接上反复发送多条消息
+
+它支持的典型模式有两种：
+
+- 一次性模式：启动后发送一条 `text` 或 `file`
+- 交互模式：启动后进入简单 REPL，持续复用同一条连接发消息
+
+### 4.3 `latencysummary`
+
+入口在 `cmd/latencysummary/main.go`。
+
+它不参与在线通信，只处理离线日志：
+
+1. 读取一个或多个原始时延 JSONL 文件
+2. 按消息聚合事件
+3. 计算多类时延指标
+4. 输出汇总 JSONL
+5. 额外输出一个 HTML 图表
+
+如果说 `server` 和 `peer` 是数据面，那么 `latencysummary` 就是观测面的离线分析工具。
+
+## 5. 核心内部模块导读
+
+### 5.1 `cmd/internal/protocol`
+
+这是协议层，决定消息的结构和线上的编码方式。
+
+#### 主要类型
+
+`Message` 是整个项目最核心的结构体，字段包括：
+
+- `Type`
+- `ID`
+- `From`
+- `To`
+- `FileName`
+- `Body`
+
+#### 支持的消息类型
+
+- `text`：正文按 UTF-8 文本解释
+- `file`：正文是原始文件字节，必须有 `FileName`
+- `register`：`peer` 向 `server` 注册身份
+- `error`：`server` 返回错误信息
+
+#### 它负责的事情
+
+- 校验不同消息类型的字段约束
+- 把结构化消息编码为字节流
+- 从字节流还原为结构化消息
+- 处理帧边界，避免 TCP 粘包/拆包问题
+
+#### 关键约束
+
+- 所有消息都必须有 `From` 和 `To`
+- `text` 不能带 `FileName`
+- `text` 的 `Body` 必须是合法 UTF-8
+- `file` 必须有 `FileName`
+- `register` 的目标必须是 `server`
+- `register` 不能带正文
+- `error` 必须由 `server` 发出
+- 单帧最大大小为 `8 * 1024 * 1024`
+
+### 5.2 `cmd/internal/transport`
+
+这是传输层，负责把协议消息稳定地跑在一条 TCP 连接上。
+
+核心类型是 `TCPConn`，它对 `net.Conn` 做了封装，提供：
+
+- `Send`
+- `Receive`
+- `ReceiveLoop`
+- `Close`
+- `CloseGracefully`
+
+#### 它解决了哪些问题
+
+- 保证发送的是一整条消息，而不是半条
+- 通过写锁避免多个 goroutine 并发写时字节流互相交错
+- 在接收侧持续读取，直到拿到完整帧
+- 在 Linux 上启用 socket timestamping，记录发送和接收链路中的内核时间戳
+
+#### Linux 相关实现
+
+`tcp_linux.go` 是这个项目比较有特色的一块。它会尝试打开 Linux 的 timestamping 能力，并记录部分关键事件，例如：
+
+- `A_TX_SCHED`
+- `A_TX_SOFTWARE`
+- `B_RX_SOFTWARE`
+
+这也是为什么项目明确写了 `Linux only`。不是只有部署目标是 Linux，而是代码本身依赖 Linux 的 socket timestamping 能力。
+
+### 5.3 `cmd/internal/server`
+
+这里只有一个核心概念：`Hub`。
+
+可以把 `Hub` 理解为“在线连接中心”，它维护：
+
+- `peer ID -> TCPConn` 的映射
+
+#### `Hub` 的主要职责
+
+- 处理新连接的注册流程
+- 拒绝未注册连接直接发业务消息
+- 拒绝重复 `peer ID`
+- 按目标 `peer ID` 查找连接并转发消息
+- 连接关闭或转发失败时清理注册表
+
+#### `Hub` 的行为边界
+
+它只负责转发和协议约束，不负责：
+
+- 业务持久化
+- 文件存储管理
+- 聊天记录管理
+- 权限控制
+
+也就是说，目前它是一个很轻量的转发中心，而不是功能复杂的消息中间件。
+
+### 5.4 `cmd/internal/peer`
+
+这个包是 `peer` 端的业务层。
+
+#### `Client`
+
+`Client` 表示一个已经连接并注册到 `server` 的节点，主要方法包括：
+
+- `Dial`
+- `SendText`
+- `SendFile`
+- `SendFilePath`
+- `Receive`
+- `ReceiveLoop`
+- `PersistMessage`
+- `Close`
+
+#### 它负责的事情
+
+- 建立到 `server` 的 TCP 连接
+- 发送 `register` 完成身份注册
+- 为业务消息分配自增 `MessageID`
+- 发送文本消息和文件消息
+- 接收来自 `server` 的转发消息或错误消息
+- 把收到的业务消息落盘
+
+#### 持久化策略
+
+接收侧落盘逻辑在 `persist.go`：
+
+- 文本消息会被追加到 `messages.log`
+- 文件消息会被写成单独文件
+- 文件名格式是：`<from>-<messageID>-<baseFileName>`
+
+这样做的好处是：
+
+- 文本消息便于顺序追踪
+- 文件消息天然避免覆盖
+- 文件名里直接带了来源和消息 ID，方便回溯
+
+#### 网络绑定能力
+
+`peer` 还支持：
+
+- `-bind-ip`：指定本地源 IP
+- `-bind-device`：指定 Linux 网络设备，例如 `eth0`、`wwan0`
+
+这对多网卡环境或特殊链路测试比较有用。
+
+### 5.5 `cmd/internal/latencylog`
+
+这个包负责“记录”和“分析”两件事。
+
+#### 记录侧
+
+`logger.go` 定义了：
+
+- `Event`
+- `Logger`
+- `JSONLLogger`
+- 一组 `LogMessageEvent` / `LogMessageEventAt` 辅助函数
+
+当前业务上最重要的事件有：
+
+- `A_APP_PREP_BEGIN`
+- `A_TX_SCHED`
+- `A_TX_SOFTWARE`
+- `B_RX_SOFTWARE`
+- `B_APP_RECV`
+- `B_PERSIST_BEGIN`
+- `B_PERSIST_END`
+
+其中：
+
+- `A_*` 表示发送侧
+- `B_*` 表示接收侧
+- `TX/RX` 更偏内核或传输链路
+- `APP/PERSIST` 更偏应用层
+
+#### 分析侧
+
+`summary.go` 会把原始事件按消息聚合，并计算：
+
+- `AProcessingLatencyNS`
+- `AQueueLatencyNS`
+- `ABTransportPropagationNS`
+- `BKernelReceivePathLatencyNS`
+- `BProcessingLatencyNS`
+- `EndToEndLatencyNS`
+- `ApproxRTTNS`
+
+`summary_chart.go` 则把这些摘要结果渲染成 HTML 页面，方便快速观察不同消息的时延分布。
+
+## 6. 核心消息流
+
+这一节按一次完整消息生命周期来梳理。
+
+### 6.1 连接与注册
+
+1. `peer` 启动后调用 `Dial(serverAddr, peerID, ...)`
+2. 底层建立 TCP 连接
+3. `peer` 立刻发送一条 `register` 消息
+4. `server` 的 `Hub.ServeConn` 先读取首条消息
+5. 如果首条消息不是 `register`，连接会被拒绝
+6. 如果 `peer ID` 重复，连接会被拒绝并收到 `error`
+7. 注册成功后，`Hub` 把该连接加入在线表
+
+注册阶段决定了后续所有转发的寻址基础。
+
+### 6.2 发送文本或文件
+
+发送侧调用：
+
+- `SendText(to, body)` 或
+- `SendFile(to, fileName, body)` 或
+- `SendFilePath(to, path)`
+
+发送前会生成新的 `MessageID`，然后：
+
+1. 记录发送前的应用层事件 `A_APP_PREP_BEGIN`
+2. 交给 `transport.TCPConn.Send`
+3. `transport` 调用协议层编码
+4. 编码后的消息被写入 TCP 连接
+5. Linux 侧尽量采集 `A_TX_SCHED` 和 `A_TX_SOFTWARE`
+
+### 6.3 `server` 转发
+
+`server` 收到消息后：
+
+1. 确认消息类型只能是 `text` 或 `file`
+2. 强制把 `msg.From` 改成当前已注册的 `peer ID`
+3. 通过 `msg.To` 查找目标连接
+4. 找不到目标时返回 `error`
+5. 找到目标就直接转发
+
+这里有一个重要细节：`server` 不信任客户端自己填写的 `From`。即使发送端伪造了 `From`，`Hub` 也会用实际注册身份覆盖它。
+
+### 6.4 接收与落盘
+
+接收侧 `peer` 的接收循环拿到消息后：
+
+1. `transport` 在 Linux 下尝试记录 `B_RX_SOFTWARE`
+2. `Client.Receive` / `ReceiveLoop` 记录 `B_APP_RECV`
+3. 根据消息类型调用 `PersistMessage`
+4. 持久化开始时记录 `B_PERSIST_BEGIN`
+5. 写盘完成后记录 `B_PERSIST_END`
+
+因此，一条业务消息从“发送端开始准备”到“接收端落盘完成”形成了相对完整的一条时延链路。
+
+### 6.5 时延日志汇总
+
+后处理阶段由 `latencysummary` 完成：
+
+1. 用一个或多个 `-input` 指定原始 JSONL 日志
+2. 加载所有事件
+3. 按消息聚合
+4. 计算摘要时延
+5. 输出一个汇总 JSONL
+6. 按输出文件名自动生成一个同名 HTML 图表
+
+## 7. 协议说明
+
+### 7.1 消息结构
+
+业务层统一使用 `protocol.Message`：
+
+```text
+Type / ID / From / To / FileName / Body
+```
+
+其中：
+
+- `FileName` 仅对 `file` 消息有意义
+- `Body` 不进入 header JSON，而是作为二进制正文附加在后面
+
+### 7.2 TCP 上传输的帧格式
+
+从 TCP 视角，完整格式可以理解为：
+
+```text
+[4-byte frameLength][4-byte headerLen][header JSON][body bytes]
+```
+
+更细一点说：
+
+- `WriteFrame` 负责最外层的 `frameLength`
+- `EncodeMessage` 负责 payload 内部的 `headerLen + header JSON + body`
+
+这样做的目的很明确：TCP 是字节流，不天然保留消息边界，所以要自己在协议层补齐边界信息。
+
+### 7.3 错误语义
+
+当前协议里的错误消息由 `server` 发送，类型是 `error`。常见场景包括：
+
+- 首条消息不是 `register`
+- 重复注册相同 `peer ID`
+- 已注册 `peer` 再次发送 `register`
+- 目标 `peer` 不存在
+- 发送了不支持的消息类型
+
+从设计上看，`error` 仍然走同一条消息通道，而不是额外开一个控制通道。
+
+## 8. 时延日志机制
+
+### 8.1 为什么项目里有这套日志
+
+这个仓库不只是做“能发消息”，还明显在关注消息经过网络栈时的细粒度时延。尤其是：
+
+- 应用层开始准备消息的时间
+- 消息进入发送调度队列的时间
+- 消息进入软件发送路径的时间
+- 接收侧内核把数据交给协议栈的时间
+- 接收侧应用真正读到消息的时间
+- 接收侧写盘完成的时间
+
+这些点能帮助区分：
+
+- 应用侧处理慢
+- 发送侧排队慢
+- 网络传输慢
+- 接收侧内核路径慢
+- 接收侧持久化慢
+
+### 8.2 当前谁在打点
+
+当前实际打点来源主要有两类：
+
+- `peer` 应用层：发送、接收、持久化
+- `transport` 传输层：Linux kernel timestamping
+
+`server` 代码里保留了 `WithLogger` 和 `-latency-log` 相关入口，但当前实现仍然把 `server` 视为黑盒转发器，不主动为转发过程写入业务级端到端事件。这一点从现有测试也能看出来：服务端转发路径默认不产出这类事件。
+
+### 8.3 汇总结果怎么看
+
+`latencysummary` 输出的摘要结果按“单条消息”聚合。阅读时可以重点看：
+
+- `EndToEndLatencyNS`：从发送侧准备开始到接收侧写盘完成
+- `AQueueLatencyNS`：发送端从进入调度到真正进入软件发送路径
+- `ABTransportPropagationNS`：从发送侧真正发出到接收侧应用读到
+- `BProcessingLatencyNS`：接收端应用读到后到写盘完成
+
+如果某些事件缺失，摘要里会带 `MissingTimestamps`，告诉你少了哪些关键时间点。
+
+## 9. 运行与调试补充
+
+### 9.1 构建入口
+
+按 `README.md` 当前给出的方式，主要构建命令是：
+
+```bash
+go build -o bin/server ./cmd/server
+go build -o bin/peer ./cmd/peer
+go build -o bin/latencysummary ./cmd/latencysummary
+```
+
+也可以按不同 Linux 架构交叉编译。
+
+### 9.2 `server` 常用参数
+
+- `-listen`：监听地址，默认 `:9000`
+- `-latency-log`：原始时延 JSONL 输出路径
+
+### 9.3 `peer` 常用参数
+
+- `-id`：当前节点 ID
+- `-server`：服务端地址
+- `-to`：一次性发送时的目标 `peer`
+- `-text`：一次性发送文本
+- `-file`：一次性发送文件
+- `-inbox-dir`：接收内容的落盘目录
+- `-bind-ip`：本地源 IP
+- `-bind-device`：本地网络设备
+- `-latency-log`：原始时延 JSONL 输出路径
+- `-interactive`：是否启用交互式 REPL，默认开启
+
+### 9.4 交互命令
+
+交互模式支持：
+
+```text
+help
+text <peer> <message>
+file <peer> <path>
+quit
+```
+
+这让你可以在同一条长连接上连续发送多次，而不用每发一条消息就重启一次进程。
+
+### 9.5 Linux-only 限制
+
+这个项目应当被当作 Linux 项目来理解。
+
+需要注意两层含义：
+
+- 部署目标是 Linux
+- 代码实现也依赖 Linux 特性
+
+在当前 Windows 环境下执行 `go test ./...`，会因为 `cmd/internal/transport` 中的 Linux 专属实现而构建失败。这属于平台限制，不代表仓库当前代码损坏。换句话说，这个失败更接近“当前平台不支持这套实现”，而不是“代码逻辑错误”。
+
+## 10. 推荐阅读顺序
+
+如果你刚接手项目，建议按下面顺序读：
+
+1. `README.md`
+2. `cmd/server/main.go`
+3. `cmd/peer/main.go`
+4. `cmd/internal/protocol/message.go`
+5. `cmd/internal/protocol/codec.go`
+6. `cmd/internal/transport/tcp.go`
+7. `cmd/internal/transport/tcp_linux.go`
+8. `cmd/internal/server/hub.go`
+9. `cmd/internal/peer/client.go`
+10. `cmd/internal/peer/persist.go`
+11. `cmd/internal/latencylog/logger.go`
+12. `cmd/internal/latencylog/summary.go`
+13. `cmd/internal/latencylog/summary_chart.go`
+
+这样阅读的好处是：
+
+- 先知道程序怎么启动
+- 再知道消息长什么样
+- 再知道消息怎么传
+- 再知道服务端和客户端各自做什么
+- 最后再看时延观测和分析
+
+## 11. 你接手后最值得先记住的几件事
+
+- 这是一个“中心转发”的系统，不是 `peer` 直连。
+- `register` 是连接建立后的第一条消息，缺了它后续都不成立。
+- `server` 会用已注册身份覆盖消息里的 `From`，不会信任客户端自报身份。
+- 文本消息和文件消息共享同一套协议，只是约束不同。
+- `transport` 不只是收发 TCP，还承担 Linux 时间戳采集。
+- 接收侧持久化是 `peer` 的职责，不是 `server` 的职责。
+- `latencysummary` 是离线分析工具，不在在线转发链路里。
+
+如果后续你准备改协议、改传输层，或者新增消息类型，建议先把 `protocol -> transport -> peer/server -> latencylog` 这一整条链路一起过一遍，再开始动代码。