ring

README

ring

Go utility to build Peer to Peer Architecture easily.

Ring Configuration parameters

Parameters	Type	Usage
BindAddr	string	The address that Ring will bind to for communication with other members on the ring. By default this is "0.0.0.0:7946". Read more
Tags	map[string]string	Tags will be sent with NodeName when a new member joins the ring.
NodeName	string	Unique node name to identify this member.
SeedAddresses	[]string	Addresses of other members to join upon start up.
VirtualNodeCount	int	Number of virtual nodes to create on the ring for this member.
HashFunction	HashFunction	Hash function to calculate position of the server on the ring.
MemberType	MemberType	Type of the membership: 1. ShardMember 2. LoadBalancerMember.

Quick Start

Create a new ring member. LoadBalancerMember member has the list of all types of members.

import (
// Other dependencies....
"github.com/Brijeshlakkad/ring"
)

ringMember, err := ring.NewMember(ring.Config{
NodeName:           'Unique_node_name_0', // Node name.
SeedAddresses:      []string{},       // Addresses of other members to join upon start up.
BindAddr:           '127.0.0.1:7946', // The address that Ring will bind to for communication with other members on the ring. By default this is "0.0.0.0:7946".
RPCPort:            '7373',           // The address that Ring will bind to for the member's RPC server. By default this is "127.0.0.1:7373", allowing only loopback connections.
VirtualNodeCount:   '3', // This will create 3 virtual nodes on the ring.
MemberType:         LoadBalancerMember, // This member will not take part in the sharding, but has the list of members (ShardMember) who is responsible for sharding. 
})

Use ringMember#AddListener method to add a new handler to be notified when new node joins on the ring. Look at this Handler interface to implement your own handler.

ringMember.AddListener(listenerId string, handler Handler)

Use ringMember#AddListener method to remove the handler from listening to the joining/leaving of other members. All the handlers' RemoveListener will get called when the member shutdowns.

ringMember.RemoveListener(listenerId string)

Upon join a listener will receive the below parameters in the function call:

1. rpcAddr - RPC address of the new member that has joined the ring.
2. vNodeCount - Number of virtual nodes of the new member on the ring.

Can I contribute to this project?

Feel free to create a PR, I’m more than happy to review and merge it.

What's the long-term goal?

• Onboard videos and documentation
• Clean code, full test coverage and minimal tech debt
• This utility will evolve over time!!!

References (Thank you!)

1. Serf
2. https://en.wikipedia.org/wiki/Consistent_hashing

Documentation

Index

• Variables
• type Config
• type Handler
• type HashFunction
• type MD5HashFunction
• type MemberType
• type MembershipConfig
• type Ring
  • func NewRing(config Config) (*Ring, error)
  • func (r *Ring) AddListener(listenerId string, handler Handler)
  • func (r *Ring) AddResponsibilityChangeListener(listenerId string, handler ShardResponsibilityHandler)
  • func (r *Ring) GetLoadBalancers() []string
  • func (r *Ring) GetNode(objKey string) (map[string]string, bool)
  • func (r *Ring) RemoveListener(listenerId string)
  • func (r *Ring) RemoveResponsibilityChangeListener(listenerId string)
  • func (r *Ring) Shutdown() error
• type ShardResponsibility
  • func (s *ShardResponsibility) ResponsibleNode() string
  • func (s *ShardResponsibility) ResponsibleNodeTags() map[string]string
  • func (s *ShardResponsibility) Transfer(objectKey string) bool
• type ShardResponsibilityHandler

Variables

var (
	ErrRealNodeNotFound = errors.New("real node not found")
)

Types

type Config

type Config struct {
	BindAddr         string
	Tags             map[string]string
	NodeName         string
	SeedAddresses    []string
	VirtualNodeCount int
	HashFunction     HashFunction
	Logger           hclog.Logger
	MemberType       MemberType
}

type Handler

type Handler interface {
	Join(nodeName string, tags map[string]string) error
	Leave(nodeName string) error
}

Handler interface to get notified when a new member joins or existing member leaves the ring.

type HashFunction

type HashFunction interface {
	// contains filtered or unexported methods
}

HashFunction hashes key (string) to uint64.

type MD5HashFunction

type MD5HashFunction struct {
	HashFunction
}

MD5HashFunction Default hash function

type MemberType

type MemberType uint8

const (
	ShardMember        MemberType = iota // RingMember takes part in the sharding.
	LoadBalancerMember                   // Doesn't take part in the sharding, but knows the addresses of member.
)

type MembershipConfig

type MembershipConfig struct {
	NodeName      string
	BindAddr      string
	Tags          map[string]string
	SeedAddresses []string
	// contains filtered or unexported fields
}

type Ring

type Ring struct {
	Config
	// contains filtered or unexported fields
}

func NewRing

func NewRing(config Config) (*Ring, error)

func (*Ring) AddListener

func (r *Ring) AddListener(listenerId string, handler Handler)

AddListener registers the listener that will be called upon the node join/leave event in the ring.

func (*Ring) AddResponsibilityChangeListener

func (r *Ring) AddResponsibilityChangeListener(listenerId string, handler ShardResponsibilityHandler)

AddResponsibilityChangeListener registers the listener that will be called when the current node responsibility changes due to joining of the new nodes.

func (*Ring) GetLoadBalancers

func (r *Ring) GetLoadBalancers() []string

GetLoadBalancers gets the load balancers of the ring.

func (*Ring) GetNode

func (r *Ring) GetNode(objKey string) (map[string]string, bool)

GetNode gets the node responsible for the given #objKey.

func (*Ring) RemoveListener

func (r *Ring) RemoveListener(listenerId string)

RemoveListener removes the listener using the listenerId.

func (*Ring) RemoveResponsibilityChangeListener

func (r *Ring) RemoveResponsibilityChangeListener(listenerId string)

RemoveResponsibilityChangeListener removes the listener from the router using the listenerId.

func (*Ring) Shutdown

func (r *Ring) Shutdown() error

type ShardResponsibility

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

ShardResponsibility to determine if an object should get be transferred to the given node.

func (*ShardResponsibility) ResponsibleNode

func (s *ShardResponsibility) ResponsibleNode() string

func (*ShardResponsibility) ResponsibleNodeTags

func (s *ShardResponsibility) ResponsibleNodeTags() map[string]string

func (*ShardResponsibility) Transfer

func (s *ShardResponsibility) Transfer(objectKey string) bool

type ShardResponsibilityHandler

type ShardResponsibilityHandler interface {
	// OnChange This will be fired if the current node is affected by the new members.
	OnChange([]ShardResponsibility)
}

ShardResponsibilityHandler to listen to responsibility change when any new member joins the ring at the next position of the current node.