ruby_ami 0.1.1

data/lib/ruby_ami/lexer_machine.rl

@@ -0,0 +1,87 @@
+%%{ #%
+
+#########
+## This file is written with the Ragel programming language and parses the Asterisk Manager Interface protocol. It depends
+## upon Ragel actions which should be implemented in another Ragel-parsed file which includes this file.
+##
+## Ragel was used because the AMI protocol is extremely non-deterministic and, in the edge cases, requires something both
+## very robust and something which can recover from syntax errors.
+##
+## Note: This file is language agnostic. From this AMI parsers in many other languages can be generated.
+#########
+
+machine ami_protocol_parser_machine;
+
+cr = "\r";              # A carriage return. Used before (almost) every newline character.
+lf = "\n";              # Newline. Used (with cr) to separate key/value pairs and stanzas.
+crlf = cr lf;           # Means "carriage return and line feed". Used to separate key/value pairs and stanzas
+loose_newline = cr? lf; # Used sometimes when the AMI protocol is nondeterministic about the delimiter
+
+white = [\t ];                 # Single whitespace character, either a tab or a space
+colon = ":" [ ]**;             # Separates keys from values. "A colon followed by any number of spaces"
+stanza_break = crlf crlf;      # The seperator between two stanzas.
+rest_of_line = (any* -- crlf); # Match all characters until the next line seperator.
+
+Prompt = "Asterisk Call Manager/" digit+ >version_starts "." digit+ %version_stops crlf;
+
+Key = ((alnum | print) -- (cr | lf | ":"))+;
+KeyValuePair = Key >key_starts %key_stops colon rest_of_line >value_starts %value_stops crlf;
+
+FollowsDelimiter = loose_newline "--END COMMAND--";
+
+Response = "Response"i colon;
+
+Success  = Response "Success"i %init_success crlf @{ fgoto success; };
+Pong     = Response "Pong"i %init_success crlf @{ fgoto success; };
+Event    = "Event"i colon %event_name_starts rest_of_line %event_name_stops crlf @{ fgoto success; };
+Error    = Response "Error"i %init_error crlf (("Message"i colon rest_of_line >error_reason_starts crlf >error_reason_stops) | KeyValuePair)+ crlf @error_received;
+Follows  = Response "Follows"i crlf @init_response_follows @{ fgoto response_follows; };
+
+# For "Response: Follows"
+FollowsBody = (any* -- FollowsDelimiter) >follows_text_starts FollowsDelimiter @follows_text_stops crlf;
+
+ImmediateResponse = (any+ -- (loose_newline | ":")) >immediate_response_starts loose_newline @immediate_response_stops @{fret;};
+SyntaxError       = (any+ -- crlf) >syntax_error_starts crlf @syntax_error_stops;
+
+irregularity := |*
+  ImmediateResponse; # Performs the fret in the ImmediateResponse FSM
+  SyntaxError       => { fret; };
+*|;
+
+# When a new socket is established, Asterisk will send the version of the protocol per the Prompt machine. Because it's
+# tedious for unit tests to always send this, we'll put some intelligence into this parser to support going straight into
+# the protocol-parsing machine. It's also conceivable that a variant of AMI would not send this initial information.
+main := |*
+  Prompt => { fgoto protocol; };
+  any => {
+    # If this scanner's look-ahead capability didn't match the prompt, let's ignore the need for a prompt
+    fhold;
+    fgoto protocol;
+  };
+*|;
+
+protocol := |*
+  Prompt;
+  Success;
+  Pong;
+  Event;
+  Error;
+  Follows crlf;
+  crlf => { fgoto protocol; }; # If we get a crlf out of place, let's just ignore it.
+  any  => {
+    # If NONE of the above patterns match, we consider this a syntax error. The irregularity machine can recover gracefully.
+    fhold;
+    fcall irregularity;
+  };
+*|;
+
+success := KeyValuePair* crlf @message_received @{fgoto protocol;};
+
+# For the "Response: Follows" protocol abnormality. What happens if there's a protocol irregularity in this state???
+response_follows := |*
+    KeyValuePair+;
+    FollowsBody;
+    crlf @{ message_received @current_message; fgoto protocol; };
+*|;
+
+}%%

data/lib/ruby_ami/metaprogramming.rb

@@ -0,0 +1,17 @@
+class Object
+  def metaclass
+    class << self
+      self
+    end
+  end
+
+  def meta_eval(&block)
+    metaclass.instance_eval &block
+  end
+
+  def meta_def(name, &block)
+    meta_eval do
+      define_method name, &block
+    end
+  end
+end

data/lib/ruby_ami/response.rb

@@ -0,0 +1,44 @@
+module RubyAMI
+  ##
+  # This is the object containing a response from Asterisk.
+  #
+  # Note: not all responses have an ActionID!
+  #
+  class Response
+    class << self
+      def from_immediate_response(text)
+        new.tap do |instance|
+          instance.text_body = text
+        end
+      end
+    end
+
+    attr_accessor :action,
+                  :text_body  # For "Response: Follows" sections
+    attr_reader   :events
+
+    def initialize
+      @headers = HashWithIndifferentAccess.new
+    end
+
+    def has_text_body?
+      !!@text_body
+    end
+
+    def headers
+      @headers.clone
+    end
+
+    def [](arg)
+      @headers[arg]
+    end
+
+    def []=(key,value)
+      @headers[key] = value
+    end
+
+    def action_id
+      @headers['ActionID']
+    end
+  end
+end # RubyAMI

data/lib/ruby_ami/stream.rb

@@ -0,0 +1,60 @@
+module RubyAMI
+  class Stream < EventMachine::Connection
+    class ConnectionStatus
+      def eql?(other)
+        other.is_a? self.class
+      end
+
+      alias :== :eql?
+    end
+
+    Connected = Class.new ConnectionStatus
+    Disconnected = Class.new ConnectionStatus
+
+    def self.start(host, port, event_callback)
+      EM.connect host, port, self, event_callback
+    end
+
+    def initialize(event_callback)
+      super()
+      @event_callback = event_callback
+      @logger = Logger.new($stdout)
+      @logger.level = Logger::FATAL
+      @logger.debug "Starting up..."
+      @lexer = Lexer.new self
+    end
+
+    [:started, :stopped, :ready].each do |state|
+      define_method("#{state}?") { @state == state }
+    end
+
+    def post_init
+      @state = :started
+      @event_callback.call Connected.new
+    end
+
+    def send_action(action)
+      @logger.debug "[SEND] #{action.to_s}"
+      send_data action.to_s
+    end
+
+    def receive_data(data)
+      @logger.debug "[RECV] #{data}"
+      @lexer << data
+    end
+
+    def message_received(message)
+      @logger.debug "[RECV] #{message.inspect}"
+      @event_callback.call message
+    end
+
+    alias :error_received :message_received
+
+    # Called by EM when the connection is closed
+    # @private
+    def unbind
+      @state = :stopped
+      @event_callback.call Disconnected.new
+    end
+  end
+end

data/lib/ruby_ami/version.rb

@@ -0,0 +1,3 @@
+module RubyAMI
+  VERSION = "0.1.1"
+end

