Documentation
¶
Overview ¶
Package rule 实现 Protocol Semantic Rule(协议语义规则)。
定位:让插件告诉 GameTrace "对于我解析出来的 Event JSON,应该怎样判断、 提取和解释它的语义"。插件定义规则,平台执行规则:
Event JSON → GJSON 取值 → Predicate 判断 → Effect 产生语义
第一版 Effect 闭集只有三个:
- pair 配对(Request ↔ Response 等键相等关系)
- extract 提取(一个网络 Event 内的多个逻辑子事件)
- annotate 标注(request/response/notification/error 语义属性)
设计原则:Predicate 只做判断不做业务逻辑;不引入 Expr、脚本或自定义函数; Group / 高级因果关系(caused-by 等)在真实协议事实出现之前不做。
Index ¶
Constants ¶
const ( SeverityError = "error" SeverityWarn = "warn" )
const ( RuleIDRequired = "gt.semantic.rule-id-required" RuleIDFormat = "gt.semantic.rule-id-format" RuleIDDuplicate = "gt.semantic.rule-id-duplicate" WhenRequired = "gt.semantic.when-required" EffectRequired = "gt.semantic.effect-required" EffectUnknown = "gt.semantic.effect-unknown" OpUnknown = "gt.semantic.op-unknown" OpRequired = "gt.semantic.op-required" PathRequired = "gt.semantic.path-required" ValueRequired = "gt.semantic.value-required" ValueArrayRequired = "gt.semantic.value-array-required" CombinatorEmpty = "gt.semantic.combinator-empty" CombinatorMixed = "gt.semantic.combinator-mixed" PairKeyRequired = "gt.semantic.pair-key-required" PairSidesLimit = "gt.semantic.pair-sides-limit" ExtractSourceRequired = "gt.semantic.extract-source-required" ExtractChildRequired = "gt.semantic.extract-child-required" AnnotateSemanticRequired = "gt.semantic.annotate-semantic-required" AnnotateSemanticUnknown = "gt.semantic.annotate-semantic-unknown" EvaluateFailed = "gt.semantic.evaluate-failed" )
语义规则层的规则 ID(gt.semantic.* 命名空间)。 真源是 contract/contract.yaml 的 rules 段,这里只放常量防拼错。
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Child ¶
type Child struct {
RuleID string
EventType string // child.event_type
SchemaID string // child.schema_id
Index int // 在 Source 数组中的下标;Source 为对象时为 0
Value event.Value
}
Child 是一条 extract 规则产出的子事件。 子事件不是三条新网络包:宿主必须保留其与父事件的来源关系(§7)。
type Effect ¶
type Effect struct {
Type EffectType `yaml:"type"`
// pair:Key 是 GJSON path,其取值(字符串化)为配对键;
// Sides 是角色判定,两个事件键相等且各匹配一个不同 side 时配对。
// Sides 为空表示仅按键配对(角色由 When 区分)。
Key string `yaml:"key,omitempty"`
Sides []Predicate `yaml:"sides,omitempty"`
// extract:Source 是 GJSON path,指向数组(每个元素一个子事件)
// 或对象(单个子事件)。子事件保留父事件来源关系,由宿主挂接。
Source string `yaml:"source,omitempty"`
Child *ChildSpec `yaml:"child,omitempty"`
// annotate:命中时给事件打上的语义标签。
Semantic Semantic `yaml:"semantic,omitempty"`
}
Effect 是规则成立之后"意味着什么"。
字段按 Type 取用:
- pair: Key(必填)+ Sides(0 或 2 个)
- extract: Source(必填)+ Child(必填)
- annotate: Semantic(必填,闭集)
type EffectType ¶
type EffectType string
EffectType 是 Effect 种类闭集(§5 / §6)。
const ( EffectPair EffectType = "pair" EffectExtract EffectType = "extract" EffectAnnotate EffectType = "annotate" )
type Issue ¶
type Issue struct {
RuleID string // gt.semantic.* 规则 ID
Path string // 定位,如 semantic_rules[0].when.path
Message string
Severity string // SeverityError | SeverityWarn
}
Issue 是语义规则层校验发现的一条问题。 与 contract.Violation 解耦:rule 包不依赖 contract,由上层 checker 转换 (与 schema/state 包同模式)。
func RulesReport ¶
RulesReport 是一组规则声明校验的总入口:逐条 Validate + 全局唯一性。 供 contract.PluginChecker 与宿主在注册期调用。
type Op ¶
type Op string
Op 是判断操作闭集(§4)。Predicate 只做判断,不做业务逻辑; 第一版不引入 Expr、脚本、自定义函数,避免 SDK 演变成新的 DSL。
type PairHit ¶
type PairHit struct {
RuleID string
Key string // 配对键的字符串化取值
Side int // 命中的 sides 下标;规则未声明 sides 时为 -1
}
PairHit 是一条 pair 规则在单个事件上的命中。 平台侧配对语义:两个事件的 PairHit 满足 MatchPair 时构成 Request ↔ Response 式配对(同规则、键相等、各占一个不同 side)。
type Predicate ¶
type Predicate struct {
// 组合器(与单条件互斥)
All []Predicate `yaml:"all,omitempty"`
Any []Predicate `yaml:"any,omitempty"`
// 单条件
Path string `yaml:"path,omitempty"` // GJSON path,如 data.targetId
Op Op `yaml:"op,omitempty"`
Value any `yaml:"value,omitempty"` // 字面量:标量或数组
}
Predicate 是最小判断单元:GJSON path 取值后做一次判断(§4)。
两种形态互斥:
单条件: {path: seqId, op: neq, value: 0}
组合器: {all: [ ... ]} / {any: [ ... ]}
语义约定:除 exists / not_exists 外,所有操作在 path 取值不存在时判 false (缺失检查交给 exists / not_exists 显式表达)。
type Result ¶
type Result struct {
Semantics []Semantic // annotate 命中的语义标签(去重保序)
Pairs []PairHit // pair 命中(键 + 角色),实际配对由平台执行
Children []Child // extract 产出的子事件
}
Result 是一组语义规则在单个事件上的评估产出。
func Evaluate ¶
Evaluate 对一个事件的 payload 执行全部语义规则。
Event JSON → GJSON 取值 → Predicate 判断 → Effect 产生语义(§3 / §13)。 payload 经 Value.MarshalJSON 转 JSON 后用 GJSON path 取值;extract 的子事件 载荷从对应 JSON 元素还原为 event.Value(整数在范围内保持 Int 精度)。
非法规则(未先 Validate)被跳过,不 panic;decode 的 panic 边界由 SDK wrapper 兜底, 这里同样遵守"网络字节不使进程崩溃"的契约。