ruby_ami 0.1.1

data/features/step_definitions/lexer_steps.rb

@@ -0,0 +1,207 @@
+Given "a new lexer" do
+  @lexer = IntrospectiveManagerStreamLexer.new
+  @custom_stanzas = {}
+  @custom_events  = {}
+
+  @GivenPong = lambda do |with_or_without, action_id, number|
+    number = number == "a" ? 1 : number.to_i
+    data = case with_or_without
+      when "with"    then "Response: Pong\r\nActionID: #{action_id}\r\n\r\n"
+      when "without" then "Response: Pong\r\n\r\n"
+      else raise "Do not recognize preposition #{with_or_without.inspect}. Should be either 'with' or 'without'"
+    end
+    number.times do
+      @lexer << data
+    end
+  end
+end
+
+Given "a version header for AMI $version" do |version|
+  @lexer << "Asterisk Call Manager/1.0\r\n"
+end
+
+Given "a normal login success with events" do
+  @lexer << fixture('login/standard/success')
+end
+
+Given "a normal login success with events split into two pieces" do
+  stanza = fixture('login/standard/success')
+  @lexer << stanza[0...3]
+  @lexer << stanza[3..-1]
+end
+
+Given "a stanza break" do
+  @lexer << "\r\n\r\n"
+end
+
+Given "a multi-line Response:Follows body of $method_name" do |method_name|
+  multi_line_response_body = send(:follows_body_text, method_name)
+
+  multi_line_response = format_newlines(<<-RESPONSE + "\r\n") % multi_line_response_body
+Response: Follows\r
+Privilege: Command\r
+ActionID: 123123\r
+%s\r
+--END COMMAND--\r\n\r
+  RESPONSE
+
+  @lexer << multi_line_response
+end
+
+Given "a multi-line Response:Follows response simulating uptime" do
+  uptime_response = "Response: Follows\r
+Privilege: Command\r
+System uptime: 46 minutes, 30 seconds\r
+--END COMMAND--\r\n\r\n"
+  @lexer << uptime_response
+end
+
+Given "syntactically invalid $name" do |name|
+  @lexer << send(:syntax_error_data, name)
+end
+
+Given /^(\d+) Pong responses with an ActionID of ([\d\w.]+)$/ do |number, action_id|
+  @GivenPong.call "with", action_id, number
+end
+
+Given /^a Pong response with an ActionID of ([\d\w.]+)$/ do |action_id|
+  @GivenPong.call "with", action_id, 1
+end
+
+Given /^(\d+) Pong responses without an ActionID$/ do |number|
+  @GivenPong.call "without", Time.now.to_f, number
+end
+
+Given /^a custom stanza named "(\w+)"$/ do |name|
+  @custom_stanzas[name] = "Response: Success\r\n"
+end
+
+Given 'the custom stanza named "$name" has key "$key" with value "$value"' do |name,key,value|
+  @custom_stanzas[name] << "#{key}: #{value}\r\n"
+end
+
+Given 'an AMI error whose message is "$message"' do |message|
+  @lexer << "Response: Error\r\nMessage: #{message}\r\n\r\n"
+end
+
+Given 'an immediate response with text "$text"' do |text|
+  @lexer << "#{text}\r\n\r\n"
+end
+
+Given 'a custom event with name "$event_name" identified by "$identifier"' do |event_name, identifer|
+  @custom_events[identifer] = {:Event => event_name }
+end
+
+Given 'a custom header for event identified by "$identifier" whose key is "$key" and value is "$value"' do |identifier, key, value|
+  @custom_events[identifier][key] = value
+end
+
+Given "an Authentication Required error" do
+  @lexer << "Response: Error\r\nActionID: BPJeKqW2-SnVg-PyFs-vkXT-7AWVVPD0N3G7\r\nMessage: Authentication Required\r\n\r\n"
+end
+
+Given "a follows packet with a colon in it" do
+  @lexer << follows_body_text("with_colon")
+end
+
+########################################
+#### WHEN
+########################################
+
+When 'the custom stanza named "$name" is added to the buffer' do |name|
+  @lexer << (@custom_stanzas[name] + "\r\n")
+end
+
+When 'the custom event identified by "$identifier" is added to the buffer' do |identifier|
+  custom_event = @custom_events[identifier].clone
+  event_name = custom_event.delete :Event
+  stringified_event = "Event: #{event_name}\r\n"
+  custom_event.each_pair do |key,value|
+    stringified_event << "#{key}: #{value}\r\n"
+  end
+  stringified_event << "\r\n"
+  @lexer << stringified_event
+end
+
+When "the buffer is lexed" do
+  @lexer.resume!
+end
+
+########################################
+#### THEN
+########################################
+
+Then "the protocol should have lexed without syntax errors" do
+  current_pointer     = @lexer.send(:instance_variable_get, :@current_pointer)
+  data_ending_pointer = @lexer.send(:instance_variable_get, :@data_ending_pointer)
+  current_pointer.should equal(data_ending_pointer)
+  @lexer.syntax_errors.size.should equal(0)
+end
+
+Then /^the protocol should have lexed with (\d+) syntax errors?$/ do |number|
+  @lexer.syntax_errors.size.should equal(number.to_i)
+end
+
+Then "the syntax error fixture named $name should have been encountered" do |name|
+  irregularity = send(:syntax_error_data, name)
+  @lexer.syntax_errors.find { |error| error == irregularity }.should_not be_nil
+end
+
+Then /^(\d+) messages? should have been received$/ do |number_received|
+  @lexer.received_messages.size.should equal(number_received.to_i)
+end
+
+Then /^the 'follows' body of (\d+) messages? received should equal (\w+)$/ do |number, method_name|
+  multi_line_response = follows_body_text method_name
+  @lexer.received_messages.should_not be_empty
+  @lexer.received_messages.select do |message|
+    message.text_body == multi_line_response
+  end.size.should eql(number.to_i)
+end
+
+Then "the version should be set to $version" do |version|
+  @lexer.ami_version.should eql(version.to_f)
+end
+
+Then /^the ([\w\d]*) message received should have a key "([^\"]*)" with value "([^\"]*)"$/ do |ordered,key,value|
+  ordered = ordered[/^(\d+)\w+$/, 1].to_i - 1
+  @lexer.received_messages[ordered][key].should eql(value)
+end
+
+Then "$number AMI error should have been received" do |number|
+  @lexer.ami_errors.size.should equal(number.to_i)
+end
+
+Then 'the $order AMI error should have the message "$message"' do |order, message|
+  order = order[/^(\d+)\w+$/, 1].to_i - 1
+  @lexer.ami_errors[order].should be_kind_of(RubyAMI::Error)
+  @lexer.ami_errors[order].message.should eql(message)
+end
+
+Then '$number message should be an immediate response with text "$text"' do |number, text|
+  matching_immediate_responses = @lexer.received_messages.select do |response|
+    response.kind_of?(RubyAMI::Response) && response.text_body == text
+  end
+  matching_immediate_responses.size.should equal(number.to_i)
+  matching_immediate_responses.first["ActionID"].should eql(nil)
+end
+
+Then 'the $order event should have the name "$name"' do |order, name|
+  order = order[/^(\d+)\w+$/, 1].to_i - 1
+  @lexer.received_messages.select do |response|
+    response.kind_of?(RubyAMI::Event)
+  end[order].name.should eql(name)
+end
+
+Then '$number event should have been received' do |number|
+  @lexer.received_messages.select do |response|
+    response.kind_of?(RubyAMI::Event)
+  end.size.should equal(number.to_i)
+end
+
+Then 'the $order event should have key "$key" with value "$value"' do |order, key, value|
+  order = order[/^(\d+)\w+$/, 1].to_i - 1
+  @lexer.received_messages.select do |response|
+    response.kind_of?(RubyAMI::Event)
+  end[order][key].should eql(value)
+end

