freec 0.2.0

data/Manifest

@@ -0,0 +1,17 @@
+lib/call_variables.rb
+lib/freec.rb
+lib/listener.rb
+lib/freec_base.rb
+lib/freec_logger.rb
+lib/freeswitch_applications.rb
+lib/tools.rb
+Manifest
+Rakefile
+README.rdoc
+spec/event_parser_spec.rb
+spec/freec_base_spec.rb
+spec/freeswitch_applications_spec.rb
+spec/spec_helper.rb
+spec/data/event.rb
+spec/data/event_with_body.rb
+

data/README.rdoc

@@ -0,0 +1,73 @@
+= About
+Freec is a framework you can build voice applications on top of. It makes use of the Event socket outbound API of Freeswitch.
+
+= Installation
+  sudo gem install jankubr-freec
+
+= Usage
+1. Install Freeswitch and point a chosen extension to the IP where your app will run:
+  
+  <extension name="telfa">
+    <condition field="destination_number" expression="^.*$">
+      <action application="socket" data="127.0.0.1:8084 async full" />
+    </condition>
+  </extension>
+  
+2. Create a file with the main class of your application (e.g. Jukebox) and make it a subclass of Freec. Name the file according to the class name (e.g. jukebox.rb). Implement
+   a step method instructions for which will follow. Simple example:
+ 
+  #jukebox.rb
+  require 'rubygems'
+  require 'freec'
+  class Jukebox < Freec
+    def step
+      @step ||= 1
+      case @step
+        when 1
+          answer
+        when 2
+          playback('music/8000/danza-espanola-op-37-h-142-xii-arabesca.wav')
+        when 3
+          return nil
+      end
+      @step += 1
+    end
+  end
+
+3. Run it with:
+  ruby jukebox.rb
+
+= How does it work 
+The step method is called after each even is finished (e.g. file is played, recording is finished). Here is what you can do:
+* read call variables from the hash in call_vars
+* call one of the following methods (Freeswitch apps):
+ * answer
+ * playback(path_to_file)
+ * bridge(number_or_numbers)
+ * record(path_to_file)
+ * read(path_to_file)
+ * set_variable(name, value)
+ * any other via execute_app(app_name, params)
+If you return nil or false from the step method, the call will be hungup.
+  
+= Cool stuff
+* Your application's main file as well as everything you might have in the lib directory will be reloaded on each step in development mode.
+* Passing -d will daemonize the application and automatically implies production mode. 
+* The log directory contains the log file and the pid file.
+* There is a hidden feature.
+
+= Stinks?
+What Freec can do at the moment was enough for me to implement Telfa (http://telfapbx.com). If it doesn't fit your needs, you can:
+1. Complain to hi@jankubr.com .
+2. Fork it and change yourself.
+3. Check Liverpie (http://www.liverpie.com/) or Telegraph (http://code.google.com/p/telegraph/), Freec is inspired by them.
+4. Write yours :-)
+
+= License
+Copyright © 2009 Jan Kubr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('freec', '0.2.0') do |p|
+  p.description    = "Layer between your Ruby voice app and Freeswitch."
+  p.url            = "http://github.com/jankubr/freec"
+  p.author         = "Jan Kubr"
+  p.email          = "hi@jankubr.com"
+  p.ignore_pattern = []
+  p.runtime_dependencies = ['daemons']
+  p.development_dependencies = ['rspec']
+end
+
+desc 'Clean up files.'
+task :clean do |t|
+  FileUtils.rm_rf "tmp"
+  FileUtils.rm_rf "pkg"
+end
+
+spec = Gem::Specification.new do |s| 
+  s.name              = "freec"
+  s.version           = '0.2.0'
+  s.author            = "Jan Kubr"
+  s.email             = "hi@jankubr.com"
+  s.homepage          = "http://github.com/jankubr/freec"
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = "Layer between your Ruby voice app and Freeswitch."
+  s.files             = FileList["README*",
+                                 "Rakefile",
+                                 "{lib,spec}/**/*"].to_a
+  s.require_path      = "lib"
+  s.rubyforge_project = "freec"
+  s.has_rdoc          = false
+  s.extra_rdoc_files  = FileList["README*"].to_a
+  s.rdoc_options << '--line-numbers' << '--inline-source'
+  s.requirements << "daemons"
+  s.add_development_dependency 'rspec'
+end
+
+desc "Generate a gemspec file for GitHub"
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
+require 'spec/rake/spectask'
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+end

data/freec.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{freec}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jan Kubr"]
+  s.date = %q{2009-10-26}
+  s.description = %q{Layer between your Ruby voice app and Freeswitch.}
+  s.email = %q{hi@jankubr.com}
+  s.extra_rdoc_files = ["lib/call_variables.rb", "lib/freec.rb", "lib/listener.rb", "lib/freec_base.rb", "lib/freec_logger.rb", "lib/freeswitch_applications.rb", "lib/tools.rb", "README.rdoc"]
+  s.files = ["lib/call_variables.rb", "lib/freec.rb", "lib/listener.rb", "lib/freec_base.rb", "lib/freec_logger.rb", "lib/freeswitch_applications.rb", "lib/tools.rb", "Manifest", "Rakefile", "README.rdoc", "spec/event_parser_spec.rb", "spec/freec_base_spec.rb", "spec/freeswitch_applications_spec.rb", "spec/spec_helper.rb", "spec/data/event.rb", "spec/data/event_with_body.rb", "freec.gemspec"]
+  s.homepage = %q{http://github.com/jankubr/freec}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Freec", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{freec}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Layer between your Ruby voice app and Freeswitch.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<daemons>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<daemons>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<daemons>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end

data/lib/call_variables.rb

@@ -0,0 +1,21 @@
+module CallVariables
+
+  # Value of the variable_sip_from_user variable
+  # This is the callee username/number
+  def sip_from_user
+    call_vars[:variable_sip_from_user]
+  end
+
+  # Value of the variable_sip_to_user variable
+  # This is the called username/number  
+  def sip_to_user
+    call_vars[:variable_sip_to_user]    
+  end
+
+  # Value of the channel_destination_number variable
+  # This is the extension this call was routed to in Freeswitch
+  def channel_destination_number
+    call_vars[:channel_destination_number]    
+  end
+
+end

data/lib/freec.rb

@@ -0,0 +1,68 @@
+lib_dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+require "freec_base"
+require 'listener'
+
+require 'fileutils'
+require 'daemons/daemonize'
+include Daemonize
+
+def freec_app_file_name
+  $0.sub(/\.[^\.]*$/, '')  
+end
+
+def freec_app_class_name
+  freec_app_file_name.split('_').map{|w| w.capitalize}.join
+end
+
+def freec_app_log_dir
+  "#{ROOT}/log"
+end
+
+def create_freec_app_log_dir
+  FileUtils.mkdir_p(freec_app_log_dir)  
+end
+
+def freec_app_log_file
+  @@log_file ||= "#{freec_app_log_dir}/#{freec_app_file_name}.log"
+end
+
+def freec_app_pid_file
+  "#{freec_app_log_dir}/#{freec_app_file_name}.pid"
+end
+
+def load_freec_app_config
+  if File.exist?(freec_app_configuration_file)
+    @@config = YAML.load_file(freec_app_configuration_file)
+  else
+    @@config = {}
+  end
+  @@config['listen_port'] ||= '8084' 
+end
+
+def freec_app_configuration_file
+  "#{ROOT}/config/config.yml"
+end
+
+unless defined?(TEST)
+  at_exit do
+    ROOT = File.expand_path(File.dirname($0))
+    ENVIRONMENT = ARGV[0] == '-d' ? 'production' : 'development'
+    create_freec_app_log_dir
+    load_freec_app_config
+    if ARGV[0] == '-d'
+      puts 'Daemonizing...'
+      daemonize(freec_app_log_file)
+    end
+    open(freec_app_pid_file, "w") {|f| f.write(Process.pid) }
+
+    server = Listener.new('0.0.0.0', @@config['listen_port'].to_i, freec_app_class_name)
+    server.audit = true
+    server.start
+    puts "Listening on port #{@@config['listen_port']}"
+    loop do
+      break if server.stopped?
+      sleep(1)
+    end
+  end
+end

data/lib/freec_base.rb

@@ -0,0 +1,188 @@
+require 'gserver'
+require 'rubygems'
+require 'uri'
+
+require 'tools'
+require "freeswitch_applications"
+require "call_variables"
+
+class Freec
+  include FreeswitchApplications
+  include CallVariables
+  
+  attr_reader :call_vars, :event_body, :log
+  
+  def initialize(io, log) #:nodoc:
+    @call_vars ||= {}
+    @last_app_executed = 'initial_step'
+    @io = io    
+    @log = log
+  end
+        
+  def handle_call #:nodoc:
+    call_initialization    
+    loop do
+      subscribe_to_new_channel_events
+      if last_event_dtmf? && respond_to?(:on_dtmf)
+        callback(:on_dtmf, call_vars[:dtmf_digit])
+      elsif waiting_for_this_response? || execute_completed?
+        reset_wait_for if waiting_for_this_response?
+        reload_application_code
+        break if disconnect_notice? || !callback(:step)
+      end      
+      read_response
+      parse_response
+    end
+    callback(:on_hangup)
+    hangup unless @io.closed?
+    send_and_read('exit') unless @io.closed?
+  end
+    
+  def wait_for(key, value)
+    @waiting_for_key = key && key.to_sym
+    @waiting_for_value = value
+  end
+
+  def reset_wait_for
+    wait_for(nil, nil)
+    true 
+  end  
+    
+  def execute_completed?
+    channel_execute_complete? || channel_destroyed_after_bridge? || disconnect_notice?
+  end
+  
+private
+
+  def call_initialization
+    connect_to_freeswitch
+    subscribe_to_events
+  end
+
+  def channel_execute_complete?
+    return true if @last_app_executed == 'initial_step'
+    complete =  call_vars[:content_type] == 'text/event-plain' && 
+                call_vars[:event_name] == 'CHANNEL_EXECUTE_COMPLETE' &&
+                @last_app_executed == call_vars[:application]
+    @last_app_executed = nil if complete
+    complete
+  end
+  
+  def channel_destroyed_after_bridge?
+    call_vars[:application] == 'bridge' && call_vars[:event_name] == 'CHANNEL_DESTROY'
+  end
+  
+  def disconnect_notice?
+    call_vars[:content_type] == 'text/disconnect-notice'
+  end
+
+  def callback(callback_name, *args)
+    send(callback_name, *args) if respond_to?(callback_name)
+  rescue StandardError => e
+    log.error e.message
+    e.backtrace.each {|trace_line| log.error(trace_line)}    
+  end
+
+  def reload_application_code
+    return unless ENVIRONMENT == 'development'
+    load($0)
+    lib_dir = "#{ROOT}/lib"
+    return unless File.exist?(lib_dir)
+    Dir.open(lib_dir).each do |file|      
+      full_file_name = File.join(lib_dir, file)
+      next unless File.file?(full_file_name)
+      load(full_file_name)
+    end
+  end
+
+  def connect_to_freeswitch
+    send_and_read('connect')
+    parse_response
+  end
+  
+  def subscribe_to_events
+    send_and_read('events plain all')
+    parse_response    
+    send_and_read("filter Unique-ID #{@unique_id}") 
+    parse_response    
+  end
+  
+  def subscribe_to_new_channel_events
+    return unless call_vars[:event_name] == 'CHANNEL_BRIDGE'
+    send_and_read("filter Unique-ID #{call_vars[:other_leg_unique_id]}")
+  end
+      
+  def waiting_for_this_response?
+    @waiting_for_key && @waiting_for_value && call_vars[@waiting_for_key] == @waiting_for_value
+  end
+  
+  def last_event_dtmf?
+    call_vars[:content_type] == 'text/event-plain' && call_vars[:event_name] == 'DTMF'
+  end
+          
+  def send_data(data)
+    log.debug "Sending: #{data}"
+    @io.write("#{data}\n\n") unless disconnect_notice?
+  end
+  
+  def send_and_read(data)
+    send_data(data)
+    read_response
+  end
+  
+  def read_response
+    return if disconnect_notice?
+    read_response_info
+    read_event_header
+    read_event_body
+  end
+  
+  def read_response_info
+    @response = ''
+    begin
+      line = @io.gets.to_s
+      @response += line
+    end until @response[-2..-1] == "\n\n"    
+  end
+  
+  def read_event_header
+    header_length = @response.sub(/^Content-Length: ([0-9]+)$.*/m, '\1').to_i
+    return if header_length == 0
+    header = ''
+    begin
+      line = @io.gets.to_s
+      header += line.to_s
+    end until header[-2..-1] == "\n\n"
+    @response += header        
+  end
+  
+  def read_event_body
+    body_length = @response.sub(/^Content-Length.*^Content-Length: ([0-9]+)$.*/m, '\1').to_i
+    return if body_length == 0
+    body = ''
+    begin
+      line = @io.read(body_length).to_s
+      body += line.to_s
+    end until body.length == body_length
+    @response += body    
+  end
+        
+  def parse_response
+    hash = {}
+    if @response =~ /^Content-Length.*^Content-Length/m
+      @event_body = @response.sub(/.*\n\n.*\n\n(.*)/m, '\1').strip 
+    else
+      @event_body = nil
+    end
+    @response.split("\n").each do |line|
+      k,v = line.split(/\s*:\s*/)
+      hash[k.strip.gsub('-', '_').downcase.to_sym] = URI.unescape(v).strip if k && v
+    end    
+    call_vars.merge!(hash)
+    @unique_id ||= call_vars[:unique_id]
+    raise call_vars[:reply_text] if call_vars[:reply_text] =~ /^-ERR/
+    log.debug "\n\tUnique ID: #{call_vars[:unique_id]}\n\tContent-type: #{call_vars[:content_type]}\n\tEvent name: #{call_vars[:event_name]}"
+    @response = ''
+  end
+  
+end

data/lib/freec_logger.rb

@@ -0,0 +1,12 @@
+require 'logger'
+
+class FreecLogger < Logger
+    def format_message(severity, timestamp, progname, msg)  #:nodoc:
+      "#{timestamp.strftime("%Y-%m-%d %H:%M:%S")}.#{(timestamp.usec / 1000.0).round} #{severity} #{msg}\n"
+    end
+    
+    # Prints the message with twenty #'s before and after it.
+    def highlighted_info(message)
+      info("#{'#'*20} #{message} #{'#'*20}")
+    end
+end

data/lib/freeswitch_applications.rb

@@ -0,0 +1,101 @@
+module FreeswitchApplications
+  
+  # Answers the call.
+  def answer
+    execute_app('answer')
+  end
+
+  # Plays the file in file_name
+  # file_name is either an absolute path or path relative 
+  # to the sound_prefix variable set in Freeswitch's vars.xml configuration file.
+  def playback(file_name)
+    execute_app('playback', file_name)
+  end
+
+  # Spells the string
+  def spell(string)
+    execute_app('phrase', "spell,#{string}")
+  end
+  
+  # Says the given string
+  # Don't forget to set up your TTS engine and set variables tts_engine and tts_voice accordingly
+  # See e.g.: http://wiki.freeswitch.org/wiki/Mod_flite
+  def speak(string)
+    execute_app('speak', string)
+  end
+  
+  # Bridges the call to the given number or numbers (this param can be a number or an array of numbers).
+  def bridge(number_or_numbers, options = {})
+    number_or_numbers = number_or_numbers.join(",") if number_or_numbers.is_a?(Array)
+    execute_app("bridge", "#{number_or_numbers}")
+  end
+  
+  # Transfers the call to the given extension
+  def transfer(extension)
+    execute_app("transfer", "#{extension}")
+  end
+  
+  # Records the call to a file with the given file_name
+  # file_name is either an absolute path or path relative 
+  # to the sound_prefix variable set in Freeswitch's vars.xml configuration file.
+  #
+  # Options:
+  # * <tt>:time_limit_secs</tt> overrides the default timeout, which is 600 seconds
+  def record(file_name, options = {})
+    options = {:time_limit_secs => 600}.merge(options) #no reverse_merge, no fun :-)
+    execute_app("record", "#{file_name} #{options[:time_limit_secs]}")
+  end
+  
+  # Plays the file in file_name and reads input (key presses) from the user.
+  #
+  # Options:
+  # * <tt>:terminators</tt> option to set a different terminator or terminators (defaults to '#')
+  # * <tt>:variable</tt> to set the variable where the results is put (defaults to call_vars[:input])
+  # * <tt>:timeout</tt> to override the default timeout value (which is 10 seconds)
+  # * <tt>:min and :max</tt> options to override the default maximum and minimum of characters that will be read (both default to 1)
+  def read(file_name, options = {})
+    options[:terminators] = [options[:terminators]] if options[:terminators].is_a?(String)
+    options = {:timeout => 10, :variable => 'input', :min => 1, :max => 1, :terminators => ['#']}.merge(options)
+    execute_app("read", "#{options[:min]} #{options[:max]} #{file_name} #{options[:variable]} #{options[:timeout] * 1000} #{options[:terminators].join(',')}")
+  end
+  
+  # Starts recording the call in file in file_name
+  #
+  def start_recording(file_name)
+    execute_app('record_session', file_name)
+  end
+
+  # Stops recording the call in file in file_name
+  #  
+  def stop_recording(file_name)
+    execute_app('stop_record_session', file_name)
+  end
+  
+  # Sets a variable with the give name to the given value.
+  def set_variable(name, value)
+    execute_app('set', "#{name}=#{value}")
+  end
+
+  # Hangs up the call.
+  def hangup
+    execute_app('hangup')
+  end  
+  
+  # Executes an app using the sendmsg command of Freeswitch.
+  # Use this if there is no method for the application you want to run.
+  #
+  # Params:
+  # * <tt>app</tt> is the application name
+  # * <tt>pars</tt> is a string of arguments of the app
+  # * <tt>lock</tt> can be set to false so Freeswitch won't wait for this app to finish before running the next one
+  def execute_app(app, pars = '', lock = true, unique_id = nil)    
+    @last_app_executed = app
+    unique_id = @unique_id unless unique_id
+    cmd = "sendmsg #{unique_id}"
+    cmd << "\ncall-command: execute"
+    cmd << "\nexecute-app-name: #{app}"
+    cmd << "\nexecute-app-arg: #{pars}" unless pars.blank?
+    cmd << "\nevent-lock:#{lock}"
+    send_data cmd
+  end  
+end

data/lib/listener.rb

@@ -0,0 +1,34 @@
+require 'gserver'
+require 'freec_logger'
+
+class Listener < GServer  
+  def initialize(host, port, application_class_name) #:nodoc:
+    @application_class_name = application_class_name
+    @logger = FreecLogger.new(dev_or_test? ? STDOUT : @@log_file)
+    @logger.level = Logger::INFO unless dev_or_test?
+    super(port, host, (1.0/0.0))
+    self.audit = true
+    connect_to_database
+  end
+        
+  def serve(io) #:nodoc:
+    app = Kernel.const_get(@application_class_name).new(io, @logger)
+    app.handle_call
+  rescue StandardError => e
+    @logger.error e.message
+    e.backtrace.each {|trace_line| @logger.error(trace_line)}    
+  end
+
+private
+  
+  def connect_to_database
+    return unless @@config['database'] && @@config['database'][ENVIRONMENT]
+    require 'active_record'
+    ActiveRecord::Base.establish_connection(@@config['database'][ENVIRONMENT])
+  end  
+  
+  def dev_or_test?
+    ['development', 'test'].include?(ENVIRONMENT)
+  end
+  
+end

data/lib/tools.rb

@@ -0,0 +1,5 @@
+class Object
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+end

data/spec/data/event.rb

@@ -0,0 +1,56 @@
+unless defined?(EVENT)
+EVENT=<<STRING
+Content-Length: 1693
+Content-Type: text/event-plain
+
+Event-Name: CHANNEL_EXECUTE
+Core-UUID: 4a78c88d-38cc-4e35-92af-c155def76f9a
+FreeSWITCH-Hostname: air.local
+FreeSWITCH-IPv4: 10.0.1.2
+FreeSWITCH-IPv6: %3A%3A1
+Event-Date-Local: 2009-05-14%2019%3A29%3A09
+Event-Date-GMT: Thu,%2014%20May%202009%2017%3A29%3A09%20GMT
+Event-Date-Timestamp: 1242322149917313
+Event-Calling-File: switch_core_session.c
+Event-Calling-Function: switch_core_session_exec
+Event-Calling-Line-Number: 1460
+Channel-State: CS_EXECUTE
+Channel-State-Number: 4
+Channel-Name: sofia/internal/jan.kubr.gmail.com%4010.0.1.2
+Channel-Destination-Number: 886
+Unique-ID: f3c2d5ee-d064-4f55-9280-5be2a65867e8
+Call-Direction: inbound
+Presence-Call-Direction: inbound
+Answer-State: answered
+Channel-Read-Codec-Name: GSM
+Channel-Read-Codec-Rate: 8000
+Channel-Write-Codec-Name: GSM
+Channel-Write-Codec-Rate: 8000
+Caller-Username: jan.kubr.gmail.com
+Caller-Dialplan: XML
+Caller-Caller-ID-Name: Jan%20Local
+Caller-Caller-ID-Number: jan.kubr.gmail.com
+Caller-Network-Addr: 10.0.1.2
+Caller-Destination-Number: 0
+Caller-Unique-ID: f3c2d5ee-d064-4f55-9280-5be2a65867e8
+Caller-Source: mod_sofia
+Caller-Context: default
+Caller-Channel-Name: sofia/internal/jan.kubr.gmail.com%4010.0.1.2
+Caller-Profile-Index: 1
+Caller-Profile-Created-Time: 1242322142643329
+Caller-Channel-Created-Time: 1242322142643329
+Caller-Channel-Answered-Time: 1242322143798188
+Caller-Channel-Progress-Time: 0
+Caller-Channel-Progress-Media-Time: 1242322142657064
+Caller-Channel-Hangup-Time: 0
+Caller-Channel-Transfer-Time: 0
+Caller-Screen-Bit: true
+Caller-Privacy-Hide-Name: false
+Caller-Privacy-Hide-Number: false
+variable_sip_to_user: 886
+variable_sip_from_user: 1001
+Application: set
+Application-Data: continue_on_fail%3Dtrue
+
+STRING
+end

data/spec/data/event_with_body.rb

@@ -0,0 +1,25 @@
+unless defined?(EVENT_WITH_BODY)
+EVENT_WITH_BODY=<<STRING
+Content-Length: 460
+Content-Type: text/event-plain
+
+Event-Name: DETECTED_SPEECH
+Core-UUID: b61467b4-6d7c-4a6f-ba87-32ade7b79951
+FreeSWITCH-Hostname: air.local
+FreeSWITCH-IPv4: 10.0.1.2
+FreeSWITCH-IPv6: %3A%3A1
+Event-Date-Local: 2009-05-04%2020%3A40%3A48
+Event-Date-GMT: Mon,%2004%20May%202009%2018%3A40%3A48%20GMT
+Event-Date-Timestamp: 1241462448174337
+Event-Calling-File: switch_ivr_async.c
+Event-Calling-Function: speech_thread
+Event-Calling-Line-Number: 1878
+Speech-Type: detected-speech
+Content-Length: 132
+
+<interpretation grammar="battle" score="100">
+  <result name="match">FREESTYLE</result>
+  <input>FREESTYLE</input>
+</interpretation>
+STRING
+end

data/spec/event_parser_spec.rb

@@ -0,0 +1,56 @@
+require "#{File.dirname(__FILE__)}/spec_helper"
+
+describe Freec do
+  before do
+    io = stub(:io)
+    log = FreecLogger.new(STDOUT)
+    log.level = Logger::FATAL
+    @freec = Freec.new(io, log)
+  end
+  
+  describe "parses body-less event" do
+
+    before do
+      @freec.instance_variable_set(:@response, EVENT)
+      @freec.send :parse_response
+    end
+    
+    it "should read unique id from response" do
+      @freec.instance_variable_get(:@unique_id).should == 'f3c2d5ee-d064-4f55-9280-5be2a65867e8'
+    end
+    
+    it "should parse variables from response" do
+      @freec.call_vars[:call_direction].should == 'inbound'
+      @freec.call_vars[:caller_context].should == 'default'
+      @freec.call_vars[:application].should == 'set'
+    end    
+  
+    it "should make the value of the sip_from_user variable available as a method" do
+      @freec.sip_from_user.should == '1001'
+    end
+
+    it "should make the value of the sip_to_user variable available as a method" do
+      @freec.sip_to_user.should == '886'
+    end
+
+    it "should make the value of the channel_destination_number variable available as a method" do
+      @freec.channel_destination_number.should == '886'
+    end
+  end
+
+  describe "parses an event with a body" do
+    before do
+      @freec.instance_variable_set(:@response, EVENT_WITH_BODY)
+      @freec.send :parse_response
+    end
+      
+    it "should parse the variables from the event header" do
+      @freec.call_vars[:event_name].should == 'DETECTED_SPEECH'
+    end
+    
+    it "makes the body of the response available as a public method" do
+      @freec.event_body.should =~ /<\/interpretation>$/
+    end
+
+  end
+end

data/spec/freec_base_spec.rb

@@ -0,0 +1,176 @@
+require "#{File.dirname(__FILE__)}/spec_helper"
+
+module FreecSpecHelper
+  def event_parts(event=EVENT)
+    @parts = event.split("\n\n").map {|p| "#{p}\n\n"}  
+  end
+  
+  def initial_response
+    @initial_response ||= EVENT.split("\n\n")[1] + "\n\n"
+  end
+  
+end
+
+describe Freec do
+  include FreecSpecHelper
+
+  before do
+    @io = stub(:io)
+    log = FreecLogger.new(STDOUT)
+    log.level = Logger::FATAL
+    @freec = Freec.new(@io, log)
+  end
+
+  describe "call initialization" do
+  
+    it "sends 'connect' command to Freeswitch" do
+      @freec.should_receive(:send_data).with("connect")
+      @freec.should_receive(:send_data)
+      @freec.should_receive(:send_data)
+      @io.should_receive(:gets).exactly(3).and_return(initial_response)
+      @freec.send :call_initialization
+    end
+    
+    it "subscribes to events" do
+      @freec.should_receive(:send_data)
+      @freec.should_receive(:send_data).with('events plain all')
+      @freec.should_receive(:send_data).with('filter Unique-ID f3c2d5ee-d064-4f55-9280-5be2a65867e8')
+      @io.should_receive(:gets).exactly(3).and_return(initial_response)
+      @freec.send :call_initialization
+    end
+    
+  end
+  
+  describe "response reader" do
+  
+    it "reads the full body-less event" do
+      @io.should_receive(:gets).and_return(event_parts(EVENT)[0], event_parts(EVENT)[1])
+      @freec.send(:read_response)
+    end
+    
+    it "reads the full event with body" do
+      @io.should_receive(:gets).and_return(event_parts(EVENT_WITH_BODY)[0], 
+                                          event_parts(EVENT_WITH_BODY)[1])
+      @io.should_receive(:read).and_return(event_parts(EVENT_WITH_BODY)[2].strip.chomp)
+      @freec.send(:read_response)
+    end
+  
+  end
+  
+  describe "event recognition" do
+
+    it "should subscribe to events of other leg channel after bridge" do
+      bridge_event = EVENT.sub('CHANNEL_EXECUTE', 'CHANNEL_BRIDGE').sub('Caller-Profile-Index: 1', 'Other-Leg-Unique-ID: 6c75cb42-e72d-48bf-9ecf-d71bd4b60617')
+      @freec.instance_variable_set(:@response, bridge_event)
+      @freec.send(:parse_response)
+      @freec.should_receive(:send_and_read).with("filter Unique-ID 6c75cb42-e72d-48bf-9ecf-d71bd4b60617")
+      @freec.send(:subscribe_to_new_channel_events)
+    end
+    
+    it "should recognize last event was DTMF to call the on_dtmf callback" do
+      dtmf_event = EVENT.sub('CHANNEL_EXECUTE', 'DTMF')
+      @freec.instance_variable_set(:@response, dtmf_event)
+      @freec.send(:parse_response)
+      @freec.send(:last_event_dtmf?).should be_true
+    end
+      
+    it "should recognize an event as a non-DTMF one" do
+      @freec.instance_variable_set(:@response, EVENT)
+      @freec.send(:parse_response)
+      @freec.send(:last_event_dtmf?).should be_false
+    end
+      
+    it "should recognize that app execution has been completed for the last run app" do
+      @freec.instance_variable_set(:@last_app_executed, 'set')
+      set_executed_event = EVENT.sub('CHANNEL_EXECUTE', 'CHANNEL_EXECUTE_COMPLETE')
+      @freec.instance_variable_set(:@response, set_executed_event)
+      @freec.send(:parse_response)      
+    
+      @freec.send(:execute_completed?).should be_true
+      @freec.instance_variable_get(:@last_app_executed).should be_nil
+    end
+      
+    it "should recognize that app execution has been completed but not for the last run one" do
+      @freec.instance_variable_set(:@last_app_executed, 'different')
+      set_executed_event = EVENT.sub('CHANNEL_EXECUTE', 'CHANNEL_EXECUTE_COMPLETE')
+      @freec.instance_variable_set(:@response, set_executed_event)
+      @freec.send(:parse_response)      
+    
+      @freec.send(:execute_completed?).should be_false
+      @freec.instance_variable_get(:@last_app_executed).should == 'different'
+    end
+      
+    it "should hangup the call, send exit command to Freeswitch and disconnect from it when step callback returns nil" do
+      @freec.should_receive(:send_data).with("connect")
+      @freec.should_receive(:send_data).with("events plain all")      
+      @freec.should_receive(:send_data).with('filter Unique-ID f3c2d5ee-d064-4f55-9280-5be2a65867e8')
+      
+      @io.should_receive(:gets).and_return(initial_response, initial_response, initial_response, "bye\n\n")
+      @io.should_receive(:closed?).twice.and_return(false)
+      @freec.should_receive(:step).and_return(nil)
+      @freec.should_receive(:execute_app).with('hangup')
+      @freec.should_receive(:on_hangup)
+      @freec.should_receive(:send_data).with("exit")      
+      @freec.handle_call
+    end
+    
+    it "should exit when Freeswitch disconnects (e.g. caller hangs up) and neither call the step callback nor send any other data to Freeswitch" do
+      disconnect_event = EVENT.sub('text/event-plain', 'text/disconnect-notice')
+      @freec.should_receive(:send_data).with("connect")
+      @freec.should_receive(:send_data).with("events plain all")      
+      @freec.should_receive(:send_data).with('filter Unique-ID f3c2d5ee-d064-4f55-9280-5be2a65867e8')
+      @io.should_receive(:gets).and_return(initial_response, initial_response, event_parts(disconnect_event)[0], event_parts(disconnect_event)[1])
+      @io.should_receive(:closed?).twice.and_return(true)
+      @freec.should_receive(:step).never
+      @freec.should_receive(:on_hangup)
+      @freec.should_receive(:execute_app).never      
+      @freec.should_receive(:send_data).never
+      @freec.handle_call
+    end
+      
+  end
+  
+  describe "callback exception handling" do
+  
+    it "should catch and log any exception occurred in a callback" do
+      @freec.should_receive(:callback_name).and_raise(RuntimeError)
+      @freec.log.should_receive(:error).with('RuntimeError')
+      @freec.log.should_receive(:error).at_least(1).times #backtrace
+      lambda { @freec.send(:callback, :callback_name) }.should_not raise_error(Exception)
+    end
+  
+  end
+  
+  describe "custom waiting conditions" do
+    
+    # it "should return true from waiting_for_this_response? when the conditions for the response are met" do
+    #   @freec.wait_for(:content_type, 'command/reply')
+    #   @freec.instance_variable_set(:@response, EVENT)
+    #   @freec.send(:parse_response)
+    #   @freec.send(:waiting_for_this_response?).should be_true
+    # end
+    #   
+    # it "should return false from waiting_for_this_response? when the conditions for the response are not met" do
+    #   @freec.wait_for(:content_type, 'text/event-plain')
+    #   @freec.instance_variable_set(:@response, EVENT)
+    #   @freec.send(:parse_response)
+    #   @freec.send(:waiting_for_this_response?).should be_false
+    # end
+    #   
+    # it "should reset the waiting conditions after they have been met" do      
+    #   @freec.wait_for(:content_type, 'command/reply')
+    #   @freec.should_receive(:send_data).with("connect")
+    #   @freec.should_receive(:send_data).with("myevents")      
+    #   @io.should_receive(:gets).and_return(EVENT, EVENT, "bye\n\n")
+    #   @freec.instance_variable_set(:@last_app_executed, 'set')
+    #   @freec.should_receive(:step).and_return(nil)
+    #   @freec.should_receive(:execute_app).with('hangup')
+    #   @freec.should_receive(:on_hangup)
+    #   @freec.should_receive(:send_data).with("exit")      
+    #   @freec.handle_call
+    #   @freec.send(:waiting_for_this_response?).should be_nil
+    # end
+    #   
+  end
+
+end

data/spec/freeswitch_applications_spec.rb

@@ -0,0 +1,128 @@
+require "#{File.dirname(__FILE__)}/spec_helper"
+
+module FreeswitchApplicationsSpecHelper
+  def freeswitch_command(app, pars = nil)    
+    cmd = "sendmsg "
+    cmd += "\ncall-command: execute"
+    cmd += "\nexecute-app-name: #{app}"
+    cmd += "\nexecute-app-arg: #{pars}" unless pars.blank?
+    cmd += "\nevent-lock:true"
+    cmd
+  end
+end
+
+describe Freec do
+
+  before do
+    io = stub(:io)
+    log = FreecLogger.new(STDOUT)
+    log.level = Logger::FATAL
+    @freec = Freec.new(io, log)
+  end
+
+  describe "executes Freeswitch applications" do
+    include FreeswitchApplicationsSpecHelper
+
+    it "should set the last_app_executed variable to last run app" do
+      @freec.should_receive(:send_data).with(freeswitch_command('answer'))
+      @freec.answer
+      @freec.instance_variable_get(:@last_app_executed).should == 'answer'
+    end
+
+    it "should execute the answer app when called the answer method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('answer'))
+      @freec.answer
+    end
+  
+    it "should execute the playback app when called the playback method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('playback', 'sounds/file.wav'))
+      @freec.playback('sounds/file.wav')
+    end
+
+    it "should execute the phrase app with spell option when called the spell method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('phrase', 'spell,abcd'))
+      @freec.spell('abcd')
+    end
+
+    it "should execute the speak app when called the speak method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('speak', 'hello'))
+      @freec.speak('hello')
+    end
+
+    it "should execute the bridge app when called the bridge method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('bridge', 'user/brian@10.0.1.2'))
+      @freec.bridge('user/brian@10.0.1.2')
+    end
+
+    it "should execute the transfer app when called the transfer method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('transfer', '1000'))
+      @freec.transfer('1000')
+    end
+
+    it "should pass all numbers passed to the bridge method as params of the bridge separated by comma (thus numbers are called simultaneously)" do
+      @freec.should_receive(:send_data).with(freeswitch_command('bridge', 'user/brian@10.0.1.2,user/karl@10.0.1.2'))
+      @freec.bridge(['user/brian@10.0.1.2', 'user/karl@10.0.1.2'])
+    end
+
+    it "should execute the record app when called the record method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('record', 'recordings/file.mp3 600'))
+      @freec.record('recordings/file.mp3')
+    end
+
+    it "should set the time_limit_secs option send to the record method as the max length of the recording" do
+      @freec.should_receive(:send_data).with(freeswitch_command('record', 'recordings/file.mp3 120'))
+      @freec.record('recordings/file.mp3', :time_limit_secs => 120)
+    end
+
+    it "should execute the read app when called the input method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '1 1 sounds/file.mp3 input 10000 #'))
+      @freec.read('sounds/file.mp3')
+    end
+
+    it "should allow to pass the minimum and maximum digits to be read" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '2 5 sounds/file.mp3 input 10000 #'))
+      @freec.read('sounds/file.mp3', :min => 2, :max => 5)
+    end
+
+    it "should allow to pass the timeout in seconds before the read apps before it times out" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '1 1 sounds/file.mp3 input 5000 #'))
+      @freec.read('sounds/file.mp3', :timeout => 5)
+    end
+
+    it "should allow to pass the terminator for the read app" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '1 1 sounds/file.mp3 input 10000 *'))
+      @freec.read('sounds/file.mp3', :terminators => '*')
+    end
+
+    it "should allow to pass the terminators as an array for the read app" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '1 1 sounds/file.mp3 input 10000 #,*'))
+      @freec.read('sounds/file.mp3', :terminators => ['#', '*'])
+    end
+
+    it "should allow to specify the variable name the input is read by the read app" do
+      @freec.should_receive(:send_data).with(freeswitch_command('read', '1 1 sounds/file.mp3 name 10000 #'))
+      @freec.read('sounds/file.mp3', :variable => 'name')
+    end
+
+    it "should execute the record_session app when called the start_recording method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('record_session', 'file.wav'))
+      @freec.start_recording('file.wav')
+    end
+
+    it "should execute the stop_record_session app when called the start_recording method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('stop_record_session', 'file.wav'))
+      @freec.stop_recording('file.wav')
+    end
+  
+    it "should call the set app to set a variable" do
+      @freec.should_receive(:send_data).with(freeswitch_command('set', 'name=value'))
+      @freec.set_variable('name', 'value')
+    end
+  
+    it "should call the hangup app when caled the hangup method" do
+      @freec.should_receive(:send_data).with(freeswitch_command('hangup'))
+      @freec.hangup
+    end
+    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'spec'
+
+$:.unshift(File.join(File.dirname(__FILE__), "..", 'lib')).unshift(File.dirname(__FILE__)).
+  unshift(File.join(File.dirname(__FILE__), 'data'))
+ROOT = File.join(File.dirname(__FILE__), '..') unless defined?(ROOT)
+@@config = ''
+ENVIRONMENT = 'test' unless defined?(ENVIRONMENT)
+TEST = true unless defined?(TEST)
+require 'freec'
+require 'event'
+require 'event_with_body'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: freec
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Jan Kubr
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-26 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: daemons
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Layer between your Ruby voice app and Freeswitch.
+email: hi@jankubr.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/call_variables.rb
+- lib/freec.rb
+- lib/listener.rb
+- lib/freec_base.rb
+- lib/freec_logger.rb
+- lib/freeswitch_applications.rb
+- lib/tools.rb
+- README.rdoc
+files: 
+- lib/call_variables.rb
+- lib/freec.rb
+- lib/listener.rb
+- lib/freec_base.rb
+- lib/freec_logger.rb
+- lib/freeswitch_applications.rb
+- lib/tools.rb
+- Manifest
+- Rakefile
+- README.rdoc
+- spec/event_parser_spec.rb
+- spec/freec_base_spec.rb
+- spec/freeswitch_applications_spec.rb
+- spec/spec_helper.rb
+- spec/data/event.rb
+- spec/data/event_with_body.rb
+- freec.gemspec
+has_rdoc: true
+homepage: http://github.com/jankubr/freec
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Freec
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: freec
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Layer between your Ruby voice app and Freeswitch.
+test_files: []
+