jicksta-adhearsion 0.7.999

data/lib/adhearsion/component_manager.rb

@@ -0,0 +1,208 @@
+module Adhearsion
+  module Components
+    
+    mattr_accessor :component_manager
+    
+    class ConfigurationError < Exception; end
+    
+    class ComponentManager
+      
+      class << self
+        
+        def scopes_valid?(*scopes)
+          unrecognized_scopes = (scopes.flatten - SCOPE_NAMES).map(&:inspect)
+          raise ArgumentError, "Unrecognized scopes #{unrecognized_scopes.to_sentence}" if unrecognized_scopes.any?
+          true
+        end
+        
+      end
+      
+      SCOPE_NAMES = [:dialplan, :events, :generators, :rpc, :global]
+      DEFAULT_CONFIG_NAME = "config.yml"
+      
+      attr_reader :scopes, :lazy_config_loader
+      def initialize(path_to_container_directory)
+        @path_to_container_directory = path_to_container_directory
+        @scopes = SCOPE_NAMES.inject({}) do |scopes, name|
+          scopes[name] = Module.new
+          scopes
+        end
+        @lazy_config_loader = LazyConfigLoader.new(self)
+      end
+      
+      ##
+      # Includes the anonymous Module created for the :global scope in Object, making its methods globally accessible.
+      #
+      def globalize_global_scope!
+        Object.send :include, @scopes[:global]
+      end
+      
+      def load_components
+        components = Dir.glob(File.join(@path_to_container_directory + "/*")).select do |path|
+          File.directory?(path)
+        end
+        components.map! { |path| File.basename path }
+        components.each do |component|
+          next if component == "disabled"
+          component_file = File.join(@path_to_container_directory, component, component + ".rb")
+          if File.exists? component_file
+            load_file component_file
+          else
+            ahn_log.warn "Component directory does not contain a matching .rb file! Was expecting #{component_file.inspect}"
+          end
+        end
+        
+      end
+      
+      ##
+      # Loads the configuration file for a given component name.
+      #
+      # @return [Hash] The loaded YAML for the given component name. An empty Hash if no YAML file exists.
+      #
+      def configuration_for_component_named(component_name)
+        component_dir = File.join(@path_to_container_directory, component_name)
+        config_file = File.join component_dir, DEFAULT_CONFIG_NAME
+        if File.exists?(config_file)
+          YAML.load_file config_file
+        else
+          return {}
+        end
+      end
+      
+      def extend_object_with(object, *scopes)
+        raise ArgumentError, "Must supply at least one scope!" if scopes.empty?
+        
+        self.class.scopes_valid? scopes
+        
+        scopes.each do |scope|
+          methods = @scopes[scope]
+          if object.kind_of?(Module)
+            object.send :include, methods
+          else
+            object.extend methods
+          end
+        end
+        object
+      end
+    
+      def load_code(code)
+        load_container ComponentDefinitionContainer.load_code(code)
+      end
+
+      def load_file(filename)
+        load_container ComponentDefinitionContainer.load_file(filename)
+      end
+      
+      protected
+      
+      def load_container(container)
+        container.constants.each do |constant_name|
+          constant_value = container.const_get(constant_name)
+          Object.const_set(constant_name, constant_value)
+        end
+        metadata = container.metaclass.send(:instance_variable_get, :@metadata)
+        metadata[:initialization_block].call if metadata[:initialization_block]
+        
+        self.class.scopes_valid? metadata[:scopes].keys
+        
+        metadata[:scopes].each_pair do |scope, method_definition_blocks|
+          method_definition_blocks.each do |method_definition_block|
+            @scopes[scope].module_eval(&method_definition_block)
+          end
+        end
+        container
+      end
+
+      class ComponentDefinitionContainer < Module
+        
+        class << self
+          def load_code(code)
+            returning(new) do |instance|
+              instance.module_eval code
+            end
+          end
+          
+          def load_file(filename)
+            returning(new) do |instance|
+              instance.module_eval File.read(filename), filename
+            end
+          end
+        end
+        
+        def initialize(&block)
+          # Hide our instance variables in the singleton class
+          metadata = {}
+          metaclass.send(:instance_variable_set, :@metadata, metadata)
+          
+          metadata[:scopes] = ComponentManager::SCOPE_NAMES.inject({}) do |scopes, name|
+            scopes[name] = []
+            scopes
+          end
+          
+          super
+          
+          meta_def(:initialize) { raise "This object has already been instantiated. Are you sure you didn't mean initialization()?" }
+        end
+        
+        def methods_for(*scopes, &block)
+          raise ArgumentError if scopes.empty?
+          
+          ComponentManager.scopes_valid? scopes
+          
+          metadata = metaclass.send(:instance_variable_get, :@metadata)
+          scopes.each { |scope| metadata[:scopes][scope] << block }
+        end
+        
+        def initialization(&block)
+          # Raise an exception if the initialization block has already been set
+          metadata = metaclass.send(:instance_variable_get, :@metadata)
+          if metadata[:initialization_block]
+            raise "You should only have one initialization() block!"
+          else
+            metadata[:initialization_block] = block
+          end
+        end
+        alias initialisation initialization
+        
+        protected
+        
+        class << self
+          def self.method_added(method_name)
+            @methods ||= []
+            @methods << method_name
+          end
+        end
+        
+      end
+    
+      class ComponentMethodDefinitionContainer < Module
+        class << self
+          def method_added(method_name)
+            @methods ||= []
+            @methods << method_name
+          end
+        end
+        
+        attr_reader :scopes
+        def initialize(*scopes, &block)
+          @scopes = []
+          super(&block)
+        end
+        
+      end
+    
+      class LazyConfigLoader
+        def initialize(component_manager)
+          @component_manager = component_manager
+        end
+        
+        def method_missing(component_name)
+          config = @component_manager.configuration_for_component_named(component_name.to_s)
+          (class << self; self; end).send(:define_method, component_name) { config }
+          config
+        end
+      end
+    
+    end
+  end
+end

