cluster

package module
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Nov 14, 2025 License: MIT Imports: 8 Imported by: 0

README

Cluster

Golang Package for System Clustering.


Documentation

Usage

To create a cluster

import (
    "fmt"
    "github.com/clivern/cluster"
)


clus := &cluster.Cluster{}

// Generate a unique name
nodeName := clus.GetNodeName()

// Get a default configs
config := clus.GetConfig()
config.Name = nodeName
config.BindPort = 0 // assign a free port
config.Events = cluster.NewNodeEvents(nil)

// Override configs
clus.SetConfig(config)

clus.AddLocalNode([]string{}) // or []string{"x.x.x.x:port"} in case of the second, third ... node

fmt.Println(clus.GetLocalNode())

// 2020/10/18 20:44:19 [DEBUG] memberlist: Using dynamic bind port 52053
// A node has joined: Clivern-2.local--c5553465-2bc9-4ef1-8a83-384e5a0c4097
// Clivern-2.local--c5553465-2bc9-4ef1-8a83-384e5a0c4097

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, Cluster is maintained under the Semantic Versioning guidelines and release process is predictable and business-friendly.

See the Releases section of our GitHub project for changelogs for each release version of Cluster. It contains summaries of the most noteworthy changes made in each release.

Bug tracker

If you have any suggestions, bug reports, or annoyances please report them to our issue tracker at https://github.com/clivern/cluster/issues

Security Issues

If you discover a security vulnerability within Cluster, please send an email to hello@clivern.com

Contributing

We are an open source, community-driven project so please feel free to join us. see the contributing guidelines for more details.

License

© 2020, Clivern. Released under MIT License.

Cluster is authored and maintained by @clivern.

Documentation

Overview

Package cluster provides a simple interface for creating and managing distributed clusters using the hashicorp/memberlist library. It includes features for node discovery, state synchronization, and load balancing across cluster members.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateUUID4 

func GenerateUUID4() string

GenerateUUID4 generates a new UUID v4 string.

func InArray 

func InArray(val interface{}, array interface{}) bool

InArray checks if a value exists in an array or slice.

func Unset 

func Unset(a []string, i int) []string

Unset removes an element at position i from a string slice.

Types

type Broadcast 

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

Broadcast implements the memberlist.Broadcast interface for state synchronization. It wraps a message and optional notification channel.

func (*Broadcast) Finished added in v0.0.8 

func (b *Broadcast) Finished()

Finished is called when the broadcast has been sent to all nodes. It closes the notification channel if one was provided.

func (*Broadcast) Invalidates added in v0.0.8 

func (b *Broadcast) Invalidates(_ memberlist.Broadcast) bool

Invalidates determines if this broadcast invalidates another broadcast. Returns false to allow all broadcasts to be processed.

func (*Broadcast) Message added in v0.0.8 

func (b *Broadcast) Message() []byte

Message returns the broadcast message bytes.

type Cluster 

type Cluster struct {
	// Config holds the memberlist configuration.
	// See https://github.com/hashicorp/memberlist/blob/master/config.go#L350
	Config *memberlist.Config

	// Memlist is the underlying memberlist instance.
	Memlist *memberlist.Memberlist
}

Cluster represents a cluster node that can join and communicate with other nodes. It wraps the hashicorp/memberlist library to provide a simpler interface.

func (*Cluster) AddLocalNode 

func (c *Cluster) AddLocalNode(members []string) (int, error)

AddLocalNode creates a new memberlist instance and optionally joins existing members. If members is empty, it creates a standalone node. Otherwise, it attempts to join the cluster using the provided member addresses.

func (*Cluster) GetConfig 

func (c *Cluster) GetConfig() *memberlist.Config

GetConfig returns a default local memberlist configuration. The returned config can be modified before calling SetConfig.

func (*Cluster) GetLocalNode 

func (c *Cluster) GetLocalNode() *memberlist.Node

GetLocalNode returns the local node information from the memberlist. Returns nil if the cluster has not been initialized with AddLocalNode.

func (*Cluster) GetNodeName 

func (c *Cluster) GetNodeName() string

GetNodeName generates a unique node name by combining the hostname with a UUID. If hostname cannot be determined, it uses "unknown" as the hostname.

func (*Cluster) SetConfig 

