tavern 0.0.1 → 1.0.0

data/README.md

@@ -1,6 +1,9 @@
 # Tavern
 
-TODO: Write a gem description
+Tavern is a simple implementation of Pub / Sub for Ruby applications, allowing one
+to subscribe to topics (named by a:b:c) and to then publish events. It's designed
+to have a minimal surface area for the api to make it simple to integrate into other
+systems (e.g. so you can publish events over a network).
 
 ## Installation
 
@@ -18,7 +21,27 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+
+The core of Tavern is a `Tavern::Hub`, a default one which can be accessed at `Tavern.hub`.
+
+The core methods on this object (and any new Taver Hub) are:
+
+* `hub.subscribe(topic, callable = nil, &block)` - Creates a subscription for the given topic
+  using either a callable object or a block. Will return the instance of the subscription. Note
+  that this will also match any child notifications - e.g. publishing `a:b:c` will match subscriptions
+  for `a:b` and `a`. The callable should take one argument which includes an environment merged with
+  some extra details.
+* `hub.publish(topic, context = {})` - Publishes an event with a given name, including the specified
+  context optionally passed into the callable. Topics should be of the form `a:b:c` with no limit on items.
+  Will return the full published metadata.
+* `hub.unsubscribe(subscription)` - Given a return from `hub.subscribe`, will unsubscribe it and prevent
+  it from receiving any new messages.
+
+The idea behind this decoupled architecture is that it doesn't matter how the middle layer is implemented,
+you can just publish and receive messages with no worries. At the moment, subscriptions happen in app.
+
+For conveinience sake, we also proxy `subscribe` and `publish` on the `Tavern` object to the default hub
+at `Tavern.hub`.
 
 ## Contributing
 

data/lib/tavern/hub.rb

@@ -2,6 +2,7 @@ require 'tavern/subscription'
 require 'tavern/subscriptions'
 require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/object/blank'
+require 'active_support/lazy_load_hooks'
 
 module Tavern
 
@@ -93,9 +94,9 @@ module Tavern
 
     def primary=(value)
       value = !!value
-      if value != @value
-        @value = value
-        ActiveSupport.run_load_hooks :smeg_head_hub, self
+      if value != @primary
+        @primary = value
+        ActiveSupport.run_load_hooks :tavern_hub, self if @primary
       end
     end
 

data/lib/tavern/version.rb

@@ -1,3 +1,3 @@
 module Tavern
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/spec/hub_spec.rb

@@ -15,6 +15,10 @@ describe Tavern::Hub do
         published << ctx
       end
 
+      def times_called
+        published.size
+      end
+
     end
   end
 
@@ -26,43 +30,125 @@ describe Tavern::Hub do
 
   describe 'the primary hub' do
 
-    it 'should let you query if something is the primary hub'
+    after :each do
+      # Force a final reset
+      Tavern.hub = nil
+    end
 
-    it 'should run the load hook when the hub is changed'
+    it 'should let you query if something is the primary hub' do
+      hub.should respond_to(:primary?)
+      hub.should_not be_primary
+      Tavern.hub.should_not == hub
+      Tavern.hub.should be_primary
+    end
 
-    it 'should unset it when changing the hub'
+    it 'should run the load hook when the hub is changed' do
+      Tavern.hub # Force it to have loaded before hand.
+      called = 0
+      found_hub = nil
+      ActiveSupport.on_load(:tavern_hub) do |hub|
+        called += 1
+        found_hub = hub
+      end
+      called = 0
+      Tavern.hub = hub
+      called.should == 1
+      found_hub.should == hub
+    end
 
-    it 'should set it to primary when setting it to the hub value'
+    it 'should unset it when changing the hub' do
+      hub = Tavern.hub
+      hub.should be_primary
+      Tavern.hub = Tavern::Hub.new
+      hub.should_not be_primary
+    end
 
