serf-handler 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89e48bd05d6d46a7feeade8446bc03f7a7f2a7f456bca0496f05376bb34beefc
+  data.tar.gz: 8f86ce486ec9db1c382bccac2a6fc78656fa9a7d77e9ce7e3ab081aa0fc5219b
+SHA512:
+  metadata.gz: '095ade60b063e1d407de476c05004957ed7a7387184ca970cba1398d24fef5af58b43ddbc8bb08dec48e81d9f8d0055cdf07b98e7beb9803203f535a1d15b07a'
+  data.tar.gz: 49164a7711e770f76335ea4941d4adf2d6a221b8343e81eeb75af4f75492e168dbf50b72fa9a92686b273ad8c9c374963b0a576f42aa0281f76fb793db08b2a2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in serf-handler.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Kirk Haines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Kirk Haines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# Serf::Handler
+
+Serf (https://www.serf.io/) is a decentralized tool, by HashiCorp, for managing
+cluster membership, failure detection, and Orchestration. One of Serf's key
+features is the ability to issue queries and trigger events on other agents
+in the cluster. Serf can run arbitrary handlers in order to handle these
+queries and events.
+
+This package encapsulates a small, simple library to facilitate writing flexible
+Serf handlers with Ruby. Also included in the package is a set of prebuilt
+handlers which can be used immediately in your own Serf cluster.
+
+## Usage
+
+```ruby
+require 'serf/handler'
+
+Serf::Handler.run
+```
+
+No additional code is necessary to implement a Serf handler. This basic
+implementation is available in `bin/serf-handler.rb`.
+
+Specific query/event handlers are implemented as Ruby classes, by `include`ing
+`Serf::Handler` into your class. A very basic DSL is provided to aid
+implementation.
+
+```ruby
+require 'serf/handler'
+include Serf::Handler
+
+describe "Provide a list of all available handlers."
+
+on :query, 'list-handlers', 0 do |event|
+  Serf::Handler::Tasks.collect do |task|
+    "#{task.type}: #{task.name}\n"
+  end.join
+end
+```
+
+* `describe`: Attach a human readable description to whatever event is defined next.
+* `on`: Takes two, or, optionally, three arguments (type, name, order) to describe the task, and a block that implements the task.
+
+When a query or an event is received by the handler, it will run any tasks with
+a matching type that do not have a name, in an order described by sorting the
+tasks numerically on their order value. The default value for order, if not
+given, is 0. It will then run any named task or tasks with a matching name.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `rake test` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/wyhaines/serf-handler.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "serf/handler"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/serf-handler

@@ -0,0 +1,5 @@
+#!/bin/env ruby
+
+require 'serf/handler'
+
+Serf::Handler.run

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/serf/handler.rb

@@ -0,0 +1,101 @@
+require "serf/handler/version"
+require "serf/handler/cli"
+require "serf/handler/tasklist"
+require "serf/handler/event"
+require "json"
+
+module Serf
+  module Handler
+
+    Tasks = TaskList.new
+
+    def describe(*strings)
+      description = ''
+      strings.each do |line|
+        if description[-1] =~ /[^\s]/ && line[0] =~ /[^\s]/
+          description << " #{line}"
+        else
+          description << line
+        end
+      end
+
+      @_handler_description = description
+    end
+
+    def on(*args, &block)
+      if Hash === args.first
+        type = args[:type]
+        name = args[:name]
+        order = args[:order]
+      else
+        type, name, order = *args
+      end
+
+      type = :event if type == :user
+      type ||= :query
+      name ||= nil
+      order ||= 0
+
+      desc = @_handler_description
+      @_handler_description = ''
+      Tasks << Task.new(type, name, order, desc, &block)
+    end
+
+    class << self
+
+      def run
+        load_tasks
+        result = run_tasks
+        STDOUT.write ( result.length > 1 ? result.to_json : result.first )
+      end
+
+      def event
+        unless @event
+          config = Serf::Handler::Cli.new
+          @event = Serf::Handler::Event.new( config )
+        end
+
+        @event
+      end
+
+      def load_tasks
+        sources = []
+        sources << ENV['SERF_HANDLER_CONFIG'] if ENV['SERF_HANDLER_CONFIG']
+        sources += find_serf_handler_directories
+        source = sources.collect {|s| File.join(s, 'config.rb')}.
+                         select {|s| FileTest.exist?(s)}.first
+        require File.expand_path(source) if source
+      end
+
+      def find_serf_handler_directories
+        sources = []
+        sources << File.join(Dir.pwd,'.serf-handler')
+        sources << File.join(Dir.home, '.serf-handler') if Dir.home rescue nil
+        sources << '/etc/serf/handlers/.serf-handler'
+        sources.select {|s| FileTest.exist?(s)}
+      end
+
+      def run_tasks
+        result = []
+        Tasks.sort.each do |task|
+          next if task.type && task.type != event.type
+          begin
+            if task.type == :event && ( task.name.to_s.empty? || task.name.to_s == event.name.to_s )
+              task.call event
+            elsif task.type == :query && ( task.name.to_s.empty? || task.name.to_s == event.name.to_s )
+              result << task.call( event )
+            end
+          rescue Exception => e
+            result << "ERROR: #{e}"
+          end
+        end
+
+        result
+      end
+
+    end
+  end
+end
+
+require 'serf/handler/events/list-handlers'
+require 'serf/handler/events/describe-handler'

data/lib/serf/handler/cli.rb

@@ -0,0 +1,23 @@
+require 'optparse'
+
+module Serf
+  module Handler
+    class Cli < Hash
+      def initialize
+        OptionParser.new do |opts|
+          opts.banner = "Usage: handler [options]\n\nWhen given CLI options, payload items that are normally passed to the handler via Serf can be specified manually."
+          opts.separator ''
+          opts.on('-t','--type [TYPE]',[:query, :event],'The type of request to trigger -- a query or an event. Defaults to an event.') do |type|
+            self[:type] = type
+          end
+          opts.on('-n','--name [NAME]',String,'The name of the query or event to trigger.') do |name|
+            self[:name] = name
+          end
+          opts.on('-p','--payload [PAYLOAD]',String,'The payload to deliver to the event handler that processes the request.') do |payload|
+            self[:payload] = payload.to_s
+          end
+        end.parse!
+      end
+    end
+  end
+end

data/lib/serf/handler/event.rb

@@ -0,0 +1,15 @@
+module Serf
+  module Handler
+    class Event
+      attr_accessor :type, :name, :payload
+
+      def initialize(cli = {})
+        @type = cli[:type] || ENV['SERF_EVENT']&.to_sym || :query
+        @type = :event if @type == :user
+        @name = cli[:name] || ( @type == :query ? ENV['SERF_QUERY_NAME'] : ENV['SERF_USER_EVENT'] )
+        @payload = cli[:payload] || STDIN.read
+        @payload.strip!
+      end
+    end
+  end
+end

data/lib/serf/handler/events/describe-handler.rb

@@ -0,0 +1,15 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Takes the name of a handler and returns its description. If there are",
+         "multiple handlers with the same name, all matching results will be",
+         "returned."
+
+on :query, 'describe-handler' do |event|
+  name = event.payload.strip
+  Serf::Handler::Tasks.select do |task|
+    name == task.name
+  end.collect do |task|
+    task.description
+  end.join("\n---\n")
+end

data/lib/serf/handler/events/df.rb

@@ -0,0 +1,8 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Return a comma separated table of filesystem information."
+
+on :query, 'df' do |event|
+  `/bin/df -k`.split(/\n/).collect {|r| r.split.join(',').sub(/Mounted,on/,"Mounted on")}.join("\n")
+end

data/lib/serf/handler/events/git-index-deploy.rb

@@ -0,0 +1,46 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Expects a hash code in the payload which will be queried using",
+         "git-index. A 'git fetch --all && git pull' will be executed on all",
+         "matching repositories. Deployment hooks are available in order to",
+         "execute arbitrary code during the deploy process. If any of the",
+         "following files are found in the REPO root directory, they will be",
+         "executed in the order described by their name.\n",
+         ".serf-before-deploy\n",
+         ".serf-after-deploy\n",
+         ".serf-on-deploy-failure\n",
+         ".serf-on-deploy-success\n"
+
+on :event, 'git-index-deploy' do |event|
+  user = `whoami` # Serf's executable environments are stripped of even basic information like HOME
+  dir = `eval echo "~#{user}"`.strip
+  `git-index -d #{dir}/.git-index.db -q #{event.payload}`.split(/\n/).each do |match|
+    hash,data = match.split(/:\s+/,2)
+    path,url = data.split(/\|/,2)
+
+    ENV['SERF_DEPLOY_PAYLOAD'] = event.payload
+    ENV['SERF_DEPLOY_HASH'] = hash
+    ENV['SERF_DEPLOY_PATH'] = path
+    ENV['SERF_DEPLOY_URL'] = url
+
+    success = Dir.chdir(path)
+    break unless success
+
+    if FileTest.exist?(File.join(path, ".serf-before-deploy"))
+      system(File.join(path, ".serf-before-deploy"))
+    end
+
+    success = system("git fetch --all && git pull")
+
+    if success && FileTest.exist?(File.join(path, ".serf-on-deploy-success"))
+      system(File.join(path, ".serf-on-deploy-success"))
+    elsif !success && FileTest.exist?(File.join(path, ".serf-on-deploy-failure"))
+      system(File.join(path, ".serf-on-deploy-failure"))
+    end
+
+    if FileTest.exist?(File.join(path, ".serf-after-deploy"))
+      system(File.join(path, ".serf-after-deploy"))
+    end
+  end
+end

data/lib/serf/handler/events/git-index-list.rb

@@ -0,0 +1,11 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Returns a list of all repositories that git-index knows of, if",
+         "git-index is available to execute."
+
+on :query, 'git-index-list' do |event|
+  user = `whoami` # Serf's executable environments are stripped of even basic information like HOME
+  dir = `eval echo "~#{user}"`.strip
+  `git-index -d #{dir}/.git-index.db --list`
+end

data/lib/serf/handler/events/list-handlers.rb

@@ -0,0 +1,13 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Provide a list of all available handlers."
+
+on :query, 'list-handlers' do |event|
+  r = ''
+  Serf::Handler::Tasks.each do |task|
+    r << "#{task.type}: #{task.name}\n"
+  end
+
+  r
+end

data/lib/serf/handler/events/load_average.rb

@@ -0,0 +1,9 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Return the 1-minute, 5-minute, and 15-minute load averages as a",
+         "comma separated list of values."
+
+on :query, 'load-average' do |event|
+  `/usr/bin/uptime`.gsub(/^.*load\s+averages:\s+/,'').split.join(',').strip
+end

data/lib/serf/handler/events/mpstat.rb

@@ -0,0 +1,9 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Return a comma separated table of CPU performance information",
+         "collected from mpstat."
+
+on :query, 'mpstat' do |event|
+  `/usr/bin/mpstat`.split(/\n/)[2..-1].collect {|r| r.split.join(',').sub(/,/,' ')}.join("\n")
+end

data/lib/serf/handler/events/ping.rb

@@ -0,0 +1,9 @@
+require 'serf/handler' unless Object.const_defined?(:Serf) && Serf.const_defined?(:Handler)
+include Serf::Handler
+
+describe "Return a hearbeat from the system with the amount of time that it",
+         "has been up."
+
+on :query, 'ping' do |event|
+  `/usr/bin/uptime`.sub(/^.*(up[^,]+).*\n?$/,'\1')
+end

data/lib/serf/handler/task.rb

@@ -0,0 +1,38 @@
+module Serf
+  module Handler
+    class Task
+      include Comparable
+
+      attr_accessor :order, :type, :name, :description, :task
+
+      def initialize(type = :query, name = nil, order = 0, description = '', &task)
+        @order = order
+        @type = type
+        @name = name
+        @description = description
+        @task = task
+      end
+
+      def <=>(another_task)
+        if @order < another_task.order
+          -1
+        elsif @order > another_task.order
+          1
+        else
+          if @task.to_s < another_task.task.to_s
+            -1
+          elsif @task.to_s > another_task.task.to_s
+            1
+          else
+            0
+          end
+        end
+      end
+
+      def call(*args)
+        @task.call(*args) if @task
+      end
+
+    end
+  end
+end

data/lib/serf/handler/tasklist.rb

@@ -0,0 +1,8 @@
+require 'serf/handler/task'
+
+module Serf
+  module Handler
+    class TaskList < Array
+    end
+  end
+end

data/lib/serf/handler/version.rb

@@ -0,0 +1,5 @@
+module Serf
+  module Handler
+    VERSION = "1.0.0"
+  end
+end

data/serf-handler.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "serf/handler/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "serf-handler"
+  spec.version       = Serf::Handler::VERSION
+  spec.authors       = ["Kirk Haines"]
+  spec.email         = ["wyhaines@gmail.com"]
+
+  spec.summary       = %q{This is a framework for a modular handler for serf.}
+  spec.description   = <<~EDESC
+    This is a framework for creating handlers for serf, by Hashicorp. The handlers
+    are modular, loading themselves according to a configuration file that
+    indicates what commands are supported, and where to load the code for those
+    commands. The framework will also support executing the handler on the
+    command line, with the serf payload provided on the command line. This is
+    useful for testing.
+  EDESC
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^#{spec.bindir}/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: serf-handler
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kirk Haines
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  This is a framework for creating handlers for serf, by Hashicorp. The handlers
+  are modular, loading themselves according to a configuration file that
+  indicates what commands are supported, and where to load the code for those
+  commands. The framework will also support executing the handler on the
+  command line, with the serf payload provided on the command line. This is
+  useful for testing.
+email:
+- wyhaines@gmail.com
+executables:
+- console
+- serf-handler
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/serf-handler
+- bin/setup
+- lib/serf/handler.rb
+- lib/serf/handler/cli.rb
+- lib/serf/handler/event.rb
+- lib/serf/handler/events/describe-handler.rb
+- lib/serf/handler/events/df.rb
+- lib/serf/handler/events/git-index-deploy.rb
+- lib/serf/handler/events/git-index-list.rb
+- lib/serf/handler/events/list-handlers.rb
+- lib/serf/handler/events/load_average.rb
+- lib/serf/handler/events/mpstat.rb
+- lib/serf/handler/events/ping.rb
+- lib/serf/handler/task.rb
+- lib/serf/handler/tasklist.rb
+- lib/serf/handler/version.rb
+- serf-handler.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: This is a framework for a modular handler for serf.
+test_files: []