sevenscale-adhearsion 0.7.1003 → 0.8.0

data/lib/adhearsion/voip/dial_plan.rb

@@ -1,6 +1,4 @@
 # Hardcoding require for now since for some reason it's not being loaded
-require 'adhearsion/blank_slate'
-require 'adhearsion/component_manager'
 require 'adhearsion/voip/dsl/dialplan/control_passing_exception'
 
 module Adhearsion
@@ -8,25 +6,40 @@ module Adhearsion
     attr_accessor :loader, :entry_points
     def initialize(loader = Loader)
       @loader       = loader
-      @entry_points = @loader.load_dial_plan.contexts
+      @entry_points = @loader.load_dialplans.contexts
     end
     
     ##
     # Lookup and return an entry point by context name
+    #
     def lookup(context_name)
       entry_points[context_name]
     end
     
     ##
-    # Executable environment for a dial plan in the scope of a call
+    # Executable environment for a dial plan in the scope of a call. This class has all the dialplan methods mixed into it.
+    #
     class ExecutionEnvironment
       
+      class << self
+        def create(*args)
+          returning(new(*args)) { |instance| instance.stage! }
+        end
+      end
+      
       attr_reader :call
-      def initialize(call, entry_point=nil)
+      def initialize(call, entry_point)
         @call, @entry_point = call, entry_point
+      end
+      
+      ##
+      # Adds the methods to this ExecutionEnvironment which make it useful. e.g. dialplan-related methods, call variables,
+      # and component methods.
+      #
+      def stage!
         extend_with_voip_commands!
         extend_with_call_variables!
-        extend_with_components_with_call_context!
+        extend_with_dialplan_component_methods!
       end
       
       def run
@@ -41,27 +54,22 @@ module Adhearsion
         end
       end
       
-      private
-        attr_reader :entry_point
-        
-        def extend_with_voip_commands!
-          extend(Adhearsion::VoIP::Conveniences)
-          extend(Adhearsion::VoIP::Commands.for(call.originating_voip_platform))
-        end
-        
-        def extend_with_call_variables!
-          call.define_variable_accessors self
-        end
-        
-        def extend_with_components_with_call_context!
-          ComponentManager.components_with_call_context.keys.each do |component_name|
-            eval <<-COMPONENT_BUILDER
-              def self.new_#{component_name.underscore}(*args, &block)
-                ComponentManager.components_with_call_context['#{component_name}'].instantiate_with_call_context(self, *args, &block)
-              end
-            COMPONENT_BUILDER
-          end
-        end
+      protected
+
+      attr_reader :entry_point
+      def extend_with_voip_commands!
+        extend Adhearsion::VoIP::Conveniences
+        extend Adhearsion::VoIP::Commands.for(call.originating_voip_platform)
+      end
+      
+      def extend_with_call_variables!
+        call.define_variable_accessors self
+      end
+      
+      def extend_with_dialplan_component_methods!        
+        Components.component_manager.extend_object_with(self, :dialplan) if Components.component_manager
+      end
+      
     end
     
     class Manager
@@ -81,20 +89,19 @@ module Adhearsion
       
       def handle(call)
         if call.failed_call?
-          environment = ExecutionEnvironment.new(call)
-          call.extract_failed_reason_from(environment)
+          environment = ExecutionEnvironment.create(call, nil)
+          call.extract_failed_reason_from environment
           raise FailedExtensionCallException.new(environment)
         end
         
         if call.hungup_call?
-          raise HungupExtensionCallException.new(ExecutionEnvironment.new(call))
+          raise HungupExtensionCallException.new(ExecutionEnvironment.new(call, nil))
         end
         
         starting_entry_point = entry_point_for call
         raise NoContextError, "No dialplan entry point for call context '#{call.context}' -- Ignoring call!" unless starting_entry_point
-      
-        @context = ExecutionEnvironment.new(call, starting_entry_point)
-        inject_context_names_into_environment(@context)
+        @context = ExecutionEnvironment.create(call, starting_entry_point)
+        inject_context_names_into_environment @context
         @context.run
       end
       
@@ -103,7 +110,7 @@ module Adhearsion
       def entry_point_for(call)
         if entry_point = dial_plan.lookup(call.context.to_sym)
           entry_point
-        elsif m = call.request.path.match(%r{/([^/]+)})
+        elsif call.respond_to?(:request) && m = call.request.path.match(%r{/([^/]+)})
           dial_plan.lookup(m[1].to_sym)
         end
       end
@@ -124,50 +131,55 @@ module Adhearsion
         attr_accessor :default_dial_plan_file_name
         
         def load(dial_plan_as_string)
-          returning new do |loader|
-            inject_dial_plan_component_classes_into dial_plan_as_string
-            loader.load(dial_plan_as_string)
+          string_io = StringIO.new dial_plan_as_string
+          def string_io.path
+            "(eval)"
           end
+          load_dialplans string_io
         end
         
-        def load_dial_plan(file_name = default_dial_plan_file_name)
-          load read_dialplan_file(AHN_ROOT.dial_plan_named(file_name))
-        end
-        
-        private
-          def inject_dial_plan_component_classes_into(dial_plan_as_string)
-            dial_plan_as_string[0, 0] = ComponentManager.components_with_call_context.keys.map do |component| 
-              "#{component} = ::Adhearsion::ComponentManager.components_with_call_context['#{component}'] unless defined? #{component}\n"
-            end.join
+        def load_dialplans(*files)
+          files = Adhearsion::AHN_CONFIG.files_from_setting("paths", "dialplan") if files.empty?
+          files = Array files
+          files.map! do |file|
+            case file
+              when File, StringIO
+                file
+              when String
+                File.new file
+              else
+                raise ArgumentError, "Unrecognized type of file #{file.inspect}"
+            end
           end
-          
-          def read_dialplan_file(filename)
-            File.read filename
+          returning new do |loader|
+            files.each do |file|
+              loader.load file
+            end
           end
-          
+        end
+        
       end
       
       self.default_dial_plan_file_name ||= 'dialplan.rb'
 
-      attr_reader :contexts
       def initialize
-        @contexts = {}
+        @context_collector = ContextNameCollector.new
       end
       
-      def load(dial_plan_as_string)
-        contexts.update(ContextNameCollector.build(dial_plan_as_string))
+      def contexts
+        @context_collector.contexts
+      end
+      
+      def load(dialplan_file)
+        dialplan_code = dialplan_file.read
+        @context_collector.instance_eval(dialplan_code, dialplan_file.path)
+        nil
       end
       
       class ContextNameCollector# < ::BlankSlate
         
         class << self
-          
-          def build(dial_plan_as_string)
-            builder = new
-            builder.instance_eval(dial_plan_as_string)
-            builder.contexts
-          end
-          
+
           def const_missing(name)
             super
           rescue ArgumentError
@@ -185,6 +197,7 @@ module Adhearsion
           super if !block_given? || args.any?
           contexts[name] = DialplanContextProc.new(name, &block)
         end
+        
       end
     end
     class DialplanContextProc < Proc

data/lib/adhearsion/voip/dsl/dialing_dsl.rb

@@ -15,7 +15,7 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
-require 'adhearsion/core_extensions/metaprogramming'
+require 'adhearsion/foundation/metaprogramming'
 require 'adhearsion/voip/conveniences'
 require 'adhearsion/voip/constants'
 require 'adhearsion/voip/dsl/dialing_dsl/dialing_dsl_monkey_patches'

data/lib/adhearsion/voip/dsl/dialplan/parser.rb

@@ -14,14 +14,10 @@ module Adhearsion
           
           #TODO: separate into smaller pieces
           def self.get_contexts
-            unless Adhearsion::Paths.manager_for?("dialplans")
-              raise "No dialplan files found in .ahnrc!" 
-            end
-            
             envelope = ContextsEnvelope.new
             
-            dialplans = all_dialplans
-            warn "No dialplan files were found!" if dialplans.empty?
+            dialplans = AHN_CONFIG.files_from_setting "paths", "dialplan"
+            ahn_log.dialplan.warn "No dialplan files were found!" if dialplans.empty?
             
             returning({}) do |contexts|
               dialplans.each do |file|

data/lib/adhearsion/voip/dsl/numerical_string.rb

@@ -52,10 +52,10 @@ module Adhearsion
 
         # Checks against a pattern identifying US local numbers (i.e numbers
         # without an area code seven digits long)
-        def local_number?() to_s =~ Adhearsion::VoIP::Constants::US_LOCAL_NUMBER end
+        def us_local_number?() to_s =~ Adhearsion::VoIP::Constants::US_LOCAL_NUMBER end
 
         # Checks against a pattern identifying US domestic numbers.
-        def national_number?() to_s =~ Adhearsion::VoIP::Constants::US_NATIONAL_NUMBER end
+        def us_national_number?() to_s =~ Adhearsion::VoIP::Constants::US_NATIONAL_NUMBER end
 
         # Checks against a pattern identifying an ISN number. See http://freenum.org
         # for more info.

data/lib/adhearsion/voip/freeswitch/oes_server.rb

@@ -52,7 +52,7 @@ module Adhearsion
           # If the target context does not exist, warn and don't handle the call
           unless first_context
             log "No context '#{first_context_name}' found in " +
-                "#{all_dialplans.to_sentence(:connector => "or")}. Ignoring request!"
+                "#{AHN_CONFIG.files_from_setting("paths", "").to_sentence(:connector => "or")}. Ignoring request!"
             return
           end
           
@@ -91,7 +91,7 @@ module Adhearsion
         # time.
         def should_reload_contexts?
           !@abstract_contexts || !@abstract_dispatcher ||
-            all_dialplans.map { |x| File.mtime(x) }.max < Time.now
+            AHN_CONFIG.files_from_setting("paths", "dialplan").map { |x| File.mtime(x) }.max < Time.now
         end
         
         def rubyize_keys_for(hash)

data/lib/adhearsion.rb

@@ -3,30 +3,35 @@ STDERR.puts "WARNING: You are running Adhearsion in an unsupported
 version of Ruby (Ruby #{RUBY_VERSION} #{RUBY_RELEASE_DATE})!
 Please upgrade to at least Ruby v1.8.5." if RUBY_VERSION < "1.8.5"
 
-module Adhearsion
-  # Sets up the Gem require path.
-  AHN_INSTALL_DIR = File.expand_path(File.dirname(__FILE__) + "/..")
-  CONFIG = {}
-end
-
 $: << File.expand_path(File.dirname(__FILE__))
 
 require 'rubygems'
+
 require 'adhearsion/version'
 require 'adhearsion/voip/call'
 require 'adhearsion/voip/dial_plan'
 require 'adhearsion/voip/asterisk/special_dial_plan_managers'
-require 'adhearsion/core_extensions/all'
-require 'adhearsion/blank_slate'
-require 'adhearsion/hooks'
+require 'adhearsion/foundation/all'
 require 'adhearsion/events_support'
 require 'adhearsion/logging'
+require 'adhearsion/component_manager'
 require 'adhearsion/initializer/configuration'
 require 'adhearsion/initializer'
-require 'adhearsion/initializer/paths'
 require 'adhearsion/voip/dsl/numerical_string'
 require 'adhearsion/voip/dsl/dialplan/parser'
 require 'adhearsion/voip/commands'
 require 'adhearsion/voip/asterisk/commands'
 require 'adhearsion/voip/dsl/dialing_dsl'
-require 'adhearsion/voip/call_routing'
+require 'adhearsion/voip/call_routing'
+
+module Adhearsion
+  # Sets up the Gem require path.
+  AHN_INSTALL_DIR = File.expand_path(File.dirname(__FILE__) + "/..")
+  AHN_CONFIG = Configuration.new
+  
+  ##
+  # This Array holds all the Threads whose life matters. Adhearsion will not exit until all of these have died.
+  #
+  IMPORTANT_THREADS = []
+  
+end

data/lib/theatre/README.markdown

@@ -0,0 +1,64 @@
+Theatre
+=======
+
+Present status: stable
+
+A library for choreographing a dynamic pool of hierarchically organized actors. This was originally extracted from the [Adhearsion](http://adhearsion.com) framework by Jay Phillips.
+
+In the Adhearsion framework, it was necessary to develop an internal message-passing system that could work either synchronously or asynchronously. This is used by the framework itself and for framework extensions (called _components_) to talk with each other. The source of the events is completely undefined -- events could originate from within the framework out outside the framework. For example, a Message Queue such as [Stomp](http://stomp.codehaus.org) can wire incoming events into Theatre and catch events going to a particular destination so it can proxy them out to the server.
+
+Motivations and Design Decisions
+--------------------------------
+
+* Must maintain Ruby 1.8 and JRuby compatibility
+* Must be Thread-safe
+* Must provide some level of transparency into the events going through it
+* Must be dynamic enough to reallocate the number of triggerrs based on load
+* Must help facilitate test-driven development of Actor functionality
+* Must allow external persistence in case of a crash
+
+Example
+-------
+
+Below is an example taken from Adhearsion for executing framework-level callbacks. Note: the framework treats this callback synchronously.
+
+    events.framework.asterisk.before_call.each do |event|
+      # Pull headers from event and respond to it here.
+    end
+
+Below is an example of integration with [Stomp](http://stomp.codehaus.org/), a simple yet robust open-protocol message queue.
+
+    events.stomp.new_call.each do |event|
+      # Handle all events from the Stomp MQ server whose name is "new_call" (the String)
+    end
+
+This will filter all events whose name is "new_call" and yield the Stomp::Message to the block.
+
+Framework terminology
+--------------------
+
+Below are definitions of terms I use in Theatre. See the respective links for more information.
+
+* **callback**: This is the block given to the `each` method which triggers events coming in.
+* **payload**: This is the "message" sent to the Theatre and is what will ultimately be yielded to the callback
+* **[Actor](http://en.wikipedia.org/wiki/Actor_model)**: This refers to concurrent responders to events in a concurrent system.
+
+Synchronous vs. Asynchronous
+----------------------------
+
+With Theatre, all events are asynchronous with the optional ability to synchronously block until the event is scheduled, triggered, and has returned. If you wish to synchronously trigger the event, simple call `wait` on an `Invocation` object returned from `trigger` and then check the `Invocation#current_state` property for `:success` or `:error`. Optionally the `Invocation#success?` and `Invocation#error?` methods also provide more intuitive access to the finished state. If the event finished with `:success`, you may retrieve the returned value of the event Proc by calling `Invocation#returned_value`. If the event finished with `:error`, you may get the Exception with `Invocation#error`.
+
+Because many callbacks can be registered for a particular namespace, each needing its own Invocation object, the `Theatre#trigger` method returns an Array of Invocation objects.
+
+    # We'll assume only one callback is registered and call #first on the Array of Invocations returned by #trigger
+    invocation = my_theatre.trigger("your/namespace/here", YourSpecialClass.new("this can be anything")).first
+    invocation.wait
+    raise invocation.error if invocation.error?
+    log "Actor finished with return value #{invocation.returned_value}"
+
+Ruby 1.8 vs. Ruby 1.9 vs. JRuby
+-------------------------------
+
+Theatre was created for Ruby 1.8 because no good Actor system existed on Ruby 1.8 that met Adhearsion's needs (e.g. hierarchal with synchronous and asynchronous modes. If you wish to achieve real processor-level concurrency, use JRuby.
+
+Presently Ruby 1.9 compatibility is not a priority but patches for compatibility will be accepted, as long as they preserve compatibility with both MRI and JRuby.

data/lib/theatre/callback_definition_loader.rb

@@ -0,0 +1,84 @@
+module Theatre
+  
+  ##
+  # This class provides the a wrapper aroung which an events.rb file can be instance_eval'd.
+  #
+  class CallbackDefinitionLoader
+    
+    attr_reader :theatre, :root_name
+    def initialize(theatre, root_name=:events)
+      @theatre   = theatre
+      @root_name = root_name
+      
+      create_recorder_method root_name
+    end
+    
+    def anonymous_recorder
+      BlankSlateMessageRecorder.new(&method(:callback_registered))
+    end
+    
+    ##
+    # Parses the given Ruby source code file and returns this object.
+    #
+    # @param [String, File] file The filename or File object for the Ruby source code file to parse.
+    #
+    def load_events_file(file)
+      file = File.open(file) if file.kind_of? String
+      instance_eval file.read, file.path
+      self
+    end
+    
+    ##
+    # Parses the given Ruby source code and returns this object.
+    #
+    # NOTE: Only use this if you're generating the code yourself! If you're loading a file from the filesystem, you should
+    # use load_events_file() since load_events_file() will properly attribute errors in the code to the file from which the
+    # code was loaded.
+    #
+    # @param [String] code The Ruby source code to parse
+    #
+    def load_events_code(code)
+      instance_eval code
+      self
+    end
+    
+    protected
+    
+    ##
+    # Immediately register the namespace and callback with the Theatre instance given to the constructor. This method is only
+    # called when a new BlankSlateMessageRecorder is instantiated and receives #each().
+    #
+    def callback_registered(namespaces, callback)
+      # Get rid of all arguments passed to the namespaces. Will support arguments in the future.
+      namespaces = namespaces.map { |namespace| namespace.first }
+      
+      theatre.namespace_manager.register_callback_at_namespace namespaces, callback
+    end
+    
+    def create_recorder_method(record_method_name)
+      (class << self; self; end).send(:alias_method, record_method_name, :anonymous_recorder)
+    end
+    
+    class BlankSlateMessageRecorder
+      
+      (instance_methods - %w[__send__ __id__]).each { |m| undef_method m }
+      
+      def initialize(&notify_on_completion)
+        @notify_on_completion = notify_on_completion
+        @namespaces = []
+      end
+      
+      def method_missing(*method_name_and_args)
+        raise ArgumentError, "Supplying a block is not supported" if block_given?
+        @namespaces << method_name_and_args
+        self
+      end
+      
+      def each(&callback)
+        @notify_on_completion.call(@namespaces, callback)
+      end
+      
+    end
+    
+  end
+end

data/lib/theatre/guid.rb

@@ -0,0 +1,23 @@
+# Right now Adhearsion also defines this method. The eventual solution will be to extract the Adhearsion features on which
+# Theatre depends and make that a dependent library.
+
+unless respond_to? :new_guid
+  
+  def random_character
+    case random_digit = rand(62)
+      when  0...10 : random_digit.to_s
+      when 10...36 : (random_digit + 55).chr
+      when 36...62 : (random_digit + 61).chr
+    end
+  end
+  
+  def random_string(length_of_string=8)
+    Array.new(length_of_string) { random_character }.join
+  end
+  
+  # This GUID implementation doesn't adhere to the RFC which wants to make certain segments based on the MAC address of a
+  # network interface card and other wackiness. It's sufficiently random for our needs.
+  def new_guid
+    [8,4,4,4,12].map { |segment_length| random_string(segment_length) }.join('-')
+  end
+end

data/lib/theatre/invocation.rb

@@ -0,0 +1,121 @@
+require 'theatre/guid'
+require 'thread'
+require 'monitor'
+
+module Theatre
+  
+  ##
+  # An Invocation is an object which Theatre generates and returns from Theatre#trigger.
+  #
+  class Invocation
+    
+    attr_reader :queued_time, :started_time, :finished_time, :unique_id, :callback, :namespace, :error, :returned_value
+    
+    class InvalidStateError < Exception; end
+    
+    ##
+    # Create a new Invocation.
+    #
+    # @param [String] namespace The "/foo/bar/qaz" path to the namespace to which this Invocation belongs.
+    # @param [Proc] callback The block which should be executed by an Actor scheduler.
+    # @param [Object] payload The message that will be sent to the callback for processing.
+    #
+    def initialize(namespace, callback, payload=:theatre_no_payload)
+      raise ArgumentError, "Callback must be a Proc" unless callback.kind_of? Proc
+      @payload       = payload
+      @unique_id     = new_guid.freeze
+      @callback      = callback
+      @current_state = :new
+      @state_lock    = Mutex.new
+      
+      # Used just to protect access to the @returned_value instance variable
+      @returned_value_lock = Monitor.new
+      
+      # Used when wait() is called to notify all waiting threads by using a ConditionVariable
+      @returned_value_blocker = Monitor::ConditionVariable.new @returned_value_lock
+    end
+    
+    def queued
+      with_state_lock do
+        raise InvalidStateError unless @current_state == :new
+        @current_state = :queued
+        @queued_time = Time.now.freeze
+      end
+      true
+    end
+    
+    def current_state
+      with_state_lock { @current_state }
+    end
+    
+    def start
+      with_state_lock do
+        raise InvalidStateError unless @current_state == :queued
+        @current_state = :running
+      end
+      @started_time = Time.now.freeze
+      
+      begin
+        self.returned_value = if @payload.equal? :theatre_no_payload
+          @callback.call
+        else
+          @callback.call @payload
+        end
+        with_state_lock { @current_state = :success }
+      rescue => @error
+        with_state_lock { @current_state = :error }
+      ensure
+        @finished_time = Time.now.freeze
+      end
+    end
+    
+    def execution_duration
+      return nil unless @finished_time
+      @finished_time - @started_time
+    end
+    
+    def error?
+      current_state.equal? :error
+    end
+    
+    def success?
+      current_state.equal? :success
+    end
+    
+    ##
+    # When this Invocation has been queued, started, and entered either the :success or :error state, this method will
+    # finally return. Until then, it blocks the Thread.
+    #
+    # @return [Object] The result of invoking this Invocation's callback
+    #
+    def wait
+      with_returned_value_lock { return @returned_value if defined? @returned_value }
+      @returned_value_blocker.wait
+      # Return the returned_value
+      with_returned_value_lock { @returned_value }
+    end
+    
+    protected
+    
+    ##
+    # Protected setter which does some other housework when the returned value is found (such as notifying wait()ers)
+    #
+    # @param [returned_value] The value to set this returned value to.
+    #
+    def returned_value=(returned_value)
+      with_returned_value_lock do
+        @returned_value = returned_value
+        @returned_value_blocker.broadcast
+      end
+    end
+    
+    def with_returned_value_lock(&block)
+      @returned_value_lock.synchronize(&block)
+    end
+    
+    def with_state_lock(&block)
+      @state_lock.synchronize(&block)
+    end
+    
+  end
+end