Skip to content

Core API Reference ​

While flux aims to keep your domain logic completely framework-agnostic, interacting with the infrastructure layers requires understanding a few core API contracts.

Sentinel Errors ​

The framework exports standard sentinel errors to allow consumers to programmatically evaluate failure reasons using errors.Is().

go
var (
	// ErrAggregateNotFound is returned when an aggregate cannot be loaded from the EventStore or SnapshotStore.
	ErrAggregateNotFound = errors.New("aggregate not found")

	// ErrEventNotFound is returned when an event cannot be found in a stream.
	ErrEventNotFound = errors.New("event not found")

	// ErrSnapshotNotFound is returned by a SnapshotStore when no snapshot exists for a stream.
	ErrSnapshotNotFound = errors.New("snapshot not found")

	// ErrConcurrency is returned by an EventStore when an optimistic concurrency check fails.
	ErrConcurrency = errors.New("optimistic concurrency check failed")

	// ErrInvalidEvent is returned when an aggregate's FromEvents encounters an event type it cannot apply.
	ErrInvalidEvent = errors.New("invalid event type for aggregate")

	// ErrNoHandler is returned by Command and Query buses when no handler is registered for a given type.
	ErrNoHandler = errors.New("no handler registered")

	// ErrInvalidHandlerType is returned when a requested handler signature does not match the registered handler.
	ErrInvalidHandlerType = errors.New("invalid handler type")
)

Typed Contexts ​

To bridge the gap between keeping domain payloads lean and providing explicit, type-safe metadata (avoiding "magic" context.WithValue keys), the framework defines custom contexts for every boundary.

Because they embed standard context.Context, they can be passed directly into standard library functions, database queries, and the Event Store.

TIP

To reparent a typed context with a new Go context.Context (such as after starting an OpenTelemetry span or applying a timeout) while preserving all typed metadata and identifiers, use the WithParent(parent context.Context) method on the typed context (or the flux.WithParent(ctx, parent) package helper).

Base Context ​

Provides guaranteed access to cross-cutting metadata.

go
// package flux
type Context interface {
	context.Context
	Actor() Actor
	CorrelationIdentifier() Identifier
	CausationIdentifier() Identifier
	Logger() *slog.Logger
	Instrumentation() Instrumentation
}

Command Context ​

Extends the base context specifically for mutations.

go
// package command
type Context interface {
	flux.Context
	CommandIdentifier() flux.Identifier
	WithParent(parent context.Context) Context
}

Query Context ​

Extends the base context specifically for read operations.

go
// package query
type Context interface {
	flux.Context
	QueryIdentifier() flux.Identifier
	WithParent(parent context.Context) Context
}

Event Context ​

Provides strongly-typed access to the Envelope metadata (stream, revision, global position) while keeping your event structs pure.

go
// package event

// EventMetadata is flux.Context plus read-only access to the envelope currently
// being handled (stream coordinates and application metadata).
// It is embedded by [Context], [projection.Context], and [workflow.Context].
// Note: This is not an io.Reader and not a CQRS read-model type.
type EventMetadata interface {
	flux.Context
	EventIdentifier() flux.Identifier
	Stream() flux.Stream
	Revision() uint64
	Position() uint64
	Metadata() map[string]string
}

// Context provides EventMetadata and supports reparenting the underlying Go context.
type Context interface {
	EventMetadata
	WithParent(parent context.Context) Context
}

Projection Context ​

Extends event metadata and provides a distinct type boundary guaranteeing that the context is bound to the projection's active database transaction.

go
// package projection
type Context interface {
	event.EventMetadata
	WithParent(parent context.Context) Context
}

Workflow Context ​

Extends event metadata, giving workflow handlers the ability to dispatch commands transactionally via an outbox.

go
// package workflow
type Context interface {
	event.EventMetadata
	QueuedCommands() []any
	WithParent(parent context.Context) Context
}

Event Type Registry ​

The event package provides a reflection-free type registry to instantiate concrete event pointers by name during deserialization.

go
// package event

var ErrTypeNotRegistered = errors.New("event type not registered")

type Types struct {
	mu        sync.RWMutex
	factories map[string]func() flux.Event
}

func NewTypes() *Types

func (t *Types) Register(name string, factory func() flux.Event)

func RegisterType[T flux.Event](t *Types)

func RegisterPointerType[T any, PT interface {
	*T
	flux.Event
}](t *Types)

func (t *Types) Instantiate(name string) (flux.Event, error)

Serialization Codecs ​

The codec package and subpackages provide pluggable serializers for encoding and decoding flux.Envelope instances while preserving domain model purity.

Codec Interface ​

go
// package codec

var (
	ErrNilEvent = errors.New("envelope event cannot be nil")
	ErrEmptyEventName = errors.New("event name cannot be empty")
)

type Serializer interface {
	Marshal(env flux.Envelope) ([]byte, error)
	Unmarshal(data []byte) (flux.Envelope, error)
}

type TypeRegistry interface {
	Instantiate(name string) (flux.Event, error)
}

func AsValue(e flux.Event) flux.Event

JSON Codec ​

go
// package json ("github.com/wotek/flux/codec/json")

type Serializer struct {
	types codec.TypeRegistry
}

func New(types codec.TypeRegistry) *Serializer

func (s *Serializer) Marshal(env flux.Envelope) ([]byte, error)

func (s *Serializer) Unmarshal(data []byte) (flux.Envelope, error)

XML Codec ​

go
// package xml ("github.com/wotek/flux/codec/xml")

type Serializer struct {
	types codec.TypeRegistry
}

func New(types codec.TypeRegistry) *Serializer

func (s *Serializer) Marshal(env flux.Envelope) ([]byte, error)

func (s *Serializer) Unmarshal(data []byte) (flux.Envelope, error)

Protocol Buffers Codec ​

go
// package protobuf ("github.com/wotek/flux/codec/protobuf")

var ErrNotProtoMessage = errors.New("event does not implement proto.Message")

type Serializer struct {
	types codec.TypeRegistry
}

func New(types codec.TypeRegistry) *Serializer

func (s *Serializer) Marshal(env flux.Envelope) ([]byte, error)

func (s *Serializer) Unmarshal(data []byte) (flux.Envelope, error)

Storage Backends ​

In-Memory Event Store ​

go
// package store ("github.com/wotek/flux/event/store")

type EventStore struct {
	mu           sync.RWMutex
	streams      map[string][]flux.Envelope
	globalStream []flux.Envelope
}

func New() *EventStore

func (s *EventStore) Append(ctx context.Context, stream flux.Stream, expectedRevision uint64, events []flux.Envelope) error

func (s *EventStore) Read(ctx context.Context, stream flux.Stream, fromRevision uint64) (flux.StreamIterator, error)

func (s *EventStore) Stream(ctx context.Context, position uint64) (flux.StreamIterator, error)

func (s *EventStore) Find(ctx context.Context, stream flux.Stream, eventID flux.Identifier) (flux.Envelope, error)

In-Memory Snapshot Store ​

go
// package store ("github.com/wotek/flux/snapshot/store")

type SnapshotStore[S any] struct {
	mu        sync.RWMutex
	snapshots map[string]flux.Snapshot[S]
}

func New[S any]() *SnapshotStore[S]

func NewSnapshotStore[S any]() *SnapshotStore[S]

func (s *SnapshotStore[S]) Load(ctx context.Context, stream flux.Stream) (flux.Snapshot[S], error)

func (s *SnapshotStore[S]) Save(ctx context.Context, stream flux.Stream, snap flux.Snapshot[S]) error

Redis Event Store ​

go
// package redis ("github.com/wotek/flux/event/store/redis")

type Option func(*config)

func WithKeyPrefix(prefix string) Option

func WithBatchSize(size int64) Option

type EventStore struct {
	client       redis.UniversalClient
	serializer   codec.Serializer
	config       config
	appendScript *redis.Script
}

func New(client redis.UniversalClient, serializer codec.Serializer, opts ...Option) *EventStore

func NewEventStore(client redis.UniversalClient, serializer codec.Serializer, opts ...Option) *EventStore

func (s *EventStore) Append(ctx context.Context, stream flux.Stream, expectedRevision uint64, events []flux.Envelope) error

func (s *EventStore) Read(ctx context.Context, stream flux.Stream, fromRevision uint64) (flux.StreamIterator, error)

func (s *EventStore) Stream(ctx context.Context, position uint64) (flux.StreamIterator, error)

func (s *EventStore) Find(ctx context.Context, stream flux.Stream, eventID flux.Identifier) (flux.Envelope, error)

Redis Snapshot Store ​

go
// package redis ("github.com/wotek/flux/snapshot/store/redis")

type Option func(*config)

