colloquy 1.0.0

data/lib/colloquy/response.rb

@@ -0,0 +1,4 @@
+
+class Colloquy::Response < String
+  attr_accessor :flow_state
+end

data/lib/colloquy/runner.rb

@@ -0,0 +1,93 @@
+require 'goliath/api'
+require 'goliath/runner'
+
+require 'goliath/rack/default_response_format'
+require 'goliath/rack/heartbeat'
+require 'goliath/rack/params'
+require 'goliath/rack/render'
+require 'goliath/rack/default_mime_type'
+require 'goliath/rack/tracer'
+require 'goliath/rack/formatters/json'
+require 'goliath/rack/formatters/html'
+require 'goliath/rack/formatters/xml'
+require 'goliath/rack/jsonp'
+
+require 'goliath/rack/validation/request_method'
+require 'goliath/rack/validation/required_param'
+require 'goliath/rack/validation/required_value'
+require 'goliath/rack/validation/numeric_range'
+require 'goliath/rack/validation/default_params'
+require 'goliath/rack/validation/boolean_value'
+
+class Colloquy::Runner
+  class << self
+    # Much of this is borrowed verbatim from Goliath internals so we 
+    # can use our own class structure
+    def run!(argv)
+      options = {}
+      goliath_argv = []
+
+      option_parser = OptionParser.new do |opt|
+        opt.banner = 'Usage: colloquy [options] /path/to/flow/root'
+        
+        opt.on('-a', '--address HOST', 'Hostname or IP address to bind to') do |host|
+          goliath_argv << '-a' << host
+        end
+        
+        opt.on('-p', '---port PORT', 'Port to run the server on') do |port|
+          goliath_argv << '-p' << port
+        end
+        
+        opt.on('-e', '---environment ENV', 'Rack environment to run the renderer') do |env|
+          goliath_argv << '-e' << env
+          options[:environment] = env
+        end
+        
+        opt.on('-P', '--pidfile PATH_TO_FILE', 'Location to write the PID file to') do |pid_file|
+          goliath_argv << '-P' << pid_file
+        end
+        
+        opt.on('-d', '--daemonize', 'Daemonize the server') do
+          goliath_argv << '-d'
+        end
+        
+        opt.on('-v', '--verbose', 'Turn on debug logging') do
+          goliath_argv << '-v'
+          options[:verbose] = true
+        end
+        
+        opt.on('-s', '--simulator', 'Run the flow simulator instead') do
+          options[:interactive] = true
+        end
+        
+        opt.on( '-h', '--help', 'Display this screen' ) do
+          puts opt
+          exit!
+        end
+      end
+      
+      option_parser.parse!(argv)
+      
+      path_root = argv.pop
+      unless path_root
+        puts 'You have to provide a flow root directory. See colloquy --help'
+        exit!
+      end
+      
+      goliath_argv << '-l' << Pathname.new(path_root).realpath.join('log', 'server.log').to_s
+      
+      if options[:interactive]
+        simulator = Colloquy::Simulator.new(path_root: path_root, verbose: options[:verbose])
+        simulator.run
+      else      
+        klass = Colloquy::Server
+        api = klass.new(path_root: path_root, verbose: options[:verbose])
+        runner = Goliath::Runner.new(goliath_argv, api)
+
+        runner.app = Goliath::Rack::Builder.build(klass, api)
+        runner.load_plugins(klass.plugins)
+        runner.run
+      end
+    end
+  end
+end

data/lib/colloquy/server.rb

@@ -0,0 +1,157 @@
+require 'goliath/api'
+require 'goliath/runner'
+require 'goliath/rack/params'
+
+require 'em-synchrony'
+require 'em-synchrony/em-http'
+require 'yajl'
+
+class Colloquy::Server < Goliath::API
+  use Goliath::Rack::Params   # parse and merge query and body parameters
+
+  # Create an instance of Colloquy::Renderer with given options
+  # and set's it up
+  # @param options [Hash] The options hash.
+  def initialize(options = {})
+    @renderer = Colloquy::Renderer.new(options)
+    @renderer.prepare!
+  end
+
+  # This methods overrides #response of Goliath::API.
+  # So this is where parameters are validated and fed to an instance of Renderer.
+  # This methods returns response array with a http 200 status and body on successful execution.
+  #
+  # It validates the incoming request by checking presence of flow, msisdn and session_id. It sanitizes
+  # the parameters and obtains a hash containing flow, msisdn, session_id and input. Any exception raised
+  # at this point is rescued and a default error message is stored in response.
+  #
+  # After validation params are passed on the #apply method of instance of Renderer which was created and
+  # configured in Server constructor.
+  #
+  # @param [Goliath::Env] env The request environment.
+  # @return [Array] Array contains [Status code, Headers Hash, Body]
+  def response(env)
+    response = Colloquy::Response.new
+
+    begin
+      parameters = {}
+      parameters = validate_request(env)
+      parameters = sanitize_parameters(parameters)
+      logger.debug "REQUEST flow: #{parameters[:flow_name]}, msisdn: #{parameters[:msisdn]}, \
+        session_id: #{parameters[:session_id]}, input: #{parameters[:input]}, other: #{parameters[:params].inspect}"
+    rescue Exception => e
+      logger.error "Exception #{e.inspect} when trying to validate request flow: #{parameters[:flow_name]}, \
+        msisdn: #{parameters[:msisdn]}, session_id: #{parameters[:session_id]}, input: #{parameters[:input]}"
+      logger.debug "#{e.backtrace.inspect}"
+      logger.info 'Responding with default error message'
+
+      response = Colloquy::Response.new(Colloquy::Renderer::DEFAULT_ERROR_MESSAGE)
+      response.flow_state = :notify
+    end
+
+    response = @renderer.apply(parameters[:flow_name], parameters[:msisdn], parameters[:session_id], parameters[:input], parameters[:params]) if response.empty?
+
+    body = case parameters[:params][:accept]
+           when 'text/plain'
+             response.to_s
+           else
+             Yajl.dump({ response: response, flow_state: response.flow_state })
+           end
+
+    [200, {}, body]
+  end
+
+  private
+  def logger
+    @renderer.logger
+  end
+
+  # Validate request and return parameters
+  # @param [Goliath::Env] env The request environment
+  # @return [Hash] parameters The extracted parameters
+  def validate_request(env)
+    parameters = extract_request_parameters
+
+    validate_flow_presence!(parameters)
+    validate_msisdn!(parameters)
+    validate_session_id!(parameters)
+
+    parameters
+  end
+
+  # Create a hash with all request parameters combined
+  # @return [Hash] The request parameters
+  def extract_request_parameters
+    flow_name = env['REQUEST_PATH'][1..-1].to_s
+
+    # Use dup to preserve original env.
+    params = env['params'].dup.to_options
+    msisdn = params.delete(:msisdn).to_s
+    session_id = params.delete(:session_id).to_s
+    input = params.delete(:input).to_s
+
+    {
+        flow_name: flow_name,
+        params: params,
+        msisdn: msisdn,
+        session_id: session_id,
+        input: input
+    }
+  end
+
+  # Check if required flow is present. Raise FlowNotFound exception if not
+  # @param [Hash] parameters Extracted request parameters
+  # @return [nil]
+  # @raise [Colloquy::FlowNotFound]
+  #   if flow is not present
+  def validate_flow_presence!(parameters)
+    unless @renderer.flow_exists?(parameters[:flow_name])
+      raise Colloquy::FlowNotFound, "Flow not found: #{parameters[:flow_name]}"
+    end
+  end
+
+  # Checks whether msisdn is present, raises MSISDNParameterEmpty if not
+  # @param [Hash] parameters The paramters hash
+  # @return [nil]
+  # @raise [Colloquy::MSISDNParameterEmpty]
+  #   if msisdn parameter not present
+  def validate_msisdn!(parameters)
+    if parameters[:msisdn] == ''
+      raise Colloquy::MSISDNParameterEmpty, 'The msisdn parameter should not be empty.'
+    end
+  end
+
+  # Checks whether session_id is present
+  # @param [Hash] parameters The parameters hash
+  # @return [nil]
+  # @raise [Colloquy::SessionIDParameterEmpty]
+  #   if session_id not present
+  def validate_session_id!(parameters)
+    if parameters[:session_id] == ''
+      raise Colloquy::SessionIDParameterEmpty, 'The session_id parameter should not be empty.'
+    end
+  end
+
+  # Clean parameter values(exact type, size etc)
+  # @param [Hash] parameters The Parameters hash
+  # @return [Hash] Parameters Sanitized parameters hash
+  def sanitize_parameters(parameters)
+    flow_name = parameters[:flow_name].to_sym
+    msisdn = parameters[:msisdn].to_i.to_s
+    session_id = parameters[:session_id].to_s[0..20]
+    input = parameters[:input].to_s[0..160]
+
+    #remove default proc so that the hash can be serialized using Marshal
+    params = parameters[:params].tap do |p|
+      p.default = nil
+    end
+
+    {
+        flow_name: flow_name,
+        params: params,
+        msisdn: msisdn,
+        session_id: session_id,
+        input: input
+    }
+  end
+end

data/lib/colloquy/session_store.rb

@@ -0,0 +1,46 @@
+class Colloquy::SessionStore
+  KEY_PREFIX = 'ussd_renderer:'
+
+  class << self
+    # Returns a Memory store object according to the type of memory.
+    # @param [Symbol, Hash], Type and Options
+    # @return [Colloquy::SessionStore::Memory Colloquy::SessionStore::Redis]
+    def haystack(type = :memory, options = {})
+      case type.to_sym
+      when :memory
+        require_relative 'session_store/memory'
+
+        Colloquy::SessionStore::Memory.new(options)
+      else :redis
+        require_relative 'session_store/redis'
+        
+        Colloquy::SessionStore::Redis.new(options)
+      end
+    end
+  end 
+
+  def initialize(options = {})
+    @identifier = options[:identifier] || :sessions
+  end
+
+  private
+  def normalized_key_name(key)
+    KEY_PREFIX + @identifier.to_s + ":" + key.to_s
+  end
+
+  def encode_value(value)
+    Marshal.dump(value)
+  end
+  
+  def decode_value(string)
+    if string
+      Marshal.load(string)
+    else
+      {}
+    end
+  rescue TypeError
+    {}
+  rescue ArgumentError
+    {}
+  end
+end

data/lib/colloquy/session_store/memory.rb

@@ -0,0 +1,14 @@
+class Colloquy::SessionStore::Memory < Colloquy::SessionStore
+
+  def []=(key, value)    
+    @store ||= {}
+    @store[normalized_key_name(key)] = encode_value(value)
+  end
+  
+  def [](key)
+    @store ||= {}
+    string = @store[normalized_key_name(key)]
+    
+    decode_value(string)
+  end
+end

data/lib/colloquy/session_store/redis.rb

@@ -0,0 +1,24 @@
+class Colloquy::SessionStore::Redis < Colloquy::SessionStore
+  KEY_EXPIRY = 300 # 5 minutes
+  
+  def []=(key, value)    
+    @store ||= redis_connection
+    @store.set(normalized_key_name(key), encode_value(value), KEY_EXPIRY)
+  end
+  
+  def [](key)
+    @store ||= redis_connection
+    string = @store.get(normalized_key_name(key))
+    
+    decode_value(string)
+  end
+  
+  private
+  def redis_connection
+    @redis = Colloquy::Helpers::Redis::RedisProxy.instance
+    @redis.configure
+    
+    @redis[@identifier]
+  end
+  
+end

data/lib/colloquy/simulator.rb

@@ -0,0 +1,114 @@
+require 'em-synchrony'
+
+class Colloquy::Simulator
+  def initialize(options = {})
+    @renderer = Colloquy::Renderer.new(options)
+    @renderer.prepare!
+  end
+
+  def construct_response 
+    @renderer.apply(@flow_name, @msisdn, @session_id, @input)
+  end
+  
+  def run_simulator(input)
+    response = construct_response
+    puts response
+    
+    if response.flow_state == :notify
+      puts "\n---Flow complete---"
+      reset
+    else
+      read_input
+    end
+    
+    run_simulator(@input)
+  end
+  
+  def reset
+    puts "\n--Going back to beginning of flow--\n"
+    
+    # Get a new session_id when the simulator is reset
+    @session_id = @session_id.to_i + 1
+    
+    puts 'Initial input (for direct flow):'
+    read_input
+    
+    run!
+  end
+  
+  def ask_for_flow_parameters
+    puts 'Please enter flow name:'
+    @flow_name = EM::Synchrony.gets.strip
+    puts 'Please enter msisdn: '
+    @msisdn = EM::Synchrony.gets.strip
+    puts 'Please enter session_id: '
+    @session_id = EM::Synchrony.gets.strip
+    puts 'Initial input (for direct flow): '
+    read_input
+  end
+  
+  # Run simulator inside EM.synchrony loop
+  def run
+    EM.synchrony do
+      ask_for_flow_parameters
+      run!
+    end
+  end
+  
+  def run!
+    validate_request
+    sanitize_parameters!
+    
+    run_simulator(@input)
+  end
+  
+  private
+  def read_input
+    print '> '
+    @input = EM::Synchrony.gets.strip
+    sanitize_parameters!
+    
+    case @input 
+    when 'reset'
+      reset
+    when 'quit'
+      puts 'Bye!'
+      exit!
+    end
+  end
+  
+  def logger
+    @renderer.logger
+  end
+  
+  def validate_request
+    validate_flow_presence!
+    validate_msisdn!
+    validate_session_id!
+  end
+  
+  def validate_flow_presence!
+    unless @renderer.flow_exists?(@flow_name)
+      raise Colloquy::FlowNotFound, "Flow not found: #{@flow_name}"
+    end
+  end
+  
+  def validate_msisdn!
+    if @msisdn == ''
+      raise Colloquy::MSISDNParameterEmpty, 'The msisdn parameter should not be empty.'
+    end
+  end
+  
+  def validate_session_id!
+    if @session_id == ''
+      raise Colloquy::SessionIDParameterEmpty, 'The session_id parameter should not be empty.'
+    end
+  end
+  
+  def sanitize_parameters!
+    @flow_name = @flow_name.to_sym
+    @msisdn = @msisdn.to_i.to_s
+    @session_id = @session_id.to_s[0..20].strip
+    @input = @input.to_s[0..160].strip
+  end
+end