chasqui 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 12b2617a27713b277443f047d9c67da2c7e18433
-  data.tar.gz: ee175fd077ade18393fccc35bbb2773ef23247dd
+  metadata.gz: c7b83716114be3ede50a3559cb742d776cdecd1f
+  data.tar.gz: df453dfaa501a592ddc6b3c650fcae09a9343123
 SHA512:
-  metadata.gz: eb442618ee0aef74d6898a7effeb6d28eebb164806013a8621b8f0b622e44935d85c27cc187c04acf54597af83f516aa9e7e3fbf44c1d417b2d477135031165e
-  data.tar.gz: 30fe8a703c8fd84b780c7cbde3c702aabd64ed93ad0be632a7deac93261636fe9199de4f092ebe41c0d9b0a85d9e282e22260008ab28b59fe00b51e1fc83d46f
+  metadata.gz: 91b367f3cd65f4bceffd73ebbdd6ef9d9af344741d797ebb8909d7b372c8246c99cee930b3b0a3cf09f316cbd48e84f11f82cfcd16f2251acdaa63c089fba7be
+  data.tar.gz: 420990d6feaa68f81d4db1ec6076a0c2b8fa2e5bd137dcf41a222d89734fa8e560e5d2e8cbb07a455d22a827e020c43c744f886e78a6f17e3f60c9e255f73f55

data/README.md

@@ -9,131 +9,111 @@ messaging pattern for service oriented architectures.
 Chasqui delivers messages to subscribers in a Resque-compatible format. If you are already
 using Resque and/or Sidekiq, Chasqui will make a wonderful companion to your architecture.
 
-## Why do you need Chasqui?
+## Installation
 
-* To reduce coupling between applications
-* To process, monitor, and retry messages idependent of request cycles
+Add this line to your application's Gemfile:
 
-## Design
+    gem 'chasqui'
 
-Chasqui is designed with reliability in mind.
-Failure is expected and planned for in the design.
+And then execute:
 
-Chasqui uses Redis to create persistent queues. Chasqui does not use the Redis Pub/Sub feature
-because it cannot ensure delivery of messages, especially when subscribers are not running.
+    $ bundle
 
-Chasqui consists of two components, a client and a server.
-The client provides a simple interface for publishing messages. The client places messages
-on a persistent queue, called an inbox, where they wait for further processing.
-The server reads messages from the inbox and places them on the queues of each subscriber.
-The server will create queues for subscribers if the queues do not exist.
+Or install it yourself as:
 
-The advantage of this design is that messages are not lost when the chasqui server or the
-chasqui subscribers are not running.
+    $ gem install chasqui
 
-## Is Chasqui the best choice for you?
+## Dependencies
 
-Chasqui is perfect for you if your current architecture meets all of the following criteria
-listed below.
+Chasqui uses Redis to queue events and manage subscriptions. You can install
+redis with your favorite package manager, such as homebrew, yum, or apt, or if
+you prefer, you can run `vagrant up` to run Redis in a virtual machine.
 
-1. You have a service oriented architecture of some kind.
-2. You primarily use resque and/or sidekiq to process jobs already.
-3. You want a simple Pub/Sub solution with minimal setup and maintenance.
-4. Your organization or traffic volume is not high enough to warrant a more complex solution.
+## Quick Start
 
-If any of the above are not true for you, you may want to consider other available solutions.
-This website maintains a list of alternatives for you to consider: http://queues.io/
+Chasqui consistents of two components - a client and a broker. The broker's
+responsibility is to forward published events to registered subscribers. The
+client can both publish events and register subscribers.
 
-If Chasqui is not right for you, then please use another solution. I designed Chasqui to
-solve a specific problem for a particular scale and company size.
+### Start the broker
 
-## Installation
+    chasqui -r redis://localhost:6379/0 -q my-app
 
-Add this line to your application's Gemfile:
+Your broker must use the same redis connection as your sidekiq (or resque)
+workers. For a list of available broker options, run `chasqui --help`.
 
-```ruby
-gem 'chasqui'
-```
+### Publish events
 
-And then execute:
+Publishing events is simple.
 
-    $ bundle
+    # file: publisher.rb
+    require 'chasqui'
+    Chasqui.publish 'user.sign-up', 'Luke Skywalker'
+    Chasqui.publish 'user.cancel', 'Dart Vader', 'invalid use of the force'
 
-Or install it yourself as:
+Be sure to run the publisher, broker, and subscribers in separate terminal
+windows.
 
-    $ gem install chasqui
+    ruby publisher.rb
 
-## Publishing events
+### Subscribe to events
 
-Publishing events is simple.
+Subscribing to events is also simple. The following example tells chasqui to
+forward events to the subscriber's 'my-app' queue, for which chasqui will
+generate the appropriate worker class. Within the subscriber block, you define
+one or more `on` blocks in which you place your application logic for handling
+an event.
 
-```rb
-Chasqui.publish 'user.sign-up', user_id
-```
+    # file: subscriber1.rb
+    require 'chasqui'
 
-To prevent conflicts with other applications, you can choose a unique channel for your events.
+    Chasqui.subscribe queue: 'my-app' do
 
-```rb
-# config/initializers/chasqui.rb
-Chasqui.configure do |config|
-  config.channel = 'com.example.myapp'
-end
-```
+      on 'user.sign-up' do |user_id|
+        # do something when the user signs up
+      end
 
-Now when you call `Chasqui.publish 'event.name', data, ...`, Chasqui will publish the event
-`com.example.myapp.user.sign-up`.
+      on 'user.cancel' do |user_id, reason|
+        # do something else when user cancels
+      end
 
-## Subscribing to events
+    end
 
-```rb
-# file: otherapp/app/subscribers/user_events.rb
-Chasqui.subscribe 'com.example.myapp', queue: 'unique_queue_name_for_app' do
+You can have as many subscribers as you like, but __each subscriber must have
+its own unique queue name__.
 
-  on 'user.sign-up' do |user_id|
-    user = User.find user_id
-    UserMailer.signup(user).deliver
-  end
+Here is how you can run the subscriber as a sidekiq worker:
 
-  on 'user.cancel' do |user_id, reason|
-    user = User.find user_id
-    AdminMailer.user_cancelled(user, reason).deliver
-    user.archive!
-  end
+    sidekiq -r subscriber.rb
 
-end
-```
+To run the resque worker, you first need to create a Rakefile.
 
-## Configure Chasqui
+    # Rakefile
+    require 'resque'
+    require 'resque/tasks'
 
-```rb
-Chasqui.configure do |config|
-  config.channel = 'com.example.transcoder'
-  config.redis = ENV.fetch('REDIS_URL')
-  config.workers = :sidekiq # or :resque
-  ...
-end
-```
+    task 'resque:setup' => ['chasqui:subscriber']
 
-## Running the broker
+    namespace :chasqui do
+      task :subscriber do
+        require './subscriber.rb'
+      end
+    end
 
-Installing and running Chasqui on Ubuntu using the system ruby.
+Then you can run the resque worker to start processing events.
 
-```sh
-# install required dependencies
-$ sudo apt-get install ruby redis-server
+    rake resque:work
 
-# install chasqui
-$ sudo gem install chasqui --no-ri --no-rdoc
+## Why Chasqui?
 
-# run chasqui
-$ chasqui
-I, [2015-09-23T00:58:16.630857 #2420]  INFO -- chasqui: broker started with pid 2420
-I, [2015-09-23T00:58:16.631147 #2420]  INFO -- chasqui: configured to fetch events from inbox on #<Redis client v3.2.1 for redis://127.0.0.1:6379/0>
-```
+* Reduces coupling between applications
+* Integrates with the popular sidekiq and resque background worker libraries
+* Queues events for registered subscribers even if a subscriber is unavailable
 
-There is also a sample Upstart init script in [examples/upstart.conf](examples/upstart.conf).
+## Limitations
 
-If you prefer a different distro or init system, please consider opening a pull-request. Your efforts will be greatly admired and appreciated!
+In order for chasqui to work properly, the publisher, broker, and all
+subscribers must connect to the same Redis database.
 
 ## Contributing
 

data/lib/chasqui.rb

@@ -32,8 +32,9 @@ module Chasqui
       redis.lpush inbox_queue, build_payload(event, *args).to_json
     end
 
-    def subscribe(channel, options={}, &block)
+    def subscribe(options={}, &block)
       queue = options.fetch :queue
+      channel = options.fetch :channel, config.channel
 
       create_subscription(queue, channel).tap do |subscription|
         subscription.subscriber.evaluate(&block) if block_given?

data/lib/chasqui/subscription.rb

@@ -18,7 +18,6 @@ module Chasqui
     end
 
     def worker
-      # TODO How can we store this in an instance variable without breaking things?
       case worker_backend
       when :resque
         Chasqui::ResqueWorker.create subscriber
@@ -33,7 +32,15 @@ module Chasqui
     private
 
     def worker_backend
-      Chasqui.config.worker_backend
+      Chasqui.config.worker_backend || find_first_available_worker_backend
+    end
+
+    def find_first_available_worker_backend
+      if Object.const_defined? :Sidekiq
+        :sidekiq
+      elsif Object.const_defined? :Resque
+        :resque
+      end
     end
 
     SUPPORTED_WORKER_BACKENDS = [:resque, :sidekiq].freeze

