134 lines
3.0 KiB
Markdown
134 lines
3.0 KiB
Markdown
|
# notify
|
|||
|
|
|
|||
|
|
`b612.me/notify` 是一个面向点对点直连场景的 Go 通信基础包，覆盖消息信令、流式传输、批量数据通道和文件传输内核能力。
|
|||
|
|
|
|||
|
|
## 模块定位
|
|||
|
|
|
|||
|
|
- 消息面：`Send`、`SendWait`、`Reply`、`SetLink`
|
|||
|
|
- 流式数据面：`OpenStream`
|
|||
|
|
- 记录流数据面：`OpenRecordStream`
|
|||
|
|
- 批量数据面：`OpenBulk`（`shared` / `dedicated`）
|
|||
|
|
- 文件传输内核：transfer control / progress / resume
|
|||
|
|
- 会话模型：`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))
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 传输与 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` 作为兼容适配层继续保留
|