data/lib/adhearsion/events_support.rb

@@ -0,0 +1,84 @@
+%w[theatre jicksta-theatre].each do |theatre_gem_name|
+  # Some older versions of the master branch required the theatre gem be installed. This is deprecation logic to inform the
+  # user to uninstall the gem if they happened to have used theatre in the past.
+  begin
+    gem theatre_gem_name
+  rescue LoadError
+    # Good. It should not be installed.
+  else
+    abort <<-MESSAGE
+It seems you have the "#{theatre_gem_name}" gem installed. As of Dec. 7th, 2008 Theatre has been rolled into Adhearsion
+and will be distributed with it.
+
+Please uninstall the gem by doing "sudo gem uninstall #{theatre_gem_name}".
+
+You will not need to install it again in the future. Sorry for the inconvenience.
+    MESSAGE
+  end
+end
+
+require 'theatre'
+
+
+module Adhearsion
+  module Events
+    
+    DEFAULT_FRAMEWORK_EVENT_NAMESPACES = %w[
+      /after_initialized
+      /shutdown
+      /asterisk/manager_interface
+      /asterisk/before_call
+      /asterisk/after_call
+      /asterisk/hungup_call
+      /asterisk/failed_call
+    ]
+    
+    class << self
+      
+      def framework_theatre
+        defined?(@@framework_theatre) ? @@framework_theatre : reinitialize_theatre!
+      end
+      
+      def trigger(*args)
+        framework_theatre.trigger(*args)
+      end
+      
+      def trigger_immediately(*args)
+        framework_theatre.trigger_immediately(*args)
+      end
+      
+      def reinitialize_theatre!
+        @@framework_theatre.gracefully_stop! if defined? @@framework_theatre
+      rescue
+        # Recover and reinitalize
+      ensure
+        # TODO: Extract number of threads to use from AHN_CONFIG
+        @@framework_theatre = Theatre::Theatre.new
+        DEFAULT_FRAMEWORK_EVENT_NAMESPACES.each do |namespace|
+          register_namespace_name namespace
+        end
+        return @@framework_theatre
+      end
+      
+      def register_namespace_name(name)
+        framework_theatre.register_namespace_name name
+      end
+      
+      def stop!
+        Events.trigger :shutdown
+        framework_theatre.graceful_stop!
+        framework_theatre.join
+      end
+      
+      def register_callback(namespace, block_arg=nil, &method_block)
+        raise ArgumentError, "Cannot supply two blocks!" if block_arg && block_given?
+        block = method_block || block_arg
+        raise ArgumentError, "Must supply a callback!" unless block
+        
+        framework_theatre.register_callback_at_namespace(namespace, block)
+      end
+      
+    end
+    
+  end
+end

data/lib/adhearsion/foundation/all.rb

@@ -0,0 +1,9 @@
+require 'English'
+require 'tmpdir'
+require 'tempfile'
+require 'active_support'
+
+# Require all other files here.
+Dir.glob File.join(File.dirname(__FILE__), "*rb") do |file|
+  require file
+end

data/lib/adhearsion/foundation/blank_slate.rb

@@ -0,0 +1,5 @@
+class BlankSlate
+  instance_methods.each do |method| 
+    undef_method method unless method =~ /^__/ || method == 'instance_eval'
+  end
+end

data/lib/adhearsion/foundation/custom_daemonizer.rb

@@ -0,0 +1,45 @@
+# This is largely based on the Daemonize library by Travis Whitton and
+# Judson Lester. http://grub.ath.cx/daemonize. I cleaned it up a bit to
+# meet Adhearsion's quality standards.
+module Adhearsion
+  module CustomDaemonizer
+  
+    # Try to fork if at all possible retrying every 5 sec if the
+    # maximum process limit for the system has been reached
+    def safefork
+      begin
+        pid = fork
+        return pid if pid
+      rescue Errno::EWOULDBLOCK
+        sleep 5
+        retry
+      end
+    end
+
+    # This method causes the current running process to become a daemon
+    def daemonize(log_file='/dev/null')
+      oldmode = 0
+      srand # Split rand streams between spawning and daemonized process
+      safefork and exit # Fork and exit from the parent
+
+      # Detach from the controlling terminal
+      unless sess_id = Process.setsid
+        raise 'Cannot detach from controlled terminal'
+      end
+
+      # Prevent the possibility of acquiring a controlling terminal
+      if oldmode.zero?
+        trap 'SIGHUP', 'IGNORE'
+        exit if pid = safefork
+      end
+
+      Dir.chdir "/"   # Release old working directory
+      File.umask 0000 # Ensure sensible umask
+
+      STDIN.reopen "/dev/null"
+      STDOUT.reopen '/dev/null', "a"
+      STDERR.reopen log_file 
+      return oldmode ? sess_id : 0
+    end
+  end
+end

data/lib/adhearsion/foundation/event_socket.rb

