fire_and_forget 0.1.2 → 0.2.0

data/lib/fire_and_forget/launcher.rb

@@ -1,17 +1,44 @@
 module FireAndForget
   module Launcher
-    def add_task(task_name, path_to_binary, default_params={}, niceness=0)
-      if default_params.is_a?(Numeric)
-        niceness = default_params
-        default_params = {}
-      end
-      tasks[task_name] = Task.new(task_name, path_to_binary, default_params, niceness)
+    # Registers a task and makes it available for easy launching using #fire
+    #
+    # @param [Symbol] task_name
+    #   the name for the task. This should be unique
+    #
+    # @param [String] path_to_binary
+    #   the path to the executable that should be run when this task is launched
+    #
+    # @param [Fixnum] niceness
+    #   the niceness value of the process >= 0. The higher this value the 'nicer' the launched
+    #   process will be (a high nice value results in a low priority task).
+    #   On UNIX systems the max, nicest, value is 20
+    #
+    # @param [Hash] default_params
+    #   A Hash of parameters that should be passed to every invocation of the task.
+    #   These will be converted to command line parameters
+    #     { "setting" => "value", "output" => "destination"}
+    #   gives the parameters
+    #     --setting=value --output=destination
+    #   @see FireAndForget::Utilities#to_arguments
+    #
+    # @param [Hash] env
+    #   A Hash of values to add to the task's ENV settings
+    #
+    def add_task(task_name, path_to_binary, niceness=0, default_params={}, env={})
+      tasks[task_name] = TaskDescription.new(task_name, path_to_binary, niceness, default_params, env)
     end
 
+    # Returns the path to the binary for the given task
+    #
+    # @param [Symbol] task_name the name of the task
+    # @return [String] the path of the task's binary
     def binary(task_name)
       tasks[task_name].binary
     end
 
+    # Gets the TaskDescription of a task
+    #
+    # @param [Symbol] task_name the name of the task to get
     def [](task_name)
       tasks[task_name]
     end
@@ -20,35 +47,65 @@ module FireAndForget
       @tasks ||= {}
     end
 
+    # Launches the given task
+    #
+    # @param [Symbol] task_name the name of the task to launch
+    # @param [Hash] params parameters to pass to the executable
     def fire(task_name, params={})
       task = tasks[task_name]
       command = Command::Fire.new(task, params)
       Client.run(command)
     end
 
+    # Sets the status of the given task enabling simple interprocess communication through string messages
+    #
+    # @param [String] task_name the name of the task to set the status for
+    # @param [#to_s] status the setting for the given task's status
     def set_status(task_name, status)
       command = Command::SetStatus.new(task_name, status)
       Client.run(command)
     end
 
+    # Get the status for the given task
+    # @see #set_status
+    #
+    # @param [Symbol] task_name the name of the task
+    # @return [String] the current status of the task
     def get_status(task_name)
       command = Command::GetStatus.new(task_name)
       Client.run(command)
     end
 
+    # Used by the {FireAndForget::Daemon} module to set the correct PID for a given task
     def map_pid(task_name, pid)
       command = Command::SetPid.new(task_name, pid)
       Client.run(command)
     end
+    alias_method :set_pid, :map_pid
+
+    # Retrieve the PID of the running task given by task_name
+    def get_pid(task_name)
+      command = Command::GetPid.new(task_name)
+      Client.run(command)
+    end
+    alias_method :pid, :get_pid
 
+    # Sends a running task the TERM signal
     def term(task_name)
       kill(task_name, "TERM")
     end
 
+    # Sends a running task the INT signal
     def int(task_name)
       kill(task_name, "INT")
     end
 
+    # Sends a running task an arbitrary signal
+    #
+    # @param [Symbol] task_name the name of the task to send the signal
+    # @param [String] signal the signal to send
+    #
+    # @see Signal#list for a full list of signals available
     def kill(task_name, signal="TERM")
       command = Command::Kill.new(task_name, signal)
       Client.run(command)
