Documentation
¶
Index ¶
- Constants
- Variables
- func CallbackDispatcherConsumerName(event Event) string
- func DecodeDatasetPeriodCompleted(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetPeriodCompleted, error)
- func DecodeDatasetPeriodCompletedWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetPeriodCompleted, error)
- func DecodeDatasetRowsUpserted(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetRowsUpserted, error)
- func DecodeDatasetRowsUpsertedWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetRowsUpserted, error)
- func DecodeDatasetSyncPoint(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetSyncPoint, error)
- func DecodeDatasetSyncPointWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetSyncPoint, error)
- func DecodeRaw(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, proto.Message, error)
- func DecodeViewDataReady(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.ViewDataReady, error)
- func DecodeViewDataReadyWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.ViewDataReady, error)
- func InstrumentDelistEventID(exchange, market, exchangeSymbol, scope string, delistAt time.Time) string
- func InstrumentDelistSubjectID(exchange, market, exchangeSymbol string) string
- func IsStorageDatasetSubject(subject string) bool
- func IsStorageViewDurable(name string) bool
- func ObservabilityStreamName() string
- func StorageViewConsumerName(spaceID, datasetID string) string
- type Consumer
- type ConsumerConfig
- type EncodedEvent
- type Event
- func (e Event) Name() string
- func (e Event) NewPayload() proto.Message
- func (e Event) Owner() string
- func (e Event) PayloadFullName() protoreflect.FullName
- func (e Event) Stream() string
- func (e Event) Validate(message *eventpb.EventMessage, payload proto.Message) error
- func (e Event) Version() uint32
- type EventDelivery
- type EventMessage
- type EventValidator
- type PayloadValidationError
- type PublishOptions
- type Publisher
- type RawPublisher
- type Registry
- func (r *Registry) Encode(event Event, payload proto.Message, opts PublishOptions) (EncodedEvent, error)
- func (r *Registry) Events() []Event
- func (r *Registry) FamilyPattern(event Event) (string, error)
- func (r *Registry) Lookup(name string, version uint32) (Event, bool)
- func (r *Registry) MarshalMessage(event Event, payload proto.Message, opts PublishOptions) ([]byte, error)
- func (r *Registry) RenderSubject(event Event, spaceID, subjectID string) (string, error)
- func (r *Registry) SpacePattern(event Event, spaceID string) (string, error)
- func (r *Registry) SubjectForMessage(message *eventpb.EventMessage) (string, error)
- func (r *Registry) UnmarshalMessage(raw []byte) (*eventpb.EventMessage, error)
- func (r *Registry) Validate() error
- func (r *Registry) ValidateMessage(message *eventpb.EventMessage) (Event, error)
- type SpaceConsumerConfig
- type SubjectTemplate
Constants ¶
const ( DelistMarketSpot = "SPOT" DelistMarketSwap = "SWAP" DelistSourceBinanceSpotSchedule = "BINANCE_SPOT_SCHEDULE" DelistSourceBinanceSwapExchangeInfo = "BINANCE_SWAP_EXCHANGE_INFO" DelistSourceOKXSwapInstruments = "OKX_SWAP_INSTRUMENTS" DelistSourceManual = "MANUAL" DelistScopeAll = "ALL" DelistScopePaperOnly = "PAPER_ONLY" // DelistSystemSpaceID 是下架事件的信封空间:下架是交易所层面的事实,不属于任何业务空间,沿用系统事件的空间。 DelistSystemSpaceID = "mooxsys" )
标的下架事件里 payload 的取值。
const ( StorageViewConsumerStream = "MOOX_STORAGE" // StorageViewConsumerPrefix 是每个数据集各一个的 View 消费者名前缀:view_<数据集哈希>。名字里不带任何业务含义。 StorageViewConsumerPrefix = "view_" )
Storage View 消费者的名字是 EventBus 拓扑契约的一部分,放在 events 包里, 让 Storage、Admin 与运维工具不会各记一份而悄悄漂移。
const ( MaxLogReportRecords = 100 MaxLogMessageBytes = 4096 MaxLogRecordFields = 32 MaxLogFieldKeyBytes = 128 MaxLogFieldValueSize = 1024 )
一批重要日志的上限:条数、单条正文与字段的大小。发送方按这些上限截断,超出的事件直接拒收。
const ContentType = "application/vnd.moox.event+protobuf"
const ContentTypeZstd = ContentType + "+zstd"
ContentTypeZstd 标识事件信封经 zstd 字典压缩后的字节。发布器默认压缩; 消费端经 DecodeRaw 透明解压,业务代码不感知。字典由帧头里的字典 ID 决定,解码不需要知道空间。
const ObservabilityFilterSubject = "moox.event.observability.>"
Variables ¶
var ( ObservabilityMetricsSnapshotReported = declareEvent("event.observability.metrics.snapshot.reported", 1, "MOOX_OBSERVABILITY", "service", func() proto.Message { return &metricspb.MetricReport{} }, validateObservabilityMetricsSnapshotReported) ObservabilityHostSnapshotReported = declareEvent("event.observability.host.snapshot.reported", 1, "MOOX_OBSERVABILITY", "hostagent", func() proto.Message { return &hostmetricpb.HostMetric{} }, validateObservabilityHostSnapshotReported) // ObservabilityLogReported 是各服务上报的一批重要日志(Error 及以上、关键事件),Monitor 收到后写进自己的库。 ObservabilityLogReported = declareEvent("event.observability.log.reported", 1, "MOOX_OBSERVABILITY", "service", func() proto.Message { return &metricspb.LogReport{} }, validateObservabilityLogReported) DatasetRowsUpserted = declareEvent("event.storage.dataset.rows.upserted", 2, "MOOX_STORAGE", "storage", func() proto.Message { return &storagepb.DatasetRowsUpserted{} }, validateDatasetRowsUpserted) // DatasetPeriodCompleted 是数据集一期完成的统一事件:来源(ledger 账本判定 / producer 写入方报告)只描述怎么判定的,不是业务分类。 DatasetPeriodCompleted = declareEvent("event.storage.dataset.period.completed", 1, "MOOX_STORAGE", "storage", func() proto.Message { return &storagepb.DatasetPeriodCompleted{} }, validateDatasetPeriodCompleted) // CollectorKlineBackfilled 在 K 线于周期结束后被补写(补采分块读回确认、合成的补写)时由 Collector 发布,只带元数据,不带行情数据。 CollectorKlineBackfilled = declareEvent("event.collector.kline.backfilled", 1, "MOOX_COLLECTOR", "collector", func() proto.Message { return &storagepb.CollectorKlineBackfilled{} }, validateCollectorKlineBackfilled) // InstrumentDelistScheduled 在 Collector 的下架检测发现标的即将下架(或手工登记)时发布,只带元数据; // 信封 subject 是“交易所:市场:交易所代码”,空间固定为系统空间。 InstrumentDelistScheduled = declareEvent("event.collector.instrument.delist_scheduled", 1, "MOOX_COLLECTOR", "collector", func() proto.Message { return &storagepb.InstrumentDelistScheduled{} }, validateInstrumentDelistScheduled) ViewDataReady = declareEvent("event.storage.view.data.ready", 2, "MOOX_STORAGE", "storage", func() proto.Message { return &storagepb.ViewDataReady{} }, validateViewDataReady) DatasetSyncPoint = declareEvent("event.storage.dataset.sync_point", 1, "MOOX_STORAGE", "storage", func() proto.Message { return &storagepb.DatasetSyncPoint{} }, validateDatasetSyncPoint) LogicalAccountTargetWeightRequested = declareEvent("event.trade.target.weight_requested", 1, "MOOX_TRADE", "strategy", func() proto.Message { return &tradeeventpb.LogicalAccountTargetWeightRequested{} }, validateLogicalAccountTargetWeightRequested) )
var CallbackDispatcherEvents = []Event{DatasetPeriodCompleted, ViewDataReady, CollectorKlineBackfilled, InstrumentDelistScheduled}
CallbackDispatcherEvents 是事件中心(callback-dispatcher)消费的事件,每个事件一个固定的 durable。 放在 events 包里,让事件中心与 EventBus 凭据生成不会各记一份而悄悄漂移; 不开放 MOOX_TRADE 的事件:它是工作队列,再挂消费者会和 Trade 抢消息。
var StorageDatasetEvents = []Event{DatasetRowsUpserted, DatasetPeriodCompleted, DatasetSyncPoint}
StorageDatasetEvents 是随数据集产生的三类 Storage 事件:清除某个数据集的历史事件、对齐 View 消费者的过滤主题时, 都按这三类处理。放在这里让 Storage 命令行与 Admin 的 EventBus 维护接口不会各记一份。
Functions ¶
func CallbackDispatcherConsumerName ¶
CallbackDispatcherConsumerName 返回事件中心消费某个事件的 durable 名: NATS 的 durable 名不能含点号,所以取去掉“event.”前缀的事件名,点换成下划线,前面加 callback_dispatcher_,后面加 _v<版本>,例如 callback_dispatcher_collector_instrument_delist_scheduled_v1。
func DecodeDatasetPeriodCompleted ¶
func DecodeDatasetPeriodCompleted(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetPeriodCompleted, error)
DecodeDatasetPeriodCompleted validates and decodes a dataset period completion event.
func DecodeDatasetPeriodCompletedWithContentType ¶
func DecodeDatasetPeriodCompletedWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetPeriodCompleted, error)
DecodeDatasetPeriodCompletedWithContentType also validates broker content type.
func DecodeDatasetRowsUpserted ¶
func DecodeDatasetRowsUpserted(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetRowsUpserted, error)
DecodeDatasetRowsUpserted validates the governed storage envelope and its structured delta payload.
func DecodeDatasetRowsUpsertedWithContentType ¶
func DecodeDatasetRowsUpsertedWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetRowsUpserted, error)
DecodeDatasetRowsUpsertedWithContentType validates the broker content type and the structured storage envelope. Live consumers should pass the NATS Content-Type header received with the delivery.
func DecodeDatasetSyncPoint ¶
func DecodeDatasetSyncPoint(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.DatasetSyncPoint, error)
DecodeDatasetSyncPoint validates and decodes an ordered Dataset sync point.
func DecodeDatasetSyncPointWithContentType ¶
func DecodeDatasetSyncPointWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.DatasetSyncPoint, error)
DecodeDatasetSyncPointWithContentType also validates broker content type.
func DecodeRaw ¶
func DecodeRaw(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, proto.Message, error)
DecodeRaw is the single envelope decoder for governed EventMessage values. It validates broker metadata, registry membership, rendered subject, and the registered protobuf payload type before returning the typed payload.
func DecodeViewDataReady ¶
func DecodeViewDataReady(registry *Registry, raw []byte, subject, messageID string) (*eventpb.EventMessage, *storagepb.ViewDataReady, error)
DecodeViewDataReady validates and decodes a View readiness event.
func DecodeViewDataReadyWithContentType ¶
func DecodeViewDataReadyWithContentType(registry *Registry, raw []byte, subject, messageID, contentType string) (*eventpb.EventMessage, *storagepb.ViewDataReady, error)
DecodeViewDataReadyWithContentType also validates broker content type.
func InstrumentDelistEventID ¶
func InstrumentDelistEventID(exchange, market, exchangeSymbol, scope string, delistAt time.Time) string
InstrumentDelistEventID 由(交易所、市场、代码、范围、下架时间)确定性生成事件 ID, 同一条下架重复发布时 NATS 会在去重窗口内丢弃重复消息;范围也参与计算,演练用的“仅模拟盘”登记不会挡住同标的同时间的真实下架。
func InstrumentDelistSubjectID ¶
InstrumentDelistSubjectID 返回下架事件的信封 subject:“交易所:市场:交易所代码”。
func IsStorageDatasetSubject ¶
IsStorageDatasetSubject 报告 subject 是否是某个空间某个数据集在 StorageDatasetEvents 里的确切主题: 前缀为事件族,其后恰好两个由 EncodeSubjectToken 产生的 token(空间、数据集),不允许通配符。
func IsStorageViewDurable ¶
IsStorageViewDurable 报告 name 是否是 Storage View 的消费者:view_<12 位十六进制>。
func ObservabilityStreamName ¶
func ObservabilityStreamName() string
func StorageViewConsumerName ¶
StorageViewConsumerName 返回数据集的 View 消费者名:view_<空间与数据集身份哈希的前 12 位十六进制>。
Types ¶
type Consumer ¶
type Consumer struct {
// contains filtered or unexported fields
}
func NewConsumer ¶
func NewSpaceConsumer ¶
func (*Consumer) FetchEvents ¶
func (*Consumer) MaxDeliver ¶
type ConsumerConfig ¶
type ConsumerConfig struct {
Name string
Event Event
Stream string
// Events binds one durable to multiple governed families in the same Stream.
Events []Event
// FilterSubjects binds one durable to an explicit set of exact subjects.
// It is mutually exclusive with Event/Events and requires Stream.
FilterSubjects []string
AckWait time.Duration
MaxDeliver int
MaxAckPending int
FetchMaxWait time.Duration
DeliverPolicy nats.DeliverPolicy
DeliverDecodeErrors bool
}
type EncodedEvent ¶
type EncodedEvent struct {
Message *eventpb.EventMessage
Subject string
Payload []byte
}
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event 表示一个由代码声明的业务事件契约。
func (Event) NewPayload ¶
func (Event) PayloadFullName ¶
func (e Event) PayloadFullName() protoreflect.FullName
type EventDelivery ¶
type EventDelivery struct {
Delivery *jetstream.Delivery
Message *eventpb.EventMessage
Payload proto.Message
Err error
}
func DecodeDelivery ¶
func DecodeDelivery(registry *Registry, delivery *jetstream.Delivery) *EventDelivery
DecodeDelivery 在业务边界解码一条 JetStream 原始投递。 JetStream 基础层不感知 EventMessage。
type EventMessage ¶
type EventMessage = eventpb.EventMessage
type EventValidator ¶
type EventValidator func(*eventpb.EventMessage, proto.Message) error
type PayloadValidationError ¶
PayloadValidationError distinguishes a decoded but invalid business payload from malformed envelope or transport metadata.
func (*PayloadValidationError) Error ¶
func (e *PayloadValidationError) Error() string
func (*PayloadValidationError) Unwrap ¶
func (e *PayloadValidationError) Unwrap() error
type PublishOptions ¶
type Publisher ¶
type Publisher struct {
// contains filtered or unexported fields
}
func NewPublisher ¶
func NewPublisher(client RawPublisher, registry *Registry) (*Publisher, error)
func (*Publisher) Close ¶
Close releases the underlying transport when it owns a closeable client. Publishers backed by test or embedded transports that do not expose Close remain valid no-ops.
func (*Publisher) Publish ¶
func (p *Publisher) Publish(ctx context.Context, event Event, payload proto.Message, opts PublishOptions) (*jetstream.PublishAck, error)
func (*Publisher) PublishMessage ¶
func (p *Publisher) PublishMessage(ctx context.Context, message *eventpb.EventMessage) (*jetstream.PublishAck, error)
PublishMessage publishes an already encoded EventMessage. Outbox relays use this path so the exact bytes committed with local state are sent to NATS.
type RawPublisher ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func DefaultRegistry ¶
func (*Registry) Encode ¶
func (r *Registry) Encode(event Event, payload proto.Message, opts PublishOptions) (EncodedEvent, error)
func (*Registry) MarshalMessage ¶
func (r *Registry) MarshalMessage(event Event, payload proto.Message, opts PublishOptions) ([]byte, error)
MarshalMessage 生成 outbox 保存的确定性 EventMessage 字节。 Relay 必须直接发布这些字节,不能根据 topic 字符串或 JSON payload 重建事件。
func (*Registry) RenderSubject ¶
func (*Registry) SpacePattern ¶
SpacePattern returns the subject family for exactly one space. It is useful for consumers which own all routes of an event type within one tenant, while keeping completions from other spaces out of their durable consumer.
func (*Registry) SubjectForMessage ¶
func (r *Registry) SubjectForMessage(message *eventpb.EventMessage) (string, error)
SubjectForMessage 只根据受治理的业务信封生成 NATS subject。
func (*Registry) UnmarshalMessage ¶
func (r *Registry) UnmarshalMessage(raw []byte) (*eventpb.EventMessage, error)
func (*Registry) ValidateMessage ¶
func (r *Registry) ValidateMessage(message *eventpb.EventMessage) (Event, error)
ValidateMessage 不依赖 NATS 传输元数据,校验完整业务信封及其强类型 payload。
type SpaceConsumerConfig ¶
type SpaceConsumerConfig struct {
ConsumerConfig
SpaceID string
}
SpaceConsumerConfig binds every subject route for one event family and one space. It deliberately does not consume the same event from another space.
type SubjectTemplate ¶
type SubjectTemplate struct {
// contains filtered or unexported fields
}
func NewSubjectTemplate ¶
func NewSubjectTemplate(raw string) (SubjectTemplate, error)