@@ -0,0 +1,203 @@
+##
+# EventSocket is a small abstraction of TCPSocket which causes it to behave much like an EventMachine Connection object for
+# the sake of better testability. The EventMachine Connection paradigm (as well as other networking libraries such as the 
+# Objective-C HTTP library) uses callbacks to signal different stages of a socket's lifecycle. 
+#
+# A handler can be registered in one of two ways: through registrations on an object yielded by the constructor or 
+# pre-defined on the object given as a constructor parameter. Below is an example definition which uses the block way:
+#
+#   EventSocket.new do |handler|
+#     def handler.receive_data(data)
+#       # Do something here
+#     end
+#     def handler.disconnected
+#       # Do something here
+#     end
+#     def handler.connected
+#       # Do something here
+#     end
+#   end
+#
+# Note: this is also a valid way of defining block callbacks:
+#
+#   EventSocket.new do |handler|
+#     handler.receive_data { |data| do_something }
+#     handler.disconnected { do_something }
+#     handler.connected    { do_something }
+#   end
+#
+# and here is an example of using a handler object:
+#
+#   class MyCallbackHandler
+#     def receive_data(data) end
+#     def connected() end
+#     def disconnected() end
+#   end
+#   EventSocket.new(MyCallbackHandler.new)
+#
+# If you wish to ask the EventSocket what state it is in, you can call the Thread-safe EventSocket#state method. The 
+# supported states are:
+#
+#  - :new
+#  - :connected
+#  - :stopped
+#  - :connection_dropped
+#
+# Note: the EventSocket's state will be changed before these callbacks are executed. For example, if your "connected" 
+# callback queried its own EventSocket for its state, it will have already transitioned to the connected() state.
+#
+# Warning: If an exception occurs in your EventSocket callbacks, they will be "eaten" and never bubbled up the call stack. 
+# You should always wrap your callbacks in a begin/rescue clause and handle exceptions explicitly.
+#
+require "thread"
+require "socket"
+
+class EventSocket
+
+  class << self
+    
+    ##
+    # Creates and returns a connected EventSocket instance.
+    #
+    def connect(*args, &block)
+      instance = new(*args, &block)
+      instance.connect!
+      instance
+    end
+  end
+
+  MAX_CHUNK_SIZE = 256 * 1024
+  
+  def initialize(host, port, handler=nil, &block)
+    raise ArgumentError, "Cannot supply both a handler object and a block" if handler && block_given?
+    raise ArgumentError, "Must supply either a handler object or a block" if !handler && !block_given?
+    
+    @state_lock = Mutex.new
+    @host  = host
+    @port  = port
+    
+    @state = :new
+    @handler = handler || new_handler_from_block(&block)
+  end
+  
+  def state
+    @state_lock.synchronize { @state }
+  end
+  
+  def connect!
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        raise ConnectionError, "Already connected!"
+      else
+        @socket = TCPSocket.new(@host, @port)
+        @state  = :connected
+      end
+    end
+    @handler.connected rescue nil
+    @reader_thread = spawn_reader_thread
+    self
+  rescue => error
+    @state = :failed
+    raise error
+  end
+  
+  ##
+  # Thread-safe implementation of write.
+  #
+  # @param [String] data Data to write
+  #
+  def send_data(data)
+    # Note: TCPSocket#write is intrinsically Thread-safe
+    @socket.write data
+  rescue
+    connection_dropped!
+  end
+    ##
+  # Disconnects this EventSocket and sets the state to :stopped
+  #
+  def disconnect!
+    @state_lock.synchronize do
+      @socket.close rescue nil
+      @state = :stopped
+    end
+  end
+  
+  ##
+  # Joins the Thread which reads data off the socket.
+  #
+  def join
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        @reader_thread.join
+      else
+        nil
+      end
+    end
+  end
+  
+  def receive_data(data)
+    @handler.receive_data(data)
+  end
+  
+  protected
+  
+  def connection_dropped!
+    @state_lock.synchronize do
+      unless @state.equal? :connection_dropped
+        @state = :connection_dropped
+        @handler.disconnected
+      end
+    end
+  end
+  
+  def spawn_reader_thread
+    Thread.new(&method(:reader_loop))
+  end
+  
+  def reader_loop
+    until state.equal? :stopped
+      data = @socket.readpartial(MAX_CHUNK_SIZE)
+      @handler.receive_data data
+    end
+  rescue EOFError
+    connection_dropped!
+  end
+
+  def new_handler_from_block(&handler_block)
+    handler = Object.new
+    handler.metaclass.send :attr_accessor, :set_callbacks
+    handler.set_callbacks = {:receive_data => false, :disconnected => false, :connected => false }
+    
+    def handler.receive_data(&block)
+      self.metaclass.send(:remove_method, :receive_data)
+      self.metaclass.send(:define_method, :receive_data) { |data| block.call data }
+      set_callbacks[:receive_data] = true
+    end
+    def handler.connected(&block)
+      self.metaclass.send(:remove_method, :connected)
+      self.metaclass.send(:define_method, :connected) { block.call }
+      set_callbacks[:connected] = true
+    end
+    def handler.disconnected(&block)
+      self.metaclass.send(:remove_method, :disconnected)
+      self.metaclass.send(:define_method, :disconnected) { block.call }
+      set_callbacks[:disconnected] = true
+    end
+    
+    def handler.singleton_method_added(name)
+      set_callbacks[name.to_sym] = true
+    end
+    
+    yield handler
+    
+    handler.set_callbacks.each_pair do |callback_name,was_set|
+      handler.send(callback_name) {} unless was_set
+    end
+    
+    handler
+    
+  end
+
+  class ConnectionError < Exception; end
+  
+end

data/lib/adhearsion/foundation/future_resource.rb

@@ -0,0 +1,36 @@
+require "thread"
+
+class FutureResource
+  
+  def initialize
+    @resource_lock          = Monitor.new
+    @resource_value_blocker = @resource_lock.new_cond
+  end
+  
+  def set_yet?
+    @resource_lock.synchronize { defined? @resource }
+  end
+  
+  def resource
+    @resource_lock.synchronize do
+      @resource_value_blocker.wait unless defined? @resource
+      @resource
+    end
+  end
+  
+  def resource=(resource)
+    @resource_lock.synchronize do
+      raise ResourceAlreadySetException if defined? @resource
+      @resource = resource
+      @resource_value_blocker.broadcast
+      @resource_value_blocker = nil # Don't really need it anymore.
+    end
+  end
+  
+  class ResourceAlreadySetException < Exception
+    def initialize
+      super "Cannot set this resource twice!"
+    end
+  end
+  
+end

data/lib/adhearsion/foundation/global.rb

@@ -0,0 +1 @@
+Infinity = 1.0/0.0

data/lib/adhearsion/foundation/metaprogramming.rb

@@ -0,0 +1,17 @@
+class Object
+  def metaclass
+    class << self
+      self
+    end
+  end
+  
+  def meta_eval(&block)
+    metaclass.instance_eval &block
+  end
+  
+  def meta_def(name, &block)
+    meta_eval do
+      define_method name, &block
+    end
+  end
+end

data/lib/adhearsion/foundation/numeric.rb

@@ -0,0 +1,13 @@
+class Numeric
+  
+  def digit()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+  def digits()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+end

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