events

README

github.com/gobuffalo/events

Note: This package was first introduced to Buffalo in this PR. Assuming the PR is merged Buffalo will not start emitting events until v0.13.0-beta.2 or greater.

A list of known emitted events can be found at https://godoc.org/github.com/gobuffalo/events#pkg-constants

Installation

$ go get -u -v github.com/gobuffalo/events

Listening For Events

To listen for events you need to register an events#Listener function first.

func init() {
  // if you want to give your listener a nice name to identify itself
  events.NamedListen("my-listener", func(e events.Event) {
    fmt.Println("### e ->", e)
  })

  // if you don't care about identifying your listener
  events.Listen(func(e events.Event) {
    fmt.Println("### e ->", e)
  })
}

Emitting Events

events.Emit(events.Event{
  Kind:    "my-event",
  Message: // optional message,
  Payload: // optional payload,
  Error:   // optional error,
})

There is only one required field when emitting an event, Kind.

The Kind field is key to how people will interpret your messages, and should be constructed as such: <namespace>:<event-kind>:<err-optional>.

In the examples below from Buffalo you can see it is using the buffalo: name space for its events.

// EvtAppStart is emitted when buffalo.App#Serve is called
EvtAppStart = "buffalo:app:start"
// EvtAppStartErr is emitted when an error occurs calling buffalo.App#Serve
EvtAppStartErr = "buffalo:app:start:err"
// EvtAppStop is emitted when buffalo.App#Stop is called
EvtAppStop = "buffalo:app:stop"
// EvtAppStopErr is emitted when an error occurs calling buffalo.App#Stop
EvtAppStopErr = "buffalo:app:stop:err"

Implementing a Manager

By default events implements a basic manager for you. Should you want to replace that with your own implementation, perhaps that's backed by a proper message queue, you can implement the events#Manager interface.

var _ events.Manager = MyManager{}
events.SetManager(MyManager{})

Listening via Buffalo Plugins

Once Buffalo is actively emitting events, plugins, will be able to listen those events via their CLIs.

To do so you can set the BuffaloCommand to events when telling Buffalo which plugin in commands are available. Buffalo will create a new listener that says the JSON version of the event to that command in question.

var availableCmd = &cobra.Command{
	Use:   "available",
	Short: "a list of available buffalo plugins",
	RunE: func(cmd *cobra.Command, args []string) error {
		plugs := plugins.Commands{
			{Name: "echo", UseCommand: "echo", BuffaloCommand: "events", Description: echoCmd.Short, Aliases: echoCmd.Aliases},
		}
		return json.NewEncoder(os.Stdout).Encode(plugs)
	},
}


events.Emit(events.Event{
  Kind:    "my-event",
})

// buffalo-foo echo "{\"kind\": \"my-event\"}"

Documentation

Index

• Constants
• func Emit(e Event) error
• func EmitError(kind string, err error, payload interface{}) error
• func EmitPayload(kind string, payload interface{}) error
• func List() ([]string, error)
• func LoadPlugins() error
• func SetManager(m Manager)
• type DeleteFn
  • func Listen(l Listener) (DeleteFn, error)
  • func NamedListen(name string, l Listener) (DeleteFn, error)
• type Event
  • func (e Event) IsError() bool
  • func (e Event) MarshalJSON() ([]byte, error)
  • func (e Event) String() string
  • func (e Event) Validate() error
• type Listener
  • func Filter(s string, fn Listener) Listener
• type Manager
  • func DefaultManager() Manager
• type Payload

Constants

const (
	// ErrGeneral is emitted for general errors
	ErrGeneral = "general:err"
	// ErrPanic is emitted when a panic is recovered
	ErrPanic = "panic:err"
)

const Version = "v1.4.0"

Functions

func Emit

func Emit(e Event) error

Emit an event to all listeners

func EmitError

func EmitError(kind string, err error, payload interface{}) error

func EmitPayload

func EmitPayload(kind string, payload interface{}) error

func List

func List() ([]string, error)

List all listeners

func LoadPlugins

func LoadPlugins() error

LoadPlugins will add listeners for any plugins that support "events"

func SetManager

func SetManager(m Manager)

SetManager allows you to replace the default event manager with a custom one

Types

type DeleteFn

type DeleteFn func()

func Listen

func Listen(l Listener) (DeleteFn, error)

Listen for events.

func NamedListen

func NamedListen(name string, l Listener) (DeleteFn, error)

NamedListen for events. Name is the name of the listener NOT the events you want to listen for, so something like "my-listener", "kafka-listener", etc...

type Event

type Event struct {
	// Kind is the "type" of event "app:start"
	Kind string `json:"kind"`
	// Message is optional
	Message string `json:"message"`
	// Payload is optional
	Payload Payload `json:"payload"`
	// Error is optional
	Error error `json:"-"`
}

Event represents different events in the lifecycle of a Buffalo app

func (Event) IsError

func (e Event) IsError() bool

func (Event) MarshalJSON

func (e Event) MarshalJSON() ([]byte, error)

MarshalJSON implements the json marshaler for an event

func (Event) String

func (e Event) String() string

func (Event) Validate

func (e Event) Validate() error

Validate that an event is ready to be emitted

type Listener

type Listener func(e Event)

Listener is a function capable of handling events

func Filter

func Filter(s string, fn Listener) Listener

Filter compiles the string as a regex and returns the original listener wrapped in a new listener that filters incoming events by the Kind

type Manager

type Manager interface {
	Listen(string, Listener) (DeleteFn, error)
	Emit(Event) error
}

Manager can be implemented to replace the default events manager

func DefaultManager

func DefaultManager() Manager

DefaultManager implements a map backed Manager

type Payload

type Payload = mapi.Mapi