cluster

package
v1.4.2 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2024 License: Apache-2.0 Imports: 18 Imported by: 3

Documentation

Overview

Package cluster contains functions and types needed to connect to a Hazelcast cluster.

Port Range

Port Range configuration allows you to specify the port range for cluster addresses where you did not specify any port. If no port range was specified and also no port was set on an address, then the default port range will be applied (5701-5703). If you use a port range in any way, then the client will try all the ports for a given address until it is able to connect to the right member.

Load Balancer

Load balancer configuration allows you to specify which cluster address to send next operation.

If smart client mode is used, only the operations that are not key-based are routed to the member that is returned by the load balancer. Load balancer is ignored for unisocket mode.

The default load balancer is the RoundRobinLoadBalancer, which picks the next address in order among the provided addresses. The other built-in load balancer is RandomLoadBalancer. You can also write a custom load balancer by implementing LoadBalancer.

Use config.Cluster.SetLoadBalancer to set the load balancer: 

config := hazelcast.Config{}
config.Cluster.SetLoadBalancer(cluster.NewRandomLoadBalancer())

Hazelcast Cloud Discovery

Hazelcast Go client can discover and connect to Hazelcast clusters running on Hazelcast Cloud https://cloud.hazelcast.com. In order to activate it, set the cluster name, enable Hazelcast Cloud discovery and add Hazelcast Cloud Token to the configuration. Here is an example: 

config := hazelcast.Config{}
config.Cluster.Name = "MY-CLUSTER-NAME"
cc := &config.Cluster.Cloud
cc.Enabled = true
cc.Token = "MY-CLUSTER-TOKEN"
client, err := hazelcast.StartNewClientWithConfig(config)
if err != nil {
	log.Fatal(err)
}

Also check the code sample in https://github.com/hazelcast/hazelcast-go-client/tree/master/examples/discovery/cloud.

If you have enabled encryption for your cluster, you should also enable TLS/SSL configuration for the client.

External Client Public Address Discovery

When you set up a Hazelcast cluster in the Cloud (AWS, Azure, GCP, Kubernetes) and would like to use it from outside the Cloud network, the client needs to communicate with all cluster members via their public IP addresses. Whenever Hazelcast cluster members are able to resolve their own public external IP addresses, they pass this information to the client. As a result, the client can use public addresses for communication, if it cannot access members via private IPs.

Hazelcast Go client has a built-in mechanism to use public IP addresses instead of private ones. You can enable this feature by setting config.Discovery.UsePublicIP to true and specifying the adddress of at least one member: 

config := hazelcast.Config{}
config.Cluster.Network.SetAddresses("30.40.50.60:5701")
config.Cluster.Discovery.UsePublicIP = true

For more details on member-side configuration, refer to the Discovery SPI section in the Hazelcast IMDG Reference Manual.

Client Connection Strategy

You can configure how the client reconnects to the cluster after a disconnection by setting config.Cluster.ConnectionStrategy.ReconnectMode. cluster.ReconnectModeOn is the default and causes the client to try to reconnect until cluster connection timeout. cluster.ReconnectModeOff disables reconnection. You can control the cluster connection timeout using config.Cluster.ConnectionStrategy.Timeout setting: 

config := hazelcast.Config{}
config.Cluster.ConnectionStrategy.ReconnectMode = cluster.ReconnectModeOn
config.Cluster.ConnectionStrategy.Timeout = types.Duration(5 * time.Minute)

The client tries to reconnect when the client is disconnected from the cluster. The waiting duration before the next reconnection attempt is found using the following formula: 

backoff = minimum(MaxBackoff, InitialBackoff)
duration = backoff + backoff*Jitter*2.0*(RandomFloat64()-1.0)
next(backoff) = minimum(MaxBackoff, backoff*Multiplier)

You can configure the frequency of the reconnection attempts using config.Cluster.ConnectionStrategy.Retry setting: 

config := hazelcast.Config{}
r := &config.Cluster.ConnectionStrategy.Retry
r.MaxBackoff = types.Duration(30*time.Second)
r.InitialBackoff = types.Duration(1*time.Second)
r.Jitter = 0.0
r.Multiplier = 1.05

TLS/SSL

Hazelcast supports encrypted communication between the client and the server using TLS/SSL protocol with key stores and trust stores. This feature requires Hazelcast Enterprise.

In order to use TLS encryption, the Hazelcast members should be configured. See https://docs.hazelcast.com/hazelcast/latest/security/tls-ssl.html#tlsssl-for-hazelcast-members for more information.

