rmsg 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d584ea38af8db2b4492bc2f4ac94b2cb9688e489
-  data.tar.gz: 51cb5b1e0d85825525be13e078757caadb5a5009
+  metadata.gz: cd8c186f2b3eb1994af8a571b97014da0b5c6555
+  data.tar.gz: 1082fd88c45cda89d57a806cc795c1f4342f6d46
 SHA512:
-  metadata.gz: 27c5e065f5f75924352f4b1f774dcbcc0e26745a3854e07a6fab12162c313036070d5f14fe16ca1f3b0f773fcf8542c10dc55cd8b8d55dbf53cbffc0b2846cd5
-  data.tar.gz: 63703855f633d97edcc1d4a4b7db89aaf1ee5a36a4cc2ac07cae9cca6efe64e31bc881d526e0cedcd1328a5802cb8bccd9ef788f9034e2b7eb012c480c8f6c2b
+  metadata.gz: 44647529cd573666348ddc2540eedfdf6eb1ff4ab6b92005f8b9e9ce0c6f4ed457d4bf874083a3a0f974d1bd00c45a18277214210c8abc18dceb98b3ac7e031d
+  data.tar.gz: 1c6834888978b829861c5507f95d254c93044bc0fe52ffacc70d8a59c3d463da5b4b9da974163695167e498267fe70099330920ae5afb31be50873f278ddb7ca

data/README.md

@@ -1,6 +1,6 @@
 # Rmsg
 
-Topics and Tasks in Ruby over RabbitMQ. A thin, minimal layer on top of [Bunny](https://github.com/ruby-amqp/bunny).
+RabbitMQ messaging in Ruby, with topics and tasks. A thin, minimal layer on top of [Bunny](https://github.com/ruby-amqp/bunny).
 
 ## Installation.
 
@@ -18,7 +18,100 @@ gem 'rmsg'
 
 ## Usage.
 
-TODO.
+Rmsg supports messaging following the pub/sub over topics pattern and the tasks (work queues) pattern. Publishers are non-blocking since the typical scenario is publishing a message from a web app. Topic Subscribers and Task Consumers are blocking, long-running processes. You should run them as multiple independent processes using a supervisor like [runit](http://smarden.org/runit/).
+
+## Topics.
+
+Scenario: you have several independent services running. One of them holds users credentials. When an user changes his global API key you want to inform all interested services that the key has changed. Services choose to communicate over the "services" topic. You can have multiple publishers and multiple subscribers for the same topic and routing key.
+
+### Subscriber.
+
+A topic subscriber is a service listening to the "services" topic, for messages published with the "users.key_changed" routing key.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rmsg'
+
+rabbit = Rmsg::Rabbit.new
+services = Rmsg::Topic.new(rabbit: rabbit, topic: 'services')
+
+services.subscribe('users.key_changed') do |message|
+   p message
+end
+```
+
+You can also have a subscriber listening to all events related to users, not only to a specific event, by changing the routing key of the subscriber to:
+
+```ruby
+services.subscribe('users.*') do |message| ...
+```
+
+### Publisher.
+
+A topic publisher is a service publishing the message to inform all other services that the event 'users.key_changed' has just happened.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rmsg'
+
+message = {
+  id: 1,
+  key: 'xxxccc'
+}
+key = 'users.key_changed'
+
+rabbit = Rmsg::Rabbit.new
+services = Rmsg::Topic.new(rabbit: rabbit, topic: 'services')
+
+services.publish(message, key)
+
+rabbit.close
+```
+
+## Tasks.
+
+Scenario: you have many email messages coming through a web API and you want to enqueue them as fast as possible, processing them at a later time using distributed consumers. Task publishers and consumers use durable queues and persistent messages, to ensure that tasks will survive a RabbitMQ restart. Consumers will send a manual ack after processing a task, in order to avoid losing tasks if a consumer crashes while processing a task. Tasks will be distributed to consumer processes with a simple round-robin schedule, one task per consumer.
+
+### Consumer.
+
+A task consumer is a process that grabs a task from the tasks queue and performs some work with it.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rmsg'
+
+rabbit = Rmsg::Rabbit.new
+messages = Rmsg::Task.new(rabbit: rabbit, queue: 'messages')
+
+messages.subscribe do |message|
+  sleep 1
+  p message
+end
+```
+
+### Publisher.
+
+A task publisher is a process that publishes a task on a tasks queue as fast as possible.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rmsg'
+
+rabbit = Rmsg::Rabbit.new
+messages = Rmsg::Task.new(rabbit: rabbit, queue: 'messages')
+
+message = {
+  id: 1,
+  body: 'email body'
+}
+messages.publish(message)
+
+rabbit.close
+```
 
 ## Tests.
 
@@ -29,10 +122,14 @@ TODO.
 bundle exec rake test:spec
 ```
 
-## Contributing
+## Contributing.
 
 1. Fork it ( https://github.com/badshark/rmsg/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## License.
+
+[MIT](LICENSE.txt)

data/lib/rmsg/task.rb

@@ -4,8 +4,8 @@ module Rmsg
     # When initializing a task handler, the queue
     # will be declared durable, to survive RabbitMQ restarts.
     # @param params [Hash]
-    # * :rabbit [Rmsg::Rabbit] Example: Rmsg::Rabbit.new
-    # * :queue [String] Example: 'messages'
+    # @option params :rabbit [Rmsg::Rabbit] Example: Rmsg::Rabbit.new
+    # @option params :queue [String] Example: 'messages'
     def initialize(params)
       @rabbit = params[:rabbit]
       @queue = @rabbit.channel.queue(params[:queue], durable: true)
@@ -24,7 +24,7 @@ module Rmsg
     # When receiving INT it will gracefully close.
     # Consumer processes have a prefetch value of 1 for round-robin distribution.
     # Consumer processes will send a manual ack after processing, to avoid losing tasks.
-    # @yield message [Hash] A block to process the message received.
+    # @yieldparam message [Hash] The message received, to be processed within the block.
     def subscribe
       @rabbit.channel.prefetch(1)
       begin

data/lib/rmsg/topic.rb

@@ -3,15 +3,15 @@ module Rmsg
   # to a topic with a key, over RabbitMQ.
   class Topic
     # @param params [Hash]
-    # * :rabbit [Rmsg::Rabbit] Example: Rmsg::Rabbit.new
-    # * :topic [String] Example: 'services'
+    # @option params :rabbit [Rmsg::Rabbit] Example: Rmsg::Rabbit.new
+    # @option params :topic [String] Example: 'services'
     def initialize(params)
       @rabbit = params[:rabbit]
       @exchange = @rabbit.channel.topic(params[:topic])
     end
 
     # Publish a message with a routing key.
-    # @param message [Hash] Example: {id: 1, key: 'xxxccc'}
+    # @param message [Hash] Message to be published.
     # @param key [String] Example: 'users.key_changed'
     # @return [Exchange] The exchange used to publish.
     def publish(message, key)
@@ -23,7 +23,7 @@ module Rmsg
     # It is specifically designed for long running processes.
     # When receiving INT it will gracefully close.
     # @param key [String] Example: 'users.key_changed'
-    # @yield message [Hash] A block to process the message received.
+    # @yieldparam message [Hash] The message received, to be processed within the block.
     def subscribe(key)
       @queue = @rabbit.channel.queue("", :exclusive => true)
       @queue.bind(@exchange, :routing_key => key)

data/lib/rmsg/version.rb

@@ -1,3 +1,3 @@
 module Rmsg
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/rmsg.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "yard"
 
   spec.add_dependency "bunny", "~> 1.6"
   spec.add_dependency "json", "~> 1.8.1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rmsg
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - badshark
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: bunny
   requirement: !ruby/object:Gem::Requirement
@@ -126,3 +140,4 @@ test_files:
 - test/spec/rabbit_spec.rb
 - test/spec/task_spec.rb
 - test/spec/topic_spec.rb
+has_rdoc: