adhearsion 0.7.7 → 0.8.0

data/lib/adhearsion/foundation/pseudo_guid.rb

@@ -0,0 +1,10 @@
+module PseudoGuidGenerator
+  ##
+  # Generates a new 128-bit Globally Unique Identifier. It is a "pseudo" in that it does not adhere to the RFC which mandates
+  # that a certain section be reserved for a fragment of the NIC MAC address.
+  def new_guid(separator="-")
+    [8,4,4,4,12].map { |segment_length| String.random(segment_length) }.join(separator)
+  end
+end
+
+include PseudoGuidGenerator

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 : random_digit.to_s
+      when 10...36 : (random_digit + 55).chr
+      when 36...62 : (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 < Exception
+      
+    end
+    
+  end
+  
+  
+end

data/lib/adhearsion/initializer.rb

@@ -0,0 +1,373 @@
+module Adhearsion
+  
+  class << self
+    
+    ##
+    # Shuts down the framework.
+    #
+    def self.shutdown!
+      ahn_log "Shutting down gracefully at #{Time.now}."
+      Events.stop!
+      exit
+    end    
+    
+  end
+  class PathString < String
+    
+    class << self
+      
+      ##
+      # Will return a PathString for the application root folder to which the specified arbitrarily nested subfolder belongs.
+      # It works by traversing parent directories looking for the .ahnrc file. If no .ahnrc is found, nil is returned.
+      #
+      # @param [String] folder The path to the directory which should be a 
+      # @return [nil] if the subdirectory does not belong to a parent Adhearsion app directory
+      # @return [PathString] if a directory is found 
+      #
+      def from_application_subdirectory(folder)
+        folder = File.expand_path folder
+        ahn_rc = nil
+        
+        until ahn_rc || folder == "/"
+          possible_ahn_rc = File.join(folder, ".ahnrc")
+          if File.exists?(possible_ahn_rc)
+            ahn_rc = possible_ahn_rc
+          else
+            folder = File.expand_path(folder + "/..")
+          end
+        end
+        ahn_rc ? new(folder) : nil
+      end
+    end
+    
+    attr_accessor :component_path, :dialplan_path, :log_path
+    
+    def initialize(path)
+      super
+      defaults
+    end
+    
+    def defaults
+      @component_path = build_path_for "components"
+      @dialplan_path  = dup
+      @log_path       = build_path_for "logs"
+    end
+
+    def base_path=(value)
+      replace(value)
+      defaults
+    end
+    
+    def using_base_path(temporary_base_path, &block)
+      original_path = dup
+      self.base_path = temporary_base_path
+      block.call
+    ensure
+      self.base_path = original_path
+    end
+    
+    private
+      def build_path_for(path)
+        File.join(to_s, path)
+      end
+  end
+  
+  class Initializer
+    
+    class << self
+      def get_rules_from(location)
+        location = File.join location, ".ahnrc" if File.directory? location
+        File.exists?(location) ? YAML.load_file(location) : nil
+      end
+      
+      def ahn_root=(path)
+        if Object.constants.include?("AHN_ROOT")
+          Object.const_get(:AHN_ROOT).base_path = File.expand_path(path)
+        else
+          Object.const_set(:AHN_ROOT, PathString.new(File.expand_path(path)))
+        end
+      end
+      
+      def start(*args, &block)
+        new(*args, &block).start
+      end
+      
+      def start_from_init_file(file, ahn_app_path)
+        return if defined?(@@started) && @@started
+        start ahn_app_path, :loaded_init_files => file
+      end
+      
+    end
+  
+    attr_reader :path, :daemon, :pid_file, :log_file, :ahn_app_log_directory
+    
+    # Creation of pid_files
+    #
+    #  - You may want to have Adhearsion create a process identification
+    #    file when it boots so that a crash monitoring program such as
+    #    Monit can reboot if necessary or so the init script can kill it
+    #    for system shutdowns.
+    #  - To have Adhearsion create a pid file in the default location (i.e.
+    #    AHN_INSTALL_DIR/adhearsion.pid), supply :pid_file with 'true'. Otherwise
+    #    one is not created UNLESS it is running in daemon mode, in which
+    #    case one is created. You can force Adhearsion to not create one
+    #    even in daemon mode by supplying "false".
+    def initialize(path=nil, options={})
+      @@started = true
+      @path     = path
+      @daemon   = options[:daemon]
+      @pid_file = options[:pid_file].nil? ? ENV['PID_FILE'] : options[:pid_file]
+      @loaded_init_files  = options[:loaded_init_files]
+    end
+    
+    def start
+      self.class.ahn_root = path
+      
+      resolve_pid_file_path
+      resolve_log_file_path
+      switch_to_root_directory
+      catch_termination_signal
+      bootstrap_rc
+      daemonize! if should_daemonize?
+      initialize_log_file
+      load_all_init_files
+      init_components_subsystem
+      init_modules
+      init_events_subsystem
+      create_pid_file if pid_file
+      load_components
+      init_events_file
+      
+      ahn_log "Adhearsion initialized!"
+      
+      trigger_after_initialized_hooks
+      join_important_threads
+      
+      self
+    end
+    
+    def default_pid_path
+      File.join AHN_ROOT, 'adhearsion.pid'
+    end
+    
+    def resolve_pid_file_path
+      @pid_file = if pid_file.equal?(true) then default_pid_path
+      elsif pid_file then pid_file
+      elsif pid_file.equal?(false) then nil
+      # FIXME @pid_file = @daemon? Assignment or equality? I'm assuming equality.
+      else @pid_file = @daemon ? default_pid_path : nil
+      end
+    end
+    
+    def resolve_log_file_path      
+      @ahn_app_log_directory = AHN_ROOT + '/log'
+      @log_file = File.expand_path(ahn_app_log_directory + "/adhearsion.log")
+    end
+    
+    def switch_to_root_directory
+      Dir.chdir AHN_ROOT
+    end
+    
+    def catch_termination_signal
+      %w'INT TERM'.each do |process_signal|
+        trap process_signal do
+          ahn_log "Shutting down gracefully at #{Time.now}."
+          Events.trigger :shutdown
+          exit
+        end
+      end
+    end
+    
+    ##
+    # This step in the initialization process loads the .ahnrc in the given app folder. With the information in .ahnrc, we
+    # can continue the initialization knowing where certain files are specifically.
+    #
+    def bootstrap_rc
+      rules = self.class.get_rules_from AHN_ROOT
+      
+      AHN_CONFIG.ahnrc = rules
+      
+      # DEPRECATION: Check if the old paths format is being used. If so, abort and notify.
+      if rules.has_key?("paths") && rules["paths"].kind_of?(Hash)
+        paths = rules["paths"].each_pair do |key,value|
+          if value.kind_of?(Hash)
+            if value.has_key?("directory") || value.has_key?("pattern")
+              puts
+              puts *caller
+              puts
+                            
+              abort <<-WARNING
+Deprecation Warning
+-------------------
+The (hidden) .ahnrc file in this app is of an older format and needs to be fixed.
+
+There is a rake task to automatically fix it or you can do it manually. Note: it's
+best if you do it manually so you can retain the YAML comments in your .ahnrc file.
+  
+The rake task is called "deprecations:fix_ahnrc_path_format". 
+
+To do it manually, find all entries in the "paths" section of your ".ahnrc" file
+which look like the following:
+
+paths:
+  key_name_could_be_anything:
+    directory: some_folder
+    pattern: *.rb
+
+Note: the "models" section had this syntax before:
+
+models:
+  directory: models
+  pattern: "*.rb"
+
+The NEW syntax is as follows (using models as an example):
+
+models: models/*.rb
+
+This new format is much cleaner.
+
+Adhearsion will abort until you fix this. Sorry for the incovenience.
+              WARNING
+            end
+          end
+        end
+      end
+      
+      gems = rules['gems']
+      if gems.kind_of?(Hash) && gems.any? && respond_to?(:gem)
+        gems.each_pair do |gem_name,properties_hash|
+          if properties_hash && properties_hash["version"]
+            gem gem_name, properties_hash["version"]
+          else
+            gem gem_name
+          end
+          if properties_hash
+            case properties_hash["require"]
+              when Array
+                properties_hash["require"].each { |lib| require lib }
+              when String
+                require properties_hash["require"]
+            end 
+          end
+        end
+      end
+    end
+    
+    def load_all_init_files
+      init_files_from_rc = AHN_CONFIG.files_from_setting("paths", "init").map { |file| File.expand_path(file) }
+      already_loaded_init_files = Array(@loaded_init_files).map { |file| File.expand_path(file) }
+      (init_files_from_rc - already_loaded_init_files).each { |init| load init }
+    end
+    
+    def init_modules
+      require 'adhearsion/initializer/database.rb'
+      require 'adhearsion/initializer/asterisk.rb'
+      require 'adhearsion/initializer/drb.rb'
+      require 'adhearsion/initializer/rails.rb'
+      # require 'adhearsion/initializer/freeswitch.rb'
+      
+      DatabaseInitializer.start if AHN_CONFIG.database_enabled?
+      AsteriskInitializer.start if AHN_CONFIG.asterisk_enabled?
+      DrbInitializer.start      if AHN_CONFIG.drb_enabled?
+      RailsInitializer.start    if AHN_CONFIG.rails_enabled?
+      # FreeswitchInitializer.start if AHN_CONFIG.freeswitch_enabled?
+    end
+    
+    def init_events_subsystem
+      application_events_files = AHN_CONFIG.files_from_setting("paths", "events")
+      if application_events_files.any?
+        Events.register_callback(:shutdown) do
+          ahn_log.events "Performing a graceful stop of events subsystem"
+          Events.framework_theatre.graceful_stop!
+        end
+        Events.framework_theatre.start!
+      else
+        ahn_log.events.warn 'No entries in the "events" section of .ahnrc. Skipping its initialization.'
+      end
+    end
+    
+    def init_events_file
+      application_events_files = AHN_CONFIG.files_from_setting("paths", "events")
+      application_events_files.each do |file|
+        Events.framework_theatre.load_events_file file
+      end
+    end
+    
+    def should_daemonize?
+      @daemon || ENV['DAEMON']
+    end
+    
+    def daemonize!
+      ahn_log "Daemonizing now! Creating #{pid_file}."
+      extend Adhearsion::CustomDaemonizer
+      daemonize log_file
+    end
+    
+    def initialize_log_file
+      Dir.mkdir(ahn_app_log_directory) unless File.directory? ahn_app_log_directory
+      file_logger = Log4r::FileOutputter.new("Main Adhearsion log file", :filename => log_file, :trunc => false)
+      
+      if should_daemonize?
+        Logging::AdhearsionLogger.outputters  = file_logger
+      else
+        Logging::AdhearsionLogger.outputters << file_logger
+      end
+      Logging::DefaultAdhearsionLogger.redefine_outputters
+    end
+    
+    def create_pid_file(file = pid_file)
+      if file
+        File.open pid_file, 'w' do |file|
+          file.puts Process.pid
+        end
+        
+        Events.register_callback :shutdown do
+          File.delete(pid_file) if File.exists?(pid_file)
+        end
+      end
+    end
+    
+    def init_components_subsystem
+      @components_directory = File.expand_path "components"
+      if File.directory? @components_directory
+        Components.component_manager = Components::ComponentManager.new @components_directory
+        Kernel.send(:const_set, :COMPONENTS, Components.component_manager.lazy_config_loader)
+        Components.component_manager.globalize_global_scope!
+        Components.component_manager.extend_object_with(Theatre::CallbackDefinitionLoader, :events)
+      else
+        ahn_log.warn "No components directory found. Not initializing any components."
+      end
+    end
+    
+    def load_components
+      if Components.component_manager
+        Components.component_manager.load_components
+      end
+    end
+    
+    def trigger_after_initialized_hooks
+      Events.trigger_immediately :after_initialized
+    end
+    
+    ##
+    # This method will block Thread.main() until calling join() has returned for all Threads in IMPORTANT_THREADS.
+    # Note: IMPORTANT_THREADS won't always contain Thread instances. It simply requires the objects respond to join().
+    #
+    def join_important_threads
+      # Note: we're using this ugly accumulator to ensure that all threads have ended since IMPORTANT_THREADS will almost
+      # certainly change sizes after this method is called.
+      index = 0
+      until index == IMPORTANT_THREADS.size
+        begin
+          IMPORTANT_THREADS[index].join
+        rescue => e
+          ahn_log.error "Error after join()ing Thread #{thread.inspect}. #{e.message}"
+        ensure
+          index = index + 1
+        end
+      end
+    end
+    
+    class InitializationFailedError < Exception; end
+  end
+end