bcap/README.md

# bcap

`bcap` 是一个轻量的 Go 报文解析库，重点提供两类能力：

- 统一提取报文事实
- 基于连续报文输出轻量协议提示

它适合作为抓包工具、离线诊断工具、CLI/TUI 浏览器的底层解析层，但并不试图替代完整协议栈、深度重组引擎或最终用户报告系统。

## 1. 核心定位

`bcap` 主包当前围绕 3 个对象展开：

- `Decoder`
  - 无状态，只负责单包解码，输出 `Packet`
- `Tracker`
  - 有状态，只负责基于连续报文做轻量跟踪，输出 `Observation`
- `Analyzer`
  - `Decoder + Tracker` 的组合入口，适合大多数直接接入场景

分工可以直接理解为：

- `Decoder` 负责单包事实
- `Tracker` 负责跨包提示
- `Analyzer` 负责把两者串起来

## 2. 适用场景

`bcap` 主要适合：

- 在线抓包后的统一元数据提取
- 离线 pcap 遍历分析
- TCP/UDP/ICMP/ARP 的统一识别
- TCP 关键行为提示，例如握手、挥手、重传、keepalive、RST

`bcap` 不直接负责：

- 诊断结论生成
- CLI/TUI 文案
- Excel / JSON / 报告拼装
- 动作编排与干预逻辑
- 工具侧业务状态缓存

## 3. 快速开始

安装：

```bash
go get b612.me/bcap
```

最常见的接入方式是直接使用 `Analyzer`：

```go
package main

import (
	"fmt"

	"b612.me/bcap"
	"github.com/gopacket/gopacket"
)

func consume(packet gopacket.Packet) error {
	analyzer := bcap.NewAnalyzer()
	defer analyzer.Stop()

	obs, err := analyzer.ObservePacket(packet)
	if err != nil {
		return err
	}

	fmt.Println("flow:", obs.Flow.Stable)
	fmt.Println("protocol:", obs.Packet.Transport.Kind)
	fmt.Println("summary:", obs.Hints.Summary.Code)

	if obs.Hints.TCP != nil {
		fmt.Println("tcp event:", obs.Hints.TCP.Event)
	}
	return nil
}
```

如果你需要自行控制“解码”和“跟踪”两个阶段，也可以拆开使用：

```go
decoder := bcap.NewDecoder()
tracker := bcap.NewTracker()
defer tracker.Stop()

decoded, err := decoder.Decode(packet)
if err != nil {
	return err
}

obs, err := tracker.Observe(decoded)
if err != nil {
	return err
}
```

## 4. 支持范围

当前主包支持的主要识别范围：

- 链路层
  - `Ethernet`
  - `Linux SLL`
  - `Linux SLL2`
- 网络层
  - `IPv4`
  - `IPv6`
  - `ARP`
- 传输层 / 协议层
  - `TCP`
  - `UDP`
  - `ICMPv4`
  - `ICMPv6`
  - `Unknown`

当前 TCP 轻量提示重点覆盖：

- 三次握手
- 四次挥手
- 普通 ACK
- 重传
- keepalive
- keepalive response
- RST
- ECE / CWR

## 5. 如何选接口

优先级建议：

- 大多数工具直接用 `Analyzer`
- 只要报文事实时用 `Decoder`
- 你已经有自己的输入管线，只缺轻量状态跟踪时用 `Tracker`

如果没有特殊理由，优先选择 `Analyzer`，接入成本最低。

## 6. 包结构

### 6.1 主包 `b612.me/bcap`

负责：

- 统一事实模型
- 统一 flow 模型
- 统一 hint 模型
- 轻量 TCP 跟踪

### 6.2 子包 `libpcap`

负责：

- 基于 pcap 的抓包输入适配

### 6.3 子包 `nfq`

负责：

- 基于 NFQUEUE 的输入适配

通常的组合方式是：

- `libpcap` / `nfq` 提供输入
- `bcap.Analyzer` 负责解析与提示
- 上层工具负责展示、统计、导出和策略

## 7. 文档导航

如果你只是要快速接入，看本 README 基本够用。

如果你要看完整 API、模型字段、配置项和迁移说明，请继续阅读：

- [`doc/api.md`](./doc/api.md)

如果你要看当前架构思路和设计边界，请看：

- [`doc/dev.md`](./doc/dev.md)

## 8. 迁移提示

`bcap` 主包已经移除了旧的胖接口，旧的以下模型不再推荐使用，并且主体已经删除：

- `Packets`
- `PacketInfo`
- `ParsePacket`
- `NewPackets`
- `NewPacketsWithConfig`
- `LegacyPacketInfoFromObservation`
- `GetStateDescription`
- `PrintStats`
- `ExportConnectionsToJSON`

新的迁移方向是：

- 单包事实解析改用 `Decoder`
- 报文观察结果改用 `Observation`
- TCP 轻量状态识别改用 `Tracker`
- 大多数场景直接改用 `Analyzer`

## 9. 测试

开发或改动后，至少建议执行：

```bash
go test ./...
```

## 10. License

本项目采用 Apache License 2.0。

完整协议文本见：

- [`LICENSE`](./LICENSE)