adhearsion 2.4.0.beta1 → 2.4.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0e1b64f1b1643fc319f4203fbf8e6cf2452c444d
-  data.tar.gz: f533f739a9536421599852a4f049407b287b30b1
+  metadata.gz: 954ba804ad541b402e9b92a8bc467cfe6d37bd5d
+  data.tar.gz: 220bcee6bb1362c837b7a1f652135aaf279d7ae9
 SHA512:
-  metadata.gz: bb6cad9f60e451a309f4e98b5cdb61e19835032e44f053cba58598b9dc4b188abc1d089802d9c596566c3ebdc107e2fec1d61e5a4e26c5f0bfca24bb6f6e5ed8
-  data.tar.gz: 803b943cbebf981da00a580e46151dad0fc86bb188ccb89171e759461cbb03f889355c159e9b9ad67f77a2d5bb149717e85ae10ff96428128bdbff43aff528f5
+  metadata.gz: c21bfd97fb6181317bc98cf881b893b84d69ca2028fd20da89f1acf192390305a48b89677cacc40181f07bcdd0580c20de961abf446d7dd273d73b7fb6b20b59
+  data.tar.gz: 07321554930f529a73ea01aa6c8f79ebb45782272a8a023e3b6610957297cd202fbe333694071357ef72aabb25be0e8c8cecd7531b34c14169ffc5c23bc81d44

data/CHANGELOG.md

@@ -1,18 +1,28 @@
 # [develop](https://github.com/adhearsion/adhearsion)
 
-# [2.4.0.beta1](https://github.com/adhearsion/adhearsion/compare/v2.3.5...v2.4.0.beta1) - [2013-08-20](https://rubygems.org/gems/adhearsion/versions/2.4.0.beta1)
+# [2.4.0.beta2](https://github.com/adhearsion/adhearsion/compare/v2.3.5...v2.4.0.beta2) - [2013-08-23](https://rubygems.org/gems/adhearsion/versions/2.4.0.beta2)
+  * Deprecation: Ruby 1.9.2 support is deprecated and will be dropped in a future version of Adhearsion
+  * Feature: Update to Punchblock 2.0 for JRuby compatibility, better performance and Rayo spec compliance
   * Feature: Add Call#wait_for_end, which blocks until the call ends and returns its end reason
   * Feature: Add joined call attribute to dial status
   * Feature: Track call start/end time and duration
   * Feature: Add per-call join duration and disposition to DialStatus
-  * Feature: Add `CallController#dial_and_confirm` which allows parallel confirmation of outbound calls
+  * Feature: Add `CallController#dial_and_confirm` which allows parallel confirmation of outbound calls and apologies to losing parties
+  * Feature: Add `CallController::Dial::Dial#split`, `#rejoin`, `#merge` and `#skip_cleanup` to support conferencing and transfer use cases
   * Feature: Add `#originate` method to console as alias for `Adhearsion::OutboundCall.originate`
   * Feature: Allow the console to be disabled using `--no-console`
   * Feature: Add CLI options to generate hooks for a plugin to register on [ahnhub.com](http://www.ahnhub.com)
   * Bugfix: Removed unnecessary Mocha reference from generated plugin
-  * Bugfix: Call loggers should be deleted after a call finishes
+  * Bugfix: Call loggers are deleted after a call finishes, fixing a memory leak
   * Bugfix: A menu definition's block context is now available
   * Bugfix: Ensure call's command registry is not leaked outside the actor
+  * Bugfix: An application's lib/ directory is now in the load path so dependencies may be reasolved more simply. You may now require 'foo.rb' instead of "#{Adhearsion.root}/lib/foo.rb"
+  * Bugfix: Resolve hostname to some local name when experiencing network issues
+  * Bugfix: Ensure smooth shutdown of console and XMPP connections
+  * Bugfix: Warn when booting Adhearsion with an invalid environment name
+  * Bugfix: `CallController#reject` now terminates a call controller in the same way as `#hangup`
+  * Bugfix: `Call` actors can now process other queries while waiting for responses to commands from a VoIP engine
+  * Bugfix: Allow the CLI to function on JRuby
 
 # [2.3.5](https://github.com/adhearsion/adhearsion/compare/v2.3.4...v2.3.5) - [2013-06-06](https://rubygems.org/gems/adhearsion/versions/2.3.5)
   * Bugfix: Fix race conditions in barging in before output start is acknowledged

data/README.markdown

@@ -27,7 +27,7 @@ Adhearsion rests above a lower-level telephony platform, for example [Asterisk](
 * A VoIP platform:
   * Asterisk 1.8+
   * FreeSWITCH
-  * Prism 11+ with rayo-server
+  * 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:

data/lib/adhearsion/call.rb

@@ -30,7 +30,20 @@ module Adhearsion
       end
     end
 
-    attr_reader :end_reason, :controllers, :variables, :start_time, :end_time
+    # @return [Symbol] the reason for the call ending
+    attr_reader :end_reason
+
+    # @return [Array<Adhearsion::CallController>] the set of call controllers executing on the call
+    attr_reader :controllers
+
+    # @return [Hash<String => String>] a collection of SIP headers set during the call
+    attr_reader :variables
+
+    # @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 :start_time
+
+    # @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
 
     delegate :[], :[]=, :to => :variables
     delegate :to, :from, :to => :offer, :allow_nil => true
@@ -57,6 +70,7 @@ module Adhearsion
     def id
       offer.target_call_id if offer
     end
+    alias :to_s :id
 
     #
     # @return [String, nil] The domain on which the call resides
@@ -161,13 +175,27 @@ module Adhearsion
       end
 
       on_joined do |event|
-        target = event.call_uri || event.mixer_name
+        if event.call_uri
+          target = event.call_uri
+          type = :call
+        else
+          target = event.mixer_name
+          type = :mixer
+        end
+        logger.info "Joined to #{type} #{target}"
         @peers[target] = Adhearsion.active_calls[target]
         signal :joined, target
       end
 
       on_unjoined do |event|
-        target = event.call_uri || event.mixer_name
+        if event.call_uri
+          target = event.call_uri
+          type = :call
+        else
+          target = event.mixer_name
+          type = :mixer
+        end
+        logger.info "Unjoined from #{type} #{target}"
         @peers.delete target
         signal :unjoined, target
       end
@@ -277,6 +305,7 @@ module Adhearsion
     # @param [Hash, Optional] options further options to be joined with
     #
     def join(target, options = {})
+      logger.info "Joining to #{target}"
       command = Punchblock::Command::Join.new options.merge(join_options_with_target(target))
       write_and_await_response command
     end
@@ -289,6 +318,7 @@ module Adhearsion
     # @option target [String] mixer_name The mixer to unjoin from
     #
     def unjoin(target)
+      logger.info "Unjoining from #{target}"
       command = Punchblock::Command::Unjoin.new join_options_with_target(target)
       write_and_await_response command
     end
@@ -366,11 +396,6 @@ module Adhearsion
     def logger_id
       "#{self.class}: #{id}@#{domain}"
     end
-    # @private
-    def to_ary
-      [current_actor]
-    end
-
     # @private
     def inspect
       attrs = [:offer, :end_reason, :commands, :variables, :controllers, :to, :from].map do |attr|

data/lib/adhearsion/call_controller.rb

@@ -77,6 +77,15 @@ module Adhearsion
       @call, @metadata, @block = call, metadata || {}, block
     end
 
+    def method_missing(method_name, *args, &block)
+      if @block
+        block_context = eval "self", @block.binding
+        block_context.send method_name, *args, &block
+      else
+        super
+      end
+    end
+
     #
     # Execute the controller, allowing passing control to another controller
     #

data/lib/adhearsion/call_controller/dial.rb

@@ -76,33 +76,36 @@ module Adhearsion
           raise Call::Hangup unless call.alive? && call.active?
           @options, @call = options, call
           @targets = to.respond_to?(:has_key?) ? to : Array(to)
+          @call_targets = {}
           set_defaults
         end
 
-        def set_defaults
-          @status = DialStatus.new
-
-          @latch = CountDownLatch.new @targets.size
-
-          @options[:from] ||= @call.from
-
-          _for = @options.delete :for
-          @options[:timeout] ||= _for if _for
-
-          @confirmation_controller = @options.delete :confirm
-          @confirmation_metadata = @options.delete :confirm_metadata
+        def inspect
+          "#<#{self.class} to=#{@to.inspect} options=#{@options.inspect}>"
         end
 
+        # Prep outbound calls, link call lifecycles and place outbound calls
         def run
           track_originating_call
           prep_calls
           place_calls
         end
 
+        #
+        # Links the lifecycle of the originating call to the Dial operation such that the Dial is unblocked when the originating call ends
         def track_originating_call
-          @call.on_end { |_| @latch.countdown! until @latch.count == 0 }
+          @call.on_end do |_|
+            logger.info "Root call ended, unblocking everything..."
+            @waiters.each do |latch|
+              latch.countdown! until latch.count == 0
+            end
+          end
         end
 
+        #
+        # Prepares a set of OutboundCall actors to be dialed and links their lifecycles to the Dial operation
+        #
+        # @yield Each call to the passed block for further setup operations
         def prep_calls
           @calls = @targets.map do |target, specific_options|
             new_call = OutboundCall.new
@@ -122,9 +125,11 @@ module Adhearsion
               pre_confirmation_tasks new_call
 
               new_call.on_unjoined @call do |unjoined|
-                new_call["dial_countdown_#{@call.id}"] = true
                 join_status.ended
-                @latch.countdown!
+                unless @splitting
+                  new_call["dial_countdown_#{@call.id}"] = true
+                  @latch.countdown!
+                end
               end
 
               if @confirmation_controller
@@ -141,31 +146,107 @@ module Adhearsion
                 @call.answer
                 join_status.started
                 new_call.join @call
-                status.answer!(new_call)
+                status.answer!
               elsif status.result == :answer
                 join_status.lost_confirmation!
               end
             end
 
-            [new_call, target, specific_options]
+            @call_targets[new_call] = [target, specific_options]
+
+            yield new_call if block_given?
+
+            new_call
           end
 
           status.calls = @calls
         end
 
+        #
+        # Dials the set of outbound calls
         def place_calls
-          @calls.map! do |call, target, specific_options|
+          @calls.each do |call|
+            target, specific_options = @call_targets[call]
             local_options = @options.dup.deep_merge specific_options if specific_options
             call.dial target, (local_options || @options)
-            call
           end
         end
 
+        # Split calls party to the dial
+        # Marks the end time in the status of each join, but does not unblock #dial until one of the calls ends
+        # Optionally executes call controllers on calls once split, where 'current_dial' is available in controller metadata in order to perform further operations on the Dial, including rejoining and termination.
+        # @param [Hash] targets Target call controllers to execute on call legs once split
+        # @option options [Adhearsion::CallController] :main The call controller class to execute on the 'main' call leg (the one who initiated the #dial)
+        # @option options [Proc] :main_callback A block to call when the :main controller completes
+        # @option options [Adhearsion::CallController] :others The call controller class to execute on the 'other' call legs (the ones created as a result of the #dial)
+        # @option options [Proc] :others_callback A block to call when the :others controller completes on an individual call
+        def split(targets = {})
+          logger.info "Splitting calls apart"
+          @splitting = true
+          @calls.each do |call|
+            logger.info "Unjoining peer #{call.id}"
+            ignoring_missing_joins { @call.unjoin call.id }
+            if split_controller = targets[:others]
+              logger.info "Executing split controller #{split_controller} on #{call.id}"
+              call.execute_controller split_controller.new(call, 'current_dial' => self), targets[:others_callback]
+            end
+          end
+          if split_controller = targets[:main]
+            logger.info "Executing split controller #{split_controller} on main call"
+            @call.execute_controller split_controller.new(@call, 'current_dial' => self), targets[:main_callback]
+          end
+        end
+
+        # Rejoin parties that were previously split
+        # @param [Call, String, Hash] target The target to join calls to. See Call#join for details.
+        def rejoin(target = @call)
+          logger.info "Rejoining to #{target}"
+          unless target == @call
+            @call.join target
+          end
+          @calls.each do |call|
+            call.join target
+          end
+        end
+
+        # Merge another Dial into this one, joining all calls to a mixer
+        # @param [Dial] other the other dial operation to merge calls from
+        def merge(other)
+          logger.info "Merging with #{other.inspect}"
+          mixer_name = SecureRandom.uuid
+
+          split
+          other.split
+
+          rejoin mixer_name: mixer_name
+          other.rejoin mixer_name: mixer_name
+
+          calls_to_merge = other.status.calls + [other.root_call]
+          @calls.concat calls_to_merge
+
+          latch = CountDownLatch.new calls_to_merge.size
+          calls_to_merge.each do |call|
+            call.on_end { |event| latch.countdown! }
+          end
+          @waiters << latch
+        end
+
+        #
+        # Block until the dial operation is completed by an appropriate quorum of the involved calls ending
         def await_completion
           @latch.wait(@options[:timeout]) || status.timeout!
-          @latch.wait if status.result == :answer
+          return unless status.result == :answer
+          @waiters.each(&:wait)
+        end
+
+        #
+        # Do not hangup outbound calls when the Dial operation finishes. This allows outbound calls to continue with other processing once they are unjoined.
+        def skip_cleanup
+          @skip_cleanup = true
         end
 
+        #
+        # Hangup any remaining calls
         def cleanup_calls
           calls_to_hangup = @calls.map do |call|
             begin
@@ -177,18 +258,45 @@ module Adhearsion
             logger.info "#dial finished with no remaining outbound calls"
             return
           end
-          logger.info "#dial finished. Hanging up #{calls_to_hangup.size} outbound calls which are still active: #{calls_to_hangup.map(&:first).join ", "}."
-          calls_to_hangup.each do |id, outbound_call|
-            begin
-              outbound_call.hangup
-            rescue Celluloid::DeadActorError
-              # This actor may previously have been shut down due to the call ending
+          if @skip_cleanup
+            logger.info "#dial finished. Leaving #{calls_to_hangup.size} outbound calls going which are still active: #{calls_to_hangup.map(&:first).join ", "}."
+          else
+            logger.info "#dial finished. Hanging up #{calls_to_hangup.size} outbound calls which are still active: #{calls_to_hangup.map(&:first).join ", "}."
+            calls_to_hangup.each do |id, outbound_call|
+              begin
+                outbound_call.hangup
+              rescue Celluloid::DeadActorError
+                # This actor may previously have been shut down due to the call ending
+              end
             end
           end
         end
 
+        protected
+
+        def root_call
+          @call
+        end
+
         private
 
+        def set_defaults
+          @status = DialStatus.new
+
+          @latch = CountDownLatch.new @targets.size
+          @waiters = [@latch]
+
+          @options[:from] ||= @call.from
+
+          _for = @options.delete :for
+          @options[:timeout] ||= _for if _for
+
+          @confirmation_controller = @options.delete :confirm
+          @confirmation_metadata = @options.delete :confirm_metadata
+
+          @skip_cleanup = false
+        end
+
         def pre_confirmation_tasks(call)
           on_all_except call do |target_call|
             logger.info "#dial hanging up call #{target_call.id} because this call has been answered by another channel"
@@ -200,7 +308,7 @@ module Adhearsion
         end
 
         def on_all_except(call)
-          @calls.each do |target_call, _|
+          @calls.each do |target_call|
             begin
               next if target_call.id == call.id
               yield target_call
@@ -209,16 +317,22 @@ module Adhearsion
             end
           end
         end
+
+        def ignoring_missing_joins
+          yield
+        rescue Punchblock::ProtocolError => e
+          raise unless e.name == :service_unavailable
+        end
       end
 
       class ParallelConfirmationDial < Dial
+        private
+
         def set_defaults
           super
           @apology_controller = @options.delete :apology
         end
 
-        private
-
         def pre_confirmation_tasks(call)
         end
 
@@ -237,7 +351,7 @@ module Adhearsion
 
       class DialStatus
         # The collection of calls created during the dial operation
-        attr_accessor :calls, :joined_call
+        attr_accessor :calls
 
         # A collection of status objects indexed by call. Provides status on the joins such as duration
         attr_accessor :joins
@@ -257,8 +371,7 @@ module Adhearsion
         end
 
         # @private
-        def answer!(call)
-          @joined_call = call
+        def answer!
           @result = :answer
         end
 

data/lib/adhearsion/console.rb

@@ -43,7 +43,7 @@ module Adhearsion
     end
 
     def stop
-      return unless instance_variable_defined?(:@pry_thread)
+      return unless instance_variable_defined?(:@pry_thread) && @pry_thread
       @pry_thread.kill
       @pry_thread = nil
       logger.info "Adhearsion Console shutting down"

data/lib/adhearsion/generators/app/templates/README.md

@@ -17,6 +17,23 @@ If you are using Asterisk 1.8, you will need to add an additional context with t
 
 ## FreeSWITCH
 
+### With mod_rayo (recommended)
+
+* Ensure that mod_rayo is installed and configured according to its' documentation.
+* Add an extension to your dialplan like so:
+
+```xml
+<extension name='Adhearsion'>
+  <condition field="destination_number" expression="^10$">
+    <action application='rayo'/>
+  </condition>
+</extension>
+```
+
+* Connect Adhearsion via XMPP using the Rayo protocol, as per the sample config.
+
+### With Punchblock's FreeSWITCH mode (deprecated)
+
 * Ensure that mod_event_socket is installed, and configure it in autoload_configs/event_socket.conf.xml to taste
 * Add an extension to your dialplan like so:
 
@@ -25,11 +42,13 @@ If you are using Asterisk 1.8, you will need to add an additional context with t
   <condition field="destination_number" expression="^10$">
     <action application="set" data="hangup_after_bridge=false"/>
     <action application="set" data="park_after_bridge=true"/>
-    <action application='park'/>
+    <action application='rayo'/>
   </condition>
 </extension>
 ```
 
+* Connect Adhearsion via EventSocket, as per the sample config.
+
 ## Voxeo PRISM
 
 Install the [rayo-server](https://github.com/rayo/rayo-server) app into PRISM 11 and follow the [configuration guide](https://github.com/rayo/rayo-server/wiki/Single-node-and-cluster-configuration-reference).