go_cluster

README

Go Cluster

P2P model of clustering for Go.

This project aims to be minimal, performance and code size wise.

Note

The package uses gob for encoding messages, before using the library register all of the message types to gob.

More on that gob docs Register method

Why?

Go has a great concurrency model that makes the language be frequently used for RPC.

The purpose of this project is to provide a simple and efficient solution to cluster Go microservices easily.

How?

Peer to peer connectivity, using a custom protocol over TCP. TCP was chosen because of it's reliability.

The model itself isn't a master-slave model, this lets the every node to be independent on each other. Each node can introduce new nodes to all of the other nodes. Each node is identified with a custom ID, so nodes can communicate with each other as well.

Features

• Resilent - Every node is independent of other nodes so when a node crashes the cluster is still stable.
• Fast - The package uses the gob encoding which is very fast and efficient
• Customizable - The Message interface is supposed to be customizable, send any type of message you'd like over the cluster.

Documentation

Overview

TODO Add heartbeat mechanism

This file contains structs and functions for the nodes.

Index

• func Init()
• func RegisterMessage(msg Message)
• type Connection
  • func (c Connection) Close() error
  • func (c Connection) Write(msg Message) error
• type ErrorMessage
  • func (m ErrorMessage) Msg() interface{}
  • func (m ErrorMessage) Type() string
• type GreetingMessage
  • func (m GreetingMessage) Msg() interface{}
  • func (m GreetingMessage) Type() string
• type IntroduceMessage
  • func (m IntroduceMessage) Msg() interface{}
  • func (m IntroduceMessage) Type() string
• type Message
• type NewNodeMessage
  • func (m NewNodeMessage) Msg() interface{}
  • func (m NewNodeMessage) Type() string
• type Node
  • func CreateCluster(address string, data interface{}) *Node
  • func JoinCluster(address, maddress string, data interface{}) (*Node, error)
  • func (n Node) Broadcast(message Message, except ...int) error
  • func (n *Node) Close()
  • func (n Node) Log(args ...interface{})
  • func (n Node) Send(message Message, ids ...int) error
• type ReadyMessage
  • func (m ReadyMessage) Msg() interface{}
  • func (m ReadyMessage) Type() string
• type Transport

Functions

func Init

func Init()

func RegisterMessage

func RegisterMessage(msg Message)

Register the message type to gob

Types

type Connection

type Connection struct {
	Conn *net.TCPConn // The connection
	Data interface{}  // The remote node's extra data
}

Resembles a connection between two nodes.

func (Connection) Close

func (c Connection) Close() error

Close the connection

func (Connection) Write

func (c Connection) Write(msg Message) error

Write a message to the connection

type ErrorMessage

type ErrorMessage struct {
	Err error
}

A message containing only errors

func (ErrorMessage) Msg

func (m ErrorMessage) Msg() interface{}

func (ErrorMessage) Type

func (m ErrorMessage) Type() string

type GreetingMessage

type GreetingMessage struct {
	Id   int
	Data interface{}
}

The message a node sends to the node it's newly connected to with its id to make authentication easier

func (GreetingMessage) Msg

func (m GreetingMessage) Msg() interface{}

func (GreetingMessage) Type

func (m GreetingMessage) Type() string

type IntroduceMessage

type IntroduceMessage struct {
	Addr string
	Data interface{}
}

The message a new node sends to the master with its information

func (IntroduceMessage) Msg

func (m IntroduceMessage) Msg() interface{}

func (IntroduceMessage) Type

func (m IntroduceMessage) Type() string

type Message

type Message interface {
	Type() string
	Msg() interface{}
}

The Message interface, this is supposed to be customized (for example Msg is encoded in gob).

type NewNodeMessage

type NewNodeMessage struct {
	Id   int         // The Id
	Addr string      // The address to connect to
	Data interface{} // The new node's data
}

The message the master sends when all nodes when a new node joins

func (NewNodeMessage) Msg

func (m NewNodeMessage) Msg() interface{}

func (NewNodeMessage) Type

func (m NewNodeMessage) Type() string

type Node

type Node struct {
	Addr    string       // Incoming connections address
	Ready   bool         // Whether is node is ready for connections
	Id      int          // This node's ID
	NextId  int          // Next client's id
	Message chan Message // The channel to forward messages to
	Nodes   *sync.Map    // A map that maps other node ids to their connections.
	Data    interface{}  // Allows the node to have extra information attached to it
}

The node is the general data type in go-cluster, it resembles a node in the cluster

func CreateCluster

func CreateCluster(address string, data interface{}) *Node

Creates a new master node This new node will introduce other nodes to each other.

func JoinCluster

func JoinCluster(address, maddress string, data interface{}) (*Node, error)

Creates a new node and connects to the master

func (Node) Broadcast

func (n Node) Broadcast(message Message, except ...int) error

Sends a message to all nodes

func (*Node) Close

func (n *Node) Close()

Shuts down the node, if the node is the master it will broadcast the new master to all nodes before closing. It accepts a channel that will receive a boolean when the node is shutdown.

func (Node) Log

func (n Node) Log(args ...interface{})

func (Node) Send

func (n Node) Send(message Message, ids ...int) error

Sends a message to a specific amount of nodes

type ReadyMessage

type ReadyMessage struct {
	Id      int
	EntryId int
}

The message the master sends to a newly connected node with its id

func (ReadyMessage) Msg

func (m ReadyMessage) Msg() interface{}

func (ReadyMessage) Type

func (m ReadyMessage) Type() string

type Transport

type Transport struct {
	Type    string
	Message Message
}

The transport protocol