In order to enable TLS on the client side, set config.Cluster.Network.SSl.Enabled to true. 

// error handling is omitted for brevity.
var config hazelcast.Config
config.Cluster.Network.SSL.Enabled = true

If you need to set a custom tls.Config, for example to turn off verification, you need to assign the tls.Config before any other SSL configuration, except Enabled: Check out this page for further details about tls.Config options: https://pkg.go.dev/crypto/tls#Config 

// warning: never set InsecureSkipVerify: true on production
// config.Cluster.Network.SSL.SetTLSConfig(&tls.Config{InsecureSkipVerify: true})

You need to set the host name with: 

config.Cluster.Network.SSL.ServerName = "foo.com"

Certificates of the Hazelcast members can be validated against CA file. SSLConfig.SetCAPath()'s argument should point to the absolute path of the concatenated CA certificates in PEM format. When SSL is enabled and CA file path is not set, a set of default CA certificates from default locations will be used. 

// error handling is omitted for brevity.
var config hazelcast.Config
_ := config.Cluster.Network.SSL.SetCAPath("/path/of/server.pem")
client, _ := hazelcast.StartNewClientWithConfig(ctx, config)

When mutual authentication is enabled on the member side, clients or other members should also provide a certificate file that identifies themselves. Then, Hazelcast members can use these certificates to validate the identity of their peers. To enable mutual authentication, firstly, you need to set the following property on the server side in the hazelcast.xml file: 

<network>
  <ssl enabled="true">
    <properties>
      <property name="javax.net.ssl.mutualAuthentication">REQUIRED</property>
    </properties>
  </ssl>
</network>

Client certificate, private key and private key password can be set using the SSLConfig.AddClientCertAndEncryptedKeyPath() method. The arguments should point to the absolute paths of the client certificate and private key in PEM format. If the private key is encrypted using a password, third argument will be used to decrypt it. 

// error handling is omitted for brevity.
var config hazelcast.Config
_ := config.Cluster.Network.SSL.AddClientCertAndEncryptedKeyPath("/path/of/cert.pem", "path/of/key.pem", "password")
client, _ := hazelcast.StartNewClientWithConfig(ctx, config)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Address 

type Address string

Address is the address of a Hazelcast member

func NewAddress 

func NewAddress(host string, port int32) Address

func (Address) Equal 

func (a Address) Equal(b Address) bool

func (Address) String 

func (a Address) String() string

type CloudConfig 

type CloudConfig struct {
	// Token is the Hazelcast Cloud token.
	Token string `json:",omitempty"`
	// Enabled enables Hazelcast Cloud integration.
	Enabled bool `json:",omitempty"`
	// ExperimentalAPIBaseURL sets the Viridian API base URL.
	// You generally should leave its value unset.
	// Note that this configuration may be modified or removed anytime.
	ExperimentalAPIBaseURL string `json:",omitempty"`
}

CloudConfig contains configuration for Hazelcast Cloud.

func (CloudConfig) Clone 

func (h CloudConfig) Clone() CloudConfig

func (CloudConfig) Validate 

func (h CloudConfig) Validate() error

type Config 

type Config struct {

	// Security contains security related configuration such as credentials.
	Security SecurityConfig
	// Discovery contains configuration related to discovery of Hazelcast members.
	Discovery DiscoveryConfig
	// Name is the cluster name.
	Name string `json:",omitempty"`
	// Cloud contains Hazelcast Cloud related configuration.
	Cloud CloudConfig
	// Network contains connection configuration.
	Network NetworkConfig
	// ConnectionStrategy contains cluster connection strategy configuration.
	ConnectionStrategy ConnectionStrategyConfig
	// InvocationTimeout is the maximum time to wait for the response of an invocation.
	InvocationTimeout types.Duration `json:",omitempty"`
	// HeartbeatInterval is the frequency of sending pings to the cluster to keep the connection alive.
	HeartbeatInterval types.Duration `json:",omitempty"`
	// HeartbeatTimeout is the maximum time to wait for the response of a ping before closing the connection.
	HeartbeatTimeout types.Duration `json:",omitempty"`
	// RedoOperation enables retrying some errors even when they are not retried by default.
	RedoOperation bool `json:",omitempty"`
	// Unisocket disables smart routing and enables unisocket mode of operation.
	Unisocket bool `json:",omitempty"`
	// contains filtered or unexported fields
}

Config contains cluster and connection configuration.

