notify/README.md

# notify

`b612.me/notify` 是一个面向点对点直连场景的 Go 通信基础包，覆盖消息信令、流式传输、批量数据通道和文件传输内核能力。

## 模块定位

- 消息面：`Send`、`SendWait`、`Reply`、`SetLink`
- 流式数据面：`OpenStream`
- 记录流数据面：`OpenRecordStream`
- 批量数据面：`OpenBulk`（`shared` / `dedicated`）
- 文件传输内核：transfer control / progress / resume
- 观测面：runtime snapshot / diagnostics summary
- 会话模型：`LogicalConn`（逻辑会话）与 `TransportConn`（物理承载）分离

## 版本要求

- Go `1.24+`

## 安全初始化要求

`Client` / `Server` 在 `Connect` / `Listen` 前必须完成安全配置。默认使用现代 PSK 方案。

- 客户端：`UseModernPSKClient`
- 服务端：`UseModernPSKServer`

未配置时会返回 `errModernPSKRequired`。

## 快速开始

服务端：

```go
package main

import (
	"log"

	"b612.me/notify"
)

func main() {
	srv := notify.NewServer()
	if err := notify.UseModernPSKServer(srv, []byte("shared-secret"), nil); err != nil {
		log.Fatal(err)
	}
	srv.SetLink("ping", func(msg *notify.Message) {
		_ = msg.Reply([]byte("pong"))
	})
	if err := srv.Listen("tcp", "127.0.0.1:28080"); err != nil {
		log.Fatal(err)
	}
	select {}
}
```

客户端：

```go
package main

import (
	"log"
	"time"

	"b612.me/notify"
)

func main() {
	cli := notify.NewClient()
	if err := notify.UseModernPSKClient(cli, []byte("shared-secret"), nil); err != nil {
		log.Fatal(err)
	}
	if err := cli.Connect("tcp", "127.0.0.1:28080"); err != nil {
		log.Fatal(err)
	}
	defer cli.Stop()

	reply, err := cli.SendWait("ping", []byte("hello"), 5*time.Second)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("reply=%s", string(reply.Value))
}
```

## RecordStream 说明

`RecordStream` 构建在 `Stream` 之上，适合“有边界的顺序记录”场景。

- 写入入口：`OpenRecordStream`、`WriteRecord`
- 接收入口：`ReadRecord`
- 确认入口：`AckRecord`
- 检查点：`Barrier`、`BarrierTo`
- 错误回包：`RecordFailure`

确认语义：

- `AckRecord` 表示“该序号及其之前的连续记录已完成 apply”，不是“已收到”
- `Barrier` / `BarrierTo` 等待的是对端 `apply-complete` 的最大连续序号
- `RecordFailure` 会返回 `FailedSeq`、`Code`、`Retryable`、`Message`

兼容与传输：

- record stream 在打开阶段协商 batch ack 能力
- 双端都支持时，累计 `AckSeq` 会随 batch header piggyback 发送
- 对端不支持时，自动回退到独立 ack frame
- mixed-version peer 可以互通，不要求双方同时升级

## 诊断快照

顶层诊断入口：

- `GetClientDiagnosticsSnapshot`
- `GetServerDiagnosticsSnapshot`

快照内容：

- 会话运行态：client / server runtime
- 数据面快照：`StreamSnapshot`、`BulkSnapshot`、`RecordSnapshot`
- 文件传输快照：`TransferSnapshot`
- 汇总视图：`DiagnosticsSummary`

`RecordSnapshot` / `DiagnosticsSummary.RecordTelemetry` 当前覆盖：

- batch / ack / error frame 收发计数
- piggyback ack 命中计数
- barrier 等待时间拆分：`flush` / `apply`
- `outstanding records/bytes`
- `pending apply / pending ack / peak pending apply`

## 传输与 IPC

- `tcp`
- `udp`
- `unix`
- `npipe`（Windows）

示例目录：

- [examples/signal](/mnt/c/coding/gocode/src/b612.me/notify/examples/signal)

## 现代 PSK 与兼容入口

现代方案特性：

- 共享密钥派生（Argon2id）
- 消息层加密（AES-GCM）
- `stream` / `bulk` fast path 复用现代编码栈

兼容入口仍保留，但属于历史路径：

- `UseLegacySecurityClient`
- `UseLegacySecurityServer`
- `ExchangeKey`
- `SetSecretKey`
- `SetMsgEn` / `SetMsgDe`

## 发布前检查

```bash
export SENTRUX_SKIP_GRAMMAR_DOWNLOAD='1'
sentrux check .
env GOCACHE=/tmp/b612-gocache GOMODCACHE=/tmp/b612-gomodcache go test ./...
env GOCACHE=/tmp/b612-gocache GOMODCACHE=/tmp/b612-gomodcache go test -race ./...
env GOCACHE=/tmp/b612-gocache GOMODCACHE=/tmp/b612-gomodcache go vet ./...
```

手工 soak 测试（可选）：

```bash
env GOCACHE=/tmp/b612-gocache GOMODCACHE=/tmp/b612-gomodcache \
go test -tags notify_manual_soak -run 'Test_ServerTuAndClientCommon|Test_normal|Test_normal_udp'
```

## 兼容性说明

- 对外主入口保留：`NewClient`、`NewServer`、`Connect`、`Listen`、`SetLink`、`SetDefaultLink`、`Send`、`SendWait`、`SendObj`、`Reply`、`Stop`
- 内部主对象已迁移为 `LogicalConn` / `TransportConn`
- `ClientConn` 作为兼容适配层继续保留