@@ -56,6 +113,12 @@ module FireAndForget
 
     protected
 
+    # Catch method missing to enable launching of tasks by direct name
+    # e.g.
+    #   FireAndForget.add_task(:process_things, "/usr/bin/process")
+    # launch this task:
+    #   FireAndForget.process_things
+    #
     def method_missing(method, *args, &block)
       if tasks.key?(method)
         fire(method, *args, &block)

data/lib/fire_and_forget/server.rb

@@ -7,7 +7,11 @@ module FireAndForget
     end
 
     def self.run(cmd)
-      cmd.run
+      if Command.allowed?(cmd)
+        cmd.run
+      else
+        raise PermissionsError, "'#{cmd.class}' is not an approved command"
+      end
     end
 
     def self.kill(task_name, signal="TERM")

data/lib/fire_and_forget/task_description.rb

@@ -0,0 +1,11 @@
+
+
+module FireAndForget
+  class TaskDescription
+    attr_reader :name, :binary, :niceness, :params, :env
+
+    def initialize(name, path_to_binary, niceness=0, default_parameters={}, env={})
+      @name, @binary, @params, @niceness, @env = name, path_to_binary, default_parameters, niceness, env
+    end
+  end
+end

data/lib/fire_and_forget/utilities.rb

@@ -4,16 +4,16 @@ module FireAndForget
   module Utilities
     def to_arguments(params={})
       params.keys.sort { |a, b| a.to_s <=> b.to_s }.map do |key|
-        %(--#{key}=#{to_json(params[key])})
+        %(--#{key}=#{to_parameter(params[key])})
       end.join(" ")
     end
 
-    def to_json(obj)
+    def to_parameter(obj)
       if obj.is_a?(String)
-        obj.inspect
+        obj
       else
         JSON.generate(obj)
-      end
+      end.inspect
     end
   end
 end

data/lib/fire_and_forget/version.rb

@@ -1,4 +1,4 @@
 
 module FireAndForget
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/fire_and_forget.rb

@@ -1,16 +1,20 @@
 
 module FireAndForget
-  DEFAULT_PORT = 3001
+  DEFAULT_SOCKET = "/tmp/fire_and_forget.sock"
+  ENV_SOCKET = "__FAF_SOCKET"
+  ENV_TASK_NAME = "__FAF_TASK_NAME"
 
   autoload :Config, "fire_and_forget/config"
   autoload :Utilities, "fire_and_forget/utilities"
   autoload :Launcher, "fire_and_forget/launcher"
-  autoload :Task, "fire_and_forget/task"
+  autoload :TaskDescription, "fire_and_forget/task_description"
   autoload :Client, "fire_and_forget/client"
   autoload :Command, "fire_and_forget/command"
   autoload :Server, "fire_and_forget/server"
   autoload :Daemon, "fire_and_forget/daemon"
 
+  require "fire_and_forget/errors"
+
   extend Config
   extend Utilities
   extend Launcher

data/test/test_fire_and_forget.rb

@@ -7,7 +7,7 @@ class TestFireAndForget < Test::Unit::TestCase
         :param1 => "value1",
         :param2 => "value2",
         :array => [1, 2, "3"]
-      }).should == %(--array=[1,2,"3"] --param1="value1" --param2="value2")
+      }).should == %(--array="[1,2,\\"3\\"]" --param1="value1" --param2="value2")
     end
   end
   context "configuration" do
@@ -29,20 +29,24 @@ class TestFireAndForget < Test::Unit::TestCase
       FAF.publish(args)
     end
 
-    should "enable setting of port for server" do
-      FAF.port = 3007
-      FAF.port.should == 3007
-    end
+    should "enable setting of path to socket" do
+      FAF.socket = "/tmp/something"
+      FAF.socket.should ==  "/tmp/something"
+    end
+    # should "enable setting of port for server" do
+    #   FAF.port = 3007
+    #   FAF.port.should == 3007
+    # end
 