func (*Config) Clone 

func (c *Config) Clone() Config

func (*Config) LoadBalancer 

func (c *Config) LoadBalancer() LoadBalancer

LoadBalancer returns the load balancer.

func (*Config) SetLoadBalancer 

func (c *Config) SetLoadBalancer(lb LoadBalancer)

SetLoadBalancer sets the load balancer for the cluster. If load balancer is nil, the default load balancer is used.

func (*Config) Validate 

func (c *Config) Validate() error

type ConnectionRetryConfig 

type ConnectionRetryConfig struct {
	// InitialBackoff is the duration to wait for before the first reconnection attempt.
	// Defaults to 1 second.
	InitialBackoff types.Duration `json:",omitempty"`
	// MaxBackoff is the maximum duration to wait for before the next reconnection attempt.
	// Defaults to 30 seconds.
	MaxBackoff types.Duration `json:",omitempty"`
	// Multiplier controls the speed of increasing backoff duration.
	// Defaults to 1.05.
	// Should be greater than or equal to 1.
	Multiplier float64 `json:",omitempty"`
	// Jitter controls the amount of randomness introduces to reduce contention.
	// Defaults to 0.
	Jitter float64 `json:",omitempty"`
}

ConnectionRetryConfig contains configuration to computer the waiting the duration between connection attempts.

The waiting duration before the next reconnection attempt is found using the following formula: 

backoff = minimum(MaxBackoff, InitialBackoff)
duration = backoff + backoff*Jitter*2.0*(RandomFloat64()-1.0)
next(backoff) = minimum(MaxBackoff, backoff*Multiplier)

func (ConnectionRetryConfig) Clone 

func (c ConnectionRetryConfig) Clone() ConnectionRetryConfig

func (*ConnectionRetryConfig) Validate 

func (c *ConnectionRetryConfig) Validate() error

type ConnectionStrategyConfig 

type ConnectionStrategyConfig struct {
	// Retry contains the backoff configuration.
	Retry ConnectionRetryConfig
	// Timeout is the maximum time before giving up reconnecting to a cluster.
	// Default is 0, infinite duration when failover is not enabled and 120 seconds when it is enabled.
	Timeout types.Duration `json:",omitempty"`
	// ReconnectMode enables or disables reconnecting to a cluster.
	ReconnectMode ReconnectMode `json:",omitempty"`
}

ConnectionStrategyConfig contains configuration for reconnecting to a cluster.

func (ConnectionStrategyConfig) Clone 

func (c ConnectionStrategyConfig) Clone() ConnectionStrategyConfig

func (*ConnectionStrategyConfig) Validate 

func (c *ConnectionStrategyConfig) Validate() error

type CredentialsConfig 

type CredentialsConfig struct {
	Username string `json:",omitempty"`
	Password string `json:",omitempty"`
}

func (CredentialsConfig) Clone 

func (c CredentialsConfig) Clone() CredentialsConfig

func (CredentialsConfig) Validate 

func (c CredentialsConfig) Validate() error

type DiscoveryConfig 

type DiscoveryConfig struct {
	// Strategy is a discovery.Strategy implementation.
	// See the documentation in the discovery package.
	Strategy discovery.Strategy `json:",omitempty"`
	// UsePublicIP causes the client to use the public addresses of members instead of their private addresses, if available.
	UsePublicIP bool `json:",omitempty"`
}

func (DiscoveryConfig) Clone 

func (c DiscoveryConfig) Clone() DiscoveryConfig

func (DiscoveryConfig) Validate 

func (c DiscoveryConfig) Validate() error

type EndpointQualifier 

type EndpointQualifier struct {
	Identifier string
	Type       EndpointQualifierType
}

type EndpointQualifierType 

type EndpointQualifierType int32
const (
	EndpointQualifierTypeMember   EndpointQualifierType = 0
	EndpointQualifierTypeClient   EndpointQualifierType = 1
	EndpointQualifierTypeWan      EndpointQualifierType = 2
	EndpointQualifierTypeRest     EndpointQualifierType = 3
	EndpointQualifierTypeMemCache EndpointQualifierType = 4
)

func (EndpointQualifierType) String 

func (t EndpointQualifierType) String() string

type FailoverConfig added in v1.1.0 

