adhearsion 2.0.0.alpha3 → 2.0.0.beta1

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 2.0.0.beta1 - 2012-03-07
+  * Bugfix: #speak now correctly casts the argument to string if it is not SSML
+  * Bugfix: The console pauses controllers on a call while taking control
+  * Feature: Reopen logfiles on SIGHUP
+  * Feature: Toggle :trace logging on SIGALRM (useful for debugging a live process)
+  * Feature: It is now possible to execute a global component (using `Adhearsion::PunchblockPlugin.execute_component`)
+  * Feature: Now set XMPP JID resource to a concatenation of hostname and process ID for ID/debugging purposes
+  * Feature: CallController#dial now returns a DialStatus object indicating the status of the dial command
+  * Feature: Punchblock plugin can now configure the active media engine (mostly for use on Asterisk)
+  * Bugfix: Fix forcing Adhearsion to stop with enough SIGTERM or CTRL+C
+
 # 2.0.0.alpha3 - 2012-02-21
   * Feature: Add `ahn generate` command to allow invocation of generators
   * Feature: Add simple generator for call controllers
@@ -10,11 +21,12 @@
   * Feature: The console can take control of a call
   * Bugfix: CallController#dial now blocks until all outbound calls complete
   * Bugfix: Call commands timing out now raise a timeout exception in the caller, but do not crash the actor
+  * Feature: It is now possible to pause/resume call controllers
   * Bugfix: CallController#dial now unblocks immediately if the original call ends
   * Bugfix: CallController#dial now unblocks when the connected outbound call unjoins, rather than ending, incase post-processing on the outbound call is required
   * Bugfix: CallController#dial now hangs up outbound legs when it unblocks
   * Feature: CallController#dial now defaults the outbound caller ID to that of the controller's call
-  * Change: The command to take control of a call is now 'take' rather than 'use'.  'take' called without a call ID present a list of currently running calls
+  * Change: The command to take control of a call is now 'take' rather than 'use'. 'take' called without a call ID present a list of currently running calls
 
 # 2.0.0.alpha2 - 2012-01-30
   * Change: Plugins no longer load dialplan/event/rpc/console methods using corresponding class methods

data/README.markdown

@@ -20,7 +20,7 @@ Features
 Requirements
 ------------
 
-* Ruby 1.9.2+ or JRuby 1.6.5+
+* Ruby 1.9.2+ or JRuby 1.6.7+
 * A VoIP platform:
   * Asterisk 1.8+
   * Prism 11+ with rayo-server

data/features/cli_daemon.feature

@@ -9,8 +9,7 @@ Feature: Adhearsion Ahn CLI (daemon)
     When I run `ahn daemon path/somewhere`
     And I cd to "path/somewhere"
     And I terminate the process using the pid file "adhearsion.pid"
-    Then the output should contain "Daemonizing now"
-    And the exit status should be 0
+    Then the exit status should be 0
 
   Scenario: Command daemon with pid option
     Given JRuby skip test
@@ -18,4 +17,4 @@ Feature: Adhearsion Ahn CLI (daemon)
     When I run `ahn daemon path/somewhere --pid-file=ahn.pid`
     And I cd to "path/somewhere"
     And I terminate the process using the pid file "ahn.pid"
-    Then the output should contain "Daemonizing now"
+    Then the exit status should be 0

data/features/step_definitions/cli_steps.rb

@@ -69,6 +69,5 @@ When /^I terminate the process using the pid file "([^"]*)"$/ do |pidfile|
     pid = File.read(pidfile).to_i
     Process.kill("TERM", pid)
     sleep 1
-    Process.kill("KILL", pid)
   end
 end

data/lib/adhearsion/call.rb

@@ -1,33 +1,27 @@
 require 'thread'
 
-module Celluloid
-  module ClassMethods
-    def ===(other)
-      other.kind_of? self
-    end
-  end
-
-  class ActorProxy
-    def is_a?(klass)
-      Actor.call @mailbox, :is_a?, klass
-    end
-
-    def kind_of?(klass)
-      Actor.call @mailbox, :kind_of?, klass
-    end
-  end
-end
-
 module Adhearsion
   ##
   # Encapsulates call-related data and behavior.
   #
   class Call
 
+    ExpiredError = Class.new Celluloid::DeadActorError
+
     include Celluloid
     include HasGuardedHandlers
 
-    attr_accessor :offer, :client, :end_reason, :commands, :variables
+    def self.new(*args, &block)
+      super.tap do |proxy|
+        def proxy.method_missing(*args)
+          super
+        rescue Celluloid::DeadActorError => e
+          raise ExpiredError, "This call is expired and is no longer accessible"
+        end
+      end
+    end
+
+    attr_accessor :offer, :client, :end_reason, :commands, :variables, :controllers
 
     delegate :[], :[]=, :to => :variables
     delegate :to, :from, :to => :offer, :allow_nil => true
@@ -35,9 +29,10 @@ module Adhearsion
     def initialize(offer = nil)
       register_initial_handlers
 
-      @tags       = []
-      @commands   = CommandRegistry.new
-      @variables  = {}
+      @tags         = []
+      @commands     = CommandRegistry.new
+      @variables    = {}
+      @controllers  = []
 
       self << offer if offer
     end
@@ -77,7 +72,7 @@ module Adhearsion
 
     alias << deliver_message
 
-    def register_initial_handlers
+    def register_initial_handlers # :nodoc:
       register_event_handler Punchblock::Event::Offer do |offer|
         @offer  = offer
         @client = offer.client
@@ -93,10 +88,14 @@ module Adhearsion
         clear_from_active_calls
         @end_reason = event.reason
         commands.terminate
-        after(5) { current_actor.terminate! }
+        after(after_end_hold_time) { current_actor.terminate! }
       end
     end
 
+    def after_end_hold_time # :nodoc:
+      30
+    end
+
     def on_end(&block)
       register_event_handler Punchblock::Event::End do |event|
         block.call event
@@ -126,7 +125,7 @@ module Adhearsion
       write_and_await_response Punchblock::Command::Hangup.new(:headers => headers)
     end
 
-    def clear_from_active_calls
+    def clear_from_active_calls # :nodoc:
       Adhearsion.active_calls.remove_inactive_call current_actor
     end
 
@@ -180,17 +179,17 @@ module Adhearsion
     end
 
     def write_command(command)
-      abort Hangup.new unless active? || command.is_a?(Punchblock::Command::Hangup)
+      abort Hangup.new(@end_reason) unless active? || command.is_a?(Punchblock::Command::Hangup)
       variables.merge! command.headers_hash if command.respond_to? :headers_hash
-      logger.trace "Executing command #{command.inspect}"
+      logger.debug "Executing command #{command.inspect}"
       client.execute_command command, :call_id => id
     end
 
-    def logger_id
+    def logger_id # :nodoc:
       "#{self.class}: #{id}"
     end
 
-    def logger
+    def logger # :nodoc:
       super
     end
 
@@ -198,8 +197,15 @@ module Adhearsion
       [current_actor]
     end
 
+    def inspect
+      attrs = [:offer, :end_reason, :commands, :variables, :controllers, :to, :from].map do |attr|
+        "#{attr}=#{send(attr).inspect}"
+      end
+      "#<#{self.class}:#{id} #{attrs.join ', '}>"
+    end
+
     def execute_controller(controller, latch = nil)
-      Adhearsion::Process.important_threads << Thread.new do
+      Thread.new do
         catching_standard_errors do
           begin
             CallController.exec controller
@@ -208,10 +214,22 @@ module Adhearsion
           end
           latch.countdown! if latch
         end
-      end
+      end.tap { |t| Adhearsion::Process.important_threads << t }
+    end
+
+    def register_controller(controller)
+      @controllers << controller
+    end
+
+    def pause_controllers
+      controllers.each &:pause!
+    end
+
+    def resume_controllers
+      controllers.each &:resume!
     end
 
-    class CommandRegistry < ThreadSafeArray
+    class CommandRegistry < ThreadSafeArray # :nodoc:
       def terminate
         hangup = Hangup.new
         each { |command| command.response = hangup if command.requested? }

data/lib/adhearsion/call_controller.rb

@@ -54,13 +54,13 @@ module Adhearsion
 
     delegate :[], :[]=, :to => :@metadata
     delegate :variables, :logger, :to => :call
-    delegate :write_and_await_response, :answer, :reject, :mute, :unmute, :join, :to => :call
 
     def initialize(call, metadata = nil, &block)
       @call, @metadata, @block = call, metadata || {}, block
     end
 
