electric_slide 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b6b7652ebb0629af9310a93d7c6ac0352fd92c8
-  data.tar.gz: f5fd82735d7d8949b14a4ea8ee318c096820092f
+  metadata.gz: 7b7f9f14186f1dee1e5d75e38e79f6c1c127522e
+  data.tar.gz: 4f44af8a5750560e6f802227e36227142fba373f
 SHA512:
-  metadata.gz: 9b9bafc665557361a51d504d71d94d2775a8e68924a22600e23a68f8b53acb7a2fcb85a3197e797e0c8af7cccc272f606d63f651c9a654f0aa9e2dc2aa69ac7a
-  data.tar.gz: 85da4abe01db3cd099748cc11ada5c59383c38b8ac1e1994adaa01f98d9d6af05db659e767e6dae6cdef3c4fbae42c414689d9af2d09a670142b1355ec820caa
+  metadata.gz: 7d3f04f5f1ce98f47913ba04fed0da9cf827c9e1bed80e9e6731e0e22e371b6214e1e03550213a7f48abcf3259732b538ea75a71b8d65fc436311cd240d2747f
+  data.tar.gz: 6cf73dd16a211f07e738e0cbd779e1a099e88786e57ec087763cfa58c1b77a84917c2e39020354fad302ee4a11de36a0907d002925da38a1276b9a571aafdd4a

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -1,3 +1,3 @@
-source :rubygems
+source 'https://rubygems.org'
 gemspec
 

data/Guardfile

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+group 'rspec' do
+  guard 'rspec', cmd: 'bundle exec rspec' do
+    watch(%r{^spec/.+_spec\.rb$})
+    watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+    watch('spec/spec_helper.rb')  { "spec/" }
+  end
+end

data/README.markdown

@@ -1,3 +1,153 @@
-AhnQueue - Automatic Call Distribution (ACD) Services for Adhearsion
+Electric Slide - Simple Call Distribution for Adhearsion
 ====================================================================
 
