eventing

Eventing

This package make working with events easy. Its provides functions for store events and derive projections (your entities) from the list of events.

This package is under heavy development. The API may encounter breaking changes. You are welcome to contribute.

Wording

Basic Functionality

You can find a combined usage-example in the example directory

Event

A Event needs to implement the Event-interface. This is typically done by embedding the BasicEvent struct and providing a constructor function:

type ExampleEvent struct {
	eventing.BasicEvent `bson:",inline"` // Using inline here is recommended
	MyData       string `json:"my_data" bson:"my_data"` // Providing custom json and bson-keys for MongoDB
}

func NewExampleEvent(data string) *ExampleEvent {
	return &ExampleEvent{
		BasicEvent: eventing.NewBasicEvent(uuid.NewV4().String(), "ExampleEvent"),
		MyData:     data,
	}
}

Projection

A Projection needs to implement the Projection-interface. This is typically done by embedding the BasicProjection struct and providing some functions:

• Implement / override the Apply function to apply specific events. Its highly recommended to call the Apply function of the embedded BasicProjection first, to apply basic event data.
• A (private) function to build the concrete Projection by a list of Events. This is necessary as long as go does not support of generics.

type ExampleProjection struct {
	eventing.BasicProjection `bson:",inline"`
	SomeString               string `json:"some_string" bson:"some_string"`
}

func (ex *ExampleProjection) Apply(event eventing.Event) {
	ex.BasicProjection.Apply(event)
	switch v := event.(type) {
	case *ExampleEvent:
		ex.SomeString = v.Data.SomeString
	default:
		fmt.Println("could not handle event")
	}
}

func buildExampleProjection(ctx context.Context, events []eventing.Event) (eventing.Projection, error) {
	ex := &ExampleProjection{}
	for _, event := range events {
		ex.Apply(event)
	}
	return ex, nil
}

Controller

You should create one Controller per Projection. A Controller can be initialized like this:

func main() {
    projectionController := eventing.NewController(&ExampleProjection{}, buildExampleProjection, SOME_STORAGE_PROVIDER)
}

Storage Providers

To store Events and Projections you will need a StorageProvider, e.g. A database. This project holds a example provider for MongoDB which can be easily be used:

func main() {
    database := connectToMongo("localhost", "27017", "root", "root", "testEventing")
    storage := provider.NewMongoStorageProvider(database, "events", eventing.BasicProjectionGenerator)
}

Registering Events

You may need to provide a function to build a concrete Event by the raw Database output. The provided MongoDB-implementation depends on. Make sure to register all your events. This can be done by using the fluent API:

func main() {
    storage := provider.NewMongoStorageProvider(database, "events", eventing.BasicProjectionGenerator).
            WithEvent("ExampleEvent", exampleEventFromCursor)
}

func exampleEventFromCursor(raw *mongo.Cursor) (eventing.Event, error) {
	e := &ExampleEvent{}
	err := raw.Decode(e)
	if err != nil {
		return nil, err
	}
	return e, nil
}