ruby_ami 0.1.1

data/.gitignore

@@ -0,0 +1,14 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+lib/ruby_ami/lexer.rb
+.rvmrc
+.yardoc
+doc
+coverage
+spec/reports
+features/reports
+vendor
+*.swp

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--colour
+--tty

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# develop
+
+# 0.1.1
+  * Bugfix: Make countdownlatch and i18n runtime dependencies
+  * Bugfig: Include the generated lexer file in the gem
+
+# 0.1.0
+  * Initial release

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ruby_ami.gemspec
+gemspec
+
+if RUBY_PLATFORM =~ /darwin/
+  gem 'growl_notify'
+  gem 'rb-fsevent'
+end

data/Guardfile

@@ -0,0 +1,5 @@
+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/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ben Langfeld, Jay Phillips
+
+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/README.md

@@ -0,0 +1,49 @@
+# RubyAMI
+RubyAMI is an AMI client library in Ruby and based on EventMachine with the sole purpose of providing an connection to the Asterisk Manager Interface. RubyAMI does not provide any features beyond connection management and protocol parsing. Actions are sent over the wire, and responses come back via callbacks. It's up to you to match these up into something useful. In this regard, RubyAMI is very similar to [Blather](https://github.com/sprsquish/blather) for XMPP or [Punchblock](https://github.com/adhearsion/punchblock), the Ruby 3PCC library. In fact, Punchblock uses RubyAMI under the covers for its Asterisk implementation, including an implementation of AsyncAGI.
+
+## Installation
+    gem install ruby_ami
+
+## Usage
+```ruby
+require 'ruby_ami'
+
+class MyAMIClient < RubyAMI::Client
+  def on_connect
+    puts "AMI Connected successfully"
+    write_action "Originate", ...some options...
+  end
+
+  def handle_event(event)
+    puts "Received an AMI event: #{event}"
+  end
+
+  def handle_error(error)
+    ...similar here...
+  end
+
+  def handle_response(response)
+    ...similar here...
+  end
+end
+
+EM.run { MyAMIClient.run '127.0.0.1', 5038, 'admin', 'password' }
+```
+
+## Links:
+* [Source](https://github.com/adhearsion/ruby_ami)
+* [Documentation](http://rdoc.info/github/adhearsion/ruby_ami/master/frames)
+* [Bug Tracker](https://github.com/adhearsion/ruby_ami/issues)
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  * If you want to have your own version, that is fine but bump version in a commit by itself so I can ignore when I pull
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2011 Ben Langfeld, Jay Phillips. MIT licence (see LICENSE for details).

data/Rakefile

@@ -0,0 +1,69 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'ci/reporter/rake/rspec'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rspec_opts = '--color'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rspec_opts = '--color'
+end
+
+require 'cucumber'
+require 'cucumber/rake/task'
+require 'ci/reporter/rake/cucumber'
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = %w{--tags ~@jruby} unless defined?(JRUBY_VERSION)
+end
+
+Cucumber::Rake::Task.new(:wip) do |t|
+  t.cucumber_opts = %w{-p wip}
+end
+
+task :default => [:ragel, :spec, :features]
+task :ci => [:ragel, 'ci:setup:rspec', :spec, 'ci:setup:cucumber', :features]
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+desc "Check Ragel version"
+task :check_ragel_version do
+  ragel_version_match = `ragel --version`.match /(\d)\.(\d)+/
+  abort "Could not get Ragel version! Is it installed? You must have at least version 6.3" unless ragel_version_match
+  big, small = ragel_version_match.captures.map &:to_i
+  if big < 6 || (big == 6 && small < 3)
+    abort "Please upgrade Ragel! You're on version #{ragel_version_match[0]} and must be on 6.3 or later"
+  end
+  if (big == 6 && small < 7)
+    puts "WARNING: A change to Ruby since 1.9 affects the Ragel generated code."
+    puts "WARNING: You MUST be using Ragel version 6.7 or have patched it using"
+    puts "WARNING: the patch found at:"
+    puts "WARNING: http://www.mail-archive.com/ragel-users@complang.org/msg00440.html"
+  end
+end
+
+RAGEL_FILES = %w[lib/ruby_ami/lexer.rl.rb]
+
+desc "Used to regenerate the AMI source code files. Note: requires Ragel 6.3 or later be installed on your system"
+task :ragel => :check_ragel_version do
+  RAGEL_FILES.each do |ragel_file|
+    ruby_file = ragel_file.sub ".rl.rb", ".rb"
+    puts `ragel -n -R #{ragel_file} -o #{ruby_file} 2>&1`
+    raise "Failed generating code from Ragel file #{ragel_file}" if $?.to_i.nonzero?
+  end
+end
+
+desc "Generates a GraphVis document showing the Ragel state machine"
+task :visualize_ragel => :check_ragel_version do
+  RAGEL_FILES.each do |ragel_file|
+    base_name = File.basename ragel_file, ".rl.rb"
+    puts "ragel -V #{ragel_file} -o #{base_name}.dot 2>&1"
+    puts `ragel -V #{ragel_file} -o #{base_name}.dot 2>&1`
+    raise "Failed generating code from Ragel file #{ragel_file}" if $?.to_i.nonzero?
+  end
+end

data/cucumber.yml

@@ -0,0 +1,2 @@
+default: --tags ~@wip
+wip: --wip --tags @wip

data/features/lexer.feature

@@ -0,0 +1,260 @@
+Feature: Lexing AMI
+  As a RubyAMI user
+  I want to lex the AMI protocol
+  So that I can control Asterisk asynchronously
+
+  Scenario: Lexing only the initial AMI version header
+    Given a new lexer
+    And a version header for AMI 1.0
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the version should be set to 1.0
+
+  Scenario: Lexing the initial AMI header and a login attempt
+    Given a new lexer
+    And a version header for AMI 1.0
+    And a normal login success with events
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+
+  Scenario: Lexing the initial AMI header and then a Response:Follows section
+    Given a new lexer
+    And a version header for AMI 1.0
+    And a multi-line Response:Follows body of ragel_description
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the 'follows' body of 1 message received should equal ragel_description
+
+  Scenario: Lexing a Response:Follows section with no body
+    Given a new lexer
+    And a version header for AMI 1.0
+    And a multi-line Response:Follows body of empty_String
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the 'follows' body of 1 message received should equal empty_string
+
+  Scenario: Lexing a multi-line Response:Follows simulating the "core show channels" command
+    Given a new lexer
+    And a version header for AMI 1.0
+    Given a multi-line Response:Follows body of show_channels_from_wayne
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the 'follows' body of 1 message received should equal show_channels_from_wayne
+
+  Scenario: Lexing a multi-line Response:Follows simulating the "core show uptime" command
+    Given a new lexer
+    And a version header for AMI 1.0
+    Given a multi-line Response:Follows response simulating uptime
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the first message received should have a key "System uptime" with value "46 minutes, 30 seconds"
+
+  Scenario: Lexing a Response:Follows section which has a colon not on the first line
+    Given a new lexer
+    And a multi-line Response:Follows body of with_colon_after_first_line
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+    And the 'follows' body of 1 message received should equal with_colon_after_first_line
+
+  @wip
+  Scenario: Lexing an immediate response with a colon in it.
+    Given a new lexer
+    And an immediate response with text "markq        has 0 calls (max unlimited) in 'ringall' strategy (0s holdtime), W:0, C:0, A:0, SL:0.0% within 0s\r\n   No Members\r\n   No Callers\r\n\r\n\r\n\r\n"
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+    And 1 message should be an immediate response with text "markq        has 0 calls (max unlimited) in 'ringall' strategy (0s holdtime), W:0, C:0, A:0, SL:0.0% within 0s\r\n   No Members\r\n   No Callers"
+
+  Scenario: Lexing the initial AMI header and then an "Authentication Required" error.
+    Given a new lexer
+    And a version header for AMI 1.0
+    And an Authentication Required error
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+
+  Scenario: Lexing the initial AMI header and then a Response:Follows section
+    Given a new lexer
+    And a version header for AMI 1.0
+    And a multi-line Response:Follows body of ragel_description
+    And a multi-line Response:Follows body of ragel_description
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the 'follows' body of 2 messages received should equal ragel_description
+
+  Scenario: Lexing a stanza without receiving an AMI header
+    Given a new lexer
+    And a normal login success with events
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+
+  Scenario: Receiving an immediate response as soon as the socket is opened
+    Given a new lexer
+    And an immediate response with text "Immediate responses are so ridiculous"
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+    And 1 message should be an immediate response with text "Immediate responses are so ridiculous"
+
+  Scenario: Receiving an immediate message surrounded by real messages
+    Given a new lexer
+    And a normal login success with events
+    And an immediate response with text "No queues have been created."
+    And a normal login success with events
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 3 messages should have been received
+    And 1 message should be an immediate response with text "No queues have been created."
+
+  Scenario: Receiving a Pong after a simulated login
+    Given a new lexer
+    And a version header for AMI 1.0
+    And a normal login success with events
+    And a Pong response with an ActionID of randomness
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 2 messages should have been received
+
+  Scenario: Ten Pong responses in a row
+    Given a new lexer
+    And 5 Pong responses without an ActionID
+    And 5 Pong responses with an ActionID of randomness
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 10 messages should have been received
+
+  Scenario: A Pong with an ActionID
+    Given a new lexer
+    And a Pong response with an ActionID of 1224469850.61673
+
+    When the buffer is lexed
+
+    Then the first message received should have a key "ActionID" with value "1224469850.61673"
+
+  Scenario: A response containing a floating point value
+    Given a new lexer
+    And a custom stanza named "call"
+    And the custom stanza named "call" has key "ActionID" with value "1224469850.61673"
+    And the custom stanza named "call" has key "Uniqueid" with value "1173223225.10309"
+
+    When the custom stanza named "call" is added to the buffer
+    And the buffer is lexed
+
+    Then the 1st message received should have a key "Uniqueid" with value "1173223225.10309"
+
+  Scenario: Receiving a message with custom key/value pairs
+    Given a new lexer
+    And a custom stanza named "person"
+    And the custom stanza named "person" has key "ActionID" with value "1224469850.61673"
+    And the custom stanza named "person" has key "Name" with value "Jay Phillips"
+    And the custom stanza named "person" has key "Age" with value "21"
+    And the custom stanza named "person" has key "Location" with value "San Francisco, CA"
+    And the custom stanza named "person" has key "x-header" with value "<FooBAR>"
+    And the custom stanza named "person" has key "Channel" with value "IAX2/127.0.0.1/4569-9904"
+    And the custom stanza named "person" has key "I have spaces" with value "i have trailing padding   "
+
+    When the custom stanza named "person" is added to the buffer
+    And the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And the first message received should have a key "Name" with value "Jay Phillips"
+    And the first message received should have a key "ActionID" with value "1224469850.61673"
+    And the first message received should have a key "Name" with value "Jay Phillips"
+    And the first message received should have a key "Age" with value "21"
+    And the first message received should have a key "Location" with value "San Francisco, CA"
+    And the first message received should have a key "x-header" with value "<FooBAR>"
+    And the first message received should have a key "Channel" with value "IAX2/127.0.0.1/4569-9904"
+    And the first message received should have a key "I have spaces" with value "i have trailing padding   "
+
+  Scenario: Executing a stanza that was partially received
+    Given a new lexer
+    And a normal login success with events split into two pieces
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 message should have been received
+
+  Scenario: Receiving an AMI error followed by a normal event
+    Given a new lexer
+    And an AMI error whose message is "Missing action in request"
+    And a normal login success with events
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 AMI error should have been received
+    And the 1st AMI error should have the message "Missing action in request"
+    And 1 message should have been received
+
+  Scenario: Lexing an immediate response
+    Given a new lexer
+    And a normal login success with events
+    And an immediate response with text "Yes, plain English is sent sometimes over AMI."
+    And a normal login success with events
+
+    When the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 3 messages should have been received
+    And 1 message should be an immediate response with text "Yes, plain English is sent sometimes over AMI."
+
+  Scenario: Lexing an AMI event
+    Given a new lexer
+    And a custom event with name "NewChannelEvent" identified by "this_event"
+    And a custom header for event identified by "this_event" whose key is "Foo" and value is "Bar"
+    And a custom header for event identified by "this_event" whose key is "Channel" and value is "IAX2/127.0.0.1:4569-9904"
+    And a custom header for event identified by "this_event" whose key is "AppData" and value is "agi://localhost"
+
+    When the custom event identified by "this_event" is added to the buffer
+    And the buffer is lexed
+
+    Then the protocol should have lexed without syntax errors
+    And 1 event should have been received
+    And the 1st event should have the name "NewChannelEvent"
+    And the 1st event should have key "Foo" with value "Bar"
+    And the 1st event should have key "Channel" with value "IAX2/127.0.0.1:4569-9904"
+    And the 1st event should have key "AppData" with value "agi://localhost"
+
+  Scenario: Lexing an immediate packet with a colon in it (syntax error)
+    Given a new lexer
+    And syntactically invalid immediate_packet_with_colon
+    And a stanza break
+
+    When the buffer is lexed
+
+    Then 0 messages should have been received
+    And the protocol should have lexed with 1 syntax error
+    And the syntax error fixture named immediate_packet_with_colon should have been encountered