qup 1.1.0

data/.autotest

@@ -0,0 +1,41 @@
+# vim: syntax=ruby
+
+require 'autotest/restart'
+# vim: ft=ruby
+
+Autotest.add_hook :initialize do |at|
+
+  at.libs    = %w[lib spec].join(File::PATH_SEPARATOR)
+  at.testlib = 'rspec'
+
+  at.add_exception 'coverage.info'
+  at.add_exception 'coverage'
+  at.add_exception '.git'
+
+  at.clear_mappings
+
+  # file in /spec -> run it
+  at.add_mapping(%r|^spec/.*_spec\.rb$|) do |filename, _|
+    filename
+  end
+
+  # file in /lib -> run test in /spec
+  at.add_mapping(%r|^lib/(.*)\.rb$|) do |_, match|
+    at.files_matching %r|^spec/#{match[1]}_spec.rb|
+  end
+
+  at.add_mapping(%r|^spec/spec_helper\.rb|) do
+    at.files_matching( %r|^spec/.*_spec\.rb| )
+  end
+
+  # Make the class map for things in lib
+  class_map = {}
+  sep = File::SEPARATOR
+  Dir.glob("lib/**/*.rb").each do |f|
+    c = f.sub(/lib#{sep}/,'').sub(/\.rb$/,'').split sep
+    c = c.map { |path| path.split(/_|(\d+)/).map { |seq| seq.capitalize }.join }
+    class_map[c.join("::")] = f
+  end
+  at.extra_class_map = class_map
+end
+

data/.gemtest

@@ -0,0 +1 @@
+

data/ADAPTER_API.rdoc

@@ -0,0 +1,97 @@
+= Adding an Adapter
+
+Adding an Adapter to Qup should take the implementation of 3 classes
+
+* Adapter - Inherit from Qup::Adapter
+* Queue - Implement Qup::QueueAPI
+* Topic - Implement Qup::TopicAPI
+
+The rest of the system uses the defined interfaces in the above 3
+Classes/Modules to implement the rest of the behavior.
+
+Qup ships with 2 adapters already and you should use those as a guideline for
+implementing your own Adapter. Feel free to {open an
+issue on Github}[https://github.com/copiousfreetime/qup/issues] with me to
+create a new adaptor, or send me a pull request.
+
+== Adapter
+
+The Qup::Adapter class is how the Adapter gets loaded and is the entry point
+that Qup will use to use the backend.
+
+The Adapter API is laid out in Qup::Adapter.
+
+The Adapter class you implement must have Qup::Adapter as its parent class so that
+you can call the 'register' class method to register your adapter. Your adapter
+will be invoked when a URI with a scheme equivalent to your registration key is
+used.
+
+The other instance methods are an Internal API that the Qup::Session object will
+use to interface with your Adapter. These methods should not be used by an end
+user of the library, they are solely for use by the Qup library.
+
+* Qup::Adapter#close  - close the Adapter for further use
+* Qup::Adapter#closed? - is the Adapter closed
+* Qup::Adapter#queue   - create an object that implements the QueueAPI
+* Qup::Adapter#topic   - create an object that implements the TopicAPI
+
+See Qup::Adapter::Maildir or Qup::Adapter::Kestrel
+
+=== Example
+
+  class Qup::Adapter::MyBackend < Qup::Adapter
+    register :mybackend
+  end
+
+  session = Qup::Session.new( 'mybackend://...' )
+
+
+== Qup::Adapter::MyBackend::Queue
+
+The Queue class is a point-to-point Messaging implementation, typically used for
+worker queues. You should create a 'Qup::Adapter::MyBackend' and have it
+'include Qup:QueueAPI'. These are the methods that are defined for Queue
+objects.
+
+When Qup::Adapter::MyBackend#queue is invoked, it should return an instance of
+the object that implements Qup::QueueAPI.
+
+See Qup::Adapter::Maildir::Queue or Qup::Adapter::Kestrel::Queue
+
+=== Public API used by end users of the system
+
+* Qup::QueueAPI#depth       - How many Messages are currently on the Queue
+* Qup::QueueAPI#destroy     - Remove the Queue from the System if possible
+* Qup::QueueAPI#flush       - Remove all Messages from the Queue
+* Qup::QueueAPI#name        - The String Name of the Queue
+
+=== Internal API used by the Qup library to implement the higher level patterns
+
+* Qup::QueueAPI#acknowledge - Tell the System that you have completed processing a Message
+* Qup::QueueAPI#consume     - Take a message off of the Queue
+* Qup::QueueAPI#produce     - Put a message onto the Queue
+
+
+== Qup::Adapter::MyBackend::Topic
+
+The Topic class is a fanout or pub/sub Messaging implementation, typically
+used to alert or send the same message from one publisher to many subscribers.
+This API is defined in Qup::TopicAPI and all these methods must be implemented.
+
+When Qup::Adapter::MyBackend#topic is invoked, it should return an instance of
+the object that implements Qup::TopicAPI.
+
+See Qup::Adapter::Maildir::Topic or Qup::Adapter::Kestrel::Topic
+
+=== Public API used by end users of the system
+
+* Qup::TopicAPI#destroy          - Remove the Topic from the System if possible
+* Qup::TopicAPI#name             - The String Name of the Topic
+* Qup::TopicAPI#publisher        - Create a new Publisher to the Topic
+* Qup::TopicAPI#subscriber       - Create a new Subscriber to the Topic
+* Qup::TopicAPI#subscriber_count - The number of Subscribers on the Topic
+
+=== Internal API used by the Qup library to implement the higher level patterns
+
+* Qup::TopicAPI#publish          - Send a Message to all the Subscribers
+

data/HISTORY.rdoc

@@ -0,0 +1,9 @@
+= Changelog
+
+== Version 1.0.0 - 2012-03-10
+
+* Initial public release
+
+== Version 1.1.0 - 2012-03-12
+
+* Addition of a Redis Adapter (thanks aniero)

data/Manifest.txt

@@ -0,0 +1,52 @@
+.autotest
+.gemtest
+ADAPTER_API.rdoc
+HISTORY.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/qup.rb
+lib/qup/adapter.rb
+lib/qup/adapter/kestrel.rb
+lib/qup/adapter/kestrel/destination.rb
+lib/qup/adapter/kestrel/queue.rb
+lib/qup/adapter/kestrel/topic.rb
+lib/qup/adapter/maildir.rb
+lib/qup/adapter/maildir/queue.rb
+lib/qup/adapter/maildir/topic.rb
+lib/qup/adapter/redis.rb
+lib/qup/adapter/redis/connection.rb
+lib/qup/adapter/redis/queue.rb
+lib/qup/adapter/redis/topic.rb
+lib/qup/consumer.rb
+lib/qup/message.rb
+lib/qup/producer.rb
+lib/qup/publisher.rb
+lib/qup/queue_api.rb
+lib/qup/session.rb
+lib/qup/subscriber.rb
+lib/qup/topic_api.rb
+spec/qup/adapter/kestrel/queue_spec.rb
+spec/qup/adapter/kestrel/topic_spec.rb
+spec/qup/adapter/kestrel_context.rb
+spec/qup/adapter/kestrel_spec.rb
+spec/qup/adapter/maildir/queue_spec.rb
+spec/qup/adapter/maildir/topic_spec.rb
+spec/qup/adapter/maildir_context.rb
+spec/qup/adapter/maildir_spec.rb
+spec/qup/adapter/redis/queue_spec.rb
+spec/qup/adapter/redis/topic_spec.rb
+spec/qup/adapter/redis_context.rb
+spec/qup/adapter/redis_spec.rb
+spec/qup/adapter_spec.rb
+spec/qup/consumer_spec.rb
+spec/qup/message_spec.rb
+spec/qup/producer_spec.rb
+spec/qup/queue_api_spec.rb
+spec/qup/session_spec.rb
+spec/qup/shared_adapter_examples.rb
+spec/qup/shared_queue_examples.rb
+spec/qup/shared_topic_examples.rb
+spec/qup/topic_api_spec.rb
+spec/qup_spec.rb
+spec/spec_helper.rb

data/README.rdoc

@@ -0,0 +1,156 @@
+= qup - Queue Up
+
+* http://github.com/copiousfreetime/qup
+
+== DESCRIPTION
+
+Qup is a generalized API for Message Queue and Publish/Subscribe messaging
+patterns with the ability to plug in an appropriate messaging infrastructure
+based upon your needs.
+
+Qup ships with support for {Kestrel}[https://github.com/robey/kestrel] and a
+filesystem infrastructure based on {Maildir}[https://rubygems.org/gems/maildir].
+Additional Adapters will be developed as needs arise. {Please submit an
+Issue}[https://github.com/copiousfreetime/qup/issues] to have a new Adapter
+created. Pull requests gladly accepted.
+
+== FEATURES
+
+Qup provides an abstract implementation of two common messaging patterns.
+
+[Basic Message Queue]
+
+  Examples of a basic message queue are {Work/Task
+  Queues}[http://www.rabbitmq.com/tutorials/tutorial-two-python.html], {JMS
+  Queue}[http://docs.oracle.com/javaee/6/api/javax/jms/Queue.html], or {Amazon
+  SQS}[http://aws.amazon.com/sqs/]. This is a pattern where one or more
+  Producers puts Messages on a Queue and one or more Consumers received those
+  Messages. Each Message is delivered only 1 time to a Consumer.
+
+[Publish/Subscribe]
+
+  {Wikipedia Article on Pub/Sub
+  pattern}[http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern].
+
+  Qup implements a Topic based system, where Publishers send Messages on a Topic
+  and all Subscribers to that topic each receive their own copy of the message.
+
+Qup assumes that the messaging systems it has adapters for provided durable and
+acknowledgeable messaging.
+
+[Durability]
+
+  When message is sent to the messaging system by Qup, the message is persisted to
+  disk.
+
+[Acknowledgeable Messages]
+
+  When a Consumer receives a Message, and then processes it, Qup assumes that
+  the messaging infrastructure requires that the Message be positively
+  acknowledged. In other words, if the Consumer does not acknowledge the message
+  then the messages infrastructure will put the Message back onto the Queue.
+
+== SYNOPSIS
+
+=== Basic Message Queue
+
+  session  = Qup::Session.new( "maildir:///tmp/test-queue" )
+  queue    = session.queue( 'basic-messaging' )
+  producer = queue.producer
+
+  consumer_1 = queue.consumer
+  consumer_2 = queue.consumer
+
+  producer.produce( 'message_1' )
+  producer.produce( 'message_2' )
+
+  message_1 = consumer_1.consume
+  puts message_1.data                 # => 'message_1'
+  consumer_1.acknowledge( message_1 )
+
+  consumer_2.consume do |message_2|
+    puts message_2.data               # => 'message_2'
+  end  # auto acknowledged at the end of the block
+
+=== Publish/Subscribe
+
+  session   = Qup::Session.new( "kestrel://messaging.example.com:22133" )
+  topic     = session.topic( 'topic-messaging' )
+  publisher = topic.publisher
+
+  subscribers = []
+  3.times do |n|
+    subscribers << topic.subscriber( "subscriber-#{n}" )
+  end
+
+  publisher.publish( 'a fine message on a topic' )
+
+  subscribers.each do |sub|
+    sub.consume do |msg|
+      puts msg.data                   # => 'a fine message on a topic'
+    end                               # auto acknowledge an end of block
+  end
+
+== REQUIREMENTS
+
+Depending on the backend messaging system you want to use, you'll need to
+install additional gems. At the current moment, these are the supported
+messaging backends.
+
+* Qup::Adapter::Maildir - built in and uses the 'maildir' gem
+* Qup::Adapter::Kestrel - uses the 'kestrel-client' gem
+
+== INSTALL
+
+* gem install qup
+
+== DEVELOPERS
+
+After checking out the source, run:
+
+  $ rake develop
+
+This task will install any missing dependencies. You may then run:
+
+  $ rake test
+
+Other tasks are viewable with
+
+  $ rake -T
+
+=== Kestrel
+
+To run the Kestrel tests you will need:
+
+* gem install kestrel-client
+* A Kestrel server running on <tt>localhost:22133</tt>
+
+You can download Kestrel from http://robey.github.com/kestrel/ and then run the
++scripts/devel.sh+ command and you will have a default Kestrel server running on
+<tt>localhost:22133</tt>. This will be enough to run the kestrel tests.
+
+
+== LICENSE
+
+(The ISC LICENSE)
+
+Copyright (c) 2012 Jeremy Hinegardner
+
+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,246 @@
+# vim: syntax=ruby
+
+This.name     = "qup"
+This.author   = "Jeremy Hinegardner"
+This.email    = "jeremy@copiousfreetime.org"
+This.homepage = "http://github.com/copiousfreetime/#{ This.name }"
+This.version  = Util.version
+
+#------------------------------------------------------------------------------
+# If you want to Develop on qup just run 'rake develop' and you'll have all you
+# need to get going. If you want to use bundler for development, then run
+# 'rake develop:using_bundler'
+#------------------------------------------------------------------------------
+namespace :develop do
+  task :default do
+    require 'rubygems/dependency_installer'
+    installer = Gem::DependencyInstaller.new
+
+    puts "Installing gem depedencies needed for development"
+    This.gemspec.dependencies.each do |dep|
+      if dep.matching_specs.empty? then
+        puts "Installing : #{dep}"
+        installer.install dep
+      else
+        puts "Skipping   : #{dep} -> already installed #{dep.matching_specs.first.full_name}"
+      end
+    end
+    puts "\n\nNow run 'rake test'"
+  end
+
+  file 'Gemfile' => :gemspec do
+    File.open( "Gemfile", "w+" ) do |f|
+      f.puts 'source :rubygems'
+      f.puts 'gemspec'
+    end
+  end
+
+  desc "Create a bundler Gemfile"
+  task :using_bundler => 'Gemfile' do
+    puts "Now you can 'bundle'"
+  end
+  CLOBBER << FileList['Gemfile*']
+end
+desc "Boostrap development"
+task :develop => "develop:default"
+
+#------------------------------------------------------------------------------
+# RSpec
+#------------------------------------------------------------------------------
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new( :test ) do |t|
+    t.ruby_opts    = %w[ -w ]
+    t.rspec_opts   = %w[ --color --format documentation ]
+  end
+  task :default => :test
+rescue LoadError
+  Util.task_warning( 'test' )
+end
+
+#------------------------------------------------------------------------------
+# RDoc
+#------------------------------------------------------------------------------
+begin
+  require 'rdoc/task'
+  RDoc::Task.new do |t|
+    t.markup   = 'tomdoc'
+    t.rdoc_dir = 'doc'
+    t.main     = 'README.rdoc'
+    t.title    = "#{This.name} #{This.version}"
+    t.rdoc_files.include( '*.rdoc', 'lib/**/*.rb' )
+  end
+rescue LoadError
+  Util.task_warning( 'rdoc' )
+end
+
+#------------------------------------------------------------------------------
+# Coverage
+#------------------------------------------------------------------------------
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs      << 'spec'
+    t.pattern   = 'spec/**/*_spec.rb'
+    t.verbose   = true
+    t.rcov_opts << "-x ^/"           # remove all the global files
+    t.rcov_opts << "--sort coverage" # so we see the worst files at the top
+  end
+rescue LoadError
+  Util.task_warning( 'rcov' )
+end
+
+#------------------------------------------------------------------------------
+# Manifest - most of this is from Hoe
+#------------------------------------------------------------------------------
+namespace 'manifest' do
+  desc "Check the manifest"
+  task :check => :clean do
+    files = FileList["**/*", ".*"].exclude( This.exclude_from_manifest ).to_a.sort
+    files = files.select{ |f| File.file?( f ) }
+
+    tmp = "Manifest.tmp"
+    File.open( tmp, 'w' ) do |f|
+      f.puts files.join("\n")
+    end
+
+    begin
+      sh "diff -du Manifest.txt #{tmp}"
+    ensure
+      rm tmp
+    end
+    puts "Manifest looks good"
+  end
+
+  desc "Generate the manifest"
+  task :generate => :clean do
+    files = %x[ git ls-files ].split("\n").sort
+    files.reject! { |f| f =~ This.exclude_from_manifest }
+    File.open( "Manifest.txt", "w" ) do |f|
+      f.puts files.join("\n")
+    end
+  end
+end
+
+#------------------------------------------------------------------------------
+# Gem Specification
+#------------------------------------------------------------------------------
+This.gemspec = Gem::Specification.new do |spec|
+  spec.name        = This.name
+  spec.version     = This.version
+  spec.author      = This.author
+  spec.email       = This.email
+  spec.homepage    = This.homepage
+
+  spec.summary     = This.summary
+  spec.description = This.description
+
+  spec.files       = This.manifest
+  spec.executables = spec.files.grep(/^bin/) { |f| File.basename(f) }
+  spec.test_files  = spec.files.grep(/^spec/)
+
+  spec.extra_rdoc_files += spec.files.grep(/(txt|rdoc)$/)
+  spec.rdoc_options = [ "--main"  , 'README.rdoc',
+                        "--markup", "tomdoc" ]
+
+  # The Runtime Dependencies
+  spec.add_runtime_dependency( 'maildir', '~> 2.0.0' )
+
+  # Additional functionality if used
+  spec.add_development_dependency( 'kestrel-client'  , '~> 0.7.1' )
+  spec.add_development_dependency( 'redis'           , '~> 2.2.2' )
+  spec.add_development_dependency( 'SystemTimer'     , '~> 1.2.3' )
+
+  # The Development Dependencies
+  spec.add_development_dependency( 'rake'  , '~> 0.9.2.2')
+  spec.add_development_dependency( 'rcov'  , '~> 1.0.0'  )
+  spec.add_development_dependency( 'rspec' , '~> 2.8.0'  )
+  spec.add_development_dependency( 'rdoc'  , '~> 3.12'   )
+
+end
+This.gemspec_file = "#{This.name}.gemspec"
+
+desc "Build the #{This.name}.gemspec file"
+task :gemspec do
+  File.open( This.gemspec_file, "wb+" ) do |f|
+    f.write This.gemspec.to_ruby
+  end
+end
+CLOBBER << This.gemspec_file
+
+require 'rubygems/package_task'
+Gem::PackageTask.new( This.gemspec ) do
+  # nothing
+end
+
+#------------------------------------------------------------------------------
+# Release
+#------------------------------------------------------------------------------
+task :release_check do
+  unless `git branch` =~ /^\* master$/
+    abort "You must be on the master branch to release!"
+  end
+  unless `git status` =~ /^nothing to commit/m
+    abort "Nope, sorry, you have unfinished business"
+  end
+end
+
+desc "Create tag v#{This.version}, build and push #{This.gemspec.full_name} to rubygems.org"
+task :release => [ :release_check, 'manifest:check', :gem ] do
+  sh "git commit --allow-empty -a -m 'Release #{This.version}'"
+  sh "git tag -a -m 'v#{This.version}' v#{This.version}"
+  sh "git push origin master"
+  sh "git push origin v#{This.version}"
+  sh "gem push pkg/#{This.gemspec.full_name}.gem"
+end
+
+#------------------------------------------------------------------------------
+# Rakefile Support
+#------------------------------------------------------------------------------
+BEGIN {
+
+  require 'ostruct'
+  require 'rake/clean'
+  require 'rubygems' unless defined? Gem
+
+  module Util
+    def self.version
+      line = File.read( "lib/#{ This.name }.rb" )[/^\s*VERSION\s*=\s*.*/]
+      line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+    end
+
+    # Partition an rdoc file into sections and return the text of the section
+    # as an array of paragraphs
+    def self.section_of( file, section_name )
+      re    = /^=+ (.*)$/
+      parts = File.read( file ).split( re )[1..-1]
+      parts.map! { |p| p.strip }
+
+      sections = Hash.new
+      Hash[*parts].each do |k,v|
+        sections[k] = v.split("\n\n")
+      end
+      return sections[section_name]
+    end
+
+    def self.task_warning( task )
+      warn "WARNING: '#{task}' tasks are not defined. Please run 'rake develop'"
+    end
+
+    def self.read_manifest
+      abort "You need a Manifest.txt" unless File.readable?( "Manifest.txt" )
+      File.readlines( "Manifest.txt" ).map { |l| l.strip }
+    end
+  end
+
+  # Hold all the metadata about this project
+  This = OpenStruct.new
+  desc = Util.section_of( 'README.rdoc', 'DESCRIPTION')
+  This.summary     = desc.first
+  This.description = desc.join("\n\n")
+
+
+  This.exclude_from_manifest = %r/tmp$|\.(git|DS_Store)|^(doc|coverage|pkg)|\.gemspec$|\.swp$|\.jar|\.rvmrc$|~$/
+  This.manifest = Util.read_manifest
+
+}