larynx 0.1.0

data/lib/larynx/command.rb

@@ -0,0 +1,73 @@
+module Larynx
+  class Command
+    include Callbacks
+    attr_reader :command
+
+    define_callback :before, :after
+
+    def initialize(command, params=nil, &block)
+      @command, @params, @callbacks = command, params, {}
+      after(&block) if block_given?
+    end
+
+    def to_s
+      @command
+    end
+
+    def name
+      @command
+    end
+
+    def interruptable?
+      false
+    end
+  end
+
+  class CallCommand < Command
+    def name
+      "#{@command}#{" #{@params}" if @params}"
+    end
+
+    def to_s
+      cmd =  "#{@command}"
+      cmd << " #{@params}" if @params
+      cmd << "\n\n"
+    end
+  end
+
+  class ApiCommand < Command
+    def name
+      "#{@command}#{" #{@params}" if @params}"
+    end
+
+    def to_s
+      cmd =  "api #{@command}"
+      cmd << " #{@params}" if @params
+      cmd << "\n\n"
+    end
+  end
+
+  class AppCommand < Command
+    def initialize(command, params=nil, options={}, &block)
+      super command, params, &block
+      @options = options.reverse_merge(:bargein => true)
+    end
+
+    def name
+      "#{@command}#{" '#{@params}'" if @params}"
+    end
+
+    def to_s
+      cmd =  "sendmsg\n"
+      cmd << "call-command: execute\n"
+      cmd << "execute-app-name: #{@command}\n"
+      cmd << "execute-app-arg: #{@params}\n" if @params
+      cmd << "event-lock: #{@options[:lock]}\n" if @options[:lock]
+      cmd << "\n"
+    end
+
+    def interruptable?
+      @options[:bargein]
+    end
+  end
+end

data/lib/larynx/commands.rb

@@ -0,0 +1,88 @@
+module Larynx
+  module Commands
+
+    def connect(&block)
+      execute CallCommand.new('connect', &block)
+    end
+
+    def myevents(&block)
+      execute CallCommand.new('myevents', &block)
+    end
+
+    def filter(type, &block)
+      execute CallCommand.new('filter', type, &block)
+    end
+
+    def linger(&block)
+      execute CallCommand.new('linger', &block)
+    end
+
+    def answer(&block)
+      execute AppCommand.new('answer', &block)
+    end
+
+    def hangup(&block)
+      execute AppCommand.new('hangup', &block)
+    end
+
+    def playback(data, options={}, &block)
+      execute AppCommand.new('playback', data, options, &block)
+    end
+    alias_method :play, :playback
+
+    def speak(data, options={}, &block)
+      execute AppCommand.new('speak', data, options, &block)
+    end
+
+    def phrase(data, options={}, &block)
+      execute AppCommand.new('phrase', data, options, &block)
+    end
+
+
+    # Executes read command with some default values.
+    # Allows length option which expands into minimum and maximum length values. Length can be a range.
+    # Passes user input into callback block.
+    #
+    # Defaults:
+    #    timeout:  5000 or 5 seconds
+    #    termchar: #
+    #
+    # Example:
+    #
+    #   read(:minimum => 1, :maximum => 2, :sound_file => 'en/us/callie/conference/8000/conf-pin.wav') {|input|
+    #     speak "You entered #{input}"
+    #   }
+    #
+    # Or
+    #
+    #   read(:length => 1..2, :sound_file => 'en/us/callie/conference/8000/conf-pin.wav') {|input|
+    #     speak "You entered #{input}"
+    #   }
+    #
+    def read(options={}, &block)
+      options.reverse_merge!(:timeout => 5000, :var_name => 'read_result', :termchar => '#')
+      options[:bargein] = false
+
+      if length = options.delete(:length)
+        values = length.is_a?(Range) ? [length.first, length.last] : [length, length]
+        options.merge!(:minimum => values[0], :maximum => values[1])
+      end
+
+      order = [:minimum, :maximum, :sound_file, :var_name, :timeout, :termchar]
+      data  = order.inject('') {|data, key| data += " #{options[key]}"; data }.strip
+
+      execute AppCommand.new('read', data, options).after {
+        block.call(response.body[:variable_read_result])
+      }
+    end
+
+    def prompt(options={}, &block)
+      execute Prompt.new(self, options, &block).command
+    end
+
+    def break!
+      execute AppCommand.new('break'), true
+    end
+
+  end
+end

data/lib/larynx/fields.rb

@@ -0,0 +1,143 @@
+module Larynx
+  class NoPromptDefined < StandardError; end
+
+  module Fields
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      attr_accessor :fields
+
+      def field(name, options={}, &block)
+        @fields ||= []
+        @fields << Field.new(name, options, &block)
+        attr_accessor name
+      end
+
+    end
+
+    module InstanceMethods
+
+      def next_field(field_name=nil)
+        @current_field ||= 0
+        @current_field = index_of_field(field_name) if field_name
+        if field = self.class.fields[@current_field]
+          field.run(self)
+          @current_field += 1
+          field
+        end
+      end
+
+      def index_of_field(name)
+        field = self.class.fields.find {|f| f.name == name }
+        self.class.fields.index(field)
+      end
+
+    end
+
+    class Field
+      include Callbacks
+
+      attr_reader :name
+      define_callback :setup, :validate, :invalid, :success, :failure
+
+      def initialize(name, options, &block)
+        @name, @callbacks = name, {}
+        @options = options.reverse_merge(:attempts => 3)
+        @prompt_queue = []
+
+        instance_eval(&block)
+        raise(Larynx::NoPromptDefined, 'A field requires a prompt to be defined') if @prompt_queue.empty?
+      end
+
+      def prompt(options)
+        add_prompt(options)
+      end
+
+      def reprompt(options)
+        raise 'A reprompt can only be used after a prompt' if @prompt_queue.empty?
+        add_prompt(options)
+      end
+
+      def add_prompt(options)
+        repeats = options.delete(:repeats) || 1
+        options.merge!(@options.slice(:length, :min_length, :max_length))
+        @prompt_queue += ([options] * repeats)
+      end
+
+      def current_prompt
+        options = (@prompt_queue[@attempt-1] || @prompt_queue.last).dup
+        method  = ([:play, :speak, :phrase] & options.keys).first
+        message = options[method].is_a?(Symbol) ? @app.send(options[method]) : options[method]
+        options[method] = message
+
+        Prompt.new(call, options) {|input|
+          set_instance_variables(input)
+          evaluate_input
+        }
+      end
+
+      def execute_prompt
+        call.execute current_prompt.command
+      end
+
+      def increment_attempts
+        @attempt += 1
+      end
+
+      def fire_callback(callback)
+        if block = @callbacks[callback]
+          @app.instance_eval(&block)
+        else
+          true
+        end
+      end
+
+      def valid?
+        @value.size >= minimum_length && fire_callback(:validate)
+      end
+
+      def evaluate_input
+        if valid?
+          fire_callback(:success)
+        else
+          fire_callback(:invalid)
+          if @attempt < @options[:attempts]
+            increment_attempts
+            execute_prompt
+          else
+            fire_callback(:failure)
+          end
+        end
+      end
+
+      def set_instance_variables(input)
+        @value = input
+        @app.send("#{@name}=", input)
+      end
+
+      def maximum_length
+        @options[:max_length] || @options[:length]
+      end
+
+      def minimum_length
+        @options[:min_length] || @options[:length] || 1
+      end
+
+      def run(app)
+        @app = app
+        @attempt = 1
+        fire_callback(:setup)
+        execute_prompt
+      end
+
+      def call
+        @app.call
+      end
+    end
+
+  end
+end

data/lib/larynx/form.rb

@@ -0,0 +1,19 @@
+module Larynx
+  class Form < Application
+    include Fields
+
+    def self.setup(&block)
+      @@setup = block
+    end
+
+    def run
+      instance_eval &@@setup if @@setup
+      next_field
+    end
+
+    def restart_form
+      @current_field = 0
+      run
+    end
+  end
+end

data/lib/larynx/logger.rb

@@ -0,0 +1,8 @@
+module Larynx
+  class Logger < ::Logger
+    def format_message(severity, timestamp, progname, msg)
+      time = timestamp.strftime("%Y-%m-%dT%H:%M:%S.") << "%06d" % timestamp.usec
+      "[%s] %5s: %s\n" % [time, severity, msg]
+    end
+  end
+end

data/lib/larynx/observable.rb

@@ -0,0 +1,35 @@
+module Larynx
+  module Observable
+
+    def add_observer(object)
+      @observers ||= []
+      @observers << object
+    end
+
+    def remove_observer(object)
+      @observers && @observers.delete(object)
+    end
+
+    def clear_observers!
+      @observers = []
+    end
+
+    # Like an observer stack which only notifies top observer
+    def notify_current_observer(event, data=nil)
+      return unless @observers
+      obs = @observers.last
+      if obs.respond_to?(event)
+        data ? obs.send(event, data) : obs.send(event)
+      end
+    end
+
+    def notify_observers(event, data=nil)
+      return unless @observers
+      @observers.each do |obs|
+        next unless obs.respond_to?(event)
+        data ? obs.send(event, data) : obs.send(event)
+      end
+    end
+
+  end
+end

data/lib/larynx/prompt.rb

@@ -0,0 +1,88 @@
+module Larynx
+  class NoPromptCommandValue < StandardError; end
+
+	# The prompt class neatly wraps up a convention where you prompt for input of
+	# certain length. The prompt waits until the required input length is reached,
+	# the user presses the terminator button or the time runs out. Think of the
+	# play_and_get_digits command except it works for speak as well. It also
+	# provides a bargein option to allow or prevent the user from interrupting
+	# the speech or playback.
+	#
+	# Pass a block to the method as a callback which receives input as an argument.
+	#
+  class Prompt
+    attr_reader :call
+
+    def initialize(call, options, &block)
+      @call, @options, @block = call, options, block
+      @options.reverse_merge!(:bargein => true, :timeout => 10, :interdigit_timeout => 3, :termchar => '#')
+      raise NoPromptCommandValue, "No output command value supplied. Use one of playback, speak or phrase keys." if command_name.blank?
+    end
+
+    def command
+      @command ||= AppCommand.new(command_name, message, :bargein => @options[:bargein]).
+        before { call.clear_input }.
+        after  {
+          if prompt_finished?
+            finalise
+          else
+            call.add_observer self
+            add_digit_timer
+            add_input_timer
+          end
+        }
+    end
+
+    def input
+      (call.input.last == termchar ? call.input[0..-2] : call.input).join
+    end
+
+    def prompt_finished?
+      call.input.last == termchar || call.input.size == maximum_length
+    end
+
+    def termchar
+      @options[:termchar]
+    end
+
+    def maximum_length
+      @options[:max_length] || @options[:length]
+    end
+
+    def command_name
+      ([:play, :speak, :phrase] & @options.keys).first.to_s
+    end
+
+    def message
+      @options[command_name.to_sym]
+    end
+
+    def finalise
+      call.remove_observer self
+      @block.call(input)
+    end
+
+    def dtmf_received(digit)
+      if prompt_finished?
+        call.stop_timer(:input)
+        call.cancel_timer(:digit)
+      else
+        call.restart_timer(:digit)
+      end
+    end
+
+    def add_digit_timer
+      call.timer(:digit, @options[:interdigit_timeout]) {
+        call.cancel_timer :input
+        finalise
+      }
+    end
+
+    def add_input_timer
+      call.timer(:input, @options[:timeout]) {
+        call.cancel_timer :digit
+        finalise
+      }
+    end
+  end
+end

data/lib/larynx/response.rb

@@ -0,0 +1,57 @@
+module Larynx
+  class Response
+    attr_reader :header, :body
+
+    def initialize(header, body)
+      @header = CallHandler.headers_2_hash(header)
+      if body
+        @body = body.match(/:/) ? CallHandler.headers_2_hash(body) : body
+        @body.each {|k,v| v.chomp! if v.is_a?(String)}
+      end
+    end
+
+    def reply?
+      @header[:content_type] == 'command/reply'
+    end
+
+    def event?
+      @header[:content_type] == 'text/event-plain'
+    end
+
+    def ok?
+      @header[:reply_text] =~ /\+OK/
+    end
+
+    def error?
+      @header[:reply_text] =~ /ERR/
+    end
+
+    def executing?
+      event_name == 'CHANNEL_EXECUTE'
+    end
+
+    def executed?
+      event_name == 'CHANNEL_EXECUTE_COMPLETE'
+    end
+
+    def command_name
+      @body[:application] if @body
+    end
+
+    def event_name
+      @body[:event_name] if @body
+    end
+
+    def dtmf?
+      @body[:event_name] == 'DTMF' if @body
+    end
+
+    def speech?
+      @body[:event_name] == 'DETECTED_SPEECH' if @body
+    end
+
+    def disconnect?
+      @header[:content_type] == 'text/disconnect-notice'
+    end
+  end
+end

data/lib/larynx/restartable_timer.rb

@@ -0,0 +1,26 @@
+module Larynx
+  # Adds restart to EM timer class. Implementation influenced by EM::PeriodicTimer class
+  # so hopefully it should not cause any issues.
+  class RestartableTimer < EM::Timer
+    def initialize(interval, callback=nil, &block)
+      @interval = interval
+      @code = callback || block
+      schedule
+    end
+
+    # Restart the timer
+    def restart
+      cancel
+      schedule
+    end
+
+    def schedule
+      @signature = EM::add_timer(@interval, method(:fire))
+    end
+
+    def fire
+      @code.call
+    end
+
+  end
+end

data/lib/larynx/session.rb

@@ -0,0 +1,20 @@
+module Larynx
+  class Session
+    attr_reader :variables
+
+    def initialize(data)
+      @variables = data
+    end
+
+    def method_missing(method, *args, &block)
+      if @variables.has_key?(method.to_sym)
+        @variables[method.to_sym]
+      end
+    end
+
+    def [](key)
+      @variables[key]
+    end
+
+  end
+end

data/lib/larynx/version.rb

@@ -0,0 +1,3 @@
+module Larynx
+  VERSION = '0.1.0'
+end

data/lib/larynx.rb

@@ -0,0 +1,109 @@
+require 'rubygems'
+require 'eventmachine'
+require 'active_support'
+require 'logger'
+require 'daemons/daemonize'
+
+require 'larynx/version'
+require 'larynx/logger'
+require 'larynx/observable'
+require 'larynx/callbacks'
+require 'larynx/session'
+require 'larynx/response'
+require 'larynx/command'
+require 'larynx/commands'
+require 'larynx/prompt'
+require 'larynx/application'
+require 'larynx/fields'
+require 'larynx/form'
+require 'larynx/restartable_timer'
+require 'larynx/call_handler'
+
+module Larynx
+  class << self
+    include Callbacks
+
+    define_callback :connect, :answer, :hungup
+
+    def parse_options(args=ARGV)
+      @options = {
+        :ip       => "0.0.0.0",
+        :port     => 8084,
+        :pid_file => './larynx.pid',
+        :log_file => './larynx.log'
+      }
+      opts = OptionParser.new
+      opts.banner = "Usage: larynx [options]"
+      opts.separator ''
+      opts.separator "Larynx is a tool to develop FreeSWITCH IVR applications in Ruby."
+      opts.on('-i', '--ip IP',         'Listen for connections on this IP') {|ip| @options[:ip] = ip }
+      opts.on('-p', '--port PORT',     'Listen on this port', Integer)      {|port| @options[:port] = port }
+      opts.on('-d', '--daemonize',     'Run as daemon')                     { @options[:daemonize] = true }
+      opts.on('-l', '--log-file FILE', 'Defaults to /app/root/larynx.log')  {|log| @options[:log_file] = log }
+      opts.on(      '--pid-file FILE', 'Defaults to /app/root/larynx.pid')  {|pid| @options[:pid_file] = pid }
+      opts.on('-h', '--help',          'This is it')                        { $stderr.puts opts; exit 0 }
+      opts.on('-v', '--version')                                            { $stderr.puts "Larynx version #{Larynx::VERSION}"; exit 0 }
+      opts.parse!(args)
+    end
+
+    def setup_logger
+      logger = Larynx::Logger.new(@options[:log_file])
+      logger.level = Logger::INFO
+      Object.const_set "LARYNX_LOGGER", logger
+    end
+
+    def graceful_exit
+      LARYNX_LOGGER.info "Shutting down Larynx"
+      EM.stop_server @em_signature
+      @em_signature = nil
+      remove_pid_file if @options[:daemonize]
+      exit 130
+    end
+
+    def daemonize
+      Daemonize.daemonize
+      Dir.chdir LARYNX_ROOT
+      File.open(@options[:pid_file], 'w+') {|f| f.write("#{Process.pid}\n") }
+    end
+
+    def remove_pid_file
+      File.delete @options[:pid_file]
+    end
+
+    def trap_signals
+      trap('TERM') { graceful_exit }
+      trap('INT')  { graceful_exit }
+    end
+
+    def setup_app
+      if ARGV[0].nil?
+        $stderr.puts "You must specify an application file"
+        exit -1
+      end
+      Object.const_set "LARYNX_ROOT", File.expand_path(File.dirname(ARGV[0]))
+      require File.expand_path(ARGV[0])
+    end
+
+    def start_server
+      LARYNX_LOGGER.info "Larynx starting up on #{@options[:ip]}:#{@options[:port]}"
+      EM::run {
+        @em_signature = EM::start_server @options[:ip], @options[:port], Larynx::CallHandler
+      }
+    end
+
+    def run
+      parse_options(ARGV)
+      setup_app
+      daemonize if @options[:daemonize]
+      setup_logger
+      trap_signals
+      start_server
+    end
+
+    def running?
+      !@em_signature.nil?
+    end
+  end
+end
+
+Larynx.run unless defined?(TEST)