adhearsion 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 61315b79e7d1320dea8413e2b5c26f9b1c953551
-  data.tar.gz: 2935a1722a541274a596fb2a35d5e3e5b7d05a23
+  metadata.gz: 9155fcf025c8ed90e014e5262b70387e46e31937
+  data.tar.gz: dcb5d1f0104f854e3b487f34cf199e3134d5d38d
 SHA512:
-  metadata.gz: d4210b4cae9891cc1f5f2e6ecca89e7e4b0f371287d0726f3a876b99910e35b887758d1f5ab6e59a2afca1c58c9e270cb4377c531c55d4d79e1c9454773319af
-  data.tar.gz: 8302e6d6500220edd4892b557f79b1c5fcdcaa1d68771a3bb6db2f7094f36912c349c9f297adaeef8b4ba572aa0dadddf2fc2121c09e1dd592d20bff843d625d
+  metadata.gz: 00076ee1fdd8a0d208dc1895dbb74f33f5c0adc23a2348248c0c8938378715d2bd40b7f8bfe64e42b05d2cd3e9594a0159d00af5b64f8e3285e37d2336249011
+  data.tar.gz: 7b1e9f478d6860f662e485a1c5add9e69ed0d1c2cf0f1d038ed661c47e2fd791224855bd452d89c79c09b18ebec16988df30af6650fb03870b77cde1f190ab14

data/.travis.yml

@@ -1,14 +1,14 @@
 language: ruby
 rvm:
-  - 1.9.2
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-19mode
-  - rbx-19mode
+  - rbx-2.1.1
   - ruby-head
 matrix:
   allow_failures:
-    - rvm: rbx-19mode
+    - rvm: rbx-2.1.1
     - rvm: ruby-head
 env: ARUBA_TIMEOUT=120 RAILS_ENV=development AHN_ENV=development
 notifications:

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # [develop](https://github.com/adhearsion/adhearsion)
 
+# [2.5.0](https://github.com/adhearsion/adhearsion/compare/v2.4.0...v2.5.0) - [2014-02-03](https://rubygems.org/gems/adhearsion/versions/2.5.0)
+  * **Change: Ruby 1.9.2 is no longer supported**
+  * Change: Set default call post-hangup lifetime to one second for better out of the box performance.
+  * Feature: Allow stopping all components executed by a controller when passing from it (`#hard_pass`) or at will (`#stop_all_components`)
+  * Feature: Generated plugins include a .gitignore file
+  * Feature: Detect something like "1234#" as characters instead of text
+  * Feature: Add `--empty` switch to app generator for power users. Generates an app with less fluff.
+  * Feature: Default generated applications with config appropriate for [Telephony Dev Box](http://github.com/mojolingo/Telephony-Dev-Box)
+  * Feature: Allow preventing automatic call hangup after controller completion. Set `Call#auto_hangup = false` prior to controller termination.
+  * Feature: Allow specifying a pre-join callback to #dial
+  * Feature: Allow specifying ringback to `#dial` as either a list or a proc
+  * Feature: Allow passing `:join_options` parameter to `#dial` to specify the kind of join to perform.
+  * Feature: Allow passing `:join_target` parameter to `#dial` to specify who to join to (eg a mixer).
+  * Feature: Generated apps now encourage storing most app code in `app/`, which is in the load path. Nothing in this directory is auto-loaded, but can be easily required without messy relative paths.
+  * Feature: Routes and event handlers are now split out of main config file for readability. They may be retained in the main config file for existing apps.
+  * Feature: Add `Call#end_code`, which specifies the platform code for the call end event.
+  * Feature: Allow XMPP messages to be sent via Punchblock
+  * Bugfix: Don't block shutdown waiting for the console to terminate
+  * Bugfix: Ensure that splitting a dial rejoined to an alternative target (eg a mixer) or merged with another dial can still be split properly.
+  * Bugfix: Ensure that hungup calls don't prevent dial splits/merges.
+  * Bugfix: Ensure that merged dials which are split and rejoined all get rejoined to the mixer.
+  * Bugfix: Ensure that `Call#peers` are correctly maintained - this was broken by Rayo moving to full call URIs in joined/unjoined events
+  * Bugfix: Ensure that failure to dial a call kills the actor
+  * Bugfix: Adhearsion call actors should do recursion detection on #inspect
+  * Bugfix: Fix controller block context on JRuby
+  * Bugfix: Require only Bundler groups appropriate to application environment
+  * Bugfix: Call event handlers now cannot crash the call, and no longer stop on return value
+  * Bugfix: Call controllers are gracefully terminated when a command is attempted against a dead call
+
 # [2.4.0](https://github.com/adhearsion/adhearsion/compare/v2.3.5...v2.4.0) - [2013-08-29](https://rubygems.org/gems/adhearsion/versions/2.4.0)
   * Deprecation: Ruby 1.9.2 support is deprecated and will be dropped in a future version of Adhearsion
   * Deprecation: Some media options from Punchblock config are now overriden by other core config, and will eventually be removed.

data/Gemfile

@@ -1,5 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-gem 'activesupport', '~> 3.0' if RUBY_VERSION == "1.9.2"

data/Guardfile

@@ -1,7 +1,7 @@
 ENV['SKIP_RCOV'] = 'true'
 
 group 'rspec' do
-  guard 'rspec', :cli => '--format documentation' do
+  guard 'rspec', cmd: 'bundle exec rspec' do
     watch(%r{^spec/.+_spec\.rb$})
     watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
     watch('spec/spec_helper.rb')  { "spec/" }
@@ -9,7 +9,7 @@ group 'rspec' do
 end
 
 group 'cucumber' do
-  guard 'cucumber', :cli => '--profile guard' do
+  guard 'cucumber', :cli => '--profile guard', all_on_start: false do
     watch(%r{^features/.+\.feature$})
     watch(%r{^features/support/.+$})                      { 'features' }
     watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }

data/README.markdown

@@ -23,18 +23,15 @@ Adhearsion rests above a lower-level telephony platform, for example [Asterisk](
 
 ## Requirements
 
-* Ruby 1.9.2+ or JRuby 1.7.0+
+* Ruby 1.9.3+ or JRuby 1.7.0+
+* [ruby_speech dependencies](https://github.com/benlangfeld/ruby_speech#dependencies)
 * A VoIP platform:
   * Asterisk 1.8+
   * FreeSWITCH
   * A Rayo server (Prism 11+ with rayo-server, or FreeSWITCH with mod_rayo)
 * An interest in building cool new things
 
-\* Support for Ruby 1.9.2 is deprecated, and requires locking your application to ActiveSupport 3.x as follows:
-
-```ruby
-gem 'active_support', '~> 3.0'
-```
+**Ruby 1.9.2 is no longer supported by Adhearsion or the Ruby core team. You should upgrade to Ruby 1.9.3 or Ruby 2 as a matter of urgency in order to continue receiving security fixes.**
 
 ## Install
 

data/Rakefile

@@ -29,7 +29,7 @@ end
 begin
   require 'yard'
   YARD::Rake::YardocTask.new do |t|
-    t.files = ['lib/**/*.rb'] + %w[README.markdown TODO.markdown LICENSE]
+    t.files = ['lib/**/*.rb']
   end
 rescue LoadError
   STDERR.puts "\nCould not require() YARD! Install with 'gem install yard' to get the 'yardoc' task\n\n"

data/adhearsion.gemspec

@@ -12,6 +12,10 @@ Gem::Specification.new do |s|
   s.summary     = "Adhearsion, open-source telephony development framework"
   s.description = "Adhearsion is an open-source telephony development framework"
 
+  s.license = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.3'
+
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
@@ -25,11 +29,11 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'deep_merge'
   s.add_runtime_dependency 'ffi', ["~> 1.0"]
   s.add_runtime_dependency 'girl_friday'
-  s.add_runtime_dependency 'has-guarded-handlers', ["~> 1.5"]
+  s.add_runtime_dependency 'has-guarded-handlers', ["~> 1.6"]
   s.add_runtime_dependency 'jruby-openssl' if RUBY_PLATFORM == 'java'
   s.add_runtime_dependency 'logging', ["~> 1.8"]
   s.add_runtime_dependency 'pry'
-  s.add_runtime_dependency 'punchblock', ["~> 2.0"]
+  s.add_runtime_dependency 'punchblock', ["~> 2.3"]
   s.add_runtime_dependency 'rake'
   s.add_runtime_dependency 'ruby_speech', ["~> 2.0"]
   s.add_runtime_dependency 'thor', "~> 0.18.0"
@@ -43,6 +47,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'simplecov'
   s.add_development_dependency 'simplecov-rcov'
   s.add_development_dependency 'yard'
+  s.add_development_dependency 'guard-yard'
   s.add_development_dependency 'coveralls'
   s.add_development_dependency 'timecop'
 end

data/features/cli_create.feature

@@ -3,18 +3,96 @@ Feature: Adhearsion Ahn CLI (Create)
   I want the ahn command to allow creating an app
   So that I can write an Adhearsion app
 
-  Scenario: Command create with correct arguments
+  Scenario: Generate application with valid layout
     When I run `ahn create path/somewhere`
     And I cd to "path/somewhere"
-    Then the following files should exist:
-      | Gemfile               |
-      | README.md             |
-      | Rakefile              |
+    Then the following directories should exist:
+      | app/call_controllers  |
+      | lib                   |
+      | config                |
+      | script                |
+      | spec                  |
+      | spec/call_controllers |
+      | spec/support          |
+
+    And the following files should exist:
+      | .gitignore                                |
+      | .rspec                                    |
+      | app/call_controllers/simon_game.rb        |
+      | config/adhearsion.rb                      |
+      | config/environment.rb                     |
+      | config/events.rb                          |
+      | config/routes.rb                          |
+      | Gemfile                                   |
+      | script/ahn                                |
+      | spec/spec_helper.rb                       |
+      | spec/call_controllers/simon_game_spec.rb  |
+      | README.md                                 |
+      | Rakefile                                  |
+      | Procfile                                  |
+
+    And the file "config/adhearsion.rb" should contain each of these content parts:
+    """
+    Adhearsion.config
+    logging.level
+    config.punchblock
+    """
+    And the file "config/events.rb" should contain each of these content parts:
+    """
+    Adhearsion::Events.draw do
+    """
+    And the file "config/routes.rb" should contain each of these content parts:
+    """
+    Adhearsion.router
+    """
+    And the file "README.md" should contain each of these content parts:
+    """
+    Start your new app with
+    AGI(agi
+    """
+    And the file "Rakefile" should contain "adhearsion/tasks"
+    And the file "Gemfile" should contain each of these content parts:
+    """
+    source 'https://rubygems.org
+    gem 'adhearsion-asr'
+    """
+    And the file "app/call_controllers/simon_game.rb" should contain "class SimonGame"
+    And the file "script/ahn" should contain "require 'adhearsion'"
+
+  Scenario: Generate application --empty
+    When I run `ahn create path/somewhere --empty`
+    And I cd to "path/somewhere"
+    Then the following directories should exist:
+      | app/call_controllers  |
+      | lib                   |
+      | config                |
+      | script                |
+      | spec                  |
+      | spec/call_controllers |
+      | spec/support          |
+
+    And the following files should exist:
+      | .gitignore            |
+      | .rspec                |
       | config/adhearsion.rb  |
       | config/environment.rb |
+      | config/events.rb      |
+      | config/routes.rb      |
+      | Gemfile               |
+      | script/ahn            |
       | spec/spec_helper.rb   |
-    And the file "config/adhearsion.rb" should contain "Adhearsion.router"
-    Then the exit status should be 0
+      | README.md             |
+      | Rakefile              |
+      | Procfile              |
+
+    And the following files should not exist:
+      | app/call_controllers/simon_game.rb        |
+      | spec/call_controllers/simon_game_spec.rb  |
+
+    And the file "config/events.rb" should not contain each of these content parts:
+    """
+    # Register global handlers for events
+    """
 
   Scenario: Running create with no arguments
     When I run `ahn create`

data/features/plugin_generator.feature

@@ -11,6 +11,7 @@ Feature: Adhearsion plugin generator
     | test_plugin/lib/test_plugin |
     | test_plugin/spec            |
     And the following files should exist:
+    | test_plugin/.gitignore                                  |
     | test_plugin/test_plugin.gemspec                         |
     | test_plugin/Rakefile                                    |
     | test_plugin/README.md                                   |
@@ -21,6 +22,7 @@ Feature: Adhearsion plugin generator
     | test_plugin/lib/test_plugin/controller_methods.rb       |
     | test_plugin/spec/spec_helper.rb                         |
     | test_plugin/spec/test_plugin/controller_methods_spec.rb |
+    And the file "test_plugin/.gitignore" should contain "Gemfile.lock"
     And the file "test_plugin/test_plugin.gemspec" should contain "test_plugin/version"
     And the file "test_plugin/README.md" should contain "TestPlugin"
     And the file "test_plugin/lib/test_plugin.rb" should contain each of these content parts:
@@ -62,6 +64,7 @@ Feature: Adhearsion plugin generator
     | test_plugin/lib/test_plugin |
     | test_plugin/spec            |
     And the following files should exist:
+    | test_plugin/.gitignore                                  |
     | test_plugin/test_plugin.gemspec                         |
     | test_plugin/Rakefile                                    |
     | test_plugin/README.md                                   |
@@ -72,6 +75,7 @@ Feature: Adhearsion plugin generator
     | test_plugin/lib/test_plugin/controller_methods.rb       |
     | test_plugin/spec/spec_helper.rb                         |
     | test_plugin/spec/test_plugin/controller_methods_spec.rb |
+    And the file "test_plugin/.gitignore" should contain "Gemfile.lock"
     And the file "test_plugin/test_plugin.gemspec" should contain "test_plugin/version"
     And the file "test_plugin/README.md" should contain "TestPlugin"
     And the file "test_plugin/lib/test_plugin.rb" should contain each of these content parts:

data/features/step_definitions/app_generator_steps.rb

@@ -1,8 +1,15 @@
 # encoding: utf-8
 
 Then /^the file "([^"]*)" should contain each of these content parts:$/ do |file, content_parts|
-  parts = content_parts.split
+  parts = content_parts.split("\n")
   parts.each do |p|
     steps %Q{Then the file "#{file}" should contain "#{p}"}
   end
 end
+
+Then /^the file "([^"]*)" should not contain each of these content parts:$/ do |file, content_parts|
+  parts = content_parts.split("\n")
+  parts.each do |p|
+    steps %Q{Then the file "#{file}" should not contain "#{p}"}
+  end
+end

data/lib/adhearsion.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-abort "ERROR: You are running Adhearsion on an unsupported version of Ruby (Ruby #{RUBY_VERSION} #{RUBY_RELEASE_DATE})! Please upgrade to at least Ruby v1.9.2, JRuby 1.7.0 or Rubinius 2.0." if RUBY_VERSION < "1.9.2"
+abort "ERROR: You are running Adhearsion on an unsupported version of Ruby (Ruby #{RUBY_VERSION} #{RUBY_RELEASE_DATE})! Please upgrade to at least Ruby v1.9.3, JRuby 1.7.0 or Rubinius 2.0." if RUBY_VERSION < "1.9.3"
 
 %w{
   active_support/all
@@ -71,8 +71,7 @@ module Adhearsion
 
     def initialize_config
       _config = Configuration.new
-      env = ENV['AHN_ENV'] || ENV['RAILS_ENV']
-      env = env.to_sym if env.respond_to? :to_sym
+      env = environment.to_sym if environment.respond_to? :to_sym
       unless _config.valid_environment? env
         puts  "You tried to initialize with an invalid environment name #{env}. Valid values are #{_config.valid_environments}."
         env = nil
@@ -81,6 +80,10 @@ module Adhearsion
       _config
     end
 
+    def environment
+      ENV['AHN_ENV'] || ENV['RAILS_ENV'] || :development
+    end
+
     def environments
       config.valid_environments
     end

data/lib/adhearsion/call.rb

@@ -17,7 +17,7 @@ module Adhearsion
     include Celluloid
     include HasGuardedHandlers
 
-    execute_block_on_receiver :register_handler, :register_tmp_handler, :register_handler_with_priority, :register_event_handler, :on_joined, :on_unjoined, :on_end, :execute_controller
+    execute_block_on_receiver :register_handler, :register_tmp_handler, :register_handler_with_priority, :register_event_handler, :on_joined, :on_unjoined, :on_end, :execute_controller, *execute_block_on_receiver
     finalizer :finalize
 
     def self.new(*args, &block)
@@ -25,7 +25,7 @@ module Adhearsion
         def proxy.method_missing(*args)
           super
         rescue Celluloid::DeadActorError
-          raise ExpiredError, "This call is expired and is no longer accessible"
+          raise ExpiredError, "This call is expired and is no longer accessible. See http://adhearsion.com/docs/calls for further details."
         end
       end
     end
@@ -33,6 +33,9 @@ module Adhearsion
     # @return [Symbol] the reason for the call ending
     attr_reader :end_reason
 
+    # @return [String] the reason code for the call ending
+    attr_reader :end_code
+
     # @return [Array<Adhearsion::CallController>] the set of call controllers executing on the call
     attr_reader :controllers
 
@@ -45,8 +48,25 @@ module Adhearsion
     # @return [Time] the time at which the call began. For inbound calls this is the time at which the call was offered to Adhearsion. For outbound calls it is the time at which the remote party answered.
     attr_reader :end_time
 
+    # @return [true, false] wether or not the call should be automatically hung up after executing its controller
+    attr_accessor :auto_hangup
+
     delegate :[], :[]=, :to => :variables
-    delegate :to, :from, :to => :offer, :allow_nil => true
+
+    # @return [String] the value of the To header from the signaling protocol
+    delegate :to, to: :offer, allow_nil: true
+
+    # @return [String] the value of the From header from the signaling protocol
+    delegate :from, to: :offer, allow_nil: true
+
+    def self.uri(transport, id, domain)
+      return nil unless id
+      s = ""
+      s << transport << ":" if transport
+      s << id
+      s << "@" << domain if domain
+      s
+    end
 
     def initialize(offer = nil)
       register_initial_handlers
@@ -57,9 +77,11 @@ module Adhearsion
       @variables    = HashWithIndifferentAccess.new
       @controllers  = []
       @end_reason   = nil
+      @end_code     = nil
       @end_blocker  = Celluloid::Condition.new
       @peers        = {}
       @duration     = nil
+      @auto_hangup  = true
 
       self << offer if offer
     end
@@ -83,12 +105,7 @@ module Adhearsion
     # @return [String, nil] The uri at which the call resides
     #
     def uri
-      return nil unless id
-      s = ""
-      s << transport << ":" if transport
-      s << id
-      s << "@" << domain if domain
-      s
+      self.class.uri(transport, id, domain)
     end
 
     #
@@ -146,13 +163,26 @@ module Adhearsion
       end
     end
 
+    #
+    # Register a handler for events on this call. Note that Adhearsion::Call implements the has-guarded-handlers API, and all of its methods are available. Specifically, all Adhearsion events are available on the `:event` channel.
+    #
+    # @param [guards] guards take a look at the guards documentation
+    #
+    # @yield [Object] trigger_object the incoming event
+    #
+    # @return [String] handler ID for later manipulation
+    #
+    # @see http://adhearsion.github.io/has-guarded-handlers for more details
+    #
     def register_event_handler(*guards, &block)
       register_handler :event, *guards, &block
     end
 
     def deliver_message(message)
       logger.debug "Receiving message: #{message.inspect}"
-      catching_standard_errors { trigger_handler :event, message }
+      catching_standard_errors do
+        trigger_handler :event, message, broadcast: true, exception_callback: ->(e) { Adhearsion::Events.trigger :exception, [e, logger] }
+      end
     end
     alias << deliver_message
 
@@ -166,12 +196,10 @@ module Adhearsion
         @offer  = offer
         @client = offer.client
         @start_time = Time.now
-        throw :pass
       end
 
       register_event_handler Punchblock::HasHeaders do |event|
         merge_headers event.headers
-        throw :pass
       end
 
       on_joined do |event|
@@ -183,7 +211,8 @@ module Adhearsion
           type = :mixer
         end
         logger.info "Joined to #{type} #{target}"
-        @peers[target] = Adhearsion.active_calls[target]
+        call = Adhearsion.active_calls.with_uri(target)
+        @peers[target] = call
         signal :joined, target
       end
 
@@ -206,10 +235,10 @@ module Adhearsion
         @duration = @end_time - @start_time if @start_time
         clear_from_active_calls
         @end_reason = event.reason
+        @end_code = event.platform_code
         @end_blocker.broadcast event.reason
         @commands.terminate
         after(Adhearsion.config.platform.after_hangup_lifetime) { terminate }
-        throw :pass
       end
     end
 
@@ -234,7 +263,6 @@ module Adhearsion
     def on_joined(target = nil, &block)
       register_event_handler Punchblock::Event::Joined, *guards_for_target(target) do |event|
         block.call event
-        throw :pass
       end
     end
 
@@ -246,22 +274,16 @@ module Adhearsion
     # @option target [String] mixer_name The mixer name to guard on
     #
     def on_unjoined(target = nil, &block)
-      register_event_handler Punchblock::Event::Unjoined, *guards_for_target(target) do |event|
-        block.call event
-        throw :pass
-      end
+      register_event_handler Punchblock::Event::Unjoined, *guards_for_target(target), &block
     end
 
     # @private
     def guards_for_target(target)
-      target ? [join_options_with_target(target)] : []
+      target ? [target_from_join_options(join_options_with_target(target))] : []
     end
 
     def on_end(&block)
-      register_event_handler Punchblock::Event::End do |event|
-        block.call event
-        throw :pass
-      end
+      register_event_handler Punchblock::Event::End, &block
     end
 
     #
@@ -304,10 +326,29 @@ module Adhearsion
     # @option target [String] mixer_name The mixer to join to
     # @param [Hash, Optional] options further options to be joined with
     #
+    # @return [Hash] where :command is the issued command, :joined_waiter is a #wait responder which is triggered when the join is complete, and :unjoined_waiter is a #wait responder which is triggered when the entities are unjoined
+    #
     def join(target, options = {})
       logger.info "Joining to #{target}"
+
+      joined_condition = CountDownLatch.new(1)
+      on_joined target do
+        joined_condition.countdown!
+      end
+
+      unjoined_condition = CountDownLatch.new(1)
+      on_unjoined target do
+        unjoined_condition.countdown!
+      end
+
+      on_end do
+        joined_condition.countdown!
+        unjoined_condition.countdown!
+      end
+
       command = Punchblock::Command::Join.new options.merge(join_options_with_target(target))
       write_and_await_response command
+      {command: command, joined_condition: joined_condition, unjoined_condition: unjoined_condition}
     end
 
     ##
@@ -329,7 +370,7 @@ module Adhearsion
       when Call
         { :call_uri => target.uri }
       when String
-        { :call_uri => "#{transport}:#{target}@#{domain}" }
+        { :call_uri => self.class.uri(transport, target, domain) }
       when Hash
         abort ArgumentError.new "You cannot specify both a call URI and mixer name" if target.has_key?(:call_uri) && target.has_key?(:mixer_name)
         target
@@ -338,6 +379,13 @@ module Adhearsion
       end
     end
 
+    # @private
+    def target_from_join_options(options)
+      call_uri = options[:call_uri]
+      return {call_uri: call_uri} if call_uri
+      {mixer_name: options[:mixer_name]}
+    end
+
     def wait_for_joined(expected_target)
       target = nil
       until target == expected_target do
@@ -361,25 +409,27 @@ module Adhearsion
     end
 
     # @private
-    def write_and_await_response(command, timeout = 60)
+    def write_and_await_response(command, timeout = 60, fatal = false)
       @commands << command
       write_command command
 
+      error_handler = fatal ? ->(error) { raise error } : ->(error) { abort error }
+
       response = defer { command.response timeout }
       case response
       when Punchblock::ProtocolError
         if response.name == :item_not_found
-          abort Hangup.new(@end_reason)
+          error_handler[Hangup.new(@end_reason)]
         else
-          abort response
+          error_handler[response]
         end
       when Exception
-        abort response
+        error_handler[response]
       end
 
       command
     rescue Timeout::Error
-      abort CommandTimeout.new(command.to_s)
+      error_handler[CommandTimeout.new(command.to_s)]
     ensure
       @commands.delete command
     end
@@ -392,18 +442,39 @@ module Adhearsion
       client.execute_command command, call_id: id, domain: domain, async: true
     end
 
+    ##
+    # Sends a message to the caller
+    #
+    # @param [String] body The message text.
+    # @param [Hash, Optional] options The message options.
+    # @option options [String] subject The message subject.
+    #
+    def send_message(body, options = {})
+      logger.debug "Sending message: #{body}"
+      client.send_message id, domain, body, options
+    end
+
     # @private
     def logger_id
       "#{self.class}: #{id}@#{domain}"
     end
     # @private
     def inspect
+      return "..." if Celluloid.detect_recursion
       attrs = [:offer, :end_reason, :commands, :variables, :controllers, :to, :from].map do |attr|
         "#{attr}=#{send(attr).inspect}"
       end
       "#<#{self.class}:#{id}@#{domain} #{attrs.join ', '}>"
     end
 
+    #
+    # Execute a call controller asynchronously against this call.
+    #
+    # @param [Adhearsion::CallController] controller an instance of a controller initialized for this call
+    # @param [Proc] a callback to be executed when the controller finishes execution
+    #
+    # @yield execute the current block as the body of a controller by specifying no controller instance
+    #
     def execute_controller(controller = nil, completion_callback = nil, &block)
       raise ArgumentError, "Cannot supply a controller and a block at the same time" if controller && block_given?
       controller ||= CallController.new current_actor, &block