Documentation
¶
Overview ¶
Package eventstream provides a transport-neutral runtime event stream surface for go-router. The package owns scoped publish/subscribe behavior, bounded replay, stable cursors, scope matching, drop accounting, stats snapshots, and optional observability hooks while leaving HTTP/SSE framing to higher-level adapters.
v1 keeps stream ownership separate from websocket-specific hubs/history. Control frames such as heartbeats, retry directives, and stream gaps belong to transport adapters like ssefiber, not to this package.
Index ¶
- Constants
- func ExactMatch(subscription Scope, published Scope) bool
- func SubsetMatch(subscription Scope, published Scope) bool
- type Config
- type DropEvent
- type Event
- type Hooks
- type MatchFunc
- type Option
- type PublishEvent
- type Record
- type Scope
- type Stats
- type Stream
- type SubscribeEvent
- type Subscription
Constants ¶
const ( // DefaultBufferSize is the default retained-record capacity per published scope. DefaultBufferSize = 256 // DefaultSubscriberQueueSize is the default buffered queue capacity per subscriber. DefaultSubscriberQueueSize = 32 )
Variables ¶
This section is empty.
Functions ¶
func ExactMatch ¶
ExactMatch requires the published scope to equal the subscription scope.
func SubsetMatch ¶
SubsetMatch allows broader subscriptions, such as tenant-only listeners, to receive more specific published scopes that include additional labels.
Types ¶
type Config ¶
Config defines the constructor-time surface for stream behavior.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the normalized constructor defaults for the stream.
type Event ¶
type Event struct {
Name string `json:"name"`
Payload json.RawMessage `json:"payload,omitempty"`
Timestamp time.Time `json:"timestamp"`
Metadata map[string]string `json:"metadata,omitempty"`
}
Event is the transport-neutral payload stored by the stream core.
type Hooks ¶
type Hooks struct {
OnPublish func(PublishEvent)
OnSubscribe func(SubscribeEvent)
OnDrop func(DropEvent)
}
Hooks provides optional observability callbacks for stream lifecycle events.
type MatchFunc ¶
MatchFunc decides whether a published scope should be delivered to a subscription scope.
type Option ¶
type Option func(*Config)
Option mutates stream configuration before construction.
func WithBufferSize ¶
WithBufferSize sets retained replay capacity per published scope.
func WithMatcher ¶
WithMatcher overrides the default exact scope matcher.
func WithSubscriberBuffer ¶
WithSubscriberBuffer is an alias for WithSubscriberQueueSize.
func WithSubscriberQueueSize ¶
WithSubscriberQueueSize sets the live delivery queue size per subscriber.
type PublishEvent ¶
PublishEvent describes a successful publish operation.
type Record ¶
type Record struct {
Cursor string `json:"cursor"`
ScopeKey string `json:"scope_key"`
Event Event `json:"event"`
PublishedAt time.Time `json:"published_at"`
}
Record is a published event with stream-assigned metadata.
type Stats ¶
type Stats struct {
PublishedCount int64
ResumeCount int64
ActiveSubscribers int
BufferedRecords int
DropReasons map[string]int64
}
Stats exposes a point-in-time stream snapshot for observability.
type Stream ¶
type Stream interface {
Publish(scope Scope, event Event) Record
Subscribe(ctx context.Context, scope Scope, afterCursor string) (*Subscription, error)
SnapshotStats() Stats
}
Stream is the public replayable event stream surface shared by transports.