serfx 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f0ff2a01e8c008418b2e2197c0ee87271c349673
-  data.tar.gz: 6fe0634414b78225c6c898da48d5a2793f96e0b1
+  metadata.gz: ab02aaee627c779f2426f107a2e48d4e876e14b0
+  data.tar.gz: c6429bf923f68a9f5cb13981fcf96377c4e24cc5
 SHA512:
-  metadata.gz: 565e2ad3c3c35d84991b7cd2bd35bb326464506a8cc87a8c2e4b782d2b2808fa04d1d9a5a8466ddbd208718a169a148f69216e42f945326ffc77f5ce72b6f2b4
-  data.tar.gz: b39cdbb74ed2f2df86b354c2f3855a025d780c529cf0cff22e9e71339c44f37744e9c0e298320b01fe3f01d6640a38ef99c0543d247c1ace35c2eada0bbb7d05
+  metadata.gz: 58f1c41cfcd50252d7618e8370a37d86432647d8897c41cb677bbc17c125e19b6b716a264bbedafe3813900b84a6157db4822f7a346eb829ec0d994f4a040694
+  data.tar.gz: 644b79b040b7a4cfbe507b1264d2709622a747dcd4b6f5ba8ed8d2af18067703652748e135452649f82401267456a667eae246e5e9df68d9da805edd1633b3ef

data/README.md

@@ -48,6 +48,100 @@ conn.query('foo', 'bar') do |response|
 end
 ```
 
+## Writing custom handlers
+
+serf agents can be configured to invoke an executable script when an user event is received.
+
+`Serfx::Utils::Handler` module provides a set of helper methods to ease writing ruby based serf event handlers. It wraps the data passed via serf into a convenient `SerfEvent` object, as well as provides observer like API where callbacks can be registered based on event name and type.
+
+For example, following script will respond to any qury event named 'upcase' and return the uppercase version of the original query event's payload
+
+```ruby
+require 'serfx/utils/handler'
+
+include Serfx::Utils::Handler
+
+on :query, 'upcase' do |event|
+  STDOUT.write(event.payload.upcase)
+end
+
+run
+```
+
+Assuming this event handler is configured with `upcase` user event (-event-handler 'query:upcase=/path/to/handler'), it can be used as:
+
+```sh
+serf query -no-ack upcase foo
+Response from 'node1': FOO
+```
+
+## Managing long running tasks via serf handlers
+
+Serf event handler invocations are blocking calls. i.e. serf
+will not process any other event when a handler invocation is
+in progress. Due to this, long running tasks should not be
+invoked as serf handler directly.
+
+AsyncJob helps buildng serf handlers that involve long running commands.
+It starts the command in background, allowing handler code to
+return immediately. It does double fork where the first child process is
+detached (attached to init as parent process) and and the target long
+running task is spawned as a second child process. This allows the first
+child  process to wait and reap the output of actual long running task.
+
+The first child process updates a state file before spawing
+the long ranning task(state='invoking'), during the lon running task
+execution (state='running') and after the spawned process' return
+(state='finished'). This state file provides a convenient way to
+query the current state of an AsyncJob.
+
+AsyncJob porvide four methods to manage jobs. AsyncJob#start will
+start the task. Once started, `AyncJob#state_info` can be used to check
+whether the job is still running or finished. One started a job can be
+either in 'running' state or in 'finished' state. `AsyncJob#reap`
+is used for deleting the state file once the task is finished.
+An AsyncJob can be killed, if its in running state, using the
+`AsyncJob#kill` method. A new AyncJob can not be started unless previous
+AsyncJob with same name/state file is reaped.
+
+```ruby
+require 'serfx/utils/async_job'
+require 'serfx/utils/handler'
+
+include Serfx::Utils::Handler
+
+job = Serfx::Utils::AsyncJob.new(
+  name: "bash_test"
+  command: "bash -c 'for i in `seq 1 300`; do echo $i; sleep 1; done'",
+  state: '/opt/serf/states/long_task'
+  )
+
+on :query, 'bash_test' do |event|
+  case event.payload
+  when 'start'
+    puts job.start
+  when 'kill'
+    puts job.kill
+  when 'reap'
+    puts job.reap
+  when 'check'
+    puts job.state_info
+  else
+    puts 'failed'
+  end
+end
+
+run
+```
+Assuming this handler is configured with `bash_test` query events (-event-handler query:bash_test=/path/to/handler), it can be used as:
+
+```sh
+serf query bash_test start
+serf query bash_test check # check if job is running or finished
+serf query bash_test reap # delete a finished job's state file
+serf query bash_test kill
+```
+
 ## Specifying connection details
 By default Serfx will try to connect to localhost at port 7373 (serf agent's default RPC port). Both `Serfx::Connection#new` as well as `Serfx.connect` accepts a hash specifying connection options i.e host, port, encryption, which can be used to specify non-default values.
 

data/Rakefile

@@ -5,7 +5,7 @@ require 'yard'
 
 RSpec::Core::RakeTask.new("spec")
 
-Rubocop::RakeTask.new(:rubocop) do |task|
+RuboCop::RakeTask.new(:rubocop) do |task|
   task.patterns = ['lib/**/*.rb']
 end
 

data/lib/serfx/commands.rb

@@ -8,7 +8,6 @@ module Serfx
   # Implements all of Serf's rpc commands using
   # Serfx::Connection#request method
   module Commands
-
     # performs initial hanshake of an RPC session. Handshake has to be the
     # first command to be invoked during an RPC session.
     #
@@ -43,13 +42,13 @@ module Serfx
     end
 
     # force a failed node to leave the cluster
-    # 
+    #
     # @param node [String] name of the failed node
     # @return  [Response]
     def force_leave(node)
       request(:force_leave, 'Node' => node)
     end
-    
+
     # join an existing cluster.
     #
     # @param existing [Array] an array of existing serf agents
@@ -58,7 +57,7 @@ module Serfx
     def join(existing, replay = false)
       request(:join, 'Existing' => existing, 'Replay' => replay)
     end
-    
+
     # obtain the list of existing members
     #
     # @return  [Response]
@@ -71,12 +70,13 @@ module Serfx
     # @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]
     def members_filtered(tags, status = 'alive', name = nil)
       filter = {
         'Tags' => tags,
         'Status' => status
-        }
+      }
       filter['Name'] = name unless name.nil?
       request(:members_filtered, filter)
     end
