adhearsion 1.2.6 → 2.0.0.alpha1

data/lib/adhearsion/call.rb

@@ -0,0 +1,176 @@
+require 'thread'
+
+module Adhearsion
+  ##
+  # Encapsulates call-related data and behavior.
+  #
+  class Call
+
+    include HasGuardedHandlers
+
+    attr_accessor :offer, :client, :end_reason, :commands
+
+    def initialize(offer = nil)
+      if offer
+        @offer  = offer
+        @client = offer.client
+      end
+
+      @tag_mutex        = Mutex.new
+      @tags             = []
+      @end_reason_mutex = Mutex.new
+      end_reason        = nil
+      @commands         = CommandRegistry.new
+
+      register_initial_handlers
+    end
+
+    def id
+      @offer.call_id
+    end
+
+    def tags
+      @tag_mutex.synchronize { @tags.clone }
+    end
+
+    # This may still be a symbol, but no longer requires the tag to be a symbol although beware
+    # that using a symbol would create a memory leak if used improperly
+    # @param [String, Symbol] label String or Symbol with which to tag this call
+    def tag(label)
+      raise ArgumentError, "Tag must be a String or Symbol" unless [String, Symbol].include?(label.class)
+      @tag_mutex.synchronize { @tags << label }
+    end
+
+    def remove_tag(symbol)
+      @tag_mutex.synchronize do
+        @tags.reject! { |tag| tag == symbol }
+      end
+    end
+
+    def tagged_with?(symbol)
+      @tag_mutex.synchronize { @tags.include? symbol }
+    end
+
+    def register_event_handler(*guards, &block)
+      register_handler :event, *guards, &block
+    end
+
+    def deliver_message(message)
+      trigger_handler :event, message
+    end
+    alias << deliver_message
+
+    def register_initial_handlers
+      on_end do |event|
+        hangup
+        @end_reason_mutex.synchronize { @end_reason = event.reason }
+        commands.terminate
+      end
+    end
+
+    def on_end(&block)
+      register_event_handler :class => Punchblock::Event::End do |event|
+        block.call event
+        throw :pass
+      end
+    end
+
+    def active?
+      @end_reason_mutex.synchronize { !end_reason }
+    end
+
+    def accept(headers = nil)
+      write_and_await_response Punchblock::Command::Accept.new(:headers => headers)
+    end
+
+    def answer(headers = nil)
+      write_and_await_response Punchblock::Command::Answer.new(:headers => headers)
+    end
+
+    def reject(reason = :busy, headers = nil)
+      write_and_await_response Punchblock::Command::Reject.new(:reason => reason, :headers => headers)
+    end
+
+    def hangup!(headers = nil)
+      return false unless active?
+      @end_reason_mutex.synchronize { @end_reason = true }
+      write_and_await_response Punchblock::Command::Hangup.new(:headers => headers)
+    end
+
+    def hangup
+      Adhearsion.active_calls.remove_inactive_call self
+    end
+
+    def join(other_call_id)
+      write_and_await_response Punchblock::Command::Join.new :other_call_id => other_call_id
+    end
+
+    # Lock the socket for a command.  Can be used to allow the console to take
+    # control of the thread in between AGI commands coming from the dialplan.
+    def with_command_lock
+      @command_monitor ||= Monitor.new
+      @command_monitor.synchronize { yield }
+    end
+
+    def write_and_await_response(command, timeout = 60)
+      logger.trace "Executing command #{command.inspect}"
+      commands << command
+      write_command command
+      response = command.response timeout
+      raise response if response.is_a? Exception
+      command
+    end
+
+    def write_command(command)
+      raise Hangup unless active? || command.is_a?(Punchblock::Command::Hangup)
+      client.execute_command command, :call_id => id
+    end
+
+    # Sanitize the offer id
+    def logger_id
+      "#{self.class}: #{id}"
+    end
+
+    def variables
+      offer ? offer.headers_hash : nil or {}
+    end
+
+    def execute_controller(controller, latch = nil)
+      Adhearsion::Process.important_threads << Thread.new do
+        catching_standard_errors do
+          begin
+            CallController.exec controller
+          ensure
+            hangup!
+          end
+          latch.countdown! if latch
+        end
+      end
+    end
+
+    class CommandRegistry < ThreadSafeArray
+      def terminate
+        hangup = Hangup.new
+        each { |command| command.response = hangup if command.requested? }
+      end
+    end
+
+    class Registry
+      @registry = Hash.new
+      @mutex = Mutex.new
+
+      def self.[](k)
+        @mutex.synchronize do
+          @registry[k]
+        end
+      end
+
+      def self.[]=(k, value)
+        @mutex.synchronize do
+          @registry[k] = value
+        end
+      end
+    end#Registry
+
+  end#Call
+end#Adhearsion

data/lib/adhearsion/call_controller.rb

@@ -0,0 +1,134 @@
+module Adhearsion
+  class CallController
+    extend ActiveSupport::Autoload
+
+    autoload :Dial
+    autoload :Input
+    autoload :Output
+    autoload :Record
+    autoload :Menu
+    autoload :Utility
+
+    include Dial
+    include Input
+    include Output
+    include Record
+    include Menu
+    include Utility
+
+    class_attribute :callbacks
+
+    self.callbacks = {:before_call => [], :after_call => []}
+
+    self.callbacks.keys.each do |name|
+      class_eval <<-STOP
+        def self.#{name}(method_name = nil, &block)
+          callback = if method_name
+            lambda { send method_name }
+          elsif block
+            block
+          end
+          self.callbacks = self.callbacks.dup.tap { |cb| cb[:#{name}] += Array(callback) }
+        end
+      STOP
+    end
+
+    def self.exec(controller, fresh_call = true)
+      return unless controller
+
+      new_controller = catch :pass_controller do
+        controller.skip_accept! unless fresh_call
+        controller.execute!
+        nil
+      end
+
+      exec new_controller, false
+    end
+
+    attr_reader :call, :metadata
+
+    delegate :[], :[]=, :to => :@metadata
+    delegate :variables, :logger, :to => :call
+    delegate :write_and_await_response, :accept, :answer, :reject, :to => :call
+
+    def initialize(call, metadata = nil)
+      @call, @metadata = call, metadata || {}
+      setup
+    end
+
+    def setup
+      Plugin.add_dialplan_methods self if Plugin
+    end
+
+    def execute!(*options)
+      execute_callbacks :before_call
+      accept if auto_accept?
+      run
+    rescue Hangup
+      logger.info "Call was hung up"
+    rescue SyntaxError, StandardError => e
+      Events.trigger :exception, e
+    ensure
+      after_call
+    end
+
+    def run
+    end
+
+    def invoke(controller_class, metadata = nil)
+      controller = controller_class.new call, metadata
+      controller.run
+    end
+
+    def pass(controller_class, metadata = nil)
+      throw :pass_controller, controller_class.new(call, metadata)
+    end
+
+    def execute_callbacks(type)
+      self.class.callbacks[type].each do |callback|
+        catching_standard_errors do
+          instance_exec &callback
+        end
+      end
+    end
+
+    def skip_accept!
+      @skip_accept = true
+    end
+
+    def skip_accept?
+      @skip_accept || false
+    end
+
+    def auto_accept?
+      Adhearsion.config.platform.automatically_accept_incoming_calls && !skip_accept?
+    end
+
+    def after_call
+      @after_call ||= execute_callbacks :after_call
+    end
+
+    def hangup(headers = nil)
+      hangup_response = call.hangup! headers
+      after_call unless hangup_response == false
+    end
+
+    def mute
+      write_and_await_response ::Punchblock::Command::Mute.new
+    end
+
+    def unmute
+      write_and_await_response ::Punchblock::Command::Unmute.new
+    end
+
+    def execute_component_and_await_completion(component)
+      write_and_await_response component
+
+      yield component if block_given?
+
+      complete_event = component.complete_event
+      raise StandardError, complete_event.reason.details if complete_event.reason.is_a? Punchblock::Event::Complete::Error
+      component
+    end
+  end#class
+end

data/lib/adhearsion/call_controller/dial.rb

@@ -0,0 +1,70 @@
+module Adhearsion
+  class CallController
+    module Dial
+      #
+      # Dial a third party and join to this call
+      #
+      # @param [String|Array<String>] number represents the extension or "number" that asterisk should dial.
+      # Be careful to not just specify a number like 5001, 9095551001
+      # You must specify a properly formatted string as Asterisk would expect to use in order to understand
+      # whether the call should be dialed using SIP, IAX, or some other means.
+      # You can also specify an array of destinations: each will be called with the same options simultaneously.
+      # The first call answered is joined, the others are hung up.
+      #
+      # @param [Hash] options
+      #
+      # +:caller_id+ - the caller id number to be used when the call is placed.  It is advised you properly adhere to the
+      # policy of VoIP termination providers with respect to caller id values.
+      #
+      # +:name+ - this is the name which should be passed with the caller ID information
+      # if :name=>"John Doe" and :caller_id => "444-333-1000" then the compelete CID and name would be "John Doe" <4443331000>
+      # support for caller id information varies from country to country and from one VoIP termination provider to another.
+      #
+      # +:for+ - this option can be thought of best as a timeout.  i.e. timeout after :for if no one answers the call
+      # For example, dial("SIP/jay-desk-650&SIP/jay-desk-601&SIP/jay-desk-601-2", :for => 15.seconds, :caller_id => callerid)
+      # this call will timeout after 15 seconds if 1 of the 3 extensions being dialed do not pick prior to the 15 second time limit
+      #
+      # +:options+ - This is a string of options like "Tr" which are supported by the asterisk DIAL application.
+      # for a complete list of these options and their usage please check the link below.
+      #
+      # +:confirm+ - ?
+      #
+      # @example Make a call to the PSTN using my SIP provider for VoIP termination
+      #   dial "SIP/19095551001@my.sip.voip.terminator.us"
+      #
+      # @example Make 3 Simulataneous calls to the SIP extensions, try for 15 seconds and use the callerid
+      # for this call specified by the variable my_callerid
+      #   dial ["SIP/jay-desk-650", "SIP/jay-desk-601", "SIP/jay-desk-601-2"], :for => 15.seconds, :caller_id => my_callerid
+      #
+      # @example Make a call using the IAX provider to the PSTN
+      #   dial "IAX2/my.id@voipjet/19095551234", :name => "John Doe", :caller_id => "9095551234"
+      #
+      def dial(to, options = {})
+        latch = CountDownLatch.new 1
+        calls = Array(to).map do |target|
+          new_call = OutboundCall.new options
+
+          new_call.on_answer do |event|
+            calls.each do |call_to_hangup, target|
+              call_to_hangup.hangup! unless call_to_hangup.id == new_call.id
+            end
+            new_call.join call.id
+          end
+
+          new_call.on_end do |event|
+            latch.countdown!
+          end
+
+          [new_call, target]
+        end
+
+        calls.each do |call, target|
+          call.dial target, options
+        end
+
+        latch.wait
+      end
+
+    end#module Dial
+  end
+end

data/lib/adhearsion/call_controller/input.rb

@@ -0,0 +1,173 @@
+module Adhearsion
+  class CallController
+    module Input
+      #
+      # Waits for a single digit and returns it, or returns nil if nothing was pressed
+      #
+      # @param [Integer] the timeout to wait before returning, in seconds. nil or -1 mean no timeout.
+      # @return [String|nil] the pressed key, or nil if timeout was reached.
+      #
+      def wait_for_digit(timeout = 1)
+        timeout = nil if timeout == -1
+        timeout *= 1_000 if timeout
+        input_component = execute_component_and_await_completion ::Punchblock::Component::Input.new :mode => :dtmf,
+          :initial_timeout => timeout,
+          :inter_digit_timeout => timeout,
+            :grammar => {
+              :value => grammar_accept.to_s
+          }
+
+        reason = input_component.complete_event.reason
+        result = reason.respond_to?(:interpretation) ? reason.interpretation : nil
+        parse_single_dtmf result
+      end
+
+      # Used to receive keypad input from the user. Digits are collected
+      # via DTMF (keypad) input until one of three things happens:
+      #
+      #  1. The number of digits you specify as the first argument is collected
+      #  2. The timeout you specify with the :timeout option elapses, in seconds.
+      #  3. The "#" key (or the key you specify with :accept_key) is pressed
+      #
+      # Usage examples
+      #
+      #   input   # Receives digits until the caller presses the "#" key
+      #   input 3 # Receives three digits. Can be 0-9, * or #
+      #   input 5, :accept_key => "*"   # Receive at most 5 digits, stopping if '*' is pressed
+      #   input 1, :timeout => 60000 # Receive a single digit, returning an empty
+      #                                   string if the timeout is encountered
+      #   input 9, :timeout => 7000, :accept_key => "0" # Receives nine digits, returning
+      #                                              # when the timeout is encountered
+      #                                              # or when the "0" key is pressed.
+      #   input 3, :play => "you-sound-cute"
+      #   input :play => ["if-this-is-correct-press", 1, "otherwise-press", 2]
+      #   input :interruptible => false, :play => ["you-cannot-interrupt-this-message"] # Disallow DTMF (keypad) interruption
+      #                                                                                 # until after all files are played.
+      #
+      # When specifying outputs to play, the playback of the sequence of files will stop
+      # immediately when the user presses the first digit.
+      #
+      # Accepted output types are:
+      #   1. Any object supported by detect_type (@see detect_type)
+      #   2. Any valid SSML document
+      #   3. An Hash with at least the :value key set to a supported object type, and other keys as options to the specific output
+      #
+      # :play usage examples
+      #   input 1, :play => RubySpeech::SSML.draw { string "hello there" } # 1 digit, SSML document
+      #   input 2, :play => "hello there" # 2 digits, string
+      #   input 2, :play => {:value => Time.now, :strftime => "%H:%M"} # 2 digits, Hash with :value
+      #   input :play => [ "the time is", {:value => Time.now, :strftime => "%H:%M"} ] # no digit limit, two mixed outputs
+      #
+      # The :timeout option works like a digit timeout, therefore each digit pressed
+      # causes the timer to reset. This is a much more user-friendly approach than an
+      # absolute timeout.
+      #
+      # Note that when the digit limit is not specified the :accept_key becomes "#".
+      # Otherwise there would be no way to end the collection of digits. You can
+      # obviously override this by passing in a new key with :accept_key.
+      #
+      # @return [String] The keypad input received. An empty string is returned in the
+      #                  absense of input. If the :accept_key argument was pressed, it
+      #                  will not appear in the output.
+      def input(*args, &block)
+        begin
+          input! *args, &block
+        rescue PlaybackError => e
+          logger.warn { e }
+          retry # If sound playback fails, play the remaining sound files and wait for digits
+        end
+      end
+
+      # Same as {#input}, but immediately raises an exception if sound playback fails
+      #
+      # @return (see #input)
+      # @raise [Adhearsion::PlaybackError] If a sound file cannot be played
+      def input!(*args, &block)
+        options = args.last.kind_of?(Hash) ? args.pop : {}
+        number_of_digits = args.shift
+
+        options[:play] = Array(case options[:play]
+          when String
+            options[:play]
+          when Array
+            options[:play].compact
+          when NilClass
+            []
+          else
+            [options[:play]]
+        end)
+
+        play_command = if options.has_key?(:interruptible) && options[:interruptible] == false
+          :play!
+        else
+          options[:interruptible] = true
+          :interruptible_play!
+        end
+
+        if options.has_key? :speak
+          raise ArgumentError, ':speak must be a Hash' unless options[:speak].is_a? Hash
+          raise ArgumentError, 'Must include a text string when requesting TTS fallback' unless options[:speak].has_key?(:text)
+          if options.has_key?(:speak) && options.has_key?(:play) && options[:play].size > 0
+            raise ArgumentError, 'Must specify only one of :play or :speak'
+          end
+        end
+
+        timeout     = options[:timeout]
+        terminator  = options[:terminator]
+
+        terminator = if terminator
+          terminator.to_s
+        elsif number_of_digits.nil? && !terminator.equal?(false)
+          '#'
+        end
+
+        if number_of_digits && number_of_digits < 0
+          logger.warn "Giving -1 to #input is now deprecated. Do not specify a first " +
+                           "argument to allow unlimited digits." if number_of_digits == -1
+          raise ArgumentError, "The number of digits must be positive!"
+        end
+
+        buffer = ''
+        if options[:play].any?
+          # Consume the sound files one at a time. In the event of playback
+          # failure, this tells us which files remain unplayed.
+          while output = options[:play].shift
+            if output.class == Hash
+              argument = output.delete(:value)
+              raise ArgumentError, ':value has to be specified for each :play argument that is a Hash' if argument.nil?
+              output = [argument, output]
+            end
+            key = send play_command, output
+            key = nil if play_command == :play!
+            break if key
+          end
+          key ||= ''
+          # instead use a normal play command, :speak is basically an alias
+        elsif options[:speak]
+          speak_output = options[:speak].delete(:text)
+          key = send play_command, speak_output, options[:speak]
+          key = nil if play_command == :play!
+        else
+          key = wait_for_digit timeout
+        end
+
+        loop do
+          return buffer if key.nil?
+          if terminator
+            if key == terminator
+              return buffer
+            else
+              buffer << key
+              return buffer if number_of_digits && number_of_digits == buffer.length
+            end
+          else
+            buffer << key
+            return buffer if number_of_digits && number_of_digits == buffer.length
+          end
+          return buffer if block_given? && yield(buffer)
+          key = wait_for_digit timeout
+        end
+      end # #input!
+    end # Input
+  end
+end