bus: github.com/mustafaturan/bus Index | Files

package bus

import "github.com/mustafaturan/bus"

Package bus is a minimalist event/message bus implementation for internal communication

Configure

The package requires a unique id generator to assign ids to events. You can write your own function to generate unique ids or use a package that provides unique id generation functionality. Here is a sample configuration using `monoton` id generator:

Example code for configuration:

import (
	"github.com/mustafaturan/bus"
	"github.com/mustafaturan/monoton"
	"github.com/mustafaturan/monoton/sequencer"
)

func init() {
	// configure id generator (it doesn't have to be monoton)
	node        := uint(1)
	initialTime := uint(0)
	monoton.Configure(sequencer.NewMillisecond(), node, initialTime)

	// configure bus
	if err := bus.Configure(bus.Config{Next: monoton.Next}); err != nil {
		panic("whoops")
	}
	// ...
}

Register Topics

To emit events to the topics, topic names should be registered first:

Example code:

func init() {
	// ...
	// register topics
	bus.RegisterTopics("order.received", "order.fulfilled")
	// ...
}

Register Handlers

To receive topic events you need to register handlers; A handler basically requires two vals which are a `Handle` function and topic `Matcher` regex pattern.

Example code:

handler := bus.Handler{
	Handle: func(e *Event){
		// do something
		// NOTE: Highly recommended to process the event in an async way
	}),
	Matcher: ".*", // matches all topics
}
bus.RegisterHandler("a unique key for the handler", &handler)

Emit Event

Example code:

txID  := "some-transaction-id-if-exists" // if it is blank, package will generate one
topic := "order.received" // event topic name (must be registered before)
order := make(map[string]string) // interface{} data for the event

order["orderID"]     = "123456"
order["orderAmount"] = "112.20"
order["currency"]    = "USD"

// emit the event for the topic with the transaction id
bus.Emit(topic, order, txID)

Processing Events

When an event is emitted, the topic handlers will receive events with order. It is highly recommended to process events asynchronous. Package leave the decision to the packages/projects to use concurrency abstractions depending on use-cases.

Index

Package Files

bus.go config.go config_actions.go doc.go event.go event_actions.go handler.go handler_actions.go topic.go topic_actions.go

func Configure Uses

func Configure(c Config) error

Configure sets configuration for bus package

func DeregisterHandler Uses

func DeregisterHandler(key string)

DeregisterHandler deletes handler from the registry

func DeregisterTopics Uses

func DeregisterTopics(topicNames ...string)

DeregisterTopics deletes topic

func ListHandlerKeys Uses

func ListHandlerKeys() []string

ListHandlerKeys returns list of registered handler keys

func RegisterHandler Uses

func RegisterHandler(key string, h *Handler)

RegisterHandler re/register the handler to the registry

func RegisterTopics Uses

func RegisterTopics(topicNames ...string)

RegisterTopics registers topics and fullfills handlers

type Config Uses

type Config struct {
    Next func() string // Unique id generator
}

Config holds configuration structure for bus library

type Event Uses

type Event struct {
    ID         string      // identifier
    TxID       string      // transaction identifier
    Topic      *Topic      // topic name
    Data       interface{} // actual event data
    OccurredAt int64       // creation time in nanoseconds
}

Event is data structure for any logs

func Emit Uses

func Emit(topicName string, data interface{}, txID string) (*Event, error)

Emit inits a new event and delivers to the interested in handlers

type Handler Uses

type Handler struct {
    Handle  func(e *Event) // handler func to process events
    Matcher string         // topic matcher as regex pattern
}

Handler is a receiver for event reference with the given regex pattern

func (*Handler) Subscriptions Uses

func (h *Handler) Subscriptions() []*Topic

Subscriptions returns all subscriptions of the handler

type Topic Uses

type Topic struct {
    Name string
    // contains filtered or unexported fields
}

Topic structure

func ListTopics Uses

func ListTopics() []*Topic

ListTopics list registered topics

func (*Topic) Handlers Uses

func (t *Topic) Handlers() []*Handler

Handlers returns all handlers of the topic

Package bus imports 4 packages (graph). Updated 2019-05-18. Refresh now. Tools for package owners.