master

package module
v0.0.0-...-3d827b6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 1, 2019 License: MIT Imports: 8 Imported by: 0

README

CircleCI codecov Go Report Card Godocs

go-master

A simple library for enabling master selection using flexible backends.

With the proliferation of micro-services, there are often cases where a clustered service that already has a shared backend resource will need to implement master selection. This library provides a simple way to enable master selection in a clustered service with a shared backend. It also includes a set of swappable lock implementations for common backends.

Unlike more complex leader election mechanisms based on consensus algorithms, this simply uses a lock on a shared resource. In an environment of micro-services running in a docker orchestration platform it can often be difficult to obtain direct communication channels between all the nodes of a service, and many services will already require a backend database to store shared state. This master selection library is designed to cover those use cases.

Example Use Cases

Database migrations - In-app database migrations can be difficult to run in a clustered application. Use go-master to pick a master node and only run migrations from the master.

One-time tasks - Ensure something is only run by one node in a clustered service. For example sending a email that should only be sent once.

Master Selection

There is a single master at all times. The master is chosen using the master lock backend. All nodes will attempt to become a master, but only one will succeed. The node chosen to be the master will write a heartbeat to the master lock while it is healthy and executing its duties.











Start and Stop Hooks

Custom start and stop hooks can be used to define what happens when a node becomes a master or is no longer a master. When a node becomes a master, the provided start hook function will be executed as a way of notifying your code that the current node is now the master. Similarly, when a node is no longer a master, the stop hook is called. The master selection mechanism does not block on these hook functions nor does it receive an error. If a critical error occurs in your start hook such that this node should not continue as the master, use the Stop() method to stop the node from continuing as a master.

Supported Backends

This library comes with support for a set of backend databases that are commonly used. All backend implementations can be found in go-master/backend, each under their own packages.

Currently supported:

  • MongoDB
  • MySQL
Example MySQL backend usage
	"github.com/InVisionApp/go-master"
	"github.com/InVisionApp/go-master/backend/mysql"

	mysqlBackend := mysql.NewMySQLBackend(&mysql.MySQLBackendConfig{
		User:     "user",
		Password: "pass",
		Host:     "localhost",
		Port:     3306,
		DBName:   "gomaster",
	})

	if err := mysqlBackend.Connect(); err != nil {
		logger.Errorf("Unable to connect to MySQL: %v", err)
		return err
	}
	
	m := master.New(&master.MasterConfig{
		MasterLock: mysqlBackend,
		Logger:     logger,
	})

	if err := m.Start(); err != nil {
		logger.Errorf("Unable to start go-master: %v", err)
		return err
	}


[Credit]

The go-master gopher image by talpert
Original artwork designed by Renée French

Documentation

Index

Constants

View Source
const (
	DefaultHeartbeatFrequency = time.Second * 1
	DefaultVersion            = "unset"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Master

type Master interface {
	Start() error
	Stop() error
	IsMaster() bool
	ID() string

	Status() (interface{}, error)
}

func New

func New(cfg *MasterConfig) Master

type MasterConfig

type MasterConfig struct {
	// Required: Backend that will be used for master election
	MasterLock backend.MasterLock

	// Optional: How often should a master send heartbeats (default: */1s)
	HeartBeatFrequency time.Duration

	// Optional: StartHook func is called as soon as a master lock is achieved.
	// It is the callback to signal becoming a master
	StartHook func()

	// Optional: StopHook func is called when the master lock is lost
	// It is the callback to signal that it is no longer the master.
	// It is not called when the master is stopped manually
	StopHook func()

	// Optional: Error channel to receive go-master related error messages
	Err chan error

	// Optional: Logger for go-master to use (default: new logrus shim will be created)
	Logger log.Logger

	// Optional: If set, workers will NOT perform any work if the master's
	// version differs from their own version. (default: "unset")
	Version string
}

Directories

Path Synopsis
mysql
database initialization functionality
database initialization functionality
fakes
fakebackend
Code generated by counterfeiter.
Code generated by counterfeiter.
fakemaster
Code generated by counterfeiter.
Code generated by counterfeiter.
syncfakes
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL