kennethkalmer-daemon-kit 0.1.0

data/History.txt

@@ -0,0 +1,7 @@
+== 0.1.0 2009-01-08
+
+* Ability to freeze the gem/edge copies of DaemonKit
+* Simple non-evented Jabber generator
+* Flexible UNIX signal trapping configuration
+* Basic generator completed
+* 1 small step for man, 1 giant leap for mankind

data/Manifest.txt

@@ -0,0 +1,58 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.textile
+Rakefile
+TODO.txt
+app_generators/daemon_kit/USAGE
+app_generators/daemon_kit/daemon_kit_generator.rb
+app_generators/daemon_kit/templates/README
+app_generators/daemon_kit/templates/Rakefile
+app_generators/daemon_kit/templates/bin/daemon.erb
+app_generators/daemon_kit/templates/config/boot.rb
+app_generators/daemon_kit/templates/config/environment.rb
+app_generators/daemon_kit/templates/config/environments/development.rb
+app_generators/daemon_kit/templates/config/environments/production.rb
+app_generators/daemon_kit/templates/config/environments/test.rb
+app_generators/daemon_kit/templates/config/initializers/readme
+app_generators/daemon_kit/templates/libexec/daemon.erb
+bin/daemon_kit
+config/website.yml.sample
+daemon_generators/jabber/USAGE
+daemon_generators/jabber/jabber_generator.rb
+daemon_generators/jabber/templates/config/initializers/jabber.rb
+daemon_generators/jabber/templates/config/jabber.yml
+daemon_generators/jabber/templates/libexec/daemon.rb
+features/development.feature
+features/steps/common.rb
+features/steps/env.rb
+lib/daemon_kit.rb
+lib/daemon_kit/application.rb
+lib/daemon_kit/initializer.rb
+lib/daemon_kit/jabber.rb
+lib/daemon_kit/patches/force_kill_wait.rb
+lib/daemon_kit/tasks.rb
+lib/daemon_kit/tasks/framework.rake
+rubygems_generators/install_rspec/USAGE
+rubygems_generators/install_rspec/install_rspec_generator.rb
+rubygems_generators/install_rspec/templates/spec.rb
+rubygems_generators/install_rspec/templates/spec/spec.opts
+rubygems_generators/install_rspec/templates/spec/spec_helper.rb
+rubygems_generators/install_rspec/templates/tasks/rspec.rake
+script/console
+script/destroy
+script/generate
+script/txt2html
+spec/daemon_kit_spec.rb
+spec/initializer_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake
+test/test_daemon-kit_generator.rb
+test/test_generator_helper.rb
+test/test_jabber_generator.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

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

data/README.textile

@@ -0,0 +1,77 @@
+h1. Daemon Kit
+
+* http://daemon-kit.rubyforge.org/ (coming soon)
+
+h2. 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:
+
+* Evented and non-evented Jabber Bot (coming next)
+* Evented and non-evented loops (coming soon)
+* Queue poller (SQS, AMQP, etc) (coming soon)
+
+h2. Features/Problems
+
+* Build it
+* Review TODO.txt
+
+h2. Synopsis
+
+  $ 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.
+
+h2. Generators
+
+Currently only two generators exist, a 'default' generator and a 'jabber' generator.
+
+The default generator creates a simple daemon with an infinite loop inside that you can adapt.
+
+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.
+
+h2. Requirements
+
+* Ruby 1.8.6
+* daemons 1.0.10
+* xmpp4r-simple 0.8.8 (if using the 'jabber' generator)
+* eventmachine 0.12.2 (if using any of the evented generators)
+* rspec 1.1.11 (for writing/running your specs)
+
+h2. Install
+
+  $ git clone git://github.com/kennethkalmer/daemon-kit.git
+  $ rake gem
+  $ gem install pkg/daemon-kit-X.X.X.gem
+
+h2. 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,30 @@
+
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/daemon_kit'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('daemon-kit', DaemonKit::VERSION) 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       = p.name # TODO this is default value
+  p.extra_deps         = [
+     ['daemons','>= 1.0.10'],
+  ]
+  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/TODO.txt

