hello_goodbye 0.1.0

data/.gitignore

@@ -0,0 +1,24 @@
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# For vim:
+*.swp
+
+# built gems
+*.gem
+
+vendor/bundle
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hello_goodbye.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Joshua Murray
+
+MIT License
+
+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,308 @@
+HelloGoodbye
+===============
+A daemon manager with a TCP interface built on top of EventMachine.
+
+Installation
+------------------
+    gem build hello_goodbye.gemspec
+    gem install hello_goodbye-0.1.0.gem
+
+The Foremen Manager
+-------------------
+The foremen manager is the mother-ship for all your custom foremen that will spawn workers (or do whatever you wish).  
+A foreman itself, the manager creates a TCP console of its own so foremen can be reviewed and managed from the manager
+itself.
+
+    manager = HelloGoodbye::ForemenManager.new(:port => 8080, :server => "127.0.0.1")
+    # or...
+    manager = HelloGoodbye.manager(8080, "127.0.0.1")
+
+To register foremen (before "start!"ing the manager), execute code like the following:
+
+    manager.register_foreman( :port => 8081, :class => HelloGoodbye::TestForeman )
+
+If you want to capture errors (and you should -- if the manager goes down, everything is liable to go down with it),
+pass a block to the on_error method as follows:
+
+    manager.on_error do |e|
+      # Do stuff. 
+    end
+
+When you're all set up, fire away with the start! method:
+
+    manager.start!
+
+This will block.  After this is executed, all your manager and all your foremen should be listening in on their respective ports
+for your command.
+
+Consoles
+-------------
+After making a TCP connection to one of the consoles, communication should occur to and from the console using one of the following standard JSON packages.
+
+Commands issued to a service should be formatted as follows:
+
+    {
+      "command": "YOUR COMMAND"
+    }
+
+Responses from the service will be formatted as follows:
+
+    {
+      "success": true,
+      "message": "MESSAGE FROM SERVICE",
+      "results": []
+    }
+
+Note the following: 
+
+* **success** can be **true** for **false**
+* **results** will either be an array of data relavent to the command, or will be absent.
+
+The Manager Console
+--------------------
+Once started, your manager will be available for TCP connections, and will respond to the following commands:
+<table>
+  <tr>
+    <th>Command</th><th>Response Message</th><th>Results</th><th>Action Performed</th>
+  </tr>
+  <tr>
+    <td>
+      hello
+    </td>
+    <td>
+      hello
+    </td>
+    <td>
+      None.
+    </td>
+    <td>
+      Nothing.  Just a convenient way to "ping" the service.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      goodbye
+    </td>
+    <td>
+      goodbye
+    </td>
+    <td>
+      None.
+    </td>
+    <td>
+      Closes the connection.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      foremen 
+    </td>
+    <td>
+      ok
+    </td>
+    <td>
+      An array of hashes with details about each forman. 
+    </td>
+    <td>
+      Nothing.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      start XX 
+    </td>
+    <td>
+      "ok" if successful.
+    </td>
+    <td>
+      An array of started foreman ids.
+    </td>
+    <td>
+      The foreman with the name XX is started.  If XX is "all", all stopped foremen
+      will be started. 
+
+      XX will be "test" if the foreman name is TestForman.
+      Otherwise, if XX is an integer, the ID of the active foreman will be consulted
+      instead of the name.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      stop XX 
+    </td>
+    <td>
+      "ok" if successful.
+    </td>
+    <td>
+      An array of stopped foreman ids.
+    </td>
+    <td>
+      The foreman with the name XX is stopped.  If XX is "all", all active foremen
+      will be stopped. 
+
+      XX will be "test" if the foreman name is TestForman.
+      Otherwise, if XX is an integer, the ID of the active foreman will be consulted
+      instead of the name.
+    </td>
+  </tr>
+  <tr>
+    <td>
+    (Anything else)
+    </td>
+    <td>
+      unknown command
+    </td>
+    <td>
+      None.
+    </td>
+    <td>Nothing.</td>
+  </tr>
+</table>
+
+
+
+Custom Foremen
+-------------------
+Foremen that you build must inherit from HelloGoodbye::Foreman.  Beyond that, you should only have to implement a few instance methods that will be executed when the corresponding console commands are executed during a TCP connection:
+
+    def start
+      # Start listening for events to respond to.
+    end
+
+    def stop
+      # Stop listening for events.
+    end
+
+
+Foremen Console
+-------------------
+Once started, your foreman will be available for TCP connections, and will respond to the following commands:
+<table>
+  <tr>
+    <th>Command</th><th>Response Message</th><th>Results</th><th>Action Performed</th>
+  </tr>
+  <tr>
+    <td>
+      hello
+    </td>
+    <td>
+      hello
+    </td>
+    <td>
+      None.
+    </td>
+    <td>
+      Nothing.  Just a convenient way to "ping" the service.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      goodbye
+    </td>
+    <td>
+      goodbye
+    </td>
+    <td>
+      None.
+    </td>
+    <td>
+      Closes the connection.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      start
+    </td>
+    <td>
+      ok
+    </td>
+    <td>
+      Nothing. 
+    </td>
+    <td>
+      Executes the foreman's static "start" method.  Typically, this would execute whatever "daemon" will listen for events and spawn workers.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      stop
+    </td>
+    <td>
+      ok
+    </td>
+    <td>
+      Nada 
+    </td>
+    <td>
+      Executes the forman's "stop" method, stopping the foreman's daemon.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      status 
+    </td>
+    <td>
+      "running" or "stopped" 
+    </td>
+    <td>
+      Nada 
+    </td>
+    <td>
+      Nothing.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      (Anything else not implemented by your custom foreman)
+    </td>
+    <td>
+      unknown command
+    </td>
+    <td>
+      None.
+    </td>
+    <td>
+      Nothing.
+    </td>
+  </tr>
+</table>
+
+Custom Consoles
+------------------
+Although there is a generic 
+```
+HelloGoodbye::ForemanConsole
+``` 
+that will hopefully suit the needs for most usecases, custom consoles can easily be created and attached to custom foremen as needed.
+
+First, to implement your custom console, inherit from 
+```
+HelloGoodbye::ForemanConsole
+```
+and override 
+```
+receive_command
+```
+.
+
+To make your own class extensible, and to make use of the built in console commands implemented in the
+```
+HelloGoodbye::ForemanConsole
+```
+class, you'll want to start with the template below when overriding this method:
+
+  def receive_command(command)
+    # Process additional commands here.
+    # Return if processes successfully
+    super   # Process the default commands.  If no match, a failure response will be returned. 
+  end
+
+The last little catch is this: you must let your custom forman class know which console to use.  To do this, in your Foreman class, assuming your console class is HelloGoodbye::TestConsole (yes, your console **must** be in the HelloGoodbye module ):
+
+    set_console_type :test   # i.e. ":test" for TestConsole
+
+Thus, the rules are as follow:
+
+* Your console's class name must be prefixed with "Console".
+* When setting this type with the class method, you must pass in a symbol matching the de-classified class name, minus the "Console" prefix.
+

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec) do |t| 
+    t.rspec_opts = ["-c", "-f progress","-r ./spec/spec_helper.rb"]
+      t.pattern = './spec/**/*_spec.rb'
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/hello_goodbye.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/hello_goodbye/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Joshua Murray"]
+  gem.email         = ["joshua.murray@gmail.com"]
+  gem.description   = %q{A daemon manager with a TCP interface built on top of EventMachine.}
+  gem.summary       = %q{A daemon manager with a TCP interface built on top of EventMachine.}
+  gem.homepage      = "https://github.com/joshcom/hello_goodbye"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "hello_goodbye"
+  gem.require_paths = ["lib"]
+  gem.version       = HelloGoodbye::VERSION
+
+  gem.add_dependency "eventmachine", "0.12.10"
+  gem.add_dependency "json", "1.5.3"
+  gem.add_development_dependency "bundler"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "shoulda", ">= 0"
+  gem.add_development_dependency "rspec", "2.6.0"
+end

