tavern 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tavern.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Darcy Laycock
+
+MIT License
+
+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/README.md

@@ -0,0 +1,29 @@
+# Tavern
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'tavern'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tavern
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,17 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+task :default => :spec
+
+begin
+  require 'ci/reporter/rake/rspec'
+rescue LoadError
+end
+
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new :spec

data/lib/tavern/hub.rb

@@ -0,0 +1,117 @@
+require 'tavern/subscription'
+require 'tavern/subscriptions'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/blank'
+
+module Tavern
+
+  class << self
+
+    # Gets the current application wide hub, initializing
+    # a new one if it hasn't been set yet.
+    # @return [Hub] the subscription hub
+    def hub
+      @hub ||= Hub.new.tap { |h| h.primary = true }
+    end
+
+    def hub=(value)
+      old_hub = @hub
+      @hub = value.presence
+      if old_hub != @hub
+        old_hub.primary = false if old_hub
+        @hub.primary    = true  if @hub
+      end
+    end
+
+    # We delegate the subscription management methods to the default hub.
+    # Note: This does not replace having an application-wide hub which is still
+    # a good idea.
+    delegate :subscribe, :unsubscribe, :publish, :to => :hub
+
+  end
+
+  # Implements a simplified Pub / Sub hub for in-application notifications.
+  # Used inside smeghead as a general replacement for observers and a way
+  # for items to hook into events.
+  class Hub
+
+    attr_reader :subscriptions
+
+    # Initializes the given hub with an empty set of subscriptions.
+    def initialize
+      @subscriptions = Subscriptions.new
+      @primary       = false
+    end
+
+    # Subscribes to a given path string and either a proc callback or
+    # any object responding to #call.
+    # @param [String] path the subscription path
+    # @param [#call] object if present, the callback to invoke
+    # @param [Proc] blk the block to use for the callback (if the object is nil)
+    # @example Subscribing with a block
+    #   hub.subscribe 'hello:world' do |ctx|
+    #     puts "Context is #{ctx.inspect}"
+    #   end
+    # @example Subscribing with an object
+    #   hub.subscribe 'hello:world', MyCallableClass
+    def subscribe(path, object = nil, &blk)
+      if object and not object.respond_to?(:call)
+        raise ArgumentError, "you provided an object as an argument but it doesn't respond to #call"
+      end
+      subscription = Subscription.new(path, (object || blk))
+      level        = subscriptions.sublevel_at subscription.to_subscribe_keys
+      level.add subscription
+      subscription
+    end
+
+    # Deletes the given subscription from this pub sub hub.
+    # @param [Subscription] subscription the subscription to delete
+    # @return [Subscription] the deleted subscription
+    def unsubscribe(subscription)
+      return if subscription.blank?
+      level = subscriptions.sublevel_at subscription.to_subscribe_keys
+      level.delete subscription
+      subscription
+    end
+
+    # Publishes a message to the given path and with a given hash context.
+    # @param [String] path the pubsub path
+    # @param [Hash{Symbol => Object}] context the message context
+    # @return [true,false] whether or not all callbacks executed successfully.
+    # @example Publishing a message
+    #   hub.publish 'hello:world', :hello => 'world'
+    def publish(path, context = {})
+      path_parts = path.split(":")
+      context = merge_path_context path_parts, context
+      # Actually handle publishing the subscription
+      subscriptions.call(context.merge(:path_parts => path_parts, :full_path => path)) != false
+    end
+
+    def primary?
+      !!@primary
+    end
+
+    def primary=(value)
+      value = !!value
+      if value != @value
+        @value = value
+        ActiveSupport.run_load_hooks :smeg_head_hub, self
+      end
+    end
+
+    private
+
+    def merge_path_context(path_parts, context)
+      if context.has_key?(:path_keys)
+        context   = context.dup
+        path_keys = Array(context.delete(:path_keys))
+        path_keys.each_with_index do |part, idx|
+          next if part.blank?
+          context[part.to_sym] = path_parts[idx]
+        end
+      end
+      context
+    end
+
+  end
+end

data/lib/tavern/mock_hub.rb

@@ -0,0 +1,54 @@
+require 'tavern/hub'
+
+module Tavern
+  # A simple hub you can use to completely disable the pub / sub process
+  # but still record what happens.
+  class MockHub < Hub
+
+    class Publication < Struct.new(:path, :context)
+    end
+
+    attr_reader :subscriptions, :unsubscriptions, :publications
+
+    def initialize
+      super
+      @subscriptions, @unsubscriptions, @publications = [], [], []
+    end
+
+    # Subscribes to a given path string and either a proc callback or
+    # any object responding to #call.
+    # @param [String] path the subscription path
+    # @param [#call] object if present, the callback to invoke
+    # @param [Proc] blk the block to use for the callback (if the object is nil)
+    # @example Subscribing with a block
+    #   hub.subscribe 'hello:world' do |ctx|
+    #     puts "Context is #{ctx.inspect}"
+    #   end
+    # @example Subscribing with an object
+    #   hub.subscribe 'hello:world', MyCallableClass
+    def subscribe(path, object = nil, &blk)
+      subscription = Subscription.new(path, (object || blk))
+      subscriptions << subscription
+      subscription
+    end
+
+    # Deletes the given subscription from this pub sub hub.
+    # @param [Subscription] subscription the subscription to delete
+    # @return [Subscription] the deleted subscription
+    def unsubscribe(subscription)
+      return if subscription.blank?
+      subscriptions.delete subscription
+      subscription
+    end
+
+    # Publishes a message to the given path and with a given hash context.
+    # @param [String] path the pubsub path
+    # @param [Hash{Symbol => Object}] context the message context
+    # @example Publishing a message
+    #   hub.publish 'hello:world', :hello => 'world'
+    def publish(path, context = {})
+      publications << Publication.new(path, context)
+    end
+
+  end
+end

data/lib/tavern/subscription.rb

@@ -0,0 +1,34 @@
+module Tavern
+  # A general subscription in a given hub, including a name and a given callback
+  # block. As part of this, it provides tools to make it easy to handle the subscriptions.
+  class Subscription
+
+    attr_reader :name, :callback
+
+    # Initializes a new subscription with a given name and callback.
+    # @param [String] name the name of this subscription
+    # @param [#call] callback the callback for this subscription
+    def initialize(name, callback)
+      @name            = name.to_s
+      @callback        = callback
+      @_subscribe_keys = @name.to_s.split(":")
+    end
+
+    # Returns the list of subscription sublevel keys.
+    # @return [Array<String>] the list of sublevel keys
+    def to_subscribe_keys
+      @_subscribe_keys
+    end
+
+    # Invokes the callback, returning whatever it returns.
+    # @param [Hash] context the callback context.
+    def call(context)
+      @callback.call context
+    end
+
+    def to_proc
+      proc { |ctx| call ctx }
+    end
+
+  end
+end

data/lib/tavern/subscriptions.rb

@@ -0,0 +1,79 @@
+module Tavern
+  # Tavern::Subscriptions implements a simple tree-like structure for handling subscriptions, facilitating
+  # the efficient depth-first processing of callbacks based on a given path.
+  #
+  # Each level of the tree is composed of some callbacks as well as a set of sublevels, each represented by
+  # part of a subscription namespace. Namely, given a key of "a:b:c", there will be four levels:
+  #
+  # 1. The root level - Currently, nothing subscribes to this level
+  # 2. The "a" level - this is nested under the root level.
+  # 3. The "b" level - this is nested under the "a" level.
+  # 4. The "c" level - this is nested under the "b" level.
+  #
+  # When an event is published to "a:b:c", the top level Subscriptions instance will recursively ``#call`` the
+  # child levels, breaking if at any point a subscription returns false. Ideally, this means that for a normal
+  # event, we will get events (if present) invoked on all four levels, allowing a nice and structured event
+  # dispatch.
+  class Subscriptions
+
+    # Creates a new subscription with an empty list of subscriptions and an empty subkeys mapping.
+    def initialize
+      @subscriptions = []
+      @subkeys    = {}
+    end
+
+    # Given a specified context, calls all nested matching subcontexts and then invokes the
+    # callbacks on this level, breaking if it encounters false (like terminators in AS callbacks).
+    #
+    # This means that if your subscription returns false, it will halt further callbacks. Also,
+    # It also means that dispatching events are depth first based on the key. E.g., given a callback
+    # key of "a:b:c", the callbacks for "a:b:c" will be called first followed by those for "a:b" and "a".
+    #
+    # @param [Hash] context the given context for this publish call
+    # @option context [Array<String>] :path_parts an array of the current children keys to dispatch on
+    def call(context = {})
+      path_parts  = context[:path_parts].dup
+      # Call the sublevel, breaking when a value returns false
+      if path_parts.any? and (subkey = @subkeys[path_parts.shift])
+        result = subkey.call context.merge(:path_parts => path_parts)
+        return result if result == false
+      end
+      # Iterate over the subscriptions, breaking when one of them returns false
+      @subscriptions.each do |subscription|
+        return false if subscription.call(context) == false
+      end
+      # Otherwise, return nil
+      true
+    end
+
+    # Adds a new subscription to this subscriptions list.
+    # @param [Subscription] subscription the new subscription to add
+    def add(subscription)
+      @subscriptions << subscription
+    end
+
+    # Removes a given subscription from this level.
+    # @param [Subscription] subscription the old subscription to remove
+    def delete(subscription)
+      @subscriptions.delete subscription
+    end
+
+    # Gets the sublevel with the given key, initializing a new
+    # sublevel if it is as of yet unknown.
+    # @param [String] key the key of the given sublevel
+    # @return [Subscriptions] the returned subscription level
+    def sublevel(key)
+      @subkeys[key] ||= Subscriptions.new
+    end
+
+    # Given a list of subkeys, will return the association sublevel.
+    # @param [Array<String>] parts the list of path-parts to reach the desired sublevel.
+    # @return [Subscriptions] the given sublevel subscriptions object.
+    def sublevel_at(*parts)
+      parts.flatten.inject(self) do |level, part|
+        level.sublevel part
+      end
+    end
+
+  end
+end

