events

package module
v0.0.0-...-cbee766 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 25 Imported by: 1

Documentation

Index

Constants

View Source
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 的取值。

View Source
const (
	StorageViewConsumerStream = "MOOX_STORAGE"
	// StorageViewConsumerPrefix 是每个数据集各一个的 View 消费者名前缀:view_<数据集哈希>。名字里不带任何业务含义。
	StorageViewConsumerPrefix = "view_"
)

Storage View 消费者的名字是 EventBus 拓扑契约的一部分,放在 events 包里, 让 Storage、Admin 与运维工具不会各记一份而悄悄漂移。

View Source
const (
	MaxLogReportRecords  = 100
	MaxLogMessageBytes   = 4096
	MaxLogRecordFields   = 32
	MaxLogFieldKeyBytes  = 128
	MaxLogFieldValueSize = 1024
)

一批重要日志的上限:条数、单条正文与字段的大小。发送方按这些上限截断,超出的事件直接拒收。

View Source
const ContentType = "application/vnd.moox.event+protobuf"
View Source
const ContentTypeZstd = ContentType + "+zstd"

ContentTypeZstd 标识事件信封经 zstd 字典压缩后的字节。发布器默认压缩; 消费端经 DecodeRaw 透明解压,业务代码不感知。字典由帧头里的字典 ID 决定,解码不需要知道空间。

View Source
const ObservabilityFilterSubject = "moox.event.observability.>"

Variables

View Source
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)
)

CallbackDispatcherEvents 是事件中心(callback-dispatcher)消费的事件,每个事件一个固定的 durable。 放在 events 包里,让事件中心与 EventBus 凭据生成不会各记一份而悄悄漂移; 不开放 MOOX_TRADE 的事件:它是工作队列,再挂消费者会和 Trade 抢消息。

StorageDatasetEvents 是随数据集产生的三类 Storage 事件:清除某个数据集的历史事件、对齐 View 消费者的过滤主题时, 都按这三类处理。放在这里让 Storage 命令行与 Admin 的 EventBus 维护接口不会各记一份。

Functions

func CallbackDispatcherConsumerName

func CallbackDispatcherConsumerName(event Event) string

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

func InstrumentDelistSubjectID(exchange, market, exchangeSymbol string) string

InstrumentDelistSubjectID 返回下架事件的信封 subject:“交易所:市场:交易所代码”。

func IsStorageDatasetSubject

func IsStorageDatasetSubject(subject string) bool

IsStorageDatasetSubject 报告 subject 是否是某个空间某个数据集在 StorageDatasetEvents 里的确切主题: 前缀为事件族,其后恰好两个由 EncodeSubjectToken 产生的 token(空间、数据集),不允许通配符。

func IsStorageViewDurable

func IsStorageViewDurable(name string) bool

IsStorageViewDurable 报告 name 是否是 Storage View 的消费者:view_<12 位十六进制>。

func ObservabilityStreamName

func ObservabilityStreamName() string

func StorageViewConsumerName

func StorageViewConsumerName(spaceID, datasetID string) string

StorageViewConsumerName 返回数据集的 View 消费者名:view_<空间与数据集身份哈希的前 12 位十六进制>。

Types

type Consumer

type Consumer struct {
	// contains filtered or unexported fields
}

func NewConsumer

func NewConsumer(ctx context.Context, client *jetstream.Client, registry *Registry, cfg ConsumerConfig) (*Consumer, error)

func NewSpaceConsumer

func NewSpaceConsumer(ctx context.Context, client *jetstream.Client, registry *Registry, cfg SpaceConsumerConfig) (*Consumer, error)

func (*Consumer) Close

func (c *Consumer) Close() error

func (*Consumer) Fetch

func (c *Consumer) Fetch(ctx context.Context, batch int) ([]*jetstream.Delivery, error)

func (*Consumer) FetchEvents

func (c *Consumer) FetchEvents(ctx context.Context, batch int) ([]*EventDelivery, error)

func (*Consumer) MaxDeliver

func (c *Consumer) MaxDeliver() int

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) Name

func (e Event) Name() string

func (Event) NewPayload

func (e Event) NewPayload() proto.Message

func (Event) Owner

func (e Event) Owner() string

func (Event) PayloadFullName

func (e Event) PayloadFullName() protoreflect.FullName

func (Event) Stream

func (e Event) Stream() string

func (Event) Validate

func (e Event) Validate(message *eventpb.EventMessage, payload proto.Message) error

func (Event) Version

func (e Event) Version() uint32

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

type PayloadValidationError struct {
	EventName string
	Cause     error
}

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 PublishOptions struct {
	EventID    string
	OccurredAt time.Time
	SpaceID    string
	SubjectID  string
}

type Publisher

type Publisher struct {
	// contains filtered or unexported fields
}

func NewPublisher

func NewPublisher(client RawPublisher, registry *Registry) (*Publisher, error)

func (*Publisher) Close

func (p *Publisher) Close() error

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 RawPublisher interface {
	PublishRaw(context.Context, string, string, []byte, string) (*jetstream.PublishAck, error)
}

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

func DefaultRegistry

func DefaultRegistry() (*Registry, error)

func (*Registry) Encode

func (r *Registry) Encode(event Event, payload proto.Message, opts PublishOptions) (EncodedEvent, error)

func (*Registry) Events

func (r *Registry) Events() []Event

func (*Registry) FamilyPattern

func (r *Registry) FamilyPattern(event Event) (string, error)

func (*Registry) Lookup

func (r *Registry) Lookup(name string, version uint32) (Event, bool)

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 (r *Registry) RenderSubject(event Event, spaceID, subjectID string) (string, error)

func (*Registry) SpacePattern

func (r *Registry) SpacePattern(event Event, spaceID string) (string, error)

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) Validate

func (r *Registry) Validate() 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)

func (SubjectTemplate) Render

func (t SubjectTemplate) Render(spaceID, subjectID string) (string, error)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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