watchdog

package
v0.40.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

turn.go —— INV3 轮级括号配对(issue #171)。

INV1/INV2(watchdog.go)是**工具调用级**配对:声明↔结果。本文件是它的外层—— **轮级**配对:turn_started 开括号、turn_ended 闭括号。任何以事件流呈现轮生命 周期的宿主都有这对括号,且都面对同一组异常态:无归因的闭合、重复闭合、停机留 开放(**合法**)、开放超时(泄漏)。

只告警不裁决

与既有 INV 同一章程:本文件只登记、校验与归因告警,**闭合动作仍由宿主恢复 路径执行**(recovery/boot-reconcile/panic 各自发 closed_by 的 turn_ended)。

判得了什么,判不了什么(刻意写明的边界)

  • 判得了:闭合有没有归因(closed_by ∈ 词表)、status 是否在 contract 终态 词表内、闭合有没有对应的开括号、开放括号是否超 TTL。
  • 判不了:「闭合 status 与会话终态一致」。那需要会话存储面(本轮到底收敛成 什么),watchdog 没有存储面,也不该有——语义裁决归宿主恢复路径。本包只判 词表成员与配对/归因,**不判断归因内容对不对**(例如 recovery 是否真的由 恢复循环发起)。

停机留开放 = 合法

进程停机路径刻意不落 turn_ended,让括号保持开放、由下次启动的对账/恢复关闭。 因此 Run 因 ctx 取消退出时**不做扫尾告警**:扫尾只在进程存活、事件持续到达时 按 TTL 触发。否则每个宿主的正常停机都会误报一片泄漏。

Package watchdog 被动配对不变量监视(spec 2026-09-15-tool-identity-otel-guard-design P3):

生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。

订阅事件总线校验配对不变量——只告警,不裁决(热路径裁决在 IdentityGuard)。 INV1 环节收口仍有未执行声明 → reason=declared_not_executed; INV2 结果无对应声明(重复/幽灵结果)→ reason=unpaired_result。 INV3(issue #171)是工具配对的外层——轮级括号 turn_started/turn_ended 的 配对、闭合归因(closed_by)与 status 终态词表校验,见 turn.go。 注意命名撞车:spec 2026-09-15-tool-identity-otel-guard-design §8 的「INV3 (事件面 checksum 抽验)」是另一条不变量,本包仍不实现它——tool_result 载荷 截断到 2000 字符,无法重算 checksum,内容级校验由守卫在源头全量覆盖。

Index

Constants

View Source
const (
	// ClosedByLoop 收尾漏斗正常出口(宿主编排循环自己闭合)。
	ClosedByLoop = "loop"
	// ClosedByRecovery 恢复循环归因(中断会话的统一收敛体)。
	ClosedByRecovery = "recovery"
	// ClosedByBootReconcile 启动对账归因(发版重启后的孤儿回收)。
	ClosedByBootReconcile = "boot-reconcile"
	// ClosedByPanic 编排 panic 归因(recoverPanic 就地收口)。
	ClosedByPanic = "panic"
)

闭合归因(closed_by)缺省词表。宿主可在 Config.ClosedBy 里扩充, 内核只判「有没有(在册的)归因」,不判归因语义。

View Source
const (
	// ReasonTurnEndUnattributed 闭合无归因,或归因不在宿主注册的词表内。
	ReasonTurnEndUnattributed = "turn_end_unattributed"
	// ReasonTurnEndUnknownStatus 闭合携带的 status 不在 contract 终态词表内
	// (含缺失)。语义裁决归宿主,这里只判词表成员。
	ReasonTurnEndUnknownStatus = "turn_end_unknown_status"
	// ReasonTurnEndUnopened 闭合没有对应的开括号(重复闭合 / 事件乱序丢开括号)。
	ReasonTurnEndUnopened = "turn_end_unopened"
	// ReasonTurnOpenLeak 开放括号超 TTL 未闭合(进程存活时按 TTL 清扫)。
	// 停机退出不触发——停机留开放是合法态。
	ReasonTurnOpenLeak = "turn_open_leak"
)

轮括号告警 reason 词表(EventTurnBracketViolation 的 payload["reason"])。

Variables

This section is empty.

Functions

This section is empty.

Types

type Config added in v0.38.0

type Config struct {
	// ClosedBy 宿主注册的闭合归因词表。缺省(空)时使用 defaultClosedBy;
	// 填了则在缺省词表基础上**扩充**(不是替换)——缺省四值是所有宿主共有的
	// 收尾路径,只增不减才能避免「宿主少写一个值就把合法归因判成红」。
	ClosedBy []string
	// OpenTTL 开放括号的泄漏判定阈值;缺省(<=0)复用 openIdleTTL。
	OpenTTL time.Duration
	// SweepEvery 清扫间隔;缺省(<=0)复用 sweepEvery。
	SweepEvery time.Duration
}

Config INV3 轮括号的可选配置。零值 = 缺省语义(New 即零值配置)。

type Pub

type Pub func(sessionID, caseID string, stepID *uint64, typ, level string, payload map[string]any)

Pub 告警发布(与调度器 pub 同一落库广播路径:repo.InsertEvent + Bus.Broadcast)。

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher 配对不变量监视器。Run 单协程消费事件通道,无需加锁。

func New

func New(pub Pub) *Watcher

New 构造(pub 必填;nil 时告警静默丢弃——不阻塞事件流)。

缺省配置:closed_by 四值(loop|recovery|boot-reconcile|panic)+ 2h 开放 TTL。

func NewWithConfig added in v0.38.0

func NewWithConfig(pub Pub, cfg Config) *Watcher

NewWithConfig 带 INV3 配置的构造(additive:New(pub) 的调用面与缺省语义不变)。

cfg 的零值 = New 的缺省语义;ClosedBy 在缺省四值上**扩充**,OpenTTL / SweepEvery <=0 时复用既有 openIdleTTL / sweepEvery。

func (*Watcher) Run

func (w *Watcher) Run(ctx context.Context, bus *eventbus.Bus)

Run 消费事件流直到 ctx 取消(main 装配期后台 goroutine)。

ctx 取消退出**不做扫尾告警**:停机路径刻意留开放轮括号给恢复循环/启动对账 闭合,把「停机」当「泄漏」会误报每个宿主的正常收尾。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL