roster

README

Roster: A library for simple service discovery using Dynamodb for Golang

Instead of having to manage a separate distributed key store like etcd or ZooKeeper, leverage AWS's own Dynamodb so you don't have to worry about hardware provisioning, setup and configuration, replication, software patching, or cluster scaling.

As the only dependency is Dynamodb, it has the added benefit of allowing service discovery between applications running on EC2 and dockerized applications running within ECS.

Another service discovery tool...why??

Wanting to leverage as much of the managed AWS services as possible - less to go wrong (hopefully). Also a good exercise in using the AWS SDK for Go - there's not many examples out there using Dyanamodb from Go using the offical SDK, so seemed like a good project to try it out.

Requirements

1. Go 1.5 or above
2. AWS credentials setup as per AWS SDK documentation. It seems the Go SDK needs credentials even for 100% local access; however these can be dummy values (see the example Docker Compose yml file.)

Usage

Examples

Within the examples folder there is an example echo client and server that demonstrate basic registry and discovery. Ensuring you have Docker Compose installed, simply run docker-compose up. This creates 1 client and 2 instances of the server service - when one of these servers is stopped, the client should remain operational and shouldn't drop any requests.

Using a local Dynamodb instance for development

The easiest way to get a local instance of Dynamodb running is to pull down this docker image. Then the following steps (assumes Docker Machine is being used with default name):

1. docker pull tutum/dynamodb
2. docker run -d -p 8000:8000 tutum/dynamodb
3. 'export DYNAMODB_PORT=http://$(docker-machine ip default):8000'
4. Run your Go app.

Contributing

This is very much experimental at present...so please feel free to contribute any bugs (and even better PR's with fixes!)

Installation

1. Clone the repository
2. Install Glide which is used to handle vendoring and dependency management
3. Install dependencies $ glide install

Running tests

go test . will run tests. By default the tests will connect to the Amazon hosted Dynamodb in the default region. You can override the region by setting AWS_REGION environment variable as per the AWS SDK. Also if the DYNAMODB_PORT environment variable is set, tests will be run against the local dynamodb instance.

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(config ClientConfig) *Client
  • func (c *Client) Discover(name string) (*Service, error)
  • func (c *Client) GetLocalIP() (string, error)
  • func (c *Client) Register(name string, endpoint string) (*Service, error)
• type ClientConfig
  • func (cc ClientConfig) GetConfig() *aws.Config
  • func (cc ClientConfig) GetRegistryName() *string
• type Registry
  • func NewRegistry(svc *dynamodb.DynamoDB, name *string) *Registry
  • func (r *Registry) Create() error
  • func (r *Registry) Delete() error
  • func (r *Registry) Exists() (bool, error)
  • func (r *Registry) IsActive() (bool, error)
• type Service
  • func (s *Service) Unregister()

Constants

const (
	HeartbeatInterval = 1000 * time.Millisecond
	ServiceTTL        = 5
)

Variables

var (
	ErrServiceNotFound = errors.New("roster: No matching service found")
	ErrLocalIpNotFound = errors.New("roster: No non loopback local IP address could be found")
)

var (
	ErrRegistryNotActive = errors.New("roster: Registry table has taken longer than expected to reach ACTIVE state")
)

Types

type Client

type Client struct {
	Registry *Registry
	// contains filtered or unexported fields
}

func NewClient

func NewClient(config ClientConfig) *Client

func (*Client) Discover

func (c *Client) Discover(name string) (*Service, error)

Query the registry for named service

func (*Client) GetLocalIP

func (c *Client) GetLocalIP() (string, error)

Returns the non loopback local IP of the host the client is running on

func (*Client) Register

func (c *Client) Register(name string, endpoint string) (*Service, error)

Register the service in the registry

type ClientConfig

type ClientConfig struct {
	RegistryName string
	Region       string
	Endpoint     string
}

func (ClientConfig) GetConfig

func (cc ClientConfig) GetConfig() *aws.Config

func (ClientConfig) GetRegistryName

func (cc ClientConfig) GetRegistryName() *string

type Registry

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

func NewRegistry

func NewRegistry(svc *dynamodb.DynamoDB, name *string) *Registry

Creates a new registry

func (*Registry) Create

func (r *Registry) Create() error

Create table with 2 attributes (Name and Expiry)

func (*Registry) Delete

func (r *Registry) Delete() error

Delete the registry

func (*Registry) Exists

func (r *Registry) Exists() (bool, error)

Does the registry exist

func (*Registry) IsActive

func (r *Registry) IsActive() (bool, error)

Is the registry in an active state

type Service

type Service struct {
	Name     string
	Endpoint string
	Expiry   int64
	// contains filtered or unexported fields
}

func (*Service) Unregister

func (s *Service) Unregister()

Unregister the service