event

type Bus interface {
	// Publish sends a single event. The returned error reflects whether
	// the configured transport accepted the frame, not whether
	// downstream handlers succeeded.
	Publish(ctx context.Context, evt Event, opts ...PublishOption) error
	// PublishBatch submits multiple events through the same route
	// resolution pass. Atomicity is transport-specific: transactional
	// transports participate in the caller's transaction, while
	// non-transactional transports may partially accept a batch before
	// returning an error.
	PublishBatch(ctx context.Context, evts []Event, opts ...PublishOption) error
	// Subscribe registers a handler for the given event type. The
	// registration is buffered when the bus has not started and
	// flushed during Bus.Start, so framework modules can subscribe
	// during fx Provide regardless of startup order.
	Subscribe(eventType string, h Handler, opts ...SubscribeOption) (Unsubscribe, error)
}

type Envelope struct {
	// ID is the unique message ID generated on publish. It is stable
	// across retries and is the dedupe key for the Inbox middleware.
	ID string
	// Type mirrors Event.EventType() and drives routing and dispatch.
	Type string
	// Source identifies the producing service; defaults to the
	// application name configured under vef.app.
	Source string
	// OccurredAt is the business time of the event; defaults to now.
	OccurredAt time.Time
	// PublishedAt is stamped by the bus at the publish call (and, on the
	// outbox path, equals the outbox row's insert time). It is not the
	// moment a transport accepted the frame — for relayed events the gap
	// to actual sink delivery can be large.
	PublishedAt time.Time
	// TraceID / SpanID propagate W3C tracing context across transports.
	TraceID string
	SpanID  string
	// CorrelationID groups related events; opaque to the framework.
	CorrelationID string
	// Headers carry arbitrary string metadata, forwarded verbatim.
	Headers map[string]string
	// Payload holds the original Event for in-process delivery, or a
	// RawPayload when the message has crossed a process boundary.
	// SubscribeTyped[T] transparently handles both shapes.
	Payload Event
}

type ErrorSink func(err error, env Envelope)

type Event interface {
	EventType() string
}

type Handler func(ctx context.Context, env Envelope) error

type MetricsRecorder interface {
	// PublishObserved is called once per publish attempt with the
	// resolved event type and the publish outcome. err is non-nil when
	// the underlying transport rejected the frame.
	PublishObserved(eventType string, err error)
	// ConsumeObserved is called once per consume attempt with the
	// resolved event type, the handler's wall-clock elapsed time, and
	// the outcome.
	ConsumeObserved(eventType string, elapsed time.Duration, err error)
}

type PublishConfig struct {
	// Tx, when non-nil, forces routing through a TxTransport using the
	// supplied transaction handle. Returns ErrTxRequired at publish
	// time when the resolved route contains no TxTransport.
	Tx orm.DB
	// Async, when true, enqueues the publish on the bus's fan-in queue
	// and returns immediately. Errors flow to the bus ErrorSink, not
	// the caller. Mutually exclusive with Tx (a transactional publish
	// must complete before the transaction commits).
	Async bool
	// Source overrides Envelope.Source.
	Source string
	// OccurredAt overrides Envelope.OccurredAt.
	OccurredAt time.Time
	// CorrelationID stamps the envelope with a caller-controlled key.
	CorrelationID string
	// Headers are merged into the envelope; later keys override earlier.
	Headers map[string]string
}

type PublishOption func(*PublishConfig)

type RawPayload struct {
	// Type mirrors Envelope.Type and is what EventType() returns.
	Type string
	// Body is the canonical JSON encoding of the original Event.
	Body []byte
}

type RouteInspector interface {
	// HasTransactionalRoute reports whether the resolved route for
	// eventType contains at least one transport whose Capabilities
	// declare Transactional=true. Returns false when no transports
	// route to the type, or when the bus has not yet built its router
	// (i.e. before Start).
	//
	// Modules that publish with WithTx (transactional outbox pattern)
	// should call this once during fx lifecycle OnStart to assert that
	// their event types route to a Transactional transport — without
	// it, the first Publish under WithTx would fail with ErrTxRequired
	// at runtime.
	HasTransactionalRoute(eventType string) bool

	// HasSubscribableTransport reports whether the resolved route for
	// eventType contains at least one transport whose Capabilities do
	// not declare PublishOnly. Returns false when no transports route
	// to the type, or when the bus has not yet built its router.
	//
	// Modules whose framework-side code subscribes to an event
	// (binding listeners, projections, integration handlers) should
	// call this during fx lifecycle OnStart to assert that subscribers
	// can actually receive deliveries. Without it, a route that
	// resolves only to publish-only transports (e.g. the transactional
	// outbox alone) lets the application start, but every Subscribe
	// call against the route fails at runtime with ErrNoRouteMatched
	// — typically after the bus has already accepted publishes that
	// no consumer will ever see.
	HasSubscribableTransport(eventType string) bool
}

type StreamGroupInfo struct {
	// Name is the consumer group name (the subscription's WithGroup value
	// or its derived default).
	Name string `json:"name"`
	// Consumers is the number of consumer records registered in the group,
	// including historical consumers of restarted processes.
	Consumers int64 `json:"consumers"`
	// Pending is the number of delivered-but-unacknowledged entries.
	Pending int64 `json:"pending"`
	// Lag is the number of stream entries not yet delivered to this group,
	// as reported by Redis (approximate after trimming; zero on server
	// versions that do not report lag).
	Lag int64 `json:"lag"`
	// LastDeliveredID is the stream ID of the last entry delivered to the
	// group. Its timestamp part shows how long the group has been stalled.
	LastDeliveredID string `json:"lastDeliveredId"`
}

type StreamInfo struct {
	// Stream is the full transport-level stream key (prefix + event type).
	Stream string `json:"stream"`
	// Length is the current number of entries in the stream (post-trim).
	Length int64 `json:"length"`
	// Groups lists the consumer groups attached to the stream.
	Groups []StreamGroupInfo `json:"groups"`
}

type StreamInspector interface {
	// Streams lists every stream under the transport's prefix together
	// with its consumer groups.
	Streams(ctx context.Context) ([]StreamInfo, error)
}

type SubscribeConfig struct {
	// Group is the consumer group name. Two subscriptions sharing a
	// group on a SupportsGroups transport receive at most one delivery
	// per message between them (load balancing).
	Group string
	// Concurrency is the desired worker count for parallel handler
	// dispatch within this subscription. Defaults to 1.
	Concurrency int
}

type SubscribeOption func(*SubscribeConfig)

type TypedHandler[T Event] func(ctx context.Context, evt T, env Envelope) error

type Unsubscribe func()