@@ -0,0 +1,24 @@
+DaemonKit TODO List
+===================
+
+This is purely a drop in the bucket of what has to come...
+
+* [DONE] Easy way to trap signals 
+* Error handling to the degree Rails does
+* Easy configuration of an ORM of choice, including patching it if needed (ActiveRecourd *cough*)
+* Improved generators for creating skeleton daemons:
+  * [DONE] Jabber bot
+  * Evented jabber bot
+  * Empty periodic event loop
+  * Empty periodic loop (non-evented)
+  * Queue (SQS, AMQP, etc) pollers
+* Rake tasks for generating:
+  * god configs
+* Pre-built capistrano configs for easy deployment
+* Support for dropping privileges
+* Support for chroot'ing
+* Improved and cleaned up logging
+* Plenty of docs, seriously a lot of docs
+* Specs & features, tons of them too
+* Some level of thread safety, or mechanisms to ease thread safety
+* 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,121 @@
+class DaemonKitGenerator < RubiGen::Base
+
+  DEFAULT_SHEBANG = File.join(Config::CONFIG['bindir'],
+                              Config::CONFIG['ruby_install_name'])
+
+  VALID_GENERATORS = ['default', 'jabber']
+  
+  default_options :shebang => DEFAULT_SHEBANG,
+  :author => nil
+
+  attr_reader :daemon_name
+  attr_reader :installer
+
+  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
+          
+    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}.rb"
+      else
+        m.dependency installer, [daemon_name], :destination => destination_root, :collision => :force
+      end
+
+      # Config/Environment
+      m.directory "config"
+      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/initializers"
+      m.file      "config/initializers/readme", "config/initializers/readme"
+
+      # Libraries
+      m.directory "lib"
+      
+      # Tests
+      m.directory "tasks"
+      m.dependency "install_rspec", [daemon_name], :destination => destination_root, :collision => :force
+
+      # Others
+      m.directory "log"
+      m.directory "tmp"
+      m.directory "vendor"
+
+      m.dependency "install_rubigen_scripts", [destination_root, 'daemon_kit'],
+        :shebang => options[:shebang], :collision => :force
+    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("-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'
+    end
+
+end

data/app_generators/daemon_kit/templates/README

@@ -0,0 +1,48 @@
+DaemonKit README
+================
+
+DaemonKit has generated a skeleton Ruby daemon for you to build on. Please read
+through this file to ensure you get going quickly.
+
+Directories
+===========
+
+bin/
+  <%= daemon_name %> - Stub executable to control your daemon with
+
+config/
+  Environment configuration files
+
+lib/
+  Place for your libraries
+
+libexec/
+  <%= daemon_name %>.rb - Your daemon code
+
+log/
+  Log files based on the environment name
+
+spec/
+  rspec's home
+
+tasks/
+  Place for rake tasks
+
+vendor/
+  Place for unpacked gems and DaemonKit
+
+tmp/
+  Scratch folder
+
+
+Logging
+=======
+
+One of the biggest issues with writing daemons are gettign insight into what your
+daemons are doing. Logging with DaemonKit is simplified as DaemonKit creates log
+files per environment in log.
+
+On all environments except production the log level is set to DEBUG, but you can
+toggle the log level by sending the running daemon SIGUSR1 and SIGUSR2 signals.
+SIGUSR1 will toggle between DEBUG and INFO levels, SIGUSR2 will blatantly set the
+level to DEBUG.

data/app_generators/daemon_kit/templates/Rakefile

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'daemon_kit/tasks'
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/*.rake')].each { |rake| load rake }

data/app_generators/daemon_kit/templates/bin/daemon.erb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+#
+# Stub executable for <%= daemon_name %>
+
+require File.dirname(__FILE__) + '/../config/environment'
+
+DaemonKit::Application.run( DAEMON_ROOT + '/libexec/<%= daemon_name %>.rb' )

data/app_generators/daemon_kit/templates/config/boot.rb

@@ -0,0 +1,52 @@
+# Don't change this file!
+# Configure your daemon in config/environment.rb
+
+DAEMON_ROOT = "#{File.dirname(__FILE__)}/.." unless defined?( DAEMON_ROOT )
+
+module DaemonKit
+  class << self
+    def boot!
+      unless booted?
+        pick_boot.run
+      end
+    end
+
+    def booted?
+      defined? DaemonKit::Initializer
+    end
+
+    def pick_boot
+      (vendor_kit? ? VendorBoot : GemBoot).new
+    end
+
+    def vendor_kit?
+      File.exists?( "#{DAEMON_ROOT}/vendor/daemon_kit" )
+    end
+  end
+
+  class Boot
+    def run
+      load_initializer
+      DaemonKit::Initializer.run
+    end
+  end
+
+  class VendorBoot < Boot
+    def load_initializer
+      require "#{DAEMON_ROOT}/vendor/daemon_kit/lib/daemon_kit/initializer"
+    end
+  end
+  
+  class GemBoot < Boot
+    def load_initializer
+      require 'rubygems'
+      gem 'daemon-kit'
+      require 'daemon_kit/initializer'
+    rescue Gem::LoadError => e
+      $stderr.puts %(Missing the daemon-kit gem. Please 'gem install daemon_kit')
+      exit 1
+    end
+  end
+end
+
+DaemonKit.boot!

data/app_generators/daemon_kit/templates/config/environment.rb

@@ -0,0 +1,19 @@
+# Be sure to restart your daemon when you modify this file
+
+# Uncomment below to force your daemon into production mode
+#ENV['DAEMON_ENV'] ||= 'production'
+
+# Boot up
+require File.join(File.dirname(__FILE__), 'boot')
+
+DaemonKit::Initializer.run do |config|
+
+  # The name of the daemon as reported by process monitoring tools
+  config.daemon_name = '<%= daemon_name %>'
+
+  # Uncomment to allow multiple instances to run
+  # config.mulitple = true
+
+  # Force the daemon to be killed after X seconds from asking it to
+  # config.force_kill_wait = 30
+end

data/app_generators/daemon_kit/templates/config/initializers/readme

@@ -0,0 +1,11 @@
+# You can place files in here to be loaded before the code is daemonized.
+#
+# DaemonKit looks for a file named '<config.daemon_name>.rb' and loads
+# that file with as if inside a DaemonKit::Initializer block.
+# 
+# These files are mostly useful for operations that should fail blatantly
+# before daemonizing, like loading gems.
+#
+# Be careful not to open any form of IO in here and expecting it to be
+# open inside the running daemon since all IO instances are closed when
+# daemonizing (including STDIN, STDOUT & STDERR).

data/app_generators/daemon_kit/templates/libexec/daemon.erb

@@ -0,0 +1,18 @@
+# Change this file to be a wrapper around your daemon code.
+
+# Do your post daemonization configuration here
+# At minimum you need just the first line (without the block), or a lot
+# of strange things might start happening...
+DaemonKit::Application.running! do |config|
+  # Trap signals with blocks or procs
+  # config.trap( 'INT' ) do
+  #   # do something clever
+  # end
+  # config.trap( 'TERM', Proc.new { puts 'Going down' } )
+end
+
+# Sample loop to show process
+loop do
+  DaemonKit.logger.info "I'm running"
+  sleep 60
+end

data/bin/daemon_kit

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rubigen'
+
+if %w(-v --version).include? ARGV.first
+  require 'daemon_kit'
+  puts "#{File.basename($0)} #{DaemonKit::VERSION}"
+  exit(0)
+end
+
+require 'rubigen/scripts/generate'
+RubiGen::Base.use_application_sources! :rubygems
+RubiGen::Base.prepend_sources(*[
+  RubiGen::PathSource.new(:app, File.join(File.dirname(__FILE__), "..", "app_generators")),
+  RubiGen::PathSource.new(:app, File.join(File.dirname(__FILE__), "..", "daemon_generators")),
+  RubiGen::PathSource.new(:app, File.join(File.dirname(__FILE__), "..", "rubygems_generators"))
+])
+RubiGen::Scripts::Generate.new.run(ARGV, :generator => 'daemon_kit')

data/daemon_generators/jabber/USAGE

@@ -0,0 +1,5 @@
+Description:
+  
+  
+Usage:
+  

data/daemon_generators/jabber/jabber_generator.rb

@@ -0,0 +1,65 @@
+class JabberGenerator < RubiGen::Base
+
+  default_options :author => nil
+
+  attr_reader :name
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+    usage if args.empty?
+    @name = args.shift
+    extract_options
+  end
+
+  def manifest
+    record do |m|
+      # Ensure appropriate folder(s) exists
+      m.directory ''
+
+      # Create stubs
+      # m.template           "template.rb.erb", "some_file_after_erb.rb"
+      # m.template_copy_each ["template.rb", "template2.rb"]
+      # m.template_copy_each ["template.rb", "template2.rb"], "some/path"
+      # m.file           "file", "some_file_copied"
+      # m.file_copy_each ["path/to/file", "path/to/file2"]
+      # m.file_copy_each ["path/to/file", "path/to/file2"], "some/path"
+      
+      # Copy over our configs
+      m.directory 'config'
+      m.template  'config/jabber.yml', 'config/jabber.yml'
+      m.directory 'config/initializers'
+      m.template  'config/initializers/jabber.rb', "config/initializers/#{name}.rb"
+
+      # Copy over our daemon
+      m.directory 'libexec'
+      m.template 'libexec/daemon.rb', "libexec/#{name}.rb"
+    end
+  end
+
+  protected
+    def banner
+      <<-EOS
+Creates a ...
+
+USAGE: #{$0} #{spec.name} name
+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("-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]
+    end
+end

data/daemon_generators/jabber/templates/config/initializers/jabber.rb

@@ -0,0 +1,8 @@
+begin
+  require 'xmpp4r-simple'
+rescue LoadError => e
+  $stderr.puts "Missing xmpp4-simple gem. Please run 'gem install xmpp4r-simple'."
+  exit 1
+end
+
+require 'daemon_kit/jabber'

data/daemon_generators/jabber/templates/config/jabber.yml

@@ -0,0 +1,26 @@
+# Jabber configuration file
+
+# The configuration specifies the following keys:
+# * jabber_id  - Identidy (username) of the user
+# * password   - Password used to authenticate
+# * resource   - Multiple connections can be made with the same credentials and different resources
+# * masters    - Array of Jabber ID's whose messages will be processed
+# * supporters - Additional 'buddies' to keep on roster, but messages won't be processed
+
+defaults: &defaults
+  jabber_id: <%= name %>@gmail.com
+  password: secret
+  resource: daemon_kit
+  masters: 
+    - you@gmail.com
+  supporters:
+    - someone@gmail.com
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults
+
+production:
+  <<: *defaults

data/daemon_generators/jabber/templates/libexec/daemon.rb

@@ -0,0 +1,27 @@
+# Generated jabber daemon
+
+# Do your post daemonization configuration here
+# At minimum you need just the first line (without the block), or a lot
+# of strange things might start happening...
+DaemonKit::Application.running! do |config|
+  # Trap signals with blocks or procs
+  # config.trap( 'INT' ) do
+  #   # do something clever
+  # end
+  # config.trap( 'TERM', Proc.new { puts 'Going down' } )
+end
+
+# IMPORTANT CONFIGURATION NOTE
+#
+# Please review and update 'config/jabber.yml' accordingly or this
+# daemon won't work as advertised.
+
+# This block gets called every time a message has been received from a
+# valid master.
+DaemonKit::Jabber.received_messages do |message|
+  # Simple echo service
+  DaemonKit::Jabber.deliver( message.from, message.body )
+end
+
+# Run our Jabber bot
+DaemonKit::Jabber.run