@@ -114,7 +114,7 @@ module Serfx
       end
       [res, t]
     end
-      
+
     # monitor is similar to the stream command, but instead of events it
     # subscribes the channel to log messages from the agent
     #
@@ -123,12 +123,12 @@ module Serfx
     def monitor(loglevel = 'debug')
       request(:monitor, 'LogLevel' => loglevel.upcase)
     end
-    
+
     # stop is used to stop either a stream or monitor
     def stop(sequence_number)
       tcp_send(:stop, 'Stop' => sequence_number)
     end
-    
+
     # leave is used trigger a graceful leave and shutdown of the current agent
     #
     # @return  [Response]

data/lib/serfx/connection.rb

@@ -34,7 +34,7 @@ module Serfx
       remove_key:       [:header, :body],
       list_keys:        [:header, :body],
       stats:            [:header, :body]
-      }
+    }
 
     include Serfx::Commands
     extend Forwardable
@@ -69,7 +69,6 @@ module Serfx
     def unpacker
       @unpacker ||= MessagePack::Unpacker.new(socket)
     end
-    
     # read data from tcp socket and pipe it through msgpack unpacker for
     # deserialization
     #
@@ -77,7 +76,7 @@ module Serfx
     def read_data
       unpacker.read
     end
-    
+
     # takes raw RPC command name and an optional request body
     # and convert them to msgpack encoded data and then send
     # over tcp
@@ -91,7 +90,7 @@ module Serfx
       header = {
         'Command' => command.to_s.gsub('_', '-'),
         'Seq' => seq
-        }
+      }
       Log.info("#{__method__}|Header: #{header.inspect}")
       buff = MessagePack::Buffer.new
       buff << header.to_msgpack
@@ -101,16 +100,15 @@ module Serfx
       @requests[seq] = { header: header, ack?: false }
       seq
     end
-    
+
     # checks if the RPC response header has `error` field popular or not
     # raises [RPCError] exception if error string is not empty
-    # 
+    #
     # @param header [Hash] RPC response header as hash
     def check_rpc_error!(header)
       fail RPCError, header['Error'] unless header['Error'].empty?
     end
 
-
     # read data from the tcp socket. and convert it to a [Response] object
     #
     # @param command [String] RPC command name for which response will be read

data/lib/serfx/exceptions.rb

@@ -1,5 +1,5 @@
 # encoding: UTF-8
 
 module Serfx
-  class RPCError < RuntimeError ; end
+  class RPCError < RuntimeError; end
 end

data/lib/serfx/response.rb

@@ -6,7 +6,6 @@ module Serfx
   # body.
   #
   class Response
-
     # Header is composed of two sub-parts
     # - Seq : an integer representing the original request
     # - Error: a string that represent whether the request made, was

data/lib/serfx/utils/async_job.rb