-    def execute!(*options)
+    def execute!(*options) # :nodoc:
+      call.register_controller! self
       execute_callbacks :before_call
       run
     rescue Hangup
@@ -84,7 +84,7 @@ module Adhearsion
       throw :pass_controller, controller_class.new(call, metadata)
     end
 
-    def execute_callbacks(type)
+    def execute_callbacks(type) # :nodoc:
       self.class.callbacks[type].each do |callback|
         catching_standard_errors do
           instance_exec &callback
@@ -92,15 +92,21 @@ module Adhearsion
       end
     end
 
-    def after_call
+    def after_call # :nodoc:
       @after_call ||= execute_callbacks :after_call
     end
 
     def hangup(headers = nil)
+      block_until_resumed
       hangup_response = call.hangup headers
       after_call unless hangup_response == false
     end
 
+    def write_and_await_response(command)
+      block_until_resumed
+      call.write_and_await_response command
+    end
+
     def execute_component_and_await_completion(component)
       write_and_await_response component
 
@@ -110,5 +116,48 @@ module Adhearsion
       raise StandardError, complete_event.reason.details if complete_event.reason.is_a? Punchblock::Event::Complete::Error
       component
     end
+
+    def answer(*args)
+      block_until_resumed
+      call.answer *args
+    end
+
+    def reject(*args)
+      block_until_resumed
+      call.reject *args
+    end
+
+    def mute(*args)
+      block_until_resumed
+      call.mute *args
+    end
+
+    def unmute(*args)
+      block_until_resumed
+      call.unmute *args
+    end
+
+    def join(*args)
+      block_until_resumed
+      call.join *args
+    end
+
+    def block_until_resumed # :nodoc:
+      @pause_latch && @pause_latch.wait
+    end
+
+    def pause! # :nodoc:
+      @pause_latch = CountDownLatch.new 1
+    end
+
+    def resume! # :nodoc:
+      return unless @pause_latch
+      @pause_latch.countdown!
+      @pause_latch = nil
+    end
+
+    def inspect
+      "#<#{self.class} call=#{call.id}, metadata=#{metadata.inspect}>"
+    end
   end#class
 end

data/lib/adhearsion/call_controller/dial.rb

@@ -32,6 +32,7 @@ module Adhearsion
       #
       def dial(to, options = {}, latch = nil)
         targets = Array(to)
+        status = DialStatus.new
 
         latch ||= CountDownLatch.new targets.size
 
@@ -43,7 +44,7 @@ module Adhearsion
         options[:from] ||= call.from
 
         calls = targets.map do |target|
-          new_call = OutboundCall.new options
+          new_call = OutboundCall.new
 
           new_call.on_answer do |event|
             calls.each do |call_to_hangup, target|
@@ -57,17 +58,18 @@ module Adhearsion
             end
 
             new_call.register_event_handler Punchblock::Event::Unjoined, :other_call_id => call.id do |event|
-              new_call[:"dial_countdown_#{call.id}"] = true
+              new_call["dial_countdown_#{call.id}"] = true
               latch.countdown!
               throw :pass
             end
 
             logger.debug "Joining call #{new_call.id} to #{call.id} due to a #dial"
             new_call.join call
+            status.answer!
           end
 
           new_call.on_end do |event|
-            latch.countdown! unless new_call[:"dial_countdown_#{call.id}"]
+            latch.countdown! unless new_call["dial_countdown_#{call.id}"]
           end
 
           [new_call, target]
@@ -78,7 +80,10 @@ module Adhearsion
           call
         end
 
-        timeout = latch.wait options[:timeout]
+        status.calls = calls
+
+        no_timeout = latch.wait options[:timeout]
+        status.timeout! unless no_timeout
 
         logger.debug "#dial finished. Hanging up #{calls.size} outbound calls #{calls.inspect}."
         calls.each do |outbound_call|
@@ -90,9 +95,24 @@ module Adhearsion
           end
         end
 
-        return timeout unless timeout
+        status
+      end
+
+      class DialStatus
+        attr_accessor :calls
+        attr_reader :result
+
+        def initialize
+          @result = :no_answer
+        end
+
+        def answer!
+          @result = :answer
+        end
 
-        calls.size == 1 ? calls.first : calls
+        def timeout!
+          @result = :timeout
+        end
       end
 
     end#module Dial

