pub 0.0.1 → 0.1.0

data/README.md

@@ -1,21 +1,9 @@
-Jotting down the idea:
+# Pub
 
-# Configure
+Pub is a Redis-backed pub with a non-blocking bar counter, or, putting aside
+the metaphor for a moment, a processing queue where consumers, instead of
+simply queuing jobs and getting on with their lives, queue and wait for a
+response without blocking the Ruby process.
 
-    Pub.redis = "localhost:6379"
-    Pub.expires_in = 900
-
-# Subscriber: A request
-
-    Queue["foo"].subscribe("1234") do |resp|
-      puts resp
-    end
-
-# Publisher: A background worker
-
-    queue = Queue["foo"]
-    # Process up to 10 requests at a time
-    reqs = queue.pop(10)
-    process(reqs) do |req, resp|
-      queue.publish(req, resp)
-    end
+This is a barebone work-in-progress that I am about to give a test ride to in
+an app I'm building.

data/Rakefile

@@ -1 +1,14 @@
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
+require "cucumber/rake/task"
+require "rspec/core/rake_task"
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "features --format pretty"
+end
+
+desc "Run all specs in spec directory"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => [:spec, :features]

data/features/README.md

@@ -0,0 +1,9 @@
+# Pub
+
+Pub is a Redis-backed pub with a non-blocking bar counter, or, putting aside
+the metaphor for a moment, a processing queue where consumers, instead of
+simply queuing jobs and getting on with their lives, queue and wait for a
+response without blocking the Ruby process.
+
+This is a barebone work-in-progress that I am about to give a test ride to in
+an app I'm building.

data/features/order.feature

@@ -0,0 +1,63 @@
+Feature: Order beers
+  As a pub patron  
+  I want bartenders to take orders asynchronously  
+  So I do not block the counter  
+
+  Below we assume a bartender can fill an order in one second.
+
+  Scenario: Order a beer
+    Given 1 bartender
+    When "John" orders:
+      | beer           |
+      | Brooklyn Lager |
+    Then "John" should receive his beer in 1 second
+
+  Scenario: Order multiple beers
+    Given 1 bartender
+    When "John" orders:
+      | beer           |
+      | Brooklyn Lager |
+      | Efes Pilsen    |
+    Then "John" should receive his beers in 2 seconds
+
+  Scenario: Two bartenders
+    Given 2 bartenders
+    When "John" orders:
+      | beer           |
+      | Brooklyn Lager |
+      | Efes Pilsen    |
+    Then "John" should receive his beers in 1 second
+
+  Scenario: Timeout
+    Given 1 bartender
+    And "John" has no patience to wait more than 2 seconds at the counter
+    When "John" orders:
+      | beer           |
+      | Brooklyn Lager |
+      | Efes Pilsen    |
+      | Stella         |
+    Then "John" should receive the following beers in 2 seconds:
+      | beer                    |
+      | A pint of Brooklyn Lager |
+      | A pint of Efes Pilsen    |
+
+  Scenario: Two patrons order the same beer
+    Given 1 bartender
+    And "John" orders:
+      | beer           |
+      | Brooklyn Lager |
+    And "Jane" orders:
+      | beer           |
+      | Brooklyn Lager |
+    Then "John" should receive his beer in 1 second
+    And "Jane" should receive her beer in 1 second
+
+  Scenario: Crowd
+    Given 10 bartenders
+    When 10 patrons order 1 beer each
+    Then they should receive their beers within 1 second
+
+  Scenario: Overcrowding
+    Given 2 bartenders
+    When 4 patrons order 2 beers each
+    Then they should receive their beers within 4 seconds

data/features/step_definitions/numeric_transforms.rb

@@ -0,0 +1,3 @@
+Transform /^-?\d+$/ do |number|
+  number.to_i
+end

data/features/step_definitions/pub_steps.rb

