pq-wsm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c57d60c589e660e163c69281336d7df78c743c4
+  data.tar.gz: 2db6479616a377cd2d0b5e38390aa35463ba4983
+SHA512:
+  metadata.gz: 57a65396a0b836c2c4380c11276b0789af30807abd8523b83ae91b24690208eaeec17396ed6ed4a686893dbc82fe38686e1f3fbaaab4f5b421c368fd04500b38
+  data.tar.gz: 37770ac8c7cbee10c60d8fedc599d5f3c492f424614c439c941ee6936fb087eb3232a1ed1589d7b57082a77afab1384c37491c264fd7a1fe4e06c34a3199b27a

data/README.md

@@ -0,0 +1,86 @@
+## PcQueues
+
+A Queue Management Gem with Redis backing.
+
+Copyright (c) ProctorCam Inc. 2014 All rights reserved
+
+### Installation
+
+Dependency: Rails, Database, PubNub
+
+Add the following to your Gemfile
+
+```ruby
+gem 'pc-queues', :git => 'git@gitlab.proctorcam.com:proctorcam-development/pc-queues', :branch => 'develop'
+```
+
+Run the install and migration generators
+
+```bash
+> rails g pc_queues:install
+> rails g pc_queues:migration
+> rake db:migrate
+```
+
+Update the initializer in config/initializers/pc_queues.rb to initialize the PubNub instance used.
+
+That's it - you're done setting up.
+
+### Getting Started
+
+Once you've got the gem setup. You'll designate Models as Enqueable and as Queue owners. Classes that are Enqueueable
+can be enqueued and dequeued from a Queue Classes that are Queue owners can have has_one and has_many relationships to
+Queues. 
+
+Queues are setup for single table inheritance, so you can derive from Queue to handle Class specific behavior.
+
+An ActiveRecordClass can be both a Queue owner and Enqueable.
+
+#### Setting Up to be a Queue Owner
+
+```ruby
+require 'pc_queues'
+
+class MyQueue < PcQueues::Queue
+end
+
+class MyModel < ActiveRecord::Base
+  include ACTS_AS_QUEUE_OWNER
+  
+  has_many_queues_as :my_queues
+  has_one_queue_as :fast_stuff, class_name: 'MyQueue'
+end
+```
+
+#### Setting Up to be a Queue Item
+
+```ruby
+require 'pc_queues'
+
+class MyModel < ActiveRecord::Base
+  include ACTS_AS_ENQUEABLE
+
+end
+```
+
+#### Queue Manipulation
+
+```ruby
+model = MyModel.create attr1: value1
+
+# has_one
+model.create_fast_stuff attr1: value1
+
+# has_many
+model.my_queues.create attr1: value1
+
+# Enqueue/Dequeue
+model.fast_stuff.enqueue my_acts_as_enqueuable_object
+
+my_acts_as_enqueuable_object = model.fast_stuff.dequeue
+
+
+# Queue Length
+length = model.fast_stuff.length
+
+```

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PcQueues'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/generators/pc_queues/install_generator.rb

@@ -0,0 +1,9 @@
+class PcQueues::InstallGenerator < ::Rails::Generators::Base
+  source_root File.expand_path('../templates', __FILE__)
+  desc "Installs PcQueues."
+
+  def install
+    template "initializer.rb", "config/initializers/pc_queues.rb"
+    readme "README"
+  end
+end

data/lib/generators/pc_queues/migration_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators/active_record'
+
+class PcQueues::MigrationGenerator < ::Rails::Generators::Base
+  include Rails::Generators::Migration
+  source_root File.expand_path('../templates', __FILE__)
+  desc "Installs PcQueues Gem migration file."
+
+  def install
+    migration_template 'migration.rb', 'db/migrate/create_pc_queues_tables.rb'
+  end
+
+  def self.next_migration_number(dirname)
+    ActiveRecord::Generators::Base.next_migration_number(dirname)
+  end
+end

data/lib/generators/pc_queues/templates/README

@@ -0,0 +1,15 @@
+===============================================================================
+
+There is a setup that will be needed before you use pc-queues.
+
+1 - You'll need to edit config/initializers/pc_queues.rb to setup the PubNub instance
+to use when publishing Queue activity and managing presence info.
+
+2 - Run the migration generator and migrate
+
+>  rails g pc_queues:migration
+>  rake db:migrate
+
+That's it, that's all. Enjoy!
+
+===============================================================================

data/lib/generators/pc_queues/templates/initializer.rb

@@ -0,0 +1,6 @@
+require 'pc_queues'
+
+PcQueues.config do |config|
+  #  PcQueues uses pubnub to update interested clients when things change
+  # config.the_pubnub = Pubnub::the_pubnub
+end

data/lib/generators/pc_queues/templates/migration.rb

@@ -0,0 +1,36 @@
+class CreatePcQueuesTables < ActiveRecord::Migration
+  def change
+    create_table :queues do |t|
+      t.string :name
+      t.string :type
+      t.boolean :is_in_cold_start, :default => false
+      t.integer :queue_owner_id
+      t.string :queue_owner_type
+    end
+    
+    create_table :queue_items do |t|
+      t.integer :position
+      t.integer :enqueued_time
+      t.integer :queue_id
+      t.integer :enqueable_id
+      t.string :enqueable_type
+      t.string :type
+    end
+    
+    create_table :queue_rule_sets do |t|
+      t.boolean :is_any, :default => false
+      t.integer :queue_id
+    end
+    
+    create_table :queue_rules do |t|
+      t.string :type
+      t.string :name
+      t.integer :numeric_value
+      t.string :string_value
+      t.integer :queue_rule_set_id
+      t.boolean :bool_value
+    end
+  end
+end
+
+

data/lib/pc_queues.rb

@@ -0,0 +1,43 @@
+#
+# This source file is part of project: PcQueues
+#
+# A Proctoring Workflow Platform
+#
+# Copyright (c) ProctorCam Inc. 2014 All rights reserved
+#
+
+module PcQueues
+  autoload :ActsAsQueueOwner,   "pc_queues/acts_as_queue_owner"
+  autoload :ActsAsEnqueable,    "pc_queues/acts_as_enqueable"
+  autoload :Queue,              "pc_queues/queue"
+  autoload :QueueRule,          "pc_queues/queue_rule"
+  autoload :PriorityQueueItem,  "pc_queues/priority_queue_item"
+  autoload :QueueItem,          "pc_queues/queue_item"
+  autoload :QueueRuleSet,       "pc_queues/queue_rule_set"
+  
+  module QueueRules
+    autoload :BooleanQueueRule,     "pc_queues/queue_rules/boolean_queue_rule"
+    autoload :NumericQueueRule,     "pc_queues/queue_rules/numeric_queue_rule"
+    autoload :SampleQueueRule,      "pc_queues/queue_rules/sample_queue_rule"
+    autoload :StringMatchQueueRule, "pc_queues/queue_rules/string_match_queue_rule"
+  end
+  
+  class << self
+    ##
+    # Configuration for PcQueues - see config/initializers/pc_queues.rb for details
+    #
+    def config
+      yield self
+    end
+    
+    def the_pubnub=(pubnub)
+      @@pubnub = pubnub
+    end
+    
+    def the_pubnub
+      @@pubnub
+    end
+    
+  end
+  
+end

data/lib/pc_queues/acts_as_enqueable.rb

@@ -0,0 +1,31 @@
+#
+# This source file is part of project: PcQueues
+#
+# A Proctoring Workflow Platform
+#
+# Copyright (c) ProctorCam Inc. 2014 All rights reserved
+#
+require 'active_support'
+
+module PcQueues
+  module ActsAsEnqueable
+    extend ActiveSupport::Concern
+
+    included do
+      acts_as_enqueuable
+    end
+    
+    module ClassMethods
+      def acts_as_enqueuable
+        # instances are enqueued with a polymorphic PcQueues::QueueItem instance
+        has_many :enqueued_with, :class_name => 'PcQueues::QueueItem', :as => :enqueable
+      
+        # queues will return the PcQueues::Queue instances that
+        # this object is in.
+        has_many :queues, :through => :enqueued_with
+        
+        before_destroy { |record| record.queues.each { |q| q.remove(record) } }
+      end
+    end
+  end
+end

data/lib/pc_queues/acts_as_queue_owner.rb

@@ -0,0 +1,30 @@
+#
+# This source file is part of project: PcQueues
+#
+# A Proctoring Workflow Platform
+#
+# Copyright (c) ProctorCam Inc. 2014 All rights reserved
+#
+require 'active_support'
+
+module PcQueues
+  module ActsAsQueueOwner
+    extend ActiveSupport::Concern
+  
+    module ClassMethods
+      def has_many_queues_as(symbol, options = {})
+        klass = options[:class_name] or symbol.to_s.camelize.singularize
+        # has_many symbol, options.merge(:as => :queue_owner, :dependent => :destroy, :conditions => {:type => klass})
+        has_many symbol, -> {where(type: klass)},  options.merge(:as => :queue_owner, :dependent => :destroy) #==at :condtions is deprecated in rails 4, so replaced it with this 
+      end
+
+      def has_one_queue_as(symbol, options = {})
+        klass = options[:class_name] or symbol.to_s.camelize.singularize
+        has_one symbol, -> {where(type: klass)}, options.merge(:as => :queue_owner, :dependent => :destroy) 
+        # has_one symbol, options.merge(:as => :queue_owner, :dependent => :destroy, :conditions => {:type => klass})
+      end
+      
+    end
+  end
+end
+

data/lib/pc_queues/priority_queue_item.rb

@@ -0,0 +1,13 @@
+#
+# This source file is part of project: PcQueues
+#
+# A Proctoring Workflow Platform
+#
+# Copyright (c) ProctorCam Inc. 2014 All rights reserved
+#
+module PcQueues
+  # PriorityQueueItems are a flavor of QueueItems that
+  # have higher priority.
+  class PriorityQueueItem < QueueItem
+  end
+end

data/lib/pc_queues/queue.rb

@@ -0,0 +1,312 @@
+#
+# This source file is part of project: PcQueues
+#
+# A Proctoring Workflow Platform
+#
+# Copyright (c) ProctorCam Inc. 2014 All rights reserved
+#
+module PcQueues
+  # TODO: handle PubNub failures more gracefully
+
+  class Queue < ActiveRecord::Base
+    def self.accessible_attributes
+      [:name, :is_in_cold_start]
+    end
+    # attr_accessible :name, :is_in_cold_start
+    
+    has_many :queue_items, dependent: :destroy, class_name: 'PcQueues::PriorityQueueItem'
+    has_many :priority_queue_items, dependent: :destroy, class_name: 'PcQueues::PriorityQueueItem'
+    has_many :queue_rule_sets, dependent: :destroy
+    
+    belongs_to :queue_owner, :polymorphic => true
+
+    class_attribute :enqueue_callbacks, :dequeue_callbacks, :enqueable_type, :eager_load_relations
+    
+    self.enqueue_callbacks = []
+    self.dequeue_callbacks = []
+    self.eager_load_relations = []
+    
+    class << self
+
+      # An array of Queue Ids that have at least one client looking at them
+      def active_queue_ids
+        PubSub.proctors_for_class_instances(PcQueues::Queue).keys
+      end
+      
+      # return Queue instances that have subscribers
+      def active_queues        
+        Queue.find(active_queue_ids)
+      end
+      
+      # Publish statistics for all "active" queues, where
+      # the length is non-zero and there are active subscribers.
+      #
+      # Returns the active queues
+      def publish_active_queues
+        aq = active_queues
+        
+        aq.each do |queue|
+          PubSub.publish(
+            :channel => "pc-queue-#{queue.id}",
+            :message => {
+              :qualifier => "stats",
+              :data => queue.stats
+            }
+          ) { |data| }          
+        end
+        
+        aq
+      end
+
+      # Publish positions for all queue items in the queues provided
+      # if they have someone looking at them.
+      #
+      # The data published for each queue item is JSON-encoded:
+      # * position
+      # * estimated_time_left (in seconds)
+      #
+      def publish_positions(queues)
+        queues.each do |queue|
+          queue.publish_positions()
+        end
+      end
+
+      # Provide one or more callbacks to call before an item has been enqueued
+      #
+      # @param callbacks (symbol) the method name of the class that receives one
+      # parameters: the dequeued enqueable
+      def on_enqueue(*callbacks)
+        self.enqueue_callbacks = callbacks
+      end
+
+      # Provide one or more callbacks to call before an item has been dequeued
+      #
+      # @param callbacks (symbol) the method name of the class that receives one
+      # parameters: the dequeued enqueable
+      def on_dequeue(*callbacks)
+        self.dequeue_callbacks = callbacks
+      end
+
+      def enqueues(klass)
+        self.enqueable_type = klass
+      end
+
+      def eagerly_load(relations)
+        self.eager_load_relations = relations
+      end    
+
+    end
+    
+
+    # A list of all the elements in this queue
+    def enqueables(options = {})
+      @enqueables ||= queue_items.includes(:enqueable).where(options).map{ |queue_item| queue_item.enqueable }
+    end
+
+    def length()
+      # Due to Single Table Inheritance queue_items.count will count all types.
+      # This will include priority queue items as well.
+      queue_items.count
+    end
+
+
+    def priority_length()
+      priority_queue_items.count
+    end
+    
+    # The current queue_item advancement rate
+    # Returns 0 if there is no item.
+    def rate()
+      first = queue_items.first
+      first and first.rate
+    end
+    
+    # The current estimated wait time in seconds for items
+    # added to the queue. Returns 0 if there are no items.
+    def wait_time()
+      first = queue_items.first
+      first and first.wait_time
+    end
+    
+    # Enqueue an Object onto the Queue
+    def enqueue(obj)
+      with_lock do
+        # queue_item = obj.enqueued_with.create enqueued_time: Time.now.to_i, position: (length + 1), :queue => self
+        queue_item = queue_items.create enqueued_time: Time.now.to_i, position: (length + 1), enqueable: obj
+
+        enqueue_queue_item queue_item
+      end
+
+      obj
+    end
+
+    # Enqueue an object onto the queue with high priority
+    # -> it will get dequeued before any enqueables that were
+    #    added with `enqueue`
+    def priority_enqueue(obj)
+      with_lock do
+        queue_item = priority_queue_items.create enqueued_time: Time.now.to_i, position: (priority_length + 1), enqueable: obj
+
+        enqueue_queue_item queue_item
+      end
+      
+      obj
+    end
+    
+    # enqueue an object if it passes the rules for this queue
+    def enqueue_if_passes(enqueable, *args)
+      enqueue(enqueable) if rules_pass(enqueable, *args)
+    end
+    
+    # Dequeue an Object from a Queue. The Object
+    # will no longer be in the Queue.
+    def dequeue()
+      obj = nil
+      
+      while true do
+        begin 
+          with_lock do
+            # Check priority_queue_items first, then queue_items
+            q_item = (priority_queue_items.first or queue_items.first)
+      
+            return nil unless q_item
+
+            obj = q_item.enqueable
+      
+            ActiveRecord::Associations::Preloader.new(obj, eager_load_relations).run
+
+            q_item.delete
+          end
+        rescue
+          # OK - Collided on a dequeued item, go try again.
+          next
+        end
+        # We've got an item, break
+        break
+      end
+
+      PubSub.publish(
+        :channel => "pc-queue-#{id}",
+        :message => [{
+          :qualifier => "dequeued",
+          :data => { :id => obj.id }
+          }, stats_message]        
+      ) { |data| }          
+    
+      dequeue_callbacks.each { |callback| send callback, obj }
+      
+      obj
+    end
+    
+    # Remove a specific item from the Queue
+    def remove(obj)
+      begin   
+        with_lock do
+          q_item = queue_items.where(enqueable_id: obj.id).first
+        
+          return nil unless q_item
+
+          q_item.destroy
+        end
+      rescue
+        # Someone else beat us to the punch - just leave
+        return nil
+      end
+        
+      PubSub.publish(
+        :channel => "pc-queue-#{id}",
+        :message => [{
+          :qualifier => "removed",
+          :data => { :id => obj.id }
+          }, stats_message ]        
+      ) { |data| }          
+      
+      dequeue_callbacks.each { |callback| send callback, obj }
+
+      obj
+    end    
+    
+    # Determine if the rules for this queue pass
+    def rules_pass(enqueable, *args)
+      queue_rule_sets.includes(:queue_rules).all.each { |rule| return false unless rule.passes?(enqueable, *args) }
+      true
+    end
+    
+    # Return the next object to be dequeued without dequeuing
+    def peek()
+      (item = queue_items.first)
+      item.cur_position = 1 unless item.nil?
+      item
+    end
+    
+    # Current statistics for this queue
+    def stats
+      {
+        :length => length,
+        :rate => peek ? peek.rate : 0,
+        :longest_queue_wait => peek ? peek.wait_time : 0
+      }
+    end
+
+    # stats suitable for publishing
+    def stats_message
+      {
+        :qualifier => "stats",
+        :data => stats
+      }
+    end
+    
+    def publish_stats
+      PcQueues::the_pubnub.publish(
+        :channel => "pc-queue-#{id}",
+        :message => stats_message
+      ) { |data| }
+    end
+    
+    # Publish positions for this queue; see class method for more detail
+    def publish_positions
+      positionize()
+      queue_items.each do |item|
+        PubSub.publish(
+          :channel => "pc-queue-item-#{item.enqueable.id}",
+          :message => {
+            :qualifier => "stats",
+            :data => item.stats
+          }          
+          ) { |data| }
+      end
+    end
+    
+    protected
+    
+    # DRY code for handling the common code between the regular and priority queues
+    def enqueue_queue_item(item)
+      # If validations fail, then the item is already in the queue.
+      return unless item.valid?
+
+      PubSub.publish(
+        :channel => "pc-queue-#{id}",
+        :message => [{
+          :qualifier => "enqueued",
+          :data => { :id => item.enqueable.id }
+          }, stats_message]        
+      ) { |data| }          
+
+      enqueue_callbacks.each { |callback| send callback, item.enqueable }
+      item.enqueable
+    end
+    
+    # update the current position for Right Now of each queue item
+    def positionize
+      q_items = queue_items.select {|item| item.instance_of? ::PcQueues::QueueItem}
+      p_queue_items = queue_items.select {|item| item.instance_of? ::PcQueues::PriorityQueueItem}
+      (p_queue_items | q_items).each_with_index { |item, ndx| item.cur_position = ndx + 1 }
+    end
+    
+    # Convert an array of objects to a hash by ids
+    def objects_to_id_hash(objects)
+      Hash[objects.collect {|o| [o.id, o]}]
+    end
+    
+  end
+end