starainrt
7ed3dd5b37
- 将 RecordStream 出站路径收敛为单 writer loop - 支持在 batch header 中 piggyback AckSeq，保留独立 ack 作为兼容回退 - 增加 record stream 打开阶段能力协商，支持 mixed-version peer 自动降级 - 补充 RecordSnapshot 与 diagnostics summary 的 record-plane 观测项 - 增加 batch/ack/error frame、piggyback ack、barrier 等待拆分与 apply backlog 指标 - 收紧 TransportConn detach 后的 runtime snapshot 语义 - 补充 README 中的 RecordStream 语义、兼容行为与诊断快照说明 - 补充相关单测与 race 回归验证
4.4 KiB
4.4 KiB
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。
快速开始
服务端：
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 {}
}
客户端：
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 可以互通，不要求双方同时升级
诊断快照
顶层诊断入口：
GetClientDiagnosticsSnapshotGetServerDiagnosticsSnapshot
快照内容：
- 会话运行态：client / server runtime
- 数据面快照：
StreamSnapshot、BulkSnapshot、RecordSnapshot - 文件传输快照：
TransferSnapshot - 汇总视图：
DiagnosticsSummary
RecordSnapshot / DiagnosticsSummary.RecordTelemetry 当前覆盖：
- batch / ack / error frame 收发计数
- piggyback ack 命中计数
- barrier 等待时间拆分：
flush/apply outstanding records/bytespending apply / pending ack / peak pending apply
传输与 IPC
tcpudpunixnpipe（Windows）
示例目录：
现代 PSK 与兼容入口
现代方案特性：
- 共享密钥派生（Argon2id）
- 消息层加密（AES-GCM）
stream/bulkfast path 复用现代编码栈
兼容入口仍保留，但属于历史路径：
UseLegacySecurityClientUseLegacySecurityServerExchangeKeySetSecretKeySetMsgEn/SetMsgDe
发布前检查
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 测试（可选）：
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作为兼容适配层继续保留