message_router 0.0.2 → 0.1.1

data/.rvmrc

@@ -1 +1 @@
-rvm use --create --install 1.8.7@message_router
+rvm use --install ree

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    message_router (0.0.2)
+    message_router (0.1.1)
 
 GEM
   remote: http://rubygems.org/

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Brad Gessler
+Copyright (c) 2009-2012 Brad Gessler
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,6 +1,6 @@
 = Message Router
 
-Message router is a Sinatra-like DSL for processing simple messages, like SMS messages or Tweets.
+Message router is a DSL for routing and processing simple messages, like SMS messages or Tweets.
 
 == Installation
 
@@ -8,54 +8,166 @@ Message router is a Sinatra-like DSL for processing simple messages, like SMS me
 
 == Example Code
 
-This is a contrived example for a Twitter message router, but it gives you an idea of how it works.
+See rdoc for MessageRouter::Router.build (lib/message_router/router.rb) for examples.
 
-    class TwitterRouter < MessageRouter
-      context :all_caps_with_numbers do
-        # All caps without numbers... but in a proc
-        context Proc.new{|r| r.message[:body] =~ /^[A-Z\s]+$/ } do
-          match /.+/ do
-            "STOP SHOUTING WITHOUT NUMBERS!"
-          end
-        end
-    
-        match /.+/ do
-          "STOP SHOUTING WITH NUMBERS!"
-        end
+And now some irb action.
+
+    1.8.7 :001 > class HelloRouter < MessageRouter::Router
+    1.8.7 :002?>     match /hi/ do
+    1.8.7 :003 >           puts "Hi there. You sent me: #{env.inspect}"
+    1.8.7 :004?>         true # puts returns nil, and that would fail the matcher
+    1.8.7 :005?>       end
+    1.8.7 :006?>   end
+     => [[/hi/, #<Proc:0x00000000026963b8@(irb):2>]] 
+    1.8.7 :007 > HelloRouter.new.call({'body' => 'can you say hi to me?'})
+    Hi there. You sent me: {'body'=>"can you say hi to me?"}
+     => true 
+    1.8.7 :008 > class MainRouter < MessageRouter::Router
+    1.8.7 :009?>     match({'to' => 'greeter'}, HelloRouter.new)
+    1.8.7 :010?>     match(true) do
+    1.8.7 :011 >           puts "WTF? I don't know how to do that!"
+    1.8.7 :012?>         true # puts returns nil, and that would fail the matcher
+    1.8.7 :013?>       end
+    1.8.7 :014?>   end
+     => [[{:to=>"greeter"}, #<HelloRouter:0x25fef90 @rules=[[#<Proc:0x000000000266b2d0@/home/paul/sc/pe/message_router/lib/message_router/router.rb:165>, #<Proc:0x00000000026963b8@(irb):2>]]>], [true, #<Proc:0x00000000025ff580@(irb):10>]] 
+    1.8.7 :015 > MainRouter.new.call({'body' => 'can you say hi to me?'})
+    WTF? I don't know how to do that!
+     => true 
+    1.8.7 :016 > MainRouter.new.call({'body' => 'can you say hi to me?', 'to' => 'greeter'})
+    Hi there. You sent me: {'body'=>"can you say hi to me?", 'to'=>"greeter"}
+     => true 
+
+
+== TODO
+
+Get docs working nicely (formatting, etc.) with RDoc.
+
+Add tests to ensure that instance variables can be shared between initializers and helpers. For example:
+    class MyRouter < MessageRouter::Router
+      def initilaize(config)
+        @sender = config[:sender]
+        super
       end
-  
-      match /hi dude/ do
-        "pleased to meet you"
+
+      match true do
+        send_something
       end
-  
-      match /hi (\w+)/ do |name|
-        "how do you do #{name}"
+
+      def send_something
+        @sender.puts 'something'
       end
-  
-      match /hola (\w+)/, :from => 'bradgessler' do |name|
-        "hello #{name} in spanish"
+    end
+    MyRouter.new(:sender => STDOUT).call({})  # prints out 'something' to standard out.
+
+Pass Regexp captures on to the proc when there is a match. Examples:
+    match /some (cool|awesome) thing/ do |match|
+      puts "You thought the thing was #{match[1]}"
+    end
+    match 'some_attr' => /some (cool|awesome) thing/, 'body' => /(.*)/ do |matches|
+      puts "You thought that #{matches['body'][1]} was #{matches['some_attr'][1]}"
+    end
+    -- OR --
+    match /some (cool|awesome) thing/ do
+      puts "You thought the thing was #{env['message_router_match'][1]}"
+    end
+    match 'some_attr' => /some (cool|awesome) thing/, 'body' => /(.*)/ do
+      puts "You thought that #{env['message_router_matches']['body'][1]} was #{env['message_router_matches']['some_attr'][1]}"
+    end
+    -- OR -- (probably best because it is simplest)
+    match /some (cool|awesome) thing(.*)/ do |word, the_rest|
+      puts "You thought the thing was #{word}. But the rest is #{the_rest}"
+    end
+    match 'some_attr' => /some (cool|awesome) thing(.*)/, 'body' => /(.*)/ do |hash|
+      puts "You thought that #{hash['body']} was #{hash['some_attr'][0]}. But the rest is #{hash['some_attr'][1]}"
+    end
+    -- OR -- (if the note below about setting context/scope of annonymous functions is done)
+    match /some (cool|awesome) thing(.*)/ do |word, the_rest|
+      puts "You thought the thing was #{word}. But the rest is #{the_rest}"
+    end
+    match 'some_attr' => /some (cool|awesome) thing(.*)/, 'body' => /(.*)/ do |hash|
+      puts "You thought that #{hash['body']} was #{hash['some_attr'][0]}. But the rest is #{hash['some_attr'][1]}"
+    end
+
+Improve specs to minimize use of global variables. The idea below about passing copies of the env hash around (instead of modifying it in place) might help here. I could have various bits of code being tested modify the env hash, and the final return value would be the env hash, which I could examine.
+
+Consider making the String matcher more flexible. There could be options for:
+* Exact match
+* Case sensitivity
+* Partial matches:
+  * starts with
+  * ends with
+  * contains
+
+Recursion detection: It could be done by having a specific key in the message hash for parents. Before sending #call to a matcher's proc we could run something like "message['message_router_stack'] << self". Then we could check the size of this. The maximum number of levels would need to be configurable to allow some recursion.
+* We could just rely on a stack overflow, but having recursion detection would make debugging easier.
+
+Make helper methods defined (or included) in parent routers available in sub routers. It could be done with delegation, but that might get messy. It may be easier to not implement this and just require the user to use sub-classing to get the desired behavior.
+
+Pass around copies of the env Hash instead of modifying the existing Hash in place.
+* This _might_ help with multi-threading
+  * Perhaps a parent router wants to delegate to 2 sub-routers which are independent of each other. The current implementation has a shared env hash, so I couldn't use multi-threading, (though forking could work). I would have to trust the user to call #dup on at least one of the env hashes. With this new way, it is safe by default.
+* Convention would be for the 'should_i' Procs to return a copy of the env hashes, either modified or not, depending on their needs.
+  * They would still return nil or false if they don't match.
+* We could also require (by convention only) that sub-routers also return a copy of the env hash (if they succeed) so this (optionally modified) env hash can be used for further routing.
+  * This would give the original router access to both the modified env hash and the original env hash.
+
+Find a way to allow user-defined 'do_this' procs/blocks to not have to return a true value to be considered to have matched. We still need a way to know if a sub-router matched or not. This _may_require that the code treat sub-routers and user-defined 'do_this' procs/blocks differently, which could get awkward.
+
+Allow routers to accept an optional logger. Depending on the log level, print out info such as:
+* When a matcher is registered
+* Each time a matcher is evaluated, including what the return value was.
+* Each time a 'do_this' block is evaluated, including what the return value was.
+Each time we write to the log include the following (depending on the log level):
+* The value of the env hash
+* The name of the class (so we can tell which subclass we are in)
+* Any instance variables set (so we know the config and if it changed)
+
+Consider creating some sort of RouterRun class, each instance of which would encapsulate a call to MessageRouter::Router#call. This class would have all the helper methods as well as the #env helper method. This may help make this gem more threadsafe by keeping the shared state in the MessageRouter::Router objects immutable.
+
+Consider having #call duplicate the router so that each run happens in its own instance. When MessageRouter::Router#call was called, call `self.dup.call(env, :no_dup)`. This would create a copy of the router for handling the message. It would be safe to use instance variables, except (maybe) deep-nested ones, but they could be handled by requiring the user to overwrite #dup.
+
+Consider having a class called Run nested within the router's namespace. Instead of allowing users to define helper methods inside the router, they would be defined inside a subclass of MessageGateway::Router::Run. MessageGateway::Router#call might look something like:
+    def call(env)
+      Run.new(env, self).run
+    end
+Run#run might look something like:
+    def run
+      router.rules.detect do |should_i, do_this|
+        should_i = if should_i.kind_of?(Proc)
+          self.instance_eval &should_i
+        else
+          should_i.call env
+        end
+
+        if should_i
+          do_this = if do_this.kind_of?(Proc)
+            self.instance_eval &do_this
+          else
+            do_this.call env
+          end
+
+          return do_this if do_this
+        end
       end
-  
-    private
-      def all_caps_with_numbers
-        message[:body] =~ /^[A-Z0-9\s]+$/
+    end
+A user's router might look like this:
+    class MyRouter < MessageRouter::Router
+      match :hello? { say 'hi' }
+      class Run < MessageRouter::Router::Run
+        def hello?
+          env['body'] == 'hi'
+        end
+        def say(msg)
+          puts msg
+        end
       end
     end
+This would make all instance variables inside the helpers safe and intuitive. I'd need to double check, but I think Ruby's constant lookup method would allow for inheritance to work fairly intuitively as long as the Run class and the router class both inherit from the same place. (I.e. if you inherit from MyBaseRouter, then your run class should also inherit from MyBaseRouter::Run.)
 
-And now some irb action.
-
-    >> TwitterRouter.new(:body => 'hi dude').dispatch
-    => {:body => "pleased to meet you"}
-    >> TwitterRouter.new(:body => 'hi brad').dispatch
-    => {:body => "how do you do brad"}
-    >> TwitterRouter.new(:body => 'HI BRAD 90').dispatch
-    => {:body => "STOP SHOUTING WITH NUMBERS!"}
-    >> TwitterRouter.new(:body => 'HI BRAD').dispatch
-    => {:body => "STOP SHOUTING WITHOUT NUMBERS!"}
 
 == License
 
-Copyright (c) 2010, Brad Gessler
+Copyright (c) 2009-2012, Brad Gessler
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -73,4 +185,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/lib/message_router.rb

@@ -1,73 +1,5 @@
 require "message_router/version"
 
 class MessageRouter
-
-  autoload :Context,  'message_router/context'
-  autoload :Matcher,  'message_router/matcher'
-  autoload :Mount,    'message_router/mount'
-
-  class << self
-    def match(*args, &block)
-      route Matcher.new(*args, &block)
-    end
-
-    def context(proc, &block)
-      route Context.new(proc, &block)
-    end
-
-    def mount(mounted_router_klass)
-      route Mount.new(mounted_router_klass)
-    end
-
-    def routes
-      @routes ||= []
-    end
-
-    def route(proc)
-      routes.push proc
-    end
-
-    def dispatch(*args)
-      new(*args).dispatch
-    end
-  end
-
-  attr_accessor :message, :halted_value
-
-  def initialize(*args)
-    @message = normalize_arguments(*args)
-  end
-
-  def halt(val=nil, opts={})
-    @halted = true
-    @halted_value = normalize_arguments(val, opts)
-  end
-
-  def halted?
-    !!@halted
-  end
-
-  # Iterate through all of the matchers, find the first one, and call the block on it.
-  def dispatch
-    self.class.routes.each do |route|
-      # Break out of the loop if a match is found
-      if match = route.call(self)
-        return match
-      elsif halted?
-        return halted_value
-      end
-    end
-    return nil # If nothing is matched, we get here and we should return a nil
-  end
-
-  def default_key
-    :body
-  end
-
-private
-  # Make our router accept the first argument as the default message key, then optional keys last.
-  def normalize_arguments(message=nil, opts={})
-    message = opts.merge(:body => message) unless message.is_a? Hash and opts.empty?
-    message
-  end
-end
+  autoload :Router,  'message_router/router'
+end

data/lib/message_router/router.rb

@@ -0,0 +1,320 @@
+class MessageRouter
+  # To define a router, subclass MessageRouter::Router, then call #match
+  # inside the class definition.
+  # An example:
+  #     class MyApp::Router::Application < MessageRouter::Router
+  #       # Share helpers between routers by including modules
+  #       include MyApp::Router::MyHelper
+  #
+  #       prerequisite :db_connected?
+  #
+  #       match SomeOtherRouter.new
+  #       # `mount` is an alias of `match`
+  #       mount AnotherRouter.new
+  #
+  #       match(lamba { env['from'].nil? }) do
+  #         Logger.error "Can't reply when when don't know who a message is from: #{env.inspect}"
+  #       end
+  #
+  #       match 'ping' do
+  #         PingCounter.increment!
+  #         send_reply 'pong', env
+  #       end
+  #
+  #       match /\Ahelp/i do
+  #         SupportQueue.contact_asap(env['from'])
+  #         send_reply 'Looks like you need some help. Hold tight someone will call you soon.', env
+  #       end
+  #
+  #       # StopRouter would have been defined just like this router.
+  #       match /\Astop/i, MyApp::Router::StopRouter
+  #
+  #       match 'to' => /(12345|54321)/ do
+  #         Logger.warn "Use of deprecated short code: #{msg.inspect}"
+  #         send_reply "Sorry, you are trying to use a deprecated short code. Please try again.", env
+  #       end
+  #
+  #       match :user_name => PriorityUsernameRouter.new
+  #       match :user_name, OldStyleUsernameRouter.new
+  #       match :user_name do
+  #         send_reply "I found you! Your name is #{user_name}.", env
+  #       end
+  #
+  #       match %w(stop end quit), StopRouter.new
+  #
+  #       # Array elements don't need to be the same type
+  #       match [
+  #         :user_is_a_tester,
+  #         {'to' => %w(12345 54321)},
+  #         {'RAILS_ENV' => 'test'},
+  #         'test'
+  #       ], TestRouter.new
+  #
+  #       # Works inside a Hash too
+  #       match 'from' => ['12345', '54321', /111\d\d/] do
+  #         puts "'#{env['from']}' is a funny looking short code"
+  #       end
+  #
+  #       match true do
+  #         UserMessage.create! env
+  #         send_reply "Sorry we couldn't figure out how to handle your message. We have recorded it and someone will get back to you soon.", env
+  #       end
+  #
+  #
+  #       def send_reply(body, env)
+  #         OutgoingMessage.deliver!(:body => body, :to => env['from'], :from => env['to'])
+  #       end
+  #
+  #       def user_name(env)
+  #         env['user_name'] ||= User.find(env['from'])
+  #       end
+  #
+  #       def db_connected?
+  #         Database.connected?
+  #       end
+  #     end
+  #
+  #     router = MyApp::Router::Application.new
+  #     router.call({})  # Logs an error about not knowing who the message is from
+  #     router.call({'from' => 'mr-smith', 'body' => 'ping'})  # Sends a 'pong' reply
+  #     router.call({'from' => 'mr-smith', 'to' => 12345})     # Sends a deprecation warning reply
+  class Router
+
+    class << self
+      # The 1st argument to a matcher can be:
+      # * true, false, or nil
+      # * String or Regexp, which match against env['body']. Strings match against
+      #   the 1st word.
+      # * Array - Elements can be Strings or Regexps. They are matched against
+      #   'body'. Matches if any element is matches.
+      # * Hash - Keys are expected to be a subset of the env's keys. The
+      #   values are String, Regexp, or Array to be match again the corresponding
+      #   value in the env Hash. True if there is a match for all keys.
+      # * Symbol - Calls a helper method of the same name. If the helper can take
+      #   an argument, the env will be passed to it. The return value of the
+      #   helper method determines if the matcher matches.
+      # * Anything that responds to #call - It is passed the env as the only
+      #   arugment. The return value determines if the matcher matches.
+      # Because Routers are trigged by the method #call, one _could_ use a Router
+      # as the 1st argument to a matcher. However, it would actually run that
+      # Router's code, which is not intuitive, and therefore not recommonded.
+      # If the 1st argument to a matcher resolves to a true value, then the 2nd
+      # argument is sent `#call(env)`. If that also returns a true value,
+      # then the matcher has "matched" and the router stops. However, if the 2nd
+      # argument returns false, then the router will continue running. This
+      # allows us to mount sub-routers and continue trying other rules if those
+      # subrouters fail to match something.
+      # The 2nd argument to #match can also be specified with a block.
+      # If the 1st argument is skipped, then it is assumed to be true. This is
+      # useful for passing a message to a sub-router, which will return nil if
+      # it doesn't match. For example:
+      #     match MyOtherRouter.new
+      # is a short-hand for:
+      #     match true, MyOtherRouter.new
+      # It is important to keep in mind that blocks, procs, and lambdas, whether
+      # they are the 1st or 2nd argument, will be run in the scope of the router,
+      # just like the methods referenced by Symbols. That means that they have
+      # access to all the helper methods. However, it also means they have the
+      # ability to edit/add instance variables on the router; NEVER DO THIS. If
+      # you want to use an instance variable inside a helper, block, proc, or
+      # lambda, you MUST use the env hash instance. Examples:
+      #     # BAD
+      #     match :my_helper do
+      #       @cached_user ||= User.find_by_id(@user_id)
+      #     end
+      #     def find_user
+      #       @id ||= User.get_id_from_guid(env['guid'])
+      #     end
+      #
+      #     # GOOD
+      #     match :my_helper do
+      #       env['cached_user'] ||= User.find_by_id(env['user_id'])
+      #     end
+      #     def find_user
+      #       env['id'] ||= User.get_id_from_guid(env['guid'])
+      #     end
+      # If you do not follow this requirement, then when subsequent keywords are
+      # routed, they will see the instance variables from the previous message.
+      # In the case of the above example, every subsequent message will have
+      # @cached_user set the the user for the 1st message.
+      def match *args, &block
+        args << block if block
+        case args.size
+        when 0
+          raise ArgumentError, "You must provide either a block or an argument which responds to call."
+        when 1
+          if args[0].respond_to?(:call)
+            should_i = true
+            do_this  = args[0]
+          elsif args[0].kind_of?(Hash) && args[0].values.size == 1 && args[0].values[0].respond_to?(:call)
+            # Syntactical suger to make:
+            #     match :cool? => OnlyForCoolPeopleRouter.new
+            # work just like:
+            #     match :cool?, OnlyForCoolPeopleRouter.new
+            should_i = args[0].keys[0]
+            do_this  = args[0].values[0]
+          else
+            raise ArgumentError, "You must provide either a block or a 2nd argument which responds to call."
+          end
+        when 2
+          should_i, do_this = args
+          raise ArgumentError, "The 2nd argument must respond to call." unless do_this.respond_to?(:call)
+        else
+          raise ArgumentError, "Too many arguments. Note: you may not provide a block when a 2nd argument has been provided."
+        end
+
+        # Save the arguments for later.
+        rules << [should_i, do_this]
+      end
+      alias :mount :match
+
+      # Defines a prerequisite for this router. Prerequisites are like rules,
+      # except that if any of them don't match, the rest of the router is
+      # skipped.
+      # Anything that can be the 1st argument to `match` can be passed as an
+      # argument to `prerequisite`.
+      def prerequisite(arg=nil, &block)
+        arg ||= block if block
+        prerequisites << arg
+      end
+
+      # The rules are defined at the class level. But any helper methods
+      # referenced by Symbols are defined/executed at the instance level.
+      def rules
+        @rules ||= []
+      end
+
+      def prerequisites
+        @prerequisites ||= []
+      end
+    end
+
+
+    # This method initializes all the rules stored at the class level. When you
+    # create your subclass, if you want to add your own initializer, it is very
+    # important to call `super` or none of your rules will be matched.
+    def initialize
+      @rules = []
+      # Actually create the rules so that the procs we create are in the
+      # context of an instance of this object. This is most important when the
+      # rule is based on a symbol. We need that symbol to resolve to an
+      # instance method; however, instance methods are not available until
+      # after an instance is created.
+      self.class.rules.each {|rule| match *rule }
+
+      @prerequisites = []
+      self.class.prerequisites.each {|prerequisite| @prerequisites << normalize_match_params(prerequisite) }
+    end
+
+    # Kicks off the router. 'env' is a Hash. The keys are up to the user;
+    # however, the default key (used when a matcher is just a String or Regexp)
+    # is 'body'. If you don't specify this key, then String and Regexp matchers
+    # will always be false.
+    # Returns nil if no rules match
+    # Returns true if a rule matches
+    # A rule "matches" if both its procs return true. For example:
+    #     match(true) { true }
+    # matches. However:
+    #     match(true) { false }
+    # does not count as a match. This allows us to mount sub-routers and
+    # continue trying other rules if those subrouters fail to match something.
+    # However, this does mean you need to be careful when writing the 2nd
+    # argument to #match. If you return nil or false, the router will keep
+    # looking for another match.
+    def call(env)
+      # I'm pretty sure this is NOT thread safe. Having two threads use the
+      # same router at the same time will almost certainly give you VERY weird
+      # and incorrect results. We may want to introduce a RouterRun object to
+      # encapsulate one invocation of this #call method.
+      @env = env
+
+      # All prerequisites must return true in order to continue.
+      return false unless @prerequisites.all? do |should_i|
+        if should_i.kind_of?(Proc)
+          self.instance_eval &should_i
+        else
+          should_i.call @env
+        end
+      end
+
+      @rules.detect do |should_i, do_this|
+        should_i = if should_i.kind_of?(Proc)
+          self.instance_eval &should_i
+        else
+          should_i.call @env
+        end
+
+        if should_i
+          do_this = if do_this.kind_of?(Proc)
+            self.instance_eval &do_this
+          else
+            do_this.call @env
+          end
+
+          return true if do_this
+        end
+      end
+    ensure
+      @env = nil
+    end
+
+
+    private
+    def env; @env; end
+
+    def match(should_i, do_this)
+      @rules << [normalize_match_params(should_i), do_this]
+    end
+
+    def normalize_match_params(should_i=nil, &block)
+      should_i ||= block if block
+
+      case should_i
+      when Regexp, String
+        # TODO: Consider making this default attribute configurable.
+        normalize_match_params 'body' => should_i
+
+      when TrueClass, FalseClass, NilClass
+        Proc.new { should_i }
+
+      when Symbol
+        Proc.new do
+          self.send should_i
+        end
+
+      when Array
+        should_i = should_i.map {|x| normalize_match_params x}
+        Proc.new do
+          should_i.any? { |x| x.call env }
+        end
+
+      when Hash
+        Proc.new do
+          should_i.all? do |key, val|
+            attr_matches? env[key], val
+          end
+        end
+
+      else
+        # Assume it already responds to #call.
+        should_i
+      end
+
+    end
+
+    def attr_matches?(attr, val)
+      case val
+      when String
+        attr =~ /\A#{val}\b/i # Match 1st word
+      when Regexp
+        attr =~ val
+      when Array
+        val.any? do |x|
+          attr_matches? attr, x
+        end
+      else
+        raise "Unexpected value '#{val.inspect}'. Should be String, Regexp, or Array of Strings and Regexps."
+      end
+    end
+  end
+end