event_stream 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4eb7f64821b9716f61474ae0fbeb45933544a449
+  data.tar.gz: 7b2dff88c4593999dffab1121a20cda3bafaaedf
+SHA512:
+  metadata.gz: 63b1d01de337fcedd119ec1b89435bb0153c886297ef1958420cc6c395571333466781876a71360233113eee119a0ee8d63c9d7417904b492d3c98dfff822970
+  data.tar.gz: 81f0a46e4dcf4e4dca4637d8c5b0f78cfcae07ac0e0bb5b90e26de4d91a9590f606c00b25005ad1b18a364822abdf5907c7a1f52a646806c0108dbd10e911e03

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in event_stream.gemspec
+gemspec
+
+group :development, :test do
+  gem "pry"
+  gem "awesome_print"
+  gem 'm', :git => 'git@github.com:ANorwell/m.git', :branch => 'minitest_5'
+end
+
+group :test do
+  gem 'minitest_should', :git => 'git@github.com:citrus/minitest_should.git'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Datto
+
+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,99 @@
+# EventStream
+
+A minimal library for synchronously publishing and subscribing to events.
+
+## Usage
+
+Create an event subscription:
+
+```ruby
+EventStream.subscribe(:my_event) do |event|
+  log("#{event.name}, #{event.description}")
+end
+```
+Then fire an event:
+
+```ruby
+EventStream.publish(:my_event, :description => "An example event.")
+```
+
+An event is just an OpenStruct with a name and a bundle of other attributes, so the use of `:description` here is arbitrary.
+
+Events can be subscribed to by name, as above, but many other ways are supported:
+
+```ruby
+# Subscribe to all events
+EventStream.subscribe { |e| ... }
+
+# Subscribe to events with a given name
+EventStream.subscribe(:my_event) { |e| ... }
+
+# Subscribe to events based on a name regex
+EventStream.subscribe(/my/) { |e| ... }
+
+# Subscribe to events based on their attributes
+EventStream.subscribe(:user_id => 1) { |e| ... }
+
+# Subscribe to events based on an arbitrary filter
+filter = lambda { |e| e.size > 3 }
+EventStream.subscribe(filter) { |e| ... }
+```
+
+### Event Streams
+
+If you wish, you may create more than one event stream:
+
+```ruby
+stream = EventStream::Stream.new
+stream.subscribe(...) { |e| ... }
+stream.publish(...)
+```
+
+### Subscriber DSL
+
+It's sometimes useful to separate the definition of a subscriber action
+from the registration of the subscriber. The `SubscriberDSL` module
+provides a way to do this.
+
+Define a subscriber by mixing in the module:
+
+```ruby
+class MySubscriber
+  include EventStream::SubscriberDSL
+
+  # Which event_stream to use. If not specified, the default will be used.
+  event_stream EventStream.default_stream
+
+  # Sets up a subscriber using a block
+  on(:my_event) { |event| puts event.name }
+end
+```
+
+The definition of this class does NOT subscribe to any events. To subscribe
+to the :my_event event, it is necessary to call `MySubscriber.subscribe`.
+
+It is possible to use multiple `on` statements in a single class.
+`MySubscriber.subscribe` will register all subscriptions.
+
+## Application Testing
+
+event_stream includes a test_helper module that provides some assertions, like `assert_event_published`. To use:
+1. `require 'event_stream/test_helper'`
+2. Call `EventStream::Assertions.setup_test_subscription` in the setup block of your tests
+3. Include the `EventStream::Assertions` module where needed
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'event_stream', :git => 'git@github.com:backupify/event_stream.git'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install event_stream

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/event_stream/**/*_test.rb'
+  t.libs.push 'test'
+end
+
+task :default => :test

