dispatch

package
v0.47.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: 6 Imported by: 0

Documentation

Overview

Package dispatch 派发域的**失败面**:改派错误分类(transient/fatal/other 三档) 与同域/跨域兜底改派环(issue #169,下沉自宿主 internal/engine/scheduler/experts/dispatch.go)。

生命周期: Experimental(v0.38.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。

它回答的是第四问

多执行者编排有四问,前三问各有归属,第四问此前无人回答:

① 这次派发**能不能**发生?   → 上游 oagentkit/agent/dispatch(allow 矩阵 +
   深度上限 + 自派发拒绝;原 dispatch 门面 v0.35.0 已整包删除,消费方直连上游)
② 排队**怎么排**?           → scheduling(优先级/公平/配额/背压)
③ 同一次调用要不要**原样重发**? → guardx/toolfail(处置层语义,单源)
④ 失败后**还能不能再派、派给谁**? → 本包

本包是**新立的机制包**,不是可达性门面:不碰 allow 矩阵、深度上限、 自派发拒绝三条判定,也不做队列、不排序、不执行(执行步与候选枚举都经 回调注入,见 StickyFailover)。

两条硬纪律(包头写死,测试各钉一条)

  1. **判定面只读首次失败的原始错误。** 改派环会用 `%w(已同域改派 X 仍失败)` 把改派说明拼进累计错误——那类文本**只进事件 与最终消息**(给人看),不进 Classify 的判定面。理由:文本兜底按关键词判定, 说明里若混进「权限」「连接」这类词,一次瞬态会被误判成 fatal(跨域兜底被 错误抑制),或 fatal 被误判成 transient(多烧一次跨域改派)。判定面只应看 **失败本身**,不该看编排过程。
  2. **状态码判定必须 `\b` 词边界。** 裸 `strings.Contains(msg, "403")` 会被 「省略中段 4032 字节」这类字节数/行号命中:瞬态被误判成 fatal,或 「共 429 行」把 fatal 误升级成 transient。词边界把「数字是更长数字的 一部分」整类排除。

三档词表

transient 瞬态:可跨域兜底改派(超时/连接类)。
fatal     终态类:换执行者也是白跑(权限/凭证/审批/治理类)——直接终态。
other     不确定:仅同域重试,不跨域。

词表**中英双语**(issue #207):ClassUnknown 落到文本兜底的错误文案两种语言 都会出现——transient 档若只有英文,中文瞬态(「连接被拒绝」「连接超时」) 整类不可达:跨域兜底对中文错误静默失效,最典型的瞬态还会被 fatal 档的 中文词升级成终态。语言不得成为档位偏置;fatal 档的「拒绝」因此收窄为 「权限拒绝」「拒绝访问」(裸「拒绝」会命中「连接被拒绝」这类瞬态文案)。

两级判定:上游单源优先,文本只兜底

第一级消费 `toolgate/policy.Disposition`——它是「toolfail 链 → MCP 协议层」 两级合成的**唯一**实现,本包零文本匹配。链与协议层都判不出类型 (ClassUnknown)才落第二级文本兜底(词表内置在本包)。类型已判出时**不看文本**: 「类型说了 A、文案说 B 时听文案」与判定纪律相反。

与上游的两轴映射(不是照搬)

上游回答「同一次调用要不要原样重发」,本包回答「换一个执行者有没有意义」—— 故逐档映射而非照搬:

上游处置类            本包档     换执行者有没有意义
transient             transient  有:基础设施抖动,换执行者/换后端可能通
rate_limited          transient  有:限流在服务端侧,换执行者可能绕开
self_reported         transient  有:生产者自报可重试
permanent             other      有:「能力不支持这类请求」⇒ 换**能力**可能支持
authentication        fatal      无:同一套凭证,换执行者不刷新凭证
permission_denied     fatal      无:同一套权限面,需人工放开
not_found             other      有:换执行者可能指向别的目标/用别的工具
invalid_argument      other      有:换执行者的参数构造不同,可能就对了
unknown               →文本兜底  不可分类 = 保守(不乐观)

关键分歧:上游把 not_found / invalid_argument 判「不可重试」,本包的「重试」 却是**换执行者**——换执行者正是「换构造参数的人 / 换目标对象」⇒ 不终态, 只是不跨域。

Index

Constants

View Source
const (
	// EventSameDomain 同域改派(逐候选,含尝试的候选名)。
	EventSameDomain = "same_domain_failover"
	// EventCrossDomain 瞬态跨域兜底(一次)。
	EventCrossDomain = "cross_domain_failover"
)

改派事件类别(进宿主事件面与最终消息,不进判定面)。

View Source
const (
	// DefaultSameDomain 代码缺省:同域改派一次(存量行为)。
	DefaultSameDomain = 1
	// DefaultCrossDomain 代码缺省:不跨域。
	DefaultCrossDomain = false
)

Variables

This section is empty.

Functions

func Resolve added in v0.38.0

func Resolve(entry, defaults, conf Policy) (sameDomain int, crossDomain bool)

Resolve 四级数据化优先级的解析纯函数:条目 > 表级 > conf 旋钮 > 代码缺省。

三层都可以是零值 Policy(该层什么都不声明);解析结果与逐层 Effective 叠加后取 Resolved() 等价——写成一条链是为了让「优先级顺序」 只有一处真相(顺序写错会在 Resolve 的测试里当场红)。

Types

type AttemptFunc added in v0.38.0

type AttemptFunc func(ctx context.Context, slug string) error

AttemptFunc 执行步接缝:把候选 slug 当作执行者跑一次。

返回 nil = 改派成功(宿主在此拿到产出);返回非 nil = 该候选也失败。 本包不解释错误内容,也不在环内重新判档(纪律①)。

type CandidatesFunc added in v0.38.0

type CandidatesFunc func(slug string, tried map[string]bool, sameDomain bool) []string

CandidatesFunc 改派候选接缝(issue #169 原文签名): FailoverCandidates(slug, tried, sameDomain)。

sameDomain=true 限同域(同 route_group 一类的分组),false=跨域全集; 两次调用都必须排除 tried 与 slug 本身。**候选怎么来是宿主的事**—— 注册表、能力画像、启用开关全在宿主侧,本包只消费有序列表, 与宿主的注册表/能力画像无关。

type Class added in v0.38.0

type Class string

Class 改派错误档(三档词表,机读值;取值见下常量集)。

用字符串而非整数枚举:档名要随事件载荷落日志、随调用链跨进程传递, 数字序一旦被无意依赖就会变成隐藏契约。

const (
	// ClassTransient 瞬态:可跨域兜底改派(超时/连接类)。
	ClassTransient Class = "transient"
	// ClassFatal 终态类:换执行者也是白跑(权限/凭证/审批/治理类)——直接终态。
	ClassFatal Class = "fatal"
	// ClassOther 不确定:仅同域重试,不跨域。
	ClassOther Class = "other"
)

func Classify added in v0.38.0

func Classify(err error) Class

Classify 一次失败的改派档位(两级判定,见包头)。

err 为 nil 时返回 ClassOther(没有失败可处置,保守按「仅同域」处理—— 既不跨域也不终态)。

判定面只读这个 err 本身(纪律①)

调用方**必须**把首次失败的原始错误传进来,不要传改派环累计出来的错误: 累计错误里的改派说明只进事件与最终消息。StickyFailover 已按此实现 (它自己只在进入环之前判一次),此处再写明是因为宿主也可能绕过环直接调本函数。

func (Class) String added in v0.38.0

func (c Class) String() string

String 机读名(进事件载荷与日志)。

type Event added in v0.38.0

type Event struct {
	Kind string
	// From 首次失败的执行者。
	From string
	// To 本次改派尝试的候选。
	To string
	// Err 累计错误(含改派说明)。
	Err error
}

Event 一次改派尝试的留痕。

Err 是**到目前为止的累计错误**(含 `%w(已同域改派 X 仍失败)` 说明)—— 它是给人看的,不得回喂 Classify(见包头纪律①)。

type Policy added in v0.38.0

type Policy struct {
	// SameDomain 同域改派次数上限;0=禁用改派;nil=回落下一级。
	SameDomain *int
	// CrossDomain 瞬态错误在同域改派耗尽后允许跨域兜底一次;权限/凭证类
	// 永不跨域(fatal 在环里直接终态,本开关管不到它)。nil=回落下一级。
	CrossDomain *bool
}

Policy 改派策略的**一层**声明(条目层 / 表级层 / conf 层各一份)。

字段为 nil 表示该层**未声明**,回落到下一级;非 nil 即使是 0/false 也是 显式声明(同域 0 = 禁用改派;跨域 false = 显式不跨域)。

func (Policy) Effective added in v0.38.0

func (p Policy) Effective(def Policy) Policy

Effective 解析指针语义:本层声明的字段优先,未声明的字段回落 def。

逐字段独立回落——同一条目可以只覆盖 SameDomain 而让 CrossDomain 继续回落。

func (Policy) Resolved added in v0.38.0

func (p Policy) Resolved() (sameDomain int, crossDomain bool)

Resolved 把落定后的指针解析成具体值;未声明的字段取代码缺省 (同域一次 / 不跨域)。负数次数按 0(禁用)钳位——负数没有语义, 放行会让「写错了的配置」变成一个比 0 更难解释的值。

type Request added in v0.38.0

type Request struct {
	// Slug 首次失败的执行者(也是候选枚举的起点)。
	Slug string
	// FirstErr **首次失败的原始错误**——判定面只读它(纪律①)。
	// 累计错误、改派说明一律不得放进这个字段。
	FirstErr error
	// SameDomain 同域改派次数上限(来自 Resolve;0=禁用同域改派)。
	SameDomain int
	// CrossDomain 是否允许瞬态跨域兜底一次(来自 Resolve)。
	CrossDomain bool
	// FailoverCandidates 候选枚举接缝(nil = 视为无候选)。
	FailoverCandidates CandidatesFunc
	// Attempt 执行步接缝(nil = 不执行任何改派,只给出档位与原错误)。
	Attempt AttemptFunc
	// OnEvent 每次改派尝试前的通知(nil = 不通知)。只在此处产出改派说明。
	OnEvent func(Event)
}

Request 一次改派环的输入。

type Result added in v0.38.0

type Result struct {
	// Slug 改派**成功**的候选;空 = 未改派或全部仍失败。
	Slug string
	// Err 累计错误:无改派时原样返回 FirstErr,有改派时按
	// `%w(已同域改派 X 仍失败)` / `%w(已跨域兜底 X 仍失败)` 累加(给人看)。
	// 改派成功时为 nil。
	Err error
	// Class 首次失败的档位(进事件载荷:宿主据此解释「为什么没继续改派」)。
	Class Class
	// Attempts 实际执行的改派次数(同域 + 跨域)。
	Attempts int
}

Result 改派环的结论。

func StickyFailover added in v0.38.0

func StickyFailover(ctx context.Context, req Request) Result

StickyFailover 改派环骨架(issue #169):同域 N 次 → 瞬态跨域一次 → fatal 直接终态。

次序与档位的关系

  1. **进环前判一次档**(Classify(FirstErr)),环内不再判——环会改写 Err, 二次判定读到的文本含改派说明(纪律①)。
  2. fatal:**不进任何改派**,原样返回(换执行者也是白跑,直接终态)。
  3. 同域:按候选序最多 SameDomain 次,任一次成功即返回。
  4. 跨域:仅当 CrossDomain 且档位是 transient,且只兜底**一次**。

与宿主的分工

本包不发事件、不落库、不排序候选(能力画像排序是宿主的领域资产): 事件走 OnEvent,候选走 FailoverCandidates,执行走 Attempt。 首次失败的环节状态落库(running→failed 之类)也在宿主侧——那是展示面, 不是「能不能再派」的判据。

Jump to

Keyboard shortcuts

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