Documentation
¶
Index ¶
- Variables
- func Done(inputID string) *pb.DecodeResponseV2
- func SplitReservedKeys(v Value) (Value, Value, Value)
- type Aggregator
- type Draft
- type Event
- func NewEvent(sessionID string, eventType EventType, schemaID string, source SourceID, ...) *Event
- func NewEventWithTime(sessionID string, eventType EventType, schemaID string, source SourceID, ...) *Event
- func NewEventWithTrace(sessionID string, eventType EventType, schemaID string, source SourceID, ...) *Event
- func (e *Event) ExtractStateChanges() []StateChange
- func (e *Event) Get(key string) (Value, bool)
- func (e *Event) GetID() EventID
- func (e *Event) GetSessionID() string
- func (e *Event) GetTimestamp() time.Time
- func (e *Event) GetType() EventType
- func (e *Event) MetaValue(key string) (Value, bool)
- func (e *Event) Validate() error
- func (e *Event) WithAnalysis(analysis Value) *Event
- func (e *Event) WithCausation(causationID EventID) *Event
- func (e *Event) WithCorrelation(correlationID string) *Event
- func (e *Event) WithMeta(meta Value) *Event
- func (e *Event) WithOrigin(originID EventID) *Event
- func (e *Event) WithTrace(trace TraceContext) *Event
- type EventContext
- type EventID
- type EventType
- type Identity
- type LinkType
- type Metric
- type Packet
- type Payload
- type SourceID
- type StateChange
- type TCPFlags
- type TimestampedEvent
- type TraceContext
- func (t TraceContext) HasCausation() bool
- func (t TraceContext) HasCorrelation() bool
- func (t TraceContext) HasOrigin() bool
- func (t TraceContext) IsZero() bool
- func (t TraceContext) WithCausation(causationID EventID) TraceContext
- func (t TraceContext) WithCorrelation(correlationID string) TraceContext
- func (t TraceContext) WithOrigin(originID EventID) TraceContext
- type Value
- func MergeReservedKeys(business, meta, analysis Value) Value
- func UnmarshalValueMsgpack(data []byte) (Value, error)
- func ValueArray(a []Value) Value
- func ValueBool(b bool) Value
- func ValueBytes(b []byte) Value
- func ValueFloat(f float64) Value
- func ValueFromAny(v any) Value
- func ValueFromJSON(data []byte) (Value, error)
- func ValueFromJSONMap(data []byte) (Value, error)
- func ValueFromMap(m map[string]any) Value
- func ValueFromSlice(s []any) Value
- func ValueInt(i int64) Value
- func ValueNull() Value
- func ValueObject(m map[string]Value) Value
- func ValueString(s string) Value
- func ValueUint(u uint64) Value
- func (v Value) Append(item Value) (Value, error)
- func (v Value) AsArray() ([]Value, bool)
- func (v Value) AsBool() (bool, bool)
- func (v Value) AsBytes() ([]byte, bool)
- func (v Value) AsFloat() (float64, bool)
- func (v Value) AsInt() (int64, bool)
- func (v Value) AsObject() (map[string]Value, bool)
- func (v Value) AsString() (string, bool)
- func (v Value) AsUint() (uint64, bool)
- func (v Value) Delete(key string) (Value, error)
- func (v Value) Equal(other Value) bool
- func (v Value) Get(key string) (Value, bool)
- func (v Value) GetByPath(path string) (Value, bool)
- func (v Value) Index(i int) (Value, bool)
- func (v Value) IsNull() bool
- func (v Value) Len() int
- func (v Value) MarshalJSON() ([]byte, error)
- func (v Value) MarshalMsgpack() ([]byte, error)
- func (v Value) Merge(other Value) (Value, error)
- func (v Value) Set(key string, val Value) (Value, error)
- func (v Value) String() string
- func (v Value) ToAny() any
- func (v Value) ToJSON() ([]byte, error)
- func (v Value) ToJSONIndent() ([]byte, error)
- func (v *Value) UnmarshalJSON(data []byte) error
- type ValueKind
Constants ¶
This section is empty.
Variables ¶
var ( ErrMissingEventID = errors.New("missing event ID") ErrMissingEventType = errors.New("missing event type") ErrMissingTimestamp = errors.New("missing timestamp") )
错误定义
Functions ¶
func Done ¶
func Done(inputID string) *pb.DecodeResponseV2
Done 返回一个仅回显 input_id 的终止响应(done=true),供一次输入收尾。
Types ¶
type Aggregator ¶
type Aggregator interface {
Add(event TimestampedEvent, ctx map[string]any) error
Flush() []Metric // 输出已关闭窗口的指标
FinalFlush() []Metric // 输出已关闭窗口 + 当前窗口,用于 shutdown
Window() time.Duration
}
Aggregator 是跨包聚合器接口。 Add 接收 TimestampedEvent,使聚合逻辑无需在不同事件版本之间转换。
type Draft ¶
type Draft struct {
// Type 是 event_type,描述"发生了什么"(如 game.player.moved)。
Type EventType
// SchemaRef 是 schema 的线上串(如 game.player.v1),即 Ref.Wire()。
SchemaRef string
// Value 是解码出的业务载荷(根必须是 object)。
Value Value
// Meta 是元信息(可选):direction、msg_name、role、is_push 等由系统附加的结构化字段。
// 传输契约中对应 DecodeResponseV2.meta_msgpack;IsNull() 时不传输。
Meta Value
// Analysis 是分析(可选):_state_changes、entity、entity_type、entity_id、change_count 等
// 平台推导/投影所需的数据。传输契约中对应 DecodeResponseV2.analysis_msgpack;IsNull() 时不传输。
Analysis Value
// CorrelationKey 由插件填的业务关联键(→ Trace.CorrelationID,宿主规范化)。
CorrelationKey string
// CausationInputID 由插件填的因果输入 id(→ Trace.CausationID,宿主解析)。
CausationInputID string
}
Draft 是插件侧的事件产出。它缺少宿主补齐的 Identity/Trace(EventID、 SessionID、Source、Timestamp、CausationID、OriginID 等由宿主填充),因此是 "草稿"而非完整 Event(§7.3)。
设计约定:插件只负责 type / schema / payload / 可选的关联 hint;宿主补全身份后 才是 Event。这样 payload-non-empty / input-id-echo / event-value-required 三条 传输层规则在 SDK 里天然满足,插件无需手工拼 DecodeResponseV2。
注意:SchemaRef 用线上串形态(如 "game.player.v1")而非 schema.Ref, 以遵守包依赖 DAG(event 不得 import schema/state,见 §4.3)。
func (Draft) ToResponse ¶
func (d Draft) ToResponse(inputID string) (*pb.DecodeResponseV2, error)
ToResponse 把 Draft 编码为一条非终止的 DecodeResponseV2。 自动满足 input-id-echo(input_id 原样回显)、payload-non-empty、 event-value-required(经 Value.MarshalMsgpack)。
type Event ¶
type Event struct {
// Identity 描述事件的身份信息
Identity Identity
// Trace 描述事件的执行链路上下文(Debug Trace)
Trace TraceContext
// Context 描述事件的网络上下文
Context EventContext
// Payload 包含事件的实际数据
Payload Payload
// Meta 是元信息(可选):direction、msg_name、role、is_push 等由系统附加的结构化字段。
Meta Value
// Analysis 是分析(可选):_state_changes、entity 等平台推导/投影所需的数据。
Analysis Value
}
Event 是事件模型,遵循 Event Sourcing 原则: Event = Identity + Trace + Context + Payload
核心原则: 1. 不可变性(Immutable):创建后不可修改 2. 追加写入(Append-only):只能新增,不能更新或删除 3. 事实表示:代表已发生的事件,而非命令或请求
func NewEvent ¶
func NewEvent(sessionID string, eventType EventType, schemaID string, source SourceID, payload Value, ctx EventContext) *Event
NewEvent 创建新的 Event 自动生成 UUIDv7 作为 ID,使用当前时间作为 Timestamp
func NewEventWithTime ¶
func NewEventWithTime(sessionID string, eventType EventType, schemaID string, source SourceID, payload Value, ts time.Time, ctx EventContext) *Event
NewEventWithTime 创建新的 Event,使用指定的时间戳
func NewEventWithTrace ¶
func NewEventWithTrace(sessionID string, eventType EventType, schemaID string, source SourceID, payload Value, trace TraceContext, ctx EventContext) *Event
NewEventWithTrace 创建带有执行链路上下文的 Event
func (*Event) ExtractStateChanges ¶
func (e *Event) ExtractStateChanges() []StateChange
ExtractStateChanges 从 Analysis 的 _state_changes 字段提取状态变更; Analysis 为空时兜底读取 Payload.Value 的保留键(兼容旧模型)。
func (*Event) MetaValue ¶
MetaValue 返回 _meta 中指定键的值,不存在时返回 false。 _meta 用于存放 direction、flow_id、msg_name 等由系统附加的结构化字段。
func (*Event) WithAnalysis ¶ added in v0.8.0
WithAnalysis 设置分析数据,返回新的 Event(不可变性)。
func (*Event) WithCausation ¶
WithCausation 设置直接原因事件 ID,返回新的 Event
func (*Event) WithCorrelation ¶
WithCorrelation 设置关联的业务流程 ID,返回新的 Event
func (*Event) WithOrigin ¶
WithOrigin 设置原始来源事件 ID,返回新的 Event
func (*Event) WithTrace ¶
func (e *Event) WithTrace(trace TraceContext) *Event
WithTrace 设置执行链路上下文,返回新的 Event(不可变性)
type EventContext ¶
type EventContext struct {
FlowID string `msgpack:"flow_id,omitempty"`
RawPacketID string `msgpack:"raw_packet_id,omitempty"`
MessageOrdinal int `msgpack:"message_ordinal,omitempty"`
Direction string `msgpack:"direction,omitempty"`
}
EventContext 描述事件的网络上下文,跨协议通用。不放业务数据。
func UnmarshalContextMsgpack ¶
func UnmarshalContextMsgpack(data []byte) (EventContext, error)
UnmarshalContextMsgpack 从 MsgPack 字节解码 EventContext。
func (EventContext) MarshalMsgpack ¶
func (c EventContext) MarshalMsgpack() ([]byte, error)
MarshalMsgpack 将 EventContext 编码为 MsgPack 字节。
type EventID ¶
type EventID string
EventID 是事件的全局唯一标识符 使用 UUIDv7 格式,保证时间有序且全局唯一
func NewEventID ¶
func NewEventID() EventID
NewEventID 生成新的 UUIDv7 事件 ID UUIDv7 基于时间戳,保证时间有序且全局唯一 格式:48bit timestamp(ms) + 4bit version(7) + 12bit counter + 2bit variant(10) + 62bit rand 同一毫秒内使用 12-bit 单调计数器,避免冲突并保持时间排序。
type EventType ¶
type EventType string
EventType 是事件类型的字符串表示 例如:"network.packet", "http.request", "game.login"
type Identity ¶
type Identity struct {
// ID 是事件的全局唯一标识符(UUIDv7)
ID EventID
// SessionID 是捕获或分析会话的标识
SessionID string
// Type 是事件类型(如 "network.packet", "http.request")
Type EventType
// SchemaID 是载荷的 schema 版本标识(如 "http.request.v1")
SchemaID string
// Source 是事件的创建者/来源
Source SourceID
// Timestamp 是事件发生的时间
Timestamp time.Time
}
Identity 描述事件的身份信息 回答"这是什么事件?"的问题
func NewIdentity ¶
NewIdentity 创建新的 Identity 自动生成 UUIDv7 作为 ID,使用当前时间作为 Timestamp
type LinkType ¶
type LinkType int
LinkType 是链路层类型,使用 int 以支持标准 DLT 和自定义扩展值。
const ( LinkTypeNull LinkType = 0 LinkTypeEthernet LinkType = 1 LinkTypeLoop LinkType = 108 LinkTypeLinuxSLL LinkType = 113 LinkTypeRaw LinkType = 101 LinkTypeIPv4 LinkType = 228 LinkTypeIPv6 LinkType = 229 LinkTypeIEEE80211 LinkType = 105 )
标准 DLT 值,与 gopacket/layers.LinkType 保持一致。
const ( // LinkTypeRawIP 表示没有链路层封装的原始 IP 包(如 tun/Android VPN service 输出)。 LinkTypeRawIP LinkType = 1000 + iota // LinkTypeProxyPayload 表示代理层拿到的应用层 payload,没有 IP/TCP 头。 LinkTypeProxyPayload // LinkTypeTLSPlaintext 表示 TLS 解密后的明文数据。 LinkTypeTLSPlaintext )
自定义 LinkType,从 1000 开始分配,避免与标准 DLT 冲突。
func LinkTypeFromLayers ¶
LinkTypeFromLayers 将 gopacket/layers.LinkType 转换为 event.LinkType。
type Packet ¶
type Packet struct {
ID string // 原始包在 raw_packets 表中的唯一标识;为空时由存储层生成
Timestamp time.Time
Raw []byte
LinkType LinkType
Src netip.AddrPort
Dst netip.AddrPort
Protocol string
Metadata map[string]any
TCPFlags TCPFlags // 仅 TCP 协议有效
}
Packet 是抓取层输出,也是整个系统统一的数据载体。
type Payload ¶
type Payload struct {
// SchemaID 是数据的 schema 版本标识
// 例如:"game.login.v1", "http.request.v2"
// Schema 变更时创建新版本,永不修改现有 schema
SchemaID string
// Value 是事件的实际数据内容
Value Value
}
Payload 包含事件的实际数据 使用 SchemaID 标识数据结构版本,Value 存储实际内容
func UnmarshalPayloadMsgpack ¶
UnmarshalPayloadMsgpack 从 MsgPack 格式解码 Payload
func (Payload) MarshalMsgpack ¶
MarshalMsgpack 将 Payload 编码为 MsgPack 格式
func (Payload) ToJSONIndent ¶
ToJSONIndent 将 Payload 的 Value 编码为格式化的 JSON 字节数组
type SourceID ¶
type SourceID string
SourceID 是事件的创建者/来源 例如:"tcp-capture", "http-decoder", "ai-analyzer"
type StateChange ¶
type StateChange struct {
SubjectType string `msgpack:"subject_type"`
SubjectID string `msgpack:"subject_id"`
Op string `msgpack:"op"`
Path string `msgpack:"path"`
Before Value `msgpack:"before,omitempty"`
After Value `msgpack:"after,omitempty"`
Version int64 `msgpack:"version,omitempty"`
Metadata Value `msgpack:"metadata,omitempty"`
}
StateChange 描述一个通用状态变更投影。
func ExtractStateChanges ¶
func ExtractStateChanges(v Value) []StateChange
ExtractStateChanges 从 Value 的 _state_changes 字段提取 StateChange 列表。
func (StateChange) Validate ¶
func (sc StateChange) Validate() error
Validate 校验 StateChange 的最小必填字段与 op 取值。 返回的 error 描述具体缺失/非法项,供调用方决定是否丢弃或记录。
type TCPFlags ¶
TCPFlags 描述 TCP 控制位。仅 Protocol=="tcp" 时有效。 用于判断连接关闭方(哪一侧先发 FIN/RST)等 TCP 层事件。
func (TCPFlags) HasCloseFlags ¶
HasCloseFlags 返回是否包含连接关闭相关标志位(FIN 或 RST)。
type TimestampedEvent ¶
TimestampedEvent 是带时间戳的事件抽象,供 Aggregator 等跨版本组件使用。
type TraceContext ¶
type TraceContext struct {
// CausationID 是直接前驱事件的 ID(OTel: parent span id)。
// 例如:LoginResponse 的 CausationID 指向触发它的 LoginRequest。
CausationID EventID
// CorrelationID 是同一业务流程/请求-响应组的聚合键(OTel: trace id)。
// 网络天然异步:一次 AttackRequest 可能对应 AttackResult、DamageNotify、
// BuffUpdate 多条不同方向、不同类型的消息,靠 CorrelationID 聚合。
CorrelationID string
// OriginID 是最初来源的 ID,用于快速溯源。
// 例如:从同一原始包派生的事件 OriginID 都指向该包 ID;
// 回放场景下所有事件可标记为来自同一个 replay run。
OriginID EventID
}
TraceContext 描述事件的执行链路上下文(Debug Trace)。
它回答的是"这个事件在运行链路中从哪里来、属于哪次业务操作"—— 是系统运行过程中真实存在的链路事实,不是推理出来的知识关系。
与 OpenTelemetry Trace Model 的概念对应:
OTel TraceID ↔ CorrelationID(一次业务操作/请求-响应组的聚合键) OTel SpanID ↔ Event.ID(每个事件即一个 span) OTel ParentSpanID ↔ CausationID(直接前驱事件)
典型用途:
- Protocol Inspector 按同一 CorrelationID 聚合 LoginRequest/LoginResponse
- compare_sessions 比较两个 session 的 Execution Trace
- Replay 场景用 OriginID 标记 "这些事件来自 replay #N"
func NewTraceContext ¶
func NewTraceContext(causationID EventID, correlationID string, originID EventID) TraceContext
NewTraceContext 创建新的 TraceContext。
func (TraceContext) HasCausation ¶
func (t TraceContext) HasCausation() bool
HasCausation 检查是否有直接前驱。
func (TraceContext) HasCorrelation ¶
func (t TraceContext) HasCorrelation() bool
HasCorrelation 检查是否有关联的业务流程。
func (TraceContext) WithCausation ¶
func (t TraceContext) WithCausation(causationID EventID) TraceContext
WithCausation 设置直接前驱事件 ID。
func (TraceContext) WithCorrelation ¶
func (t TraceContext) WithCorrelation(correlationID string) TraceContext
WithCorrelation 设置关联的业务流程 ID。
func (TraceContext) WithOrigin ¶
func (t TraceContext) WithOrigin(originID EventID) TraceContext
WithOrigin 设置原始来源 ID。
type Value ¶
type Value struct {
Kind ValueKind
Bool bool
Int int64
Uint uint64
Float float64
Str string
Bytes []byte
Array []Value
Object map[string]Value
}
Value 是事件载荷中的值类型,支持多种数据类型 使用 tagged union 模式,通过 Kind 字段标识实际存储的类型
func MergeReservedKeys ¶ added in v0.8.0
MergeReservedKeys 把三段合并回扁平 Value(存储写入/旧插件兼容用)。 与 SplitReservedKeys 互为逆操作。
func UnmarshalValueMsgpack ¶
UnmarshalValueMsgpack 从 MsgPack 格式解码 Value
func ValueFromAny ¶
ValueFromAny 将 any 类型转换为 Value 支持的类型:nil, bool, int/int8/int16/int32/int64, uint/uint8/uint16/uint32/uint64, float32/float64, string, []byte, []any, map[string]any 未知类型退化为字符串表示,避免静默丢失数据。
func ValueFromJSON ¶
ValueFromJSON 从 JSON 字节数组解析 Value
func ValueFromJSONMap ¶
ValueFromJSONMap 从 JSON 字节数组解析为 map[string]any,然后转换为 Value。
func ValueFromMap ¶
ValueFromMap 从 map[string]any 创建 Value
func (Value) MarshalJSON ¶
MarshalJSON 将 Value 编码为 JSON 格式
func (Value) MarshalMsgpack ¶
MarshalMsgpack 将 Value 编码为 MsgPack 格式
func (Value) ToAny ¶
ToAny 将 Value 转换为 Go 原生类型 Null -> nil Bool -> bool Int -> int64 Uint -> uint64 Float -> float64 String -> string Bytes -> []byte Array -> []any Object -> map[string]any
func (Value) ToJSONIndent ¶
ToJSONIndent 将 Value 编码为格式化的 JSON 字节数组
func (*Value) UnmarshalJSON ¶
UnmarshalJSON 从 JSON 格式解码 Value