Documentation
¶
Index ¶
- func ReadManifest() ([]byte, error)
- func ResolveRegistryAddr() string
- func RunRegisterLoop(decodeFuncV2 DecodeFuncV2)
- func RunRegisterLoopWithOptions(decodeFuncV2 DecodeFuncV2, opts RegisterOptions)
- func ValidateManifest(m *Manifest) error
- type Capabilities
- type Capability
- type ContractDecl
- type DataSchema
- type DataSpec
- type DecodeFuncV2
- type Decoder
- type EventSpec
- type FieldDecl
- type Manifest
- type ManifestMeta
- type RegisterOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ReadManifest ¶
ReadManifest 读取当前目录的 plugin.yaml 并校验,返回原始 bytes。 用于 Register RPC 的 manifest 参数。 返回 error 当 plugin.yaml 不存在、格式非法或字段校验不通过时。
直接使用本 SDK 内置的 ParseManifest/ValidateManifest,不依赖 gametrace 根模块。
func ResolveRegistryAddr ¶
func ResolveRegistryAddr() string
ResolveRegistryAddr 返回 registry 端点地址。 优先级:GT_REGISTRY_ADDR 环境变量 > --registry= 命令行参数 > 默认 :9091(TCP)。
func RunRegisterLoop ¶
func RunRegisterLoop(decodeFuncV2 DecodeFuncV2)
RunRegisterLoop 是插件 main 的标准入口(非隧道模式,保持原有行为)。
func RunRegisterLoopWithOptions ¶
func RunRegisterLoopWithOptions(decodeFuncV2 DecodeFuncV2, opts RegisterOptions)
RunRegisterLoopWithOptions 是插件 main 的标准入口,支持隧道等可选行为。
工作流程(默认模式,opts 全零值时与旧版行为完全一致):
- 创建 Decoder gRPC server,监听 DecodeV2 端点 - 默认:本地 Unix socket(同机部署,路径含 PID 避免冲突) - 跨机器:设置 GT_DECODER_ADDR=host:port 监听 TCP; 并用 GT_DECODER_PUBLIC_ADDR(缺省回退为该 listen 地址)作为注册时上报的拨号地址
- 确定 registry 端点地址(GT_REGISTRY_ADDR 环境变量 > --registry flag > 默认 :9091) - 未显式设置时回退到 SDK 默认 :9091(见 ResolveRegistryAddr);显式设置可避免连到非预期地址
- 拨号 registry 并调用 Register RPC(传入上报地址和 plugin.yaml manifest bytes)
- 按返回的 instance_id 和 heartbeat_interval_sec 启动心跳 goroutine
- 心跳断开或 Register 失败时,指数退避重试(首次 1s,上限 30s)
隧道模式(opts.Tunnel=true):跳过第 1 步(不监听本地端点,宿主不回拨), Register(tunnel=true) 成功后打开 Connect 双向流,DecodeV2 经隧道帧完成。 opts.AuthToken 非空时,所有 RPC 附带 `authorization: Bearer <token>` metadata。
func ValidateManifest ¶
ValidateManifest 校验 manifest 必填字段与格式约束。 返回 nil 表示合法,返回 error 描述具体违规字段。
Types ¶
type Capability ¶ added in v0.7.0
type Capability string
Capability 是插件能力位闭集(§6.1)。
const ( CapDecode Capability = "decode" CapSchema Capability = "schema" CapState Capability = "state" )
type ContractDecl ¶
type ContractDecl struct {
Name string `yaml:"name"` // gt.plugin
Version int `yaml:"version"` // 1
}
ContractDecl 是 manifest 的语义契约版本声明(§3.2)。
type DataSchema ¶
DataSchema 描述 v1 data 子对象的字段结构。已随 EventSpec 一并废弃。
type DataSpec ¶
type DataSpec struct {
Schema DataSchema `yaml:"schema"`
}
DataSpec 描述 v1 业务 data 子对象的入口 schema。已随 EventSpec 一并废弃。
type DecodeFuncV2 ¶
type DecodeFuncV2 func(req *pb.DecodeRequest, stream pb.Decoder_DecodeV2Server) error
DecodeFuncV2 是 V2 解码回调的签名。 插件通过 stream.Send 发送零个或多个 DecodeResponseV2 结果消息, 最后发送一个 done=true 的消息标记该 input_id 的结果已全部发完。 如果完全没有结果,应至少发送一个 {input_id, done=true} 消息。
type Decoder ¶
type Decoder struct {
pb.UnimplementedDecoderServer
// contains filtered or unexported fields
}
Decoder 实现 pb.DecoderServer。 decodeFuncV2 是可选的 V2 解码回调;如果为 nil,则 DecodeV2 返回 Unimplemented。
type EventSpec ¶
type EventSpec struct {
Fields map[string]FieldDecl `yaml:"fields"` // 遗留:v1 _fields 内字段声明
Data DataSpec `yaml:"data"` // 遗留:v1 业务 data 子对象 schema
}
EventSpec 是 v1 遗留的事件结构声明。
【已废弃,仅为兼容旧 plugin.yaml 保留解析能力】 v1 时期 payload 是 JSON,平台语义放 _fields 子对象、业务语义放 data 子对象, 本结构就是那套形状的声明。v2 起 payload 改为 MsgPack 编码的 event.Value, 业务字段直接挂根对象,data/_fields 两个约定均已不存在 (见 contract.yaml 的 output_contract)。
新插件无需使用 EventSpec:业务语义请通过 Manifest.SemanticRules 声明 (Protocol Semantic Rule,见 docs/plugin-semantic-rules.md)。
type Manifest ¶
type Manifest struct {
APIVersion string `yaml:"api_version"` // gt.decoder/v2
Name string `yaml:"name"` // kebab-case
Protocol string `yaml:"protocol"` // 主协议名
Type string `yaml:"type"` // 固定 decoder
ProtocolVersion string `yaml:"protocol_version"` // 可选,游戏协议版本
Hints []string `yaml:"hints"` // 可选,匹配提示
Event EventSpec `yaml:"event"` // 可选,遗留字段声明,见 EventSpec
Contract *ContractDecl `yaml:"contract,omitempty"` // 语义契约版本块(§3)
SemanticRules []rule.Rule `yaml:"semantic_rules,omitempty"` // Protocol Semantic Rule(插件定义协议语义,平台执行)
Schemas []schema.Schema `yaml:"schemas"` // 完整 schema 声明(宿主实际消费的是这里)
States []state.Subject `yaml:"states,omitempty"` // subject 状态形状声明(capabilities.state 时强制)
Capabilities Capabilities `yaml:"capabilities,omitempty"` // 能力位(§6)
Meta ManifestMeta `yaml:"meta"` // 可选,元数据
}
Manifest 是 plugin.yaml 的 Go 表示。 插件通过 Register RPC 传 plugin.yaml 原文,主程序 ParseManifest 后 ValidateManifest 校验。 字段语义参考 github.com/OwnSecurityGuard/gt-plugin-sdk 内置 contract 的 manifest_schema。
该类型定义与校验逻辑内置于 SDK,使插件模块无需依赖 gametrace 根模块即可完成 manifest 解析与校验(SDK 的 ReadManifest 直接复用本文件函数)。
层次沿革:v1 遗留 event 块(已废弃)→ 语义契约 v1 的 schemas/states 声明层 曾在 spec_version 5/6 短暂移除,v0.7.0 起**恢复**(数据形状声明与语义规则是互补 关系而非取代:schemas 描述数据形状,semantic_rules 描述协议语义)→ Protocol Semantic Rule(semantic_rules,§10):插件定义协议语义,平台执行。 framing/time_authority/state_ordering 等其余各层声明保持移除,不再回归。
func ParseManifest ¶
ParseManifest 解析 plugin.yaml 原文返回 Manifest。 不做字段校验,校验由 ValidateManifest 完成。 解析后执行 normalizeSchemas:遗留 indexable_fields 块升格为对应 Field 的 queryable + alias(语义契约 v1 §5,v0.5.0 起的既有行为,v0.7.1 回归)。
type ManifestMeta ¶
type ManifestMeta struct {
Author string `yaml:"author"`
Description string `yaml:"description"`
Homepage string `yaml:"homepage"`
}
ManifestMeta 是 manifest 的元数据段。
type RegisterOptions ¶
type RegisterOptions struct {
// Tunnel 为 true 时走反向隧道模式:Register(tunnel=true) 成功后,
// 插件在同一连接上打开 Connect 双向流,DecodeV2 经隧道帧完成,
// 宿主不再回拨 socket_path(此时也不需要启动本地 Decoder server)。
Tunnel bool
// AuthToken 非空时,注册/心跳/隧道请求附带
// `authorization: Bearer <token>` gRPC metadata。
AuthToken string
}
RegisterOptions 是注册行为的可选项,全部为零值时行为与旧版完全一致。
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contract 承载 GameTrace Decoder Plugin API 契约(contract.yaml)。
|
Package contract 承载 GameTrace Decoder Plugin API 契约(contract.yaml)。 |
|
examples
|
|
|
http-stream-decoder
command
Command http-stream-decoder is a complete, runnable GameTrace decoder plugin for HTTP over TCP.
|
Command http-stream-decoder is a complete, runnable GameTrace decoder plugin for HTTP over TCP. |
|
Package framing turns a captured DecodeRequest.payload into L7 application bytes.
|
Package framing turns a captured DecodeRequest.payload into L7 application bytes. |
|
Package rule 实现 Protocol Semantic Rule(协议语义规则)。
|
Package rule 实现 Protocol Semantic Rule(协议语义规则)。 |
|
Package schema defines the GTA semantic schema model: declared types, fields, refs, references, and the validation/evolution rules that turn a plugin's schema declaration into a contract the host can enforce.
|
Package schema defines the GTA semantic schema model: declared types, fields, refs, references, and the validation/evolution rules that turn a plugin's schema declaration into a contract the host can enforce. |
|
Package state 实现 Layer 4 — State Contract(§9)。
|
Package state 实现 Layer 4 — State Contract(§9)。 |