events

README

Events

An events protocol designed to be a standard communication between applications. It is meant to be used synchronously (JSON over HTTP, REST) or asynchronously (WebSocket, Socket.IO)

This is a production-ready library, however we still working on the documentation and it is coupled xlog

Example:

{
	"name": "some event",
	"version": 42,
	"id": "2465a86f-3857-423e-af86-41f67880172f",
	"flowId": "d00a5c99-ea0e-4b39-bfdc-bf1028a9c95f",
	"payload": {
		"data1": "fsadfsdf",
		"an_int64": 65484548474984654,
		"some_float": 1864.4568
	},
	"metadata": {
		"origin": "Documentation",
		"originId": "RFC-GB 0001",
		"timestamp": 1482162952
	}
}

Schema

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"description": "Event name"
		},

		"version": {
			"type": "integer",
			"minimum": 1,
			"description": "Event version"
		},


	   "id": {
		   "type": "string",
		   "description": "Unique event identifier, suggestion: UUIDv4"
	   },

	   "flowId": {
		   "type": "string",
		   "description": "Unique Flow ID. It is intended to track the flow of information in a micro-service architecture"
	   },

		"payload": {
			"type": "object",
			"description": "All data this event needs"
		},

		"metadata": {
			"type": "object",
			"description": "Metadata about this event. It is not mandatory, even with an empty metadata the application/event must work"
		}
	},

	"required": [
		"name",
		"version",
		"id",
		"flowId",
		"payload",
	]
}

Installing GO

Follow this guide https://golang.org/doc/install

Please install Go version >= 1.7

Installing glide (dependency management)

Download the binary and put in the $PATH

https://github.com/Masterminds/glide/releases

Install dependencies

$ glide install

Testing

$ go test . `glide nv`

Using Goconvey (Live Test Runner)

$ go get github.com/smartystreets/goconvey

$ $GOPATH/bin/goconvey

Access http://localhost:8080

Changelog

• 17/03/2015 - Implementing HTTPTracker and removing dependency with NewRelic

Documentation

Index

• func RandomID() string
• type Event
  • func NewError(flowID, message string) Event
  • func NewErrorWithMetadata(flowID, message string, metadata interface{}) Event
  • func NewResponse(request Event, payload interface{}) (Event, error)
• type EventDoc
• type HTTPTracker
  • func NewNoOpTracker() HTTPTracker
• type Handler
• type HandlerFunc
  • func Batch(mux *Mux) HandlerFunc
  • func (h HandlerFunc) Serve(ctx context.Context, event Event) (Event, error)
• type MockTracker
  • func (t *MockTracker) End(ctx context.Context, event Event, err error) context.Context
  • func (t *MockTracker) NoticeError(ctx context.Context, err error) context.Context
  • func (t *MockTracker) NoticeEventError(ctx context.Context, event Event, err error) context.Context
  • func (t *MockTracker) Start(ctx context.Context, event Event, w http.ResponseWriter, r *http.Request) context.Context
• type Mux
  • func NewMux() *Mux
  • func NewMuxWithTracker(tracer HTTPTracker) *Mux
  • func (m *Mux) Add(name string, version int, handler Handler)
  • func (m *Mux) ServeDoc(w http.ResponseWriter, r *http.Request)
  • func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

Functions

func RandomID

func RandomID() string

Types

type Event

type Event struct {
	Name     string          `json:"name"`
	Version  int             `json:"version"`
	ID       string          `json:"id"`
	FlowID   string          `json:"flowId,omitempty"`
	Payload  json.RawMessage `json:"payload"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

Event implementation

func NewError

func NewError(flowID, message string) Event

NewError returns a error event

func NewErrorWithMetadata

func NewErrorWithMetadata(flowID, message string, metadata interface{}) Event

NewErrorWithMetadata - Returns an error event with metadata

func NewResponse

func NewResponse(request Event, payload interface{}) (Event, error)

NewResponse builds a response event

type EventDoc

type EventDoc interface {
	Example() (interface{}, interface{})
	Input() interface{}
	Output() interface{}
	Doc() string
}

EventDoc Interface that defines methods used to generete events documentation

type HTTPTracker

type HTTPTracker interface {
	Start(context.Context, Event, http.ResponseWriter, *http.Request) context.Context
	NoticeError(context.Context, error) context.Context
	NoticeEventError(context.Context, Event, error) context.Context
	End(context.Context, Event, error) context.Context
}

HTTPTracker - An interface for tracking events

func NewNoOpTracker

func NewNoOpTracker() HTTPTracker

NewNoOpTracker - Returns a "No Operation Tracker"

type Handler

type Handler interface {
	Serve(context.Context, Event) (Event, error)
}

Handler Interface for event handler

type HandlerFunc

type HandlerFunc func(context.Context, Event) (Event, error)

HandlerFunc a event handler

func Batch

func Batch(mux *Mux) HandlerFunc

Batch is an event that executes batches of events

func (HandlerFunc) Serve

func (h HandlerFunc) Serve(ctx context.Context, event Event) (Event, error)

Serve implements Handler interface

type MockTracker

type MockTracker struct {
	StartFn            func(context.Context, Event, http.ResponseWriter, *http.Request) context.Context
	NoticeErrorFn      func(context.Context, error) context.Context
	NoticeEventErrorFn func(context.Context, Event, error) context.Context
	EndFn              func(context.Context, Event, error) context.Context

	StartCount            int
	NoticeErrorCount      int
	NoticeEventErrorCount int
	EndCount              int
}

MockTracker - A genereic mock for Tracker interface

func (*MockTracker) End

func (t *MockTracker) End(ctx context.Context, event Event, err error) context.Context

End - Imcrements the counter and calls the mock implementation

func (*MockTracker) NoticeError

func (t *MockTracker) NoticeError(ctx context.Context, err error) context.Context

NoticeError - Imcrements the counter and calls the mock implementation

func (*MockTracker) NoticeEventError

func (t *MockTracker) NoticeEventError(ctx context.Context, event Event, err error) context.Context

NoticeEventError - Imcrements the counter and calls the mock implementation

func (*MockTracker) Start

func (t *MockTracker) Start(ctx context.Context, event Event, w http.ResponseWriter, r *http.Request) context.Context

Start - Imcrements the counter and calls the mock implementation

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

Mux Events mux

func NewMux

func NewMux() *Mux

NewMuxNoOpTracker returns a new events Mux

func NewMuxWithTracker

func NewMuxWithTracker(tracer HTTPTracker) *Mux

NewMux returns a new events Mux

func (*Mux) Add

func (m *Mux) Add(name string, version int, handler Handler)

Add adds a HandlerFunc into the Mux

func (*Mux) ServeDoc

func (m *Mux) ServeDoc(w http.ResponseWriter, r *http.Request)

ServeDoc - Serves all documentation

func (*Mux) ServeHTTP

func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)