punchblock 1.2.0 → 1.3.0

data/.travis.yml

@@ -2,8 +2,8 @@ language: ruby
 rvm:
   - 1.9.2
   - 1.9.3
-  - jruby-19mode # JRuby in 1.9 mode
-  - rbx-19mode # currently in active development, may or may not work for your project
-  - ruby-head
+  # - jruby-19mode
+  # - rbx-19mode
+  # - ruby-head
 notifications:
   irc: "irc.freenode.org#adhearsion"

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # [develop](https://github.com/adhearsion/punchblock)
 
+# [v1.3.0](https://github.com/adhearsion/punchblock/compare/v1.2.0...v1.3.0) - [2012-07-22](https://rubygems.org/gems/punchblock/versions/1.3.0)
+  * Change: Asterisk output now uses Playback rather than STREAM FILE
+  * Feature: The recordings dir is now checked for existence on startup, and logs an error if it is not there. Asterisk only.
+  * Feature: Punchblock now logs an error if it was unable to add the redirect context on Asterisk on startup.
+  * Feature: Output component now exposes #recording and #recording_uri for easy access to record results.
+  * Feature: Early media support for Asterisk, using Progress to start an early media session
+  * Feature: Output component on Asterisk now supports early media. If the line is not answered, it runs Progress followed by Playback with noanswer.
+  * Feature: Record component on Asterisk now raises if called on an unanswered call
+  * Feature: Input component on Asterisk works the same whether the call is answered or unanswered
+  * Feature: AMI events are emitted to the relevant calls
+  * Feature: Simpler method of getting hold of a new client/connection
+  * Bugfix: AMI events are processed in order by the translator
+  * Bugfix: Asterisk calls and components are removed from registries when they die
+  * Bugfix: Commands for unknown calls/components respond with the correct `:item_not_found` name
+  * Bugfix: AMI events relevant to a particular call are emitted by that call to the client
+  * Bugfix: Asterisk calls send an error complete event for their dying components
+  * Bugfix: Asterisk translator sends an error end event for its dying calls
+  * Bugfix: Use the primitive version of AGI ANSWER, rather than an app
+  * Bugfix: Outbound calls which never begin progress on Asterisk end with an error
+  * Bugfix: Asterisk now responds correctly to unjoin commands
+  * Bugfix: Allow nil reject reasons
+  * Bugfix: Asterisk translator now does NOT answer the call automatically when Output, Input or Record are used.
+
 # [v1.2.0](https://github.com/adhearsion/punchblock/compare/v1.1.0...v1.2.0) - [2012-04-29](https://rubygems.org/gems/punchblock/versions/1.2.0)
   * Feature: Basic support for record component on Asterisk, using MixMonitor. Currently unsupported options include: start_paused, initial_timeout, final_timeout. Hints are additionally not supported, and recordings are stored on the * machine's local filesystem.
 

data/lib/punchblock.rb

@@ -18,6 +18,7 @@ module Punchblock
   autoload :CommandNode
   autoload :Component
   autoload :Connection
+  autoload :DeadActorSafety
   autoload :DisconnectedError
   autoload :HasHeaders
   autoload :Header
@@ -39,6 +40,29 @@ module Punchblock
     def reset_logger
       @logger = NullObject.new
     end
+
+    #
+    # Get a new Punchblock client with a connection attached
+    #
+    # @param [Symbol] type the connection type (eg :XMPP, :asterisk)
+    # @param [Hash] options the options to pass to the connection (credentials, etc
+    #
+    # @return [Punchblock::Client] a punchblock client object
+    #
+    def client_with_connection(type, options)
+      connection = Connection.const_get(type.to_s.classify).new options
+      Client.new :connection => connection
+    rescue NameError
+      raise ArgumentError, "Connection type #{type.inspect} is not valid."
+    end
+
+    def new_uuid
+      SecureRandom.uuid
+    end
+
+    def jruby?
+      @jruby ||= !!(RUBY_PLATFORM =~ /java/)
+    end
   end
 
   ##

data/lib/punchblock/command/reject.rb

@@ -41,7 +41,8 @@ module Punchblock
       # @return [Symbol] the reason type for rejecting a call
       #
       def reason
-        children.select { |c| c.is_a? Nokogiri::XML::Element }.first.name.to_sym
+        node = reason_node
+        node ? node.name.to_sym : nil
       end
 
       ##
@@ -56,12 +57,19 @@ module Punchblock
           raise ArgumentError, "Invalid Reason (#{reject_reason}), use: #{VALID_REASONS*' '}"
         end
         children.each(&:remove)