data/hello_goodbye.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'eventmachine'
+require 'json'
+
+require File.expand_path('../hello_goodbye/foremen_manager',__FILE__)
+
+module HelloGoodbye
+
+  # Resets the current foremen manager, so that the next time
+  # self.manager is called, a new ForemenManager instance will be
+  # created.
+  def self.reset!
+    @manager = nil
+  end
+
+  # Create a new manager or use the existing manager.  If an existing manager exists,
+  # port and server will be ignored.
+  # Parameters:
+  # * port:   The port the manager should connect to.
+  # * server: The server the service will run from.
+  def self.manager(port=ForemenManager.default_manager_port,server=Foreman.default_server)
+    @manager ||= ForemenManager.new(:port => port, :server => server)
+  end
+
+end

data/lib/hello_goodbye/console.rb

@@ -0,0 +1,88 @@
+module HelloGoodbye
+
+  # Commands shared by all consoles:
+  # * 'hello'   => Used to ping the server.  
+  #                Responds with 'hello'.
+  # * 'goodbye' => Used to close a connection.  
+  #                Responds with 'goodbye'.
+  class Console < EventMachine::Connection
+
+    require File.expand_path('../../hello_goodbye/consoles/foreman_console',__FILE__)
+    require File.expand_path('../../hello_goodbye/consoles/manager_console',__FILE__)
+    require File.expand_path('../../hello_goodbye/json/request',__FILE__)
+    require File.expand_path('../../hello_goodbye/json/response',__FILE__)
+
+    # :foreman
+    #   A reference to the Foreman object that instantiated the console, so that
+    #   the console can serve as an interface to this object.
+    attr_accessor :foreman
+
+    # Returns a standard console of a given type.  I'm aware this logic is dumb.
+    # Parameters:
+    # * type
+    # ** :manager => ManagerConsole
+    def self.get(type)
+      case type
+      when :manager
+        ManagerConsole
+      when :foreman
+        ForemanConsole
+      else
+        if (obj = HelloGoodbye.const_get("#{type}_console".split('_').collect(&:capitalize).join))
+            obj
+        else
+          raise ArgumentError, "What type of console is #{type}?"
+        end
+      end
+    end
+
+    def foreman=(f)
+      f.console = self
+      @foreman = f
+    end
+
+    # Returns:
+    #   true if data was handled, false if not.
+    def receive_command(command)
+      case command 
+      when "hello"
+        send_response :success => true,
+          :message => "hello"
+        return true
+      when "goodbye"
+        send_response :success => true,
+          :message => "goodbye"
+        close_connection
+        return true
+      else
+        send_response :success => false,
+          :message => "unknown command"
+      end
+      false
+    end
+
+    # Parameters:
+    #   hash
+    #   * success => true or false
+    #   * message => "Your message"
+    #   * results => []
+    def send_response(hash)
+      send_data Response.new(hash).to_json
+    end
+
+    def receive_data(data)
+      data = data.strip
+      return false if data == ""
+
+      begin
+        json = Request.new(data)
+      rescue JSON::ParserError => e
+        send_response :success => false,
+          :message => "invalid json"
+        return false
+      end
+
+      receive_command(json.command)
+    end
+  end
+end