func (c *Cluster) SetConfig(config *memberlist.Config)

SetConfig sets the memberlist configuration for this cluster. The configuration must be set before calling AddLocalNode.

type Delegate added in v0.0.8 

type Delegate struct {
	State      []byte
	Broadcasts *memberlist.TransmitLimitedQueue
	Cluster    *Cluster
	Logger     Logger
}

Delegate implements the memberlist.Delegate interface for cluster state management. It handles state synchronization, broadcasting, and merging remote state.

func NewDelegate added in v0.2.0 

func NewDelegate(logger Logger) *Delegate

NewDelegate creates a new Delegate instance.

func (*Delegate) GetBroadcasts added in v0.0.8 

func (d *Delegate) GetBroadcasts(overhead, limit int) [][]byte

GetBroadcasts returns queued broadcast messages to be sent to other nodes.

func (*Delegate) LocalState added in v0.0.8 

func (d *Delegate) LocalState(_ bool) []byte

LocalState returns the local state to be shared during push/pull synchronization.

func (*Delegate) MergeRemoteState added in v0.0.8 

func (d *Delegate) MergeRemoteState(buf []byte, _ bool)

MergeRemoteState merges remote state received during push/pull synchronization.

func (*Delegate) NodeMeta added in v0.0.8 

func (d *Delegate) NodeMeta(_ int) []byte

NodeMeta returns metadata about this node. Returns empty bytes by default, can be overridden for custom metadata.

func (*Delegate) NotifyMsg added in v0.0.8 

func (d *Delegate) NotifyMsg(msg []byte)

NotifyMsg is called when a broadcast message is received from another node.

func (*Delegate) SetCluster added in v0.0.8 

func (d *Delegate) SetCluster(cluster *Cluster)

SetCluster initializes the delegate with a cluster instance and sets up the broadcast queue. This must be called before using UpdateState or GetBroadcasts.

func (*Delegate) UpdateState added in v0.0.8 

func (d *Delegate) UpdateState(data []byte)

UpdateState updates the local state and queues a broadcast to all cluster nodes.

type Logger added in v0.2.0 

type Logger interface {
	Printf(format string, v ...interface{})
	Println(v ...interface{})
}

Logger is an interface for logging cluster events. Users can implement this interface to provide custom logging behavior.

type Message added in v0.0.8 

type Message struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Message represents a key-value message that can be serialized to JSON.

func (*Message) Bytes added in v0.0.8 

func (m *Message) Bytes() []byte

Bytes serializes the message to JSON bytes. Returns an empty byte slice if marshaling fails.

func (*Message) Load added in v0.0.8 

func (m *Message) Load(data []byte) error

Load deserializes JSON bytes into the message. Returns an error if unmarshaling fails.

type NodeEvents 

type NodeEvents struct {
	Logger Logger
}

NodeEvents handles cluster membership events (join, leave, update). It implements the memberlist.EventDelegate interface. See https://github.com/hashicorp/memberlist/blob/master/event_delegate.go#L7

func NewNodeEvents added in v0.2.0 

func NewNodeEvents(logger Logger) *NodeEvents

NewNodeEvents creates a new NodeEvents instance.

func (*NodeEvents) NotifyJoin 

func (n *NodeEvents) NotifyJoin(node *memberlist.Node)

NotifyJoin is called when a node joins the cluster.

func (*NodeEvents) NotifyLeave 

func (n *NodeEvents) NotifyLeave(node *memberlist.Node)

NotifyLeave is called when a node leaves the cluster.

func (*NodeEvents) NotifyUpdate 

func (n *NodeEvents) NotifyUpdate(node *memberlist.Node)

NotifyUpdate is called when a node's metadata is updated.

type RoundRobinBalancer added in v0.1.1 

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

RoundRobinBalancer distributes requests across cluster nodes using a round-robin algorithm.

func NewRoundRobinBalancer added in v0.1.1 

func NewRoundRobinBalancer(clus *Cluster) *RoundRobinBalancer

NewRoundRobinBalancer creates a new round-robin balancer for the given cluster.

func (*RoundRobinBalancer) Get added in v0.1.1 

func (r *RoundRobinBalancer) Get() *memberlist.Node

Get returns the next node in the round-robin sequence. It automatically refreshes the node pool from the cluster membership.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.