client

README

Serf Client

This repo provide the client package, which is used to interact with a Serf agent using the msgpack RPC system it supports. This is the official reference implementation, and is used inside the Serf CLI to support the various commands.

Full documentation can be found on godoc here.

Documentation

Index

• Constants
• type Config
• type Member
• type NodeResponse
• type QueryParam
• type RPCClient
  • func ClientFromConfig(c *Config) (*RPCClient, error)
  • func NewRPCClient(addr string) (*RPCClient, error)
  • func (c *RPCClient) Close() error
  • func (c *RPCClient) ForceLeave(node string) error
  • func (c *RPCClient) ForceLeavePrune(node string) error
  • func (c *RPCClient) GetCoordinate(node string) (*coordinate.Coordinate, error)
  • func (c *RPCClient) InstallKey(key string) (map[string]string, error)
  • func (c *RPCClient) IsClosed() bool
  • func (c *RPCClient) Join(addrs []string, replay bool) (int, error)
  • func (c *RPCClient) Leave() error
  • func (c *RPCClient) ListKeys() (map[string]int, int, map[string]string, error)
  • func (c *RPCClient) Members() ([]Member, error)
  • func (c *RPCClient) MembersFiltered(tags map[string]string, status string, name string) ([]Member, error)
  • func (c *RPCClient) Monitor(level logutils.LogLevel, ch chan<- string) (StreamHandle, error)
  • func (c *RPCClient) Query(params *QueryParam) error
  • func (c *RPCClient) RemoveKey(key string) (map[string]string, error)
  • func (c *RPCClient) Respond(id uint64, buf []byte) error
  • func (c *RPCClient) Stats() (map[string]map[string]string, error)
  • func (c *RPCClient) Stop(handle StreamHandle) error
  • func (c *RPCClient) Stream(filter string, ch chan<- map[string]interface{}) (StreamHandle, error)
  • func (c *RPCClient) UpdateTags(tags map[string]string, delTags []string) error
  • func (c *RPCClient) UseKey(key string) (map[string]string, error)
  • func (c *RPCClient) UserEvent(name string, payload []byte, coalesce bool) error
• type StreamHandle

Constants

const (
	// This is the default IO timeout for the client
	DefaultTimeout = 10 * time.Second
)

Types

type Config

type Config struct {
	// Addr must be the RPC address to contact
	Addr string

	// If provided, the client will perform key based auth
	AuthKey string

	// If provided, overrides the DefaultTimeout used for
	// IO deadlines
	Timeout time.Duration
}

Config is provided to ClientFromConfig to make a new RPCClient from the given configuration

type Member

type Member struct {
	Name        string // Node name
	Addr        net.IP // Address of the Serf node
	Port        uint16 // Gossip port used by Serf
	Tags        map[string]string
	Status      string
	ProtocolMin uint8 // Minimum supported Memberlist protocol
	ProtocolMax uint8 // Maximum supported Memberlist protocol
	ProtocolCur uint8 // Currently set Memberlist protocol
	DelegateMin uint8 // Minimum supported Serf protocol
	DelegateMax uint8 // Maximum supported Serf protocol
	DelegateCur uint8 // Currently set Serf protocol
}

Member is used to represent a single member of the Serf cluster

type NodeResponse

type NodeResponse struct {
	From    string
	Payload []byte
}

NodeResponse is used to return the response of a query

type QueryParam

type QueryParam struct {
	FilterNodes []string            // A list of node names to restrict query to
	FilterTags  map[string]string   // A map of tag name to regex to filter on
	RequestAck  bool                // Should nodes ack the query receipt
	RelayFactor uint8               // Duplicate response count to be relayed back to sender for redundancy.
	Timeout     time.Duration       // Maximum query duration. Optional, will be set automatically.
	Name        string              // Opaque query name
	Payload     []byte              // Opaque query payload
	AckCh       chan<- string       // Channel to send Ack replies on
	RespCh      chan<- NodeResponse // Channel to send responses on
}

QueryParam is provided to query set various settings.

type RPCClient

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

