runtime/secret 在并发读取时应如何管理生命周期

runtime/secret 在并发读取时，最稳妥的生命周期规则是：在同一个 secret.Do 内加载共享秘密、启动 worker，并在 Do 返回前等待所有 worker 结束。密钥只读共享，每个 worker 使用自己的算法状态和临时缓冲，外部只能收到公开结果或不含敏感内容的哨兵错误。

我最初容易忽略的一点是，secret.Do 解决的是临时存储擦除，不是同步。它不会替共享 byte 切片加锁，也不会自动替父 goroutine 等待子任务。即使当前文档说明在秘密模式内创建的 goroutine 会继承秘密模式，父作用域提前返回仍会让密钥引用、取消路径和结果所有权变得难以判断。

官方包文档：https://pkg.go.dev/runtime/secret

官方源代码说明：https://go.dev/src/runtime/secret/secret.go

把并发当成一个整体的敏感操作：父 goroutine 不只负责“启动”，还负责等待、收口错误、停止新任务并确认秘密不再被任何 worker 引用。

前置条件：先分清秘密模式与并发安全

secret.Do 的文档把 f 解释为由它发起的整个调用树。当前实现中，在秘密模式内创建的 goroutine 也会进入秘密模式，secret.Enabled() 可以在 goroutine 内确认这一点。这项继承能力对并发密码学计算很重要，但它没有改变 Go 的数据竞争规则。

如果一个 worker 会修改 key、对 key 做 append、把 key 放进共享 map，或者另一个 goroutine 同时清零 key，那么即使所有代码都在 Do 内，仍然可能出现数据竞争或读到损坏内容。秘密模式不是锁，也不是 race detector。

初始化：把 worker 和 Wait 都放进同一个 Do

并发生命周期最好遵循结构化并发：谁创建 worker，谁在当前作用域内等待 worker。对 runtime/secret 来说，这意味着 Wait 应发生在 secret.Do 的闭包里，而不是闭包外。

这样做有三个直接好处：父 goroutine 返回时不存在仍在运行的 worker；共享 key 的最后一个显式引用更容易在同一位置释放；公开结果何时完整可见也由 WaitGroup 的同步语义决定。相反，如果在 Do 内 go work() 后立即返回，子 goroutine 虽可继承秘密模式，但它可能继续运行很久，敏感堆对象也会继续保持可达。

编写代码：只读共享，临时状态按 worker 隔离

下面的示例用一份短期 HMAC key 并发处理多条公开消息。共享 key 在所有 worker 中只读；每个 worker 自己创建 hash.Hash，避免共享可变算法状态；公开摘要复制到调用方在 Do 外预分配的独立槽位。

package secretbatch

import (
    "crypto/hmac"
    "crypto/sha256"
    "errors"
    "runtime/secret"
    "sync"
    "sync/atomic"
)

var ErrSecretModeUnavailable = errors.New("secret mode unavailable")

// SumAll 在一个 secret.Do 生命周期内完成密钥加载、并发计算和等待。
func SumAll(loadKey func() []byte, messages [][]byte) ([][32]byte, error) {
    // 摘要是公开结果，由调用方作用域预先分配并长期持有。
    results := make([][32]byte, len(messages))
    var unavailable atomic.Bool

    secret.Do(func() {
        // 不支持的平台会直接执行闭包，因此先检查秘密模式是否生效。
        if !secret.Enabled() {
            unavailable.Store(true)
            return
        }

        // key 在敏感作用域内物化，并在所有 worker 完成前保持只读。
        key := loadKey()

        var wg sync.WaitGroup
        wg.Add(len(messages))

        for i, message := range messages {
            i, message := i, message
            go func() {
                defer wg.Done()

                // 当前文档规定这里会继承秘密模式；检查可防止静默降级。
                if !secret.Enabled() {
                    unavailable.Store(true)
                    return
                }

                // 每个 worker 创建独立 MAC，绝不共享可变哈希状态。
                mac := hmac.New(sha256.New, key)
                _, _ = mac.Write(message) // hash.Hash 的 Write 按约定不返回错误
                sum := mac.Sum(nil)

                // 不同索引是独立结果槽，只复制公开摘要，不导出 key。
                copy(results[i][:], sum)
            }()
        }

        // 在 Do 内等待，确保没有 worker 继续持有 key 或临时摘要。
        wg.Wait()
        key = nil
    })

    if unavailable.Load() {
        return nil, ErrSecretModeUnavailable
    }
    return results, nil
}

