redis_message_capsule 0.0.1 → 0.8.0

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+*debug.log

data/README.md

@@ -1,58 +1,182 @@
 # RedisMessageCapsule
 
-Send and receive real-time messages between applications (via redis).
+Send messages between node or rails apps asynchronously (via redis).
+* [report an issue with the ruby version] (https://github.com/arbind/redis_message_capsule/issues)
+* [report an issue with the node version] (https://github.com/arbind/redis_message_capsule-node/issues)
 
-## Installation
+## Installation (with npm for node) (as a gem for ruby)
 
-Add this line to your application's Gemfile:
+    $ npm install redis_message_capsule
+    $ gem install redis_message_capsule
 
-    gem 'redis_message_capsule'
+## Usage
+RedisMessageCapsule is used in the same way for both node and ruby (just the syntax is different, naturally).
 
-And then execute:
+The pseudo code goes something like this:
 
-    $ bundle
+    # 1. Create a capsule that is bound to the redis DB:
+    > load RedisMessageCapsule
+    > capsule = materializeCapsule(redisURL, dbNumber)
 
-Or install it yourself as:
+    # 2. Create a named channel that you want to send or receive messages on
+    > catChannel = capsule.materializeChannel('cat')
 
-    $ gem install redis_message_capsule
+    # 3.a Either: Send messages on the channel:
+    > catChannel.send('meeeooow')
+    > catChannel.send('roooaaar')
 
-## Usage
+    # 3.b Or: Handle the messages that are recieved on the channel:
+    > messageHandler = { |message| doSomethingWith(message) }
+    > catChannel.register(messageHandler) 
+
+    # 4. Create as many channels and listeners as you want, using the capsule.
+
+    # 5. Create as many capsules as you want (only need one capsule for each redisURL:dbNumber )
+
+The purpose of RedisMessageCapsule is to enable separate apps to communicate with each other asynchronously.
+
+So, normally, one app would do the sending and another would listen for the message.
+However, nothing restricts the same app from doing the sending as well as receiving its own message.
+
+This is not your typical pub/sub model as messages are not broadcast to all apps that are listening on a channel.
+
+## Advanced Usage
+If multiple apps are listening on a channel, only one will actually receive the message.
+Each app can register multiple handlers for a channel, but only one app will actually get the message for processing.
+
+In ruby, the listeners will block waiting for a message, so the app that is waiting the longest would get the message.
+
+With node, however, there is no guarentee of order, since the listeners are not blocking the event loop.
+
+## Demonstration
+Below are code demonstrations for sending messages between 2 apps (node apps, ruby apps and a combination of both).
 
-Open terminal window one (to send messages):
+* Make sure redis is running
+* Data or object being sent will automatically be serialized to json (in order to teleport through redis)
+  * in node: using obj.toJSON() or JSON.stringify(obj)
+  * in rails: using obj.to_json 
+* Demo for node <-> node: Open 2 terminal windows to send messages between 2 node apps  (outlined below)
+* Demo for ruby <-> ruby: Open 2 terminal windows to send messages between 2 ruby apps  (outlined below)
+* Demo for node <-> ruby: Open 4 terminal windows and do both of the demos above (which are outlined below)
+* Think of each window that you open as a stand-alone app
+
+### Demo for node <-> node
+In node window 1 - send cat messages:
+
+    $ node
+    RedisMessageCapsule = require('redis-message-capsule')
+    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.materializeCapsule(redisURL)
+    cat = capsule.materializeChannel('cat')
+    cat.send('meow')    // will show up in node window 2 (listening to cat)
+    cat.send('meow')    // will show up in node window 2 (listening to cat)
+ 
+In node window 2 - listen for cat messages, send messages from dog:
+
+    $ node
+    RedisMessageCapsule = require('redis-message-capsule')
+    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.materializeCapsule(redisURL)
+    cat = capsule.materializeChannel('cat')
+    cat.register( function(err, message){ console.log(message) }  ) 
+    // => meow
+    // => meow    
+    // create a dog channel to send messages to ruby, and start barking
+    dog = capsule.materializeChannel('dog')
+    dog.send('woof')  // will show up in ruby window 2 (listening to dog)
+
+In node window 1 - send more cat messages:
+
+    talk = { say: 'roar', time: new Date() }
+    cat.send(9)
+    cat.send( talk )
+    // Watch for real-time messages show up in node window 2:
+    // => 9 
+    // => {"say"=>"roar", "time"=>"2012-11-21T208:08:08.808Z"} 
+
+###  Demo for ruby <-> ruby
+In ruby window 1 - send dog messages:
 
     $ irb
     require 'redis_message_capsule'
-    channel_cat = RedisMessageCapsule.channel('cat')
-    channel_cat.send('meow')
-    channel_cat.send('meow')
+    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
+    capsule = RedisMessageCapsule.materialize_capsule redisURL
+    dog = capsule.materialize_channel 'dog'
+    dog.send 'bark'
 
-Open terminal window two (to listen for messages):
+In ruby window 2 -  listen for dog messages in ruby and send cat messages:
 
     $ irb
     require 'redis_message_capsule'
-    RedisMessageCapsule.listen('cat') do |msg| 
-        puts msg
-    end
-    # => meow
+    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
+    capsule = RedisMessageCapsule.materialize_capsule redisURL
+    dog = capsule.materialize_channel 'dog'
+    dog.register { |msg|  puts "#{msg}!" * 2 }
+    # => woof!woof!
+    # => bark!bark!
+    # create a cat channel to send messages to node
+    cat = capsule.materialize_channel 'cat'
+    cat.send 'purrr' # will show up in node window 2 (listening to cat)
+
+Back in ruby window 1 - send more dog messages:
+
+    talk = { say: 'grrrrrr', time: Time.now }
+    dog.send 2      # will show up in window 4 (listening to dog)
+    dog.send talk   # will show up in window 4 (listening to dog)
+    # Watch for real-time messages to show up in ruby window 2:
+    # => 2 
+    # => {"say"=>"grrrrrr", "time"=>"2012-11-21 08:08:08 -0800"} 
+    # => purr
 
-Go back to terminal window one:
+## Environment
+In order for 2 apps to send messages to each other, they must bind a capsule to the same redis DB and select the same db number.
 
-    channel_cat.send 9
-    channel_cat.send say: 'roar', time: Time.now
-    channel_cat.send :purr
+By default, RedisMessageCapsule will:
+* select 9 for test environment
+* select 8 for development environment
+* select 7 for production environment
+The selected db can also be overriden when materializing a capsule  (examples are below).
 
-Watch for messages in terminal window two:
+If 2 apps are not sending messages to each other:
+* check that they are both in the same environment (test, development, production)
+* or be sure to override using same dbNumber when materializing a capsule.
 
-    # => 9 
-    # => {"say"=>"roar", "time"=>"2012-11-19 23:16:08 -0800"} 
-    # => purr
+## Environment for node
+In node use one of the following to set your environment
+
+    process.env.NODE_ENV = 'test'          // redisDB.select 9
+    process.env.NODE_ENV = 'development'   // redisDB.select 8
+    process.env.NODE_ENV = 'production'    // redisDB.select 7
 
-(Make sure you have redis running)
+Alternatively, you can override these defaults for the redis db when materializing a capsule:
 
-## Comming Soon
+    RedisMessageCapsule = require('redis-message-capsule')
+    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
+    dbNumber = 5
+    capsule = RedisMessageCapsule.materializeCapsule(redisURL, dbNumber)
 
-A node.js version you can use to send messages back and forth between node and rails apps.
+## Environment for ruby
+In ruby use one of the following to set your environment
 
+    ENV["RACK_ENV"] = 'test'          // redisDB.select 9
+    ENV["RACK_ENV"] = 'development'   // redisDB.select 8
+    ENV["RACK_ENV"] = 'production'    // redisDB.select 7
+
+Alternatively, you can override these defaults for the redis db when materializing a capsule:
+
+    require 'redis_message_capsule'
+    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
+    dbNumber = 5
+    capsule = RedisMessageCapsule.materialize_capsule redisURL, dbNumber
+
+## To build the gem locally:
+    git clone git@github.com:arbind/redis_message_capsule-gem.git
+    cd redis_message_capsule-gem
+    bundle
+    
+    gem uninstall redis_message_capsule
+    gem build redis_message_capsule.gemspec
+    rake install
 
 ## Contributing
 

data/lib/redis_message_capsule/version.rb

@@ -1,3 +1,3 @@
 module RedisMessageCapsule
-  VERSION = "0.0.1"
+  VERSION = "0.8.0"
 end

data/lib/redis_message_capsule.rb

@@ -3,144 +3,179 @@ require 'redis'
 require 'json'
 require 'uri'
 
+
+# class declaration
 module RedisMessageCapsule
   class Configuration
-    attr_accessor :environment, :db_number, :redis_url
-
-    def initialize
-      self.environment = ENV["RACK_ENV"] || "development"
-      self.db_number = 7 if self.environment.eql? 'production'
-      self.db_number = 8 if self.environment.eql? 'development'
-      self.db_number = 9 if self.environment.eql? 'test'
-      self.db_number ||= 9
-      self.redis_url = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://localhost:6379/"
+  end
+  class Capsule
+    class Channel
+      class Listener
+      end
     end
   end
+end
+
 
+###
+# module
+###
+module RedisMessageCapsule
   class << self
-    attr_accessor :configuration, :redis_clients, :capsule_channels, :listener_threads, :handlers
+    attr_accessor :configuration, :capsules
   end
 
-  def self.redis_clients
-    @redis_clients ||=  {}
+  def self.config() configuration end
+  def self.configure() yield(configuration) if block_given? end
+  def self.configuration() @configuration ||=  Configuration.new end
+
+  def self.capsules() @capsules ||=  {} end
+  def self.make_capsule_key(url, db_num) "#{url}.#{db_num}" end
+  def self.materialize_capsule(redis_url=nil, db_number=-1)
+    url = redis_url || config.redis_url    
+    redis_uri = URI.parse(url) rescue nil
+    return nil if redis_uri.nil?
+
+    db_num = db_number
+    db_num = config.db_number if db_num < 0
+    key = (make_capsule_key url, db_num)
+
+    capsule = capsules[key] || (Capsule.new redis_uri, db_num)
+    capsules[key] = capsule
   end
+  def self.capsule(redis_url=nil, db_number=-1) materialize_capsule(redis_url, db_number) end # method alias)
 
-  def self.capsule_channels
-    @capsule_channels ||=  {}
+  def self.materialize_redis_client(redis_uri, db_number)
+    redis_client = Redis.new(:host => redis_uri.host, :port => redis_uri.port, :password => redis_uri.password) rescue nil
+    if redis_client.nil?
+      puts "!!!\n!!! Can not connect to redis server at #{uri}\n!!!"
+      return nil
+    end
+    redis_client.select db_number rescue nil
+    redis_client
   end
 
-  def self.listener_threads
-    @listener_threads ||=  {}
+end
+
+class RedisMessageCapsule::Configuration
+  attr_accessor :environment, :redis_url, :db_number
+  def initialize
+    self.environment = ENV["RACK_ENV"] || "development"
+    self.db_number = 7 if self.environment.eql? 'production'
+    self.db_number = 8 if self.environment.eql? 'development'
+    self.db_number = 9 if self.environment.eql? 'test'
+    self.db_number ||= 9
+    self.redis_url = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
   end
+end
+
+class RedisMessageCapsule::Capsule
+  attr_accessor :redis_client, :redis_uri, :db_number, :channels
 
-  def self.configuration
-    @configuration ||=  Configuration.new
+  def initialize(redis_uri, db_number)
+    @redis_uri = redis_uri
+    @db_number = db_number
+    @channels = {}
+    @redis_client = RedisMessageCapsule.materialize_redis_client @redis_uri, @db_number
   end
-  def self.config() configuration end
 
-  def self.configure
-    yield(configuration) if block_given?
+  def materialize_channel(channel_name)
+    channels[channel_name] ||= (Channel.new channel_name, redis_client, redis_uri, db_number)
   end
 
-  class Channel
-    attr_accessor :name, :redis_client
-    def initialize(name, redis_client)
-      self.name = name
-      self.redis_client = redis_client
-    end
+end
 
-    def send (message)
-      payload = { 'data' => message }
-      redis_client.rpush name, payload.to_json
-    end
+class RedisMessageCapsule::Capsule::Channel
+  attr_accessor :channel_name, :listener, :redis_client, :redis_uri, :db_number
 
+  def initialize(channel_name, redis_client, redis_uri, db_number )
+    self.channel_name = channel_name
+    self.redis_client = redis_client
+    self.redis_uri = redis_uri
+    self.db_number = db_number
+    @listener = nil
   end
 
-  def self.make_client_key(url, db_num)
-    "#{url}.#{db_num}"
+  def send (message)
+    payload = { 'data' => message }
+    redis_client.rpush channel_name, payload.to_json
+  rescue Exception => e
+    puts e.message
+    puts e.backtrace
+  ensure
+    self # chainability
   end
-
-  def self.make_channel_key(name, url, db_num)
-    "#{name}.#{url}.#{db_num}"
+  alias_method :emit, :send
+  alias_method :message, :send
+
+  def register(&block)
+    raise "listen_for(#{channel_name}): No callback was specified!" unless block_given?
+    @listener ||= (Listener.new channel_name, redis_uri, db_number) # listener needs its own connection since it blocks
+    @listener.register(&block)
+    self # chainability
   end
+  alias_method :on, :register
+  alias_method :listen, :register
 
-  def self.make_listener_key(channels, url, db_num)
-    [ *channels, url, db_num].join('.')
+  def unregister(&block)
+    # +++
   end
 
-  def self.channel(name, redis_url=nil, db_number=-1)
-    url = redis_url || config.redis_url
-    db_num = db_number
-    db_num = config.db_number if db_num < 0
-
-    channel_key = make_channel_key(name, url, db_num)
-    return capsule_channels[channel_key] unless capsule_channels[channel_key].nil?
+  def stop_listening
+    # +++
+  end
 
-    client_key = make_client_key(url, db_num)
-    redis_client = redis_clients[client_key]
+end
 
-    if redis_client.nil?
-      uri = URI.parse(url)
-      redis_client = Redis.new(:host => uri.host, :port => uri.port, :password => uri.password) rescue nil
-      if redis_client.nil?
-        puts "!!!\n!!! Can not connect to redis server at #{uri}\n!!!"
-        return nil
-      end
-      redis_client.select db_num
-      redis_clients[client_key] = redis_client
-    end
-    channel = Channel.new(name, redis_client)
-    capsule_channels[channel_key] = channel
-    channel
+class RedisMessageCapsule::Capsule::Channel::Listener
+  def initialize(channel_name, redis_uri, db_number)
+    @channel_name = channel_name
+    @redis_uri = redis_uri
+    @db_number = db_number
+    @handlers = []
+    @listener_thread = nil
   end
 
+  def register(&handler)
+    @handlers << handler
+    launch_listener if @listener_thread.nil?
+    handler
+  end
 
-  def self.listen(channels_array, redis_url=nil, db_number=-1)
-    url = redis_url || config.redis_url
-    db_num = db_number
-    db_num = config.db_number if db_num < 0
-    channels = *channels_array
-    key = make_listener_key(channels, url, db_number)
-    return true unless listener_threads[key].nil?
-    
-    listener_threads[key] = Thread.new do
-      Thread.current[:name] = :RedisMessageCapsule
-      Thread.current[:description] = "Listening for messages from #{url.to_s} on chanel: #{[*channels].join(',')} "
-
-      redis_client = nil # establish redis connection: 
-      until !redis_client.nil? and redis_client.ping
-        uri = URI.parse(url)
-        redis_client = Redis.new(:host => uri.host, :port => uri.port, :password => uri.password) rescue nil
-        if redis_client.nil?
-          puts "!!!\n!!! Can not connect to redis server at #{uri}\n!!!"
-          sleep 10
-        else
-          redis_client.select db_num
-          puts "connected!"
-          Thread.current[:redis_client] = redis_client
-        end
-      end
-
-      puts "Listening for messages on #{[*channels].join(', ')}"
-      loop do
-        channel_element = redis_client.blpop *channels, 0
-        channel = channel_element.first
-        element = channel_element.last
-        payload = ( JSON.parse(element) rescue {} )
-        message = payload['data']
-        # fire event on channel
-        puts "#{channel}: #{message}"
-        yield(message) if block_given?
-      end
-    end
+  def stop_listening
+    @listener_thread[:listening] = false unless @@listener_thread.nil?
   end
 
-end
+  def unregister(&handler) @handlers.delete handler end
 
+  def launch_listener
+    @listener_thread ||= Thread.new do
 
-def start_redis_listeners(channels_array, redis_url=nil)
-  channels = *channels_array
+      blocking_redis_client = RedisMessageCapsule.materialize_redis_client @redis_uri, @db_number
+      # This redis connection will block when popping, so it is created inside of its own thread 
 
-  url = redis_url || ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://localhost:6379/"
-  key = url.to_s + channels.to_s
-end
+      Thread.current[:name] = :RedisMessageCapsule
+      Thread.current[:chanel] = @channel_name
+      Thread.current[:description] = "Listening for '#{@channel_name}' messages from #{@redis_uri}"
+      Thread.current[:redis_client] = blocking_redis_client
+      Thread.current[:listening] = true
+
+      while Thread.current[:listening] do # listen forever
+        begin
+          channel_element = blocking_redis_client.blpop @channel_name, 0 # pop a message, or block the thread and wait till the next one
+          unless channel_element.nil?
+            ch = channel_element.first
+            element = channel_element.last
+            payload = ( JSON.parse(element) rescue {'data' => 'error parsing json!'} )
+            message = payload['data']
+            puts @handlers.count
+            @handlers.each { |handler| handler.call(message) }
+          end
+        rescue Exception => e
+          Thread.current[:listening] = false # stop listening
+        end
+      end # while
+    end # Thread.new
+  end # launch_listener
+
+end # class

data/redis_message_capsule.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |gem|
   gem.version       = RedisMessageCapsule::VERSION
   gem.authors       = ["Arbind"]
   gem.email         = ["arbind@carbonfive.com"]
-  gem.description   = "Send and receive real-time messages between applications (via redis)."
-  gem.summary       = ""
-  gem.homepage      = ""
+  gem.description   = "Send messages between node or rails apps asynchronously (via redis)."
+  gem.summary       = "See the README file for code demonstrations"
+  gem.homepage      = "https://github.com/arbind/redis_message_capsule-gem"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_message_capsule
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-20 00:00:00.000000000 Z
+date: 2012-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -91,7 +91,7 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Send and receive real-time messages between applications (via redis).
+description: Send messages between node or rails apps asynchronously (via redis).
 email:
 - arbind@carbonfive.com
 executables: []
@@ -107,7 +107,7 @@ files:
 - lib/redis_message_capsule/version.rb
 - redis_message_capsule.gemspec
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/arbind/redis_message_capsule-gem
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -130,6 +130,6 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: ''
+summary: See the README file for code demonstrations
 test_files:
 - spec/spec_helper.rb