data/features/support/ami_fixtures.yml

@@ -0,0 +1,30 @@
+:login:
+  :standard:
+    :client:
+      Action: Login
+      Username: :string
+      Secret: :string
+      Events: {one_of: ["on", "off"]}
+    :success:
+      Response: Success
+      Message: Authentication accepted
+    :fail:
+      Response: Error
+      Message: Authentication failed
+
+:errors:
+  :missing_action:
+    Response: Error
+    Message: Missing action in request
+
+:pong:
+  :with_action_id:
+    ActionID: 1287381.1238
+    Response: Pong
+  :without_action_id:
+    Response: Pong
+  :with_extra_keys:
+    ActionID: 1287381.1238
+    Response: Pong
+    Blah: This is something arbitrary
+    Blahhh: something else arbitrary

data/features/support/env.rb

@@ -0,0 +1,16 @@
+require 'simplecov'
+require 'simplecov-rcov'
+class SimpleCov::Formatter::MergedFormatter
+  def format(result)
+     SimpleCov::Formatter::HTMLFormatter.new.format(result)
+     SimpleCov::Formatter::RcovFormatter.new.format(result)
+  end
+end
+SimpleCov.formatter = SimpleCov::Formatter::MergedFormatter
+SimpleCov.start do
+  add_filter "/vendor/"
+end
+
+require 'cucumber'
+require 'rspec'
+require 'ruby_ami'