data/lib/hello_goodbye/consoles/foreman_console.rb

@@ -0,0 +1,23 @@
+module HelloGoodbye
+  class ForemanConsole < Console
+    def receive_command(command)
+      case command
+      when "start"
+        self.foreman.employ
+        send_response :success => true,
+          :message => "ok"
+        return true
+      when "stop"
+        self.foreman.unemploy
+        send_response :success => true,
+          :message => "ok"
+        return true
+      when "status"
+        send_response :success => true,
+          :message => self.foreman.status.to_s
+        return true
+      end
+      super
+    end
+  end
+end

data/lib/hello_goodbye/consoles/manager_console.rb

@@ -0,0 +1,35 @@
+module HelloGoodbye
+  class ManagerConsole < Console
+    def receive_command(command)
+      case command
+      when /^start /
+        id = command.gsub(/^start /, "")
+        if (started_foremen = self.foreman.trigger_foreman(:start, id))
+          send_response :success => true,
+            :message => "ok", 
+            :results => started_foremen
+        else
+          send_response :success => false,
+            :message => "no match for foreman '#{id}'"
+        end
+        return true
+      when /^stop /
+        id = command.gsub(/^stop /, "")
+        if (stopped_foremen = self.foreman.trigger_foreman(:stop,id))
+          send_response :success => true,
+            :message => "ok", 
+            :results => stopped_foremen
+        else
+          send_response :success => false,
+            :message => "no match for foreman '#{id}'"
+        end
+        return true
+      when "foremen"
+        send_response :success => true, :message => "ok", 
+          :results => self.foreman.report
+        return true
+      end
+      super
+    end
+  end
+end