@@ -3,49 +3,71 @@
 require 'json'
 module Serfx
   module Utils
-
     # Serf event handler invocations are blocking calls. i.e. serf
     # will not process any other event when a handler invocation is
-    # in progress. Due to this limitations long running tasks can not be
-    # orchestrated or invoked as serf handler directly.
+    # in progress. Due to this, long running tasks should not be
+    # invoked as serf handler directly.
+    #
+    # AsyncJob helps buildng serf handlers that involve long running commands.
+    # It starts the command in background, allowing handler code to
+    # return immediately. It does double fork where the first child process is
+    # detached (attached to init as parent process) and and the target long
+    # running task is spawned as a second child process. This allows the first
+    # child  process to wait and reap the output of actual long running task.
+    #
+    # The first child process updates a state file before spawing
+    # the long ranning task(state='invoking'), during the lon running task
+    # execution (state='running') and after the spawned process' return
+    # (state='finished'). This state file provides a convenient way to
+    # query the current state of an AsyncJob.
+    #
+    # AsyncJob porvide four methods to manage jobs. AsyncJob#start will
+    # start the task. Once started, AyncJob#state_info can be used to check
+    # whether the job is still running or finished. One started a job can be
+    # either in 'running' state or in 'finished' state. AsyncJob#reap
+    # is used for deleting the state file once the task is finished.
+    # An AsyncJob can be killed, if its in running state, using the
+    # AsyncJob#kill method. A new AyncJob can not be started unless previous
+    # AsyncJob with same name/state file is reaped.
     #
-    # AsynchJob address this by spawning the task as a background job,
-    # allowing the handler code to return immediately. It does double fork
-    # where the first child process is detached (attached to init as parent
-    # process) and spawn the second child process with the target,
-    # long running task. This allows the parent process to wait and reap the
-    # output of target task and save it in disk so that it can be exposed
-    # via other serf events
+    # Following is an example of writing a serf handler using AsyncJob.
     #
     # @example
     #   require 'serfx/utils/async_job'
     #   require 'serfx/utils/handler'
     #
+    #   include Serfx::Utils::Handler
+    #
     #   job = Serfx::Utils::AsyncJob.new(
     #     name: "bash_test"
-    #     command: "bash -c 'for i in `seq 1 3`; do echo $i; sleep 1; done'",
+    #     command: "bash -c 'for i in `seq 1 300`; do echo $i; sleep 1; done'",
     #     state: '/opt/serf/states/long_task'
     #     )
     #
-    #   on :query, 'task_fire' do |event|
-    #     puts job.run
-    #   end
-    #
-    #   on :query, 'task_check' do |event|
-    #     puts job.state_info.inspect
+    #   on :query, 'bash_test' do |event|
+    #     case event.payload
+    #     when 'start'
+    #       puts job.start
+    #     when 'kill'
+    #       puts job.kill
+    #     when 'reap'
+    #       puts job.reap
+    #     when 'check'
+    #       puts job.state_info
+    #     else
+    #       puts 'failed'
+    #     end
     #   end
     #
-    #   on :query, 'task_kill' do |event|
-    #     puts job.kill
-    #   end
+    #   run
     #
-    #   on :query, 'task_reap' do |event|
-    #     puts job.reap
-    #   end
+    # Which can be managed via serf as:
     #
-    #   run
+    # serf query bash_test start
+    # serf query bash_test check # check if job is running or finished
+    # serf query bash_test reap # delete a finished job's state file
+    # serf query bash_test kill
     class AsyncJob
-
       attr_reader :command, :state_file, :stdout_file, :stderr_file
 
       # @param opts [Hash] specify the job details
@@ -71,7 +93,7 @@ module Serfx
           begin
             Process.kill(sig, state_info['pid'].to_i)
             'success'
-          rescue Exception => e
+          rescue Exception
             'failed'
           end
         else
@@ -102,7 +124,6 @@ module Serfx
         end
       end
 
-
       # start a background daemon and spawn another process to run specified
       # command. writes back state information in the state file
       # after spawning daemon process (state=invoking), after spawning the
@@ -111,7 +132,7 @@ module Serfx
       #
       # @return [String] 'success' if task is started
       def start
-        if exists? or command.nil?
+        if exist? || command.nil?
           return 'failed'
         end
         pid = fork do
@@ -124,11 +145,15 @@ module Serfx
           }
           write_state(state)
           begin
-            child_pid = Process.spawn(command, out: stdout_file, err: stderr_file)
+            child_pid = Process.spawn(
+              command,
+              out: stdout_file,
+              err: stderr_file
+            )
             state[:pid] = child_pid
             state[:status] = 'running'
             write_state(state)
