reliable-msg 1.0.1 → 1.1.0

data/lib/reliable-msg/rails.rb

@@ -0,0 +1,114 @@
+require "action_controller"
+
+module ActionController #:nodoc:
+
+    class Base
+
+        # Convenience method for accessing queues from your Rails controller.
+        #
+        # Use this method in your controller class to create an attribute for accessing
+        # the named queue. The method can be called in one of three ways:
+        # * With a +Symbol+. Adds the named attribute to access a queue with the same name.
+        # * With a +String+. Adds the attribute <tt>queue</tt> to access the named queue.
+        # * With a +Symbol+ and a +String+. Adds the named attribute to access the named
+        #   queue.
+        #
+        # For example
+        #  queue 'default'
+        #
+        #  def index
+        #    queue.put "some message"
+        #    render :text => "added message to queue 'default'"
+        #  end
+        #
+        # :call-seq:
+        #   queue symbol
+        #   queue symbol, name
+        #   queue name
+        #
+        def self.queue *args
+            raise ArgumentError, "Expecting a Symbol specifying the attribute name, a String specifying the queue name, or both" unless args.length > 0 && args.length <= 2
+            attr = name = nil
+            case args[0]
+            when String
+                raise ArgumentError, "When first argument is a String specifying the queue name, expecting to find only one argument" unless args.length == 1
+                attr = :queue
+                name = args[0]
+            when Symbol
+                attr = args[0]
+                if args.length == 1
+                    name = args[0].to_s
+                else
+                    raise ArgumetnError, "When first argument is a Symbol specifying the attribute name, expecting the second argument to be a String specifying the queue name or absent" unless args[1].instance_of?(String)
+                    name = args[1]
+                end
+            else
+                raise ArgumentError, "Expecting first argument to be a Symbol or a String"
+            end
+            quoted = "\"" << name.gsub("\"", "\\\"") << "\""
+
+            module_eval(<<-EOS, __FILE__, __LINE__ + 1)
+                @@queue_#{attr.to_s} = ReliableMsg::Queue.new(#{quoted})
+                def #{attr.to_s}(*args)
+                    raise ArgumentError, "Attribute #{attr} is accessed without any arguments, e.g. #{attr.to_s}.put(msg)" unless args.length == 0
+                    @@queue_#{attr.to_s}
+                end
+            EOS
+        end
+
+
+        # Convenience method for accessing topics from your Rails controller.
+        #
+        # Use this method in your controller class to create an attribute for accessing
+        # the named topic. The method can be called in one of three ways:
+        # * With a +Symbol+. Adds the named attribute to access a topic with the same name.
+        # * With a +String+. Adds the attribute <tt>topic</tt> to access the named topic.
+        # * With a +Symbol+ and a +String+. Adds the named attribute to access the named
+        #   topic.
+        #
+        # For example
+        #  topic :notification
+        #
+        #  def index
+        #    :notification.put "something new"
+        #    render :text => "added message to topic 'notification'"
+        #  end
+        #
+        # :call-seq:
+        #   topic symbol
+        #   topic symbol, name
+        #   topic name
+        #
+        def self.topic *args
+            raise ArgumentError, "Expecting a Symbol specifying the attribute name, a String specifying the topic name, or both" unless args.length > 0 && args.length <= 2
+            attr = name = nil
+            case args[0]
+            when String
+                raise ArgumentError, "When first argument is a String specifying the topic name, expecting to find only one argument" unless args.length == 1
+                attr = :topic
+                name = args[0]
+            when Symbol
+                attr = args[0]
+                if args.length == 1
+                    name = args[0].to_s
+                else
+                    raise ArgumetnError, "When first argument is a Symbol specifying the attribute name, expecting the second argument to be a String specifying the topic name or absent" unless args[1].instance_of?(String)
+                    name = args[1]
+                end
+            else
+                raise ArgumentError, "Expecting first argument to be a Symbol or a String"
+            end
+            quoted = "\"" << name.gsub("\"", "\\\"") << "\""
+
+            module_eval(<<-EOS, __FILE__, __LINE__ + 1)
+                @@topic_#{attr.to_s} = ReliableMsg::Topic.new(#{quoted})
+                def #{attr.to_s}(*args)
+                    raise ArgumentError, "Attribute #{attr} is accessed without any arguments, e.g. #{attr.to_s}.put(msg)" unless args.length == 0
+                    @@topic_#{attr.to_s}
+                end
+            EOS
+        end
+
+    end
+
+end

data/lib/reliable-msg/selector.rb

@@ -2,7 +2,7 @@
 # = selector.rb - Deferred expression evaluation selector
 #
 # Author:: Assaf Arkin  assaf@labnotes.org
-# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging
+# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging
 # Copyright:: Copyright (c) 2005 Assaf Arkin
 # License:: MIT and/or Creative Commons Attribution-ShareAlike
 #
@@ -10,98 +10,88 @@
 # presentation on domain specific languages, and the BlankSlate source code.
 #
 #--
-# Changes:
 #++
 
 module ReliableMsg #:nodoc:
 
+    # A message selector is used to retrieve specific messages from the queue
+    # by matching the message headers.
+    #
+    # The selector matches messages by calling the block for each potential
+    # message. The block can access (read-only) message headers by calling
+    # methods with the same name, or using <tt>[:symbol]</tt>. It returns true
+    # if a match is found.
+    #
+    # The following three examples are equivalent:
+    #   selector = Queue::selector { priority > 2 }
+    #   selector = queue.selector { priority > 2 }
+    #   selector = Selector.new { [:priority] > 2 }
+    #
+    # The new function is always available and evaluates to the current time
+    # (in seconds from the Epoch).
+    #
+    # This example uses the delivery count and message creation date/time to
+    # implement a simple retry with back-out:
+    #
+    #   MINUTE = 60
+    #   HOUR = MINUTE * 60
+    #   BACKOUT = [ 5 * MINUTE, HOUR, 4 * HOUR, 12 * HOUR ]
+    #
+    #   selector = Queue::selector { delivered == 0 || BACKOUT[delivered - 1] + created <= now }
     class Selector
 
-            # We're using DRb. Unless we support respond_to? and instance_eval?, DRb will
-            # refuse to marshal the selector as an argument and attempt to create a remote
-            # object instead.
-            instance_methods.each { |name| undef_method name unless name =~ /^(__.*__)|respond_to\?|instance_eval$/ }
-
-            def initialize &block
-                # Call the block and hold the deferred value.
-                @value = self.instance_eval &block
-            end
-
-            def method_missing symbol, *args
-                if symbol == :__evaluate__
-                    # Evaluate the selector with the headers passed in the argument.
-                    @value.is_a?(Deferred) ? @value.__evaluate__(*args) : @value
-                else
-                    # Create a deferred value for the missing method (a header).
-                    raise ArgumentError, "Can't pass arguments to header" unless args.empty?
-                    Header.new symbol
-                end
-            end
-
-
-        class Deferred #:nodoc:
-
-            # We're using DRb. Unless we support respond_to? and instance_eval?, DRb will
-            # refuse to marshal the selector as an argument and attempt to create a remote
-            # object instead.
-            instance_methods.each { |name| undef_method name unless name =~ /^(__.*__)|respond_to\?|instance_eval$/ }
-
-            def initialize target, operation, args
-                @target = target
-                @operation = operation
-                @args = args
-            end
-
-            def coerce value
-                [Constant.new(value), self]
-            end
-
-            def method_missing symbol, *args
-                if symbol == :__evaluate__
-
-                    eval_args = @args.collect { |arg| arg.instance_of?(Deferred) ? arg.__evaluate__(*args) : arg }
-                    @target.__evaluate__(*args).send @operation, *eval_args
-                else
-                    Deferred.new self, symbol, args
-                end
-            end
+        ERROR_INVALID_SELECTOR_BLOCK = "Selector must be created with a block accepting no arguments" #:nodoc:
 
+        # Create a new selector that evaluates by calling the block.
+        #
+        # :call-seq:
+        #   Selector.new { |headers| ... } -> selector
+        #
+        def initialize &block
+            raise ArgumentError, ERROR_INVALID_SELECTOR_BLOCK unless block && block.arity < 1
+            @block = block
         end
 
-        class Header < Deferred #:nodoc:
 
-            def initialize name
-                @name = name
-            end
+        # Matches the message headers with the selectors. Returns true
+        # if a match is made, false otherwise. May raise an error if
+        # there's an error in the expression.
+        #
+        # :call-seq:
+        #   selector.match(headers) -> boolean
+        #
+        def match headers #:nodoc:
+            context = EvaluationContext.new headers
+            context.instance_eval(&@block)
+        end
+
+
+    end
+
 
-            def coerce value
-                [Constant.new(value), self]
-            end
+    class EvaluationContext #:nodoc:
 
-            def method_missing symbol, *args
-                if symbol == :__evaluate__
-                    args[0][@name]
-                else
-                    Deferred.new self, symbol, args
-                end
-            end
+        instance_methods.each { |name| undef_method name unless name =~ /^(__.*__)|instance_eval$/ }
 
+
+        def initialize headers
+            @headers = headers
         end
 
-        class Constant < Deferred #:nodoc:
 
-            def initialize value
-                @value = value
-            end
+        def now
+            Time.now.to_i
+        end
+
+
+        def [] symbol
+            @headers[symbol]
+        end
 
-            def method_missing symbol, *args
-                if symbol == :__evaluate__
-                    @value
-                else
-                    Deferred.new self, symbol, args
-                end
-            end
 
+        def method_missing symbol, *args, &block
+            raise ArgumentError, "Wrong number of arguments (#{args.length} for 0)" unless args.empty?
+            @headers[symbol]
         end
 
     end

data/lib/reliable-msg/topic.rb

@@ -0,0 +1,215 @@
+#
+# = topic.rb - Publish to topic API
+#
+# Author:: Assaf Arkin  assaf@labnotes.org
+# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging
+# Copyright:: Copyright (c) 2005 Assaf Arkin
+# License:: MIT and/or Creative Commons Attribution-ShareAlike
+#
+#--
+#++
+
+require 'drb'
+require 'reliable-msg/client'
+require 'reliable-msg/selector'
+
+
+module ReliableMsg
+
+    # == Pub/Sub Topic API
+    #
+    # Use the Topic object to publish a message on a topic, get messages from topics.
+    #
+    # You can create a Topic object that connects to a single topic by passing the
+    # topic name to the initialized. You can also access other topics by specifying
+    # the destination topic when putting a message.
+    #
+    # For example:
+    #   topic = Topic.new 'my-topic'
+    #   # Publish a message on the topic, expiring in 30 seconds.
+    #   msg = 'lorem ipsum'
+    #   mid = topic.put msg, :expires=>30
+    #   # Retrieve and process a message on the topic.
+    #   topic.get do |msg|
+    #     if msg.id == mid
+    #       print "Retrieved same message"
+    #     end
+    #     print "Message text: #{msg.object}"
+    #   end
+    #
+    # See Topic.get and Topic.put for more examples.
+    class Topic < Client
+
+        INIT_OPTIONS = [:expires, :drb_uri, :tx_timeout, :connect_count]
+
+        # The optional argument +topic+ specifies the topic name. The application can
+        # still publish messages on other topics by specifying the destination topics
+        # name in the header.
+        #
+        # The following options can be passed to the initializer:
+        # * <tt>:expires</tt> -- Message expiration in seconds. Default for new messages.
+        # * <tt>:drb_uri</tt> -- DRb URI for connecting to the queue manager. Only
+        #   required when using a remote queue manager, or different port.
+        # * <tt>:tx_timeout</tt> -- Transaction timeout. See tx_timeout.
+        # * <tt>:connect_count</tt> -- Connection attempts. See connect_count.
+        #
+        # :call-seq:
+        #   Topic.new([name [,options]])    -> topic
+        #
+        def initialize topic = nil, options = nil
+            options.each do |name, value|
+                raise RuntimeError, format(ERROR_INVALID_OPTION, name) unless INIT_OPTIONS.include?(name)
+                instance_variable_set "@#{name.to_s}".to_sym, value
+            end if options
+            @topic = topic
+            @seen = nil
+        end
+
+
+        # Publish a message on the topic.
+        #
+        # The +message+ argument is required, but may be +nil+
+        #
+        # Headers are optional. Headers are used to provide the application with additional
+        # information about the message, and can be used to retrieve messages (see Topic.get
+        # for discussion of selectors). Some headers are used to handle message processing
+        # internally (e.g. <tt>:expires</tt>).
+        #
+        # Each header uses a symbol for its name. The value may be string, numeric, true/false
+        # or nil. No other objects are allowed. To improve performance, keep headers as small
+        # as possible.
+        #
+        # The following headers have special meaning:
+        # * <tt>:topic</tt> -- Publish the onn the named topic. Otherwise, uses the topic
+        #   specified when creating this Topic object.
+        # * <tt>:expires</tt> -- Message expiration in seconds. Messages do not expire unless
+        #   specified. Zero or +nil+ means no expiration.
+        # * <tt>:expires_at</tt> -- Specifies when the message expires (timestamp). Alternative
+        #   to <tt>:expires</tt>.
+        #
+        # Headers can be set on a per-topic basis when the Topic is created. This only affects
+        # messages put through that Topic object.
+        #
+        # For example:
+        #   topic.put updates
+        #   topic.put notice, :expires=>10
+        #   topic.put object, :topic=>'other-topic'
+        #
+        # :call-seq:
+        #   topic.put(message[, headers])
+        #
+        def put message, headers = nil
+            tx = Thread.current[THREAD_CURRENT_TX]
+            # Use headers supplied by callers, or defaults for this topic.
+            defaults = {
+                :expires=> @expires
+            }
+            headers = headers ? defaults.merge(headers) : defaults
+            # Serialize the message before sending to queue manager. We need the
+            # message to be serialized for storage, this just saves duplicate
+            # serialization when using DRb.
+            message = Marshal::dump message
+            # If inside a transaction, always send to the same queue manager, otherwise,
+            # allow repeated() to try and access multiple queue managers.
+            if tx
+                tx[:qm].publish(:message=>message, :headers=>headers, :topic=>(headers[:topic] || @topic), :tid=>tx[:tid])
+            else
+                repeated { |qm| qm.publish :message=>message, :headers=>headers, :topic=>(headers[:topic] || @topic) }
+            end
+        end
+
+
+        # Get a message on the topic.
+        #
+        # Call with no arguments to retrieve the last message published on the topic. Call with
+        # selectors to retrieve only matching messages. See also Queue.get.
+        #
+        # The following headers have special meaning:
+        # * <tt>:id</tt> -- The message identifier.
+        # * <tt>:created</tt> -- Indicates timestamp (in seconds) when the message was created.
+        # * <tt>:expires_at</tt> -- Indicates timestamp (in seconds) when the message will expire,
+        #   +nil+ if the message does not expire.
+        #
+        # Call this method without a block to return the message. The returned object is of type
+        # Message, or +nil+ if no message is found.
+        #
+        # Call this method in a block to retrieve and process the message. The block is called with
+        # the Message object, returning the result of the block. Returns +nil+ if no message is found.
+        #
+        # All operations performed on the topic inside the block are part of the same transaction.
+        # See Queue.get for discussion about transactions. Note that retry counts and delivery modes
+        # do not apply to Topics. A message remains published on the topic until replaced by another
+        # message.
+        #
+        # :call-seq:
+        #   topic.get([selector]) -> msg or nil
+        #   topic.get([selector]) {|msg| ... } -> obj
+        #
+        # See: Message
+        #
+        def get selector = nil, &block
+            tx = old_tx = Thread.current[THREAD_CURRENT_TX]
+            # If block, begin a new transaction.
+            if block
+                tx = {:qm=>qm}
+                tx[:tid] = tx[:qm].begin tx_timeout
+                Thread.current[THREAD_CURRENT_TX] = tx
+            end
+            result = begin
+                # Validate the selector: nil or hash.
+                selector = case selector
+                    when Hash, Selector, nil
+                        selector
+                    else
+                        raise ArgumentError, ERROR_INVALID_SELECTOR
+                end
+                # If inside a transaction, always retrieve from the same queue manager,
+                # otherwise, allow repeated() to try and access multiple queue managers.
+                message = if tx
+                    tx[:qm].retrieve :seen=>@seen, :topic=>@topic, :selector=>(selector.is_a?(Selector) ? nil : selector), :tid=>tx[:tid]
+                else
+                    repeated { |qm| qm.retrieve :seen=>@seen, :topic=>@topic, :selector=>(selector.is_a?(Selector) ? nil : selector) }
+                end
+                # Result is either message, or result from processing block. Note that
+                # calling block may raise an exception. We deserialize the message here
+                # for two reasons:
+                # 1. It creates a distinct copy, so changing the message object and returning
+                #    it to the queue (abort) does not affect other consumers.
+                # 2. The message may rely on classes known to the client but not available
+                #    to the queue manager.
+                result = if message
+                    # Do not process message unless selector matches. Do not mark
+                    # message as seen either, since we may retrieve it if the selector
+                    # changes.
+                    if selector.is_a?(Selector)
+                        return nil unless selector.match message[:headers]
+                    end
+                    @seen = message[:id]
+                    message = Message.new(message[:id], message[:headers], Marshal::load(message[:message]))
+                    block ? block.call(message) : message
+                end
+            rescue Exception=>error
+                # Abort the transaction if we started it. Propagate error.
+                qm.abort(tx[:tid]) if block
+                raise error
+            ensure
+                # Resume the old transaction.
+                Thread.current[THREAD_CURRENT_TX] = old_tx if block
+            end
+            # Commit the transaction and return the result. We do this outside the main
+            # block, since we don't abort in case of error (commit is one-phase) and we
+            # don't retain the transaction association, it completes by definition.
+            qm.commit(tx[:tid]) if block
+            result
+        end
+
+
+        # Returns the topic name.
+        def name
+            @topic
+        end
+
+    end
+
+end
+