type FailoverConfig struct {
	// Configs is the configured list of failover cluster configurations.
	// Together with the main configuration (Cluster option), they form
	// the list of alternative cluster configs.
	//
	// The Cluster option and the cluster configurations from this list must
	// be exactly the same except the following options:
	// * Name
	// * Security
	// * Network.SSL
	// * Network.Addresses
	// * Cloud
	Configs []Config `json:",omitempty"`
	// TryCount is the count of attempts to connect to a cluster.
	//
	// For each alternative cluster, the client will try to connect to the
	// cluster respecting related ConnectionStrategy.Retry.
	//
	// When the client can not connect a cluster, it will try to connect
	// TryCount times going over the alternative client configs in a
	// round-robin fashion. This is triggered at the start and also when
	// the client disconnects from the cluster and can not connect back to
	// it by exhausting attempts described in connectionRetry config. In
	// that case, the client will continue from where it is left off in the
	// cluster configurations list, and try the next one again in round-robin
	// TryCount times.
	//
	// For example, if one failover cluster is given in the Configs list and
	// the TryCount is set as 4, the maximum number of subsequent connection
	// attempts done by the client is 4 x 2 = 8.
	//
	// When a zero value is provided, math.MaxInt32 is used instead as the
	// value for this option.
	TryCount int `json:",omitempty"`
	// Enabled is the enable failover behavior of the client.
	Enabled bool `json:",omitempty"`
}

FailoverConfig allows configuring multiple client configs to be used by a single client instance. The client will try to connect them in the given order. When the connected cluster fails or the client gets blacklisted from the cluster via the Management Center, the client will search for alternative clusters with given configs.

func (*FailoverConfig) Clone added in v1.1.0 

func (c *FailoverConfig) Clone() FailoverConfig

func (*FailoverConfig) SetConfigs added in v1.1.0 

func (c *FailoverConfig) SetConfigs(configs ...Config)

SetConfigs sets the cluster configuration list.

func (*FailoverConfig) Validate added in v1.1.0 

func (c *FailoverConfig) Validate(root Config) error

type LoadBalancer 

type LoadBalancer interface {
	// OneOf returns one of the given addresses.
	// addrs contains at least one item.
	// Order of addresses may change between calls.
	// Assume access to this function is synchronized.
	// This function should return as soon as possible, should never block.
	OneOf(addrs []Address) Address
}

LoadBalancer is used to select the next connection when sending invocations.

type MemberInfo 

type MemberInfo struct {
	Attributes map[string]string
	AddressMap map[EndpointQualifier]Address
	Address    Address
	UUID       types.UUID
	Version    MemberVersion
	LiteMember bool
}

MemberInfo represents a member in the cluster.

func (*MemberInfo) PublicAddress 

func (mi *MemberInfo) PublicAddress() (addr Address, ok bool)

PublicAddress returns the public address and ok == true if member contains a public address.

func (MemberInfo) String 

func (mi MemberInfo) String() string

type MemberVersion 

type MemberVersion struct {
	Major byte
	Minor byte
	Patch byte
}

MemberVersion is the version of the member

func (MemberVersion) MajorMinor added in v1.2.0 

func (m MemberVersion) MajorMinor() uint16

func (MemberVersion) String added in v1.2.0 

func (m MemberVersion) String() string

type MembershipState 

type MembershipState int
const (
	MembershipStateAdded MembershipState = iota
	MembershipStateRemoved
)

func (MembershipState) String 

func (m MembershipState) String() string

type MembershipStateChangeHandler 

type MembershipStateChangeHandler func(event MembershipStateChanged)

type MembershipStateChanged 

type MembershipStateChanged struct {
	Member MemberInfo
	State  MembershipState
}

func (*MembershipStateChanged) EventName 

func (e *MembershipStateChanged) EventName() string

type NetworkConfig 

type NetworkConfig struct {
	SSL               SSLConfig      `json:",omitempty"`
	Addresses         []string       `json:",omitempty"`
	PortRange         PortRange      `json:",omitempty"`
	ConnectionTimeout types.Duration `json:",omitempty"`
}

func (*NetworkConfig) Clone 

func (c *NetworkConfig) Clone() NetworkConfig

func (*NetworkConfig) SetAddresses 

func (c *NetworkConfig) SetAddresses(addrs ...string)

SetAddresses sets the candidate address list that client will use to establish initial connection. Other members of the cluster will be discovered when the client starts.

func (*NetworkConfig) SetPortRange added in v1.1.0 

func (c *NetworkConfig) SetPortRange(min int, max int)

func (*NetworkConfig) Validate 

func (c *NetworkConfig) Validate() error

type PortRange added in v1.1.0 

type PortRange struct {
	Min int `json:",omitempty"`
	Max int `json:",omitempty"`
}

func (*PortRange) Clone added in v1.1.0 

func (pr *PortRange) Clone() PortRange

type RandomLoadBalancer 

type RandomLoadBalancer rand.Rand

RandomLoadBalancer selects the next address randomly.

func NewRandomLoadBalancer 

func NewRandomLoadBalancer() *RandomLoadBalancer

NewRandomLoadBalancer creates a new RandomLoadBalancer with a predefined seed.

func (*RandomLoadBalancer) OneOf 

func (lb *RandomLoadBalancer) OneOf(addrs []Address) Address

OneOf selects a random address from the given list and returns it

type ReconnectMode 

type ReconnectMode int

ReconnectMode enables or disables reconnecting to a cluster. 

const (
	// ReconnectModeOn enables reconnecting to a cluster.
	ReconnectModeOn ReconnectMode = iota
	// ReconnectModeOff disables reconnecting to a cluster.
	ReconnectModeOff
)

func (ReconnectMode) MarshalText 

func (rm ReconnectMode) MarshalText() ([]byte, error)

func (*ReconnectMode) UnmarshalText 

func (rm *ReconnectMode) UnmarshalText(b []byte) error

type RoundRobinLoadBalancer 

type RoundRobinLoadBalancer int

RoundRobinLoadBalancer selects the next address in order.

func NewRoundRobinLoadBalancer 

func NewRoundRobinLoadBalancer() *RoundRobinLoadBalancer

NewRoundRobinLoadBalancer creates a new RoundRobinLoadBalancer

func (*RoundRobinLoadBalancer) OneOf 

func (r *RoundRobinLoadBalancer) OneOf(addrs []Address) Address

OneOf selects the next address in order from the given address list.

type SSLConfig 

type SSLConfig struct {

	// ServerName sets the host name of the server.
	ServerName string `json:",omitempty"`
	Enabled    bool   `json:",omitempty"`
	// contains filtered or unexported fields
}

SSLConfig is SSL configuration for client. SSLConfig has tls.Config embedded in it so that users can set any field of tls config as they wish.

func (*SSLConfig) AddClientCertAndEncryptedKeyPath 

func (c *SSLConfig) AddClientCertAndEncryptedKeyPath(certPath string, privateKeyPath string, password string) error

AddClientCertAndEncryptedKeyPath decrypts the keyfile with the given password and adds client certificate path and the decrypted client private key to tls config. The files in the given paths must contain PEM encoded data. The key file should have a DEK-info header otherwise an error will be returned. In order to add multiple client certificate-key pairs one should call this function for each of them. If certificates is empty then no certificate will be sent to the server. If this is unacceptable to the server then it may abort the handshake. For mutual authentication at least one client certificate should be added. It returns an error if any of files cannot be loaded.

func (*SSLConfig) AddClientCertAndKeyPath 

func (c *SSLConfig) AddClientCertAndKeyPath(clientCertPath string, clientPrivateKeyPath string) error

AddClientCertAndKeyPath adds client certificate path and client private key path to tls config. The files in the given paths must contain PEM encoded data. In order to add multiple client certificate-key pairs one should call this function for each of them. If certificates is empty then no certificate will be sent to the server. If this is unacceptable to the server then it may abort the handshake. For mutual authentication at least one client certificate should be added. It returns an error if any of files cannot be loaded.

func (*SSLConfig) Clone 

func (c *SSLConfig) Clone() SSLConfig

func (*SSLConfig) SetCAPath 

func (c *SSLConfig) SetCAPath(path string) error

SetCAPath sets CA file path.

func (*SSLConfig) SetTLSConfig 

func (c *SSLConfig) SetTLSConfig(tlsConfig *tls.Config)

SetTLSConfig overrides the internal TLS configuration. Use this method only when you want to replace the internal TLS configuration. It should be called before calling any other methods or setting any fields.

func (*SSLConfig) TLSConfig 

func (c *SSLConfig) TLSConfig() *tls.Config

TLSConfig returns the clone of internal TLS configuration.

func (*SSLConfig) Validate 

func (c *SSLConfig) Validate() error

type SecurityConfig 

type SecurityConfig struct {
	Credentials CredentialsConfig
}

func (SecurityConfig) Clone 

func (c SecurityConfig) Clone() SecurityConfig

func (*SecurityConfig) Validate 

func (c *SecurityConfig) Validate() error

Source Files

View all Source files

Directories

Path Synopsis

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.