simple_message_queue 0.0.1

data/README.md

@@ -0,0 +1,134 @@
+# Simple Message Queue
+
+Simple Message Queue is a gem to create and receive messages from AWS's SQS. You will need an AWS account with SQS enabled in order to use Simple Message Queue.
+
+Simple Message Queue can be used by a single application for background job processing (e.g. sending emails in the background), or by multiple applications to communicate with each other (e.g. sending data between applications).
+
+### Setting up Simple Message Queue
+
+In order to use Simple Message Queue in your application, you must first configure it. In order to configure Simple Message Queue, you must call a configure block and pass at least your AWS access_key_id and secret_access_key:
+
+```ruby
+SimpleMessageQueue.configure do |config|
+  config.access_key_id = 'your_access_key_id'
+  config.secret_access_key= 'your_secret_access_key'
+end
+```
+
+In a rails application this is best done in an initializer. Create a file in config/initializers called simple_message_queue.rb and add the configure block. 
+
+You can also pass in a few other variables to the configure block such as an idle_timeout and wait_time_seconds (both used only when receiving messages) as well as a logger to replace the default logger (STDOUT).
+
+```ruby
+SimpleMessageQueue.configure do |config|
+  config.access_key_id = 'your_access_key_id'
+  config.secret_access_key= 'your_secret_access_key'
+  config.idle_timeout = 10                                  # optional
+  config.wait_time_seconds = 20                             # optional
+  config.logger = Logger.new('simple_message_queue.log')    # optional
+  config.delay_between_polls = 60*30                        # optional
+end
+```
+
+### Using Simple Message Queue
+
+To use Simple Message Queue, you will need to start by creating a model for your queue such as TestQueue. This model can be created anywhere, although you will need to make sure that it is in a location that is loaded by your application. For rails applications it is best practice to place your queues in app/queues.
+
+Next you will need to extend SimpleMessageQueue in your model:
+
+```ruby
+class TestQueue
+  extend SimpleMessageQueue
+end
+```
+
+#### Queue Naming
+
+By default, your SQS queue will be named after the model you created (e.g. TestQueue will have a queue named test_queue). You can overwrite this in your model by adding a queue_name method to the class:
+
+```ruby
+class TestQueue
+  extend SimpleMessageQueue
+
+  def self.queue_name
+    'my_new_queue_name'
+  end
+end
+```
+
+#### Sending Messages
+
+In order to send a message with Simple Message Queue, simply call the following:
+
+```ruby
+TestQueue.send('my_string')
+```
+
+You can send anything you would like to the queue, but it must be a string. You can send a simple message, or you can send the json representation of an object. What you send is completely up to you.
+
+#### Receiving Messages
+
+In order to receive messages, you will need to define a process_message method for your new queue model. Since every queue will process messages differently, you will need to tell your queue how to process these messages.
+
+```ruby
+class TestQueue
+  extend SimpleMessageQueue
+
+  def self.process_message(message)
+    logger.info message.body
+  end
+end
+```
+
+Once you have defined the process_message method, you can call TestQueue.receive to receive messages once. This will poll your queue with the idle_timeout and wait_time_seconds (either the defaults or what was defined in the configure block).
+
+If you want to continuously receive messages (as opposed to once), you will need to set up something that will keep calling TestQueue.receive. You could create a rake task which is then called by a cron job, or you could set up a daemon.
+
+##### Using daemons-rails gem to continuously receive messages
+
+One of the easiest ways to continuously receive messages is to set up a daemon that will keep calling TestQueue.receive. If you are using Simple Message Queue with rails, you can use the 'daemons-rails' gem (https://github.com/mirasrael/daemons-rails). Place this in your Gemfile and bundle. Next, generate a daemon with 'rails g daemon [name]'. 2 files will be created in lib/daemons, [name]_daemon_ctl (a setup file for your daemon) and [name]_daemon.rb (which is where we will place the code to receive messages). In [name]_daemon.rb, within the while($running) block, we want to call TestQueue.receive and then have it sleep. The length we have it sleep will be the time between polling for messages.
+
+test_queue_daemon.rb
+```ruby
+#!/usr/bin/env ruby
+
+# You might want to change this
+ENV["RAILS_ENV"] ||= "production"
+
+root = File.expand_path(File.dirname(__FILE__))
+root = File.dirname(root) until File.exists?(File.join(root, 'config'))
+Dir.chdir(root)
+
+require File.join(root, "config", "environment")
+
+$running = true
+Signal.trap("TERM") do 
+  $running = false
+end
+
+while($running) do
+  
+  TestQueue.run
+  sleep 60*5
+
+end
+```
+
+This is the default [name]_daemon.rb file generated, with out code placed in the while($running) block. You can now access all of the rake tasks associated with the daemon (refer to the daemon-rails github page for these rake tasks).
+
+**NOTE:** You will want to monitor these daemons and have something to restart them if they stop. Something like God (http://godrb.com/) or Monit (http://mmonit.com/monit/) will work nicely.
+
+### Single Site Communication
+
+If you are using Simple Message Queue for background processing on a single site, all you need to do is create your model and extend SimpleMessageQueue. You will then be able to call the send and receive methods on that model.
+
+### Multiple Site Communication
+
+If you are using Simple Message Queue for background processing between sites you will need to take a few additional steps. You will need to create a model in each application that extends SimpleMessageQueue. Next, both of these models will need to have the same queue_name. You can do this with careful naming, or define the queue_name method as described above and give them the same name (recommended). 
+
+**Note:** If you have multiple models receiving messages from the same queue, there is no guarantee which model will receive which message. This is why it is best to only have a single model (on a single site) receiving messages from a specific queue. If you need multiple queues, simply create multiple models with different queue_names.
+
+## Contributing
+
+In order to contribute to this gem, please submit a pull request with passing tests. 
+In order to test locally, you will need to rename lib/config.yml.sample to lib/config.yml and add in your AWS access_key_id and secret_access_key.

data/lib/config.yml

@@ -0,0 +1,3 @@
+AWS:
+  access_key_id: 'AKIAJFYG4X4ZWVWPEL2A'
+  secret_access_key: '77QzH7gj7u81kH/Z3fJSL7PjyxzoEJdrDHy4orNu'

data/lib/config.yml.sample

@@ -0,0 +1,4 @@
+# For development purposes (running tests) add your AWS access_key_id and secret_access_key below, and rename this file config.yml
+AWS:
+  access_key_id: 'access_key_id'
+  secret_access_key: 'secret_access_key'

data/lib/simple_message_queue.rb

@@ -0,0 +1,73 @@
+require 'simple_message_queue/configuration'
+require 'simple_message_queue/core_ext/string'
+require 'simple_message_queue/errors'
+require 'aws'
+
+module SimpleMessageQueue
+  class << self
+    # Class Methods only available to SimpleMessageQueue
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+  end
+
+  def sqs
+    raise SimpleMessageQueue::ConfigurationError unless SimpleMessageQueue.configuration
+    @@sqs ||= AWS::SQS.new(:access_key_id => SimpleMessageQueue.configuration.access_key_id, :secret_access_key => SimpleMessageQueue.configuration.secret_access_key)
+  end
+
+  def queue_name
+    name.underscore.gsub('/', '_')
+  end
+
+  def queue
+    @queue ||= sqs.queues.create(queue_name)
+  end
+
+  def count
+    queue.approximate_number_of_messages
+  end
+
+   def delete_queue
+    queue.delete
+  end
+
+  def exists?
+    # Although there is a queue.exists? method, that is only relevant if you already have the queue stored in a variable and then delete it
+    # Trying to look it up by name will either return the queue object or throw an error, hence the rescue
+    true if sqs.queues.named(queue_name)
+  rescue
+    false
+  end
+
+  def send(message)
+    queue.send_message(message)
+  end
+
+  def logger
+    if SimpleMessageQueue.configuration.logger
+      @logger ||= SimpleMessageQueue.configuration.logger
+    else
+      @logger ||= Logger.new(STDOUT)
+    end
+  end
+
+  def receive
+    @count = 0
+    logger.info "Receiving messages for #{queue_name} at #{DateTime.now}"
+    queue.poll(:idle_timeout => SimpleMessageQueue.configuration.idle_timeout, :wait_time_seconds => SimpleMessageQueue.configuration.wait_time_seconds) do |message|
+      @count += 1
+      process_message(message)
+    end
+    @count
+  end
+
+  def process_message(message)
+    raise SimpleMessageQueue::NotImplementedError.new(name)
+  end
+
+end

data/lib/simple_message_queue/configuration.rb

@@ -0,0 +1,13 @@
+module SimpleMessageQueue
+  class Configuration
+    attr_accessor :access_key_id, :secret_access_key, :logger, :idle_timeout, :wait_time_seconds
+
+    def initialize
+      @access_key_id = nil
+      @secret_access_key = nil
+      @logger = nil
+      @idle_timeout = 10
+      @wait_time_seconds = 20
+    end
+  end
+end

data/lib/simple_message_queue/core_ext/string.rb

@@ -0,0 +1,11 @@
+class String
+  def underscore
+    word = self.dup
+    word.gsub!(/::/, '/')
+    word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+    word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+    word.tr!("-", "_")
+    word.downcase!
+    word
+  end
+end

data/lib/simple_message_queue/errors.rb

@@ -0,0 +1,17 @@
+module SimpleMessageQueue
+
+  class ConfigurationError < StandardError
+    def initialize
+      message = "SimpleMessageQueue has not been configured. Create an initializer with a SimpleMessageQueue.configure block and set the access_key_id and secret_access_key."
+      super(message)
+    end
+  end
+
+  class NotImplementedError < StandardError
+    def initialize(name)
+      message = "You must define the process_message method for #{name}"
+      super(message)
+    end
+  end
+
+end

data/lib/simple_message_queue/version.rb

@@ -0,0 +1,3 @@
+module SimpleMessageQueue
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: simple_message_queue
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jim Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk
+  requirement: &70108391216460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70108391216460
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70108391216040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70108391216040
+description: SimpleMessageQueue is a simple interface for Amazon Web Service's SQS.
+email:
+- jim@jimsmithdesign.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/config.yml
+- lib/config.yml.sample
+- lib/simple_message_queue/configuration.rb
+- lib/simple_message_queue/core_ext/string.rb
+- lib/simple_message_queue/errors.rb
+- lib/simple_message_queue/version.rb
+- lib/simple_message_queue.rb
+- README.md
+homepage: https://github.com/cbi/simple_message_queue
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: SimpleMessageQueue
+test_files: []