@@ -0,0 +1,112 @@
+module PubHelpers
+  def data_store(name)
+    patron_names << name unless patron_names.include?(name)
+
+    instance_variable_get("@hash_of_#{name}") ||
+    instance_variable_set("@hash_of_#{name}", Hash.new)
+  end
+
+  def find_or_create_patron(name)
+    instance_variable_get("@#{name}") ||
+    instance_variable_set("@#{name}", pub.new_patron)
+  end
+
+  def map_beers(table)
+    table.hashes.map { |hash| hash["beer"] }
+  end
+
+  def now
+    Time.now
+  end
+
+  def orders
+    @orders ||= Hash.new
+  end
+
+  def patron_names
+    @patron_names ||= []
+  end
+
+  def pub
+    @pub ||= Pub.new("Ye Olde Rubies")
+  end
+
+  def sleep_until_order_complete(name)
+    fiber = data_store(name)[:fiber]
+    EM::Synchrony.sleep(0.1) while fiber.alive?
+  end
+end
+
+World(PubHelpers)
+
+Given /^(\d+) bartenders?$/ do |count|
+  count.times do |counter|
+    bartender = pub.new_bartender
+    EM.add_periodic_timer(1) do
+      Fiber.new do
+        orders = bartender.take_orders(1)
+        order = orders.first
+        bartender.serve(order) { "A pint of #{order}" } if order
+      end.resume
+    end
+  end
+end
+
+Given /^"([^"]+)" has no patience to wait more than (\d+) seconds at the counter$/ do |name, seconds|
+  patron = find_or_create_patron(name)
+  patron.instance_variable_set(:@timeout, seconds)
+end
+
+When /^"([^"]+)" orders:$/ do |name, table|
+  beers  = map_beers(table)
+  patron = find_or_create_patron(name)
+
+  data_store(name)[:started_at] = Time.now
+
+  fiber = Fiber.new do
+    tray = patron.order(*beers)
+    data_store(name)[:tray] = tray
+  end
+  data_store(name)[:fiber] = fiber
+
+  EM.next_tick { fiber.resume }
+end
+
+When /^(\d+) patrons order (\d+) beers? each$/ do |patrons_count, beers_count|
+  patrons_count.times do |patron_counter|
+    raw = beers_count.times.inject("| beer |\n") do |raw, beer_counter|
+      raw << "| beer_#{patron_counter}_#{beer_counter} |\n"
+    end
+    name = "patron_#{patron_counter}"
+    When %{"#{name}" orders:}, table(raw)
+  end
+end
+
+Then /^"([^"]+)" should receive (?:his|her) beers? in (\d+) seconds?$/ do |name, seconds|
+  sleep_until_order_complete(name)
+
+  started_at = data_store(name)[:started_at]
+  (now - started_at).should be_within(0.2).of(seconds)
+end
+
+Then /^"([^"]+)" should receive the following beers? in (\d+) seconds?:$/ do |name, seconds, table|
+  sleep_until_order_complete(name)
+
+  started_at = data_store(name)[:started_at]
+  (now - started_at).should be_within(0.2).of(seconds)
+
+  beers = map_beers(table)
+  tray = data_store(name)[:tray]
+  tray.should =~ beers
+end
+
+Then /^they should receive their beers within (\d+) seconds?$/ do |seconds|
+  started_at  = now
+  patron_names.each do |name|
+    patron_started_at = data_store(name)[:started_at]
+    started_at = patron_started_at if patron_started_at < started_at
+    sleep_until_order_complete(name)
+  end
+
+  (now - started_at).should be_within(0.2).of(seconds)
+end

data/features/support/env.rb

@@ -0,0 +1,15 @@
+require "rubygems"
+require "bundler/setup"
+
+require "pub"
+
+Around do |scenario, block|
+  EM.synchrony do
+    block.call
+    EM.stop
+  end
+end
+
+Before do
+  Pub.counter.flushall
+end

data/lib/pub.rb

@@ -1,14 +1,64 @@
-begin
-  require "yajl"
-rescue LoadError
-  require "json"
-end
-
-require "redis/connection/synchrony"
 require "redis"
+require "redis/connection/synchrony"
+
+require "pub/helpers"
+require "pub/bartender"
+require "pub/patron"
+
+# A Redis-backed pub with a non-blocking bar counter.
+#
+# Or, putting aside the metaphor for a moment:
+#
+# A processing queue where consumers, instead of simply queuing jobs and
+# getting on with their lives, queue and wait for a response without
+# blocking the Ruby process.
+#
+# Each pub instance is a distinct queue.
+class Pub
+  # The name of the pub.
+  attr_reader :name
+
+  class << self
+    # A device that dispenses beer.
+    attr_accessor :beer_tap
+
+    # The bar counter.
+    def counter
+      Redis.new(url: beer_tap)
+    end
+  end
+
+  # Enters a pub.
+  #
+  # Takes the name of the pub and an optional block.
+  #
+  #   Pub.new('Ye Olde Rubies') do |pub|
+  #
+  #     patron = pub.new_patron
+  #
+  #     patron.order('Guinness') do |beer|
+  #       JSON.parse(beer).drink
+  #     end
+  #
+  #   end
+  #
+  def initialize(name)
+    @name = name
+    EM.synchrony { yield self } if block_given?
+  end
+
+  # Closes the pub for the night.
+  def close
+    EM.stop
+  end
 