-        self << RayoNode.new(reject_reason)
+        self << RayoNode.new(reject_reason) if reject_reason
       end
 
       def inspect_attributes # :nodoc:
         [:reason] + super
       end
+
+      private
+
+      def reason_node
+        node_children = children.select { |c| [Nokogiri::XML::Element, Niceogiri::XML::Node].any? { |k| c.is_a?(k) } }
+        node_children.first
+      end
     end # Reject
   end # Command
 end # Punchblock

data/lib/punchblock/component/record.rb

@@ -188,6 +188,22 @@ module Punchblock
         end
       end
 
+      ##
+      # Directly returns the recording for the component
+      # @return [Punchblock::Component::Record::Recording] The recording object
+      # 
+      def recording
+        complete_event.recording
+      end
+      
+      ##
+      # Directly returns the recording URI for the component
+      # @return [String] The recording URI
+      # 
+      def recording_uri
+        recording.uri
+      end
+
       class Pause < CommandNode # :nodoc:
         register :pause, :record
       end

data/lib/punchblock/core_ext/blather/stanza.rb

@@ -7,8 +7,10 @@ module Blather
     #   representing the Rayo command/event contained within the stanza
     #
     def rayo_node
-      first_child = children.first
+      first_child = at_xpath '*'
       Punchblock::RayoNode.import first_child, nil, component_id if first_child
+    rescue Punchblock::RayoNode::InvalidNodeError
+      nil
     end
 
     ##

data/lib/punchblock/dead_actor_safety.rb

@@ -0,0 +1,9 @@
+module Punchblock
+  module DeadActorSafety
+    def safe_from_dead_actors
+      yield
+    rescue Celluloid::DeadActorError => e
+      pb_logger.error e
+    end
+  end
+end

data/lib/punchblock/event/complete.rb

@@ -10,12 +10,11 @@ module Punchblock
       register :complete, :ext
 
       def reason
-        element = find_first('*')
-        if element
-          RayoNode.import(element).tap do |reason|
-            reason.target_call_id = target_call_id
-            reason.component_id = component_id
-          end
+        element = find_first '*'
+        return unless element
+        RayoNode.import(element).tap do |reason|
+          reason.target_call_id = target_call_id
+          reason.component_id = component_id
         end
       end
 
@@ -26,11 +25,10 @@ module Punchblock
 
       def recording
         element = find_first('//ns:recording', :ns => RAYO_NAMESPACES[:record_complete])
-        if element
-          RayoNode.import(element).tap do |recording|
-            recording.target_call_id = target_call_id
-            recording.component_id = component_id
-          end
+        return unless element
+        RayoNode.import(element).tap do |recording|
+          recording.target_call_id = target_call_id
+          recording.component_id = component_id
         end
       end
 

data/lib/punchblock/rayo_node.rb

@@ -5,6 +5,8 @@ require 'niceogiri'
 
 module Punchblock
   class RayoNode < Niceogiri::XML::Node
+    InvalidNodeError = Class.new Punchblock::Error
+
     @@registrations = {}
 
     class_attribute :registered_ns, :registered_name
@@ -41,6 +43,7 @@ module Punchblock
     # @param [XML::Node] node the node to import
     # @return the appropriate object based on the node name and namespace
     def self.import(node, call_id = nil, component_id = nil)
+      node = Nokogiri::XML(node.to_xml).root if Punchblock.jruby?
       ns = (node.namespace.href if node.namespace)
       klass = class_from_registration(node.element_name, ns)
       if klass && klass != self
@@ -60,6 +63,7 @@ module Punchblock
     # not provided one will be created
     # @return a new object with the registered name and namespace
     def self.new(name = registered_name, doc = nil)
+      raise InvalidNodeError, "Trying to create a new #{self} with no name" unless name
       super name, doc, registered_ns
     end
 

data/lib/punchblock/translator/asterisk.rb

@@ -19,6 +19,8 @@ module Punchblock
       REDIRECT_EXTENSION = '1'
       REDIRECT_PRIORITY = '1'
 
+      trap_exit :actor_died
+
       def initialize(ami_client, connection, media_engine = nil)
         pb_logger.debug "Starting up..."
         @ami_client, @connection, @media_engine = ami_client, connection, media_engine
@@ -31,6 +33,11 @@ module Punchblock
         @calls[call.id] ||= call
       end
 