-    it 'always set the default to be primary'
+    it 'should set it to primary when setting it to the hub value' do
+      hub = Tavern::Hub.new
+      hub.should_not be_primary
+      Tavern.hub = hub
+      hub.should be_primary
+    end
+
+    it 'always set the default to be primary' do
+      # Force a recet to nil
+      Tavern.hub = nil
+      Tavern.hub.should be_primary
+    end
 
   end
 
   describe '#subscribe' do
 
-    it 'should let you subscribe to a top level item'
+    let(:tracker)  { Struct.new(:called).new(0) }
+    let(:callback) { lambda { |e| tracker.called += 1 } }
 
-    it 'should let you subscribe to a nested item'
-
-    it 'should let you pass an object'
+    it 'should let you subscribe to a top level item' do
+      hub.subscribe('x', &callback)
+      expect { hub.publish('x') }.to change tracker, :called
+      expect { hub.publish('x:y') }.to change tracker, :called
+      expect { hub.publish('x:y:z') }.to change tracker, :called
+    end
 
-    it 'should let you pass a block'
+    it 'should let you subscribe to a nested item' do
+      hub.subscribe('x:y:z', &callback)
+      expect { hub.publish('x:y:z') }.to change tracker, :called
+      expect { hub.publish('x:y') }.to_not change tracker, :called
+      expect { hub.publish('x') }.to_not change tracker, :called
+    end 
+
+    it 'should let you pass an object' do
+      callback = Struct.new(:tracker).new(tracker)
+      def callback.call(e); tracker.called += 1; end
+      hub.subscribe('x', callback)
+      expect { hub.publish('x') }.to change tracker, :called
+    end
 
-    it 'should return a subscription'
+    it 'should let you pass a block' do
+      hub.subscribe('x') { |e| tracker.called += 1 }
+      expect { hub.publish('x') }.to change tracker, :called
+    end
 
-    it 'should automatically subscribe to lower level nested events'
+    it 'should return a subscription' do
+      subscription = hub.subscribe('x', &callback)
+      subscription.should be_present
+      subscription.should be_a Tavern::Subscription
+    end
 
-    it 'should raise an error when subscribing with an object that does not provide call'
+    it 'should raise an error when subscribing with an object that does not provide call' do
+      expect do
+        hub.subscribe 'test', Object.new
+      end.to raise_error ArgumentError
+    end
 
   end
 
   describe '#unsubscribe' do
 
-    it 'should remove an object from the subscription pool'
+    let(:tracker) { Struct.new(:count, :calls).new(0, []) }
 
-    it 'should return the subscription'
+    let!(:subscription) do
+      t = tracker
+      hub.subscribe 'test' do |e|
+        t.count += 1
+        t.calls << e
+      end
+    end
 
-    it 'should do nothing with a blank item'
+    it 'should remove an object from the subscription pool' do
+      expect { hub.publish 'test' }.to change tracker, :count
+      hub.unsubscribe subscription
+      expect { hub.publish 'test' }.to_not change tracker, :count
+    end
+
+    it 'should return the subscription' do
+      hub.unsubscribe(subscription).should == subscription
+    end
+
+    it 'should do nothing with a blank item' do
+      hub.unsubscribe(nil).should be_nil
+      hub.unsubscribe('').should be_nil
+    end
 
   end
 
@@ -104,11 +190,12 @@ describe Tavern::Hub do
       hub.publish 'hello:world', {}
     end
 
-    it 'should notify all subscriptions under the path'
-
-    it 'should not notify unmatched subscriptions on a simple case'
-
-    it 'should not notify unmatched subscriptions on a nested case'
+    it 'should notify all subscriptions under the path' do
+      expect { hub.publish 'hello:world' }.to change top_level_a, :times_called
+      expect { hub.publish 'hello:world' }.to change nested_a, :times_called
+      expect { hub.publish 'foo' }.to change top_level_b, :times_called
+      expect { hub.publish 'foo' }.to_not change nested_b, :times_called
+    end
 
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tavern
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors: