eric-adhearsion 0.7.999 → 0.8.0

data/app_generators/ahn/templates/components/disabled/HOW_TO_ENABLE

@@ -0,0 +1,7 @@
+Type "ahn enable component COMPONENT_NAME_FROM_DISABLED_FOLDER
+
+For example:
+
+~/Desktop $ ahn create myapp
+~/Desktop $ cd myapp
+~/Desktop/myapp $ ahn enable component stomp_gateway

data/app_generators/ahn/templates/components/disabled/stomp_gateway/README.markdown

@@ -0,0 +1,47 @@
+What is Stomp?
+==============
+
+Stomp is a very simple message-queue protocol with which two separate systems can communicate. Because the protocol is so simple, there are many Stomp server implementations from which you can choose. Some of these include
+
+ - ActiveMQ (http://activemq.com)
+ - Ruby "stompserver" gem (gem install stompserver)
+ - RabbitMQ (http://rabbitmq.com)
+
+If you wish to get up and running with a development environment, the Ruby stompserver gem is a fantastic starting point. For a critical production system, ActiveMQ should probably be used but it bears the cumbersome paradigm of many "enterprisey" Java applications.
+
+How does it work?
+=================
+
+Stomp is used when certain processes have defined responsibilities. For example, your Adhearsion application's responsibility is to communicate with your Asterisk machine. Other processes (e.g. a Rails web application) will probably need to instruct Adhearsion to do something. Instructions may include
+
+ - Start a new call between two given phone numbers
+ - Have a particular call do something based on a new event
+ - Hangup a call
+
+Below is a diagram which should give you a better idea of how it works.
+
+    Process  Process  Process (e.g. Rails)
+         \      |      /
+          \     |     /
+           Stomp Server       (e.g. ActiveMQ)
+                |
+                |
+             Process          (e.g. Adhearsion)
+
+Note: Adhearsion could also be the sender of messages through the Stomp server which are consumed by a number of handlers.
+
+Setting up a Ruby Stomp server
+==============================
+
+Install the pure-Ruby Stomp server by doing "gem install stompserver". This will add the "stompserver" command to your system. When running it without any parameters, it starts without requiring authentication. If you're wanting to get a quick experiment running, I recommend simply doing that.
+
+Open the config.yml file in the stomp_gateway component folder. Comment out the four settings at the top of the file named "user", "pass", "host" and "port" by prepending a "#" to their line. This will cause the component to choose defaults for those properties. The component's defaults will match the expected credentials for the experimental stompserver you're already running on your computer.
+
+You also need specify a subscription name in 
+
+    events.stomp.start_call.each do |event|
+      # The "event" variable holds a Stomp::Message object.
+      name = event.headers
+    end
+
+You a

data/app_generators/ahn/templates/components/disabled/stomp_gateway/config.yml

@@ -0,0 +1,12 @@
+# Comment out any of these properties to use a default.
+
+user: stomp_user
+pass: secret_password
+host: localhost
+port: 61613
+
+### Add your list of subscriptions below that this gateway should proxy to events.rb
+
+# subscriptions:
+#   - start_call
+#   - hangup_call

data/app_generators/ahn/templates/components/disabled/stomp_gateway/stomp_gateway.rb

@@ -0,0 +1,34 @@
+require 'stomp'
+
+# TODO: Recover from a disconnect!
+
+initialization do
+  user = COMPONENTS.stomp_gateway[:user] || ""
+  pass = COMPONENTS.stomp_gateway[:pass] || ""
+  host = COMPONENTS.stomp_gateway[:host] || "localhost"
+  port = COMPONENTS.stomp_gateway[:port] || 61613
+  
+  ::StompGatewayConnection = Stomp::Client.open(user, pass, host, port)
+  
+  subscriptions = COMPONENTS.stomp_gateway["subscriptions"]
+  
+  ahn_log.stomp_gateway "Connection established. Subscriptions: #{subscriptions.inspect}"
+  
+  Events.register_namespace_name "/stomp"
+  
+  subscriptions.each do |subscription|
+    Events.register_namespace_name "/stomp/#{subscription}"
+    ::StompGatewayConnection.subscribe subscription do |event|
+      Adhearsion::Events.trigger ["stomp", subscription], event
+    end
+  end
+  
+end
+
+methods_for :global do
+  def send_stomp(destination, message, headers={})
+    ::StompGatewayConnection.send(destination, message, headers)
+  end
+end
+
+# In the future, I may add a methods_for(:events) method which allows synchronous messaging.

data/app_generators/ahn/templates/components/simon_game/{lib/simon_game.rb → simon_game.rb}

@@ -1,10 +1,14 @@
+methods_for :dialplan do
+  def simon_game
+    SimonGame.new(self).start
+  end
+end
+
 class SimonGame
-  add_call_context :as => :call_context
 
-  attr_accessor :number, :attempt
-  def initialize
-    initialize_number
-    initialize_attempt
+  def initialize(call)
+    @call = call
+    reset
   end
   
   def start
@@ -20,38 +24,29 @@ class SimonGame
   end
 
   def update_number
-    initialize_attempt
     @number << random_number
   end
 
   def say_number
     update_number
-    call_context.say_digits number
+    @call.say_digits @number
   end
 
   def collect_attempt
-    @attempt = call_context.input(number.size)
+    @attempt = @call.input @number.length
   end
 
   def verify_attempt
     if attempt_correct? 
-      call_context.play 'good'
+      @call.play 'good'
     else
-      call_context.play %W(#{number.size - 1} times wrong-try-again-smarty)
+      @call.play %W[#{@number.length-1} times wrong-try-again-smarty]
       reset
     end
   end
 
   def attempt_correct?
-    attempt == number
-  end
-  
-  def initialize_attempt
-    @attempt ||= ''
-  end
-  
-  def initialize_number
-    @number ||= ''
+    @attempt == @number
   end
   
   def reset

data/app_generators/ahn/templates/config/startup.rb

@@ -26,12 +26,9 @@ Adhearsion::Configuration.configure do |config|
   
   # By default Asterisk is enabled with the default settings
   config.enable_asterisk
-  # config.asterisk.enable_ami :host => "127.0.0.1", :username => "admin", :password => "password"
+  # config.asterisk.enable_ami :host => "127.0.0.1", :username => "admin", :password => "password", :events => true
   
-  # To change the host IP or port on which the AGI server listens, use this:
-  # config.enable_asterisk :listening_port => 4574, :listening_host => "127.0.0.1"
-  
-  # config.enable_drb 
+  # config.enable_drb
   
   # Streamlined Rails integration! The first argument should be a relative or absolute path to 
   # the Rails app folder with which you're integrating. The second argument must be one of the 
@@ -50,4 +47,4 @@ Adhearsion::Configuration.configure do |config|
   #                        :host     => 'db.example.org'
 end
 
-Adhearsion::Initializer.start_from_init_file(__FILE__, File.dirname(__FILE__) + "/..")
+Adhearsion::Initializer.start_from_init_file(__FILE__, File.dirname(__FILE__) + "/..")

data/app_generators/ahn/templates/dialplan.rb

@@ -1,4 +1,3 @@
 adhearsion {
-  simon = new_simon_game
-  simon.start
-}
+  simon_game
+}

data/app_generators/ahn/templates/events.rb

@@ -0,0 +1,32 @@
+##
+# In this file you can define callbacks for different aspects of the framework. Below is an example:
+##
+#
+# events.asterisk.before_call.each do |call|
+#   # This simply logs the extension for all calls going through this Adhearsion app.
+#   extension = call.variables[:extension]
+#   ahn_log "Got a new call with extension #{extension}"
+# end
+#
+##
+# Asterisk Manager Interface example:
+#
+# events.asterisk.manager_interface.each do |event|
+#   ahn_log.events event.inspect
+# end
+#
+# This assumes you gave :events => true to the config.asterisk.enable_ami method in config/startup.rb
+#
+##
+# Here is a list of the events included by default:
+#
+# - events.asterisk.manager_interface
+# - events.after_initialized
+# - events.shutdown
+# - events.asterisk.before_call
+# - events.asterisk.failed_call
+# - events.asterisk.call_hangup
+#
+#
+# Note: events are mostly for components to register and expose to you.
+##

data/bin/jahn

@@ -29,4 +29,14 @@ require 'adhearsion/cli'
 # file from an app.
 # require 'adhearsion/jruby'
 
+abort(<<-MESSAGE) unless RUBY_PLATFORM =~ /java/
+You must use jahn with JRuby! Are you running this script after installing Adhearsion with non-JRuby RubyGems?
+
+If you don't want to install Adhearsion with the JRuby version of RubyGems, try running jahn directly with an absolute path:
+
+#{File.expand_path(__FILE__)} start your_app_name
+
+Note: You must have the jruby executable in your $PATH and $JRUBY_HOME set.
+MESSAGE
+
 Adhearsion::CLI::AhnCommand.execute!

data/examples/asterisk_manager_interface/standalone.rb

@@ -0,0 +1,51 @@
+# This is a file which shows you how to use the Asterisk Manager Interface library in a standalone Ruby script.
+
+PATH_TO_ADHEARSION = File.join(File.dirname(__FILE__), "/../..")
+
+MANAGER_CONNECTION_INFORMATION = {
+  :host     => "10.0.1.97",
+  :username => "jicksta",
+  :password => "roflcopter",
+  :events   => true
+}
+
+require 'rubygems'
+begin
+  require 'adhearsion'
+rescue LoadError
+  begin
+    require File.join(PATH_TO_ADHEARSION, "/lib/adhearsion")
+  rescue LoadError
+    abort "Could not find Adhearsion! Please update the PATH_TO_ADHEARSION constant in this file"
+  end
+end
+
+require 'adhearsion/voip/asterisk/manager_interface'
+
+# If you'd like to see the AMI protocol data, change this to :debug
+Adhearsion::Logging.logging_level = :warn
+
+# This makes addressing the ManagerInterface class a little cleaner
+include Adhearsion::VoIP::Asterisk::Manager
+
+# Let's instantiate a new ManagerInterface object and have it automatically connect using the Hash we defined above.
+interface = ManagerInterface.connect MANAGER_CONNECTION_INFORMATION
+
+# Send an AMI action with our new ManagerInterface object. This will return an Array of SIPPeer events.
+sip_peers = interface.send_action "SIPPeers"
+
+# Pretty-print the SIP peers on the server
+
+if sip_peers.any?
+  sip_peers.each do |peer|
+    # Uncomment the following line to view all the headers for each peer.
+    # p peer.headers
+    
+    peer_name   = peer.headers["ObjectName"]
+    peer_status = peer.headers["Status"]
+    
+    puts "#{peer_name}: #{peer_status}"
+  end
+else
+  puts "This Asterisk server has no SIP peers!"
+end

data/lib/adhearsion.rb

@@ -3,29 +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/adhearsion/cli.rb

@@ -6,16 +6,26 @@ module Adhearsion
       USAGE = <<USAGE
 Usage:
    ahn create /path/to/directory
-   ahn start [daemon] [directory]
+   ahn start [daemon] [/path/to/directory]
    ahn version|-v|--v|-version|--version
    ahn help|-h|--h|--help|-help
-
-Under development:
-   ahn create:projectname /path/to/directory
+   
+   ahn  enable component COMPONENT_NAME
+   ahn disable component COMPONENT_NAME
+   ahn  create component COMPONENT_NAME
 USAGE
     
       def self.execute!
         CommandHandler.send(*parse_arguments)
+      rescue CommandHandler::CLIException => error
+        fail_and_print_usage error
+      end
+      
+      ##
+      # Provides a small abstraction of Kernel::abort().
+      #
+      def self.fail_and_print_usage(error)
+        Kernel.abort "#{error.message}\n\n#{USAGE}"
       end
       
       def self.parse_arguments(args=ARGV.clone)
@@ -23,14 +33,14 @@ USAGE
         case action
           when /^-?-?h(elp)?$/, nil   then [:help]
           when /^-?-?v(ersion)?$/     then [:version]
-          when /^create(:([\w_.]+))?$/
-            [:create, args.shift, $LAST_PAREN_MATCH || :default]
+          when "create"
+            [:create, *args]
           when 'start'
             pid_file_regexp = /^--pid-file=(.+)$/
             if args.size > 3
-              raise CommandHandler::UnknownCommand, "Too many arguments supplied!" if args.size > 3
+              fail_and_print_usage "Too many arguments supplied!" if args.size > 3
             elsif args.size == 3
-              raise CommandHandler::UnknownCommand, "Unrecognized final argument #{args.last}" unless args.last =~ pid_file_regexp
+              fail_and_print_usage "Unrecognized final argument #{args.last}" unless args.last =~ pid_file_regexp
               pid_file = args.pop[pid_file_regexp, 1]
             else
               pid_file = nil
@@ -42,11 +52,19 @@ USAGE
             elsif args.size == 1
               path, daemon = args.first, false
             else
-              raise CommandHandler::UnknownCommand, "Invalid format for the start CLI command!"
+              fail_and_print_usage "Invalid format for the start CLI command!"
             end
             [:start, path, daemon, pid_file]
           when '-'
             [:start, Dir.pwd]
+          when "enable", "disable"
+            if args.size == 1
+              raise CommandHandler::UnknownCommand, "Must supply an argument for what you wish to #{action}"
+            elsif args.size == 2
+              [action, *args]
+            else
+              raise CommandHandler::UnknownCommand, "Too many arguments supplied!"
+            end
           else
             [action, *args]
         end
@@ -54,20 +72,61 @@ USAGE
       
       module CommandHandler
         class << self
-          def create(path, project=:default)
-            raise UnknownProject.new(project) if project != :default # TODO: Support other projects
-            require 'rubigen'
-            require 'rubigen/scripts/generate'
-            source = RubiGen::PathSource.new(:application, 
-              File.join(File.dirname(__FILE__), "../../app_generators"))
-            RubiGen::Base.reset_sources
-            RubiGen::Base.append_sources source
-            RubiGen::Scripts::Generate.new.run([path], :generator => 'ahn')
+          
+          def create(*args)
+            if args.size.zero?
+              raise CommandHandler::UnknownCommand.new("Must specify something to create!")
+            elsif args.size == 1
+              # We're creating a project
+              path = args.first
+              require 'rubigen'
+              require 'rubigen/scripts/generate'
+              source = RubiGen::PathSource.new(:application, 
+                File.join(File.dirname(__FILE__), "../../app_generators"))
+              RubiGen::Base.reset_sources
+              RubiGen::Base.append_sources source
+              RubiGen::Scripts::Generate.new.run([path], :generator => 'ahn')
+            elsif args.size == 2
+              # We're creating a feature (e.g. a component)
+              feature_type, component_name = args
+              
+              if feature_type != "component"
+                # At the moment, only components can be created.
+                raise CommandHandler::UnknownCommand.new("Don't know how to create '#{feature_type}'") 
+              end
+              
+              if component_name !~ /^[a-z][\w_]+$/
+                raise CommandHandler::ComponentError.new("Component name must be lowercase alphanumeric characters " +
+                    "and begin with a character")
+              end
+              
+              app_path = PathString.from_application_subdirectory Dir.pwd
+              
+              raise PathInvalid.new(Dir.pwd) if app_path.nil?
+              
+              new_component_dir = app_path + "/components/#{component_name}"
+              raise ComponentError.new("Component #{component_name} already exists!") if File.exists?(new_component_dir)
+              
+              # Everything's good. Let's create the component
+              Dir.mkdir new_component_dir
+              File.open(new_component_dir + "/#{component_name}.rb","w") do |file|
+                file.puts <<-RUBY
+# See http://docs.adhearsion.com for more information on how to write components or
+# look at the examples in newly-created projects.
+                RUBY
+              end
+              File.open(new_component_dir + "/config.yml","w") do |file|
+                file.puts '# You can use this file for component-specific configuration.'
+              end
+              puts "Created blank component '#{component_name}' at components/#{component_name}"
+            else
+              raise CommandHandler::UnknownCommand.new("Provided too many arguments to 'create'")
+            end
           end
         
           def start(path, daemon=false, pid_file=nil)
             raise PathInvalid, path unless File.exists? path + "/.ahnrc"
-            Adhearsion::Initializer.new path, :daemon => daemon, :pid_file => pid_file
+            Adhearsion::Initializer.start path, :daemon => daemon, :pid_file => pid_file
           end
         
           def version
@@ -78,26 +137,84 @@ USAGE
             puts USAGE
           end
         
+          def enable(type, name)
+            case type
+              when "component"
+                app_path = PathString.from_application_subdirectory Dir.pwd
+                if app_path
+                  disabled_component_path = File.join app_path, "components", "disabled", name
+                  enabled_component_path  = File.join app_path, "components", name
+                  if File.directory? disabled_component_path
+                    FileUtils.mv disabled_component_path, enabled_component_path
+                    puts "Enabled component #{name}"
+                  else
+                    raise ComponentError.new("There is no components/disabled directory!")
+                  end
+                else
+                  raise PathInvalid.new(Dir.pwd)
+                end
+              else
+                raise UnknownCommand.new("enable #{type}")
+            end
+          end
+          
+          def disable(type, name)
+            case type
+              when "component"
+                app_path = PathString.from_application_subdirectory Dir.pwd
+                if app_path
+                  disabled_dir = File.join app_path, "components", "disabled"
+                  
+                  disabled_component_path = File.join disabled_dir, name
+                  enabled_component_path  = File.join app_path, "components", name
+                  
+                  Dir.mkdir disabled_dir unless File.directory?(disabled_dir)
+                  
+                  if File.directory? enabled_component_path
+                    if File.directory?(disabled_component_path)
+                      raise ComponentError.new("There is already a disabled component at #{disabled_component_path}")
+                    else
+                      FileUtils.mv enabled_component_path, disabled_component_path
+                      puts "Disabled component #{name}"
+                    end
+                  else
+                    raise ComponentError.new("Could not find component #{name} at #{enabled_component_path} !")
+                  end
+                else
+                  raise PathInvalid.new(Dir.pwd)
+                end
+              else
+                raise UnknownCommand.new("disable #{type}")
+            end
+          end
+          
           def method_missing(action, *args)
             raise UnknownCommand, [action, *args] * " "
           end
+          
+          private
+          
         end
         
-        class UnknownCommand < Exception
+        class CLIException < Exception; end
+        
+        class UnknownCommand < CLIException
           def initialize(cmd)
-            super "Unknown command: #{cmd}\n#{USAGE}"
+            super "Unknown command: #{cmd}"
           end
         end
         
-        class UnknownProject < Exception
+        class ComponentError < CLIException; end
+        
+        class UnknownProject < CLIException
           def initialize(project)
             super "Application #{project} does not exist! Have you installed it?"
           end
         end
         
-        class PathInvalid < Exception
+        class PathInvalid < CLIException
           def initialize(path)
-            super "Directory #{path} does not contain an Adhearsion project!"
+            super "Directory #{path} does not belong to an Adhearsion project!"
           end
         end
       end