Push jobs into starling
Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
files
lib
tasks
test
MIT-LICENSE
README
Rakefile
init.rb
install.rb

README

= Simplified Starling

This plugin was coded to define an easy way to push jobs into Starling, log 
queues and daemonize the unqueue process.

== Installing Starling

Required gems.

    $ sudo gem install memcache-client
    $ sudo gem install SyslogLogger
    $ sudo gem install eventmachine

You can follow these steps to build <tt>starling</tt> from source.

    $ git clone git://github.com/starling/starling.git
    $ cd starling
    $ gem build starling.gemspec
    $ sudo gem install -l starling*.gem

You can install <tt>starling</tt> from the gem server.

    $ gem sources -a http://gems.github.com (you only have to do this once)
    $ sudo gem install starling-starling

Note: Installing <tt>starling</tt> from the gem server is still not working.

== Installing this plugin

Install this Rails plugin as usual.

    script/plugin install git://github.com/fesplugas/simplified_starling.git

After installing the plugin you'll find a configuration file on the config 
folder of your Rails application named +starling.yml+.

    development:
      host: 127.0.0.1
      port: 22122
      pid_file: /tmp/starling.pid
      queue_path: /tmp
      timeout: 0
      syslog_channel: starling-tampopo
      log_level: DEBUG
      daemonize: true
      queue: app_development

Note: If you don't use the `script/plugin install` to install the plugin 
configuration files will not be created. From the root folder of your Rails 
application run the following command to create them.

    $ rake simplified:starling:setup

=== How it works?

With +starling+ installed in your machine you can start/stop/restart Starling 
by running.

    $ rake simplified:starling:start
    $ rake simplified:starling:stop
    $ rake simplified:starling:restart

Once Starling is being started you can start processing jobs.

    $ rake simplified:starling:start_processing_jobs

You can start Starling and start processing jobs by ...

    $ rake simplified:starling:start_and_process_jobs

If you want to stop processing jobs ...

    $ rake simplified:starling:stop_processing_jobs

You can put anything into Starling, but after using Starling on a couple of 
projects I've seen I use always the same hash for storing the jobs. This will 
push into the queue the task +test_rendering+ which belongs to a model.

    ##
    # From a model/controller
    #
    newsletter = Newsletter.find(params[:id])
    newsletter.push('test_rendering')
    => STARLING.set('app', { :type => 'Newsletter', 
                             :id => 1, 
                             :task => 'test_rendering' })

You can even push a class task into the queue. This will push into the queue 
the task +recalculate+ which belongs to a model.

    ##
    # From a model/controller
    #
    Stock.push('recalculate')
    => STARLING.set('app', { :type => 'Stock', 
                             :task => 'recalculate' })

To view queue stats ...

    $ rake simplified:starling:stats

Processed jobs are logged.

    $ tail -f log/development_starling.log
    $ tail -f log/production_starling.log

=== Log

Each time a job is pushed and popped to the queue is logged.

    [2008-06-30 11:06:03] Pushed dispatch order
    [2008-06-30 11:06:03] Popped dispatch order

If database connection goes down or dies after a few hours of inactivity 
database connection will be restored and job will be processed.

    [2008-06-30 11:06:42] Pushed rebuild Page 3
    [2008-06-30 11:06:42] WARNING Database connection gone, reconnecting & retrying.
                          {:type=>"Order", :task=>"dispatch", :id=>nil}
    [2008-06-30 11:06:44] Popped rebuild Page 3

If the record you're trying to process is removed from the database before 
the queue is processed you'll see a warning on the logs.

    [2008-06-30 11:06:50] Pushed rebuild Page 3
    [2008-06-30 11:06:50] WARNING Page#3 gone from database.

=== Example 1

Push a +newsletter+ job into +starling+.

    ##
    # app/controllers/typus/newsletters_controller.rb
    #
    class Typus::NewslettersController < TypusController

      def test_deliver
        Newsletter.find(params[:id]).push('test_rendering')
        flash[:notice] = "Newsletter added to queue."
        redirect_to :back
      end

      def deliver
        Newsletter.find(params[:id]).push('deliver')
        flash[:notice] = "Newsletter added to queue."
        redirect_to :back
      end

    end

    ##
    # app/models/newsletter.rb
    #
    class Newsletter < ActiveRecord::Base

      def test_rendering
        ##
        # Your long-running task to deliver newsletter to test rendering
        # in diferent email readers.
      end

      def deliver
        ##
        # Long running task to deliver newsletter ...
        #
      end

    end

=== Example 2

Confirm an +order+ payment and push into +starling+ an stock recalculation job.

    ##
    # app/controllers/payments_controller.rb
    class PaymentsController < ApplicationController

      def confirm
        @order = Order.find_by_token(params[:token])
        @order.confirm_payment
        flash[:notice] = "Thanks for your purchase!"
        redirect_to :action => 'thanks'
      end

    end

    ##
    # app/models/order.rb
    class Order < ActiveRecord::Base

      def confirm_payment
        OrderMailer.deliver_payment_confirmation(order)
        Stock.push('recalculate')
      end

    end

    ##
    # app/models/stock.rb
    class Stock < ActiveRecord::Base

      def self.recalculate
        ##
        # A long running operation ...
        #
      end

    end

== Acknowledgments

- Blaine Cook, Twitter Inc. for this nice queue system.

Copyright (c) 2008 Francesc Esplugas Marti, released under the MIT license