pwwka 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ab413d6cec5031e40f04a92fc87f117bfbab457d
+  data.tar.gz: 0791952942b76c40e8106da29fcbc1ab3051b8d3
+SHA512:
+  metadata.gz: 12554c6f0ed97ba914939cd42f4e37856e9faf7164f74573af3f9f0138cabc7b3122d66827550118d049892067b833af4bf3250697208347e99a21da934d74e9
+  data.tar.gz: e2beebd8979bde2f0846cc24888d6ac1bbf08e287a6aff9b6a40abd5518fa011664df4ccb226298ae9f389c58b8b6e9c5497ad4d53d4ab70e832c64e21b50b47

data/.gitignore

@@ -0,0 +1,13 @@
+pkg
+spec/reports
+.vimrc
+*.sw?
+.idea/
+config/database.yml
+db
+.tddium*
+.DS_Store
+.jhw-cache
+**.orig
+.rspec
+.bundle

data/.ruby-gemset

@@ -0,0 +1 @@
+message_handler

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://www.rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,60 @@
+PATH
+  remote: .
+  specs:
+    pwwka (0.0.2)
+      activemodel
+      activesupport
+      bunny
+      mono_logger
+      sucker_punch
+
+GEM
+  remote: https://www.rubygems.org/
+  specs:
+    activemodel (4.1.4)
+      activesupport (= 4.1.4)
+      builder (~> 3.1)
+    activesupport (4.1.4)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    amq-protocol (1.9.2)
+    builder (3.2.2)
+    bunny (1.4.0)
+      amq-protocol (>= 1.9.2)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    diff-lcs (1.2.5)
+    i18n (0.6.11)
+    json (1.8.1)
+    minitest (5.4.0)
+    mono_logger (1.1.0)
+    rake (10.3.2)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.4)
+    sucker_punch (1.1)
+      celluloid (~> 0.15.2)
+    thread_safe (0.3.4)
+    timers (1.1.0)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pwwka!
+  rake
+  rspec

data/README.md

@@ -0,0 +1,186 @@
+This gem connects to a topic exchange on a RabbitMQ server. It gives any app using it the ability to do two things:
+
+* Transmit messages to the exchange
+* Receive messages from the exchange and tell the exchange whether or not the message has been acknowledged.
+
+Any app can do one or both of these things.
+
+The basic principle of the Pwwka Message Bus is this:
+
+> The transmitter should send messages to inform anyone who listens that an event has occurred. It's up to the receiver to interpret the message.
+
+As an example:
+
+* public_app sends a message that a new client has signed up
+* admin_app receives that message and updates its client index
+* email_app receives that message and sends a welcome email to the client
+
+### Persistence
+
+All transmitters and receivers share the same exchange. This means that all receivers can read all messages that any transmitter sends. To ensure that all messages are received by eveyone who wants them the Pwwka message bus is configured as follows:
+
+* The exchange is named and durable. If the service goes down and restarts the named exchange will return with the same settings so everyone can reconnect.
+* The receiver queues are all named and durable. If the service goes down and restarts the named queue will return with the same settings so everyone can reconnect, and with any unacknowledged messages waiting to be received.
+* All messages are sent as persistent and require acknowledgement. They will stick around and wait to be received and acknowledged by every queue that wants them, regardless of service interruptions.
+
+
+## Setting it up
+
+### Install RabbitMQ locally
+
+```
+brew install rabbitmq
+```
+
+And follow the instructions.
+
+### Adding it to your app
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'pwwka', require: false, git: 'https://github.com/stitchfix/pwwka.git'
+```
+
+
+### Set up your message_handler configration
+
+Connect to your RabbitMQ instance using the url and choose a name for your
+topic exchange.
+
+In `config/initializers/pwwka`:
+
+```ruby
+require 'pwwka'
+Pwwka.configure do |config|
+  config.rabbit_mq_host      = ENV['RABBITMQ_URL']
+  config.topic_exchange_name = "mycompany-topics-#{Rails.env}"
+end
+```
+
+## Sending a message
+
+You can send any kind of message using `Pwwka::Transmitter.send_message!`:
+
+```ruby
+payload = {client_id: '13452564'}
+routing_key	= 'sf.clients.client.created'
+Pwwka::Transmitter.send_message!(payload, routing_key)
+```
+The payload should be a simple hash containing primitives. Don't send objects because the payload will be converted to JSON for sending. This will blow up if an exception is raised. If you want the exception to be rescued and logged, use this instead:
+
+```ruby
+Pwwka::Transmitter.send_message_safely(payload, routing_key)
+```
+
+You can also use the two convenience methods for sending a message. To include these methods in your class use:
+
+```ruby
+include Pwwka::Handling
+```
+
+Then you can call:
+
+```ruby
+send_message!(payload, routing_key)
+```
+
+This method will blow up if something goes wrong. If you want to send safely then use:
+
+```ruby
+send_message_safely(payload, routing_key)
+```
+
+The messages are not transaction safe so for updates do your best to send them after the transaction commits. You must send create messages after the transaction commits or the receivers will probably not find the persisted records.
+
+
+## Receiving messages
+
+The message-handler comes with a rake task you can use in your Procfile to start up your message handler worker:
+
+```ruby
+message_handler: rake message_handler:receive HANDLER_KLASS=ClientIndexMessageHandler QUEUE_NAME=adminapp_style_index ROUTING_KEY='client.#.updated'
+```
+
+* `HANDLER_KLASS` (required) refers to the class you have to write in you app (equivalent to a `job` in Resque)
+* `QUEUE_NAME` (required) we must use named queues - see below
+* `ROUTING_KEY` (optional) defaults to `#.#` (all messages)
+
+You'll also need to bring the Rake task into your app.  For Rails, you'll need to edit the top-level `Rakefile`:
+
+```ruby
+require 'stitch_fix/message_handler/tasks'
+```
+
+### Queues - what messages will your queue receive
+
+It depends on your `routing_key`. If you set your routing key to `#.#` (the default) it will receive all the messages. The `#` is a wildcard so if you set it to `client.#` it will receive any message with `client.` at the beginning. The exchange registers the queue's name and routing key so it knows what messages the queue is supposed to receive. A named queue will receive each message it expects to get once and only once.
+
+The available wildcards are as follows
+* `*` (star) can substitute for exactly one word.
+* `#` (hash) can substitute for zero or more words.
+
+__A note on re-queuing:__ At the moment messages that raise an error on receipt are marked 'not acknowledged, don't resend', and the failure message is logged. All unacknowledged messages will be resent when the worker is restarted. The next iteration of this gem will allow for a specified number of resends without requiring a restart.
+
+__Spinning up some new dynos to handle the load:__ Since each named queue will receive each message only once you can spin up multiple process using the *same named queue* and they will share the messages between them. If you spin up three processes each will receive roughly one third of the messages, but each message will still only be received once.
+
+### Handlers
+Handlers are simple classes that must respond to `self.handle!`. The receiver will send the handler three arguments:
+
+* `delivery_info` - [a bunch of stuff](http://rubybunny.info/articles/queues.html#accessing_message_delivery_information)
+* `properties` - [a bunch of other stuff](http://rubybunny.info/articles/queues.html#accessing_message_properties_metadata)
+* `payload` - the hash sent by the transmitter
+
+Here is an example:
+
+```ruby
+class ClientIndexMessageHandler
+  
+  attr_reader :payload
+  def initialize(payload)
+    @payload = payload
+  end
+
+  def self.handle!(delivery_info, properties, payload)
+    # for this handler we only care about the payload
+    handler = new(payload) 
+    handler.do_a_thing
+  end
+
+  def do_a_thing
+    ###
+    # some stuff that is being done
+    ###
+  end
+
+end
+```
+
+## Monitoring
+RabbitMQ has a good API that should make it easy to set up some simple monitoring. In the meantime there is logging and manual monitoring.
+
+### Logging
+The receiver logs details of any exception raised in message handling:
+```ruby
+error "Error Processing Message on #{queue_name} -> #{payload}, #{delivery_info.routing_key}: #{e}"
+```
+.The transmitter will likewise log an error if you use the `_safely` methods:
+```ruby
+error "Error Transmitting Message on #{routing_key} -> #{payload}: #{e}"
+```
+
+### Manual monitoring
+RabbitMQ has a web interface for checking out the health of connections, channels, exchanges and queues. Access it via the Heroku add-ons page for Enigma.
+
+![RabbitMQ Management 1](docs/images/RabbitMQ_Management.png)
+![RabbitMQ Management 2](docs/images/RabbitMQ_Management-2.png)
+![RabbitMQ Management 3](docs/images/RabbitMQ_Management-3.png)
+
+## Testing
+The message_handler gem has tests for all its functionality so app testing is best done with expectations. However, if you want to test the message bus end-to-end in your app you can use some helpers in `lib/stitch_fix/message_handler/test_handler.rb`. See the gem specs for examples of how to use them.
+
+## TODO
+* automated monitoring
+* forking
+* resending
+* handling messages from inside transactions properly

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rubygems/package_task'
+require 'rspec/core/rake_task'
+require 'bundler'  
+
+$: << File.join(File.dirname(__FILE__),'lib')
+
+include Rake::DSL
+
+gemspec = eval(File.read('pwwka.gemspec'))
+Gem::PackageTask.new(gemspec) {}
+RSpec::Core::RakeTask.new(:spec)
+Bundler::GemHelper.install_tasks
+
+task :default => :spec
+

data/lib/pwwka.rb

@@ -0,0 +1,32 @@
+module Pwwka
+
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def environment
+      ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+    end   
+  end
+
+end
+
+require 'json'
+require 'sucker_punch'
+require 'active_support/inflector'
+require 'active_support/core_ext/module'
+require 'active_support/hash_with_indifferent_access'
+
+require 'pwwka/version'
+require 'pwwka/logging'
+require 'pwwka/channel_connector'
+require 'pwwka/handling'
+require 'pwwka/receiver'
+require 'pwwka/transmitter'
+
+require 'pwwka/configuration'

data/lib/pwwka/channel_connector.rb

@@ -0,0 +1,31 @@
+module Pwwka
+  class ChannelConnector
+
+    attr_reader :connection
+    attr_reader :topic_exchange_name
+    attr_reader :channel
+
+    # The channel_connector starts the connection to the message_bus
+    # so it should only be instantiated by a method that has a strategy
+    # for closing the connection
+    def initialize
+      configuration        = Pwwka.configuration
+      connection_options   = {automatically_recover: false}.merge(configuration.options)
+      @connection          = Bunny.new(configuration.rabbit_mq_host,
+                                  connection_options)
+      @topic_exchange_name = configuration.topic_exchange_name
+      @connection.start
+      @channel             = @connection.create_channel
+    end
+
+    def topic_exchange
+      @topic_exchange ||= channel.topic(topic_exchange_name, durable: true)
+    end
+
+    def connection_close
+      channel.close
+      connection.close
+    end
+
+  end
+end

data/lib/pwwka/configuration.rb

@@ -0,0 +1,19 @@
+require 'bunny'
+require 'mono_logger'
+module Pwwka
+  class Configuration
+
+    attr_accessor :rabbit_mq_host 
+    attr_accessor :topic_exchange_name
+    attr_accessor :logger
+    attr_accessor :options
+
+    def initialize
+      @rabbit_mq_host       = nil
+      @topic_exchange_name  = "pwwka-topics-#{Pwwka.environment}"
+      @logger               = MonoLogger.new(STDOUT)
+      @options              = {}
+    end
+
+  end
+end

data/lib/pwwka/handling.rb

@@ -0,0 +1,15 @@
+module Pwwka
+
+  module Handling
+
+    def send_message!(payload, routing_key)
+      Pwwka::Transmitter.send_message!(payload, routing_key)
+    end
+
+    def send_message_safely(payload, routing_key)
+      Pwwka::Transmitter.send_message_safely(payload, routing_key)
+    end
+
+  end
+
+end

data/lib/pwwka/logging.rb

@@ -0,0 +1,11 @@
+module Pwwka
+  module Logging
+
+    delegate :fatal, :error, :warn, :info, :debug, to: :logger
+
+    def logger
+      Pwwka.configuration.logger
+    end
+
+  end
+end

data/lib/pwwka/receiver.rb

@@ -0,0 +1,77 @@
+module Pwwka
+  class Receiver
+
+    extend Pwwka::Logging
+
+    attr_reader :channel_connector
+    attr_reader :channel
+    attr_reader :topic_exchange
+    attr_reader :queue_name
+    attr_reader :routing_key
+
+    def initialize(queue_name, routing_key)
+      @queue_name        = queue_name
+      @routing_key       = routing_key
+      @channel_connector = ChannelConnector.new
+      @channel           = @channel_connector.channel
+      @topic_exchange    = @channel_connector.topic_exchange
+    end
+
+    def self.subscribe(handler_klass, queue_name, routing_key: "#.#", block: true)
+      raise "#{handler_klass.name} must respond to `handle!`" unless handler_klass.respond_to?(:handle!)
+      receiver  = new(queue_name, routing_key)
+      begin
+        info "Receiving on #{queue_name}"
+        receiver.topic_queue.subscribe(ack: true, block: block) do |delivery_info, properties, payload|
+          begin
+            payload = ActiveSupport::HashWithIndifferentAccess.new(JSON.parse(payload))
+            handler_klass.handle!(delivery_info, properties, payload)
+            receiver.ack(delivery_info.delivery_tag)
+            info "Processed Message on #{queue_name} -> #{payload}, #{delivery_info.routing_key}"
+          rescue => e
+            error "Error Processing Message on #{queue_name} -> #{payload}, #{delivery_info.routing_key}: #{e}"
+            # no requeue
+            receiver.nack(delivery_info.delivery_tag)
+          end
+        end
+      rescue Interrupt => _
+        # TODO: trap TERM within channel.work_pool
+        info "Interrupting queue #{queue_name} subscriber safely"
+        receiver.channel_connector.connection_close
+      end
+      return receiver
+    end
+
+    def topic_queue
+      @topic_queue ||= begin
+        queue = channel.queue(queue_name, durable: true)
+        queue.bind(topic_exchange, routing_key: routing_key)
+        queue
+      end 
+    end
+
+    def ack(delivery_tag)
+      channel.acknowledge(delivery_tag, false)
+    end
+
+    def nack(delivery_tag)
+      channel.nack(delivery_tag, false, false)
+    end
+
+    def nack_requeue(delivery_tag)
+      channel.nack(delivery_tag, false, true)
+    end
+
+    def drop_queue
+      topic_queue.purge  
+      topic_queue.delete
+    end
+
+    def test_teardown
+      drop_queue
+      topic_exchange.delete
+      channel_connector.connection_close 
+    end
+
+  end
+end

data/lib/pwwka/tasks.rb

@@ -0,0 +1,11 @@
+namespace :message_handler do
+  desc "Start the message bus receiver"
+  task :receive => :environment do
+    raise "HANDLER_KLASS must be set" unless ENV['HANDLER_KLASS']
+    raise "QUEUE_NAME must be set" unless ENV['QUEUE_NAME']
+    handler_klass = ENV['HANDLER_KLASS'].constantize
+    queue_name    = "#{ENV['QUEUE_NAME']}_#{Rails.env}"
+    routing_key   = ENV['ROUTING_KEY'] || "#.#"
+    Pwwka::Receiver.subscribe(handler_klass, queue_name, routing_key: routing_key)
+  end
+end

data/lib/pwwka/test_handler.rb

@@ -0,0 +1,50 @@
+module Pwwka
+  class TestHandler
+
+    attr_reader :channel_connector
+    attr_reader :channel
+    attr_reader :topic_exchange
+
+    def initialize
+      @channel_connector = ChannelConnector.new
+      @channel           = channel_connector.channel
+      @topic_exchange    = channel_connector.topic_exchange
+    end
+
+    # call this method to create the queue used for testing
+    # queue needs to be declared before the exchange is published to
+    def test_setup
+      test_queue
+      true
+    end
+
+    def test_queue
+      @test_queue  ||= begin
+                         test_queue  = channel.queue("test-queue", durable: true)
+                         test_queue.bind(topic_exchange, routing_key: "*.*")
+                         test_queue
+                       end
+    end
+
+    def get_topic_message_payload_for_tests
+      delivery_info, properties, payload  = test_queue.pop
+      JSON.parse(payload)
+    end
+
+    def get_topic_message_properties_for_tests
+      delivery_info, properties, payload  = test_queue.pop
+      properties
+    end
+
+    def purge_test_queue
+      test_queue.purge  
+    end
+
+    def test_teardown
+      test_queue.delete
+      topic_exchange.delete
+      channel_connector.connection_close 
+    end
+
+  end
+end

data/lib/pwwka/transmitter.rb

@@ -0,0 +1,38 @@
+module Pwwka
+  class Transmitter
+
+    extend Pwwka::Logging
+    include SuckerPunch::Job
+
+    def self.send_message!(payload, routing_key)
+      new.async.send_message!(payload, routing_key)
+      info "BACKGROUND AFTER Transmitting Message on #{routing_key} -> #{payload}"
+    end
+
+    def self.send_message_safely(payload, routing_key)
+      begin
+        send_message!(payload, routing_key)
+      rescue => e
+        error "Error Transmitting Message on #{routing_key} -> #{payload}: #{e}"
+        return false
+      end  
+    end
+
+    # send message asynchronously using sucker_punch
+    # call async.send_message!
+    def send_message!(payload, routing_key)
+      self.class.info "BACKGROUND START Transmitting Message on #{routing_key} -> #{payload}"
+      channel_connector = ChannelConnector.new 
+      channel_connector.topic_exchange.publish(
+        payload.to_json,
+        routing_key: routing_key,
+        persistent: true)
+      channel_connector.connection_close
+      # if it gets this far it has succeeded
+      self.class.info "BACKGROUND END Transmitting Message on #{routing_key} -> #{payload}"
+      return true
+    end
+
+  end
+
+end

data/lib/pwwka/version.rb

@@ -0,0 +1,3 @@
+module Pwwka
+  VERSION = '0.0.2'
+end

data/pwwka.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'pwwka/version'
+
+Gem::Specification.new do |s|
+  s.name        = "pwwka"
+  s.version     = Pwwka::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Stitch Fix Engineering']
+  s.email       = ['eng@stitchfix.com']
+  s.homepage    = "http://www.stitchfix.com"
+  s.summary     = "Send and receive messages via RabbitMQ"
+  s.description = "The purpose of this gem is to normalise the sending and
+  receiving of messages between Rails apps using the shared RabbitMQ
+  message bus"
+
+  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.require_paths = ["lib"]
+  s.add_dependency("bunny")
+  s.add_dependency("activesupport")
+  s.add_dependency("activemodel")
+  s.add_dependency("sucker_punch")
+  s.add_dependency("mono_logger")
+  s.add_development_dependency("rake")
+  s.add_development_dependency("rspec")
+end

data/spec/handling_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe Pwwka::Handling do
+
+  class HKlass
+    include Pwwka::Handling
+  end
+
+  describe "adding handler methods" do
+
+    let(:handling_class) { HKlass.new }
+    let(:payload)     { { this: 'that'} }
+    let(:routing_key) { 'sf.merch.style.updated' }
+
+    it "should respond to 'send_message!'" do
+      expect(Pwwka::Transmitter).to receive(:send_message!).with(payload, routing_key)
+      handling_class.send_message!(payload, routing_key)
+    end
+
+    it "should respond to 'send_message_safely'" do
+      expect(Pwwka::Transmitter).to receive(:send_message_safely).with(payload, routing_key)
+      handling_class.send_message_safely(payload, routing_key)
+    end
+
+  end
+
+
+end

data/spec/logging_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper.rb'
+
+describe Pwwka::Logging do
+
+  class ForLogging
+    extend Pwwka::Logging
+  end
+
+  it "returns the logger" do
+    expect(ForLogging.logger).to be_instance_of(MonoLogger)
+  end
+
+  %w(debug info error fatal).each do |severity|
+    it "logs #{severity} messages at the class level" do
+      expect(ForLogging.respond_to?(severity.to_sym)).to eq true
+    end
+
+  end
+end

data/spec/receiver_spec.rb

@@ -0,0 +1,100 @@
+require 'spec_helper.rb'
+
+describe Pwwka::Receiver do
+
+  class HandyHandler
+    def self.handle!(delivery_info, properties, payload)
+      return "made it here"
+    end
+  end
+
+  let(:payload)     { Hash[:this, "that"] }
+  let(:routing_key) { "this.that" }
+  let(:queue_name)  { "receiver_test" }
+
+  describe "::subscribe" do
+
+    before(:each) do
+      @receiver = Pwwka::Receiver.subscribe(HandyHandler, "receiver_test", block: false)
+    end
+
+    after(:each) do
+      @receiver.test_teardown
+    end
+
+    it "should receive the sent message" do
+      expect(HandyHandler).to receive(:handle!).and_return("made it here")
+      Pwwka::Transmitter.send_message!(payload, routing_key)
+    end
+
+    it "should nack the sent message if an error is raised" do
+      expect(HandyHandler).to receive(:handle!).and_raise("blow up")
+      expect(@receiver).not_to receive(:ack)
+      expect(@receiver).to receive(:nack).with(instance_of(Fixnum))
+      Pwwka::Transmitter.send_message!(payload, routing_key)
+    end
+
+  end
+
+  describe "instance methods and ::new" do
+
+    before(:each) do
+      @receiver = Pwwka::Receiver.new(queue_name, routing_key)
+    end
+
+    after(:each) do
+      @receiver.test_teardown
+    end
+
+    describe "::new" do
+
+      it "should initialize the expected attributes" do
+        expect(@receiver.topic_exchange.name).to eq("topics-test")
+        expect(@receiver.topic_exchange.type).to eq(:topic)
+      end
+
+    end
+
+    describe "#topic_queue" do
+
+      it "should return the queue with the right attributes" do
+        queue = @receiver.topic_queue
+        expect(queue.name).to eq(queue_name)
+        expect(queue.instance_variable_get(:@bindings).count).to eq(1)
+      end
+
+    end
+
+    describe "#ack" do
+
+      it "should call the correct channel method" do
+        delivery_tag  = 1224
+        expect(@receiver.channel).to receive(:acknowledge).with(delivery_tag, false)
+        @receiver.ack(delivery_tag)
+      end
+
+    end
+
+    describe "#nack" do
+
+      it "should call the correct channel method" do
+        delivery_tag  = 1224
+        expect(@receiver.channel).to receive(:nack).with(delivery_tag, false, false)
+        @receiver.nack(delivery_tag)
+      end
+
+    end
+
+    describe "#nack_requeue" do
+
+      it "should call the correct channel method" do
+        delivery_tag  = 1224
+        expect(@receiver.channel).to receive(:nack).with(delivery_tag, false, true)
+        @receiver.nack_requeue(delivery_tag)
+      end
+
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+GEM_ROOT = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+require 'pwwka'
+require 'pwwka/test_handler'
+require 'sucker_punch/testing/inline'
+Dir["#{GEM_ROOT}/spec/support/**/*.rb"].sort.each {|f| require f}
+
+RSpec.configure do |config|
+
+  SuckerPunch.logger = nil
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+end
+
+Pwwka.configure do |config|
+  config.topic_exchange_name  = "topics-test"
+  config.logger               = MonoLogger.new("/dev/null")
+end

data/spec/transmitter_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper.rb'
+
+describe Pwwka::Transmitter do
+
+  before(:all) do
+    @test_handler = Pwwka::TestHandler.new
+    @test_handler.test_setup
+  end
+
+  after(:all) { @test_handler.test_teardown }
+
+  let(:payload)     { Hash[:this, "that"] }
+  let(:routing_key) { "this.that" }
+
+  describe "#send_message!" do
+
+    it "should send the correct payload" do
+      success = Pwwka::Transmitter.new.async.send_message!(payload, routing_key)
+      expect(success).to be_truthy
+      received_payload = @test_handler.get_topic_message_payload_for_tests
+      expect(received_payload["this"]).to eq("that")
+    end
+
+    it "should blow up if exception raised" do
+      expect(Pwwka::ChannelConnector).to receive(:new).and_raise("blow up")
+      expect {
+        Pwwka::Transmitter.new.async.send_message!(payload, routing_key)
+      }.to raise_error
+    end
+
+  end
+
+  describe "::send_message!" do
+
+    it "should send the correct payload" do
+      Pwwka::Transmitter.send_message!(payload, routing_key)
+      received_payload = @test_handler.get_topic_message_payload_for_tests
+      expect(received_payload["this"]).to eq("that")
+    end
+
+    it "should use sucker_punch to send the message in the background" do
+      expect_any_instance_of(Pwwka::Transmitter).to receive(:send_message!).with(payload, routing_key).and_return(true)
+      Pwwka::Transmitter.send_message!(payload, routing_key)
+    end
+
+    it "should blow up if exception raised" do
+      expect(Pwwka::ChannelConnector).to receive(:new).and_raise("blow up")
+      expect{
+        Pwwka::Transmitter.send_message!(payload, routing_key)
+      }.to raise_error
+    end
+
+  end
+
+  describe "::send_message_safely" do
+
+    it "should send the correct payload" do
+      Pwwka::Transmitter.send_message_safely(payload, routing_key)
+      received_payload = @test_handler.get_topic_message_payload_for_tests
+      expect(received_payload["this"]).to eq("that")
+    end
+
+    it "should not blow up if exception raised" do
+      expect(Pwwka::ChannelConnector).to receive(:new).and_raise("blow up")
+      Pwwka::Transmitter.send_message_safely(payload, routing_key)
+      # check nothing has been queued
+      expect(@test_handler.test_queue.pop.compact.count).to eq(0)
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: pwwka
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Stitch Fix Engineering
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bunny
+  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'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  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'
+- !ruby/object:Gem::Dependency
+  name: sucker_punch
+  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'
+- !ruby/object:Gem::Dependency
+  name: mono_logger
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: rspec
+  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'
+description: |-
+  The purpose of this gem is to normalise the sending and
+    receiving of messages between Rails apps using the shared RabbitMQ
+    message bus
+email:
+- eng@stitchfix.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- docs/images/RabbitMQ_Management-2.png
+- docs/images/RabbitMQ_Management-3.png
+- docs/images/RabbitMQ_Management.png
+- lib/pwwka.rb
+- lib/pwwka/channel_connector.rb
+- lib/pwwka/configuration.rb
+- lib/pwwka/handling.rb
+- lib/pwwka/logging.rb
+- lib/pwwka/receiver.rb
+- lib/pwwka/tasks.rb
+- lib/pwwka/test_handler.rb
+- lib/pwwka/transmitter.rb
+- lib/pwwka/version.rb
+- pwwka.gemspec
+- spec/handling_spec.rb
+- spec/logging_spec.rb
+- spec/receiver_spec.rb
+- spec/spec_helper.rb
+- spec/transmitter_spec.rb
+homepage: http://www.stitchfix.com
+licenses: []
+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.0
+signing_key: 
+specification_version: 4
+summary: Send and receive messages via RabbitMQ
+test_files:
+- spec/handling_spec.rb
+- spec/logging_spec.rb
+- spec/receiver_spec.rb
+- spec/spec_helper.rb
+- spec/transmitter_spec.rb