qup 1.1.0

data/lib/qup/adapter/maildir/queue.rb

@@ -0,0 +1,123 @@
+require 'qup/producer'
+require 'qup/consumer'
+
+class Qup::Adapter::Maildir
+  #
+  # Internal: The Qup Implementation in the Maildir Adapter
+  #
+  class Queue
+    include Qup::QueueAPI
+    # Internal: the name of the Queue
+    attr_reader :name
+
+    # Internal: Create a new Queue
+    #
+    # root_path - the root_path for this Queue to create under
+    # name      - the String name of the Queue
+    #
+    # Returns a new Queue.
+    def initialize( root_path, name )
+      @root_path  = ::Pathname.new( root_path )
+      @name       = name
+      @queue_path = @root_path + @name
+      @maildir    = ::Maildir.new( @queue_path, true )
+    end
+
+
+    # Internal: Remove the Queue from the system
+    #
+    # Returns nothing.
+    def destroy
+      @queue_path.rmtree
+    end
+
+
+    # Internal: Remove all messages from the Queue
+    #
+    # Returns nothing.
+    def flush
+      ::Maildir::SUBDIRS.each do |sub|
+        dir = Pathname.new( File.join( @maildir.path, sub.to_s ))
+        dir.children.each do |p|
+          p.delete if p.file?
+        end
+      end
+    end
+
+
+    # Internal: return the number of Messages on the Queue
+    #
+    # Returns an integer of the Queue depth
+    def depth
+      total = 0
+      %w[ new cur ].each do |subdir|
+        search_path = File.join( @maildir.path, subdir, '*' )
+        keys = Dir.glob( search_path )
+        total += keys.size
+      end
+      return total
+    end
+
+
+    # Internal: Put an item onto the Queue
+    #
+    # message - the data to put onto the queue.
+    #
+    # The 'message' that is passed in is wrapped in a Qup::Message before being
+    # stored.
+    #
+    # A user of the Qup API should use a Producer instance to put items onto the
+    # queue.
+    #
+    # Returns the Message that was put onto the Queue
+    def produce( message )
+      msg = @maildir.add( message )
+      return ::Qup::Message.new( msg.key, msg.data )
+    end
+
+
+    # Internal: Retrieve a Message from the Queue
+    #
+    # Yields a Message
+    #
+    # A user of the Qup API should use a Consumer instance to retrieve items
+    # from the Queue.
+    #
+    # Returns a Message
+    def consume(&block)
+      msg = @maildir.list(:new, :limit => 1).first
+      return nil if msg.nil?
+      msg.process
+      msg.seen!
+      q_message = ::Qup::Message.new( msg.key, msg.data )
+      if block_given? then
+        yield_message( q_message, &block )
+      else
+        return q_message
+      end
+    end
+
+
+    # Internal: Acknowledge that message is completed and remove it from the
+    # Queue.
+    #
+    # Returns nothing
+    def acknowledge( message )
+      md_message = @maildir.get( message.key )
+      msg = "Message #{message.key} has not been processed yet"
+      raise ::Qup::Error, msg unless md_message.dir == :cur
+      raise ::Qup::Error, msg unless md_message.seen?
+      md_message.destroy
+    end
+
+    #######
+    private
+    #######
+
+    def yield_message( message, &block )
+      yield message
+    ensure
+      acknowledge( message )
+    end
+  end
+end

data/lib/qup/adapter/maildir/topic.rb

