contract

package
v0.8.1 Latest Latest
Warning

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

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

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

View Source
const (
	SevError = SeverityError
	SevWarn  = SeverityWarn
)

Layer / Severity 定义见 types.go(从原 rule 包迁入)。 这里保留 SevError / SevWarn 作为调用点常用的短别名。

Variables

Default 返回进程内共享的 Contract 单例。

contract.yaml 在编译期 embed 且运行期不变,解析结果可安全复用。 规则查询是热路径(每次 violation 都要回查 rule),不应每次重解析 YAML。

Functions

func ManifestSchemaIndex added in v0.7.0

func ManifestSchemaIndex(m *sdk.Manifest) map[string]*schema.Schema

ManifestSchemaIndex 从 manifest 的 schemas 声明建 wire id → Schema 索引。 wire id 形如 domain.name.v1(Ref.Wire()),是宿主 schema registry 的键。 与 PluginChecker 的语义规则检查相互独立:本函数只做声明投影,不做校验。

func RawYAML

func RawYAML() []byte

RawYAML 返回 embed 的 contract.yaml 原始字节。 供需要原文的调用方(如 MCP 的 plugin.contract 工具)直接读取,无需重新解析。

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 Load

func Load() (*Contract, error)

Load 解析 embed 的 contract.yaml 返回 Contract。 因为 contract.yaml 在编译时 embed,此函数不会因文件缺失失败。

func MustLoad

func MustLoad() *Contract

MustLoad 与 Load 相同但 panic on error。用于程序启动时。

func (*Contract) FilterRules

func (c *Contract) FilterRules(f RuleFilter) []Rule

Rules 按条件返回规则集,结果按 (topic, id) 稳定排序。

典型用法:

  • plugin.brief 默认档:RuleFilter{Severity: SeverityError}
  • plugin.brief 按主题:RuleFilter{Topic: "framing"}

func (*Contract) RuleByID

func (c *Contract) RuleByID(id string) (Rule, bool)

RuleByID 按 ID 查找单条规则,供 verify/explain 回查引用。

func (*Contract) Topics

func (c *Contract) Topics() []string

Topics 返回全部规则主题,按字母序去重。供 plugin.brief 列出可选 topic。

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 绕过类型安全。

func (*ItemsSpec) UnmarshalYAML

func (i *ItemsSpec) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML 实现 yaml.Unmarshaler,按节点类型分派到 TypeName 或 Spec。

type Layer

type Layer string

Layer 标识一条违规或规则所属的契约层。

SDK 现在仅承载 Protocol Semantic Rule 一层(semantic); stream 仅作为分层报告的展示维度保留。

const (
	LayerSemantic Layer = "semantic"
	LayerSchema   Layer = "schema" // schemas 声明层(v0.7.1 回归:注册期声明校验)
	LayerStream   Layer = "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:

  • schema 层:schemas 声明自洽(字段类型合法、引用可解析等,v0.7.1 回归)
  • semantic 层:semantic_rules 声明自洽

这是 plugin.verify 在“声明期”的入口。

func (*PluginChecker) CheckEvent

func (pc *PluginChecker) CheckEvent(m *sdk.Manifest, d *event.Draft) *Report

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。

func (*Report) Add

func (r *Report) Add(v Violation)

Add 追加一条违规。

func (*Report) ByLayer

func (r *Report) ByLayer() map[Layer][]Violation

ByLayer 按层聚合违规,便于分面板展示。

func (*Report) HasErrors

func (r *Report) HasErrors() bool

HasErrors 报告是否含任意 error 级违规。

func (*Report) JSON

func (r *Report) JSON() ([]byte, error)

JSON 序列化为 plugin.verify 的机器可读输出。

func (*Report) Merge

func (r *Report) Merge(o *Report)

Merge 把另一份报告(可空)的违规并入本报告。

func (*Report) Stats

func (r *Report) Stats() []LayerStat

Stats 计算每层 error/warn 计数,按稳定顺序返回。

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 端 只持有别名常量防拼错。

func (Rule) IsPlatform

func (r Rule) IsPlatform() bool

IsPlatform 报告是否为平台规则(gt. 前缀)。

func (Rule) Namespace

func (r Rule) Namespace() string

Namespace 返回规则命名空间(ID 的首段),如 "gt" 或领域根 "game"。 由 ID 派生,不手填,避免 namespace 与 ID 不一致。

type RuleFilter

type RuleFilter struct {
	Topic    string   // 非空则只返回该 topic
	Severity Severity // 非空则只返回该 severity
}

RuleFilter 描述规则筛选条件。零值表示不过滤。

type Severity

type Severity string

Severity 是规则严重级别(契约合规词汇)。 info 仅 domain 规则可用;平台规则只用 error | warn 两档。

const (
	SeverityError Severity = "error"
	SeverityWarn  Severity = "warn"
	SeverityInfo  Severity = "info"
)

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 字符串。

func (Violation) Error

func (v Violation) Error() string

func (Violation) Spec

func (v Violation) Spec() (Rule, bool)

Spec 回查本次违规对应的规则定义。 返回 false 说明 RuleID 不在 contract.yaml 中——schema 层部分规则由 schema 包独立 持有,属正常情况,不代表漂移。

Jump to

Keyboard shortcuts

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