func WithKeyPrefix(prefix string) Option

type SnapshotStore[S any] struct {
	client redis.UniversalClient
	config config
}

func New[S any](client redis.UniversalClient, opts ...Option) *SnapshotStore[S]

func NewSnapshotStore[S any](client redis.UniversalClient, opts ...Option) *SnapshotStore[S]

func (s *SnapshotStore[S]) Load(ctx context.Context, stream flux.Stream) (flux.Snapshot[S], error)

func (s *SnapshotStore[S]) Save(ctx context.Context, stream flux.Stream, snap flux.Snapshot[S]) error

MySQL Event Store ​

go
// package mysql ("github.com/wotek/flux/event/store/mysql")

type Option func(*config)

func WithTableName(name string) Option

type EventStore struct {
	db         *sql.DB
	serializer codec.Serializer
	config     config
}

func New(db *sql.DB, serializer codec.Serializer, opts ...Option) *EventStore

func NewEventStore(db *sql.DB, serializer codec.Serializer, opts ...Option) *EventStore

func (s *EventStore) Append(ctx context.Context, stream flux.Stream, expectedRevision uint64, events []flux.Envelope) error

func (s *EventStore) Read(ctx context.Context, stream flux.Stream, fromRevision uint64) (flux.StreamIterator, error)

func (s *EventStore) Stream(ctx context.Context, position uint64) (flux.StreamIterator, error)

func (s *EventStore) Find(ctx context.Context, stream flux.Stream, eventID flux.Identifier) (flux.Envelope, error)

PostgreSQL Event Store ​

Operates on standard *sql.DB connections using the jackc/pgx driver (_ "github.com/jackc/pgx/v5/stdlib") via sql.Open("pgx", …).

go
// package postgres ("github.com/wotek/flux/event/store/postgres")

type Option func(*config)

func WithTableName(name string) Option

func WithBatchSize(size int) Option

func ValidateTableName(name string) error

var ErrInvalidTableName = errors.New("invalid table name")

type EventStore struct {
	db         *sql.DB
	serializer codec.Serializer
	config     config
}

func New(db *sql.DB, serializer codec.Serializer, opts ...Option) *EventStore

func NewEventStore(db *sql.DB, serializer codec.Serializer, opts ...Option) *EventStore

func (s *EventStore) Append(ctx context.Context, stream flux.Stream, expectedRevision uint64, events []flux.Envelope) error

func (s *EventStore) Read(ctx context.Context, stream flux.Stream, fromRevision uint64) (flux.StreamIterator, error)

func (s *EventStore) Stream(ctx context.Context, position uint64) (flux.StreamIterator, error)

func (s *EventStore) Find(ctx context.Context, stream flux.Stream, eventID flux.Identifier) (flux.Envelope, error)

MySQL Snapshot Store ​

go
// package mysql ("github.com/wotek/flux/snapshot/store/mysql")

type Option func(*config)

func WithTableName(name string) Option

type SnapshotStore[S any] struct {
	db     *sql.DB
	config config
}

func New[S any](db *sql.DB, opts ...Option) *SnapshotStore[S]

func NewSnapshotStore[S any](db *sql.DB, opts ...Option) *SnapshotStore[S]

func (s *SnapshotStore[S]) Load(ctx context.Context, stream flux.Stream) (flux.Snapshot[S], error)

func (s *SnapshotStore[S]) Save(ctx context.Context, stream flux.Stream, snap flux.Snapshot[S]) error

PostgreSQL Snapshot Store ​

Operates on standard *sql.DB connections using the jackc/pgx driver (_ "github.com/jackc/pgx/v5/stdlib") via sql.Open("pgx", …).

go
// package postgres ("github.com/wotek/flux/snapshot/store/postgres")

type Option func(*config)

func WithTableName(name string) Option

func ValidateTableName(name string) error

var ErrInvalidTableName = errors.New("invalid table name")

type SnapshotStore[S any] struct {
	db     *sql.DB
	config config
}

func New[S any](db *sql.DB, opts ...Option) *SnapshotStore[S]

func NewSnapshotStore[S any](db *sql.DB, opts ...Option) *SnapshotStore[S]

func (s *SnapshotStore[S]) Load(ctx context.Context, stream flux.Stream) (flux.Snapshot[S], error)

func (s *SnapshotStore[S]) Save(ctx context.Context, stream flux.Stream, snap flux.Snapshot[S]) error