RPCClient is used to make requests to the Agent using an RPC mechanism. Additionally, the client manages event streams and monitors, enabling a client to easily receive event notifications instead of using the fork/exec mechanism.

func ClientFromConfig

func ClientFromConfig(c *Config) (*RPCClient, error)

ClientFromConfig is used to create a new RPC client given the configuration object. This will return a client, or an error if the connection could not be established.

func NewRPCClient

func NewRPCClient(addr string) (*RPCClient, error)

NewRPCClient is used to create a new RPC client given the RPC address of the Serf agent. This will return a client, or an error if the connection could not be established. This will use the DefaultTimeout for the client.

func (*RPCClient) Close

func (c *RPCClient) Close() error

Close is used to free any resources associated with the client

func (*RPCClient) ForceLeave

func (c *RPCClient) ForceLeave(node string) error

ForceLeave is used to ask the agent to issue a leave command for a given node

func (*RPCClient) ForceLeavePrune

func (c *RPCClient) ForceLeavePrune(node string) error

ForceLeavePrune uses ForceLeave but is used to reap the node entirely

func (*RPCClient) GetCoordinate

func (c *RPCClient) GetCoordinate(node string) (*coordinate.Coordinate, error)

GetCoordinate is used to retrieve the cached coordinate of a node.

func (*RPCClient) InstallKey

func (c *RPCClient) InstallKey(key string) (map[string]string, error)

IntallKey installs a new encryption key onto the keyring

func (*RPCClient) IsClosed

func (c *RPCClient) IsClosed() bool

func (*RPCClient) Join

func (c *RPCClient) Join(addrs []string, replay bool) (int, error)

Join is used to instruct the agent to attempt a join

func (*RPCClient) Leave

func (c *RPCClient) Leave() error

Leave is used to trigger a graceful leave and shutdown of the agent

func (*RPCClient) ListKeys

func (c *RPCClient) ListKeys() (map[string]int, int, map[string]string, error)

ListKeys returns all of the active keys on each member of the cluster

func (*RPCClient) Members

func (c *RPCClient) Members() ([]Member, error)

Members is used to fetch a list of known members

func (*RPCClient) MembersFiltered

func (c *RPCClient) MembersFiltered(tags map[string]string, status string,
	name string) ([]Member, error)

MembersFiltered returns a subset of members

func (*RPCClient) Monitor

func (c *RPCClient) Monitor(level logutils.LogLevel, ch chan<- string) (StreamHandle, error)

Monitor is used to subscribe to the logs of the agent

func (*RPCClient) Query

func (c *RPCClient) Query(params *QueryParam) error

Query initiates a new query message using the given parameters, and streams acks and responses over the given channels. The channels will not block on sends and should be buffered. At the end of the query, the channels will be closed.

func (*RPCClient) RemoveKey

func (c *RPCClient) RemoveKey(key string) (map[string]string, error)

RemoveKey changes the primary encryption key on the keyring

func (*RPCClient) Respond

func (c *RPCClient) Respond(id uint64, buf []byte) error

Respond allows a client to respond to a query event. The ID is the ID of the Query to respond to, and the given payload is the response.

func (*RPCClient) Stats

func (c *RPCClient) Stats() (map[string]map[string]string, error)

Stats is used to get debugging state information

func (*RPCClient) Stop

func (c *RPCClient) Stop(handle StreamHandle) error

Stop is used to unsubscribe from logs or event streams

func (*RPCClient) Stream

func (c *RPCClient) Stream(filter string, ch chan<- map[string]interface{}) (StreamHandle, error)

Stream is used to subscribe to events

func (*RPCClient) UpdateTags

func (c *RPCClient) UpdateTags(tags map[string]string, delTags []string) error

UpdateTags will modify the tags on a running serf agent

func (*RPCClient) UseKey

func (c *RPCClient) UseKey(key string) (map[string]string, error)

UseKey changes the primary encryption key on the keyring

func (*RPCClient) UserEvent

func (c *RPCClient) UserEvent(name string, payload []byte, coalesce bool) error

UserEvent is used to trigger sending an event

type StreamHandle

type StreamHandle uint64

StreamHandle is an opaque handle passed to stop to stop streaming