[nats] 订阅 handler 的 panic 直接炸掉整个进程——SubscribeJSON 连坏 JSON 都兜了底，却把 handler panic 漏进 nats.go 内部 goroutine，一条畸形消息杀掉全部订阅

现象

nats/client.go:275/300/314/383 的 Subscribe / SubscribeJSON / QueueSubscribeJSON / Reply 全部把用户 handler 原样透传给上游 SDK：

// client.go:300
func SubscribeJSON[T any](c *Client, subject string, handler func(ctx context.Context, msg *T)) (*nats.Subscription, error) {
	return c.Subscribe(subject, func(m *nats.Msg) { ... handler(extractTraceCtx(m), &payload) })
}

而 nats.go v1.55.0 的异步派发循环直接调用、无任何 recover（nats.go@v1.55.0/nats.go:3861：mcb(m)，全文件的 recover 只用于 closeStatusListener）。同仓明文约定 AGENTS.md:31「禁止裸 go func：用 github.com/oekit/concurrency/async 的 GoSafe 系列（panic 被 recover）」，且 wsutil/outbox.go:108 写着「写协程 panic 只许死这条连接，不许死整个进程」——唯独接收外部不可信载荷的订阅 handler 没有这层隔离。

探针复现（/tmp/pbprobe，内嵌 nats-server，handler 对 "boom" panic）：

[natspanic] benign message handled
panic: handler panic (simulated)
goroutine 24 [running]:
main.natspanic.func1(...)        /tmp/pbprobe/main.go:55
github.com/oekit/network/nats.SubscribeJSON[...].func1()  /Users/zhangyi/oekit/network/nats/client.go:307
github.com/nats-io/nats.go.(*Conn).waitForMsgs(...)       nats.go@v1.55.0/nats.go:3861
exit status 2

失败场景推演

一条业务消息 JSON 反序列化成功但语义残缺（可选字段为 nil、map 查不到 key）→ handler nil 解引用 panic → 穿透 waitForMsgs 无 recover → 进程退出。后果：该进程上所有订阅、所有连接、所有在途请求一并消灭；core NATS 无持久化，这条消息永久丢失、服务端零记录。SubscribeJSON 对坏 JSON 特意做了「log 后跳过」的健壮性（client.go:303-306），唯独更常见的 handler 内 panic 没兜。

为什么测试没抓到

nats 包的 panic 相关测试全部是 nil ctx 兜底回归（nats_issue_fix_test.go:33 等，#79/#101 修复面），没有任何 handler panic 用例；panic 发生在上游 SDK goroutine，-race 也不检出。

建议修复方向

Subscribe/SubscribeJSON/QueueSubscribe/QueueSubscribeJSON/Reply 的 handler 调用点包 async.GoSafeLabeled（panic 收编为 Error 日志 + 消息丢弃留痕，与 outbox 的「只死这条连接」同口径）；至少在 godoc 显著位置明示「handler panic = 进程崩溃」。

置信度：高（探针复现：进程 exit status 2 + 堆栈直指 waitForMsgs 无 recover；基线 = network 9f3d2c3）

与既有 issue 的差异：33 条已有 issue 中 #79/#100/#101 是「API 入口 nil ctx panic」，无任何 handler panic 隔离议题；与 #54（flaky 测试）无关。

test(nats): 消除 #145 回归测试中 if-init 的 err 变量遮蔽（govet shadow）

Merge pull request #148 from oekit/fix/wave1-issue-145-146-147

已在 v0.9.2 修复并发布 ✅

变更内容

本条修复（在 v0.9.2 的版本节里定位到）：

fix(nats): 订阅 handler 的 panic 就地收编——handler 跑在 nats.go 无 recover 的派发 goroutine（waitForMsgs 直接 mcb(m)）里，一条语义残缺消息的 panic 会穿透炸掉整个进程、连同其上全部订阅与在途请求一并消灭；现在 Subscribe/QueueSubscribe（覆盖 SubscribeJSON/QueueSubscribeJSON/Reply 全部漏斗）的 handler 调用点统一 panic 收编（Error 日志 + 该条消息丢弃留痕，与 wsutil「只死这条连接」同口径），订阅与进程存活（[nats] 订阅 handler 的 panic 直接炸掉整个进程——SubscribeJSON 连坏 JSON 都兜了底，却把 handler panic 漏进 nats.go 内部 goroutine，一条畸形消息杀掉全部订阅 #145）

该版本 `v0.9.2` 的其余变更

关联问题单：#145。

fix(wsutil): Outbox 写动作 panic 同样闭合记账——write panic 时旧实现整套记账与冲刷（failInFlight/countPending/drain）被跳过，「Send(true) − Written ≡ Dropped」恒等式破口、帧静默消失且 Dropped 恒为 0（[wsutil] Outbox 的 Written/Dropped 无法闭合「Send 返回 true 的帧」—— 写失败的那一帧既不计 Written 也不计 Dropped #105/[wsutil] Outbox.Send 的 closed 检查与入队非原子——Close 后通过检查的帧永久滞留，Send 返回 true 却既不写入也不计 Dropped #117/wsutil Outbox的Dropped恒等式与实现相悖 #123 的口径只对 error 路径成立）；现在 write 调用点 panic 收编为 error 走既有失败分支（run 与 drain 两径同口径），写动作 panic 计入 Dropped（[wsutil] Outbox 写协程 panic 时记账与冲刷全部被跳过——「Send(true) − Written ≡ Dropped」恒等式再次破口，帧静默消失且 Dropped 恒为 0 #146）

关联问题单：#146。

fix(nats): Close(ctx) 重连窗口内返回 nil——上游 Drain() 在连接重连中自己执行 nc.Close()（目标态已达成）却返回 ErrConnectionReconnecting，旧豁免只认 ErrConnectionClosed，把已关误记成 "drain: connection reconnecting" 虚假错误（上层关停误报告警/非零退出码/跳过清理）；现在 ErrConnectionReconnecting 与 ErrConnectionDraining 同列「目标态已达成」豁免（[nats] Close(ctx) 落在重连窗口返回虚假错误——上游已强制关闭连接（目标态达成）却报 "drain: connection reconnecting"，与自家「目标态已达成不算错误」口径相反 #147）

关联问题单：#147。

Release: https://github.com/oekit/network/releases/tag/v0.9.2

fix(nats,wsutil): JetStream/生命周期回调 panic 收编 + 文档失实修正 + 可停 timer

Navigation Menu

Repository navigation

[nats] 订阅 handler 的 panic 直接炸掉整个进程——SubscribeJSON 连坏 JSON 都兜了底，却把 handler panic 漏进 nats.go 内部 goroutine，一条畸形消息杀掉全部订阅 #145

现象

失败场景推演

为什么测试没抓到

建议修复方向

变更内容

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[nats] 订阅 handler 的 panic 直接炸掉整个进程——SubscribeJSON 连坏 JSON 都兜了底，却把 handler panic 漏进 nats.go 内部 goroutine，一条畸形消息杀掉全部订阅 #145

Description

现象

失败场景推演

为什么测试没抓到

建议修复方向

Activity

zy84338719 commented on Nov 10, 2026

变更内容

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions