adhearsion 2.1.3 → 2.2.0

data/CHANGELOG.md

@@ -1,5 +1,92 @@
 # [develop](https://github.com/adhearsion/adhearsion)
 
+# [2.2.0](https://github.com/adhearsion/adhearsion/compare/v2.1.3...v2.2.0) - [2012-12-17](https://rubygems.org/gems/adhearsion/versions/2.2.0)
+  * Feature: Statistics API providing counts of calls dialed, offered, rejected, routed and active
+
+    ```ruby
+    Adhearsion.statistics.dump # => #<Adhearsion::Statistics::Dump timestamp=2012-12-17 10:31:05 -0500, call_counts={:dialed=>0, :offered=>18, :routed=>6, :rejected=>0, :active=>0}, calls_by_route={"Sesame Street"=>3, "Mr. Rogers Neighborhood"=>2, "default"=>1}>
+    ```
+  * Feature: Accessor for peer calls when bridged
+
+    ```ruby
+    call.peers # => {"0f4h382j290k09k" => #<Adhearsion::Call ...>}
+    ```
+  * Feature: Allow specifying controller metadata when originating outbound calls
+
+    ```ruby
+    Adhearsion::OutboundCall.originate 'foo@bar.com', controller: FooBarController, controller_metadata: {foo: 'bar'}
+    ```
+  * Feature: Allow specifying confirmation controller metadata to `CallController#dial`
+
+    ```ruby
+    dial 'foo@bar.com', confirm: ConfirmationController, confirm_metadata: {foo: 'bar'}
+    ```
+  * Feature: Set default voice on output components when specified in config
+
+    ```ruby
+    config.punchblock.default_voice = 'kal'
+    ```
+  * Feature: Be more flexible about DTMF utterance parsing
+  * Feature: Added specs for the SimonGame
+  * Feature: Allow configuring the lifetime of a call object after hangup. This makes it possible to control the number of call objects (and therefore threads) in use by Adhearsion, by expiring them earlier or later than the 30 second default (as measured from the point at which the call disconnects).
+
+    ```ruby
+    config.platform.after_hangup_lifetime = 10
+    ```
+  * Feature: Support collections passed to `CallController#play`
+    ```ruby
+    recordings = ['one', 'two', 'three']
+    play recordings
+    ````
+  * Feature: Support arrays passed to `#match` in a `CallController#menu`
+    ```ruby
+    possible_digits = [1,2,3,4]
+    menu 'foobar' do
+      match possible_digits, FooController
+    end
+    ```
+  * Feature: Output document formatter for a call controller is now overridable
+    ```ruby
+    # Replacement formatter designed to render all TTS extra slow
+    class MyFormatter < Adhearsion::CallController::Output::Formatter
+      def ssml_for_text(argument, options = {})
+        RubySpeech::SSML.draw do
+          prosody rate: 'x-slow' do
+            argument
+          end
+        end
+      end
+    end
+
+    class MyController < Adhearsion::CallController
+      def run
+        speak "This will be sloooooow"
+      end
+
+      def output_formatter
+        MyFormatter.new
+      end
+    end
+    ```
+  * Feature: Refactored recording functionality into a Recorder class for easier implementation of specific APIs
+    ```ruby
+    # Alternative #record implementation, returning the input component also
+    def record(options = {})
+      recorder = Recorder.new self, options
+
+      recorder.handle_record_completion do |event|
+        catching_standard_errors { yield event if block_given? }
+      end
+
+      recorder.run
+      [recorder.record_component, recorder.stopper_component]
+    end
+    ```
+  * Bugfix: Generate sane spec defaults for new apps and controllers
+  * Bugfix: `CallController#record` now allows partial-second timeouts
+  * Bugfix: Ensure calls are removed from the active collection when they terminate cleanly
+  * Bugfix: Plug a big memory leak
+
 # [2.1.3](https://github.com/adhearsion/adhearsion/compare/v2.1.2...v2.1.3) - [2012-10-11](https://rubygems.org/gems/adhearsion/versions/2.1.3)
   * Bugfix: Originating call is now answered before joining calls using `CallController#dial`
   * Bugfix: Output controller methods no longer falsely detect a string with a colon as a URI for an audio file

data/Guardfile

@@ -1,7 +1,7 @@
 ENV['SKIP_RCOV'] = 'true'
 
 group 'rspec' do
-  guard 'rspec', :version => 2, :cli => '--format documentation' do
+  guard 'rspec', :cli => '--format documentation' do
     watch(%r{^spec/.+_spec\.rb$})
     watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
     watch('spec/spec_helper.rb')  { "spec/" }

data/Rakefile

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-ENV['RUBY_FLAGS'] = "-I#{%w(lib ext bin spec).join(File::PATH_SEPARATOR)}"
 
 require 'bundler/gem_tasks'
 require 'bundler/setup'
@@ -9,7 +8,7 @@ task :gem => :build
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec) do |t|
-  t.ruby_opts = "-w -r./spec/capture_warnings"
+  # t.ruby_opts = "-w -r./spec/capture_warnings"
 end
 
 require 'ci/reporter/rake/rspec'

data/adhearsion.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'ffi', ["~> 1.0"]
   s.add_runtime_dependency 'future-resource', ["~> 1.0"]
   s.add_runtime_dependency 'girl_friday'
-  s.add_runtime_dependency 'has-guarded-handlers', ["~> 1.1"]
+  s.add_runtime_dependency 'has-guarded-handlers', ["~> 1.5"]
   s.add_runtime_dependency 'jruby-openssl' if RUBY_PLATFORM == 'java'
   s.add_runtime_dependency 'logging', ["~> 1.8"]
   s.add_runtime_dependency 'pry'

data/features/cli_create.feature

@@ -12,6 +12,7 @@ Feature: Adhearsion Ahn CLI (Create)
       | Rakefile              |
       | config/adhearsion.rb  |
       | config/environment.rb |
+      | spec/spec_helper.rb   |
     And the file "config/adhearsion.rb" should contain "Adhearsion.router"
     Then the exit status should be 0
 

data/features/step_definitions/cli_steps.rb

@@ -22,16 +22,6 @@ When /^I wait (\d+) seconds?$/ do |arg1|
   sleep arg1.to_i
 end
 
-# TODO: Remove after pull request is merged in cucumber.rb from Aruba
-When /^I wait for (?:output|stdout) to contain "([^"]*)"$/ do |expected|
-  Timeout::timeout(exit_timeout) do
-    loop do
-      break if assert_partial_output_interactive(expected)
-      sleep 0.1
-    end
-  end
-end
-
 Given /^that I create a valid app under "([^"]*)"$/ do |path|
   steps %Q{
     When I run `ahn create #{path}`

data/lib/adhearsion.rb

@@ -34,6 +34,7 @@ module Adhearsion
   autoload :OutboundCall
   autoload :Plugin
   autoload :Router
+  autoload :Statistics
 
   class << self
 
@@ -105,6 +106,16 @@ module Adhearsion
       end
     end
 
+    #
+    # @return [Adhearsion::Statistics] a statistics aggregator object capable of producing stats dumps
+    def statistics
+      if instance_variable_defined?(:@statistics) && @statistics.alive?
+        @statistics
+      else
+        @statistics = Statistics.new.tap(&:setup_event_handlers)
+      end
+    end
+
     def status
       Adhearsion::Process.state_name
     end

data/lib/adhearsion/call.rb

@@ -23,17 +23,10 @@ module Adhearsion
         rescue Celluloid::DeadActorError
           raise ExpiredError, "This call is expired and is no longer accessible"
         end
-
-        def proxy.join(*args)
-          Actor.call @mailbox, :join, *args
-        end
       end
     end
 
-    # @private
-    attr_accessor :offer, :client, :end_reason, :commands, :controllers
-
-    attr_accessor :variables
+    attr_reader :end_reason, :commands, :controllers, :variables
 
     delegate :[], :[]=, :to => :variables
     delegate :to, :from, :to => :offer, :allow_nil => true
@@ -41,11 +34,13 @@ module Adhearsion
     def initialize(offer = nil)
       register_initial_handlers
 
+      @offer        = nil
       @tags         = []
       @commands     = CommandRegistry.new
       @variables    = {}
       @controllers  = []
       @end_reason   = nil
+      @peers        = {}
 
       self << offer if offer
     end
@@ -92,6 +87,14 @@ module Adhearsion
       @tags.include? label
     end
 
+    #
+    # Hash of joined peers
+    # @return [Hash<String => Adhearsion::Call>]
+    #
+    def peers
+      @peers.clone
+    end
+
     def register_event_handler(*guards, &block)
       register_handler :event, *guards, &block
     end
@@ -117,11 +120,13 @@ module Adhearsion
 
       on_joined do |event|
         target = event.call_id || event.mixer_name
+        @peers[target] = Adhearsion.active_calls[target]
         signal :joined, target
       end
 
       on_unjoined do |event|
         target = event.call_id || event.mixer_name
+        @peers.delete target
         signal :unjoined, target
       end
 
@@ -130,14 +135,13 @@ module Adhearsion
         clear_from_active_calls
         @end_reason = event.reason
         commands.terminate
-        after(after_end_hold_time) { current_actor.terminate! }
+        after(Adhearsion.config.platform.after_hangup_lifetime) { current_actor.terminate! }
         throw :pass
       end
     end
 
-    # @private
-    def after_end_hold_time
-      30
+    def finalize
+      ::Logging::Repository.reset
     end
 
     ##
@@ -197,6 +201,7 @@ module Adhearsion
 
     def reject(reason = :busy, headers = nil)
       write_and_await_response Punchblock::Command::Reject.new(:reason => reason, :headers => headers)
+      Adhearsion::Events.trigger_immediately :call_rejected, call: current_actor, reason: reason
     end
 
     def hangup(headers = nil)
@@ -342,6 +347,16 @@ module Adhearsion
       controllers.each(&:resume!)
     end
 
+    private
+
+    def offer
+      @offer
+    end
+
+    def client
+      @client
+    end
+
     # @private
     class CommandRegistry < ThreadSafeArray
       def terminate

data/lib/adhearsion/call_controller.rb

@@ -88,7 +88,7 @@ module Adhearsion
         catching_standard_errors do
           exec_with_callback completion_callback
         end
-      end.tap { |t| Adhearsion::Process.important_threads << t }
+      end
     end
 
     def exec_with_callback(completion_callback = nil)

data/lib/adhearsion/call_controller/dial.rb

@@ -32,6 +32,7 @@ module Adhearsion
       #   i.e. timeout after :for if no one answers the call
       #
       # @option options [CallController] :confirm the controller to execute on answered outbound calls to give an opportunity to screen the call. The calls will be joined if the outbound call is still active after this controller completes.
+      # @option options [Hash] :confirm_metadata Metadata to set on the confirmation controller before executing it.
       #
       # @example Make a call to the PSTN using my SIP provider for VoIP termination
       #   dial "SIP/19095551001@my.sip.voip.terminator.us"
@@ -73,6 +74,7 @@ module Adhearsion
           @options[:timeout] ||= _for if _for
 
           @confirmation_controller = @options.delete :confirm
+          @confirmation_metadata = @options.delete :confirm_metadata
         end
 
         def run
@@ -112,7 +114,7 @@ module Adhearsion
 
               if @confirmation_controller
                 status.unconfirmed!
-                new_call.execute_controller @confirmation_controller.new(new_call), lambda { |call| call.signal :confirmed }
+                new_call.execute_controller @confirmation_controller.new(new_call, @confirmation_metadata), lambda { |call| call.signal :confirmed }
                 new_call.wait :confirmed
               end
 

data/lib/adhearsion/call_controller/input.rb

@@ -79,7 +79,7 @@ module Adhearsion
       # invalid input, retries and timeouts, and final failures.
       #
       # @example A complete example of the method is as follows:
-      #   ask "Welcome, ", "/opt/sounds/menu-prompt.mp3", :tries => 2, :timeout => 10 do
+      #   menu "Welcome, ", "/opt/sounds/menu-prompt.mp3", :tries => 2, :timeout => 10 do
       #     match 1, OperatorController
       #
       #     match 10..19 do
@@ -114,7 +114,7 @@ module Adhearsion
       #
       # #validator runs its block on each digit being collected. If it returns true, the collection is terminated.
       #
-      # Execution of the current context resumes after #ask finishes. If you wish to jump to an entirely different controller, use #pass.
+      # Execution of the current context resumes after #menu finishes. If you wish to jump to an entirely different controller, use #pass.
       # Menu will return :failed if failure was reached, or :done if a match was executed.
       #
       # @param [Object] args A list of outputs to play, as accepted by #play
@@ -215,8 +215,8 @@ module Adhearsion
           }
 
         reason = input_component.complete_event.reason
-        result = reason.respond_to?(:interpretation) ? reason.interpretation : nil
-        parse_single_dtmf result
+        result = reason.respond_to?(:utterance) ? reason.utterance : nil
+        parse_dtmf result
       end
 
       # @private

data/lib/adhearsion/call_controller/menu_dsl.rb

@@ -13,6 +13,7 @@ module Adhearsion
       autoload :FixnumMatchCalculator
       autoload :RangeMatchCalculator
       autoload :StringMatchCalculator
+      autoload :ArrayMatchCalculator
       autoload :MenuBuilder
       autoload :Menu
     end

data/lib/adhearsion/call_controller/menu_dsl/array_match_calculator.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Adhearsion
+  class CallController
+    module MenuDSL
+      class ArrayMatchCalculator < MatchCalculator
+        def match(query)
+          args = { :query => query, :exact_matches => [], :potential_matches => [] }
+
+          pattern.compact.each do |pat|
+            pattern_string  = pat.to_s
+            query_string    = query.to_s
+
+            if pattern_string == query_string
+              args[:exact_matches] << pat
+            elsif pattern_string.starts_with? query_string
+              args[:potential_matches] << pat
+            end
+          end
+
+          new_calculated_match args
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/call_controller/menu_dsl/fixnum_match_calculator.rb

@@ -3,20 +3,8 @@
 module Adhearsion
   class CallController
     module MenuDSL
-      class FixnumMatchCalculator < MatchCalculator
-
-        def match(query)
-          numeric_query = coerce_to_numeric query
-          exact_match, potential_match = nil
-          if pattern == numeric_query
-            exact_match = pattern
-          elsif pattern.to_s.starts_with? query.to_s
-            potential_match = pattern
-          end
-          new_calculated_match :query => query, :exact_matches => exact_match, :potential_matches => potential_match
-        end
-
-      end # class FixnumMatchCalculator
+      class FixnumMatchCalculator < StringMatchCalculator
+      end
     end
   end
 end

data/lib/adhearsion/call_controller/menu_dsl/string_match_calculator.rb

@@ -3,23 +3,23 @@
 module Adhearsion
   class CallController
     module MenuDSL
-
       class StringMatchCalculator < MatchCalculator
 
         def match(query)
           args = { :query => query, :exact_matches => nil, :potential_matches => nil }
 
-          if pattern == query.to_s
+          pattern_string  = pattern.to_s
+          query_string    = query.to_s
+
+          if pattern_string == query_string
             args[:exact_matches] = [pattern]
-          elsif pattern.starts_with? query.to_s
+          elsif pattern_string.starts_with? query_string
             args[:potential_matches] = [pattern]
           end
 
           new_calculated_match args
         end
-
-      end # class StringMatchCalculator
-
+      end
     end
   end
 end

data/lib/adhearsion/call_controller/output.rb

@@ -21,7 +21,7 @@ module Adhearsion
       # @raises [PlaybackError] if the given argument could not be played
       #
       def say(text, options = {})
-        player.play_ssml(text, options) || player.output(Formatter.ssml_for_text(text.to_s), options)
+        player.play_ssml(text, options) || player.output(output_formatter.ssml_for_text(text.to_s), options)
       end
       alias :speak :say
 
@@ -34,7 +34,7 @@ module Adhearsion
       # @raises [PlaybackError] if the given argument could not be played
       #
       def say!(text, options = {})
-        async_player.play_ssml(text, options) || async_player.output(Formatter.ssml_for_text(text.to_s), options)
+        async_player.play_ssml(text, options) || async_player.output(output_formatter.ssml_for_text(text.to_s), options)
       end
       alias :speak! :say!
 
@@ -61,7 +61,7 @@ module Adhearsion
       # @raises [PlaybackError] if (one of) the given argument(s) could not be played
       #
       def play(*arguments)
-        player.play_ssml Formatter.ssml_for_collection(arguments)
+        player.play_ssml output_formatter.ssml_for_collection(arguments)
         true
       end
 
@@ -89,7 +89,7 @@ module Adhearsion
       # @returns [Punchblock::Component::Output]
       #
       def play!(*arguments)
-        async_player.play_ssml Formatter.ssml_for_collection(arguments)
+        async_player.play_ssml output_formatter.ssml_for_collection(arguments)
       end
 
       #
@@ -104,7 +104,7 @@ module Adhearsion
       # @raises [PlaybackError] if (one of) the given argument(s) could not be played
       #
       def play_audio(file, options = nil)
-        player.play_ssml Formatter.ssml_for_audio(file, options)
+        player.play_ssml output_formatter.ssml_for_audio(file, options)
         true
       end
 
@@ -121,7 +121,7 @@ module Adhearsion
       # @returns [Punchblock::Component::Output]
       #
       def play_audio!(file, options = nil)
-        async_player.play_ssml Formatter.ssml_for_audio(file, options)
+        async_player.play_ssml output_formatter.ssml_for_audio(file, options)
       end
 
       #
@@ -141,7 +141,7 @@ module Adhearsion
       #
       def play_time(time, options = {})
         raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
-        player.play_ssml Formatter.ssml_for_time(time, options)
+        player.play_ssml output_formatter.ssml_for_time(time, options)
         true
       end
 
@@ -163,7 +163,7 @@ module Adhearsion
       #
       def play_time!(time, options = {})
         raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
-        async_player.play_ssml Formatter.ssml_for_time(time, options)
+        async_player.play_ssml output_formatter.ssml_for_time(time, options)
       end
 
       #
@@ -177,7 +177,7 @@ module Adhearsion
       #
       def play_numeric(number)
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
-        player.play_ssml Formatter.ssml_for_numeric(number)
+        player.play_ssml output_formatter.ssml_for_numeric(number)
         true
       end
 
@@ -193,7 +193,7 @@ module Adhearsion
       #
       def play_numeric!(number)
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
-        async_player.play_ssml Formatter.ssml_for_numeric(number)
+        async_player.play_ssml output_formatter.ssml_for_numeric(number)
       end
 
       #
@@ -236,7 +236,7 @@ module Adhearsion
             :value => grammar_accept(digits)
           }
 
-        player.output Formatter.ssml_for(argument) do |output_component|
+        player.output output_formatter.ssml_for(argument) do |output_component|
           stopper.register_event_handler Punchblock::Event::Complete do |event|
             output_component.stop! unless output_component.complete?
           end
@@ -245,9 +245,8 @@ module Adhearsion
 
         stopper.stop! if stopper.executing?
         reason = stopper.complete_event.reason
-        result = reason.interpretation if reason.respond_to? :interpretation
-        return parse_single_dtmf result unless result.nil?
-        result
+        result = reason.respond_to?(:utterance) ? reason.utterance : nil
+        parse_dtmf result
       end
 
       # @private
@@ -259,6 +258,13 @@ module Adhearsion
       def async_player
         @async_player ||= AsyncPlayer.new(self)
       end
+
+      #
+      # @return [Formatter] an output formatter for the preparation of SSML documents for submission to the engine
+      #
+      def output_formatter
+        Formatter.new
+      end
     end # Output
   end # CallController
 end # Adhearsion