-require "pub/version"
+  # A new bartender.
+  def new_bartender
+    Bartender.new(name)
+  end
 
-module Pub
-  # Your code goes here...
+  # A new patron.
+  def new_patron(timeout = 5)
+    Patron.new(name, timeout)
+  end
 end

data/lib/pub/bartender.rb

@@ -0,0 +1,44 @@
+class Pub
+  # A bartender.
+  #
+  # In other words, a producer in our processing queue.
+  class Bartender
+    include Helpers
+
+    # Creates a new bartender.
+    #
+    # Takes the name of the pub.
+    def initialize(pub_name)
+      @pub_name = pub_name
+    end
+
+    # Serves a beer to a thirsty patron.
+    #
+    # Takes a block which should return a glass of beer.
+    #
+    # See below for example usage.
+    def serve(beer, &block)
+      counter.lrem(@pub_name, 0, beer)
+      counter.publish(order_for(beer), block.call)
+    end
+
+    # Takes one or more orders from the queue.
+    #
+    #   orders = bartender.take_orders(3)
+    #   orders.each do |order|
+    #       bartender.serve(order) do
+    #         "A pint of #{order}"
+    #     end
+    #   end
+    def take_orders(count = 1)
+      orders = Array.new
+
+      count.times do
+        order = counter.lpop(@pub_name) || break
+        orders << order
+      end
+
+      orders
+    end
+  end
+end

data/lib/pub/helpers.rb

@@ -0,0 +1,18 @@
+class Pub
+  # Methods used by both patron and bartender.
+  module Helpers
+    # A specific order.
+    #
+    # This is a pub/sub channel through with patron and bartender communicate.
+    def order_for(beer)
+      [@pub_name, beer].join(':')
+    end
+
+    # The bar counter.
+    def counter
+      @counter ||= Pub.counter
+    end
+
+    private :order_for, :counter
+  end
+end

data/lib/pub/patron.rb

@@ -0,0 +1,56 @@
+class Pub
+  # A patron.
+  #
+  # In other words, a consumer in our processing queue.
+  class Patron
+    include Helpers
+
+    # Creates a new pub patron.
+    #
+    # Takes the name of the pub and a timeout value in seconds.
+    #
+    # The timeout designates how long a patron is willing to wait at the
+    # counter to receive his or her beer.
+    def initialize(pub_name, timeout)
+      @pub_name, @timeout = pub_name, timeout
+    end
+
+    # Orders one or more beer at the bar counter.
+    #
+    # If given a block, yields beers as they become available. Otherwise,
+    # returns all on a tray.
+    #
+    # If not all beers are served within specified timeout, it will return only
+    # the beers that are ready.
+    def order(*beers)
+      raise ArgumentError, 'Empty order' if beers.empty?
+
+      orders, tray = [], []
+
+      beers.flatten!
+
+      beers.each do |beer|
+        counter.rpush(@pub_name, beer)
+        orders << order_for(beer)
+      end
+
+      timer = EM.add_timer(@timeout) do
+        foo = counter.unsubscribe
+      end
+
+      counter.subscribe(*orders) do |on|
+        on.message do |order, beer|
+          counter.unsubscribe(order)
+          if block_given?
+            yield beer
+          else
+            tray << beer
+          end
+        end
+      end
+
+      EM.cancel_timer(timer)
+      block_given? ? nil : tray
+    end
+  end
+end

data/lib/pub/version.rb

@@ -1,3 +1,3 @@
-module Pub
-  VERSION = "0.0.1"
+class Pub
+  VERSION = "0.1.0"
 end

data/pub.gemspec

@@ -5,30 +5,28 @@ require "pub/version"
 Gem::Specification.new do |s|
   s.name        = "pub"
   s.version     = Pub::VERSION
-  s.authors     = ["Hakan Ensari"]
-  s.email       = ["hakan.ensari@papercavalier.com"]
-  s.homepage    = "http://rubygems.com/papercavalier/pub"
-  s.summary     = %q{A Redis-backed pub/sub messaging system that processes queues}
-  s.description = %q{Pub is a Redis-backed pub/sub messaging system that process queues.}
-
-  s.rubyforge_project = "pub"
+  s.authors     = ["Paper Cavalier"]
+  s.email       = "code@papercavalier.com"
+  s.homepage    = "http://github.com/papercavalier/pub"
+  s.summary     = "A Redis-backed pub or processing queue with a non-blocking bar counter"
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.test_files    = `git ls-files -- {spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
-    {
-    "eventmachine"        => "~> 1.0.0.beta.3",
+  s.required_ruby_version = ">= 1.9"
+
+  {
     "em-synchrony"        => "~> 0.3.0.beta.1",
     "hiredis"             => "~> 0.3.2",
-    "redis"               => "~> 2.2.0"
+    "redis"               => "~> 2.2.1"
   }.each do |lib, version|
     s.add_runtime_dependency lib, version
   end
 
   {
-    "rspec"               => "~> 2.6.0"
+    "cucumber"            => "~> 1.0",
+    "rspec"               => "~> 2.6",
   }.each do |lib, version|
     s.add_development_dependency lib, version
   end

data/spec/pub/bartender_spec.rb

@@ -0,0 +1,47 @@
+require "spec_helper"
+
+class Pub
+  describe Bartender do
+    let(:pub)       { Pub.new("Ye Olde Rubies") }
+    let(:bartender) { pub.new_bartender }
+    let(:counter)   { double("Counter").as_null_object }
+
+    before do
+      bartender.stub!(:counter).and_return(counter)
+    end
+
+    describe "#take_order" do
+      before do
+        counter.stub!(:lpop).and_return(Time.now)
+      end
+
+      context "when not passed a number" do
+        it "pops one order from the queue" do
+          orders = bartender.take_orders
+          orders.count.should eql 1
+        end
+      end
+
+      context "when passed a number" do
+        it "returns that many orders from the queue" do
+          orders = bartender.take_orders(3)
+          orders.count.should eql 3
+        end
+      end
+    end
+
+    describe "#serve" do
+      let(:beer) { "Guinness" }
+      after      { bartender.serve(beer) { beer } }
+
+      it "removes duplicate instances of the beer from the queue" do
+        counter.should_receive(:lrem).with(pub.name, 0, beer)
+      end
+
+      it "publishes the order" do
+        order = bartender.send(:order_for, beer)
+        counter.should_receive(:publish).with(order, beer)
+      end
+    end
+  end
+end

data/spec/pub/patron_spec.rb

@@ -0,0 +1,66 @@
+require "spec_helper"
+
+class Pub
+  describe Patron do
+    let(:pub)     { Pub.new("Ye Olde Rubies") }
+    let(:patron)  { pub.new_patron }
+    let(:counter) { double("Counter").as_null_object }
+
+    before do
+      patron.stub!(:counter).and_return(counter)
+    end
+
+    describe "#order" do
+      context "when ordering a beer" do
+        let(:beer) { "Guinness" }
+        after      { patron.order(beer) }
+
+        it "queues the beer at the counter" do
+          counter.should_receive(:rpush).with(pub.name, beer)
+        end
+
+        it "subscribes to the order" do
+          order = patron.send(:order_for, beer)
+          counter.should_receive(:subscribe).with(order)
+        end
+      end
+
+      context "when ordering two beers" do
+        let(:beers) { ["Guinness", "Stella"] }
+        after       { patron.order(*beers) }
+
+        it "queues the beers at the counter" do
+          beers.each do |beer|
+            counter.should_receive(:rpush).with(pub.name, beer)
+          end
+        end
+
+        it "subscribes to the orders" do
+          orders = beers.map do |beer|
+            patron.send(:order_for, beer)
+          end
+          counter.should_receive(:subscribe).with(*orders)
+        end
+      end
+
+      context "when ordering an array of beers" do
+        let(:beers) { ["Guinness", "Stella"] }
+        after       { patron.order(beers) }
+
+        it "splats the array and queues the beers at the counter" do
+          beers.each do |beer|
+            counter.should_receive(:rpush).with(pub.name, beer)
+          end
+        end
+      end
+
+      context "when patron does not know what he or she wants" do
+        it "raises an error" do
+          expect do
+            patron.order
+          end.to raise_error ArgumentError
+        end
+      end
+    end
+  end
+end

data/spec/pub_spec.rb

@@ -0,0 +1,28 @@
+require "spec_helper"
+
+describe Pub do
+  let(:pub) { Pub.new("Ye Olde Rubies") }
+
+  describe ".counter" do
+    it "returns a Redis connection" do
+      Pub.counter.should be_a Redis
+    end
+  end
+
+  describe "#new_bartender" do
+    it "returns a new bartender" do
+      pub.new_bartender.should be_a Pub::Bartender
+    end
+  end
+
+  describe "#new_patron" do
+    it "returns a new patron" do
+      pub.new_patron.should be_a Pub::Patron
+    end
+
+    it "optionally sets the timeout of the patron" do
+      patron = pub.new_patron(10)
+      patron.instance_variable_get(:@timeout).should eql 10
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,7 +1,15 @@
-require 'rubygems'
-require 'bundler/setup'
-require 'rspec'
+require "rubygems"
+require "bundler/setup"
+require "rspec"
 
-require File.expand_path('../../lib/pub', __FILE__)
+require File.expand_path("../../lib/pub", __FILE__)
 
-Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+RSpec.configure do |c|
+  c.around(:each) do |example|
+    EM.synchrony do
+      Pub.counter.flushall
+      example.run
+      EM.stop
+    end
+  end
+end

metadata

@@ -4,21 +4,21 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
-- Hakan Ensari
+- Paper Cavalier
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-06-08 00:00:00 +01:00
+date: 2011-06-30 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: eventmachine
+  name: em-synchrony
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -26,16 +26,16 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version 
         segments: 
-        - 1
         - 0
+        - 3
         - 0
         - beta
-        - 3
-        version: 1.0.0.beta.3
+        - 1
+        version: 0.3.0.beta.1
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: em-synchrony
+  name: hiredis
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -45,14 +45,12 @@ dependencies:
         segments: 
         - 0
         - 3
-        - 0
-        - beta
-        - 1
-        version: 0.3.0.beta.1
+        - 2
+        version: 0.3.2
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: hiredis
+  name: redis
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
@@ -60,14 +58,14 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version 
         segments: 
-        - 0
-        - 3
         - 2
-        version: 0.3.2
+        - 2
+        - 1
+        version: 2.2.1
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: redis
+  name: cucumber
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -75,11 +73,10 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version 
         segments: 
-        - 2
-        - 2
+        - 1
         - 0
-        version: 2.2.0
-  type: :runtime
+        version: "1.0"
+  type: :development
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: rspec
@@ -92,13 +89,11 @@ dependencies:
         segments: 
         - 2
         - 6
-        - 0
-        version: 2.6.0
+        version: "2.6"
   type: :development
   version_requirements: *id005
-description: Pub is a Redis-backed pub/sub messaging system that process queues.
-email: 
-- hakan.ensari@papercavalier.com
+description: 
+email: code@papercavalier.com
 executables: []
 
 extensions: []
@@ -111,12 +106,23 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- features/README.md
+- features/order.feature
+- features/step_definitions/numeric_transforms.rb
+- features/step_definitions/pub_steps.rb
+- features/support/env.rb
 - lib/pub.rb
+- lib/pub/bartender.rb
+- lib/pub/helpers.rb
+- lib/pub/patron.rb
 - lib/pub/version.rb
 - pub.gemspec
+- spec/pub/bartender_spec.rb
+- spec/pub/patron_spec.rb
+- spec/pub_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
-homepage: http://rubygems.com/papercavalier/pub
+homepage: http://github.com/papercavalier/pub
 licenses: []
 
 post_install_message: 
@@ -130,8 +136,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version 
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 9
+      version: "1.9"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
@@ -142,10 +149,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: "0"
 requirements: []
 
-rubyforge_project: pub
+rubyforge_project: 
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: A Redis-backed pub/sub messaging system that processes queues
+summary: A Redis-backed pub or processing queue with a non-blocking bar counter
 test_files: 
+- features/README.md
+- features/order.feature
+- features/step_definitions/numeric_transforms.rb
+- features/step_definitions/pub_steps.rb
+- features/support/env.rb
+- spec/pub/bartender_spec.rb
+- spec/pub/patron_spec.rb
+- spec/pub_spec.rb
 - spec/spec_helper.rb