data/features/support/introspective_lexer.rb

@@ -0,0 +1,22 @@
+class IntrospectiveManagerStreamLexer < RubyAMI::Lexer
+  attr_reader :received_messages, :syntax_errors, :ami_errors
+
+  def initialize(*args)
+    super
+    @received_messages = []
+    @syntax_errors     = []
+    @ami_errors        = []
+  end
+
+  def message_received(message = @current_message)
+    @received_messages << message
+  end
+
+  def error_received(error_message)
+    @ami_errors << error_message
+  end
+
+  def syntax_error_encountered(ignored_chunk)
+    @syntax_errors << ignored_chunk
+  end
+end

data/features/support/lexer_helper.rb

@@ -0,0 +1,103 @@
+RAGEL_FILES = %w[lib/ruby_ami/lexer.rl.rb]
+
+def regenerate_ragel
+  `rake ragel`
+end
+
+FIXTURES = YAML.load_file File.dirname(__FILE__) + "/ami_fixtures.yml"
+
+def fixture(path, overrides = {})
+  path_segments = path.split '/'
+  selected_event = path_segments.inject(FIXTURES.clone) do |hash, segment|
+    raise ArgumentError, path + " not found!" unless hash
+    hash[segment.to_sym]
+  end
+
+  # Downcase all keys in the event and the overrides
+  selected_event = selected_event.inject({}) do |downcased_hash,(key,value)|
+    downcased_hash[key.to_s.downcase] = value
+    downcased_hash
+  end
+
+  overrides = overrides.inject({}) do |downcased_hash,(key,value)|
+    downcased_hash[key.to_s.downcase] = value
+    downcased_hash
+  end
+
+  # Replace variables in the selected_event with any overrides, ignoring case of the key
+  keys_with_variables = selected_event.select { |(key, value)| value.kind_of?(Symbol) || value.kind_of?(Hash) }
+
+  keys_with_variables.each do |original_key, variable_type|
+    # Does an override an exist in the supplied list?
+    if overriden_pair = overrides.find { |(key, value)| key == original_key }
+      # We have an override! Let's replace the template value in the event with the overriden value
+      selected_event[original_key] = overriden_pair.last
+    else
+      # Based on the type, let's generate a placeholder.
+      selected_event[original_key] = case variable_type
+        when :string
+          rand(100000).to_s
+        when Hash
+          if variable_type.has_key? "one_of"
+            # Choose a random possibility
+            possibilities = variable_type['one_of']
+            possibilities[rand(possibilities.size)]
+          else
+            raise "Unrecognized Hash fixture property! ##{variable_type.keys.to_sentence}"
+          end
+        else
+          raise "Unrecognized fixture variable type #{variable_type}!"
+      end
+    end
+  end
+
+  hash_to_stanza(selected_event).tap do |event|
+    selected_event.each_pair do |key, value|
+      event.meta_def(key) { value }
+    end
+  end
+end
+
+def hash_to_stanza(hash)
+  ordered_hash = hash.to_a
+  starter = hash.find { |(key, value)| key.strip =~ /^(Response|Action)$/i }
+  ordered_hash.unshift ordered_hash.delete(starter) if starter
+  ordered_hash.inject(String.new) do |stanza,(key, value)|
+    stanza + "#{key}: #{value}\r\n"
+  end + "\r\n"
+end
+
+def format_newlines(string)
+  # HOLY FUCK THIS IS UGLY
+  tmp_replacement = random_string
+  string.gsub("\r\n", tmp_replacement).
+         gsub("\n", "\r\n").
+         gsub(tmp_replacement, "\r\n")
+end
+
+def random_string
+  (rand(1_000_000_000_000) + 1_000_000_000).to_s
+end
+
+def follows_body_text(name)
+  case name
+    when "ragel_description"
+      "Ragel is a software development tool that allows user actions to
+      be embedded into the transitions of a regular expression's corresponding state machine,
+      eliminating the need to switch from the regular expression engine and user code execution
+      environment and back again."
+    when "with_colon_after_first_line"
+      "Host                            Username       Refresh State                Reg.Time                 \r\nlax.teliax.net:5060             jicksta            105 Registered           Tue, 11 Nov 2008 02:29:55"
+    when "show_channels_from_wayne"
+      "Channel              Location             State   Application(Data)\r\n0 active channels\r\n0 active calls"
+    when "empty_string"
+      ""
+  end
+end
+
+def syntax_error_data(name)
+  case name
+    when "immediate_packet_with_colon"
+      "!IJ@MHY:!&@B*!B @ ! @^! @ !@ !\r!@ ! @ !@ ! !!m, \n\\n\n"
+  end
+end

data/lib/ruby_ami.rb

@@ -0,0 +1,29 @@
+%w{
+  active_support/dependencies/autoload
+  active_support/core_ext/object/blank
+  active_support/core_ext/numeric/time
+  active_support/core_ext/numeric/bytes
+  active_support/hash_with_indifferent_access
+
+  uuidtools
+  eventmachine
+  future-resource
+  logger
+  girl_friday
+  countdownlatch
+
+  ruby_ami/metaprogramming
+}.each { |f| require f }
+
+module RubyAMI
+  extend ActiveSupport::Autoload
+
+  autoload :Action
+  autoload :Client
+  autoload :Error
+  autoload :Event
+  autoload :Lexer
+  autoload :Response
+  autoload :Stream
+  autoload :Version
+end

data/lib/ruby_ami/Guardfile

@@ -0,0 +1,6 @@
+ENV['SKIP_RCOV'] = 'true'
+guard 'rspec', :version => 2, :cli => '--format documentation' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end

data/lib/ruby_ami/action.rb

@@ -0,0 +1,143 @@
+module RubyAMI
+  class Action
+    attr_reader :name, :headers, :action_id
+
+    attr_accessor :state
+
+    CAUSAL_EVENT_NAMES = %w[queuestatus sippeers iaxpeers parkedcalls dahdishowchannels coreshowchannels
+                            dbget status agents konferencelist] unless defined? CAUSAL_EVENT_NAMES
+
+    def initialize(name, headers = {}, &block)
+      @name       = name.to_s.downcase.freeze
+      @headers    = headers.stringify_keys.freeze
+      @action_id  = UUIDTools::UUID.random_create.to_s
+      @response   = FutureResource.new
+      @response_callback = block
+      @state      = :new
+      @events     = []
+      @event_lock = Mutex.new
+    end
+
+    [:new, :sent, :complete].each do |state|
+      define_method("#{state}?") { @state == state }
+    end
+
+    def replies_with_action_id?
+      !UnsupportedActionName::UNSUPPORTED_ACTION_NAMES.include? name
+    end
+
+    ##
+    # When sending an action with "causal events" (i.e. events which must be collected to form a proper
+    # response), AMI should send a particular event which instructs us that no more events will be sent.
+    # This event is called the "causal event terminator".
+    #
+    # Note: you must supply both the name of the event and any headers because it's possible that some uses of an
+    # action (i.e. same name, different headers) have causal events while other uses don't.
+    #
+    # @param [String] name the name of the event
+    # @param [Hash] the headers associated with this event
+    # @return [String] the downcase()'d name of the event name for which to wait
+    #
+    def has_causal_events?
+      CAUSAL_EVENT_NAMES.include? name
+    end
+
+    ##
+    # Used to determine the event name for an action which has causal events.
+    #
+    # @param [String] action_name
+    # @return [String] The corresponding event name which signals the completion of the causal event sequence.
+    #
+    def causal_event_terminator_name
+      return unless has_causal_events?
+      case name
+      when "sippeers", "iaxpeers"
+        "peerlistcomplete"
+      when "dbget"
+        "dbgetresponse"
+      when "konferencelist"
+        "conferencelistcomplete"
+      else
+        name + "complete"
+      end
+    end
+
+    ##
+    # Converts this action into a protocol-valid String, ready to be sent over a socket.
+    #
+    def to_s
+      @textual_representation ||= (
+          "Action: #{@name}\r\nActionID: #{@action_id}\r\n" +
+          @headers.map { |(key,value)| "#{key}: #{value}" }.join("\r\n") +
+          (@headers.any? ? "\r\n\r\n" : "\r\n")
+      )
+    end
+
+    #
+    # If the response has simply not been received yet from Asterisk, the calling Thread will block until it comes
+    # in. Once the response comes in, subsequent calls immediately return a reference to the ManagerInterfaceResponse
+    # object.
+    #
+    def response(timeout = nil)
+      @response.resource(timeout).tap do |resp|
+        raise resp if resp.is_a? Exception
+      end
+    end
+
+    def response=(other)
+      @state = :complete
+      @response.resource = other
+      @response_callback.call other if @response_callback
+    end
+
+    def <<(message)
+      case message
+      when Error
+        self.response = message
+      when Event
+        raise StandardError, 'This action should not trigger events. Maybe it is now a causal action? This is most likely a bug in RubyAMI' unless has_causal_events?
+        @event_lock.synchronize do
+          @events << message
+        end
+        self.response = @pending_response if message.name.downcase == causal_event_terminator_name
+      when Response
+        if has_causal_events?
+          @pending_response = message
+        else
+          self.response = message
+        end
+      end
+    end
+
+    def events
+      @event_lock.synchronize do
+        @events.dup
+      end
+    end
+
+    def eql?(other)
+      to_s == other.to_s
+    end
+    alias :== :eql?
+
+    ##
+    # This class will be removed once this AMI library fully supports all known protocol anomalies.
+    #
+    class UnsupportedActionName < ArgumentError
+      UNSUPPORTED_ACTION_NAMES = %w[queues] unless defined? UNSUPPORTED_ACTION_NAMES
+
+      # Blacklist some actions depends on the Asterisk version
+      def self.preinitialize(version)
+        if version < 1.8
+          %w[iaxpeers muteaudio mixmonitormute aocmessage].each do |action|
+            UNSUPPORTED_ACTION_NAMES << action
+          end
+        end
+      end
+
+      def initialize(name)
+        super "At the moment this AMI library doesn't support the #{name.inspect} action because it causes a protocol anomaly. Support for it will be coming shortly."
+      end
+    end
+  end
+end # RubyAMI