adhearsion-asterisk 0.1.0

data/lib/adhearsion/asterisk/queue_proxy.rb

@@ -0,0 +1,177 @@
+module Adhearsion
+  module Asterisk
+    class QueueProxy
+
+      extend ActiveSupport::Autoload
+
+      autoload :AgentProxy
+      autoload :QueueAgentsListProxy
+
+      class << self
+        def format_join_hash_key_arguments(options)
+          bad_argument = lambda do |(key, value)|
+            raise ArgumentError, "Unrecognize value for #{key.inspect} -- #{value.inspect}"
+          end
+
+          # Direct Queue() arguments:
+          timeout        = options.delete :timeout
+          announcement   = options.delete :announce
+
+          # Terse single-character options
+          ring_style     = options.delete :play
+          allow_hangup   = options.delete :allow_hangup
+          allow_transfer = options.delete :allow_transfer
+          agi            = options.delete :agi
+
+          raise ArgumentError, "Unrecognized args to join!: #{options.inspect}" if options.any?
+
+          ring_style = case ring_style
+          when :ringing then 'r'
+          when :music then   ''
+          when nil
+          else bad_argument[:play => ring_style]
+          end.to_s
+
+          allow_hangup = case allow_hangup
+          when :caller then   'H'
+          when :agent then    'h'
+          when :everyone then 'Hh'
+          when nil
+          else bad_argument[:allow_hangup => allow_hangup]
+          end.to_s
+
+          allow_transfer = case allow_transfer
+          when :caller then   'T'
+          when :agent then    't'
+          when :everyone then 'Tt'
+          when nil
+          else bad_argument[:allow_transfer => allow_transfer]
+          end.to_s
+
+          terse_character_options = ring_style + allow_transfer + allow_hangup
+
+          [terse_character_options, '', announcement, timeout, agi].map(&:to_s)
+        end
+      end
+
+      attr_reader :name, :environment
+
+      def initialize(name, environment)
+        @name, @environment = name, environment
+      end
+
+      # Makes the current channel join the queue.
+      #
+      # @param [Hash] options
+      #
+      #   :timeout        - The number of seconds to wait for an agent to answer
+      #   :play           - Can be :ringing or :music.
+      #   :announce       - A sound file to play instead of the normal queue announcement.
+      #   :allow_transfer - Can be :caller, :agent, or :everyone. Allow someone to transfer the call.
+      #   :allow_hangup   - Can be :caller, :agent, or :everyone. Allow someone to hangup with the * key.
+      #   :agi            - An AGI script to be called on the calling parties channel just before being connected.
+      #
+      #  @example
+      #    queue('sales').join!
+      #  @example
+      #    queue('sales').join! :timeout => 1.minute
+      #  @example
+      #    queue('sales').join! :play => :music
+      #  @example
+      #    queue('sales').join! :play => :ringing
+      #  @example
+      #    queue('sales').join! :announce => "custom/special-queue-announcement"
+      #  @example
+      #    queue('sales').join! :allow_transfer => :caller
+      #  @example
+      #    queue('sales').join! :allow_transfer => :agent
+      #  @example
+      #    queue('sales').join! :allow_hangup   => :caller
+      #  @example
+      #    queue('sales').join! :allow_hangup   => :agent
+      #  @example
+      #    queue('sales').join! :allow_hangup   => :everyone
+      #  @example
+      #    queue('sales').join! :agi            => 'agi://localhost/sales_queue_callback'
+      #  @example
+      #    queue('sales').join! :allow_transfer => :agent, :timeout => 30.seconds,
+      def join!(options = {})
+        environment.execute("queue", name, *self.class.format_join_hash_key_arguments(options))
+        normalize_queue_status_variable environment.get_variable("QUEUESTATUS")
+      end
+
+      # Get the agents associated with a queue
+      #
+      # @param [Hash] options
+      # @return [QueueAgentsListProxy]
+      def agents(options = {})
+        cached = options.has_key?(:cache) ? options.delete(:cache) : true
+        raise ArgumentError, "Unrecognized arguments to #agents: #{options.inspect}" if options.keys.any?
+        if cached
+          @cached_proxy ||= QueueAgentsListProxy.new(self, true)
+        else
+          @uncached_proxy ||=  QueueAgentsListProxy.new(self, false)
+        end
+      end
+
+      # Check how many channels are waiting in the queue
+      # @return [Integer]
+      # @raise QueueDoesNotExistError
+      def waiting_count
+        raise QueueDoesNotExistError.new(name) unless exists?
+        environment.get_variable("QUEUE_WAITING_COUNT(#{name})").to_i
+      end
+
+      # Check whether the waiting count is zero
+      # @return [Boolean]
+      def empty?
+        waiting_count == 0
+      end
+
+      # Check whether any calls are waiting in the queue
+      # @return [Boolean]
+      def any?
+        waiting_count > 0
+      end
+
+      # Check whether a queue exists/is defined in Asterisk
+      # @return [Boolean]
+      def exists?
+        environment.execute('RemoveQueueMember', name, 'SIP/AdhearsionQueueExistenceCheck')
+        environment.get_variable("RQMSTATUS") != 'NOSUCHQUEUE'
+      end
+
+      private
+
+      # Ensure the queue exists by interpreting the QUEUESTATUS variable
+      #
+      # According to http://www.voip-info.org/wiki/view/Asterisk+cmd+Queue
+      # possible values are:
+      #
+      # TIMEOUT      => :timeout
+      # FULL         => :full
+      # JOINEMPTY    => :joinempty
+      # LEAVEEMPTY   => :leaveempty
+      # JOINUNAVAIL  => :joinunavail
+      # LEAVEUNAVAIL => :leaveunavail
+      # CONTINUE     => :continue
+      #
+      # If the QUEUESTATUS variable is not set the call was successfully connected,
+      # and Adhearsion will return :completed.
+      #
+      # @param [String] QUEUESTATUS variable from Asterisk
+      # @return [Symbol] Symbolized version of QUEUESTATUS
+      # @raise QueueDoesNotExistError
+      def normalize_queue_status_variable(variable)
+        variable = "COMPLETED" if variable.nil?
+        variable.downcase.to_sym
+      end
+
+      class QueueDoesNotExistError < StandardError
+        def initialize(queue_name)
+          super "Queue #{queue_name} does not exist!"
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/asterisk/queue_proxy/agent_proxy.rb

@@ -0,0 +1,81 @@
+module Adhearsion
+  module Asterisk
+    class QueueProxy
+      class AgentProxy
+
+        SUPPORTED_METADATA_NAMES = %w[status password name mohclass exten channel] unless defined? SUPPORTED_METADATA_NAMES
+
+        class << self
+          def id_from_agent_channel(id)
+            id = id.to_s
+            id.starts_with?('Agent/') ? id[%r[^Agent/(.+)$],1] : id
+          end
+        end
+
+        attr_reader :interface, :proxy, :queue_name, :id
+        def initialize(interface, proxy)
+          @interface, @proxy = interface, proxy
+          @id         = self.class.id_from_agent_channel interface
+          @queue_name = proxy.name
+        end
+
+        def remove!
+          proxy.environment.execute 'RemoveQueueMember', queue_name, interface
+          case proxy.environment.get_variable("RQMSTATUS")
+          when "REMOVED"     then true
+          when "NOTINQUEUE"  then false
+          when "NOSUCHQUEUE"
+            raise QueueDoesNotExistError.new(queue_name)
+          else
+            raise "Unrecognized RQMSTATUS variable!"
+          end
+        end
+
+        # Pauses the given agent for this queue only. If you wish to pause this agent
+        # for all queues, pass in :everywhere => true. Returns true if the agent was
+        # successfully paused and false if the agent was not found.
+        def pause!(options = {})
+          args = [(options.delete(:everywhere) ? nil : queue_name), interface]
+          proxy.environment.execute 'PauseQueueMember', *args
+          case proxy.environment.get_variable("PQMSTATUS")
+          when "PAUSED"   then true
+          when "NOTFOUND" then false
+          else
+            raise "Unrecognized PQMSTATUS value!"
+          end
+        end
+
+        # Pauses the given agent for this queue only. If you wish to pause this agent
+        # for all queues, pass in :everywhere => true. Returns true if the agent was
+        # successfully paused and false if the agent was not found.
+        def unpause!(options = {})
+          args = [(options.delete(:everywhere) ? nil : queue_name), interface]
+          proxy.environment.execute 'UnpauseQueueMember', *args
+          case proxy.environment.get_variable("UPQMSTATUS")
+          when "UNPAUSED" then true
+          when "NOTFOUND" then false
+          else
+            raise "Unrecognized UPQMSTATUS value!"
+          end
+        end
+
+        # Returns true/false depending on whether this agent is logged in.
+        def logged_in?
+          status == 'LOGGEDIN'
+        end
+
+        private
+
+        def status
+          agent_metadata 'status'
+        end
+
+        def agent_metadata(data_name)
+          data_name = data_name.to_s.downcase
+          raise ArgumentError, "unrecognized agent metadata name #{data_name}" unless SUPPORTED_METADATA_NAMES.include? data_name
+          proxy.environment.variable "AGENT(#{id}:#{data_name})"
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/asterisk/queue_proxy/queue_agents_list_proxy.rb

@@ -0,0 +1,132 @@
+module Adhearsion
+  module Asterisk
+    class QueueProxy
+      class QueueAgentsListProxy
+        include Enumerable
+
+        attr_reader :proxy, :agents
+
+        def initialize(proxy, cached = false)
+          @proxy  = proxy
+          @cached = cached
+        end
+
+        def count
+          if cached? && @cached_count
+            @cached_count
+          else
+            @cached_count = proxy.environment.get_variable("QUEUE_MEMBER_COUNT(#{proxy.name})").to_i
+          end
+        end
+        alias size count
+        alias length count
+
+        # @param [Hash] args
+        # :name value will be viewable in the queue_log
+        # :penalty is the penalty assigned to this agent for answering calls on this queue
+        def new(*args)
+          options   = args.last.kind_of?(Hash) ? args.pop : {}
+          interface = args.shift
+
+          raise ArgumentError, "You must specify an interface to add." if interface.nil?
+          raise ArgumentError, "You may only supply an interface and a Hash argument!" if args.any?
+
+          penalty             = options.delete(:penalty)            || ''
+          name                = options.delete(:name)               || ''
+          state_interface     = options.delete(:state_interface)    || ''
+
+          raise ArgumentError, "Unrecognized argument(s): #{options.inspect}" if options.any?
+
+          proxy.environment.execute "AddQueueMember", proxy.name, interface, penalty, '', name, state_interface
+
+          added = case proxy.environment.get_variable("AQMSTATUS")
+                  when "ADDED"         then true
+                  when "MEMBERALREADY" then false
+                  when "NOSUCHQUEUE"   then raise QueueDoesNotExistError.new(proxy.name)
+                  else
+                    raise "UNRECOGNIZED AQMSTATUS VALUE!"
+                  end
+
+          if added
+            check_agent_cache!
+            AgentProxy.new(interface, proxy).tap do |agent_proxy|
+              @agents << agent_proxy
+            end
+          else
+            false
+          end
+        end
+
+        # Logs a pre-defined agent into this queue and waits for calls. Pass in :silent => true to stop
+        # the message which says "Agent logged in".
+        def login!(*args)
+          options = args.last.kind_of?(Hash) ? args.pop : {}
+
+          silent = options.delete(:silent).equal?(false) ? '' : 's'
+          id     = args.shift
+          id   &&= AgentProxy.id_from_agent_channel(id)
+          raise ArgumentError, "Unrecognized Hash options to #login: #{options.inspect}" if options.any?
+          raise ArgumentError, "Unrecognized argument to #login: #{args.inspect}" if args.any?
+
+          proxy.environment.execute 'AgentLogin', id, silent
+        end
+
+        # Removes the current channel from this queue
+        def logout!
+          # TODO: DRY this up. Repeated in the AgentProxy...
+          proxy.environment.execute 'RemoveQueueMember', proxy.name
+          case proxy.environment.get_variable("RQMSTATUS")
+          when "REMOVED"     then true
+          when "NOTINQUEUE"  then false
+          when "NOSUCHQUEUE"
+            raise QueueDoesNotExistError.new(proxy.name)
+          else
+            raise "Unrecognized RQMSTATUS variable!"
+          end
+        end
+
+        def each(&block)
+          check_agent_cache!
+          agents.each &block
+        end
+
+        def first
+          check_agent_cache!
+          agents.first
+        end
+
+        def last
+          check_agent_cache!
+          agents.last
+        end
+
+        def cached?
+          @cached
+        end
+
+        def to_a
+          check_agent_cache!
+          @agents
+        end
+
+        private
+
+        def check_agent_cache!
+          if cached?
+            load_agents! unless agents
+          else
+            load_agents!
+          end
+        end
+
+        def load_agents!
+          raw_data = proxy.environment.get_variable "QUEUE_MEMBER_LIST(#{proxy.name})"
+          @agents = raw_data.split(',').map(&:strip).reject(&:empty?).map do |agent|
+            AgentProxy.new agent, proxy
+          end
+          @cached_count = @agents.size
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/asterisk/version.rb

@@ -0,0 +1,5 @@
+module Adhearsion
+  module Asterisk
+    VERSION = "0.1.0"
+  end
+end

data/spec/adhearsion/asterisk/config_generators/agents_spec.rb

@@ -0,0 +1,258 @@
+require 'spec_helper'
+require 'adhearsion/asterisk/config_generator/agents'
+
+module AgentsConfigGeneratorTestHelper
+
+  def reset_agents!
+    @agents = Adhearsion::Asterisk::ConfigGenerator::Agents.new
+  end
+
+  def generated_config_has_pair(pair)
+    agents.conf.split("\n").grep(/=[^>]/).each do |line|
+      key, value = line.strip.split('=')
+      return true if pair == {key.to_sym => value}
+    end
+    false
+  end
+
+end
+
+describe "The agents.conf config file agents" do
+
+  include AgentsConfigGeneratorTestHelper
+
+  attr_reader :agents
+  before(:each) do
+    reset_agents!
+  end
+  it "The agent() method should enqueue a Hash into Agents#agent_definitions" do
+    agents.agent 1337, :password => 9876, :name => "Jay Phillips"
+    agents.agent_definitions.size.should be 1
+    agents.agent_definitions.first.should == {:id => 1337, :password => 9876, :name => "Jay Phillips"}
+  end
+
+  it 'should add the warning message to the to_s output' do
+    agents.conf.should =~ /^\s*;.{10}/
+  end
+
+  it "The conf() method should always create a general section" do
+    agents.conf.should =~ /^\[general\]/
+  end
+
+  it "The agent() method should generate a proper String" do
+    agents.agent 123, :name => "Otto Normalverbraucher", :password => "007"
+    agents.agent 889, :name => "John Doe", :password => "998"
+
+    agents.conf.split("\n").grep(/^agent =>/).map(&:strip).should == [
+      "agent => 123,007,Otto Normalverbraucher",
+      "agent => 889,998,John Doe"
+    ]
+  end
+
+  it "The persistent_agents() method should generate a persistentagents yes/no pair" do
+    agents.persistent_agents true
+    generated_config_has_pair(:persistentagents => "yes").should be true
+
+    reset_agents!
+
+    agents.persistent_agents false
+    generated_config_has_pair(:persistentagents => "no").should be true
+  end
+
+  it "The persistent_agents() method should be in the [general] section" do
+    agents.persistent_agents true
+    agents.general_section.should == {:persistentagents => "yes"}
+
+  end
+
+  it "max_login_tries() should generate a 'maxlogintries' numerical pair" do
+    agents.max_login_tries 50
+    generated_config_has_pair(:maxlogintries => "50").should be true
+  end
+
+  it "max_login_tries() should be in the agents section" do
+    agents.max_login_tries 0
+    agents.agent_section.should == {:maxlogintries => 0}
+  end
+
+  it "log_off_after_duration should generate autologoff" do
+    agents.log_off_after_duration 15.seconds
+    generated_config_has_pair(:autologoff => "15").should be true
+  end
+
+  it "log_off_if_unavailable should add autologoffunavail to the agents section" do
+    agents.log_off_if_unavailable false
+    agents.agent_section.should == {:autologoffunavail => "no"}
+  end
+
+  it "require_hash_to_acknowledge() should generate a 'ackcall' yes/no pair" do
+    agents.require_hash_to_acknowledge false
+    agents.agent_section.should == {:ackcall => "no"}
+  end
+
+  it "allow_star_to_hangup should generate a 'endcall' yes/no pair" do
+    agents.allow_star_to_hangup false
+    agents.agent_section.should == {:endcall => "no"}
+  end
+
+  it "time_between_calls should convert its argument to milliseconds" do
+    agents.time_between_calls 1.hour
+    agents.agent_section.should == {:wrapuptime => 1.hour * 1_000}
+  end
+
+  it "hold_music_class should convert its argument to a String" do
+    agents.hold_music_class :podcast
+    agents.agent_section_special.should == {:musiconhold => "podcast"}
+  end
+
+  it "play_on_agent_goodbye should generate 'agentgoodbye'" do
+    agents.play_on_agent_goodbye "tt-monkeys"
+    agents.agent_section_special.should == {:agentgoodbye => "tt-monkeys"}
+  end
+
+  it "change_cdr_source should generate updatecdr" do
+    agents.change_cdr_source false
+    agents.agent_section.should == {:updatecdr => "no"}
+  end
+
+  it "play_for_waiting_keep_alive" do
+    agents.play_for_waiting_keep_alive "tt-weasels"
+    agents.agent_section.should == {:custom_beep => "tt-weasels"}
+  end
+
+  it "save_recordings_in should generate 'savecallsin'" do
+    agents.save_recordings_in "/second/star/on/the/right"
+    agents.agent_section.should == {:savecallsin => "/second/star/on/the/right"}
+  end
+
+  it "recording_prefix should generate 'urlprefix'" do
+    agents.recording_prefix "ohai"
+    agents.agent_section.should == {:urlprefix => "ohai"}
+  end
+
+  it "recording_format should only allow a few symbols as an argument" do
+    the_following_code {
+      agents.recording_format :wav
+      agents.agent_section.should == {:recordformat => :wav}
+    }.should_not raise_error
+
+    reset_agents!
+
+    the_following_code {
+      agents.recording_format :wav49
+      agents.agent_section.should == {:recordformat => :wav49}
+    }.should_not raise_error
+
+    reset_agents!
+
+    the_following_code {
+      agents.recording_format :gsm
+      agents.agent_section.should == {:recordformat => :gsm}
+    }.should_not raise_error
+
+    reset_agents!
+
+    the_following_code {
+      agents.recording_format :mp3
+      agents.agent_section.should == {:recordformat => :mp3}
+    }.should raise_error ArgumentError
+
+  end
+
+  it "record_agent_calls should generate a 'recordagentcalls' yes/no pair" do
+    agents.record_agent_calls false
+    agents.agent_section.should == {:recordagentcalls => 'no'}
+  end
+
+  it "allow_multiple_logins_per_extension should generate 'multiplelogin' in [general]" do
+    agents.allow_multiple_logins_per_extension true
+    agents.general_section.should == {:multiplelogin => 'yes'}
+  end
+
+end
+
+describe "The default agents.conf config file converted to this syntax" do
+
+  include AgentsConfigGeneratorTestHelper
+
+  attr_reader :default_config, :agents
+  before(:each) do
+    reset_agents!
+    @default_config = <<-CONFIG
+[general]
+persistentagents=yes
+
+[agents]
+maxlogintries=5
+autologoff=15
+ackcall=no
+endcall=yes
+wrapuptime=5000
+musiconhold => default
+agentgoodbye => goodbye_file
+updatecdr=no
+group=1,2
+recordagentcalls=yes
+recordformat=gsm
+urlprefix=http://localhost/calls/
+savecallsin=/var/calls
+custom_beep=beep
+
+agent => 1001,4321,Mark Spencer
+agent => 1002,4321,Will Meadows
+    CONFIG
+  end
+
+  it "they're basically the same" do
+    agents.persistent_agents true
+    agents.max_login_tries 5
+    agents.log_off_after_duration 15
+    agents.require_hash_to_acknowledge false
+    agents.allow_star_to_hangup true
+    agents.time_between_calls 5
+    agents.hold_music_class :default
+    agents.play_on_agent_goodbye "goodbye_file"
+    agents.change_cdr_source false
+    agents.groups 1,2
+    agents.record_agent_calls true
+    agents.recording_format :gsm
+    agents.recording_prefix "http://localhost/calls/"
+    agents.save_recordings_in "/var/calls"
+    agents.play_for_waiting_keep_alive "beep"
+
+    agents.agent 1001, :password => 4321, :name => "Mark Spencer"
+    agents.agent 1002, :password => 4321, :name => "Will Meadows"
+
+    cleaned_up_default_config =
+      Adhearsion::Asterisk::ConfigGenerator.create_sanitary_hash_from(default_config)
+
+    cleaned_up_generated_config = agents.to_sanitary_hash
+
+    cleaned_up_generated_config.should == cleaned_up_default_config
+  end
+
+end
+
+
+describe "AgentsConfigGeneratorTestHelper" do
+
+  include AgentsConfigGeneratorTestHelper
+
+  attr_reader :agents
+  before(:each) do
+    reset_agents!
+  end
+
+  it "generated_config_has_pair() works properly with one pair" do
+    @agents = mock "A fake agents with just one pair", :conf => "foo=bar"
+    generated_config_has_pair(:foo => "bar").should be true
+  end
+
+  it "generated_config_has_pair() works properly with two pairs" do
+    @agents = mock "A fake agents with just one pair"
+    @agents.expects(:conf).twice.returns("[general]\n\nqaz=qwerty\nagent => 1,2,3")
+ 
+    generated_config_has_pair(:qaz => "qwerty").should be true
+    generated_config_has_pair(:foo => "bar").should be false
+  end
+end