data/lib/hello_goodbye/foreman.rb

@@ -0,0 +1,117 @@
+module HelloGoodbye
+  class Foreman
+
+    attr_accessor :server, :port, :console, :my_id, :server_id
+    attr_reader :foreman_started
+
+    DEFAULT_SERVER = "127.0.0.1"
+
+    # Overrides the default ForemanConsole console type
+    # to fire up when #start! is called.
+    def self.set_console_type(console_sym)
+      @console_type = console_sym
+    end
+
+    # Returns the current console type for this class.
+    def self.console_type
+      @console_type ||= :foreman
+    end
+
+    def self.default_server
+      DEFAULT_SERVER
+    end
+
+    # Parameters:
+    # options:
+    #  * server => 
+    #  * port   => The port to run the server on
+    def initialize(options={})
+      self.server = options[:server]
+      self.port = options[:port]
+      @foreman_started = false
+    end
+
+    # Starts the foreman's worker spawning action.
+    def start
+      raise ArgumentError, "Foreman.start must be implemented by child class."
+    end
+
+    # Stops the foreman's worker spawning action.
+    def stop
+      raise ArgumentError, "Foreman.start must be implemented by child class."
+    end
+
+    # Starts the console for the foreman.  Subclasses should implement this method,
+    # passing a block to super to start up any tasks (AMQB subscriber, etc)
+    # that may need to be done.
+    def start!
+      raise RuntimeError, "Foreman already started!" if @foreman_started == true
+      start_with_reactor do
+        self.start_console
+        yield if block_given?
+      end
+      @foreman_started = true
+    end
+
+    # Detects the name to report this foreman class as.
+    # For example, will be "test" for "HelloGoodbye::TestForeman".
+    def my_name
+      begin
+        self.class.name.match(/^HelloGoodbye::(.*)Foreman$/)[1].downcase
+      rescue
+        self.class.name
+      end
+    end
+
+    # Reports the current status of the foreman.
+    # Returns:
+    #  * :stopped if the foreman is not currently employing workers.
+    #  * :running if the foreman is active
+    def status
+      @status || :stopped
+    end
+
+    # true if the foreman is currently employing workers
+    def running?
+      self.status == :running
+    end
+
+    # Sets the foreman status to either :running or :stopped
+    def status=(status)
+      @status = status.to_sym
+    end
+
+    # Sets the foreman status to :running and calls self.start
+    def employ
+      self.start
+      self.status = :running
+    end
+
+    # Sets the foreman status to :stopped and calls self.stop
+    def unemploy
+      self.stop
+      self.status = :stopped
+    end
+
+    def server 
+      @server || DEFAULT_SERVER
+    end
+
+    def start_console
+      me = self
+      self.server_id = EM::start_server(self.server, self.port, Console.get(self.class.console_type)) do |c|
+        c.foreman = me 
+      end
+    end
+
+    def start_with_reactor(&block)
+      if EM.reactor_running?
+        block.call
+      else
+        EM.run {
+          block.call
+        }
+      end
+    end
+  end
+end