+      def deregister_call(call)
+        @channel_to_call_id.delete call.channel
+        @calls.delete call.id
+      end
+
       def call_with_id(call_id)
         @calls[call_id]
       end
@@ -54,24 +61,28 @@ module Punchblock
       end
 
       def handle_ami_event(event)
-        return unless event.is_a? RubyAMI::Event
-
-        if event.name.downcase == "fullybooted"
-          pb_logger.trace "Counting FullyBooted event"
-          @fully_booted_count += 1
-          if @fully_booted_count >= 2
-            handle_pb_event Connection::Connected.new
-            @fully_booted_count = 0
-            run_at_fully_booted
+        exclusive do
+          return unless event.is_a? RubyAMI::Event
+
+          if event.name.downcase == "fullybooted"
+            pb_logger.trace "Counting FullyBooted event"
+            @fully_booted_count += 1
+            if @fully_booted_count >= 2
+              handle_pb_event Connection::Connected.new
+              @fully_booted_count = 0
+              run_at_fully_booted
+            end
+            return
           end
-          return
-        end
 
-        handle_varset_ami_event event
+          handle_varset_ami_event event
 
-        ami_dispatch_to_or_create_call event
+          ami_dispatch_to_or_create_call event
 
-        handle_pb_event Event::Asterisk::AMI::Event.new(:name => event.name, :attributes => event.headers)
+          unless ami_event_known_call?(event)
+            handle_pb_event Event::Asterisk::AMI::Event.new(:name => event.name, :attributes => event.headers)
+          end
+        end
       end
 
       def handle_pb_event(event)
@@ -98,7 +109,7 @@ module Punchblock
         if call = call_with_id(command.target_call_id)
           call.execute_command! command
         else
-          command.response = ProtocolError.new.setup 'call-not-found', "Could not find a call with ID #{command.target_call_id}", command.target_call_id
+          command.response = ProtocolError.new.setup :item_not_found, "Could not find a call with ID #{command.target_call_id}", command.target_call_id
         end
       end
 
@@ -106,7 +117,7 @@ module Punchblock
         if (component = component_with_id(command.component_id))
           component.execute_command! command
         else
-          command.response = ProtocolError.new.setup 'component-not-found', "Could not find a component with ID #{command.component_id}", command.target_call_id, command.component_id
+          command.response = ProtocolError.new.setup :item_not_found, "Could not find a component with ID #{command.component_id}", command.target_call_id, command.component_id
         end
       end
 
@@ -117,7 +128,7 @@ module Punchblock
           register_component component
           component.execute!
         when Punchblock::Command::Dial
-          call = Call.new command.to, current_actor
+          call = Call.new_link command.to, current_actor
           register_call call
           call.dial! command
         else
@@ -134,6 +145,29 @@ module Punchblock
           'Command' => "dialplan add extension #{REDIRECT_EXTENSION},#{REDIRECT_PRIORITY},AGI,agi:async into #{REDIRECT_CONTEXT}"
         })
         pb_logger.trace "Added extension extension #{REDIRECT_EXTENSION},#{REDIRECT_PRIORITY},AGI,agi:async into #{REDIRECT_CONTEXT}"
+        send_ami_action('Command', {
+          'Command' => "dialplan show #{REDIRECT_CONTEXT}"
+        }) do |result|
+          if result.text_body =~ /failed/
+            pb_logger.error "Punchblock failed to add the #{REDIRECT_EXTENSION} extension to the #{REDIRECT_CONTEXT} context. Please add a [#{REDIRECT_CONTEXT}] entry to your dialplan."
+          end
+        end
+      end
+
+      def check_recording_directory
+        pb_logger.warning "Recordings directory #{Component::Record::RECORDING_BASE_PATH} does not exist. Recording might not work. This warning can be ignored if Adhearsion is running on a separate machine than Asterisk. See http://adhearsion.com/docs/call-controllers#recording" unless File.exists?(Component::Record::RECORDING_BASE_PATH)
+      end
+
+      def actor_died(actor, reason)
+        return unless reason
+        pb_logger.error "A linked actor (#{actor.inspect}) died due to #{reason.inspect}"
+        if id = @calls.key(actor)
+          pb_logger.info "Dead actor was a call we know about, with ID #{id}. Removing it from the registry..."
+          @calls.delete id
+          end_event = Punchblock::Event::End.new :target_call_id  => id,
+                                                 :reason          => :error
+          handle_pb_event end_event
+        end
       end
 
       private
@@ -149,10 +183,8 @@ module Punchblock
       end
 
       def ami_dispatch_to_or_create_call(event)
-        if (event['Channel'] && call_for_channel(event['Channel'])) ||
-            (event['Channel1'] && call_for_channel(event['Channel1'])) ||
-            (event['Channel2'] && call_for_channel(event['Channel2']))
-          [event['Channel'], event['Channel1'], event['Channel2']].compact.each do |channel|
+        if ami_event_known_call?(event)
+          channels_for_ami_event(event).each do |channel|
             call = call_for_channel channel
             call.process_ami_event! event if call
           end
@@ -161,14 +193,25 @@ module Punchblock
         end
       end
 
+      def channels_for_ami_event(event)
+        [event['Channel'], event['Channel1'], event['Channel2']].compact
+      end
+
+      def ami_event_known_call?(event)
+        (event['Channel'] && call_for_channel(event['Channel'])) ||
+          (event['Channel1'] && call_for_channel(event['Channel1'])) ||
+          (event['Channel2'] && call_for_channel(event['Channel2']))
+      end
+
       def handle_async_agi_start_event(event)
-        env = Call.parse_environment event['Env']
+        env = RubyAMI::AsyncAGIEnvironmentParser.new(event['Env']).to_hash
 
         return pb_logger.warn "Ignoring AsyncAGI Start event because it is for an 'h' extension" if env[:agi_extension] == 'h'
         return pb_logger.warn "Ignoring AsyncAGI Start event because it is for an 'Kill' type" if env[:agi_type] == 'Kill'
 
         pb_logger.trace "Handling AsyncAGI Start event by creating a new call"
         call = Call.new event['Channel'], current_actor, env
+        link call
         register_call call
         call.send_offer!
       end

data/lib/punchblock/translator/asterisk/call.rb

@@ -1,13 +1,12 @@
 # encoding: utf-8
 
-require 'uri'
-
 module Punchblock
   module Translator
     class Asterisk
       class Call
         include HasGuardedHandlers
         include Celluloid
+        include DeadActorSafety
 
         attr_reader :id, :channel, :translator, :agi_env, :direction, :pending_joins
 
@@ -21,26 +20,16 @@ module Punchblock
         HANGUP_CAUSE_TO_END_REASON[22] = :reject
         HANGUP_CAUSE_TO_END_REASON[102] = :timeout
 
-        class << self
-          def parse_environment(agi_env)
-            agi_env_as_array(agi_env).inject({}) do |accumulator, element|
-              accumulator[element[0].to_sym] = element[1] || ''
-              accumulator
-            end
-          end
-
-          def agi_env_as_array(agi_env)
-            URI::Parser.new.unescape(agi_env).encode.split("\n").map { |p| p.split ': ' }
-          end
-        end
+        trap_exit :actor_died
 
         def initialize(channel, translator, agi_env = nil)
           @channel, @translator = channel, translator
           @agi_env = agi_env || {}
-          @id, @components = UUIDTools::UUID.random_create.to_s, {}
+          @id, @components = Punchblock.new_uuid, {}
           @answered = false
           @pending_joins = {}
           pb_logger.debug "Starting up call with channel #{channel}, id #{@id}"
+          @progress_sent = false
         end
 
         def register_component(component)
@@ -96,9 +85,11 @@ module Punchblock
           @answered
         end
 
-        def answer_if_not_answered
-          return if answered? || outbound?
-          execute_command Command::Answer.new.tap { |a| a.request! }
+        def send_progress
+          return if answered? || outbound? || @progress_sent
+          pb_logger.debug "Sending Progress to start early media"
+          @progress_sent = true
+          send_agi_action "EXEC Progress"
         end
 
         def channel=(other)
@@ -107,19 +98,23 @@ module Punchblock
         end
 
         def process_ami_event(ami_event)
+          send_pb_event Event::Asterisk::AMI::Event.new(:name => ami_event.name, :attributes => ami_event.headers)
+
           case ami_event.name
           when 'Hangup'
             pb_logger.trace "Received a Hangup AMI event. Sending End event."
             @components.dup.each_pair do |id, component|
-              component.call_ended if component.alive?
+              safe_from_dead_actors do
+                component.call_ended if component.alive?
+              end
             end
             send_end_event HANGUP_CAUSE_TO_END_REASON[ami_event['Cause'].to_i]
           when 'AsyncAGI'
             pb_logger.trace "Received an AsyncAGI event. Looking for matching AGICommand component."
             if component = component_with_id(ami_event['CommandID'])
-              component.handle_ami_event! ami_event
+              component.handle_ami_event ami_event
             else
-              pb_logger.warn "Could not find component for AMI event: #{ami_event.inspect}"
+              pb_logger.trace "Could not find component for AMI event: #{ami_event.inspect}"
             end
           when 'Newstate'
             pb_logger.trace "Received a Newstate AMI event with state #{ami_event['ChannelState']}: #{ami_event['ChannelStateDesc']}"
@@ -130,6 +125,11 @@ module Punchblock
               @answered = true
               send_pb_event Event::Answered.new
             end
+          when 'OriginateResponse'
+            if ami_event['Response'] == 'Failure' && ami_event['Uniqueid'] == '<null>'
+              pb_logger.info "Outbound call could not be established!"
+              send_end_event :error
+            end
           when 'BridgeExec'
             if join_command = pending_joins[ami_event['Channel2']]
               join_command.response = true
@@ -165,9 +165,9 @@ module Punchblock
           pb_logger.debug "Executing command: #{command.inspect}"
           if command.component_id
             if component = component_with_id(command.component_id)
-              component.execute_command! command
+              component.execute_command command
             else
-              command.response = ProtocolError.new.setup 'component-not-found', "Could not find a component with ID #{command.component_id} for call #{id}", id, command.component_id
+              command.response = ProtocolError.new.setup :item_not_found, "Could not find a component with ID #{command.component_id} for call #{id}", id, command.component_id
             end
           end
           case command
@@ -182,7 +182,7 @@ module Punchblock
               end
             end
           when Command::Answer
-            send_agi_action 'EXEC ANSWER' do |response|
+            send_agi_action 'ANSWER' do |response|
               command.response = true
             end
           when Command::Hangup
@@ -195,7 +195,14 @@ module Punchblock
             send_agi_action 'EXEC Bridge', other_call.channel
           when Command::Unjoin
             other_call = translator.call_with_id command.call_id
-            redirect_back other_call
+            redirect_back other_call do |response|
+              case response
+              when RubyAMI::Error
+                command.response = ProtocolError.new.setup 'error', response.message
+              else
+                command.response = true
+              end
+            end
           when Command::Reject
             rejection = case command.reason
             when :busy
@@ -238,7 +245,7 @@ module Punchblock
           (name.is_a?(RubyAMI::Action) ? name : RubyAMI::Action.new(name, headers, &block)).tap do |action|
             @current_ami_action = action
             pb_logger.trace "Sending AMI action #{action.inspect}"
-            translator.send_ami_action! action
+            translator.send_ami_action action
           end
         end
 
@@ -246,7 +253,7 @@ module Punchblock
           "#{self.class}: #{id}"
         end
 
-        def redirect_back(other_call = nil)
+        def redirect_back(other_call = nil, &block)
           redirect_options = {
             'Channel'   => channel,
             'Exten'     => Asterisk::REDIRECT_EXTENSION,
@@ -259,18 +266,30 @@ module Punchblock
             'ExtraPriority'  => Asterisk::REDIRECT_PRIORITY,
             'ExtraContext'   => Asterisk::REDIRECT_CONTEXT
           }) if other_call
-          send_ami_action 'Redirect', redirect_options
+          send_ami_action 'Redirect', redirect_options, &block
+        end
+
+        def actor_died(actor, reason)
+          return unless reason
+          pb_logger.error "A linked actor (#{actor.inspect}) died due to #{reason.inspect}"
+          if id = @components.key(actor)
+            pb_logger.info "Dead actor was a component we know about, with ID #{id}. Removing it from the registry..."
+            @components.delete id
+            complete_event = Punchblock::Event::Complete.new :component_id => id, :reason => Punchblock::Event::Complete::Error.new
+            send_pb_event complete_event
+          end
         end
 
         private
 
         def send_end_event(reason)
           send_pb_event Event::End.new(:reason => reason)
+          translator.deregister_call current_actor
           after(5) { shutdown }
         end
 
         def execute_component(type, command, options = {})
-          type.new(command, current_actor).tap do |component|
+          type.new_link(command, current_actor).tap do |component|
             register_component component
             component.internal = true if options[:internal]
             component.execute!
@@ -280,7 +299,7 @@ module Punchblock
         def send_pb_event(event)
           event.target_call_id = id
           pb_logger.trace "Sending Punchblock event: #{event.inspect}"
-          translator.handle_pb_event! event
+          translator.handle_pb_event event
         end
 
         def offer_event