kanina 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ec8d730195a2d4c6669e0a7a3d6f221622e1d4fe
+  data.tar.gz: 83205977db72d11380b3d41ea71664bd56530c2d
+SHA512:
+  metadata.gz: 4f8366244d463044be02f10a692ae6a32bb9d6477243e0b726ee1bed2cd883e71cc900ee47d031110c5605884614e31fd60ba5706f5c8f58c135e1b156614d55
+  data.tar.gz: a876042754e17c9b2390a575ce9cdcedd67ec2b1990a98df7af7b57fbf6bdf98587cf3b256b420a20be3eae403d1e174efd5b68f9a9a311fe7e620edf0fcc081

data/.gitignore

@@ -0,0 +1,36 @@
+# App generated
+.bundle/
+log/*.log
+pkg
+tmp
+
+# Rails specific
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+
+# Test generated
+coverage/
+rails_best_practices_output.html
+spec/reports/
+
+# OS stuff
+.DS_Store
+.env
+
+# IDE generated stuff
+.gemtags
+.tags
+.tags_sorted_by_file
+.idea/*
+atlassian-ide-plugin.xml
+.project
+
+# Ignore, this being a gem.
+Gemfile.lock
+
+# Docs
+.yardoc
+doc/

data/.inch.yml

@@ -0,0 +1,5 @@
+files:
+  included:
+    - lib/**/*.rb
+  excluded:
+    - lib/**/templates/*.rb

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,2 @@
+LineLength:
+  Max: 100

data/.ruby-version

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

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+rvm:
+  - "2.2.0"
+  - "2.1.0"
+  - "2.0.0"
+
+branches:
+  only:
+    - master
+
+services:
+  - rabbitmq
+
+addons:
+  code_climate:
+    repo_token: 6077a1780583dcf9415ffb34dc8f8fb3b9821e84699eb3b03590017773e70640

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'coveralls', require: nil
+gem 'codeclimate-test-reporter', group: :test, require: nil
+
+platforms :rbx do
+  gem 'racc'
+  gem 'rubysl', '~> 2.0'
+  gem 'psych'
+end

data/Guardfile

@@ -0,0 +1,9 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end
+
+guard 'yard', port: '8808' do
+  watch(%r{lib/.+\.rb})
+end

data/History.md

@@ -0,0 +1,23 @@
+Changelog
+=========
+
+v0.6.0
+------
+- Mark individual messages as persistent or transient.
+- Add better documentation throughout.
+
+v0.5.0
+------
+- Add durable queues.
+
+v0.4.0
+------
+- Update Bunny version to ~1.6.
+  - Should take care of some connection issues people have been seeing from the older version of Bunny.
+  - I'm not setting the patch version, so your computer will automatically install the latest minor version.
+
+v0.3.3
+------
+- Started this changelog.
+- Remove Spring dependency for preloading.
+- Fix the way existing exchanges are found and connected to.

data/ISC-LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2014 Clinton Judy <clinton@j-udy.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+Kanina
+====
+
+A Rails plugin that makes it easier for your models to communicate with RabbitMQ.
+
+[![Build Status](https://travis-ci.org/judy/kanina.svg?branch=master)](https://travis-ci.org/judy/kanina)
+[![Code Climate](https://codeclimate.com/github/judy/kanina.png)](https://codeclimate.com/github/judy/kanina)
+[![Coverage Status](https://coveralls.io/repos/judy/kanina/badge.png)](https://coveralls.io/r/judy/kanina)
+[![Inline docs](http://inch-ci.org/github/judy/kanina.png?branch=master)](http://inch-ci.org/github/judy/kanina)
+
+Kanina abstracts away queue and exchange creation, so you can focus on the message and subscription side of things in Rails.
+
+Prerequisites
+------------
+
+You'll need **RabbitMQ** installed. Find instructions for your platform [here](http://www.rabbitmq.com/download.html).
+
+
+Installation
+------------
+
+Put this in your `Gemfile`:
+
+    gem 'kanina'
+
+Then run `bundle install` to install the gem and its dependencies. Finally, run `rails generate kanina:install` to create bin/kanina and an amqp.yml.sample file in your config folder.
+
+Copy amqp.yml.sample to amqp.yml, and change it to connect to your local RabbitMQ server. By default, it will connect to the one on your development machine, as long as you haven't changed the settings on it.
+
+Sending Messages
+----------------
+
+Run the generator:
+
+    rails generate kanina:message MessageName
+
+Then specify the name of the exchange, OR the routing key for the intended queue. To send a message, generate an instance of your new class, add data, and hit send:
+
+    msg = MessageName.new
+    msg.data = {key: "value"}
+    msg.deliver
+
+You can also specify the type of exchange you want to create, like so:
+
+    class WeatherMessage < Kanina::Message
+        fanout "reports"
+    end
+
+Remember to use [RabbitMQ's documentation](http://www.rabbitmq.com/documentation.html) to understand the rules governing how to use different types of exchanges, bindings, and queues appropriately. You don't have to create those things ahead of time with Kanina, but you do have to understand how they work!
+
+Receiving messages
+------------------
+
+Generate a subscription with this command:
+
+    rails generate kanina:subscription SubscriptionName
+
+Then tweak the resulting file to attach to the right queue, or use bindings to watch a named exchange. Use a subscribe block to define code that you want run when a message is received:
+
+    class NotifyUserSubscription < Kanina::Subscription
+      subscribe queue: "notify_user" do |data|
+        User.where(id: data[:id]).first.notify
+      end
+    end
+
+---
+
+This project was written by [Clinton Judy](http://judy.github.io), and uses the ISC license.

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/setup'
+require 'rdoc/task'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Kanina'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/kanina.gemspec

@@ -0,0 +1,43 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+
+require 'kanina/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'kanina'
+  s.version       = Kanina::VERSION
+  s.authors       = ['Clinton Judy']
+  s.email         = ['clinton@j-udy.com']
+  s.summary       = 'Rails plugin for RabbitMQ'
+  s.description   = <<-DESC
+This is a Rails plugin that makes it easier for your models
+to communicate via AMQP to RabbitMQ.
+DESC
+  s.homepage      = 'https://github.com/judy/kanina'
+  s.license       = 'ISC'
+
+  s.files         = `git ls-files -z`.split("\x0")
+  s.test_files    = s.files.grep(/spec\//)
+  s.require_paths = %w(lib)
+
+  s.add_dependency 'railties', '> 4.0'
+  s.add_dependency 'bunny', '> 1.6'
+  s.add_dependency 'daemons', '~> 1.1'
+
+  # All used for testing and code climate.
+  s.add_development_dependency 'sqlite3'
+  s.add_development_dependency 'rails', '~> 4.2'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', '3.2.0'
+  s.add_development_dependency 'guard'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'guard-livereload'
+  s.add_development_dependency 'timecop'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rubocop'
+
+  # Documentation
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'github-markup'
+  s.add_development_dependency 'guard-yard'
+end

data/lib/generators/kanina/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This generator installs a config file so Kanina knows how to connect to RabbitMQ.
+
+Example:
+    rails generate kanina
+
+    This will create:
+        config/amqp.yml

data/lib/generators/kanina/install/install_generator.rb

@@ -0,0 +1,16 @@
+require 'rails/generators'
+
+module Kanina
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+
+    # This method is called automatically by rails when you 'install' Kanina. It
+    # copies a sample amqp.yml file to the Rails config folder, and adds amqp.yml
+    # to the .gitignore.
+    def create_amqp_config_file
+      filepath = Rails.root + "config"
+      template "amqp.yml.sample", filepath + "amqp.yml.sample"
+      append_file Rails.root + '.gitignore', 'config/amqp.yml'
+    end
+  end
+end

data/lib/generators/kanina/install/templates/amqp.yml.sample

@@ -0,0 +1,18 @@
+# Refer to Bunny's new connection parameters for settings here.
+# http://rubybunny.info/articles/connecting.html
+
+defaults: &defaults
+  host: localhost
+  port: 5672
+  ssl: false
+  vhost: /
+  user: guest
+  pass: guest
+  heartbeat: :server
+  threaded: true
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults

data/lib/generators/kanina/message/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This generator installs a message inside app/messages, to send messages to RabbitMQ.
+
+Example:
+    rails generate message WeatherReport
+
+    This will create:
+        app/messages/weather_report.rb

data/lib/generators/kanina/message/message_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+
+module Kanina
+  # <tt>Kanina::MessageGenerator</tt> generates a template of a message file. Change the
+  # resulting file with your intended exchange or routing_key information. For example:
+  #
+  #   rails generate message user_notification
+  class MessageGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('../templates', __FILE__)
+
+    # This method is automatically run by Rails when generating a new message.
+    # It sets up the messages folder and adds the message template. Remember to
+    # change the template to talk to the right exchange/queue!
+    def create_message_file
+      messages_folder = Rails.root + 'app/messages'
+      empty_directory messages_folder
+      template 'message.rb', messages_folder + "#{file_name}_message.rb"
+    end
+  end
+end

data/lib/generators/kanina/message/templates/message.rb

@@ -0,0 +1,6 @@
+<% module_namespacing do -%>
+class <%= class_name %>Message < Kanina::Message
+  exchange ""
+  routing_key ""
+end
+<% end -%>

data/lib/generators/kanina/subscription/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This generator installs a message inside app/messages, to send messages to RabbitMQ.
+
+Example:
+    rails generate message WeatherReport
+
+    This will create:
+        app/messages/weather_report.rb

data/lib/generators/kanina/subscription/subscription_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+
+module Kanina
+  # <tt>Kanina::SubscriptionGenerator</tt> generates a subscription file, for
+  # example:
+  #
+  #   rails generate subscription user_notification
+  class SubscriptionGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('../templates', __FILE__)
+
+    # This method is called automatically by rails when you generate the
+    # subscription. It sets up the subscriptions folder, then adds the
+    # subscription to it.
+    def create_subscription_file
+      subscriptions_folder = Rails.root + 'app/subscriptions'
+      empty_directory subscriptions_folder
+      template 'subscription.rb', subscriptions_folder + "#{file_name}_subscription.rb"
+    end
+  end
+end

data/lib/generators/kanina/subscription/templates/subscription.rb

@@ -0,0 +1,7 @@
+<% module_namespacing do -%>
+class <%= class_name %>Subscription < Kanina::Subscription
+  subscribe queue: "queue_name" do |data|
+    # Add the code you want to run upon receiving each message in this queue.
+  end
+end
+<% end -%>

data/lib/kanina.rb

@@ -0,0 +1,11 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'bunny'
+
+require 'kanina/version'
+require 'kanina/logger'
+require 'kanina/server'
+require 'kanina/message'
+require 'kanina/subscription'
+
+require 'kanina/railtie'

data/lib/kanina/logger.rb

@@ -0,0 +1,18 @@
+require 'logger'
+
+module Kanina
+  # Simplifies sending messages to standard output and/or the Rails log files.
+  module Logger
+    DEFAULT_LOG_LEVEL = ::Logger::INFO
+
+    def logger
+      Rails.logger ||= ::Logger.new(STDOUT)
+      @logger ||= Rails.logger
+    end
+
+    def say(text, level = DEFAULT_LOG_LEVEL)
+      puts text if @loud
+      logger.add level, "HARE: #{text}"
+    end
+  end
+end

data/lib/kanina/message.rb

@@ -0,0 +1,138 @@
+module Kanina
+  # `Kanina::Message` allows you to send messages to RabbitMQ, and have
+  # your exchanges and bindings set up on the fly.
+  #
+  #     # app/messages/user_message.rb
+  #     class UserMessage < Kanina::Message
+  #       exchange "user.exchange"
+  #     end
+  #
+  #     message = UserMessage.new("data")
+  #     message.deliver
+  #
+  # Messages are encapsulated in JSON format. If you use
+  # `Kanina::Subscription` to receive messages, they're automatically
+  # parsed back out of JSON into native Ruby objects.
+  class Message
+    class << self
+      # Helper method to return the channel opened by `Kanina::Server`.
+      def channel
+        Kanina::Server.channel or fail 'Kanina::Server.channel is not open'
+      end
+
+      # @overload exchange
+      #   @return [String] the set exchange, or the default exchange.
+      # @overload exchange(name, *opts)
+      #   Set the name and type of the exchange messages should be sent to.
+      #   @param name [String] the name of the exchange
+      #   @param type [:direct, :fanout, :topic] the type of exchange
+      #   @return [String] the exchange
+      def exchange(name = nil, type: :direct)
+        if name.present?
+          @type = type
+          @exchange = channel.exchange(name, type: type)
+        else
+          @exchange || channel.default_exchange
+        end
+      end
+
+      [:direct, :fanout, :topic].each do |type|
+        define_method type do |name|
+          exchange(name, type: type)
+        end
+      end
+
+      # Set the queue to which messages at this exchange should be sent to. Note
+      # that you'll probably want to use this at the exchange level, OR a
+      # binding at the queue level.
+      # @overload routing_key
+      #   @return [String] the routing key
+      # @overload routing_key(name)
+      #   Verifies that the queue exists or is created, and sets the routing key to it.
+      #   @param name [String] the routing key
+      #   @return [String] the routing key
+      def routing_key(name = nil)
+        if name.present?
+          verify_queue(name)
+          @routing_key = name
+        else
+          @routing_key
+        end
+      end
+
+      # Sets outgoing messages to be persistent. **Note** that messages must be
+      # sent to a durable queue, or they will still be lost! By default, this is
+      # `true`.
+      def persistent
+        @persistent.nil? ? @persistent = true : @persistent
+      end
+
+      # Sets outgoing messages to be transient (*not* persistent). If the receiving queues
+      # are taken down, messages could be lost. This might be the desired functionality,
+      # if messages need to be timely and queues being destroyed aren't a big deal.
+      def transient
+        @persistent = false
+      end
+
+      # Creates the queue, or grabs the queue that already exists. Note that if
+      # the queue already exists, it must exist with the same parameters (like durability),
+      # or the Bunny gem is very unhappy.
+      def verify_queue(routing_key)
+        Kanina::Server.channel.queue(routing_key)
+      end
+    end
+
+    # @!attribute [rw] data
+    #   The actual contents of the message to be sent.
+    attr_accessor :data
+
+    # @!attribute [w] routing_key
+    #   Set this to change the queue that this message should be sent to.
+    #   (Overrides any routing key set at the class level.)
+    attr_writer :routing_key
+
+    # Create a new message to be sent.
+    # @param data [Hash] The payload of the message
+    # @param routing_key [String] Optional, to change the queue the message is sent to.
+    def initialize(data = nil, routing_key: nil)
+      @data = data || {}
+      @routing_key = routing_key
+      @persistent = persistent
+    end
+
+    # The exchange this message is going into
+    # @return [String] exchange
+    def exchange
+      self.class.exchange
+    end
+
+    # @return [String] routing_key
+    def routing_key
+      @routing_key || self.class.routing_key
+    end
+
+    # @return [Boolean] whether this message is persistent or not
+    #   Currently only set at the class level.
+    def persistent
+      @persistent.nil? ? self.class.persistent : @persistent
+    end
+
+    # @return [String] The json-formatted data being sent.
+    def json
+      data.present? ? data.to_json : {}.to_json
+    end
+
+    # Deliver the message to the specified exchange and/or queue.
+    def deliver
+      if exchange.name == ''
+        if routing_key.present?
+          exchange.publish(json, routing_key: routing_key, persistent: @persistent)
+        else
+          fail 'Routing key must be set when using default exchange.'
+        end
+      else
+        exchange.publish(json, routing_key: routing_key)
+      end
+    end
+  end
+end