rule

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Sep 10, 2026 License: MIT Imports: 7 Imported by: 0

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

View Source
const (
	SeverityError = "error"
	SeverityWarn  = "warn"
)
View Source
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

func MatchPair

func MatchPair(a, b PairHit) bool

MatchPair 报告两个 PairHit 是否可配对:同规则、键相等、 且各匹配一个不同 side(规则未声明 sides 时仅按键判定)。

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 ChildSpec

type ChildSpec struct {
	EventType string `yaml:"event_type"`
	SchemaID  string `yaml:"schema_id"`
}

ChildSpec 描述 extract 效果产出的子事件声明。

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

func RulesReport(rules []Rule) []Issue

RulesReport 是一组规则声明校验的总入口:逐条 Validate + 全局唯一性。 供 contract.PluginChecker 与宿主在注册期调用。

type Op

type Op string

Op 是判断操作闭集(§4)。Predicate 只做判断,不做业务逻辑; 第一版不引入 Expr、脚本、自定义函数,避免 SDK 演变成新的 DSL。

const (
	OpEq        Op = "eq"
	OpNeq       Op = "neq"
	OpExists    Op = "exists"
	OpNotExists Op = "not_exists"
	OpGt        Op = "gt"
	OpGte       Op = "gte"
	OpLt        Op = "lt"
	OpLte       Op = "lte"
	OpIn        Op = "in"
	OpNotIn     Op = "not_in"
	OpContains  Op = "contains"
	OpPrefix    Op = "prefix"
	OpSuffix    Op = "suffix"
)

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 显式表达)。

func (*Predicate) Evaluate

func (p *Predicate) Evaluate(doc gjson.Result) bool

Evaluate 对文档执行判断。doc 应为事件 JSON 的 gjson.Result。 声明非法的节点(调用方未先 validate)按 false 处理,不 panic。

func (*Predicate) UnmarshalYAML

func (p *Predicate) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML 支持两种 when 写法:

when: [ {path: seqId, op: neq, value: 0}, ... ]   # 序列 → 隐式 all
when: { all: [...] } / { any: [...] } / 叶子映射

序列简写是插件作者最常用的形态(多个条件 AND 起来),不做隐式转换的话 每个 manifest 都要多包一层 all。

type Result

type Result struct {
	Semantics []Semantic // annotate 命中的语义标签(去重保序)
	Pairs     []PairHit  // pair 命中(键 + 角色),实际配对由平台执行
	Children  []Child    // extract 产出的子事件
}

Result 是一组语义规则在单个事件上的评估产出。

func Evaluate

func Evaluate(rules []Rule, v event.Value) (Result, error)

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 兜底, 这里同样遵守"网络字节不使进程崩溃"的契约。

type Rule

type Rule struct {
	ID     string     `yaml:"id"`
	When   *Predicate `yaml:"when"`
	Effect Effect     `yaml:"effect"`
}

Rule 是一条语义规则:Predicate + Effect(§5)。

func (Rule) String

func (r Rule) String() string

String 返回规则的可读描述,用于 Violation Message 与日志。

func (Rule) Validate

func (r Rule) Validate() []Issue

Validate 校验单条规则声明的合法性。 返回空切片表示合法;问题以 Issue 形式返回(RuleID 为 gt.semantic.* 命名空间), 由上层 checker 转换为分层 Violation。

type Semantic

type Semantic string

Semantic 是 annotate 效果的语义标签闭集。 Error 与 Notification 是事件的语义属性,不是 Relation(§8)。

const (
	SemRequest      Semantic = "request"
	SemResponse     Semantic = "response"
	SemNotification Semantic = "notification"
	SemError        Semantic = "error"
)

Jump to

Keyboard shortcuts

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