module Serfx::Commands

Implements all of Serf’s rpc commands using Serfx::Connection#request method

Public Instance Methods

auth() click to toggle source

authenticate against the serf agent. if RPC credentials are setup, then ‘auth` has to be second command, immediately after `handshake`.

@return [Response]

# File lib/serfx/commands.rb, line 24
def auth
  tcp_send(:auth, 'AuthKey' => @authkey)
  read_response(:auth)
end
event(name, payload = nil, coalesce = true) click to toggle source

fires an user event

@param name [String] a string representing name of the event @param payload [String] payload, default is nil @param coalesce [Boolena] whether serf should coalesce events within same name during similar time frame @return [Response]

# File lib/serfx/commands.rb, line 35
def event(name, payload = nil, coalesce = true)
  event = {
    'Name' => name,
    'Coalesce' => coalesce
  }
  event['Payload'] = payload unless payload.nil?
  request(:event, event)
end
force_leave(node) click to toggle source

force a failed node to leave the cluster

@param node [String] name of the failed node @return [Response]

# File lib/serfx/commands.rb, line 48
def force_leave(node)
  request(:force_leave, 'Node' => node)
end
get_coordinate() click to toggle source

obtain network coordinate of a node

@param node [String] Name of the node @return [Response]

# File lib/serfx/commands.rb, line 217
def get_coordinate
  request(:get_coordinate, 'Node' => node)
end
handshake() click to toggle source

performs initial hanshake of an RPC session. Handshake has to be the first command to be invoked during an RPC session.

@return [Response]

# File lib/serfx/commands.rb, line 15
def handshake
  tcp_send(:handshake, 'Version' => 1)
  read_response(:handshake)
end
install_key(key) click to toggle source

install a new encryption key onto the cluster’s keyring

@param key [String] 16 bytes of base64-encoded data. @return [Response]

# File lib/serfx/commands.rb, line 179
def install_key(key)
  request(:install_key, 'Key' => key)
end
join(existing, replay = false) click to toggle source

join an existing cluster.

@param existing [Array] an array of existing serf agents @param replay [Boolean] Whether events should be replayed upon joining @return [Response]

# File lib/serfx/commands.rb, line 57
def join(existing, replay = false)
  request(:join, 'Existing' => existing, 'Replay' => replay)
end
leave() click to toggle source

leave is used trigger a graceful leave and shutdown of the current agent

@return [Response]

# File lib/serfx/commands.rb, line 135
def leave
  request(:leave)
end
list_keys() click to toggle source

return a list of all encryption keys currently in use on the cluster

@return [Response]

# File lib/serfx/commands.rb, line 202
def list_keys
  request(:list_keys)
end
members() click to toggle source

obtain the list of existing members

@return [Response]

# File lib/serfx/commands.rb, line 64
def members
  request(:members)
end
members_filtered(tags, status = 'alive', name = nil) click to toggle source

obatin the list of cluster members, filtered by tags.

@param tags [Array] an array of tags for filter @param status [Boolean] filter members based on their satatus @param name [String] filter based on exact name or pattern.

@return [Response]

# File lib/serfx/commands.rb, line 75
def members_filtered(tags, status = 'alive', name = nil)
  filter = {
    'Tags' => tags,
    'Status' => status
  }
  filter['Name'] = name unless name.nil?
  request(:members_filtered, filter)
end
monitor(loglevel = 'debug') click to toggle source

monitor is similar to the stream command, but instead of events it subscribes the channel to log messages from the agent

@param loglevel [String] @return [Response]

# File lib/serfx/commands.rb, line 123
def monitor(loglevel = 'debug')
  request(:monitor, 'LogLevel' => loglevel.upcase)
end
query(name, payload, opts = {}, &block) click to toggle source

query is used to issue a new query

@param name [String] name of the query @param payload [String] payload for this query event @param opts [Hash] additional query options @return [Response]

# File lib/serfx/commands.rb, line 145
def query(name, payload, opts = {}, &block)
  params = { 'Name' => name, 'Payload' => payload }
  params.merge!(opts)
  res = request(:query, params)
  loop do
    header = read_data
    check_rpc_error!(header)
    ev = read_data

    # Ignore responses with an empty From field
    break if ev['From'].nil? || ev['From'].empty?

    if ev['Type'] == 'done'
      break
    else
      block.call(ev) if block
    end
  end
  res
end
remove_key(key) click to toggle source

remove a key from the cluster’s keyring

@param key [String] 16 bytes of base64-encoded data. @return [Response]

# File lib/serfx/commands.rb, line 195
def remove_key(key)
  request(:remove_key, 'Key' => key)
end
respond(id, payload) click to toggle source

respond is used with ‘stream` to subscribe to queries and then respond.

@param id [Integer] an opaque value that is assigned by the IPC layer @param payload [String] payload for the response event @return [Response]

# File lib/serfx/commands.rb, line 171
def respond(id, payload)
  request(:respond, 'ID' => id, 'Payload' => payload)
end
stats() click to toggle source

obtain stats about the agent(same as info command)

@return [Response]

# File lib/serfx/commands.rb, line 209
def stats
  request(:stats)
end
stop(sequence_number) click to toggle source

stop is used to stop either a stream or monitor

# File lib/serfx/commands.rb, line 128
def stop(sequence_number)
  tcp_send(:stop, 'Stop' => sequence_number)
end
stream(types, &block) click to toggle source

subscribe to a stream of all events matching a given type filter. Events will continue to be sent until the stream is stopped

@param types [String] comma separated list of events @return [Thread, Response]

# File lib/serfx/commands.rb, line 101
def stream(types, &block)
  res = request(:stream, 'Type' => types)
  t = Thread.new do
    loop do
      header = read_data
      check_rpc_error!(header)
      if header['Seq'] == res.header.seq
        ev = read_data
        block.call(ev) if block
      else
        break
      end
    end
  end
  [res, t]
end
tags(tags, delete_tags = []) click to toggle source

alter the tags on a Serf agent while it is running. A member-update event will be triggered immediately to notify the other agents in the cluster of the change. The tags command can add new tags, modify existing tags, or delete tags

@param tags [Hash] a hash representing tags as key-value pairs @param delete_tags [Array] an array of tags to be deleted @return [Response]

# File lib/serfx/commands.rb, line 92
def tags(tags, delete_tags = [])
  request(:tags, 'Tags' => tags, 'DeleteTags' => delete_tags)
end
use_key(key) click to toggle source

change the primary key, which is used to encrypt messages

@param key [String] 16 bytes of base64-encoded data. @return [Response]

# File lib/serfx/commands.rb, line 187
def use_key(key)
  request(:use_key, 'Key' => key)
end