= Fire & Forget Fire & Forget is a simple, framework agnostic, background task launcher for Ruby web apps. What it does: - Designed for infrequent calls to very long running operations - Provides a mechanism for calling any external script from within a HTTP request - Gives simple inter-process communication for status updates - Launches long running tasks as completely independent processes so that you can restart/redeploy your application without interrupting any running tasks - Provides a 'kill' mechanism so you can cancel your tasks What it doesn't: - Have any kind of queue mechanism. If you fire the same task twice then that task will be running twice - Have any persistant state - Work in non-UNIX environments == Quick Start gem install fire_and_forget FAF works by running a simple UNIX socket server so before we want to use it we have to start this server. $ fire_forget FAF process 16235 listening on /tmp/fire_and_forget.sock ... To change the path of the socket file use the '-s' parameter: $ fire_forget -s /path/to/socket FAF process 16240 listening on /path/to/socket ... If you do this you will need to set the web-app to use the right values: FireAndForget.socket = "/path/to/socket" Now inside our Ruby app: require 'rubygems' require 'fire_and_forget' # First set register our task by giving it a name and a path to a script file FireAndForget.add_task(:long_running_task, "/path/to/script") # => # # when we want to call the script we simple call #fire passing the name of the # task and the options we want to pass FireAndForget.fire(:long_running_task, {:param3 => "value3"}) # => "OK" # Or, use the name as a method: FireAndForget.long_running_task({:param3 => "value3"}) # => "OK" This will result in the following command being exec'd in an independent process: /path/to/script --param3="value3" It up to the script to parse and deal with the command line options. The options for the #add_task call are as follows: task_name: A symbol giving the (unique) name for this task path_to_binary: The path on disk of the executable to run when this task is launched niceness: an integer in the range 0-20 giving the 'niceness' of the task process. default_params: Command line parameters to pass to each invocation of this task env: settings to add to this task's environment The higher the nice value, the lower the priority of the task. Setting a high 'nice' allows you to launch intensive background tasks without affecting the performance of your front line HTTP services. For example: FireAndForget.add_task(:long_running_task, "/path/to/script", 12, {:param1 => "value1", :param2 => "value2", :param3 => "value3"}, {"ENVIRONMENT_SETTING" => "Something"} ) this will add some default parameters to all invocations of the task, so now the call FireAndForget.fire(:long_running_task, {:param3 => "newvalue3"}) will issue the following command in the background /path/to/script --param1="value1" --param2="value2" --param3="newvalue3" as well as setting it's nice value to 12 and updating ENV with the extra parameter "ENVIRONMENT_SETTING". Parameter values are encoded in a format compatible with Thor: Arrays are encoded as --array=1 2 3 Hashes as --hash=key1:value1 key2:value2 Again, it is up to the script to decode these values. Interprocess communication is relatively easy. Take the following as the source of the script "/path/to/script" #!/usr/bin/env ruby require 'rubygems' require 'fire_and_forget' # this will mix in the F&F status methods # the F&F configuration (socket and task-name) is calculated automatically from ENV parameters include FireAndForget::Daemon 30.times do |i| # update our status. What you put here is up to you, but it should be a String set_task_status("#{i+1} of 30") sleep(1) end Now in the client all we have to do to get the status for our task is: FireAndForget.get_status(:long_running_task) # => "18 of 30" If we decided we've had enough then we can kill it: # Send "SIG_TERM" to our task FireAndForget.term(:long_running_task) # Or send any signal (see the Process.kill documentation) FireAndForget.kill(:long_running_task, "HUP") == Supporting multiple users Tasks will attempt to run as the same user as the originating process. To enable this, and hence enable a single F&F server to launch tasks for any number of separate web-apps, simply run the F&F server as root. See the following section on Security for the implications of this and how to stop unlimited access to the service. == Security F&F is intended to be run in a relatively trusted environment. You the UNIX socket file has its permissions set so that only the process owner and a defined group can write to the file. To change the UNIX group that has access pass the group name as a parameter to the server: $ fire_forget -s /path/to/socket -g webapp_group Only members of the 'webapp_group' will be able to launch processes through the server. Additionally, only scripts belonging to the same user as the F&F task description are executed. In the meantime, as I say, this is defined to be run in a trusted environment, for instance on a single non-shared server (potentially running many sites). == TODO - Improve security restrictions (perhaps by limiting the tasks that each user can launch) - Improve the tests so they are closer to testing the full stack - Add in scheduled/delayed execution of tasks == Contributing to fire_and_forget * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it * Fork the project * Start a feature/bugfix branch * Commit and push until you are happy with your contribution * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally. * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. == Copyright Copyright (c) 2010 Garry Hill. See LICENSE.txt for further details.