data/lib/tavern/version.rb

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

data/lib/tavern.rb

@@ -0,0 +1,6 @@
+require 'tavern/version'
+
+module Tavern
+  require 'tavern/hub'
+  require 'tavern/mock_hub'
+end

data/spec/hub_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+
+describe Tavern::Hub do
+
+  let(:hub) { Tavern::Hub.new }
+
+  let(:subscriber_klass) do
+    Class.new do
+
+      def published
+        @published ||= []
+      end
+
+      def call(ctx)
+        published << ctx
+      end
+
+    end
+  end
+
+  let(:ctx_from_proc) { [] }
+
+  let(:subscriber_proc) do
+    proc { |ctx| ctx_from_proc << ctx }
+  end
+
+  describe 'the primary hub' do
+
+    it 'should let you query if something is the primary hub'
+
+    it 'should run the load hook when the hub is changed'
+
+    it 'should unset it when changing the hub'
+
+    it 'should set it to primary when setting it to the hub value'
+
+    it 'always set the default to be primary'
+
+  end
+
+  describe '#subscribe' do
+
+    it 'should let you subscribe to a top level item'
+
+    it 'should let you subscribe to a nested item'
+
+    it 'should let you pass an object'
+
+    it 'should let you pass a block'
+
+    it 'should return a subscription'
+
+    it 'should automatically subscribe to lower level nested events'
+
+    it 'should raise an error when subscribing with an object that does not provide call'
+
+  end
+
+  describe '#unsubscribe' do
+
+    it 'should remove an object from the subscription pool'
+
+    it 'should return the subscription'
+
+    it 'should do nothing with a blank item'
+
+  end
+
+  describe '#publish' do
+
+    let(:nested_a)    { subscriber_klass.new }
+    let(:nested_b)    { subscriber_klass.new }
+    let(:nested_c)    { subscriber_klass.new }
+    let(:top_level_a) { subscriber_klass.new }
+    let(:top_level_b) { subscriber_klass.new }
+
+    before :each do
+      hub.subscribe 'hello',       top_level_a
+      hub.subscribe 'hello:world', nested_a
+      hub.subscribe 'foo',         top_level_b
+      hub.subscribe 'foo:bar',     nested_b
+    end
+
+    it 'should add the path parts for a top level call' do
+      mock(top_level_a).call(hash_including(:path_parts => %w()))
+      hub.publish 'hello', {}
+    end
+
+    it 'should add the path parts for a nested call' do
+      mock(top_level_a).call(hash_including(:path_parts => %w(world)))
+      mock(nested_a).call(hash_including(:path_parts => %w()))
+      hub.publish 'hello:world', {}
+    end
+
+    it 'should unpack path keys if provided' do
+      mock(top_level_a).call(hash_including(:model_name => 'world'))
+      mock(nested_a).call(hash_including(:model_name => 'world'))
+      hub.publish 'hello:world', :path_keys => [nil, :model_name]
+    end
+
+    it 'should add the full path to the publish' do
+      mock(top_level_a).call(hash_including(:full_path => 'hello:world'))
+      mock(nested_a).call(hash_including(:full_path => 'hello:world'))
+      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'
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rspec'
+require 'rr'
+
+require 'tavern'
+
+RSpec.configure do |config|
+  config.mock_with :rr
+end

data/tavern.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/tavern/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Darcy Laycock"]
+  gem.email         = ["sutto@sutto.net"]
+  gem.description   = %q{Tavern implements simple pub / sub systems for Rails applications with a simple, extendable architecture and minimal api surface area.}
+  gem.summary       = %q{Simple pubsub for Ruby apps.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "tavern"
+  gem.require_paths = ["lib"]
+  gem.version       = Tavern::VERSION
+
+  gem.add_dependency 'activesupport', '~> 3.0'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rr'
+  gem.add_development_dependency 'rspec', '~> 2.0'
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: tavern
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Darcy Laycock
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Tavern implements simple pub / sub systems for Rails applications with
+  a simple, extendable architecture and minimal api surface area.
+email:
+- sutto@sutto.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/tavern.rb
+- lib/tavern/hub.rb
+- lib/tavern/mock_hub.rb
+- lib/tavern/subscription.rb
+- lib/tavern/subscriptions.rb
+- lib/tavern/version.rb
+- spec/hub_spec.rb
+- spec/spec_helper.rb
+- tavern.gemspec
+homepage: ''
+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.21
+signing_key: 
+specification_version: 3
+summary: Simple pubsub for Ruby apps.
+test_files:
+- spec/hub_spec.rb
+- spec/spec_helper.rb