@@ -0,0 +1,85 @@
+class Qup::Adapter::Maildir
+  #
+  # Internal: A Topic for use in a publish-subscribe Messaging
+  #
+  # The topic delivers each Message that it is give to each and every Subscriber
+  #
+  class Topic
+    include Qup::TopicAPI
+
+    # Internal: the name of the Topic
+    attr_reader :name
+
+    # Internal: Create a new Topic
+    #
+    # root_path - the Session this Topic is attached to
+    # name      - the String name of the Topic
+    #
+    # Returns a new Topic.
+    def initialize( root_path, name )
+      @root_path   = ::Pathname.new( root_path )
+      @name        = name
+      @topic_path  = @root_path + @name
+      @subscribers = Hash.new
+
+      FileUtils.mkdir_p( @topic_path )
+    end
+
+    # Internal: Destroy the Topic
+    #
+    # If possible remove the existence of the Topic from the System
+    #
+    # Returns nothing.
+    def destroy
+      @topic_path.rmtree
+    end
+
+    # Internal: Creates a Publisher for the Topic
+    #
+    # Returns a new Publisher
+    def publisher
+      ::Qup::Publisher.new( self )
+    end
+
+    # Internal: Create a subscriber for the Topic
+    #
+    # name - the String name of the subscriber
+    #
+    # Creating a subscriber creates a new Subscriber that will receive a copy of
+    # every message that is published to the Topic.
+    #
+    # Subscribers are unique by name, two subscribers with the same name will
+    # act as individual Consumers on a queue of their name.
+    #
+    # Returns a Subscriber
+    def subscriber( name )
+      ::Qup::Subscriber.new( self, sub_queue( name )  )
+    end
+
+    # Internal: Return the number of Subscribers to this Topic
+    #
+    # Returns integer
+    def subscriber_count
+      @subscribers.size
+    end
+
+    # Internal: Publish a Message to all the Subscribers
+    #
+    # message - the Object to send to all subscribers
+    #
+    # Returns nothing
+    def publish( message )
+      @subscribers.each do |name, sub|
+        sub.produce( message )
+      end
+    end
+
+    #######
+    private
+    #######
+
+    def sub_queue( name )
+      @subscribers[name] ||= ::Qup::Adapter::Maildir::Queue.new( @topic_path, name )
+    end
+  end
+end

data/lib/qup/adapter/redis.rb

@@ -0,0 +1,55 @@
+require 'qup/adapter'
+require 'redis'
+
+class Qup::Adapter
+  # Internal: The backing adapter for Qup that uses Redis as the messaging
+  # infrastructure
+  class Redis < ::Qup::Adapter
+
+    # Register this adapter as :redis
+    register :redis
+
+    # Internal: Create a new Redis Adapter
+    #
+    # uri - the URI instance for this adapter to use
+    def initialize( uri, options = {} )
+      @uri        = uri
+      @options    = options
+      @closed     = false
+    end
+
+    # Internal: Create a new Queue from this Adapter
+    #
+    # name - the String name of the Queue
+    #
+    # Returns a Qup::Queue
+    def queue( name )
+      Qup::Adapter::Redis::Queue.new( @uri, name )
+    end
+
+    # Internal: Create a new Topic from this Adapter
+    #
+    # name - the name of this Topic
+    #
+    # Returns a Qup::Topic
+    def topic( name )
+      Qup::Adapter::Redis::Topic.new( @uri, name )
+    end
+
+    # Internal: Close the Redis adapter
+    #
+    # Return nothing
+    def close
+      @closed = true
+    end
+
+    # Internal: Is the Redis Adapter closed
+    #
+    # Returns true or false
+    def closed?
+      @closed
+    end
+  end
+end
+require 'qup/adapter/redis/queue'
+require 'qup/adapter/redis/topic'

data/lib/qup/adapter/redis/connection.rb

@@ -0,0 +1,32 @@
+class Qup::Adapter::Redis
+  #
+  # Internal: The Common base class for Redis Topic and Queue
+  #
+  class Connection
+
+    # Public: the name of the Queue or Topic
+    attr_reader :name
+
+    # Public: Create a new Connection
+    #
+    # uri  - the connection uri for the Redis Client
+    # name - the String name of the Connection
+    #
+    # Returns a new Connection.
+    def initialize( uri, name )
+      @uri    = uri
+      @client = Redis.new :host => @uri.host, :port => @uri.port
+      @name   = name
+    end
+
+    # Public: destroy the connection
+    #
+    # Closes the redis client connection.
+    #
+    # Returns nothing.
+    def destroy
+      @client.client.disconnect
+    end
+
+  end
+end

data/lib/qup/adapter/redis/queue.rb

@@ -0,0 +1,97 @@
+require 'qup/adapter/redis/connection'
+
+class Qup::Adapter::Redis
+  #
+  # Internal: The Qup implementation for a Redis Queue
+  #
+  class Queue < Connection
+    include Qup::QueueAPI
+
+    # Internal: create a new Queue
+    #
+    # uri  - the connection uri for the Redis Client
+    # name - the String name of the Queue
+    #
+    # Returns a new Queue.
+    def initialize( uri, name )
+      super
+      @open_messages = {}
+    end
+
+    # Internal: Destroy the queue
+    #
+    # Removes the list from redis.
+    #
+    # Returns nothing.
+    def destroy
+      @client.del name
+    end
+
+    # Internal: Empty the queue
+    #
+    # In redis, this is accomplished by merely deleting the list. If anything
+    # new is added to it, the key is re-created on the server
+    #
+    # Returns nothing
+    alias :flush :destroy
+
+    # Internal: return the number of Messages on the Queue
+    #
+    # Returns an integer of the Queue depth
+    def depth
+      @client.llen name
+    end
+
+    # Internal: Acknowledge that message is completed and remove it from the
+    # Queue.
+    #
+    # In redis, this doesn't do anything at all. The tracking is only performed
+    # to meet the API requirements.
+    #
+    # Returns nothing.
+    def acknowledge( message )
+      open_msg = @open_messages.delete( message.key )
+      raise Qup::Error, "Message #{message.key} is not currently being consumed" unless open_msg
+    end
+
+    # Internal: Put an item onto the Queue
+    #
+    # message - the data to put onto the queue.
+    #
+    # The 'message' that is passed in is wrapped in a Qup::Message before being
+    # stored.
+    #
+    # Returns the Message that was put onto the Queue
+    def produce( message )
+      @client.lpush name, message
+      return ::Qup::Message.new( message.object_id, message )
+    end
+
+    # Internal: Retrieve a Message from the Queue
+    #
+    # Yields a Message
+    #
+    # Returns a Message
+    def consume(&block)
+      queue_name, data = @client.brpop @name, 0 # blocking pop
+      message = ::Qup::Message.new( data.object_id, data )
+      @open_messages[message.key] = message
+      if block_given? then
+        yield_message( message, &block )
+      else
+        return message
+      end
+    end
+
+    #######
+    private
+    #######
+
+    def yield_message( message, &block )
+      yield message
+    ensure
+      acknowledge( message )
+    end
+
+  end
+end

data/lib/qup/adapter/redis/topic.rb

@@ -0,0 +1,76 @@
+require 'qup/adapter/redis/connection'
+
+class Qup::Adapter::Redis
+  #
+  # Internal: The Qup implementation for a Redis Topic
+  #
+  # Based on the API requirements, this is not implemented with Redis pub/sub,
+  # rather it guarantees durability of all published messages by using
+  # sub-queues internally to deliver messages to subscribers.
+  #
+  class Topic < Connection
+    include Qup::TopicAPI
+
+    # Internal: create a new Topic
+    #
+    # uri  - the connection uri for the Redis Client
+    # name - the String name of the Topic
+    #
+    # Returns a new Topic.
+    def initialize(uri, name)
+      super
+      @subscribers = Hash.new
+    end
+
+    # Internal: Creates a Publisher for the Topic
+    #
+    # Returns a new Publisher
+    def publisher
+      ::Qup::Publisher.new( self )
+    end
+
+    # Internal: Create a subscriber for the Topic
+    #
+    # name - the String name of the subscriber
+    #
+    # Creating a subscriber creates a new Subscriber that will receive a copy of
+    # every message that is published to the Topic.
+    #
+    # Returns a Subscriber
+    def subscriber(name)
+      ::Qup::Subscriber.new( self, subscriber_queue_for(name) )
+    end
+
+    # Internal: Return the number of Subscribers to this Topic
+    #
+    # Returns integer
+    def subscriber_count
+      @subscribers.size
+    end
+
+    # Internal: Publish a Message to all the Subscribers
+    #
+    # message - the Object to send to all subscribers
+    #
+    # Returns nothing
+    def publish( message )
+      @subscribers.values.each do |subscriber|
+        subscriber.produce message
+      end
+    end
+
+    #######
+    private
+    #######
+
+    # Private: create and register new sub-Queue for the given subscriber
+    #
+    # name - the name of the subscriber
+    #
+    # Returns a Queue
+    def subscriber_queue_for(name)
+      @subscribers[name] ||=
+        ::Qup::Adapter::Redis::Queue.new(@uri, "#{@name}-#{name}")
+    end
+  end
+end