watchdog

package
v0.46.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 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)。

配对键与 trajectory **同源**:eventbus.ToolCallID(全局 call_id,**不含 step**, issue #336)。step/轮次是归属信息,不是配对键:结果可以在后续 step 到达、 同一 call_id 可以跨 step 重复声明,按 step 分段配对会把这些正常形态判成 缺口(同一事件流两包相反结论)。本包不再自己构造配对键(门禁规则 tool-pairing-key-single-source 禁止直接索引 Payload["call_id"])。

INV1 会话收口(session_finished)仍有未执行声明 → reason=declared_not_executed; INV2 结果无对应声明(幽灵结果)→ reason=unpaired_result,已配对后的重复结果 → reason=duplicate_result,同号重复声明 → reason=duplicate_call。 INV1 的判定期是**会话收口或 TTL 清扫**,不是每个 step_finished:结果可能 在后续环节到达,按环节判会假红。TTL 清扫对未配对声明同样告警,不静默丢。 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 = eventbus.ClosedByLoop
	// ClosedByRecovery 恢复循环归因(中断会话的统一收敛体)。
	ClosedByRecovery = eventbus.ClosedByRecovery
	// ClosedByBootReconcile 启动对账归因(发版重启后的孤儿回收)。
	ClosedByBootReconcile = eventbus.ClosedByBootReconcile
	// ClosedByPanic 编排 panic 归因(recoverPanic 就地收口)。
	ClosedByPanic = eventbus.ClosedByPanic
	// ClosedByDeadOwner 他副本死主回收归因(reconcile.ByDeadOwner 的同源值)。
	ClosedByDeadOwner = eventbus.ClosedByDeadOwner
	// ClosedByDeadLease 他副本租约过期回收归因(reconcile.ByDeadLease 的同源值)。
	ClosedByDeadLease = eventbus.ClosedByDeadLease
)

闭合归因(closed_by)缺省词表。宿主可在 Config.ClosedBy 里扩充, 内核只判「有没有(在册的)归因」,不判归因语义。 取值引用 eventbus 的 closed_by 词表(issue #391):本包是消费方、reconcile 是生产方,两包各抄一份时本包的缺省表漏了 reconcile 的死主/租约归因,把 合法收敛报成「无归因」。词表只有一份(eventbus.ClosedBy* + ClosedByDefaults)。

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"])。

View Source
const (
	// ReasonDeclaredNotExecuted 会话收口 / TTL 过期仍未配对的调用声明。
	// 注册别名:规范 token 见 eventbus.CanonicalPairingReason。
	ReasonDeclaredNotExecuted = eventbus.PairingReasonDeclaredNotExecuted
	// ReasonUnpairedResult 结果没有任何调用声明(幽灵结果)。
	ReasonUnpairedResult = string(trajectory.PairingUnpairedResult)
	// ReasonDuplicateResult 同一 call_id 的第二个及以后结果(第一次观测是真相)。
	ReasonDuplicateResult = string(trajectory.PairingDuplicateResult)
	// ReasonDuplicateCall 同一 call_id 的第二个及以后声明(第一次观测是真相)。
	ReasonDuplicateCall = string(trajectory.PairingDuplicateCall)
)

工具调用级告警 reason 词表(EventToolPairingLeak 的 payload["reason"])。

**单源(issue #392)**:三条与 trajectory.Pairing 逐字同名的 reason 直接引用 trajectory 的导出常量,不再手抄字面量;declared_not_executed 是 trajectory.PairingMissingResult 的注册别名(eventbus 侧登记映射,线路值不变 以兼容既有消费者)。同一事实只有一份规范词表,聚合面不再把同一条件拆成 两个桶。

Variables

This section is empty.

Functions

This section is empty.

Types

type Config added in v0.38.0

type Config struct {
	// ClosedBy 宿主注册的闭合归因词表。缺省(空)时使用 defaultClosedBy;
	// 填了则在缺省词表基础上**扩充**(不是替换)——缺省值含所有宿主共有的
	// 收尾路径与内核 reconcile 的四路归因,只增不减才能避免「宿主少写一个值
	// 就把合法归因判成红」。
	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)。

接缝约束三条(#400):

  • 不得重入:不得回调 Watcher.Run/observe(本包按「单协程消费事件流」 设计,重入会打乱配对表与轮括号状态)。
  • 不得阻塞:告警在事件消费循环里同步发出;实现须自行设超时/上界, 不得无限等待(慢发布会拖住后续事件的配对判定)。
  • panic 隔离:本包不 recover Pub——实现不得 panic(panic 会掀翻 Run 的 事件消费协程);留痕失败请自行处理。

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