Documentation
¶
Overview ¶
Package contract 承载 GameTrace Decoder Plugin API 契约(contract.yaml)。
contract.yaml 是插件与宿主之间线上协议的 SSOT,描述 RPC 契约、link_types、 产出编码、payload 保留字段、manifest schema 与机器可读的规则集。
该文件自 gametrace/pkg/plugin/contract/ 迁入本 SDK。契约现单向流动:SDK 定义, 宿主(gametrace)通过本包消费,杜绝两仓库各持一份导致的漂移。
Index ¶
- Constants
- Variables
- func ManifestSchemaIndex(m *sdk.Manifest) map[string]*schema.Schema
- func RawYAML() []byte
- type Contract
- type ContractBlock
- type FieldSpec
- type HeartbeatSpec
- type ItemsSpec
- type Layer
- type LayerStat
- type LinkTypesSpec
- type ManifestSchemaSpec
- type MethodSpec
- type OutputContractSpec
- type PluginChecker
- type RPCSpec
- type Report
- type Rule
- type RuleFilter
- type Severity
- type Violation
Constants ¶
const ( SevError = SeverityError SevWarn = SeverityWarn )
Layer / Severity 定义见 types.go(从原 rule 包迁入)。 这里保留 SevError / SevWarn 作为调用点常用的短别名。
Variables ¶
var Default = sync.OnceValue(MustLoad)
Default 返回进程内共享的 Contract 单例。
contract.yaml 在编译期 embed 且运行期不变,解析结果可安全复用。 规则查询是热路径(每次 violation 都要回查 rule),不应每次重解析 YAML。
Functions ¶
func ManifestSchemaIndex ¶ added in v0.7.0
ManifestSchemaIndex 从 manifest 的 schemas 声明建 wire id → Schema 索引。 wire id 形如 domain.name.v1(Ref.Wire()),是宿主 schema registry 的键。 与 PluginChecker 的语义规则检查相互独立:本函数只做声明投影,不做校验。
Types ¶
type Contract ¶
type Contract struct {
SpecVersion int `yaml:"spec_version"`
APIVersion string `yaml:"api_version"`
Contract ContractBlock `yaml:"contract"` // 语义契约版本块(新增,§3)
RPC RPCSpec `yaml:"rpc"`
LinkTypes LinkTypesSpec `yaml:"link_types"`
RegistryDiscovery []map[string]string `yaml:"registry_discovery"` // 每项单键 map: {env|flag|default: 值}
Heartbeat HeartbeatSpec `yaml:"heartbeat"`
OutputContract OutputContractSpec `yaml:"output_contract"`
ReservedPayloadFields map[string]FieldSpec `yaml:"reserved_payload_fields"`
ManifestSchema ManifestSchemaSpec `yaml:"manifest_schema"`
Rules []Rule `yaml:"rules"`
}
Contract 是 contract.yaml 的 Go 表示。
func (*Contract) FilterRules ¶
func (c *Contract) FilterRules(f RuleFilter) []Rule
Rules 按条件返回规则集,结果按 (topic, id) 稳定排序。
典型用法:
- plugin.brief 默认档:RuleFilter{Severity: SeverityError}
- plugin.brief 按主题:RuleFilter{Topic: "framing"}
type ContractBlock ¶
type ContractBlock struct {
Name string `yaml:"name"` // gt.plugin
Version int `yaml:"version"`
Components map[string]int `yaml:"components"` // semantic 组件的版本(SDK 现仅承载 Protocol Semantic Rule 一层)
}
ContractBlock 是语义契约版本块(§3)。
type FieldSpec ¶
type FieldSpec struct {
Type string `yaml:"type"`
Description string `yaml:"description,omitempty"`
Pattern string `yaml:"pattern,omitempty"` // 正则约束,如 name 的 kebab-case
Optional bool `yaml:"optional,omitempty"` // manifest_schema 中标记非必填
Enum []string `yaml:"enum,omitempty"`
Fallback string `yaml:"fallback,omitempty"`
ConsumedBy string `yaml:"consumed_by,omitempty"`
Validation string `yaml:"validation,omitempty"`
Items *ItemsSpec `yaml:"items,omitempty"`
Required []string `yaml:"required,omitempty"`
Fields map[string]FieldSpec `yaml:"fields,omitempty"`
}
FieldSpec 描述字段的类型约束,用于 reserved_payload_fields 与 manifest_schema。
type HeartbeatSpec ¶
type HeartbeatSpec struct {
DefaultIntervalSec int `yaml:"default_interval_sec"`
OfflineTimeoutSec int `yaml:"offline_timeout_sec"`
}
HeartbeatSpec 描述心跳协议默认参数。
type ItemsSpec ¶
type ItemsSpec struct {
TypeName string // 当 items 是标量字符串时的元素类型名
Spec *FieldSpec // 当 items 是映射对象时的完整字段约束
}
ItemsSpec 表示 type=array 字段的元素约束。 YAML 中 items 有两种形态:
- 标量字符串(如 hints: { items: string }),仅声明元素类型名
- 映射对象(如 _state_changes.items 含 required/fields),描述完整字段约束
用 UnmarshalYAML 区分两种形态,避免用 any 绕过类型安全。
type Layer ¶
type Layer string
Layer 标识一条违规或规则所属的契约层。
SDK 现在仅承载 Protocol Semantic Rule 一层(semantic); stream 仅作为分层报告的展示维度保留。
type LayerStat ¶
type LayerStat struct {
Layer Layer `json:"layer"`
Errors int `json:"errors"`
Warns int `json:"warns"`
}
LayerStat 是单层违规计数。
type LinkTypesSpec ¶
type LinkTypesSpec struct {
Standard map[int]string `yaml:"standard"`
Custom map[int]string `yaml:"custom"`
}
LinkTypesSpec 描述标准与自定义链路层类型枚举。
type ManifestSchemaSpec ¶
type ManifestSchemaSpec struct {
Required []string `yaml:"required"`
Fields map[string]FieldSpec `yaml:"fields"`
}
ManifestSchemaSpec 描述 plugin.yaml manifest 的校验规则。
type MethodSpec ¶
type MethodSpec struct {
Type string `yaml:"type,omitempty"` // "bidi_stream" 等
Request map[string]string `yaml:"request"`
Response map[string]string `yaml:"response"`
}
MethodSpec 描述单个 RPC 方法的请求/响应结构。
type OutputContractSpec ¶
type OutputContractSpec struct {
Encoding string `yaml:"encoding"`
RootKind string `yaml:"root_kind"`
Builder string `yaml:"builder"`
Marshal string `yaml:"marshal"`
Unmarshal string `yaml:"unmarshal"`
Notes []string `yaml:"notes"`
}
OutputContractSpec 描述 v2 的事件产出编码约定。 v1 曾用 JSON 字符串产出并区分 data / _fields 子对象,v2 起统一为 tagged MsgPack。
type PluginChecker ¶
type PluginChecker struct {
// contains filtered or unexported fields
}
PluginChecker 是 Protocol Semantic Rule 的校验器。
它是 SDK 现在唯一保留的契约检查层:插件声明语义规则(rule 包), 平台在注册期与运行期执行这些规则。调用方接口(Check / CheckEvent)保持不变。
各层产出 *Report 后由上层 Merge,单份 Report 内可按 Layer 聚合(ByLayer / Stats)。
func NewPluginChecker ¶
func NewPluginChecker() *PluginChecker
NewPluginChecker 构造一个以 embed 契约为基准的校验器。
func (*PluginChecker) Check ¶
func (pc *PluginChecker) Check(m *sdk.Manifest) *Report
Check 对解析后的 manifest 跑语义规则声明期检查,返回完整 Report。 这是 plugin.verify 在“声明期”的入口:验证插件声明的 Protocol Semantic Rule 自洽。
func (*PluginChecker) CheckEvent ¶
CheckEvent 对单条解码事件跑语义规则运行期检查: 规则评估失败即契约违规(payload 无法转 JSON 等情况)。 annotate / pair / extract 的命中是平台执行事实,不在 verify 层判定对错。
type RPCSpec ¶
type RPCSpec struct {
RegistryService string `yaml:"registry_service"`
DecoderService string `yaml:"decoder_service"`
Methods map[string]MethodSpec `yaml:"methods"`
}
RPCSpec 描述 PluginRegistry 与 Decoder 两个 gRPC 服务的契约。
type Report ¶
type Report struct {
Violations []Violation `json:"violations"`
}
Report 是分层校验的总报告。PluginChecker 各子检查器产出 *Report 后由上层 Merge。
type Rule ¶
type Rule struct {
ID string `yaml:"id" json:"id"`
Topic string `yaml:"topic" json:"topic"`
Layer Layer `yaml:"layer,omitempty" json:"layer,omitempty"`
Severity Severity `yaml:"severity" json:"severity"`
Statement string `yaml:"statement" json:"statement"`
Detail string `yaml:"detail,omitempty" json:"detail,omitempty"`
DocRef string `yaml:"doc_ref" json:"doc_ref"`
Aliases []string `yaml:"aliases,omitempty" json:"aliases,omitempty"` // 旧裸 ID
AppliesTo []string `yaml:"applies_to,omitempty" json:"applies_to,omitempty"` // schema/event/subject ID
Since string `yaml:"since,omitempty" json:"since,omitempty"`
Deprecated bool `yaml:"deprecated,omitempty" json:"deprecated,omitempty"`
}
Rule 是一条机器可读的插件开发规则(契约合规词汇)。
它是 contract.yaml rules 段的 Go 表示,也是 plugin.brief / plugin.verify / plugin.explain 三个工具的共享词汇:brief 按 topic/severity 筛选返回,verify 用它 标注违规项,explain 用它引用归因依据。规则 ID 是唯一真源(contract.yaml),Go 端 只持有别名常量防拼错。
type RuleFilter ¶
RuleFilter 描述规则筛选条件。零值表示不过滤。
type Severity ¶
type Severity string
Severity 是规则严重级别(契约合规词汇)。 info 仅 domain 规则可用;平台规则只用 error | warn 两档。
type Violation ¶
type Violation struct {
RuleID string
Message string
Layer Layer
Severity Severity
Path string // 定位路径,如 schemas[0].fields.hp / hp
DocRef string // 来自 contract.yaml 的 rule doc_ref
}
Violation 表示一次契约违规。
RuleID 取自 contract.yaml 的 rules 段(schema 层部分规则由 schema 包独立持有, 不在 contract.yaml);拿到 Violation 的一方可用 Spec() 回查规则原文、严重级别与 文档位置,无需解析 Message 字符串。