-    should "enable setting an address for the server" do
-      FAF.bind_address = "10.0.1.10"
-      FAF.bind_address.should == "10.0.1.10"
-    end
+    # should "enable setting an address for the server" do
+    #   FAF.bind_address = "10.0.1.10"
+    #   FAF.bind_address.should == "10.0.1.10"
+    # end
   end
 
   context "commands" do
     should "serialize and deserialize correctly" do
-      task = FAF::Task.new(:publish, "/publish", {:param1 => "value1", :param2 => "value2"}, 9)
+      task = FAF::TaskDescription.new(:publish, "/publish", 9, {:param1 => "value1", :param2 => "value2"})
       cmd = FAF::Command::CommandBase.new(task, {"param2" => "newvalue2", :param3 => "value3"})
       cmd2 = FAF::Command.load(cmd.dump)
       task2 = cmd2.task
@@ -55,28 +59,56 @@ class TestFireAndForget < Test::Unit::TestCase
 
   context "actions" do
     setup do
-      @task = FAF::Task.new(:publish, "/publish", {:param1 => "value1", :param2 => "value2"}, 9)
+      @task = FAF::TaskDescription.new(:publish, "/publish", 9, {:param1 => "value1", :param2 => "value2"})
     end
     should "set status for a task" do
       cmd = FAF::Command::SetStatus.new(:publish, :doing)
       FAF::Server.run(cmd)
       cmd = FAF::Command::GetStatus.new(:publish)
       status = FAF::Server.run(cmd)
-      status.should == :doing
+      status.should == "doing"
     end
+
     should "only run scripts belonging to the same user as the ruby process" do
       stub(File).exist?("/publish") { true }
       stub(File).exists?("/publish") { true }
-      stub(File).owned?("/publish") { false }
+      stat = Object.new
+      stub(stat).uid { Process.uid + 1 }
+      stub(File).stat("/publish") { stat }
       cmd = FAF::Command::Fire.new(@task)
-      lambda { cmd.run }.should raise_error(Errno::EACCES)
+      lambda { cmd.run }.should raise_error(FAF::PermissionsError)
     end
+
+    should "not raise an error if the binary belongs to this process" do
+      stat = Object.new
+      stub(stat).uid { Process.uid }
+      stub(File).stat("/publish") { stat }
+      cmd = FAF::Command::Fire.new(@task)
+      lambda { cmd.permitted? }.should_not raise_error(FAF::PermissionsError)
+    end
+
+    should "raise an error if the binary belongs to this process" do
+      stat = Object.new
+      uid = Process.uid
+      stub(stat).uid { uid }
+      stub(File).stat("/publish") { stat }
+      stub(Process).euid { uid + 1 }
+      cmd = FAF::Command::Fire.new(@task)
+      lambda { cmd.permitted? }.should raise_error(FAF::PermissionsError)
+    end
+
     should "give error if binary doesn't exist" do
       stub(File).exist?("/publish") { false }
       stub(File).exists?("/publish") { false }
       stub(File).owned?("/publish") { true }
       cmd = FAF::Command::Fire.new(@task)
-      lambda { cmd.run }.should raise_error(Errno::ENOENT )
+      lambda { cmd.run }.should raise_error(FAF::FileNotFoundError)
+    end
+
+    should "raise error if command isn't one of the approved list" do
+      cmd = Object.new
+      mock(cmd).run.times(0)
+      lambda { FAF::Server.run(cmd) }.should raise_error(FAF::PermissionsError)
     end
   end
 
@@ -92,9 +124,8 @@ class TestFireAndForget < Test::Unit::TestCase
       stub(connection).close_write
       mock(connection).read { "99999" }
       mock(connection).close