+This library implements a simple FIFO (First-In, First-Out) call queue for Adhearsion.
+
+To ensure proper operation, a few things are assumed:
+
+* Agents will only be logged into a single queue at a time
+    If you have two types of agents (say "support" and "sales") then you should have two queues, each with their own pool of agents
+* Agent authentication will happen before entering the queue - it is not the queue's concern
+* The strategy for callers is FIFO: the caller who has been waiting the longest is the next to get an agent
+* Queues will be implemented as a Celluloid Actor, which should protect the call selection strategies against race conditions
+* There are two ways to connect an agent:
+  - If the Agent object provides an `address` attribute, and the queue's `connection_type` is set to `call`, then the queue will call the agent when a caller is waiting
+  - If the Agent object provides a `call` attribute, and the queue's `connection_type` is set to `bridge`, then the call queue will bridge the agent to the caller. In this mode, the agent hanging up will log him out of the queue
+
+TODO:
+* Example for using Matrioska to offer Agents and Callers interactivity while waiting
+* How to handle MOH
+
+## WARNING!
+
+While you can have ElectricSlide keep track of custom queues, it is recommended to use the built-in CallQueue object.
+
+The authors of ElectricSlide recommend NOT to subclass, monkeypatch, or otherwise alter the CallQueue implementation, as the likelihood of creating subtle race conditions is high.
+
+Example Queue
+-------------
+
+```ruby
+my_queue = ElectricSlide.create :my_queue, ElectricSlide::CallQueue
+
+# Another way to get a handle on a queue
+ElectricSlide.create :my_queue
+my_queue = ElectricSlide.get_queue :my_queue
+```
+
+
+Example CallController for Queued Call
+--------------------------------------
+
+```ruby
+class EnterTheQueue < Adhearsion::CallController
+  def run
+    answer
+
+    # Play music-on-hold to the caller until joined to an agent
+    player = play 'http://moh-server.example.com/stream.mp3', repeat_times: 0
+    call.on_joined do
+      player.stop!
+    end
+
+    ElectricSlide.get_queue(:my_queue).enqueue call
+
+    # The controller will exit, but the call will remain up
+    # The call will automatically hang up after speaking to an agent
+    call.auto_hangup = false
+  end
+end
+```
+
+
+Adding an Agent to the Queue
+----------------------------
+
+ElectricSlide expects to be given a objects that quack like an agent. You can use the built-in `ElectricSlide::Agent` class, or you can provide your own.
+
+To add an agent who will receive calls whenever a call is enqueued, do something like this:
+
+```ruby
+agent = ElectricSlide::Agent.new id: 1, address: 'sip:agent1@example.com', presence: :available
+ElectricSlide.get_queue(:my_queue).add_agent agent
+```
+
+To inform the queue that the agent is no longer available you *must* use the ElectricSlide queue interface. /Do not attempt to alter agent objects directly!/
+
+```ruby
+ElectricSlide.update_agent 1, presence: offline
+```
+
+If it is more convenient, you may also pass `#update_agent` an Agent-like object:
+
+```ruby
+options = {
+  id: 1,
+  address: 'sip:agent1@example.com',
+  presence: offline
+}
+agent = ElectricSlide::Agent.new options
+ElectricSlide.update_agent 1, agent
+```
+
+Switching connection types
+--------------------------
+
+ElectricSlide provides two methods for connecting callers to agents:
+- `:call`: (default) If the Agent object provides an `address` attribute, and the queue's `connection_type` is set to `call`, then the queue will call the agent when a caller is waiting
+- `:bridge`: If the Agent object provides a `call` attribute, and the queue's `connection_type` is set to `bridge`, then the call queue will bridge the agent to the caller. In this mode, the agent hanging up will log him out of the queue
+
+To select the connection type, specify it when creating the queue:
+
+```ruby
+ElectricSlide.create_queue :my_queue, ElectricSlide::CallQueue, connection_type: :bridge
+```
+
+Selecting an Agent distribution strategy
+----------------------------------------
+
+Different use-cases have different requirements for selecting the next agent to take a call.  ElectricSlide provides two strategies which may be used. You are also welcome to create your own distribution strategy by implementing the same interface as described in `ElectricSlide::AgentStrategy::LongestIdle`.
+
+To select an agent strategy, specify it when creating the queue:
+
+```ruby
+ElectricSlide.create_queue :my_queue, ElectricSlide::CallQueue, agent_strategy: ElectricSlide::AgentStrategy::LongestIdle
+```
+
+Two strategies are provided out-of-the-box:
+
+* `ElectricSlide::AgentStrategy::LongestIdle` selects the agent that has been idle for the longest amount of time.
+* `ElectricSlide::AgentStrategy::FixedPriority` selects the agent with the lowest numeric priority first.  In the event that more than one agent is available at a given priority, then the agent that has been idle the longest at the lowest numeric priority is selected.
+
+Custom Agent Behavior
+----------------------------
+
+If you need custom functionality to occur whenever an Agent is selected to take a call, you can use the callbacks on the Agent object:
+
+* `on_connect`
+* `on_disconnect`
+
+Confirmation Controllers
+------------------------
+
+In case you need to execute a confirmation controller on the call that is placed to the agent, such as "Press 1 to accept the call", you currently need to pass in the confirmation class name and the call object as metadata in the `call_options_for` callback in your `ElectricSlide::Agent` subclass.
+
+```ruby
+# an example from the Agent subclass
+def dial_options_for(queue, queued_call)
+  {
+    from: caller_digits(queued_call.from),
+    timeout: on_pstn? ? APP_CONFIG.agent_timeout * 3 : APP_CONFIG.agent_timeout,
+    confirm: MyConfirmationController,
+    confirm_metadata: {caller: queued_call, agent: self},
+  }
+end
+```
+
+You then need to handle the join in your confirmation controller, using for example:
+
+```ruby
+call.join metadata[:caller] if confirm!
+```
+
+where `confirm!` is your logic for deciding if you want the call to be connected or not. Hanging up during the confirmation controller or letting it finish without any action will result in the call being sent to the next agent.

data/Rakefile

@@ -10,7 +10,6 @@ require 'bundler/setup'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new
 
-require 'ci/reporter/rake/rspec'
-task :ci => ['ci:setup:rspec', :spec]
-task :default => :spec
+task ci: ['ci:setup:rspec', :spec]
+task default: :spec
 

data/electric_slide.gemspec

@@ -1,8 +1,11 @@
+# encoding: utf-8
+$:.push File.expand_path("../lib", __FILE__)
+require 'electric_slide/version'
 require 'date'
 
 Gem::Specification.new do |s|
   s.name = "electric_slide"
-  s.version = "0.0.2"
+  s.version = ElectricSlide::VERSION
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ben Klang"]
@@ -23,8 +26,9 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'countdownlatch'
   s.add_runtime_dependency 'activesupport'
   s.add_development_dependency 'rspec', ['>= 2.5.0']
-  s.add_development_dependency 'flexmock', ['>= 0.9.0']
   s.add_development_dependency 'ci_reporter'
+  s.add_development_dependency 'guard'
+  s.add_development_dependency 'guard-rspec'
   s.add_development_dependency 'simplecov'
   s.add_development_dependency 'simplecov-rcov'
 

data/lib/electric_slide.rb

@@ -1,65 +1,68 @@
+# encoding: utf-8
+require 'celluloid'
 require 'singleton'
-require 'active_support/dependencies/autoload'
-require 'adhearsion/foundation/thread_safety'
 
-class ElectricSlide < Adhearsion::Plugin
-  extend ActiveSupport::Autoload
+require 'adhearsion/version'
 
-  autoload :QueueStrategy
-  autoload :RoundRobin
-  autoload :RoundRobinMeetme
+if Gem::Version.new(Adhearsion::VERSION) < Gem::Version.new('3.0.0')
+  # Backport https://github.com/adhearsion/adhearsion/commit/8c6855612c70dd822fb4e4c2006d1fdc9d05fe23 to avoid confusion around dead calls
+  require 'adhearsion/call'
+  class Adhearsion::Call::ActorProxy < Celluloid::ActorProxy
+    def active?
+      alive? && super
+    rescue Adhearsion::Call::ExpiredError
+      false
+    end
+  end
+end
+
+%w(
+  call_queue
+  plugin
+).each { |f| require "electric_slide/#{f}" }
 
+class ElectricSlide
   include Singleton
 
   def initialize
+    @mutex = Mutex.new
     @queues = {}
   end
 
-  def create(name, queue_type, agent_type = Agent)
-    synchronize do
-      @queues[name] = queue_type.new unless @queues.has_key?(name)
-      @queues[name].extend agent_type
-    end
-  end
+  def create(name, queue_class = nil, *args)
+    fail "Queue with name #{name} already exists!" if @queues.key? name
 
-  def get_queue(name)
-    synchronize do
-      @queues[name]
-    end
+    queue_class ||= CallQueue
+    @queues[name] = queue_class.work *args
+    # Return the queue instance or current actor
+    get_queue name
   end
 
-  def self.method_missing(method, *args, &block)
-    instance.send method, *args, &block
+  def get_queue!(name)
+    fail "Queue #{name} not found!" unless @queues.key?(name)
+    get_queue name
   end
 
-  module Agent
-    def work(agent_call)
-      loop do
-        agent_call.execute 'Bridge', @queue.next_call
-      end
+  def get_queue(name)
+    queue = @queues[name]
+    if queue.respond_to? :actors
+      # In case we have a Celluloid supervision group, get the current actor
+      queue.actors.first
+    else
+      queue
     end
   end
 
-  class CalloutAgent
-    def work(agent_channel)
-      @queue.next_call.each do |next_call|
-        next_call.dial agent_channel
-      end
-    end
+  def shutdown_queue(name)
+    queue = get_queue name
+    queue.terminate
+    @queues.delete name
   end
 
-  class MeetMeAgent
-    include Agent
-
-    def work(agent_call)
-      loop do
-        agent_call.join agent_conf, @queue.next_call
-      end
+  def self.method_missing(method, *args, &block)
+    @@mutex ||= Mutex.new
+    @@mutex.synchronize do
+      instance.send method, *args, &block
     end
   end
-
-  class BridgeAgent
-    include Agent
-  end
 end
-

data/lib/electric_slide/agent.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+class ElectricSlide::Agent
+  attr_accessor :id, :address, :presence, :call, :connect_callback, :disconnect_callback
+
+  # @param [Hash] opts Agent parameters
+  # @option opts [String] :id The Agent's ID
+  # @option opts [String] :address The Agent's contact address
+  # @option opts [Symbol] :presence The Agent's current presence. Must be one of :available, :on_call, :away, :offline
+  def initialize(opts = {})
+    @id = opts[:id]
+    @address = opts[:address]
+    @presence = opts[:presence]
+  end
+
+  def callback(type, *args)
+    callback = self.class.instance_variable_get "@#{type}_callback"
+    instance_exec *args, &callback if callback && callback.respond_to?(:call)
+  end
+
+
+  # Provide a block to be called when this agent is connected to a caller
+  # The block will be passed the queue, the agent call and the client call
+  def self.on_connect(&block)
+    @connect_callback = block
+  end
+
+  # Provide a block to be called when this agent is disconnected to a caller
+  # The block will be passed the queue, the agent call and the client call
+  def self.on_disconnect(&block)
+    @disconnect_callback = block
+  end
+
+  # Called to provide options for calling this agent that are passed to #dial
+  def dial_options_for(queue, queued_call)
+    {}
+  end
+
+  def join(queued_call)
+    # For use in queues that need bridge connections
+    @call.join queued_call
+  end
+
+  # FIXME: Use delegator?
+  def from
+    @call.from
+  end
+end
+

data/lib/electric_slide/agent_strategy/fixed_priority.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+class ElectricSlide
+  class AgentStrategy
+    class FixedPriority
+      def initialize
+        @priorities = {}
+      end
+
+      def agent_available?
+        !!@priorities.detect do |priority, agents|
+          agents.present?
+        end
+      end
+
+      # Returns information about the number of available agents
+      # The data returned depends on the AgentStrategy in use.
+      # @return [Hash] Summary information about agents available, depending on strategy
+      # :total: The total number of available agents
+      # :priorities: A Hash containing the number of available agents at each priority
+      def available_agent_summary
+        @priorities.inject({}) do |summary, data|
+          priority, agents = *data
+          summary[:total] ||= 0
+          summary[:total] += agents.count
+          summary[:priorities] ||= {}
+          summary[:priorities][priority] = agents.count
+          summary
+        end
+      end
+
+      def checkout_agent
+        _, agents = @priorities.detect do |priority, agents|
+          agents.present?
+        end
+        agents.shift
+      end
+
+      def <<(agent)
+        # TODO: How aggressively do we check for agents duplicated in multiple priorities?
+        raise ArgumentError, "Agents must have a specified priority" unless agent.respond_to?(:priority)
+        priority = agent.priority || 999999
+        @priorities[priority] ||= []
+        @priorities[priority] << agent unless @priorities[priority].include? agent
+      end
+
+      def delete(agent)
+        @priorities.detect do |priority, agents|
+          agents.delete(agent)
+        end
+      end
+    end
+  end
+end
+

data/lib/electric_slide/agent_strategy/longest_idle.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+class ElectricSlide
+  class AgentStrategy
+    class LongestIdle
+      def initialize
+        @free_agents = [] # Needed to keep track of waiting order
+      end
+
+      # Checks whether an agent is available to take a call
+      # @return [Boolean] True if an agent is available
+      def agent_available?
+        @free_agents.count > 0
+      end
+
+      # Returns a count of the number of available agents
+      # @return [Hash] Hash of information about available agents
+      # This strategy only returns the count of agents available with :total
+      def available_agent_summary
+        { total: @free_agents.count }
+      end
+
+      # Assigns the first available agent, marking the agent :busy
+      # @return {Agent}
+      def checkout_agent
+        @free_agents.shift
+      end
+
+      def <<(agent)
+        @free_agents << agent unless @free_agents.include?(agent)
+      end
+
+      def delete(agent)
+        @free_agents.delete(agent)
+      end
+    end
+  end
+end
+