eventstream

package
v0.65.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 11 Imported by: 2

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

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

func ExactMatch(subscription Scope, published Scope) bool

ExactMatch requires the published scope to equal the subscription scope.

func SubsetMatch

func SubsetMatch(subscription Scope, published Scope) bool

SubsetMatch allows broader subscriptions, such as tenant-only listeners, to receive more specific published scopes that include additional labels.

Types

type Config

type Config struct {
	BufferSize          int
	SubscriberQueueSize int
	Matcher             MatchFunc
	Hooks               Hooks
}

Config defines the constructor-time surface for stream behavior.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the normalized constructor defaults for the stream.

type DropEvent

type DropEvent struct {
	Scope    Scope
	ScopeKey string
	Reason   string
}

DropEvent describes why a subscriber was removed.

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

type MatchFunc func(subscription Scope, published Scope) bool

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

func WithBufferSize(size int) Option

WithBufferSize sets retained replay capacity per published scope.

func WithHooks

func WithHooks(hooks Hooks) Option

WithHooks configures optional observability callbacks.

func WithMatcher

func WithMatcher(matcher MatchFunc) Option

WithMatcher overrides the default exact scope matcher.

func WithSubscriberBuffer

func WithSubscriberBuffer(size int) Option

WithSubscriberBuffer is an alias for WithSubscriberQueueSize.

func WithSubscriberQueueSize

func WithSubscriberQueueSize(size int) Option

WithSubscriberQueueSize sets the live delivery queue size per subscriber.

type PublishEvent

type PublishEvent struct {
	Scope    Scope
	ScopeKey string
	Record   Record
}

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 Scope

type Scope map[string]string

Scope identifies the published or subscribed audience for a record.

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.

func New

func New(opts ...Option) Stream

New constructs an in-memory scoped stream with bounded replay and live fanout.

type SubscribeEvent

type SubscribeEvent struct {
	Scope           Scope
	ScopeKey        string
	AfterCursor     string
	ReplayCount     int
	CursorGap       bool
	CursorGapReason string
}

SubscribeEvent describes a subscription attempt and its replay state.

type Subscription

type Subscription struct {
	Scope           Scope
	ScopeKey        string
	Records         <-chan Record
	CursorGap       bool
	CursorGapReason string
}

Subscription is a stream registration that yields ordered records.

Jump to

Keyboard shortcuts

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