Files
knowledge-governance/internal/testbarrier/barrier.go
T
姚章浩 0d3a016a9e feat(worker): 加真实中断演练的固定同步屏障
真杀 worker 只有在"写了一半"那一刻才有意义,靠 sleep 猜时间会错过阶段 ——
上一版演练脚本就是这样永远 exit 0 的。这里把"进程确实停在固定点"变成文件事实:
worker 到达点位后写 <dir>/<point>.hit 再等放行,演练方看到它再 SIGKILL,命中
是确定的。

安全边界:只有 KG_TEST_BARRIER_DIR 与 KG_TEST_BARRIER_POINTS 同时在场才生效
(默认关闭),只由本机 compose overlay 注入;单次等待有硬超时,没人放行就自己
继续;同一进程被杀后重启看到同一份 .hit 直接通过,不会把接管再拦住。屏障挂在
contentTrackedTarget(阶段之间),发布链路不需要知道演练的存在。

验证:屏障包 4 条用例(默认关闭无副作用 / 命中与放行握手 / 超时自行继续并留
.hit+.timeout / 目录不可建报错但不阻塞)与包装层接线用例全绿(后者证明真实
Apply 路径真的走到点位,漏接线会红)。
2026-10-30 03:09:29 +08:00

164 lines
5.7 KiB
Go

// Package testbarrier 是"本机真实 worker 中断演练"的固定同步屏障。
//
// 为什么需要它:真杀 worker 只有在"写了一半"的那一刻才有意义,靠 sleep 猜时间会
// 错过阶段(旧脚本就是这样永远 exit 0 的)。屏障把"进程确实停在某个固定点"变成一个
// 文件事实:worker 到达点位后写 <dir>/<point>.hit,然后等演练方写 <dir>/<point>.go
// 才继续。演练方看到 .hit 再 SIGKILL,命中是确定的,不是碰运气。
//
// 安全边界(**默认关闭**):
// - 只有 KG_TEST_BARRIER_DIR 与 KG_TEST_BARRIER_POINTS 两个环境变量同时给出才生效;
// 生产/测试栈的常规 env 里没有它们,所以行为与不接线完全一致。
// - 只在本机测试栈用:目录由 compose overlay 指向本机归档根下的 barrier/ 子目录。
// - 有硬超时(默认 120s):没人来放行就自己继续,绝不把 worker 永久挂住。
// - 同一 (point) 在一次演练里只停一次:进程被杀后重启的 worker 看到上一次的 .hit
// 就直接通过,接管不会被第二次拦住。
// - 不改 WeKnora,也不碰发布代码的语义:它只是在既有阶段之间加一个可关闭的等待。
package testbarrier
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"path/filepath"
"strings"
"time"
)
const (
// EnvDir 是屏障目录(本机受限注入;为空 = 关闭)。
EnvDir = "KG_TEST_BARRIER_DIR"
// EnvPoints 是允许停留的点位,逗号分隔,例如 "after:database"(为空 = 关闭)。
EnvPoints = "KG_TEST_BARRIER_POINTS"
// EnvTimeout 是单次等待上限(Go duration,默认 120s)。
EnvTimeout = "KG_TEST_BARRIER_TIMEOUT"
)
// hit 是"worker 已到达该点位"的现场记录。
type hit struct {
Point string `json:"point"`
Subject string `json:"subject"`
PID int `json:"pid"`
At string `json:"at"`
}
// Settings 是从环境变量解析出来的屏障配置。
type Settings struct {
Dir string
Points map[string]bool
Timeout time.Duration
}
// FromEnv 解析配置;两个必需变量缺一个就返回 enabled=false(默认关闭)。
func FromEnv() (Settings, bool) {
dir := strings.TrimSpace(os.Getenv(EnvDir))
raw := strings.TrimSpace(os.Getenv(EnvPoints))
if dir == "" || raw == "" {
return Settings{}, false
}
points := map[string]bool{}
for _, item := range strings.Split(raw, ",") {
if name := strings.TrimSpace(item); name != "" {
points[name] = true
}
}
if len(points) == 0 {
return Settings{}, false
}
timeout := 120 * time.Second
if value := strings.TrimSpace(os.Getenv(EnvTimeout)); value != "" {
if parsed, err := time.ParseDuration(value); err == nil && parsed > 0 {
timeout = parsed
}
}
return Settings{Dir: dir, Points: points, Timeout: timeout}, true
}
// Enabled 报告屏障是否已在本进程启用(演练方用它确认注入生效)。
func Enabled() bool {
_, enabled := FromEnv()
return enabled
}
// Wait 在指定点位停留:写 .hit、等 .go(或超时)。未启用的点位/进程直接返回。
//
// 返回错误只表示"屏障自身写不下现场"(目录不可写等),调用方据此照常继续——
// 屏障是演练设施,坏掉不许让生产写入失败。
func Wait(ctx context.Context, point, subject string) error {
settings, enabled := FromEnv()
if !enabled || !settings.Points[point] {
return nil
}
if err := os.MkdirAll(settings.Dir, 0700); err != nil {
return fmt.Errorf("test barrier dir unusable: %w", err)
}
base := filepath.Join(settings.Dir, safeName(point))
hitPath := base + ".hit"
if _, err := os.Stat(hitPath); err == nil {
// 上一次演练已经在这个点位停过(进程被杀后重启):直接通过,别把接管再拦住。
log.Printf("test barrier point=%s subject=%s: previous hit exists, continuing", point, subject)
return nil
}
record, err := json.Marshal(hit{Point: point, Subject: subject, PID: os.Getpid(), At: time.Now().UTC().Format(time.RFC3339Nano)})
if err != nil {
return err
}
if err := writeAtomic(hitPath, record); err != nil {
return err
}
log.Printf("test barrier point=%s subject=%s pid=%d: waiting for release", point, subject, os.Getpid())
deadline := time.Now().Add(settings.Timeout)
ticker := time.NewTicker(100 * time.Millisecond)
defer ticker.Stop()
for {
if _, err := os.Stat(base + ".go"); err == nil {
// 一次性放行:删掉放行标记,避免下一次演练被同一份标记直接放走。
_ = os.Remove(base + ".go")
log.Printf("test barrier point=%s subject=%s: released", point, subject)
return nil
}
if time.Now().After(deadline) {
_ = writeAtomic(base+".timeout", []byte(time.Now().UTC().Format(time.RFC3339Nano)))
log.Printf("test barrier point=%s subject=%s: timeout after %s, continuing (演练会看到 .timeout)", point, subject, settings.Timeout)
return nil
}
select {
case <-ctx.Done():
log.Printf("test barrier point=%s subject=%s: context done, continuing", point, subject)
return nil
case <-ticker.C:
}
}
}
// safeName 让点位名可以安全地当文件名("after:database" → "after-database")。
func safeName(point string) string {
replacer := strings.NewReplacer(":", "-", "/", "-", " ", "-")
return replacer.Replace(point)
}
func writeAtomic(path string, payload []byte) error {
temporary := path + ".tmp"
file, err := os.OpenFile(temporary, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
if err != nil {
return err
}
if _, err := file.Write(payload); err != nil {
file.Close()
_ = os.Remove(temporary)
return err
}
if err := file.Sync(); err != nil {
file.Close()
_ = os.Remove(temporary)
return err
}
if err := file.Close(); err != nil {
_ = os.Remove(temporary)
return err
}
return os.Rename(temporary, path)
}