adhearsion-cw 1.0.2.1

data/lib/adhearsion/foundation/relationship_properties.rb

@@ -0,0 +1,42 @@
+class Module
+
+  ##
+  # In OOP, relationships between classes should be treated as *properties* of those classes. Often, in a complex OO
+  # architecture, you'll end up with many relationships that intermingle in monolithic ways, blunting the effectiveness of
+  # subclassing.
+  #
+  # For example, say you have an Automobile class which, in its constructor, instantiates a new Battery class and performs
+  # some operations on it such as calling an install() method. Let's also assume the Automobile class exposes a repair()
+  # method which uses a class-level method of Battery to diagnose your own instance of Battery. If the result of the
+  # diagnosis shows that the Battery is bad, the Automobile will instantiate a new Battery object and replace the old battery
+  # with the new one.
+  #
+  # Now, what if you wish to create a new Automobile derived from existing technology: a HybridAutomobile subclass. For this
+  # particular HybridAutomobile class, let's simply say the only difference between it and its parent is which kind of
+  # Battery it uses -- it requires its own special subclass of Battery. With Automobile's current implementation, its
+  # references to which Battery it instantiates and uses are embedded in the immutable method defintions. This
+  # HybridAutomobile needs to override which Battery its superclass' methods use and nothing else.
+  #
+  # For this reason, the Battery class which Automobile uses is semantically a property which others may want to override.
+  # In OOP theory, we define overridable properties in the form of methods and override those methods in the subclasses.
+  #
+  # This method exposes one method which creates human-readable semantics to defining these relationships as properties. It's
+  # used as follows:
+  #
+  # class Automobile
+  #   relationship :battery => Battery
+  #   relationship :chassis => Chassis
+  #   # Other properties and instance methods here....
+  # end
+  #
+  # class HybridAutomobile < Automobile
+  #   relationship :battery => HybridBattery
+  # end
+  #
+  def relationships(relationship_mapping)
+    relationship_mapping.each_pair do |class_name, class_object|
+      define_method(class_name) { class_object }
+    end
+  end
+
+end

data/lib/adhearsion/foundation/string.rb

@@ -0,0 +1,26 @@
+class String
+
+  def unindent
+    gsub(/^\s*/,'')
+  end
+
+  def unindent!
+    gsub!(/^\s*/,'')
+  end
+
+  def self.random_char
+    case random_digit = rand(62)
+      when  0...10 then random_digit.to_s
+      when 10...36 then (random_digit + 55).chr
+      when 36...62 then (random_digit + 61).chr
+    end
+  end
+
+  def self.random(length_of_string=8)
+    Array.new(length_of_string) { random_char }.join
+  end
+
+  def nameify() downcase.gsub(/[^\w]/, '') end
+  def nameify!() replace nameify end
+
+end

data/lib/adhearsion/foundation/synchronized_hash.rb

@@ -0,0 +1,96 @@
+##
+# Implementation of a Thread-safe Hash. Works by delegating methods to a Hash behind-the-scenes after obtaining an exclusive # lock. Use exactly as you would a normal Hash.
+#
+class SynchronizedHash
+
+  def self.atomically_delegate(method_name)
+    class_eval(<<-RUBY, __FILE__, __LINE__)
+      def #{method_name}(*args, &block)
+        @lock.synchronize do
+          @delegate.send(#{method_name.inspect}, *args, &block)
+        end
+      end
+    RUBY
+  end
+
+  # Hash-related methods
+
+  atomically_delegate :[]
+  atomically_delegate :[]=
+  atomically_delegate :all?
+  atomically_delegate :any?
+  atomically_delegate :clear
+  atomically_delegate :collect
+  atomically_delegate :default
+  atomically_delegate :default=
+  atomically_delegate :delete
+  atomically_delegate :delete_if
+  atomically_delegate :detect
+  atomically_delegate :each
+  atomically_delegate :each_key
+  atomically_delegate :each_pair
+  atomically_delegate :each_value
+  atomically_delegate :each_with_index
+  atomically_delegate :empty?
+  atomically_delegate :entries
+  atomically_delegate :fetch
+  atomically_delegate :find
+  atomically_delegate :find_all
+  atomically_delegate :grep
+  atomically_delegate :has_key?
+  atomically_delegate :has_value?
+  atomically_delegate :include?
+  atomically_delegate :index
+  atomically_delegate :indexes
+  atomically_delegate :indices
+  atomically_delegate :inject
+  atomically_delegate :invert
+  atomically_delegate :key?
+  atomically_delegate :keys
+  atomically_delegate :length
+  atomically_delegate :map
+  atomically_delegate :max
+  atomically_delegate :member?
+  atomically_delegate :merge
+  atomically_delegate :merge!
+  atomically_delegate :min
+  atomically_delegate :partition
+  atomically_delegate :rehash
+  atomically_delegate :reject
+  atomically_delegate :reject!
+  atomically_delegate :replace
+  atomically_delegate :select
+  atomically_delegate :shift
+  atomically_delegate :size
+  atomically_delegate :sort
+  atomically_delegate :sort_by
+  atomically_delegate :store
+  atomically_delegate :to_hash
+  atomically_delegate :update
+  atomically_delegate :value?
+  atomically_delegate :values
+  atomically_delegate :values_at
+  atomically_delegate :zip
+
+  # Object-related methods
+
+  atomically_delegate :inspect
+  atomically_delegate :to_s
+  atomically_delegate :marshal_dump
+
+  def initialize(*args, &block)
+    @delegate = Hash.new(*args, &block)
+    @lock     = Mutex.new
+  end
+
+  ##
+  # If you need to do many operations atomically (a la transaction), you can call this method and access the yielded Hash
+  # which can be safely modified for the duration of your block.
+  #
+  # @yield [Hash] the Hash on which you can safely operate during your block.
+  #
+  def with_lock(&block)
+    @lock.synchronize { yield @delegate }
+  end
+
+end

data/lib/adhearsion/foundation/thread_safety.rb

@@ -0,0 +1,7 @@
+require 'thread'
+class Object
+  def synchronize(&block)
+    @mutex ||= Mutex.new
+    @mutex.synchronize &block
+  end
+end

data/lib/adhearsion/host_definitions.rb

@@ -0,0 +1,67 @@
+require 'yaml'
+
+module Adhearsion
+
+  ##
+  # This class isn't yet tied into Adhearsion.
+  #
+  class HostDefinition
+
+    SUPPORTED_KEYS = [:host, :username, :password, :key, :name]
+
+    cattr_reader :definitions
+    @@definitions ||= []
+
+    class << self
+      def import_from_data_structure(local_definitions)
+        case local_definitions
+          when Array
+            local_definitions.each do |definition|
+              raise HostDefinitionException, "Unrecognized definition: #{definition}" unless definition.is_a?(Hash)
+            end
+            local_definitions.map { |definition| new definition }
+          when Hash
+            local_definitions.map do |(name,definition)|
+              new definition.merge(:name => name)
+            end
+          else
+            raise HostDefinitionException, "Unrecognized definition #{local_definitions}"
+        end
+      end
+
+      def import_from_yaml(yaml_string)
+        import_from_data_structure YAML.load(yaml_string)
+      end
+
+      def import_from_yaml_file(file)
+        import_from_yaml YAML.load_file(file)
+      end
+
+      def clear_definitions!
+        definitions.clear
+      end
+    end
+
+    attr_reader :name, :host, :username, :password, :key
+    def initialize(hash)
+      @host, @username, @password, @key, @name = hash.values_at(*SUPPORTED_KEYS)
+      @name ||= new_guid
+
+      unrecognized_keys = hash.keys - SUPPORTED_KEYS
+      raise HostDefinitionException, "Unrecognized key(s): #{unrecognized_keys.map(&:inspect).to_sentence}" if unrecognized_keys.any?
+      raise HostDefinitionException, "You must supply a password or key!" if username && !(password || key)
+      raise HostDefinitionException, "You must supply a username!" unless username
+      raise HostDefinitionException, 'You cannot supply both a password and key!' if password && key
+      raise HostDefinitionException, 'You must supply a host!' unless host
+
+      self.class.definitions << self
+    end
+
+    class HostDefinitionException < StandardError
+
+    end
+
+  end
+
+
+end

data/lib/adhearsion/initializer/asterisk.rb

@@ -0,0 +1,87 @@
+require 'adhearsion/voip/asterisk'
+module Adhearsion
+  class Initializer
+
+    class AsteriskInitializer
+
+      cattr_accessor :config, :agi_server, :ami_client
+      class << self
+
+        def start
+          self.config     = AHN_CONFIG.asterisk
+          self.agi_server = initialize_agi
+          self.ami_client = VoIP::Asterisk.manager_interface = initialize_ami if config.ami_enabled?
+          join_server_thread_after_initialized
+
+          # Make sure we stop everything when we shutdown
+          Events.register_callback(:shutdown) do
+            ahn_log.info "Shutting down with #{Adhearsion.active_calls.size} active calls"
+            self.stop
+          end
+        end
+
+        def stop
+          agi_server.graceful_shutdown
+          ami_client.disconnect! if ami_client
+        end
+
+        private
+
+        def initialize_agi
+          VoIP::Asterisk::AGI::Server.new :host => config.listening_host,
+                                          :port => config.listening_port
+        end
+
+        def initialize_ami
+          options = ami_options
+          start_ami_after_initialized
+          VoIP::Asterisk::Manager::ManagerInterface.new(options).tap do
+            class << VoIP::Asterisk
+              if respond_to?(:manager_interface)
+                ahn_log.warn "Asterisk.manager_interface already initialized?"
+              else
+                def manager_interface
+                  # ahn_log.ami.warn "Warning! This Asterisk.manager_interface() notation is for Adhearsion version 0.8.0 only. Subsequent versions of Adhearsion will use a feature called SuperManager. Migrating to use SuperManager will be very simple. See http://docs.adhearsion.com/AMI for more information."
+                  Adhearsion::Initializer::AsteriskInitializer.ami_client
+                end
+              end
+            end
+          end
+        end
+
+        def ami_options
+          %w(host port username password events auto_reconnect).inject({}) do |options, property|
+            options[property.to_sym] = config.ami.send property
+            options
+          end
+        end
+
+        def join_server_thread_after_initialized
+          Events.register_callback(:after_initialized) do
+            begin
+              agi_server.start
+            rescue => e
+              ahn_log.fatal "Failed to start AGI server! #{e.inspect}"
+              abort
+            end
+          end
+          IMPORTANT_THREADS << agi_server
+        end
+
+        def start_ami_after_initialized
+          Events.register_callback(:after_initialized) do
+            begin
+              self.ami_client.connect!
+            rescue Errno::ECONNREFUSED
+              ahn_log.ami.error "Connection refused when connecting to AMI! Please check your configuration."
+            rescue => e
+              ahn_log.ami.error "Error connecting to AMI! #{e.inspect}"
+            end
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/adhearsion/initializer/configuration.rb

@@ -0,0 +1,321 @@
+module Adhearsion
+  class Configuration
+    module ConfigurationEntryPoint
+      def add_configuration_for(name)
+        configuration_class_name = "#{name}Configuration"
+        lowercased_name          = name.to_s.underscore
+
+        class_eval(<<-EVAL, __FILE__, __LINE__)
+          def enable_#{lowercased_name}(configuration_options = {})
+            @#{lowercased_name}_configuration = #{configuration_class_name}.new(configuration_options)
+          end
+
+          def #{lowercased_name}
+            @#{lowercased_name}_configuration
+          end
+
+          def #{lowercased_name}_enabled?
+            !#{lowercased_name}.nil?
+          end
+        EVAL
+      end
+    end
+    extend ConfigurationEntryPoint
+
+    class << self
+      def configure(&block)
+        if Adhearsion.const_defined?(:AHN_CONFIG)
+          yield AHN_CONFIG if block_given?
+        else
+          Adhearsion.const_set(:AHN_CONFIG, new(&block))
+        end
+      end
+    end
+
+    attr_accessor :automatically_answer_incoming_calls
+    attr_accessor :end_call_on_hangup
+    attr_accessor :end_call_on_error
+    attr_accessor :components_to_load
+
+    def initialize
+      @automatically_answer_incoming_calls = true
+      @end_call_on_hangup                  = true
+      @end_call_on_error                   = true
+      @components_to_load                  = []
+      yield self if block_given?
+    end
+
+    def ahnrc
+      @ahnrc
+    end
+
+    ##
+    # Load the contents of an .ahnrc file into this Configuration.
+    #
+    # @param [String, Hash] ahnrc String of YAML .ahnrc data or a Hash of the pre-loaded YAML data structure
+    #
+    def ahnrc=(new_ahnrc)
+      case new_ahnrc
+        when Hash
+          @raw_ahnrc = new_ahnrc.to_yaml.freeze
+          @ahnrc = new_ahnrc.clone.freeze
+        when String
+          @raw_ahnrc = new_ahnrc.clone.freeze
+          @ahnrc = YAML.load(new_ahnrc).freeze
+      end
+    end
+
+    def logging(options)
+      Adhearsion::Logging.logging_level = options[:level]
+    end
+
+    def add_component(*list)
+      AHN_CONFIG.components_to_load |= list
+    end
+
+    ##
+    # Adhearsion's .ahnrc file is used to define paths to certain parts of the framework. For example, the name dialplan.rb
+    # is actually specified in .ahnrc. This file can actually be just a filename, a filename with a glob (.e.g "*.rb"), an
+    # Array of filenames or even an Array of globs.
+    #
+    # @param [String,Array] String segments which convey the nesting of Hash keys through .ahnrc
+    # @raise [RuntimeError] If ahnrc has not been set yet with #ahnrc=()
+    # @raise [NameError] If the path through the ahnrc is invalid
+    #
+    def files_from_setting(*path_through_config)
+      raise RuntimeError, "No ahnrc has been set yet!" unless @ahnrc
+      queried_nested_setting = path_through_config.flatten.inject(@ahnrc) do |hash,key_name|
+        if hash.kind_of?(Hash) && hash.has_key?(key_name)
+          hash[key_name]
+        else
+          raise NameError, "Paths #{path_through_config.inspect} not found in .ahnrc!"
+        end
+      end
+      raise NameError, "Paths #{path_through_config.inspect} not found in .ahnrc!" unless queried_nested_setting
+      queried_nested_setting = Array queried_nested_setting
+      queried_nested_setting.map { |filename| files_from_glob(filename) }.flatten.uniq
+    end
+
+    private
+
+    def files_from_glob(glob)
+      Dir.glob "#{AHN_ROOT}/#{glob}"
+    end
+
+    class AbstractConfiguration
+      extend ConfigurationEntryPoint
+
+      class << self
+        private
+          def abstract_method!
+            raise "Must be implemented in subclasses"
+          end
+      end
+
+      def initialize(overrides = {})
+        overrides.each_pair do |attribute, value|
+          send("#{attribute}=", value)
+        end
+      end
+    end
+
+    # Abstract superclass for AsteriskConfiguration and FreeSwitchConfiguration.
+    class TelephonyPlatformConfiguration < AbstractConfiguration
+      attr_accessor :listening_port
+      attr_accessor :listening_host
+
+      class << self
+        def default_listening_port
+          abstract_method!
+        end
+
+        def default_listening_host
+          '0.0.0.0'
+        end
+      end
+
+      def initialize(overrides = {})
+        @listening_host = overrides.has_key?(:host) ? overrides.delete(:host) : self.class.default_listening_host
+        @listening_port = overrides.has_key?(:port) ? overrides.delete(:port) : self.class.default_listening_port
+        super
+      end
+    end
+
+    class AsteriskConfiguration < TelephonyPlatformConfiguration
+      attr_accessor :speech_engine
+      attr_accessor :argument_delimiter
+
+      class << self
+        def default_listening_port
+          4573
+        end
+
+        # Keep Asterisk 1.4 (and prior) as the default to protect upgraders
+        # This setting only applies to AGI.  AMI delimiters are always
+        # auto-detected.
+        def default_argument_delimiter
+          '|'
+        end
+      end
+
+      def initialize(overrides = {})
+        @argument_delimiter = self.class.default_argument_delimiter
+        super
+      end
+
+      class AMIConfiguration < AbstractConfiguration
+        attr_accessor :port, :username, :password, :events, :host, :auto_reconnect
+
+        class << self
+          def default_port
+            5038
+          end
+
+          def default_events
+            false
+          end
+
+          def default_host
+            'localhost'
+          end
+
+          def default_auto_reconnect
+            true
+          end
+        end
+
+        def initialize(overrides = {})
+          self.host           = self.class.default_host
+          self.port           = self.class.default_port
+          self.events         = self.class.default_events
+          self.auto_reconnect = self.class.default_auto_reconnect
+          super
+        end
+      end
+      add_configuration_for :AMI
+    end
+    add_configuration_for :Asterisk
+
+    class FreeswitchConfiguration < TelephonyPlatformConfiguration
+      class << self
+        def default_listening_port
+          4572
+        end
+      end
+    end
+    add_configuration_for :Freeswitch
+
+    class DatabaseConfiguration < AbstractConfiguration
+      attr_accessor :connection_options, :orm
+      def initialize(options)
+        @orm                = options.delete(:orm) || :active_record # TODO: ORM is a misnomer
+        @connection_options = options
+      end
+    end
+    add_configuration_for :Database
+
+    class LdapConfiguration < AbstractConfiguration
+      attr_accessor :connection_options
+      def initialize(options)
+        @connection_options = options
+      end
+    end
+    add_configuration_for :Ldap
+
+    class DrbConfiguration < AbstractConfiguration
+      attr_accessor :port
+      attr_accessor :host
+      attr_accessor :acl
+
+      # ACL = Access Control List
+
+      class << self
+        def default_port
+          9050
+        end
+
+        def default_host
+          'localhost'
+        end
+      end
+
+      def initialize(overrides = {})
+        self.port = overrides[:port] || self.class.default_port
+        self.host = overrides[:host] || self.class.default_host
+        self.acl  = overrides[:raw_acl]
+
+        unless acl
+          self.acl = []
+          [*overrides[ :deny]].compact.each { |ip| acl << 'deny' << ip }
+          [*overrides[:allow]].compact.each { |ip| acl << 'allow' << ip }
+          acl.concat %w[allow 127.0.0.1] if acl.empty?
+        end
+      end
+    end
+    add_configuration_for :Drb
+
+    class RailsConfiguration < AbstractConfiguration
+
+      attr_accessor :rails_root, :environment
+      def initialize(options)
+        path_to_rails, environment = check_options options
+        @rails_root = File.expand_path(path_to_rails)
+        @environment = environment.to_sym
+      end
+
+      private
+
+      def check_options(options)
+        options = options.clone
+        path    = options.delete :path
+        env     = options.delete :env
+        raise ArgumentError, "Unrecognied argument(s) #{options.keys.to_sentence} in Rails initializer!" unless options.size.zero?
+        raise ArgumentError, "Must supply an :env argument to the Rails initializer!" unless env
+        raise ArgumentError, "Must supply an :path argument to the Rails initializer!" unless path
+        [path, env]
+      end
+
+    end
+    add_configuration_for :Rails
+
+    class XMPPConfiguration < AbstractConfiguration
+
+      attr_accessor :jid, :password, :server, :port
+      def initialize(options)
+        jid, password, server, port = check_options options
+        @jid = jid
+        @password = password
+        @server = server
+        @port = port
+      end
+
+      class << self
+        def default_port
+          5222
+        end
+      end
+
+      private
+
+      def check_options(options)
+        options  = options.clone
+        jid      = options.delete :jid
+        password = options.delete :password
+        server   = options.delete :server
+        port     = options.delete :port
+        raise ArgumentError, "Unrecognied argument(s) #{options.keys.to_sentence} in XMPP initializer!" unless options.size.zero?
+        raise ArgumentError, "Must supply a :jid argument to the XMPP initializer!" unless jid
+        raise ArgumentError, "Must supply a :password argument to the XMPP initializer!" unless password
+        if server
+          port ||= self.class.default_port
+        else
+          raise ArgumentError, "Must supply a :server argument as well as :port to the XMPP initializer!" if port
+        end
+        [jid, password, server, port]
+      end
+
+    end
+    add_configuration_for :XMPP
+
+  end
+end