-            _ , status = Process.wait2(child_pid)
+            _, status = Process.wait2(child_pid)
             state[:exitstatus] = status.exitstatus
             state[:status] = 'finished'
           rescue Errno::ENOENT => e
@@ -159,13 +184,15 @@ module Serfx
       #
       # @return [TrueClass, FalseClass] true if the task exists, else false
       def exists?
-        File.exists?(state_file)
+        File.exist?(state_file)
       end
 
       # writes a hash as json in the state_file
       # @param [Hash] state represented as a hash, to be written
       def write_state(state)
-        File.open(state_file, 'w'){|f| f.write(JSON.generate(state))}
+        File.open(state_file, 'w') do |f|
+          f.write(JSON.generate(state))
+        end
       end
     end
   end

data/lib/serfx/utils/handler.rb

@@ -1,6 +1,5 @@
 module Serfx
   module Utils
-
     # helper module to for serf custom handlers
     #
     # serf agents can be configured to invoke an executable
@@ -22,22 +21,20 @@ module Serfx
     #   end
     #   run
     module Handler
-
       # when serf agent invokes a handler it passes the event payload
       # through STDIN. while event metadata such as event type, name etc
       # is passed as a set of environment variables.
       # [SerfEvent] encapsulates such event.
       class SerfEvent
-
         attr_reader :environment, :payload, :type, :name
 
         # @param env [Hash] environment
         # @param stdin [IO] stadard input stream for the event
         def initialize(env = ENV, stdin = STDIN)
-          @environment ={}
+          @environment = {}
           @payload = nil
           @name = nil
-          env.keys.select{|k|k=~/^SERF/}.each do | k|
+          env.keys.select { |k| k =~ /^SERF/ }.each do | k|
             @environment[k] = env[k].strip
           end
           @type = @environment['SERF_EVENT']
@@ -46,13 +43,13 @@ module Serfx
             @name = @environment['SERF_QUERY_NAME']
             begin
               @payload = stdin.read_nonblock(4096).strip
-            rescue Errno::EAGAIN => e
+            rescue Errno::EAGAIN, EOFError
             end
           when 'user'
             @name = @environment['SERF_USER_EVENT']
             begin
               @payload = stdin.read_nonblock(4096).strip
-            rescue Errno::EAGAIN => e
+            rescue Errno::EAGAIN, EOFError
             end
           end
         end
@@ -72,7 +69,7 @@ module Serfx
         event = SerfEvent.new
         callbacks[event.type.downcase.to_sym].each do |cbk|
           if cbk.name
-            cbk.block.call(event) if (event.name === cbk.name)
+            cbk.block.call(event) if event.name === cbk.name
           else
             cbk.block.call(event)
           end
@@ -84,7 +81,7 @@ module Serfx
       SerfCallback = Struct.new(:name, :block)
 
       def callbacks
-        @_callbacks ||= Hash.new{|h,k| h[k] = []}
+        @_callbacks ||= Hash.new { |h, k| h[k] = [] }
       end
     end
   end

data/lib/serfx/version.rb

@@ -2,5 +2,5 @@
 #
 # Provides version as a contsant for the serf gem
 module Serfx
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/spec/data/handler.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require 'serfx/utils/handler'
 
 include Serfx::Utils::Handler
@@ -7,5 +9,4 @@ on :query, 'upcase' do |event|
     STDOUT.write(event.payload.upcase)
   end
 end
-
 run

data/spec/serfx/client_spec.rb

@@ -133,12 +133,16 @@ describe Serfx do
     keys = @conn.list_keys.body['Keys'].keys
     expect(keys).to include('QHOYjmYlxSCBhdfiolhtDQ==')
     @conn.install_key('Ih6cZqutM33tMdoFo1iNyw==')
+    sleep 2
     keys = @conn.list_keys.body['Keys'].keys
     expect(keys).to include('Ih6cZqutM33tMdoFo1iNyw==')
+    sleep 2
     @conn.use_key('Ih6cZqutM33tMdoFo1iNyw==')
     new_keys = @conn.list_keys.body['Keys'].keys
+    sleep 2
     expect(new_keys.first).to eq('Ih6cZqutM33tMdoFo1iNyw==')
     @conn.remove_key('QHOYjmYlxSCBhdfiolhtDQ==')
+    sleep 2
     final_keys = @conn.list_keys.body['Keys'].keys
     expect(final_keys.first).to_not include('QHOYjmYlxSCBhdfiolhtDQ==')
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serfx
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Rnjib Dey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-31 00:00:00.000000000 Z
+date: 2014-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack