electric_slide 0.0.2 → 0.2.0

data/lib/electric_slide/call_queue.rb

@@ -0,0 +1,335 @@
+# encoding: utf-8
+
+# The default agent strategy
+require 'electric_slide/agent_strategy/longest_idle'
+
+class ElectricSlide
+  class CallQueue
+    include Celluloid
+    ENDED_CALL_EXCEPTIONS = [
+      Adhearsion::Call::Hangup,
+      Adhearsion::Call::ExpiredError,
+      Adhearsion::Call::CommandTimeout,
+      Celluloid::DeadActorError,
+      Punchblock::ProtocolError
+    ]
+
+    CONNECTION_TYPES = [
+      :call,
+      :bridge,
+    ].freeze
+
+    AGENT_RETURN_METHODS = [
+      :auto,
+      :manual,
+    ].freeze
+
+    def self.work(*args)
+      self.supervise *args
+    end
+
+    def initialize(opts = {})
+      agent_strategy   = opts[:agent_strategy]  || AgentStrategy::LongestIdle
+      @connection_type = opts[:connection_type] || :call
+      @agent_return_method = opts[:agent_return_method] || :auto
+
+      raise ArgumentError, "Invalid connection type; must be one of #{CONNECTION_TYPES.join ','}" unless CONNECTION_TYPES.include? @connection_type
+      raise ArgumentError, "Invalid requeue method; must be one of #{AGENT_RETURN_METHODS.join ','}" unless AGENT_RETURN_METHODS.include? @agent_return_method
+
+      @free_agents = [] # Needed to keep track of waiting order
+      @agents = []      # Needed to keep track of global list of agents
+      @queue = []       # Calls waiting for an agent
+
+      @strategy = agent_strategy.new
+    end
+
+    # Checks whether an agent is available to take a call
+    # @return [Boolean] True if an agent is available
+    def agent_available?
+      @strategy.agent_available?
+    end
+
+    # Returns information about the number of available agents
+    # The data returned depends on the AgentStrategy in use.
+    # The data will always include a :total count of the agents available
+    # @return [Hash] Summary information about agents available, depending on strategy
+    def available_agent_summary
+      # TODO: Make this a delegator?
+      @strategy.available_agent_summary
+    end
+
+    # Assigns the first available agent, marking the agent :busy
+    # @return {Agent}
+    def checkout_agent
+      agent = @strategy.checkout_agent
+      agent.presence = :busy
+      agent
+    end
+
+    # Returns a copy of the set of agents that are known to the queue
+    # @return [Array] Array of {Agent} objects
+    def get_agents
+      @agents.dup
+    end
+
+    # Returns a copy of the set of calls waiting to be answered that are known to the queue
+    # @return [Array] Array of Adhearsion::Call objects
+    def get_queued_calls
+      @queue.dup
+    end
+
+    # Finds an agent known to the queue by that agent's ID
+    # @param [String] id The ID of the agent to locate
+    # @return [Agent, Nil] {Agent} object if found, Nil otherwise
+    def get_agent(id)
+      @agents.detect { |agent| agent.id == id }
+    end
+
+    # Registers an agent to the queue
+    # @param [Agent] agent The agent to be added to the queue
+    def add_agent(agent)
+      abort ArgumentError.new("#add_agent called with nil object") if agent.nil?
+      case @connection_type
+      when :call
+        abort ArgumentError.new("Agent has no callable address") unless agent.address
+      when :bridge
+        abort ArgumentError.new("Agent has no active call") unless agent.call && agent.call.active?
+        unless agent.call[:electric_slide_callback_set]
+          agent.call.on_end { remove_agent agent }
+          agent.call[:electric_slide_callback_set] = true
+        end
+      end
+
+      logger.info "Adding agent #{agent} to the queue"
+      @agents << agent unless @agents.include? agent
+      @strategy << agent if agent.presence == :available
+      check_for_connections
+    end
+
+    # Marks an agent as available to take a call. To be called after an agent completes a call
+    # and is ready to take the next call.
+    # @param [Agent] agent The {Agent} that is being returned to the queue
+    # @param [Symbol] status The {Agent}'s new status
+    # @param [String, Optional] address The {Agent}'s address. Only specified if it has changed
+    def return_agent(agent, status = :available, address = nil)
+      logger.debug "Returning #{agent} to the queue"
+      agent.presence = status
+      agent.address = address if address
+
+      if agent.presence == :available
+        @strategy << agent
+        check_for_connections
+      end
+      agent
+    end
+
+    # Removes an agent from the queue entirely
+    # @param [Agent] agent The {Agent} to be removed from the queue
+    # @return [Agent, Nil] The Agent object if removed, Nil otherwise
+    def remove_agent(agent)
+      @strategy.delete agent
+      @agents.delete agent
+      logger.info "Removing agent #{agent} from the queue"
+    rescue Adhearsion::Call::ExpiredError
+    end
+
+    # Checks to see if any callers are waiting for an agent and attempts to connect them to
+    # an available agent
+    def check_for_connections
+      connect checkout_agent, get_next_caller while call_waiting? && agent_available?
+    end
+
+    # Add a call to the head of the queue. Among other reasons, this is used when a caller is sent
+    # to an agent, but the connection fails because the agent is not available.
+    # @param [Adhearsion::Call] call Caller to be added to the queue
+    def priority_enqueue(call)
+      # Don't reset the enqueue time in case this is a re-insert on agent failure
+      call[:enqueue_time] ||= Time.now
+      @queue.unshift call
+
+      check_for_connections
+    end
+
+    # Add a call to the end of the queue, the normal FIFO queue behavior
+    # @param [Adhearsion::Call] call Caller to be added to the queue
+    def enqueue(call)
+      ignoring_ended_calls do
+        logger.info "Adding call from #{remote_party call} to the queue"
+        call[:enqueue_time] = Time.now
+        @queue << call unless @queue.include? call
+
+        check_for_connections
+      end
+    end
+
+    # Remove a waiting call from the queue. Used if the caller hangs up or is otherwise removed.
+    # @param [Adhearsion::Call] call Caller to be removed from the queue
+    def abandon(call)
+      ignoring_ended_calls { logger.info "Caller #{remote_party call} has abandoned the queue" }
+      @queue.delete call
+    end
+
+    # Connect an {Agent} to a caller
+    # @param [Agent] agent Agent to be connected
+    # @param [Adhearsion::Call] call Caller to be connected
+    def connect(agent, queued_call)
+      unless queued_call.active?
+        logger.warn "Inactive queued call found in #connect"
+        return_agent agent
+      end
+
+      logger.info "Connecting #{agent} with #{remote_party queued_call}"
+      case @connection_type
+      when :call
+        call_agent agent, queued_call
+      when :bridge
+        unless agent.call.active?
+          logger.warn "Inactive agent call found in #connect, returning caller to queue"
+          priority_enqueue queued_call
+        end
+        bridge_agent agent, queued_call
+      end
+    rescue *ENDED_CALL_EXCEPTIONS
+      ignoring_ended_calls do
+        if queued_call.active?
+          logger.warn "Dead call exception in #connect but queued_call still alive, reinserting into queue"
+          priority_enqueue queued_call
+        end
+      end
+      ignoring_ended_calls do
+        if agent.call && agent.call.active?
+          logger.warn "Dead call exception in #connect but agent call still alive, reinserting into queue"
+          return_agent agent
+        end
+      end
+    end
+
+    def conditionally_return_agent(agent, return_method = @agent_return_method)
+      raise ArgumentError, "Invalid requeue method; must be one of #{AGENT_RETURN_METHODS.join ','}" unless AGENT_RETURN_METHODS.include? return_method
+
+      if agent && @agents.include?(agent) && agent.presence == :busy && return_method == :auto
+        logger.info "Returning agent #{agent.id} to queue"
+        return_agent agent
+      else
+        logger.debug "Not returning agent #{agent.inspect} to the queue"
+      end
+    end
+
+    # Returns the next waiting caller
+    # @return [Adhearsion::Call] The next waiting caller
+    def get_next_caller
+      @queue.shift
+    end
+
+    # Checks whether any callers are waiting
+    # @return [Boolean] True if a caller is waiting
+    def call_waiting?
+      @queue.length > 0
+    end
+
+    # Returns the number of callers waiting in the queue
+    # @return [Fixnum]
+    def calls_waiting
+      @queue.length
+    end
+
+  private
+    # Get the caller ID of the remote party.
+    # If this is an OutboundCall, use Call#to
+    # Otherwise, use Call#from
+    def remote_party(call)
+      call.is_a?(Adhearsion::OutboundCall) ? call.to : call.from
+    end
+
+
+    # @private
+    def ignoring_ended_calls
+      yield
+    rescue *ENDED_CALL_EXCEPTIONS
+      # This actor may previously have been shut down due to the call ending
+    end
+
+    def call_agent(agent, queued_call)
+      agent_call = Adhearsion::OutboundCall.new
+      agent_call[:agent]  = agent
+      agent_call[:queued_call] = queued_call
+
+      # Stash the caller ID so we don't have to try to get it from a dead call object later
+      queued_caller_id = remote_party queued_call
+
+      # The call controller is actually run by #dial, here we skip joining if we do not have one
+      dial_options = agent.dial_options_for(self, queued_call)
+      unless dial_options[:confirm]
+        agent_call.on_answer { ignoring_ended_calls { agent_call.join queued_call.uri if queued_call.active? } }
+      end
+
+      # Disconnect agent if caller hangs up before agent answers
+      queued_call.on_end { ignoring_ended_calls { agent_call.hangup } }
+
+      agent_call.on_unjoined do
+       ignoring_ended_calls { agent_call.hangup }
+       ignoring_ended_calls { queued_call.hangup }
+      end
+
+      # Track whether the agent actually talks to the queued_call
+      connected = false
+      queued_call.on_joined { connected = true }
+
+      agent_call.on_end do |end_event|
+        # Ensure we don't return an agent that was removed or paused
+        conditionally_return_agent agent
+
+        agent.callback :disconnect, self, agent_call, queued_call
+
+        unless connected
+          if queued_call.alive? && queued_call.active?
+            ignoring_ended_calls { priority_enqueue queued_call }
+            logger.warn "Call did not connect to agent! Agent #{agent.id} call ended with #{end_event.reason}; reinserting caller #{queued_caller_id} into queue"
+          else
+            logger.warn "Caller #{queued_caller_id} hung up before being connected to an agent."
+          end
+        end
+      end
+
+      agent.callback :connect, self, agent_call, queued_call
+
+      agent_call.execute_controller_or_router_on_answer dial_options.delete(:confirm), dial_options.delete(:confirm_metadata)
+
+      agent_call.dial agent.address, dial_options
+    end
+
+    def bridge_agent(agent, queued_call)
+      # Stash caller ID to make log messages work even if calls end
+      queued_caller_id = remote_party queued_call
+      agent.call[:queued_call] = queued_call
+
+      agent.call.register_tmp_handler :event, Punchblock::Event::Unjoined do
+        agent.callback :disconnect, self, agent.call, queued_call
+        ignoring_ended_calls { queued_call.hangup }
+        ignoring_ended_calls { conditionally_return_agent agent if agent.call.active? }
+        agent.call[:queued_call] = nil
+      end
+
+      agent.callback :connect, self, agent.call, queued_call
+
+      agent.join queued_call if queued_call.active?
+    rescue *ENDED_CALL_EXCEPTIONS
+      ignoring_ended_calls do
+        if agent.call.active?
+          logger.info "Caller #{queued_caller_id} failed to connect to Agent #{agent.id} due to caller hangup"
+          conditionally_return_agent agent, :auto
+        else
+          # Agent's call has ended, so remove him from the queue
+          remove_agent agent
+        end
+      end
+
+      ignoring_ended_calls do
+        if queued_call.active?
+          priority_enqueue queued_call
+          logger.warn "Call failed to connect to Agent #{agent.id} due to agent hangup; reinserting caller #{queued_caller_id} into queue"
+        end
+      end
+    end
+  end
+end

data/lib/electric_slide/plugin.rb

@@ -0,0 +1,10 @@
+# encoding: utf-8
+require 'adhearsion'
+
+class ElectricSlide
+  class Plugin < Adhearsion::Plugin
+    init do
+      logger.info 'ElectricSlide plugin loaded.'
+    end
+  end
+end

data/lib/electric_slide/version.rb

@@ -0,0 +1,4 @@
+# encoding: utf-8
+class ElectricSlide
+  VERSION = '0.2.0'
+end

data/spec/electric_slide/agent_spec.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+require 'spec_helper'
+require 'electric_slide/agent'
+
+describe ElectricSlide::Agent do
+  let(:options) { { id: 1, address: '123@foo.com', presence: :available} }
+
+  class MyAgent < ElectricSlide::Agent
+    on_connect do
+      foo
+    end
+
+    def foo
+      :bar
+    end
+  end
+
+  subject {MyAgent.new options}
+
+  it 'executes a connect callback' do
+    expect(subject.callback(:connect)).to eql :bar
+  end
+end

data/spec/electric_slide/agent_strategy/fixed_priority_spec.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+require 'spec_helper'
+require 'electric_slide/agent_strategy/fixed_priority'
+require 'ostruct'
+
+describe ElectricSlide::AgentStrategy::FixedPriority do
+  let(:subject) { ElectricSlide::AgentStrategy::FixedPriority.new }
+  it 'should allow adding an agent with a specified priority' do
+    subject.agent_available?.should be false
+    subject << OpenStruct.new({ id: 101, priority: 1 })
+    subject.agent_available?.should be true
+  end
+
+  it 'should allow adding multiple agents at the same priority' do
+    agent1 = OpenStruct.new({ id: 101, priority: 2 })
+    agent2 = OpenStruct.new({ id: 102, priority: 2 })
+    subject << agent1
+    subject << agent2
+    subject.checkout_agent.should == agent1
+  end
+
+  it 'should return all agents of a higher priority before returning an agent of a lower priority' do
+    agent1 = OpenStruct.new({ id: 101, priority: 2 })
+    agent2 = OpenStruct.new({ id: 102, priority: 2 })
+    agent3 = OpenStruct.new({ id: 103, priority: 3 })
+    subject << agent1
+    subject << agent2
+    subject << agent3
+    subject.checkout_agent.should == agent1
+    subject.checkout_agent.should == agent2
+    subject.checkout_agent.should == agent3
+  end
+
+  it 'should detect an agent available if one is available at any priority' do
+    agent1 = OpenStruct.new({ id: 101, priority: 2 })
+    agent2 = OpenStruct.new({ id: 102, priority: 3 })
+    subject << agent1
+    subject << agent2
+    subject.checkout_agent
+    subject.agent_available?.should == true
+  end
+end

data/spec/electric_slide/call_queue_spec.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+require 'spec_helper'
+
+describe ElectricSlide::CallQueue do
+  let(:queue) { ElectricSlide::CallQueue.new }
+  let(:call_a) { dummy_call }
+  let(:call_b) { dummy_call }
+  let(:call_c) { dummy_call }
+  before :each do
+    queue.enqueue call_a
+    queue.enqueue call_b
+    queue.enqueue call_c
+  end
+
+  it "should return callers in the same order they were enqueued" do
+    expect(queue.get_next_caller).to be call_a
+    expect(queue.get_next_caller).to be call_b
+    expect(queue.get_next_caller).to be call_c
+  end
+
+  it "should return a priority caller ahead of the queue" do
+    call_d = dummy_call
+    queue.priority_enqueue call_d
+    expect(queue.get_next_caller).to be call_d
+    expect(queue.get_next_caller).to be call_a
+  end
+
+  it "should remove a caller who abandons the queue" do
+    queue.enqueue call_a
+    queue.enqueue call_b
+    queue.abandon call_a
+    expect(queue.get_next_caller).to be call_b
+  end
+
+  it "should raise when given an invalid connection type" do
+    expect { ElectricSlide::CallQueue.new connection_type: :blah }.to raise_error
+  end
+
+  it "should raise when given an invalid Agent" do
+    expect { queue.add_agent nil }.to raise_error
+  end
+end