data/ruby_ami.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "ruby_ami/version"
+
+Gem::Specification.new do |s|
+  s.name        = "ruby_ami"
+  s.version     = RubyAMI::VERSION
+  s.authors     = ["Ben Langfeld"]
+  s.email       = ["ben@langfeld.me"]
+  s.homepage    = ""
+  s.summary     = %q{Futzing with AMI so you don't have to}
+  s.description = %q{A Ruby client library for the Asterisk Management Interface build on eventmachine.}
+
+  s.rubyforge_project = "ruby_ami"
+
+  s.files         = `git ls-files`.split("\n") << 'lib/ruby_ami/lexer.rb'
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency %q<activesupport>, [">= 3.0.9"]
+  s.add_runtime_dependency %q<uuidtools>, [">= 0"]
+  s.add_runtime_dependency %q<eventmachine>, [">= 0"]
+  s.add_runtime_dependency %q<future-resource>, [">= 0"]
+  s.add_runtime_dependency %q<girl_friday>, [">= 0"]
+  s.add_runtime_dependency %q<countdownlatch>, [">= 1.0.0"]
+  s.add_runtime_dependency %q<i18n>, [">= 0"]
+
+  s.add_development_dependency %q<bundler>, ["~> 1.0.0"]
+  s.add_development_dependency %q<rspec>, [">= 2.5.0"]
+  s.add_development_dependency %q<cucumber>, [">= 0"]
+  s.add_development_dependency %q<ci_reporter>, [">= 1.6.3"]
+  s.add_development_dependency %q<yard>, ["~> 0.6.0"]
+  s.add_development_dependency %q<rcov>, [">= 0"]
+  s.add_development_dependency %q<rake>, [">= 0"]
+  s.add_development_dependency %q<mocha>, [">= 0"]
+  s.add_development_dependency %q<simplecov>, [">= 0"]
+  s.add_development_dependency %q<simplecov-rcov>, [">= 0"]
+  s.add_development_dependency %q<guard-rspec>
+end

data/spec/ruby_ami/action_spec.rb

@@ -0,0 +1,163 @@
+require 'spec_helper'
+
+module RubyAMI
+  describe Action do
+    let(:name) { 'foobar' }
+    let(:headers) { {'foo' => 'bar'} }
+
+    subject do
+      Action.new name, headers do |response|
+        @foo = response
+      end
+    end
+
+    it { should be_new }
+
+    describe "SIPPeers actions" do
+      subject { Action.new('SIPPeers') }
+      its(:has_causal_events?) { should be true }
+    end
+
+    describe "Queues actions" do
+      subject { Action.new('Queues') }
+      its(:replies_with_action_id?) { should == false }
+    end
+
+    describe "IAXPeers actions" do
+      before { pending }
+      # FIXME: This test relies on the side effect that earlier tests have run
+      # and initialized the UnsupportedActionName::UNSUPPORTED_ACTION_NAMES
+      # constant for an "unknown" version of Asterisk.  This should be fixed
+      # to be more specific about which version of Asterisk is under test.
+      # IAXPeers is supported (with Action IDs!) since Asterisk 1.8
+      subject { Action.new('IAXPeers') }
+      its(:replies_with_action_id?) { should == false }
+    end
+
+    describe "the ParkedCalls terminator event" do
+      subject { Action.new('ParkedCalls') }
+      its(:causal_event_terminator_name) { should == "parkedcallscomplete" }
+    end
+
+    it "should properly convert itself into a String when additional headers are given" do
+      string = Action.new("Hawtsawce", "Monkey" => "Zoo").to_s
+      string.should =~ /^Action: Hawtsawce\r\n/i
+      string.should =~ /[^\n]\r\n\r\n$/
+      string.should =~ /^(\w+:\s*[\w-]+\r\n){3}\r\n$/
+    end
+
+    it "should properly convert itself into a String when no additional headers are given" do
+      Action.new("Ping").to_s.should =~ /^Action: Ping\r\nActionID: [\w-]+\r\n\r\n$/i
+      Action.new("ParkedCalls").to_s.should =~ /^Action: ParkedCalls\r\nActionID: [\w-]+\r\n\r\n$/i
+    end
+
+    it 'should be able to be marked as sent' do
+      subject.state = :sent
+      subject.should be_sent
+    end
+
+    it 'should be able to be marked as complete' do
+      subject.state = :complete
+      subject.should be_complete
+    end
+
+    describe '#<<' do
+      describe 'for a non-causal action' do
+        context 'with a response' do
+          let(:response) { Response.new }
+
+          it 'should set the response' do
+            subject << response
+            subject.response.should be response
+          end
+        end
+
+        context 'with an error' do
+          let(:error) { Error.new }
+
+          it 'should set the response and raise the error when reading it' do
+            subject << error
+            lambda { subject.response }.should raise_error error
+          end
+        end
+
+        context 'with an event' do
+          it 'should raise an error' do
+            lambda { subject << Event.new('foo') }.should raise_error StandardError, /causal action/
+          end
+        end
+      end
+
+      describe 'for a causal action' do
+        let(:name) { 'Status' }
+
+        context 'with a response' do
+          let(:message) { Response.new }
+
+          before { subject << message }
+
+          it { should_not be_complete }
+        end
+
+        context 'with an event' do
+          let(:event) { Event.new 'foo' }
+
+          before { subject << event }
+
+          its(:events) { should == [event] }
+        end
+
+        context 'with a terminating event' do
+          let(:response)  { Response.new }
+          let(:event)     { Event.new 'StatusComplete' }
+
+          before do
+            subject << response
+            subject.should_not be_complete
+            subject << event
+          end
+
+          its(:events) { should == [event] }
+
+          it { should be_complete }
+
+          its(:response) { should be response }
+        end
+      end
+    end
+
+    describe 'setting the response' do
+      let(:response) { :bar }
+
+      before { subject.response = response }
+
+      it { should be_complete }
+      its(:response) { should == response }
+
+      it 'should call the response callback with the response' do
+        @foo.should == response
+      end
+    end
+
+    describe 'comparison' do
+      describe 'with another Action' do
+        context 'with identical name and headers' do
+          let(:other) { Action.new name, headers }
+          it { should == other }
+        end
+
+        context 'with identical name and different headers' do
+          let(:other) { Action.new name, 'boo' => 'baz' }
+          it { should_not == other }
+        end
+
+        context 'with different name and identical headers' do
+          let(:other) { Action.new 'BARBAZ', headers }
+          it { should_not == other }
+        end
+      end
+
+      it { should_not == :foo }
+    end
+  end # Action
+end # RubyAMI

data/spec/ruby_ami/client_spec.rb

@@ -0,0 +1,324 @@
+require 'spec_helper'
+
+module RubyAMI
+  describe Client do
+    let(:event_handler) { [] }
+
+    let(:options) do
+      {
+        :host     => '127.0.0.1',
+        :port     => 50000 - rand(1000),
+        :username => 'username',
+        :password => 'password',
+        :event_handler => lambda { |event| event_handler << event }
+      }
+    end
+
+    subject { Client.new options }
+
+    it { should be_stopped }
+
+    its(:options) { should == options }
+
+    its(:action_queue) { should be_a GirlFriday::WorkQueue }
+
+    describe 'starting up' do
+      before do
+        MockServer.any_instance.stubs :receive_data
+        subject.start do
+          EM.start_server options[:host], options[:port], ServerMock
+          EM.add_timer(0.5) { EM.stop if EM.reactor_running? }
+        end
+      end
+
+      it { should be_started }
+
+      its(:events_stream)   { should be_a Stream }
+      its(:actions_stream)  { should be_a Stream }
+    end
+
+    describe 'logging in streams' do
+      context 'when the actions stream connects' do
+        let(:mock_actions_stream) { mock 'Actions Stream' }
+
+        let :expected_login_action do
+          Action.new 'Login',
+                     'Username' => 'username',
+                     'Secret'   => 'password',
+                     'Events'   => 'Off'
+        end
+
+        before do
+          Action.any_instance.stubs(:response).returns(true)
+          subject.stubs(:actions_stream).returns mock_actions_stream
+        end
+
+        it 'should log in' do
+          mock_actions_stream.expects(:send_action).with do |action|
+            action.to_s.should == expected_login_action.to_s
+          end
+
+          GirlFriday::WorkQueue.immediate!
+          subject.handle_message Stream::Connected.new
+          GirlFriday::WorkQueue.queue!
+        end
+      end
+
+      context 'when the events stream connects' do
+        let(:mock_events_stream) { mock 'Events Stream' }
+
+        let :expected_login_action do
+          Action.new 'Login',
+                     'Username' => 'username',
+                     'Secret'   => 'password',
+                     'Events'   => 'On'
+        end
+
+        before do
+          subject.stubs(:events_stream).returns mock_events_stream
+        end
+
+        it 'should log in' do
+          mock_events_stream.expects(:send_action).with do |action|
+            action.to_s.should == expected_login_action.to_s
+          end
+
+          subject.handle_event Stream::Connected.new
+        end
+      end
+    end
+
+    describe 'when the events stream disconnects' do
+      it 'should unbind' do
+        subject.expects(:unbind).once
+        subject.handle_event Stream::Disconnected.new
+      end
+    end
+
+    describe 'when the actions stream disconnects' do
+      before do
+        Action.any_instance.stubs(:response).returns(true)
+      end
+
+      it 'should prevent further actions being sent' do
+        subject.expects(:_send_action).once
+
+        GirlFriday::WorkQueue.immediate!
+        subject.handle_message Stream::Connected.new
+        GirlFriday::WorkQueue.queue!
+        subject.handle_message Stream::Disconnected.new
+
+        action = Action.new 'foo'
+        subject.send_action action
+
+        sleep 2
+
+        action.should be_new
+      end
+
+      it 'should unbind' do
+        subject.expects(:unbind).once
+        subject.handle_message Stream::Disconnected.new
+      end
+    end
+
+    describe 'when an event is received' do
+      let(:event) { Event.new 'foobar' }
+
+      it 'should call the event handler' do
+        subject.handle_event event
+        event_handler.should == [event]
+      end
+    end
+
+    describe 'sending actions' do
+      let(:action_name) { 'Login' }
+      let :headers do
+        {
+          'Username'  => 'username',
+          'Secret'    => 'password'
+        }
+      end
+      let(:expected_action) { Action.new action_name, headers }
+
+      let :expected_response do
+        Response.new.tap do |response|
+          response['ActionID'] = expected_action.action_id
+          response['Message'] = 'Action completed'
+        end
+      end
+
+      let(:mock_actions_stream) { mock 'Actions Stream' }
+
+      before do
+        subject.stubs(:actions_stream).returns mock_actions_stream
+        subject.stubs(:login_actions).returns nil
+      end
+
+      it 'should queue up actions to be sent' do
+        subject.handle_message Stream::Connected.new
+        subject.action_queue.expects(:<<).with expected_action
+        subject.send_action action_name, headers
+      end
+
+      describe 'forcibly for testing' do
+        before do
+          subject.actions_stream.expects(:send_action).with expected_action
+          subject._send_action expected_action
+        end
+
+        it 'should mark the action sent' do
+          expected_action.should be_sent
+        end
+
+        let(:receive_response) { subject.handle_message expected_response }
+
+        describe 'when a response is received' do
+          it 'should be sent to the action' do
+            expected_action.expects(:<<).once.with expected_response
+            receive_response
+          end
+
+          it 'should know its action' do
+            receive_response
+            expected_response.action.should be expected_action
+          end
+        end
+
+        describe 'when an error is received' do
+          let :expected_response do
+            Error.new.tap do |response|
+              response['ActionID'] = expected_action.action_id
+              response['Message'] = 'Action failed'
+            end
+          end
+
+          it 'should be sent to the action' do
+            expected_action.expects(:<<).once.with expected_response
+            receive_response
+          end
+
+          it 'should know its action' do
+            receive_response
+            expected_response.action.should be expected_action
+          end
+        end
+
+        describe 'when an event is received' do
+          let(:event) { Event.new 'foo' }
+
+          let(:receive_event) { subject.handle_message event }
+
+          context 'for a causal event' do
+            let(:expected_action) { Action.new 'Status' }
+
+            it 'should be sent to the action' do
+              expected_action.expects(:<<).once.with expected_response
+              expected_action.expects(:<<).once.with event
+              receive_response
+              receive_event
+            end
+
+            it 'should know its action' do
+              expected_action.stubs :<<
+              receive_response
+              receive_event
+              event.action.should be expected_action
+            end
+          end
+
+          context 'for a causal action which is complete' do
+            let(:expected_action) { Action.new 'Status' }
+
+            before do
+              expected_action.stubs(:complete?).returns true
+            end
+
+            it 'should raise an error' do
+              receive_response
+              receive_event
+              lambda { subject.handle_message Event.new('bar') }.should raise_error StandardError, /causal action/
+            end
+          end
+
+          context 'for a non-causal action' do
+            it 'should raise an error' do
+              lambda { receive_event }.should raise_error StandardError, /causal action/
+            end
+          end
+        end
+      end
+
+      describe 'from the queue' do
+        it 'should send actions to the stream and set their responses' do
+          subject.actions_stream.expects(:send_action).with expected_action
+          subject.handle_message Stream::Connected.new
+
+          Thread.new do
+            GirlFriday::WorkQueue.immediate!
+            subject.send_action expected_action
+            GirlFriday::WorkQueue.queue!
+          end
+
+          sleep 0.1
+
+          subject.handle_message expected_response
+          expected_action.response.should be expected_response
+        end
+
+        it 'should not send another action if the first action has not yet received a response' do
+          subject.actions_stream.expects(:send_action).once.with expected_action
+          subject.handle_message Stream::Connected.new
+          actions = []
+
+          2.times do
+            action = Action.new action_name, headers
+            actions << action
+            subject.send_action action
+          end
+
+          sleep 2
+
+          actions.should have(2).actions
+          actions[0].should be_sent
+          actions[1].should be_new
+        end
+      end
+    end
+
+    describe '#stop' do
+      let(:mock_actions_stream) { mock 'Actions Stream' }
+      let(:mock_events_stream) { mock 'Events Stream' }
+
+      let(:streams) { [mock_actions_stream, mock_events_stream] }
+
+      before do
+        subject.stubs(:actions_stream).returns mock_actions_stream
+        subject.stubs(:events_stream).returns mock_events_stream
+      end
+
+      it 'should close both streams' do
+        streams.each { |s| s.expects :close_connection_after_writing }
+        subject.stop
+      end
+    end
+
+    describe '#unbind' do
+      context 'if EM is running' do
+        it 'shuts down EM' do
+          EM.expects(:reactor_running?).returns true
+          EM.expects(:stop)
+          subject.unbind
+        end
+      end
+
+      context 'if EM is not running' do
+        it 'does nothing' do
+          EM.expects(:reactor_running?).returns false
+          EM.expects(:stop).never
+          subject.unbind
+        end
+      end
+    end
+  end
+end