bcap/doc/dev.md

# bcap 开发设计备忘

## 1. 这次重构的前提

当前已确认，直接使用 `bcap` 主包的范围很小，主要只有：

- `apps/tcp`
- `apps/b612` 中的 `tcm`
- `apps/b612` 中的 `tcpkill`

因此这次讨论 `bcap` 新架构时，可以明确采用以下前提：

1. 可以摒弃旧接口，不必为了兼容历史调用持续背负旧模型。
2. `bcap` 子包暂时不动，尤其是 `libpcap`、`nfq` 这类输入适配层先保持现状。
3. 重点只讨论 `bcap` 主包的新职责、新模型和新接口。

## 2. 当前主包存在的问题

当前 `bcap` 主包中，`Packets`、`PacketInfo`、`StateDescript` 这一套模型混合了承担以下几类职责：

- 报文事实解码
- TCP 状态推断
- 连接状态缓存
- 统计汇总
- 工具侧临时状态寄存
- 文本格式化辅助

这几个职责混在一起，直接导致了以下问题：

### 2.1 `PacketInfo` 同时承载“事实”和“推断”

例如：

- `SrcIP`、`DstIP`、`SrcMac`、`DstMac` 属于原始事实
- `TcpSeq`、`TcpAck`、`TcpWindow` 虽然也是事实，但只适用于 TCP
- `StateDescript` 则是推断结果
- `Comment` 又是工具业务的临时状态

这会让上层调用方无法区分：哪些字段是包里本来就有的，哪些字段是状态机推出来的，哪些字段甚至只是上层工具临时借位存进去的。

### 2.2 主包过于 TCP 化

当前主模型的核心字段和访问器明显偏向 TCP：

- `TcpSeq()`
- `TcpAck()`
- `TcpWindow()`
- `TcpPayloads()`
- `StateDescript()`

虽然已经开始支持 UDP、ICMP、ICMPv6，但整体接口风格仍然默认“TCP 才是主角，其他协议只是附带”。如果目标是做“通用 transport/protocol hint”，这个建模方式会持续妨碍扩展。

### 2.3 `Packets` 同时是解析器、状态仓库和工具 scratchpad

当前 `Packets` 既负责：

- 解析 gopacket.Packet
- 保存连接状态
- 维护统计
- 暴露 `Key()` 查询
- 暴露 `SetComment()` 给上层写入工具状态

这实际上把“协议解析层”和“工具业务状态层”耦死了。

### 2.4 字符串 key 被当成核心接口

当前以 `tcp://a:b-c:d` 这类字符串 key 作为主要流标识，这虽然方便快速实现，但不适合作为长期公共接口。

问题包括：

- 协议语义不够结构化
- 上层反复自行拼 key
- 不利于未来支持可逆 flow、单向 packet、无端口协议、ARP 等场景

### 2.5 文本格式化与 JSON 导出混入主包

像 `GetStateDescription`、`PrintStats`、`ExportConnectionsToJSON` 这种能力，不属于主包核心解析模型，应该降级为上层工具职责，或者至少转到辅助层，而不是继续成为主接口的一部分。

## 3. 新架构的总体目标

`bcap` 主包应收敛成：

- 一个统一的报文事实解码层
- 一个统一的协议 hint 推断层
- 一个以 TCP 为重点的轻量状态跟踪层

同时明确边界：

### 3.1 `bcap` 应负责的事

- 识别链路层、网络层、传输层协议
- 提取结构化元数据
- 输出通用 protocol hint
- 对 TCP 做轻状态推断
- 对 UDP/ICMP/ARP 做协议识别和元数据抽取
- 对未知协议输出“尽量完整的基础事实”

### 3.2 `bcap` 不应负责的事

- 诊断报告拼装
- 干预动作编排
- CLI/TUI 展示文案
- 工具侧临时状态寄存
- 业务策略倒计时
- 面向最终用户的统计打印

也就是说，`bcap` 的定位应是“提供事实和提示”，而不是“替工具做决策”。