data/event_stream.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'event_stream/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "event_stream"
+  spec.version       = EventStream::VERSION
+  spec.authors       = ["Arron Norwell"]
+  spec.email         = ["anorwell@datto.com"]
+  spec.summary       = %q{A minimal library for synchronously publishing and subscribing to events.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "minitest-reporters"
+
+  spec.add_dependency 'activesupport'
+end

data/lib/event_stream.rb

@@ -0,0 +1,79 @@
+require 'ostruct'
+require_relative 'event_stream/subscriber_dsl'
+
+module EventStream
+  class << self
+    extend Forwardable
+
+    # The default event stream
+    # @return [Stream]
+    def default_stream
+      @default_stream ||= Stream.new
+    end
+
+    def_delegators :default_stream, :publish, :subscribe, :clear_subscribers
+  end
+
+  # An Event. Each event is an OpenStruct with a name as well as any number of other optional fields.
+  # @!attribute name
+  #   @return [Symbol]
+  class Event < OpenStruct; end
+
+  class Stream
+    def initialize
+      @subscribers = []
+    end
+
+    # Publishes an event to this event stream
+    # @param name [Symbol] name of this event
+    # @param attrs [Hash] optional attributes representing this event
+    def publish(name, attrs = {})
+      e = Event.new(attrs.merge(:name => name))
+      @subscribers.each { |l| l.consume(e) }
+    end
+
+    # Registers a subscriber to this event stream.
+    # @param filter [Object] Filters which events this subscriber will consume.
+    # If a string or regexp is provided, these will be matched against the event name.
+    # A hash will be matched against the attributes of the event.
+    # Or, any arbitrary predicate on events may be provided.
+    # @yield [Event] action to perform when the event occurs.
+    def subscribe(filter = nil, &action)
+      add_subscriber(Subscriber.create(filter, &action))
+    end
+
+    # Clears all subscribers from this event stream.
+    def clear_subscribers
+      @subscribers = []
+    end
+
+    # Returns all subscribers for this stream
+    # @return [Array<EventStream::Subscriber]
+    def subscribers
+      @subscribers
+    end
+
+    # Adds a subscriber to this stream
+    # @param [EventStream::Subscriber]
+    def add_subscriber(subscriber)
+      @subscribers << subscriber
+    end
+  end
+
+  class Subscriber < Struct.new(:filter, :action)
+    def self.create(filter = nil, &action)
+      filter ||= lambda { |e| true }
+      filter_predicate = case filter
+                         when Symbol, String then lambda { |e| e.name.to_s == filter.to_s }
+                         when Regexp then lambda { |e| e.name =~ filter }
+                         when Hash then lambda { |e| filter.all? { |k,v| e[k] === v } }
+                         else filter
+                         end
+      new(filter_predicate, action)
+    end
+
+    def consume(event)
+      action.call(event) if filter.call(event)
+    end
+  end
+end

data/lib/event_stream/subscriber_dsl.rb

@@ -0,0 +1,49 @@
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+
+module EventStream
+  # Provides a DSL with which to create Subscribers.
+  # For example:
+  #
+  #    class MySubscriber
+  #      include EventStream::SubscriberDSL
+  #
+  #      # Which event_stream to use. If not specified, the default will be used.
+  #      event_stream EventStream.default_stream
+  #
+  #      # Sets up a subscriber using a block
+  #      on(:my_other_event) { |event| puts event.name }
+  #    end
+  #
+  # Note that this does NOT register subscribers. To register subscribers, call:
+  #
+  #     MySubscriber.subscribe
+  #
+  # This registers all subscribers to the provided event_stream (or to the default).
+  #
+  module SubscriberDSL
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_event_subscribers
+      class_attribute :_event_stream
+      attr_reader :event
+      self._event_subscribers = []
+      self._event_stream = EventStream.default_stream
+    end
+
+    module ClassMethods
+      def event_stream(event_stream)
+        self._event_stream = event_stream
+      end
+
+      def on(filter, &action)
+        self._event_subscribers << Subscriber.create(filter, &action)
+      end
+
+      def subscribe
+        _event_subscribers.each { |subscriber| _event_stream.add_subscriber(subscriber) }
+      end
+    end
+  end
+end

data/lib/event_stream/test_helper.rb

@@ -0,0 +1,34 @@
+module EventStream
+
+  module TestEventStream
+    class << self
+      attr_accessor :events
+    end
+  end
+
+  module Assertions
+    def self.setup_test_subscription
+      TestEventStream.events = []
+
+      EventStream.subscribe(//) do |event|
+        TestEventStream.events << event
+      end
+    end
+
+    def assert_event_matching(message = nil, &predicate)
+      if TestEventStream.events.nil?
+        raise "Call EventStream::TestHelper.setup prior to using event_stream test assertions!"
+      end
+
+      assert TestEventStream.events.any?(&predicate), "Event stream did not include a matching event: #{message}"
+    end
+
+    def assert_event_published(event_name)
+      assert_event_matching("No event with name #{event_name}") { |event| event.name == event_name }
+    end
+
+    def find_published_event(&predicate)
+      TestEventStream.events.find(&predicate)
+    end
+  end
+end

data/lib/event_stream/version.rb

@@ -0,0 +1,3 @@
+module EventStream
+  VERSION = "0.2.0"
+end

data/test/event_stream/event_stream_test.rb

@@ -0,0 +1,54 @@
+require_relative '../test_helper'
+
+class EventStreamTest < Minitest::Should::TestCase
+
+  def pub_sub(name, attrs = {}, filter = nil)
+    event = nil
+    EventStream.subscribe(filter) do |e|
+      event = e
+    end
+    EventStream.publish(name, attrs)
+    event
+  end
+
+  teardown do
+    EventStream.default_stream.clear_subscribers
+  end
+
+  context 'an event stream' do
+    should 'publish an event and allow a subscriber to consume it' do
+      event = pub_sub(:test)
+      assert event
+      assert_equal :test, event.name
+    end
+
+    should 'expose all event attributes to the subscriber' do
+      event = pub_sub(:test, :x => 1)
+      assert_equal 1, event.x
+    end
+
+    context 'filtering events' do
+      should 'allow subscription to event names' do
+        assert pub_sub(:test, {}, :test)
+        refute pub_sub(:test, {}, :other_name)
+      end
+
+      should 'allow subscription to event names by regex' do
+        assert pub_sub(:test_event, {}, /test/)
+        refute pub_sub(:test_event, {}, /no_match/)
+      end
+
+      should 'allow subscription by event attributes' do
+        assert pub_sub(:test, { :x => 1, :y => :attr}, :y => :attr)
+        refute pub_sub(:test, { :x => 1, :y => :other}, :y => :attr)
+      end
+
+      should 'allow subscription via arbitrary predicate' do
+        predicate = lambda { |e| e.x > 1 }
+        assert pub_sub(:test, { :x => 2, :y => :attr}, predicate)
+        refute pub_sub(:test, { :x => 1, :y => :attr}, predicate)
+      end
+
+    end
+  end
+end

data/test/event_stream/subscriber_dsl_test.rb

@@ -0,0 +1,54 @@
+require_relative '../test_helper'
+
+module EventStream
+  class SubscriberDSLTest < Minitest::Should::TestCase
+
+    class MySubscriber
+      include SubscriberDSL
+
+      class << self
+        attr_accessor :events
+      end
+
+      on(:event) { |event| self.events << event  }
+
+      def a_method(event)
+        self.class.events << event
+      end
+    end
+
+    context 'The Subscriber DSL' do
+      setup do
+        MySubscriber.events = []
+      end
+
+      context 'the default stream' do
+        setup do
+          EventStream.clear_subscribers
+          MySubscriber.event_stream(EventStream.default_stream)
+          MySubscriber.subscribe
+        end
+
+        should 'handle a published event' do
+          EventStream.publish(:event, test: true)
+          assert_equal 1, MySubscriber.events.count
+        end
+      end
+
+      context 'other event streams' do
+        setup do
+          @stream = EventStream::Stream.new
+          MySubscriber.event_stream(@stream)
+
+          @stream.clear_subscribers
+          MySubscriber.subscribe
+        end
+
+        should 'handle a published event' do
+          @stream.publish(:event, test: true)
+          assert_equal 1, MySubscriber.events.count
+        end
+      end
+    end
+  end
+end

data/test/event_stream/test_helper_test.rb

@@ -0,0 +1,42 @@
+require_relative '../test_helper'
+require 'event_stream/test_helper'
+
+module EventStream
+  class TestHelperTest < Minitest::Should::TestCase
+    include Assertions
+
+    setup do
+      EventStream.clear_subscribers
+      Assertions.setup_test_subscription
+    end
+
+    context '#assert_event_published' do
+      should 'raise no error when an event has been published' do
+        EventStream.publish(:test_event)
+        assert_event_published(:test_event)
+      end
+
+      should 'raise an error if the event has not been published' do
+        assert_raises(Minitest::Assertion) { assert_event_published(:test_event) }
+      end
+    end
+
+    context 'registering the test subscription' do
+      should 'not register multiple subscriptions' do
+        assert_equal 1, EventStream.default_stream.subscribers.length
+      end
+    end
+
+    context '#find_published_event' do
+      should 'find an event if one is present' do
+        EventStream.publish(:test_event, key: :val)
+        assert find_published_event { |evt| evt.key == :val }
+      end
+
+      should 'not find an event if it does not match' do
+        EventStream.publish(:test_event, key: :other)
+        refute find_published_event { |evt| evt.key == :val }
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'pry'
+require 'minitest/autorun'
+require 'minitest/should'
+
+
+require 'event_stream'
+
+class Minitest::Should::TestCase
+  def self.xshould(*args)
+    puts "Disabled test: #{args}"
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: event_stream
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Arron Norwell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- anorwell@datto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- event_stream.gemspec
+- lib/event_stream.rb
+- lib/event_stream/subscriber_dsl.rb
+- lib/event_stream/test_helper.rb
+- lib/event_stream/version.rb
+- test/event_stream/event_stream_test.rb
+- test/event_stream/subscriber_dsl_test.rb
+- test/event_stream/test_helper_test.rb
+- test/test_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A minimal library for synchronously publishing and subscribing to events.
+test_files:
+- test/event_stream/event_stream_test.rb
+- test/event_stream/subscriber_dsl_test.rb
+- test/event_stream/test_helper_test.rb
+- test/test_helper.rb
+has_rdoc: