colony

README

colony

A lightweight microservice framework for NSQ. Services can emit and consume data; services can also respond to messages they receive and handle response to messages they emit.

See the docs or the examples for more information.

Documentation

Overview

Package colony implements a lightweight microservice framework on top of NSQ.

Index

• type Handler
• type Message
• type Service
  • func NewService(name, id, nsqLookupd string) *Service
  • func (s Service) Announce(contentType string) error
  • func (s Service) Consume(contentType string, h Handler) error
  • func (s Service) Emit(m Message) error
  • func (s Service) HandleMessage(m *nsq.Message) error
  • func (s *Service) NewMessage(contentType string, payload []byte) Message
  • func (s *Service) NewResponse(m Message, contentType string, payload []byte) Message
  • func (s Service) Request(m Message, h Handler) error

Types

type Handler

type Handler func(<-chan Message) error

Handler receive a stream of Messages over the supplied channel in response to a corresponding outbound message. Each service needs to provide a Handler for each content type it consumes, and for each outbound message that can be responded to.

type Message

type Message struct {
	FromName      string    // name of originating service
	Payload       []byte    // actual message content
	Time          time.Time // time message was generated
	ContentType   string    // contentType of message
	MessageID     messageID // message id
	Topic         topic     // topic message appears on
	ResponseTopic topic     // responses to this message can be sent here
}

A Message wraps a payload of data, and contains everything required for successful routing through NSQ between services. Generally NewMessage should be used to generate outbound messages and NewResponse to generate responses.

type Service

type Service struct {
	Name string // Name of the service
	ID   string // ID of the service
	// contains filtered or unexported fields
}

Service contains all the information for a service necessary for successful routing of messages to and from that service. To initialise a service use NewService.

func NewService

func NewService(name, id, nsqLookupd string) *Service

NewService returns a colony service associated with a specific NSQ setup. Provide NSQ's lookupd address. This Service will be associated with an NSQD node in the network at random. If you're running NSQ locally with the default port then this will be "0.0.0.0/4161"

func (Service) Announce

func (s Service) Announce(contentType string) error

Announce the production of a new content type to the colony, to alert existing services. If Announce is not called, only new services will discover this contentType.

func (Service) Consume

func (s Service) Consume(contentType string, h Handler) error

Consume registers the supplied Handler as a reciever of colony Messages of the specified contentType. When the Handler returns the service will no longer recieve messages of this type.

func (Service) Emit

func (s Service) Emit(m Message) error

Emit sends a Message from the service to the colony

func (Service) HandleMessage

func (s Service) HandleMessage(m *nsq.Message) error

HandleMessage routes messages from the service's response topic to the appopriate Handler. This function can be safely ignored when building a service.

func (*Service) NewMessage

func (s *Service) NewMessage(contentType string, payload []byte) Message

NewMessage creates a new colony Message. Use Emit to emit this message to the network.

func (*Service) NewResponse

func (s *Service) NewResponse(m Message, contentType string, payload []byte) Message

NewResponse builds a colony Message specifically as a response to a recieved Message. Use Emit or Request to send this Message to the originating service.

func (Service) Request

func (s Service) Request(m Message, h Handler) error

Request sends a Message from the service to the colony and specifies a Handler that will recieve the stream of responses.