## 4. 新架构的核心分层

建议主包收敛成 3 个核心对象：

1. `Decoder`
2. `Tracker`
3. `Analyzer`

### 4.1 `Decoder`

`Decoder` 是无状态组件，只负责把 `gopacket.Packet` 解码成结构化“事实”。

职责：

- 识别 L2/L3/L4 协议
- 抽取 MAC、IP、端口、TTL、flags、payload 长度等事实
- 不做跨包状态推断
- 不维护连接表
- 不暴露工具业务状态

### 4.2 `Tracker`

`Tracker` 是有状态组件，只负责基于连续观测结果做轻量 hint 推断。

职责：

- 维护按 flow 组织的轻状态
- 针对 TCP 输出握手、挥手、重传、keepalive、RST 等 hint
- 针对 ICMP/ARP 等协议补充轻量语义标签
- 不负责最终展示
- 不负责业务动作控制

### 4.3 `Analyzer`

`Analyzer` 是便捷组合层，内部持有 `Decoder + Tracker`，给上层一个简单入口。

典型用途：

- `tcm` / `tcml` 这种一边收包一边展示的工具
- `diag` 这种离线分析工具
- `show` 这种需要 packet facts + hints 的浏览工具

这样设计后：

- 只关心事实解码的调用方可直接用 `Decoder`
- 需要 hint 的调用方可用 `Analyzer`
- 需要更细粒度控制的调用方可分别持有 `Decoder` 和 `Tracker`

## 5. 新的数据模型

新模型建议明确拆成“事实”和“推断”两层。

### 5.1 第一层：Packet Facts

建议定义统一的结构化事实模型，例如：

```go
type Packet struct {
    Meta      Meta
    Link      LinkFacts
    Network   NetworkFacts
    Transport TransportFacts
    Raw       RawFacts
}
```

其中：

- `Meta`：时间戳、捕获长度、原始长度、相对时间等
- `LinkFacts`：链路层类型、源/目标 MAC、链路层协议等
- `NetworkFacts`：IPv4/IPv6/ARP 等信息，包含地址、TTL/HopLimit、fragment、protocol number 等
- `TransportFacts`：TCP/UDP/ICMP/unknown 等结构化内容
- `RawFacts`：payload 长度、原始 packet 引用等

这层全部表示“包里本来就有”的事实，不包含推断结论。

### 5.2 第二层：Observation

建议把“经过跟踪器分析后的结果”定义为单独对象：

```go
type Observation struct {
    Packet Packet
    Flow   FlowRef
    Hints  HintSet
}
```

这里：

- `Packet` 是原始事实
- `Flow` 是结构化流引用
- `Hints` 是推断结果

### 5.3 FlowKey / FlowRef

建议引入结构化 flow 标识，而不是继续把字符串 key 作为主接口。

```go
type FlowKey struct {
    Family   NetworkFamily
    Protocol TransportKind
    Src      Endpoint
    Dst      Endpoint
}

type FlowRef struct {
    Forward FlowKey
    Reverse FlowKey
    Stable  string
}
```

其中：

- `Forward` / `Reverse` 提供方向化 key
- `Stable` 可以保留字符串形式，方便日志、map key、兼容旧调试习惯
- `Endpoint` 应允许“只有地址没有端口”的协议

### 5.4 HintSet

建议将所有推断信息挂在 `HintSet` 上：

```go
type HintSet struct {
    Summary SummaryHint
    Tags    []Tag

    TCP  *TCPHint
    UDP  *UDPHint
    ICMP *ICMPHint
    ARP  *ARPHint
}
```

这样做的好处是：

- `Summary` 提供给 `tcm/tcml` 这类工具快速展示一句话
- `Tags` 提供统一筛选、着色、统计能力
- 协议专属 hint 由独立结构体承载，不再污染通用顶层对象

## 6. 协议专属 hint 的建议形态

### 6.1 `TCPHint`

