queso-daemon-kit 0.1.7.10

data/PostInstall.txt

@@ -0,0 +1,6 @@
+
+For more information on daemon-kit, see http://kit.rubyforge.org/daemon-kit
+
+To get started quickly run 'daemon_kit' without any arguments
+
+

data/README.rdoc

@@ -0,0 +1,130 @@
+= Daemon Kit
+
+* http://kit.rubyforge.org/daemon-kit/rdoc/
+* http://kit.rubyforge.org/daemon-kit (coming soon)
+* http://groups.google.com/group/daemon-kit (daemon-kit@googlegroups.com)
+* #daemon-kit on Freenode
+
+== Description
+
+Daemon Kit aims to simplify creating Ruby daemons by providing a sound application skeleton (through a generator), task specific generators (jabber bot, etc) and robust environment management code.
+
+Using simple built-in generators it is easy to created evented and non-evented daemons that perform a multitude of different tasks.
+
+Supported generators:
+
+* XMPP bot (non-evented)
+* AMQP consumer (evented)
+* Nanite agent
+* Cron-style daemon
+* ruote remote participants
+
+== Features/Problems
+
+* Build it
+* Review TODO.txt
+
+== Synopsis
+
+  $ daemon_kit -h
+
+Get some help
+
+  $ daemon_kit [/path/to/your/daemon] [options]
+
+The above command generates a skeleton daemon environment for you to adapt.
+
+  $ daemon_kit [/path/to/your/daemon] -i jabber
+
+Use the 'jabber' generator instead of the default one.
+
+== Generators
+
+Currently six generators exist: default, jabber, amqp, cron, nanite & ruote
+
+The default generator creates a simple daemon with an infinite loop inside that you can adapt.
+
+=== Jabber Generator
+
+The jabber generator creates a simple daemon that leverages the "xmpp4r-simple":http://xmpp4r-simple.rubyforge.org/ gem to process inbound messages. The daemon will manage the roster and other little tasks, leaving you to provide the hooks for processing messages, presence notifications and subscription request.
+
+=== Cron Generator
+
+The cron generator creates a simple daemon that leverages the "rufus-scheduler":http://github.com/jmettraux/rufus-scheduler gem to create a simple cron-lie daemon. Please be aware that this daemon could never be a replacement for the battle-tested "cron utility":http://www.gentoo.org/doc/en/cron-guide.xml shipped standard with most *nix distributions.
+
+=== AMQP Consumer Generator
+
+The AMQP generator creates a simple daemon that has all the stub code and configuration in place to help you write AMQP consumers quickly and effectively. The generated daemon relies on the presence of the "amqp":http://github.com/tmm1/amqp gem.
+
+=== Nanite Agent Generator
+
+The "nanite":http://github.com/ezmobius/nanite agent generator gets you up and running with nanite agents very quickly.
+
+=== ruote Remote Participants
+
+The "ruote":http://openwfe.rubyforge.org remote participant generator speeds up the development of workflow participants that run outside of the Ruby process that houses the engine. Daemon-kit handles all the communication and delegation logic, allowing you to focus purely on your participant's activities.
+
+== Requirements
+
+* Ruby 1.8.6
+* eventmachine-0.12.8[http://rubyeventmachine.com]
+* rspec (for writing/running your specs)
+
+== Generator Requirements
+
+Depending on the generator you choose for your daemon, it might require additional gems to run.
+
+* jabber - xmpp4r-simple[http://xmpp4r-simple.rubyforge.org]
+* cron - rufus-scheduler[http://github.com/jmettraux/rufus-scheduler] (at least version 2.0.0)
+* amqp - amqp[http://github.com/tmm1/amqp]
+* nanite - nanite[http://github.com/ezmobius/nanite]
+* ruote - none, although ruote[http://openwfe.rubyforge.org] should probably be running somewhere
+
+== Install
+
+Currently recommended to stick to the git repo:
+
+  $ git clone git://github.com/kennethkalmer/daemon-kit.git
+  $ rake gem
+  $ gem install pkg/daemon-kit-X.X.X.gem
+
+Development versions are available as gems from github:
+
+  $ gem install kennethkalmer-daemon-kit -s http://gems.github.com
+
+Stable versions, when released are available directly from Rubyforge:
+
+  $ gem install daemon-kit
+
+== Further reading
+
+* Configuration.txt
+* Deployment.txt
+* Logging.txt
+* RuoteParticipants.txt
+* http://www.opensourcery.co.za/tag/daemon-kit/
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009 Kenneth Kalmer (Internet Exchange CC, Clear Planet Information Solutions Pty Ltd)
+
+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/Rakefile

@@ -0,0 +1,37 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require File.dirname(__FILE__) + '/lib/daemon_kit'
+
+Hoe.plugin :newgem
+Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec('daemon-kit') do |p|
+  p.summary = 'Daemon Kit aims to simplify creating Ruby daemons by providing a sound application skeleton (through a generator), task specific generators (jabber bot, etc) and robust environment management code.'
+  p.developer('Kenneth Kalmer', 'kenneth.kalmer@gmail.com')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = IO.read( 'PostInstall.txt' ) # TODO remove if post-install message not required
+  p.rubyforge_name       = 'kit' # TODO this is default value
+  p.extra_deps = [
+                  ['rubigen', '>= 1.5.2'],
+                  ['eventmachine', '>=0.12.8']
+                 ]
+  p.extra_dev_deps = [
+                      ['newgem', ">= #{::Newgem::VERSION}"]
+                     ]
+
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+task :default => [:spec] #, :features]

data/RuoteParticipants.txt

@@ -0,0 +1,113 @@
+= Writing remote ruote participants with daemon-kit
+
+daemon-kit is an ideal housing for remote ruote participants, providing a lot
+of convenience in terms of receiving and sending workitems, delegating work to
+pseudo-participant classes, handling configuration of the communication channel
+between ruote and the remote participant, and much more.
+
+== What is ruote?
+
+Ruote is a Ruby workflow engine. It is a powerful tool for defining, running and
+orchestrating business processes.
+
+* http://openwferu.rubyforge.org/
+* http://www.opensourcery.co.za/2009/03/04/ruote-in-20-minutes/
+* http://www.opensourcery.co.za/2009/07/06/driving-business-processes-in-ruby/
+
+== What are remote participants?
+
+Remote participants are participants that perform their work in a different
+Ruby processes from the one running the engine. This is useful in two cases,
+possibily many more, that involves autonomous participants.
+
+* Autonomous participants located on remote servers, driven by identity
+* Clustering autonomous participants to process workitems from a queue
+
+To learn more about the differences between local and remote participants
+please see http://openwferu.rubyforge.org/part.html
+
+Currently on the AMQP components are in place in daemon-kit, with XMPP coming
+soon.
+
+== Creating a remote participant with daemon-kit
+
+Generate your daemon using the 'ruote' generator:
+
+  $ daemon_kit partd -i ruote
+
+Make sure you have the JSON gem install, and the AMQP gem as well.
+
+== Configuring the daemon
+
+You need to review +config/ruote.yml+ to specify the AMQP queues that the daemon
+will subscribe to for receiving workitems. You'll also need to configure the 
+AMQP gem be updating +config/amqp.yml+
+
+The generated daemon in +libexec/+ already defaults to using AMQP as a transport
+for workitems.
+
+== Writing pseudo-participants
+
+Pseudo-participants in daemon-kit are pure Ruby classes. Implement your classes
+in +lib/+ and require them from +lib/<daemon_name>.rb+.
+
+Register your classes as pseudo-participants by registering them in the daemon
+file in +libexec+, just as the Sample class is registered in the generated
+code. Your class will be instantiated upon registration, and will be re-used
+for every incoming workitem passed to it.
+
+All your public methods in the pseudo-participant classes should be accept
+a single parameter, which is a ruote workitem in pure Hash form.
+
+== Wiring up the remote participant in ruote
+
+See the complete code here: http://gist.github.com/144861
+
+A sample process definition might look something like this:
+
+  class QuoteProcess < OpenWFE::ProcessDefinition
+    sequence do
+      kit :command => '/sample/quote', :queue => 'work1'
+
+      console
+    end
+  end
+
++kit+ in the above process definition is registered with the ruote engine as an
+AMQPParticipant. The AMQPParticipant delivers workitems to the specified AMQP
+queue.
+
+Based on the values in +config/ruote.yml+, your daemon will be subscribed to
+those queues.
+
+The second part is delegating the workitem inside the daemon to the correct
+pseudo-participant. This is handled by the +:command+ parameter in the process
+definition. DaemonKit::Workitem looks at the command parameter of the incoming
+workitem, and then finds a registered pseudo-participant instance and calls the
+requested method on that class.
+
+The +:command+ parameter follows the following convention (stolen shamelessly
+from Nanite):
+
+  :command => '/class_name/method_name'
+
+When classes are registered, the name of the class is downcased and camel-case
+words are separated by underscores. Method names are not changed, but methods
+are required to be public.
+
+== Processing workitems and replying to the engine
+
+The methods called in the pseudo-participants receive a single parameter, a
+ruote workitem as a hash. The participant is then free to analyze the hash
+and perform the appropriate actions required. The return value of the method
+is discarded, and the workitem is returned back to the engine. If the method
+modified the workitem, these changes will be sent along as well.
+
+== Random other notes
+
+Apart from configuring the AMPQ client (or XMPP in future) and the ruote.yml
+file, daemon developers don't need to worry about anything related to receiving
+workitems or sending replies.
+
+Our aim is to allow you to swap between participants on both sides of the
+transport without changing any of your code.

data/TODO.txt

@@ -0,0 +1,37 @@
+= DaemonKit TODO List
+
+This is purely a drop in the bucket of what has to come...
+
+== Eye on 0.2
+
+* Support for dropping privileges
+* Support for chroot'ing
+* Altering process names (fully and temporary appending)
+* bleak_house support
+* Support for tweaking REE environment variables prior to launch (bash wrapper)
+* Clustering support (run multiple workers out of same project)
+* Full 1.9 support in the framework
+
+== Later
+
+* [IN PROGRESS] Error handling to the degree Rails does
+* Easy configuration of an ORM of choice, including patching it if needed (ActiveRecord *cough*)
+* Improved generators for creating skeleton daemons:
+  * Evented jabber bot
+  * Empty periodic event loop
+  * Empty periodic loop (non-evented)
+  * Queue (SQS, AMQP, etc) pollers
+* Rake tasks for generating:
+  * Sys-V style init scripts
+* Plenty of docs, seriously a lot of docs
+* Specs & features, tons of them too
+* Integration tests for the specific daemons
+* Some level of thread safety, or mechanisms to ease thread safety
+* Built in utilities:
+  * Thread pool for 1.8
+  * Fibre pool for 1.9
+  * Some activesupport-esque functions until activesupport 3.0 hits the streets
+* DRY up the following:
+  * Loading configuration files for the daemons
+
+* DON'T FORGET 1.9 SUPPORT

data/app_generators/daemon_kit/USAGE

@@ -0,0 +1,7 @@
+Description:
+  This generator creates a new skeleton project suitable for easy
+  Ruby daemon development. The generated project is preconfigured
+  and just requires your task specific code.
+
+  Use one of the provided generators to stub out even more 
+  functionality for common daemon patterns.

data/app_generators/daemon_kit/daemon_kit_generator.rb

@@ -0,0 +1,161 @@
+class DaemonKitGenerator < RubiGen::Base
+
+  DEFAULT_SHEBANG = File.join(Config::CONFIG['bindir'],
+                              Config::CONFIG['ruby_install_name'])
+
+  VALID_GENERATORS = ['default', 'jabber', 'cron', 'amqp', 'nanite_agent', 'ruote']
+
+  DEPLOYERS = ['none', 'capistrano']
+
+  default_options :shebang => DEFAULT_SHEBANG, :author => nil
+
+  attr_reader :daemon_name
+  attr_reader :installer
+  attr_reader :deployer
+  attr_reader :cucumber
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+    usage if args.empty?
+    @destination_root = File.expand_path(args.shift)
+    @daemon_name = base_name
+    extract_options
+  end
+
+  def manifest
+    # ensure some sanity
+    unless VALID_GENERATORS.include?( installer )
+      $stderr.puts "Invalid generator: '#{installer}'."
+      $stderr.puts "Valid generators are: #{VALID_GENERATORS.join(', ')}"
+      exit 1
+    end
+
+    unless DEPLOYERS.include?( deployer )
+      $stderr.puts "Invalid deployment mechanism: '#{deployer}'."
+      $stderr.puts "Valid deployers are: #{DEPLOYERS.join(', ')}"
+      exit 1
+    end
+
+    script_options = { :chmod => 0755, :shebang => options[:shebang] == DEFAULT_SHEBANG ? nil : options[:shebang] }
+
+    record do |m|
+      # Ensure appropriate folder(s) exists
+      m.directory ''
+
+      # Create stubs
+      # m.template "template.rb",  "some_file_after_erb.rb"
+      # m.template_copy_each ["template.rb", "template2.rb"]
+      # m.file     "file",         "some_file_copied"
+      # m.file_copy_each ["path/to/file", "path/to/file2"]
+
+      # Readme
+      m.template  "README", "README"
+      m.template  "Rakefile", "Rakefile"
+
+      # Executable
+      m.directory "bin"
+      m.template  "bin/daemon.erb", "bin/#{daemon_name}", script_options
+
+      # Generator
+      if installer == "default"
+        m.directory "libexec"
+        m.template  "libexec/daemon.erb", "libexec/#{daemon_name}-daemon.rb"
+      else
+        m.dependency installer, [daemon_name], :destination => destination_root, :collision => :force
+      end
+
+      # Config/Environment
+      m.directory "config"
+      m.file      "config/arguments.rb", "config/arguments.rb"
+      m.file      "config/boot.rb", "config/boot.rb"
+      m.template  "config/environment.rb", "config/environment.rb"
+      m.directory "config/environments"
+      %w{ development test production }.each { |f| m.file "config/environments/#{f}.rb", "config/environments/#{f}.rb" }
+      m.directory "config/pre-daemonize"
+      m.file      "config/pre-daemonize/readme", "config/pre-daemonize/readme"
+      m.directory "config/post-daemonize"
+      m.file      "config/post-daemonize/readme", "config/post-daemonize/readme"
+      m.directory "script"
+      m.file      "script/destroy", "script/destroy", script_options
+      m.file      "script/console", "script/console", script_options
+      m.file      "script/generate", "script/generate", script_options
+
+      # Libraries
+      m.directory "lib"
+      m.file "lib/daemon.rb", "lib/#{daemon_name}.rb", :collision => :skip
+
+      # Tasks
+      m.directory "tasks"
+
+      # Tests
+      m.dependency "rspec", [daemon_name], :destination => destination_root, :collision => :force
+      if cucumber
+        m.dependency "cucumber", [], :destination => destination_root, :collision => :force
+      end
+
+      # Deployers
+      unless deployer == 'none'
+        m.dependency "deploy_#{deployer}", [daemon_name], :destination => destination_root, :collision => :force
+      end
+
+      # Others
+      m.directory "log"
+      m.directory "tmp"
+      m.directory "vendor"
+    end
+  end
+
+  protected
+    def banner
+      <<-EOS
+Creates a preconfigured environment for writing Ruby daemon processes.
+
+USAGE: #{spec.name} /path/to/your/daemon [options]
+EOS
+    end
+
+    def add_options!(opts)
+      opts.separator ''
+      opts.separator 'Options:'
+      # For each option below, place the default
+      # at the top of the file next to "default_options"
+      # opts.on("-a", "--author=\"Your Name\"", String,
+      #         "Some comment about this option",
+      #         "Default: none") { |o| options[:author] = o }
+
+      opts.on("-i", "--install=generator", String,
+              "Select a generator to use (other than the default).",
+              "Available generators: #{VALID_GENERATORS.join(', ')}",
+              "Defaults to: default") do |installer|
+        options[:installer] = installer
+      end
+
+      opts.on("-d", "--deploy-with=config", String,
+              "Select an optional deployment mechanism.",
+              "Available deployers: #{DEPLOYERS.join(', ')}",
+              "Defaults to: none") do |deploy|
+        options[:deployer] = deploy
+      end
+
+      opts.on("--cucumber",
+              "Install cucumber.") do
+        options[:cucumber] = true
+      end
+
+      opts.on("-r", "--ruby=path", String,
+              "Path to the Ruby binary of your choice (otherwise scripts use env, dispatchers current path).",
+              "Default: #{DEFAULT_SHEBANG}") { |x| options[:shebang] = x }
+      opts.on("-v", "--version", "Show the #{File.basename($0)} version number and quit.")
+    end
+
+    def extract_options
+      # for each option, extract it into a local variable (and create an "attr_reader :author" at the top)
+      # Templates can access these value via the attr_reader-generated methods, but not the
+      # raw instance variable value.
+      # @author = options[:author]
+      @installer = options[:installer] || 'default'
+      @deployer  = (options[:deployer] || 'none').strip
+      @cucumber  = options[:cucumber]  || false
+    end
+
+end