-      FAF.bind_address = "10.0.1.10"
-      FAF.port = 9007
-      mock(TCPSocket).open("10.0.1.10", 9007) { connection }
+      FAF.socket = "/tmp/faf.sock"
+      mock(UNIXSocket).open("/tmp/faf.sock") { connection }
       pid = FAF.publish({:param2 => "value3"})
       pid.should == "99999"
     end
@@ -107,6 +138,7 @@ class TestFireAndForget < Test::Unit::TestCase
 
     should "run any command sent to it" do
       command = Object.new
+      stub(FAF::Command).allowed? { true }
       mock(FAF::Command).load(is_a(String)) { command }
       mock(command).run { "666" }
       result = FAF::Server.parse("object")
@@ -115,17 +147,18 @@ class TestFireAndForget < Test::Unit::TestCase
   end
   context "daemon methods" do
     setup do
-      class ::TaskClass; end
+      class ::TaskDescriptionClass; end
     end
     teardown do
-      Object.send(:remove_const, :TaskClass) rescue nil
+      Object.send(:remove_const, :TaskDescriptionClass) rescue nil
     end
 
-    should "map a taskname to a pid when included" do
-      mock(FAF::Client).run(satisfy { |cmd|
-        (cmd.pid == $$) && (cmd.task_name == :tasking)
-      })
-      TaskClass.send(:include, FAF::Daemon[:tasking])
-    end
+    ## not sure how to test this
+    # should "map a taskname to a pid when included" do
+    #   mock(FAF::Client).run(satisfy { |cmd|
+    #     (cmd.pid == $$) && (cmd.task_name == :tasking)
+    #   })
+    #   TaskDescriptionClass.send(:include, FAF::Daemon)
+    # end
   end
 end

data/vendor/daemons-1.1.0/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2005-2007 Thomas Uehlinger
+
+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.
+
+This license does not apply to daemonize.rb, which is was written by 
+Travis Whitton und published under the following license:
+
+The Daemonize extension module is copywrited free software by Travis Whitton
+<whitton@atlantic.net>. You can redistribute it under the terms specified in
+the COPYING file of the Ruby distribution.

data/vendor/daemons-1.1.0/README