`TCPHint` 是新架构里的重点能力，建议承载：

- seq / ack / window
- flags
- payload length
- options 摘要
- handshake / teardown 阶段
- retransmission 判定
- keepalive 判定
- keepalive response 判定
- rst / ece / cwr 等特殊标记
- 是否疑似 out-of-order

同时建议把原来的 `StateDescript uint8` 弃用，改成更结构化的字段或 tag，例如：

- `Phase: TCPPhase`
- `Event: TCPEvent`
- `Tags: []Tag`

### 6.2 `UDPHint`

UDP 先做轻支持即可，建议包括：

- payload length
- checksum presence / checksum value
- zero-length payload
- fragment 上下文关联信息（如果网络层提供）

不建议在主包内直接引入 DNS、QUIC 等应用层推断，除非后续确认收益足够大。

### 6.3 `ICMPHint`

建议至少包括：

- family: v4 / v6
- type / code
- id / seq
- 是否 echo request / echo reply
- 是否 destination unreachable / time exceeded

这层对 `show` 和 `tcm/tcml` 的“多协议展示”已经足够有价值。

### 6.4 `ARPHint`

如果目标是支持“展示其他协议”，ARP 必须成为一等公民。

建议至少包括：

- operation
- sender MAC / sender IP
- target MAC / target IP
- request / reply tag

同时 `Decoder` 对 ARP 不应再因为没有 `NetworkLayer()` 而直接报错。

## 7. 标签体系建议

建议在主包内定义统一 tag 体系，供所有上层工具复用。

例如：

- `tcp.handshake.syn`
- `tcp.handshake.synack`
- `tcp.handshake.ack`
- `tcp.teardown.fin`
- `tcp.keepalive`
- `tcp.keepalive.response`
- `tcp.retransmit`
- `tcp.rst`
- `tcp.ece`
- `tcp.cwr`
- `udp.packet`
- `icmp.echo-request`
- `icmp.echo-reply`
- `icmp.unreachable`
- `arp.request`
- `arp.reply`
- `transport.unknown`

这比继续依赖一个不断膨胀的 `StateDescript` 枚举更稳。

## 8. 状态与并发语义

这是新架构里必须提前定死的部分。

### 8.1 `Decoder` 的并发语义

`Decoder` 无状态，应明确支持并发使用。

### 8.2 `Tracker` 的并发语义

`Tracker` 有状态，应明确：

- 同一 flow 的观测结果必须按顺序输入
- 允许多 flow 并发，但内部状态更新语义以 flow 顺序为准
- 如果调用方无法保证顺序，则 hint 结果可能退化

这点非常重要。当前的 `shardedMap` 只能提供 map 级线程安全，不能自动提供时序正确性。TCP hint 尤其依赖时序，因此新接口必须把这一点写进设计，而不是默认调用方自己猜。

### 8.3 工具侧临时状态必须外移

例如 `tcml` 的：

- delay countdown
- block / allow 状态
- 业务关键字命中后的动作状态

都不应再借用 `Comment/SetComment` 写进 `bcap` 状态仓库。

新架构里，`Tracker` 只维护协议分析所需状态，不维护工具策略状态。

## 9. 错误模型建议

建议错误也按层次整理：

- 解码失败
- 支持范围外
- 协议字段损坏
- 状态推断降级

同时要允许“部分可用”的结果。

例如：

- 能识别到 IPv4，但 transport 未识别
- 能识别到 ARP，但字段不完整
- 能拿到 TCP flags，但因为缺少上下文无法判定 retransmit

这种情况下应尽量返回事实层结果，而不是简单整体失败。

## 10. 主包不再保留的旧概念

建议在新架构中明确移除或降级以下旧概念：

- `PacketInfo`
- `Packets`
- `StateDescript()`
- `Comment()` / `SetComment()`
- `GetStateDescription()`
- `PrintStats()`
- `ExportConnectionsToJSON()`
- 各类以字符串 key 作为核心接口的模型