这段代码有意把 messages 视为公开只读输入。如果消息本身也是秘密，就不能让它们在 Do 外预先长期存在；应把加载或解封装过程移到秘密作用域内，并避免把明文任务送进外部 channel。

检查所有权：哪些数据能共享，哪些必须隔离

检查代码时可以按下面四条走：

1. 共享 key 是否严格只读：算法调用不得原地改写 key，任何手动清零都必须等所有 reader 结束。
2. 算法状态是否 worker 私有：hash.Hash、cipher 状态、临时 nonce 缓冲等通常是可变对象，不能多个 goroutine 共用。
3. 输出槽是否互不重叠：每个 worker 写独立数组元素，或者通过内部 channel 汇总；不能并发追加同一个 slice。
4. 错误和日志是否不含秘密：对外只给预定义哨兵或任务索引，不格式化 key、明文和临时摘要。

runtime/secret 会跟踪作用域内的新堆分配，但官方提醒，反复 append 或 map 增长会放大追踪和擦除成本。worker 最好使用定长数组、一次性分配或算法自带的固定状态，不要在敏感区构建不断增长的调试记录。

运行检查：不跑代码也能先审查五个边界

这类代码在进入真实实验前，可以先做静态审查。以下不是运行结果，而是设计检查项：

• secret.Do 内是否同时出现了 worker 创建和 Wait。
• worker 是否在入口检查 secret.Enabled()，避免 unsupported 平台静默按普通模式执行。
• 共享 key 是否只读，且清零或丢弃引用发生在 Wait 之后。
• 外部 channel、错误值、panic 值和日志中是否可能携带敏感切片或其引用。
• 返回结果是否由调用方预先分配，并确认它在业务上确实可以公开。

实验构建仍需显式启用包：

# runtime/secret 只在启用实验开关时可导入
GOEXPERIMENT=runtimesecret GOOS=linux GOARCH=amd64 go test ./...

# 并发代码仍应单独使用 race detector 检查数据竞争
GOEXPERIMENT=runtimesecret GOOS=linux GOARCH=amd64 go test -race ./...

这里的 -race 与秘密擦除是两条不同的检查线：race detector 检查并发访问，runtime/secret 管敏感临时存储。一个通过不能替代另一个。

扩展实验：取消发生时必须等待 worker 真正退出

context.CancelFunc 只发出取消信号，不代表 worker 已经停止。若父 goroutine 在调用 cancel() 后直接离开 Do，仍可能有 worker 持有 key、阻塞在 channel 或继续计算。

安全的取消顺序应满足这些约束：

1. 停止投递新任务或关闭内部任务源。
2. 让每个 worker 在可控位置观察 ctx.Done()。
3. 等待所有 worker 返回，而不是只等待第一个错误。
4. 丢弃对共享 key、内部 channel 和临时缓冲的引用。
5. 最后再离开 secret.Do。

使用 errgroup.Group 时也要保持同样思路：Wait 必须发生在秘密作用域内。某个任务报错后，其他任务可能仍需要一段时间响应取消；不要把“已经收到错误”误解成“所有秘密引用都已释放”。

清理与总结：并发读取的生命周期清单

常见问题

父 Do 返回后，子 goroutine 还会保持秘密模式吗？

当前官方文档说明，在秘密模式内创建的 goroutine 会像整个 goroutine 被另一个 Do 包裹。不过这不等于父作用域应该提前返回；子任务仍会延长密钥引用和整体生命周期，结构化等待更容易审计。

多个 worker 只读同一个 key 还需要锁吗？

如果 key 的底层字节在整个并发阶段确实不被任何一方修改，纯读取本身不需要互斥锁。但必须确认所调用 API 不会原地改写输入，并把清零动作放到全部 worker 结束之后。

可以把 key 放进 channel 分发吗？

不推荐把敏感切片发送到可能跨出秘密作用域的 channel。channel 会延长引用寿命，也容易被外部消费者保存。更清晰的设计是让 worker 在同一 Do 内闭包捕获只读 key，channel 只传公开任务索引或公开 payload。

Wait 完成后，堆上的 key 会立即擦除吗？

不保证立即。还必须没有其他引用，并等待 GC 发现对象不可达。Wait 的价值是让程序能确定 worker 不再持有引用，从而为后续擦除创造条件。

并发读取时真正需要管理的是“最后一个秘密引用什么时候消失”。把 worker 创建、等待、取消和结果复制都收进同一个 secret.Do，再用只读共享与私有临时状态约束数据所有权，生命周期才会从“可能还在跑”变成可推理、可审查的结构。