data/lib/adhearsion/call_controller/input.rb

@@ -7,7 +7,7 @@ module Adhearsion
       # @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)
+      def wait_for_digit(timeout = 1) # :nodoc:
         timeout = nil if timeout == -1
         timeout *= 1_000 if timeout
         input_component = execute_component_and_await_completion ::Punchblock::Component::Input.new :mode => :dtmf,

data/lib/adhearsion/call_controller/menu.rb

@@ -103,7 +103,7 @@ module Adhearsion
         return :done
       end
 
-      def play_sound_files_for_menu(menu_instance, sound_files)
+      def play_sound_files_for_menu(menu_instance, sound_files) # :nodoc:
         digit = nil
         if sound_files.any? && menu_instance.digit_buffer_empty?
           digit = interruptible_play *sound_files
@@ -111,7 +111,7 @@ module Adhearsion
         digit || wait_for_digit(menu_instance.timeout)
       end
 
-      def jump_to(match_object, overrides = nil)
+      def jump_to(match_object, overrides = nil) # :nodoc:
         if match_object.block
           instance_exec overrides[:extension], &match_object.block
         else

data/lib/adhearsion/call_controller/output.rb

@@ -2,7 +2,7 @@ module Adhearsion
   class CallController
     module Output
       def speak(text, options = {})
-        play_ssml(text, options) || output(:text, text, options)
+        play_ssml(text, options) || output(:text, text.to_s, options)
       end
 
       #
@@ -110,18 +110,18 @@ module Adhearsion
         play_ssml ssml_for_audio(argument, options)
       end
 
-      def play_ssml(ssml, options = {})
+      def play_ssml(ssml, options = {}) # :nodoc:
         if [RubySpeech::SSML::Speak, Nokogiri::XML::Document].include? ssml.class
           output :ssml, ssml.to_s, options
         end
       end
 
-      def output(type, content, options = {})
+      def output(type, content, options = {}) # :nodoc:
         options.merge! type => content
         execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
       end
 
-      def output!(type, content, options = {})
+      def output!(type, content, options = {}) # :nodoc:
         options.merge! type => content
         execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
       end
@@ -170,7 +170,7 @@ module Adhearsion
         result
       end
 
-      def detect_type(output)
+      def detect_type(output) # :nodoc:
         result = nil
         result = :time if [Date, Time, DateTime].include? output.class
         result = :numeric if output.kind_of?(Numeric) || output =~ /^\d+$/
@@ -178,7 +178,7 @@ module Adhearsion
         result ||= :text
       end
 
-      def play_ssml_for(*args)
+      def play_ssml_for(*args) # :nodoc:
         play_ssml ssml_for(args)
       end
 
@@ -189,7 +189,7 @@ module Adhearsion
       # @param [String|Hash|RubySpeech::SSML::Speak] the argument with options as accepted by the play_ methods, or an SSML document
       # @return [RubySpeech::SSML::Speak] an SSML document
       #
-      def ssml_for(*args)
+      def ssml_for(*args) # :nodoc:
         return args[0] if args.size == 1 && args[0].is_a?(RubySpeech::SSML::Speak)
         argument, options = args.flatten
         options ||= {}
@@ -197,11 +197,11 @@ module Adhearsion
         send "ssml_for_#{type}", argument, options
       end
 
-      def ssml_for_text(argument, options = {})
+      def ssml_for_text(argument, options = {}) # :nodoc:
         RubySpeech::SSML.draw { argument }
       end
 
-      def ssml_for_time(argument, options = {})
+      def ssml_for_time(argument, options = {}) # :nodoc:
         interpretation = case argument
         when Date then 'date'
         when Time then 'time'
@@ -217,13 +217,13 @@ module Adhearsion
         end
       end
 
-      def ssml_for_numeric(argument, options = {})
+      def ssml_for_numeric(argument, options = {}) # :nodoc:
         RubySpeech::SSML.draw do
           say_as(:interpret_as => 'cardinal') { argument.to_s }
         end
       end
 
-      def ssml_for_audio(argument, options = {})
+      def ssml_for_audio(argument, options = {}) # :nodoc:
         fallback = (options || {}).delete :fallback
         RubySpeech::SSML.draw do
           audio(:src => argument) { fallback }