原因是：

- `PacketInfo` 混杂事实、推断和业务临时状态
- `Packets` 角色过多，不适合作为长期主对象
- `StateDescript` 无法优雅承载多协议 hint
- `Comment/SetComment` 明显越界
- 格式化和导出不应继续作为主包核心能力

## 11. 建议的新接口形态

建议主包至少提供两层使用方式。

### 11.1 低层接口

```go
decoder := bcap.NewDecoder(opts)
pkt, err := decoder.Decode(gpkt)

tracker := bcap.NewTracker(opts)
obs, err := tracker.Observe(pkt)
```

适合：

- 想分别控制解码与跟踪的调用方
- 想单测某一层的调用方
- 想把事实层和 hint 层分开使用的工具

### 11.2 便捷接口

```go
analyzer := bcap.NewAnalyzer(opts)
obs, err := analyzer.ObservePacket(gpkt)
```

适合：

- `tcm`
- `tcml`
- `diag`
- `show`

这类工具大多要的是“输入 gopacket.Packet，得到事实 + hint”。

## 12. 对现有调用方的迁移影响

### 12.1 `tcpkill`

迁移成本最低。

它主要只需要：

- TCP 四元组
- seq / ack / window
- MAC

因此它可以优先迁移到：

- `Decoder`
- 或 `Analyzer` 中的 `Observation.Packet + Observation.Hints.TCP`

### 12.2 `tcm` / `tcml`

迁移重点在展示层。

它们当前主要依赖：

- `StateDescript`
- `TcpSeq/TcpAck/TcpWindow/TcpPayloads`
- `Key/ReverseKey`
- `Comment/SetComment`

迁移后应改成：

- 用 `Observation.Hints.Summary` 或 `Tags` 做展示语义
- 用结构化 `FlowRef` 替代字符串 key 拼接
- 将 `tcml` 的动作状态迁出 `bcap`

### 12.3 `diag`

`diag` 会受益最大。

它本质上就是一个消费“事实 + hint”的离线分析器。等 `bcap` 能稳定输出结构化 TCP/ICMP/ARP/UDP hint 后，`diag` 内部很多启发式逻辑会更容易表达，也更少依赖旧的 TCP 枚举状态。

## 13. 与子包的边界

本次先不动子包，但应明确子包定位：

- `libpcap`：抓包输入适配层
- `nfq`：NFQUEUE 输入适配层

它们不属于主模型核心，只是 `gopacket.Packet` 的来源适配。

换句话说：

- `bcap` 主包定义“如何理解 packet”
- 子包定义“packet 从哪里来”

这个边界应该长期保持稳定。

## 14. 当前结论

如果重做 `bcap` 主包，最合理的方向是：

1. 主包已经从 `Packets/PacketInfo` 旧模型切换到 `Decoder/Tracker/Analyzer` 新模型。
2. 明确分离“报文事实”和“推断 hint”。
3. 引入结构化 `FlowKey/FlowRef`，不再把字符串 key 作为主接口。
4. 用 `HintSet + Tags + protocol-specific hints` 取代 `StateDescript`。
5. 删除 `Comment/SetComment` 这类工具业务越界能力。
6. 让 `bcap` 成为“轻量协议事实 + hint 提供层”，而不是“工具状态仓库”。

## 15. 推荐的实施顺序

建议真正开始改实现时，按下面顺序推进：

1. 先定义新的公共类型草图：`Packet`、`Observation`、`FlowKey`、`HintSet`、`TCPHint`、`ICMPHint`、`ARPHint`。
2. 再实现无状态 `Decoder`，保证多协议事实提取完整。
3. 再实现有状态 `Tracker`，先把 TCP hint 迁进去。
4. 再提供 `Analyzer` 便捷入口。
5. 最后再让 `apps/tcp` 和 `apps/b612` 的调用方迁到新接口，并删除旧兼容 facade。

在这个顺序下，主架构会先稳定下来，后续迁移也更可控。