goengine

README

GoEngine

GoEngine is an Event Sourcing library written for GoLang.

The goal of this library is to reduce the amount of time you have to spend thinking about the infrastructure so you can focus on
implementing your Domains and Business logic!

Installation

go get -u github.com/hellofresh/goengine

Documentation

Check out our quick start guide which is part of your GoEngine docs. If you prefer to be closer to the code you can always refer to GoDoc.

RoadMap

The following features are planned for the future (in no specific order)

• Improve documentation and examples
• Support for Snapshots
• Inmemory Projection support
• Creating Linked EventStreams
• Distributes tracing (using opencensus and/or opentracing)
• ...

Contributing

We encourage and support an active, healthy community of contributors — including you! Details are in the contribution guide and the code of conduct.

---

Documentation

Index

• func IsUUIDEmpty(id UUID) bool
• type EventStore
• type EventStream
• type Fields
• type InvalidArgumentError
  • func (i InvalidArgumentError) Error() string
• type Logger
• type LoggerEntry
• type Message
  • func ReadEventStream(stream EventStream) ([]Message, []int64, error)
• type MessageHandler
• type MessagePayloadConverter
• type MessagePayloadFactory
• type MessagePayloadResolver
• type Projection
• type ProjectionSaga
• type Query
• type ReadOnlyEventStore
• type StreamName
• type UUID
  • func GenerateUUID() UUID

Functions

func IsUUIDEmpty

func IsUUIDEmpty(id UUID) bool

IsUUIDEmpty returns true if the UUID is empty

Types

type EventStore

type EventStore interface {
	ReadOnlyEventStore

	// Create creates an event stream
	Create(ctx context.Context, streamName StreamName) error

	// AppendTo appends the provided messages to the stream
	AppendTo(ctx context.Context, streamName StreamName, streamEvents []Message) error
}

EventStore an interface describing an event store

type EventStream

type EventStream interface {
	// Next prepares the next result for reading.
	// It returns true on success, or false if there is no next result row or an error happened while preparing it.
	// Err should be consulted to distinguish between the two cases.
	Next() bool

	// Err returns the error, if any, that was encountered during iteration.
	Err() error

	// Close closes the EventStream, preventing further enumeration. If Next is called
	// and returns false and there are no further result sets,
	// result of Err. Close is idempotent and does not affect the result of Err.
	Close() error

	// Message returns the current message and it's number within the EventStream.
	Message() (Message, int64, error)
}

EventStream is the result of an event store query. Its cursor starts before the first row of the result set. Use Next to advance through the results:

type Fields

type Fields map[string]interface{}

Fields a map of context provided to the logger

type InvalidArgumentError

type InvalidArgumentError string

InvalidArgumentError indicates that the caller is in error and passed an incorrect value.

func (InvalidArgumentError) Error

func (i InvalidArgumentError) Error() string

type Logger

type Logger interface {
	Error(msg string, fields func(LoggerEntry))
	Warn(msg string, fields func(LoggerEntry))
	Info(msg string, fields func(LoggerEntry))
	Debug(msg string, fields func(LoggerEntry))

	WithFields(fields func(LoggerEntry)) Logger
}

Logger a structured logger interface

var NopLogger Logger = &nopLogger{}

NopLogger is a no-op Logger. This logger is used when a logger with the value `nil` is passed and avoids the need for `if logger != nil` everywhere

type LoggerEntry

type LoggerEntry interface {
	Int(k string, v int)
	Int64(s string, v int64)
	String(k, v string)
	Error(err error)
	Any(k string, v interface{})
}

LoggerEntry represents the entry to be logger. This entry can be enhanced with more date.

type Message

type Message interface {
	// UUID returns the identifier of this message
	UUID() UUID

	// CreatedAt returns the created time of the message
	CreatedAt() time.Time

	// Payload returns the payload of the message
	Payload() interface{}

	// Metadata return the message metadata
	Metadata() metadata.Metadata

	// WithMetadata Returns new instance of the message with key and value added to metadata
	WithMetadata(key string, value interface{}) Message
}

Message is a interface describing a message. A message can be a command, domain event or some other type of message.

func ReadEventStream

func ReadEventStream(stream EventStream) ([]Message, []int64, error)

ReadEventStream reads the entire event stream and returns it's content as a slice. The main purpose of the function is for testing and debugging.

type MessageHandler

type MessageHandler func(ctx context.Context, state interface{}, message Message) (interface{}, error)

MessageHandler is a func that can do state changes based on a message

type MessagePayloadConverter

type MessagePayloadConverter interface {
	// ConvertPayload generates unique name for the event_name
	ConvertPayload(payload interface{}) (name string, data []byte, err error)
}

MessagePayloadConverter an interface describing converting payload data

type MessagePayloadFactory

type MessagePayloadFactory interface {
	// CreatePayload returns a reconstructed payload or a error
	CreatePayload(payloadType string, data interface{}) (interface{}, error)
}

MessagePayloadFactory is used to reconstruct message payloads

type MessagePayloadResolver

type MessagePayloadResolver interface {
	// ResolveName resolves the name of the underlying payload type
	ResolveName(payload interface{}) (string, error)
}

MessagePayloadResolver is used resolve the event_name of a payload

type Projection

type Projection interface {
	Query

	// Name returns the name of the projection
	Name() string

	// FromStream returns the stream this projection is based on
	FromStream() StreamName
}

Projection contains the information of a projection

type ProjectionSaga

type ProjectionSaga interface {
	Projection

	// DecodeState reconstitute the projection state based on the provided state data
	DecodeState(data []byte) (interface{}, error)

	// EncodeState encode the given object for storage
	EncodeState(obj interface{}) ([]byte, error)
}

ProjectionSaga is a projection that contains state data

type Query

type Query interface {
	// init initializes the state of the Query
	Init(ctx context.Context) (interface{}, error)

	// Handlers return the handlers for a set of messages
	Handlers() map[string]MessageHandler
}

Query contains the information of a query

Example when querying the total the amount of deposits the query could be as follows.

type TotalDepositState struct {
	deposited int
	times     int
}

type TotalDepositQuery struct {}
func (q *TotalDepositQuery) Init(ctx context.Context) (interface{}, error) {
	return TotalDepositState{}, nil
}
func (q *TotalDepositQuery) Handlers() interface{} {
	return map[string]MessageHandler{
		"deposited": func(ctx context.Context, state interface{}, message goengine.Message) (interface{}, error) {
			depositState := state.(TotalDepositState)

			switch event := message.Payload().(type) {
			case AccountDebited:
				depositState.deposited += event.Amount
			}

			return depositState, nil
		},
	}
}

type ReadOnlyEventStore

type ReadOnlyEventStore interface {
	// HasStream returns true if the stream exists
	HasStream(ctx context.Context, streamName StreamName) bool

	// Load returns a list of events based on the provided conditions
	Load(ctx context.Context, streamName StreamName, fromNumber int64, count *uint, metadataMatcher metadata.Matcher) (EventStream, error)
}

ReadOnlyEventStore an interface describing a readonly event store

type StreamName

type StreamName string

StreamName is the name of an event stream

type UUID

type UUID = uuid.UUID

UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC4122

func GenerateUUID

func GenerateUUID() UUID

GenerateUUID creates a new random UUID or panics