@@ -0,0 +1,224 @@
+= Daemons Version 1.1.0
+
+(See Releases for release-specific information)
+
+== What is Daemons?
+
+Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server) 
+to be <i>run as a daemon</i> and to be <i>controlled by simple start/stop/restart commands</i>.
+
+If you want, you can also use daemons to <i>run blocks of ruby code in a daemon process</i> and to control
+these processes from the main application.
+
+Besides this basic functionality, daemons offers many advanced features like <i>exception backtracing</i> 
+and logging (in case your ruby script crashes) and <i>monitoring</i> and automatic restarting of your processes
+if they crash.
+
+Daemons includes the <tt>daemonize.rb</tt> script written by <i>Travis Whitton</i> to do the daemonization
+process.
+
+== Basic Usage
+
+You can use Daemons in four different ways:
+
+=== 1. Create wrapper scripts for your server scripts or applications
+
+Layout: suppose you have your self-written server <tt>myserver.rb</tt>:
+
+  # this is myserver.rb
+  # it does nothing really useful at the moment
+  
+  loop do
+    sleep(5)
+  end
+  
+To use <tt>myserver.rb</tt> in a production environment, you need to be able to
+run <tt>myserver.rb</tt> in the _background_ (this means detach it from the console, fork it
+in the background, release all directories and file descriptors).
+
+Just create <tt>myserver_control.rb</tt> like this:
+
+  # this is myserver_control.rb
+  
+  require 'rubygems'        # if you use RubyGems
+  require 'daemons'
+  
+  Daemons.run('myserver.rb')
+  
+And use it like this from the console:
+
+  $ ruby myserver_control.rb start
+      (myserver.rb is now running in the background)
+  $ ruby myserver_control.rb restart
+      (...)
+  $ ruby myserver_control.rb stop
+  
+For testing purposes you can even run <tt>myserver.rb</tt> <i>without forking</i> in the background:
+
+  $ ruby myserver_control.rb run
+
+An additional nice feature of Daemons is that you can pass <i>additional arguments</i> to the script that 
+should be daemonized by seperating them by two _hyphens_:
+  
+  $ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument
+  
+
+=== 2. Create wrapper scripts that include your server procs
+
+Layout: suppose you have some code you want to run in the background and control that background process
+from a script:
+
+  # this is your code
+  # it does nothing really useful at the moment
+  
+  loop do
+    sleep(5)
+  end
+  
+To run this code as a daemon create <tt>myproc_control.rb</tt> like this and include your code:
+
+  # this is myproc_control.rb
+  
+  require 'rubygems'        # if you use RubyGems
+  require 'daemons'
+  
+  Daemons.run_proc('myproc.rb') do
+    loop do
+      sleep(5)
+    end
+  end
+  
+And use it like this from the console:
+
+  $ ruby myproc_control.rb start
+      (myproc.rb is now running in the background)
+  $ ruby myproc_control.rb restart
+      (...)
+  $ ruby myproc_control.rb stop
+  
+For testing purposes you can even run <tt>myproc.rb</tt> <i>without forking</i> in the background:
+
+  $ ruby myproc_control.rb run
+  
+=== 3. Control a bunch of daemons from another application
+
+Layout: you have an application <tt>my_app.rb</tt> that wants to run a bunch of 
+server tasks as daemon processes.
+
+  # this is my_app.rb
+  
+  require 'rubygems'        # if you use RubyGems
+  require 'daemons'
+  
+  task1 = Daemons.call(:multiple => true) do
+    # first server task
+    
+    loop {
+      conn = accept_conn()
+      serve(conn)
+    }
+  end
+  
+  task2 = Daemons.call do
+    # second server task
+    
+    loop {
+      something_different()
+    }
+  end
+  
+  # the parent process continues to run
+  
+  # we can even control our tasks, for example stop them
+  task1.stop
+  task2.stop
+  
+  exit
+  
+=== 4. Daemonize the currently running process
+
+Layout: you have an application <tt>my_daemon.rb</tt> that wants to run as a daemon
+(but without the ability to be controlled by daemons via start/stop commands)
+
+  # this is my_daemons.rb
+  
+  require 'rubygems'        # if you use RubyGems
+  require 'daemons'
+  
+  # Initialize the app while we're not a daemon
+  init()
+  
+  # Become a daemon
+  Daemons.daemonize
+  
+  # The server loop
+  loop {
+    conn = accept_conn()
+    serve(conn)
+  }
+
+  
+<b>For further documentation, refer to the module documentation of Daemons.</b>
+
+  
+== Download and Installation
+
+*Download*: just go to http://rubyforge.org/projects/daemons/
+
+Installation *with* RubyGems:
+  $ su
+  # gem install daemons
+  
+Installation *without* RubyGems:
+  $ tar xfz daemons-x.x.x.tar.gz
+  $ cd daemons-x.x.x
+  $ su
+  # ruby setup.rb
+  
+== Documentation
+
+For further documentation, refer to the module documentation of Daemons (click on Daemons).
+
+The RDoc documentation is also online at http://daemons.rubyforge.org
+
+
+== Author
+
+Written 2005-2010 by Thomas Uehlinger <mailto:th.uehlinger@gmx.ch>.
+Anonymous SVN checkout is available with "svn checkout http://daemons.rubyforge.org/svn/".
+
+== License
+
+Copyright (c) 2005-2010 Thomas Uehlinger
+
+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.
+
+This license does not apply to daemonize.rb, which is was written by 
+Travis Whitton und published under the following license:
+
+The Daemonize extension module is copywrited free software by Travis Whitton
+<whitton@atlantic.net>. You can redistribute it under the terms specified in
+the COPYING file of the Ruby distribution.
+
+== Feedback and other resources
+
+At http://rubyforge.org/projects/daemons.