vice

README

Go channels at horizontal scale

• Use Go channels transparently over a messaging queue technology of your choice (Currently NATS, Redis or NSQ, Amazon SQS)
• Swap vice.Transport to change underlying queueing technologies transparently
• Write idiomatic Go code instead of learning queue specific APIs
• Develop against in-memory implementation before putting it into the wild
• Independent unit tests (no need for running queue technology)

PROJECT STATUS: BETA - Aiming for v1.0 release in October 2017.

Usage

This code receives names on the |names| queue, and sends greetings on the |greetings| queue:

// get a Go channel that will receive messages on the
// |names| queue
names := transport.Receive("names")

// get a Go channel that will send messages on the
// |greetings| queue
greetings := transport.Send("greetings")

// respond to |names| messages with |greetings|
for name := range names {
	greetings <- []byte("Hello " + string(name))
}

• The code above is illustrative, be sure to read the design patterns
• Always stop the Transport, some technologies register and deregister their interest in the queues (this means trapping signals and gracefully shutting down services before exiting)
• Use Send and Receive methods to get channels, which you can then use as normal
• Be sure to always handle the ErrChan() error channel to make sure the underlying queue technology is healthy

Quick start guide

• Write your services with unit tests using normal Go channels (see our design patterns)
• Install Vice with go get github.com/matryer/vice/...
• Select a messaging queue technology
• Build a command to run your service

Read the blog post: Introducing vice: Go channels across many machines

Acknowledgements

Special thanks go to David Hernandez, Jason Hancock and Piotr Rojek for their support on this project.

Documentation

Index

• type Err
  • func (e Err) Error() string
• type Transport

Types

type Err

type Err struct {
	Message []byte
	Name    string
	Err     error
}

Err represents a vice error.

func (Err) Error

func (e Err) Error() string

type Transport

type Transport interface {
	// Receive gets a channel on which to receive messages
	// with the specified name.
	Receive(name string) <-chan []byte
	// Send gets a channel on which messages with the
	// specified name may be sent.
	Send(name string) chan<- []byte
	// ErrChan gets a channel through which errors
	// are sent.
	ErrChan() <-chan error

	// Stop stops the transport. The channel returned from Done() will be closed
	// when the transport has stopped.
	Stop()
	// Done gets a channel which is closed when the
	// transport has successfully stopped.
	Done() chan struct{}
}

Transport provides message sending and receiving capabilities over a messaging queue technology. Clients should always check for errors coming through ErrChan.