data/lib/chasqui/version.rb

@@ -1,3 +1,3 @@
 module Chasqui
-  VERSION = "0.9.2"
+  VERSION = "0.9.3"
 end

data/spec/integration/setup/resque.rb

@@ -1,7 +1,6 @@
 require 'chasqui'
-Chasqui.config.worker_backend = :resque
-
 require 'resque'
+
 Resque.redis = ENV['REDIS_URL'] if ENV['REDIS_URL']
 Resque.redis.namespace = :resque
 

data/spec/integration/setup/sidekiq.rb

@@ -1,8 +1,6 @@
 require 'chasqui'
 require 'sidekiq'
 
-Chasqui.config.worker_backend = :sidekiq
-
 Sidekiq.configure_server do |config|
   config.redis = { url: ENV['REDIS_URL'], namespace: ENV['REDIS_NAMESPACE'] }
 end

data/spec/integration/setup/subscribers.rb

@@ -4,11 +4,11 @@ def log_event subscriber, args
   subscriber.redis.rpush "#{subscriber.queue}:event_log", payload
 end
 
-Chasqui.subscribe 'integration', queue: 'app1' do
+Chasqui.subscribe channel: 'integration', queue: 'app1' do
   on('user.signup') { |*args| log_event self, args }
 end
 
-Chasqui.subscribe 'integration', queue: 'app2' do
+Chasqui.subscribe channel: 'integration', queue: 'app2' do
   on('account.*')   { |*args| log_event self, args }
   on('user.cancel') { |*args| log_event self, args }
 end

data/spec/lib/chasqui/multi_broker_spec.rb

@@ -13,9 +13,9 @@ describe Chasqui::MultiBroker do
   describe '#forward_event' do
     before do
       Chasqui.config.channel = 'app1'
-      Chasqui.subscribe 'app1', queue: 'queue1'
-      Chasqui.subscribe 'app2', queue: 'queue2'
-      Chasqui.subscribe 'app1', queue: 'queue3'
+      Chasqui.subscribe channel: 'app1', queue: 'queue1'
+      Chasqui.subscribe channel: 'app2', queue: 'queue2'
+      Chasqui.subscribe channel: 'app1', queue: 'queue3'
     end
 
     it 'places the event on all subscriber queues' do

data/spec/lib/chasqui/subscription_spec.rb

@@ -9,6 +9,9 @@ describe Chasqui::Subscription do
   describe '#worker' do
     it 'raises when no worker backend configured' do
       Chasqui.config.worker_backend = nil
+      allow_any_instance_of(Chasqui::Subscription).to receive(
+        :worker_backend).and_return(nil)
+
       expect(-> {
         new_subscription.worker
       }).to raise_error(Chasqui::ConfigurationError)

data/spec/lib/chasqui_spec.rb

@@ -134,16 +134,27 @@ describe Chasqui do
   describe '.subscribe' do
     before do
       reset_chasqui
+      Resque.redis.namespace = :resque
       Chasqui.config.worker_backend = :resque
     end
 
+    context 'with defaults' do
+      it 'subscribes to events on the default channel' do
+        sub = Chasqui.subscribe queue: 'my-queue'
+
+        channel = Chasqui.config.channel
+        queues = Chasqui.redis.smembers Chasqui.subscription_key(channel)
+        expect(queues).to eq(['resque/resque:queue:my-queue'])
+      end
+    end
+
     context 'resque worker subscriptions' do
       before { Resque.redis.namespace = 'blah' }
 
       it 'creates subscriptions using the appropriate redis namespace' do
-        sub1 = Chasqui.subscribe 'com.example.admin', queue: 'app1-queue'
-        sub2 = Chasqui.subscribe 'com.example.admin', queue: 'app2-queue'
-        sub3 = Chasqui.subscribe 'com.example.video', queue: 'app1-queue'
+        sub1 = Chasqui.subscribe channel: 'com.example.admin', queue: 'app1-queue'
+        sub2 = Chasqui.subscribe channel: 'com.example.admin', queue: 'app2-queue'
+        sub3 = Chasqui.subscribe channel: 'com.example.video', queue: 'app1-queue'
 
         queues = Chasqui.redis.smembers Chasqui.subscription_key("com.example.admin")
         expect(queues.sort).to eq(['resque/blah:queue:app1-queue', 'resque/blah:queue:app2-queue'])
@@ -164,12 +175,12 @@ describe Chasqui do
         end
 
         it 'creates subscriptions using the appropriate redis namespace' do
-          Chasqui.subscribe 'com.example.admin', queue: 'app1-queue'
+          Chasqui.subscribe channel: 'com.example.admin', queue: 'app1-queue'
           queues = Chasqui.redis.smembers Chasqui.subscription_key("com.example.admin")
           expect(queues.sort).to eq(['sidekiq/queue:app1-queue'])
 
           Sidekiq.redis = { url: redis.client.options[:url], namespace: 'foobar' }
-          Chasqui.subscribe 'com.example.video', queue: 'app2-queue'
+          Chasqui.subscribe channel: 'com.example.video', queue: 'app2-queue'
           queues = Chasqui.redis.smembers Chasqui.subscription_key("com.example.video")
           expect(queues.sort).to eq(['sidekiq/foobar:queue:app2-queue'])
         end
@@ -177,13 +188,13 @@ describe Chasqui do
     end
 
     it 'returns a subscription' do
-      subscription = Chasqui.subscribe 'com.example.admin', queue: 'app1-queue'
+      subscription = Chasqui.subscribe channel: 'com.example.admin', queue: 'app1-queue'
       expect(subscription.subscriber).to be_kind_of(Chasqui::Subscriber)
     end
 
     it 'yields a subscriber configuration context' do
       $context = nil
-      Chasqui.subscribe 'bar', queue: 'foo' do
+      Chasqui.subscribe channel: 'bar', queue: 'foo' do
         $context = self
       end
       expect($context).to be_kind_of(Chasqui::Subscriber)
@@ -195,9 +206,9 @@ describe Chasqui do
       reset_chasqui
       Chasqui.config.worker_backend = :resque
       Resque.redis.namespace = 'ns0'
-      Chasqui.subscribe 'com.example.admin', queue: 'app1-queue'
-      Chasqui.subscribe 'com.example.admin', queue: 'app2-queue'
-      Chasqui.subscribe 'com.example.video', queue: 'app1-queue'
+      Chasqui.subscribe channel: 'com.example.admin', queue: 'app1-queue'
+      Chasqui.subscribe channel: 'com.example.admin', queue: 'app2-queue'
+      Chasqui.subscribe channel: 'com.example.video', queue: 'app1-queue'
     end
 
     it 'removes the subscription' do

data/spec/support/chasqui_spec_helpers.rb

@@ -1,8 +1,8 @@
 module ChasquiSpecHelpers
 
   def reset_chasqui
-    reset_config
     flush_redis
+    reset_config
   end
 
   def reset_config

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chasqui
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - Jordan Bach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-10 00:00:00.000000000 Z
+date: 2015-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -156,7 +156,6 @@ files:
 - bin/console
 - chasqui.gemspec
 - code-of-conduct.md
-- examples/full.rb
 - examples/upstart.conf
 - lib/chasqui.rb
 - lib/chasqui/broker.rb

data/examples/full.rb

@@ -1,56 +0,0 @@
-# file: admin/config/initializers/chasqui.rb
-Chasqui.configure do |config|
-  config.channel = 'com.example.admin'
-  config.redis = ENV.fetch('REDIS_URL')
-end
-
-# file: admin/app/controllers/video_controller.rb
-class VideosController < ApplicationController
-
-  def upload
-    video = Video.find params[:id]
-
-    if video.upload params[:file]
-      Chasqui.publish 'video.upload', video.id
-      redirect_to upload_complete_url,
-    else
-      redirect_to video_url, alert: "Upload failed."
-    end
-  end
-
-end
-
-# file: transcoder/config/initializers/chasqui.rb
-Chasqui.configure do |config|
-  config.publish 'com.example.transcoder'
-  config.redis ENV.fetch('REDIS_URL')
-  config.workers :sidekiq # or :resque
-end
-
-# file: transcoder/app/subscribers/video_subscriber.rb
-Chasqui.subscribe 'com.example.admin', queue: 'transcoder.video' do
-  on 'video.upload' do |video_id|
-    begin
-      Transcorder.transcode video_url(video_id)
-      Chasqui.publish 'video.complete', video_id
-    rescue => ex
-      Chasqui.publish 'video.error', video_id, ex.message
-      raise
-    end
-  end
-end
-
-# file: admin/app/subscribers/video_subscriber.rb
-Chasqui.subscribe 'com.example.transcoder', queue: 'admin.events' do
-
-  on 'transcoder.video.complete' do |video_id|
-    video = Video.find video_id
-    VideoMailer.transcode_complete(video).deliver
-  end
-
-  on 'transcoder.video.error' do |video_id, error|
-    video = Video.find video_id
-    VideoMailer.transcode_error(video, error).deliver
-  end
-
-end