sippy_cup 0.2.3 → 0.3.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTBhNThlZWZhZGVlZTgxOWU2YWJjZGFhMmU1MjkzZDc0OTNhNzY0OA==
+    ZTYzYWNiZmNmOTU4NjU5MzBhOTRhZGI4M2ZlZjg5YzBiOWEyZmIzNw==
   data.tar.gz: !binary |-
-    NDJjY2Y0MjNkMjRlNGZmYWM5NzhmZWM3OGIyMzRjNWNlZDkwYzRiNg==
-!binary "U0hBNTEy":
+    NTU0NDIwOWUyZjc5MTRjMzkzOTQwZTNhZWZjNjhlNTMwZmM0N2NhYQ==
+SHA512:
   metadata.gz: !binary |-
-    MzQ5YzIyZTQ2MTE2YTg2ZTI1NTJmYjc4NWQxYjZiODJiZGE4MjhmY2NkMTA0
-    OTA1OWViYTE2NzM0ZjQ1NTViMzM5ZDRjNTRlZTY1Mjk0YmUyMzgwYTk2OTI0
-    ZDRiM2Y3MDE5YjkxZmQ4NzJhYTk2YWM3ODJjNTk1MGVmMDBhZmM=
+    ZWE1NDM0Nzg5OTU0NDAzMDA0MmI3Mjk0YjY1MWFkOTMzZDQ4YmU0ZTI0ZDk0
+    N2ViNjlhYWVlOGQ4YTQxOGUxYTQ5NzE0ZjY4Y2ZlNjVlMjBhMTczZmMxZmFh
+    YzAxMzU4MTk4YzYyZWZmN2EyZDRlYjMyYmZlNGYxMGY1NzdlYzg=
   data.tar.gz: !binary |-
-    Njg5MjVkNjI3ZjZhN2NiYjVhN2ZlM2I3MjA3MTk1YTcyYmY3YTkxNDVjYzE2
-    M2Y5YTkzNGE4MGJmYjFjMjE1ZDkzNmU4MGU5NmVjOGY2ZjRmMmY5ZDU5NzIz
-    YTMzNDc2ZjhkOTQ2ODJiMGZiYTgyZDhkMzlkYzhmYTNmYzRjMTU=
+    MmRiYTBlMjc4MzUxMjAwZjdmZGJjYWY1MDNjNGM2MTU5ZTEyNjk2MWE2ZTgy
+    NWE1ZDM2YTQzNmYyZDg0NDUwNTk0NDEzZWZhYTg0OWIxNGY4NzIwMTQxNWM0
+    MDk0MTEyZDhhYzIzNjU1YjIwMDMyYjU4ODJlNTkxMDI5YjZmZDk=

data/.gitignore

@@ -2,3 +2,6 @@
 .DS_Store
 *.gem
 /spec/reports/
+Gemfile.lock
+.ruby-gemset
+tmp/

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: 2.0.0
+    - rvm: jruby-19mode
+    - rvm: rbx-19mode
+    - rvm: ruby-head
+notifications:
+  irc: "irc.freenode.org#adhearsion"

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# develop
+
+# [0.3.0](https://github.com/bklang/sippy_cup/compare/v0.2.3...v0.3.0)
+* Feature: A whole lot more documentation, test coverage and cleaner internals.
+* Feature: Added a :transport_mode option that will add the -t switch to SIPp for setting TCP or other UDP modes.
+* Feature: A YAML manifest may now reference a SIPp scenario (and media) on disk rather than providing steps.
+* Feature: A media port may be specified as `:media_port` in the manifest or at runtime.
+* Feature: API for validation of scenarios in manifests.
+* Feature: Handle SIPp exit codes with clean exceptions.
+* Feature: Allow passing arbitary headers in an INVITE
+* Change: AVP is now AVPF in SDP.
+* Change: Rake tasks for executing scenarios are removed.
+* Change: Running and compiling scenarios are now separate concepts.
+  * `-c` on the CLI writes a YAML manifest to disk as SIPp XML and PCAP media. `-r` executes a YAML manifest and does not write to disk.
+  * XML scenarios may be referenced in a YAML manifest using the `scenario:` and `media:` keys, providing paths.
+  * `Runner` now takes a `Scenario` which it executes using SIPp via a temporary local-disk export. Most options passed to `Runner.new` are now properties of Scenario and can be specified in the YAML manifest. `Runner` no longer executes a scenario by path.
+* Bugfix/Security: Don't symbolise untrusted data (YAML manifests).
+* Bugfix: Allow the `sleep` step to take fractional seconds.
+* Bugfix: Proxy full SIPp output to terminal by default.
+
 # [0.2.3](https://github.com/bklang/sippy_cup/compare/v0.2.2...v0.2.3)
 * Bugfix: Handle file extensions .yaml and .yml equally (#21)
 * Bugfix: Fix missing Logger constant (#20)

data/Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem 'rake'

data/Guardfile

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

data/README.markdown

@@ -1,3 +1,9 @@
+[![Gem Version](https://badge.fury.io/rb/sippy_cup.png)](https://rubygems.org/gems/sippy_cup)
+[![Build Status](https://secure.travis-ci.org/mojolingo/sippy_cup.png?branch=master)](http://travis-ci.org/mojolingo/sippy_cup)
+[![Dependency Status](https://gemnasium.com/mojolingo/sippy_cup.png?travis)](https://gemnasium.com/mojolingo/sippy_cup)
+[![Code Climate](https://codeclimate.com/github/mojolingo/sippy_cup.png)](https://codeclimate.com/github/mojolingo/sippy_cup)
+[![Coverage Status](https://coveralls.io/repos/mojolingo/sippy_cup/badge.png?branch=master)](https://coveralls.io/r/mojolingo/sippy_cup)
+
 # Sippy Cup
 
 ## Overview
@@ -87,14 +93,16 @@ steps:
 
 Both `source` and `destination` above may be optionally supplied with a port number, eg. `192.0.2.200:5061`
 
-Next, compile and run the scenario:
+Next, execute the scenario:
 
 ```Shell
-$ sippy_cup -cr my_test_scenario.yml
-Compiling media to /Users/bklang/src/sippy_cup/my_test_scenario.pcap...done.
-Compiling scenario to /Users/bklang/src/sippy_cup/my_test_scenario.xml...done.
-"Preparing to run SIPp command: sudo sipp -i 192.0.2.15 -p 8836 -sf /Users/bklang/src/sippy_cup/my_test_scenario.xml -l 10 -m 20 -r 5 -s 1 > /dev/null 2>&1"
-$
+$ sippy_cup -r my_test_scenario.yml
+I, [2013-09-30T14:48:08.388106 #9883]  INFO -- : Preparing to run SIPp command: sudo sipp -i 192.0.2.15 -p 8836 -sf /var/folders/n4/dpzsp6_95tb3c4sp12xj5wdr0000gn/T/scenario20130930-9883-1crejcw -l 10 -m 20 -r 5 -s 1 192.0.2.200
+Password:
+
+...snip...
+
+I, [2013-09-30T14:48:16.728712 #9883]  INFO -- : Test completed successfully.
 ```
 
 ### Example embedding SIPp in another Ruby process
@@ -121,20 +129,13 @@ end
 scenario.compile!
 ```
 
-The above code can either be executed as a standalone Ruby script and run with SIPp, or it can be compiled and run using rake tasks by inserting the following code into your Rakefile:
-```Ruby
-require 'sippy_cup/tasks'
-```
-
-Then running the rake task `rake sippy_cup:compile[sippy_cup.rb]`
-
-And finally running `rake sippy_cup:run[sippy_cup.yml]` to execute the scenario.
+The above code can be executed as a standalone Ruby script and the resulting scenario file run with SIPp.
 
 ## Customize Your Scenarios
 
 ### Available Scenario Steps
 
-Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/reference.html) as optional arguments.
+Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/reference.html) as optional arguments. For a full list of available steps, see the [API documentation](http://rubydoc.info/gems/sippy_cup/SippyCup/Scenario).
 
 * `sleep <seconds>` Wait a specified number of seconds
 * `invite` Send a SIP INVITE to the specified target
@@ -155,28 +156,27 @@ Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/re
 
 Don't want your scenario to end up in the same directory as your script? Need the filename to be different than the scenario name? No problem!
 
-For the `sippy_cup` YAML specification, use `scenario`:
+For the `sippy_cup` manifest, use `filename`:
 
 ```YAML
 ---
-scenario: /path/to/scenario.xml
+filename: /path/to/somewhere
 ```
 
 Or, in Ruby:
 
 ```Ruby
-my_opts = { source: '192.168.5.5:10001', destination: '10.10.0.3:19995', filename: '/path/to/somewhere' }
-s = SippyCup::Scenario.new 'SippyCup', my_opts do
+s = SippyCup::Scenario.new 'SippyCup', source: '192.168.5.5:10001', destination: '10.10.0.3:19995', filename: '/path/to/somewhere' do
   # scenario definitions here...
 end
+s.compile!
 ```
 
-This will create the files `somewhere.xml`, `somewhere.pcap`, and `somewhere.yml` in the `/path/to/` directory.
+This will create the files `somewhere.xml` and `somewhere.pcap` in the `/path/to/` directory.
 
 ### Customizing the Test Run
 
-
-Each parameter has an impact on the test, and may either be changed once the YAML file is generated or specified in the options hash for `SippyCup::Scenario.new`. In addition to the default parameters, some additional parameters can be set:
+Each parameter has an impact on the test, and may either be changed once the XML file is generated or specified in the options hash for `SippyCup::Scenario.new`. In addition to the default parameters, some additional parameters can be set:
 <dl>
   <dt>stats_file</dt>
   <dd>Path to a file where call statistics will be stored in a CSV format, defaults to not storing stats</dd>
@@ -188,10 +188,10 @@ Each parameter has an impact on the test, and may either be changed once the YAM
   <dd>SIP username to use. Defaults to "1" (as in 1@127.0.0.1)</dd>
 
   <dt>full_sipp_output</dt>
-  <dd>By default, SippyCup will hide SIPp's command line output while running a scenario. Set this parameter to `true` to see full command line output</dd>
+  <dd>By default, SippyCup will show SIPp's command line output while running a scenario. Set this parameter to `false` to hide full command line output</dd>
 
-  <dt>rtcp_port</dt>
-  <dd>By default, SIPp assigns RTCP ports dynamically. However, if there is a need for a static RTCP port (say, for data collection purposes), it can be done by supplying a port number here.</dd>
+  <dt>media_port</dt>
+  <dd>By default, SIPp assigns RTP ports dynamically. However, if there is a need for a static RTP port (say, for data collection purposes), it can be done by supplying a port number here.</dd>
 
   <dt>scenario_variables</dt>
   <dd>If you're using sippy_cup to run a SIPp XML file, there may be CSV fields in the scenario ([field0], [field1], etc.). Specify a path to a CSV file containing the required information using this option. (File is semicolon delimeted, information can be found [here](http://sipp.sourceforge.net/doc/reference.html#inffile).)</dd>
@@ -202,14 +202,14 @@ Each parameter has an impact on the test, and may either be changed once the YAM
 With Sippy Cup, you can add additional attributes to each step of the scenario:
 
 ```Ruby
-#This limits the amount of time the server has to reply to an invite (3 seconds)
+# This limits the amount of time the server has to reply to an invite (3 seconds)
 s.receive_answer timeout: 3000
 
-#You can override the default 'optional' parameters
+# You can override the default 'optional' parameters
 s.receive_ringing optional: false
 s.receive_answer optional: true
 
-#Let's combine multiple attributes...
+# Let's combine multiple attributes...
 s.receive_answer timeout: 3000, crlf: true
 ```
 

data/Rakefile

@@ -1,6 +1,5 @@
 require 'rspec/core/rake_task'
-require 'ci/reporter/rake/rspec'
 
 RSpec::Core::RakeTask.new(:spec)
-task :spec => ['ci:setup:rspec']
-task :default => [:spec]
+
+task :default => :spec

data/bin/sippy_cup

@@ -6,9 +6,8 @@ require 'getoptlong'
 def usage
   puts "#{$0} [OPTS] </path/to/sippy_cup_definition.yml>"
   puts
-  puts "--compile, -c  Compile the given scenario YAML to XML and PCAP"
-  puts "--run, -r      Run the scenario. If used without -c, must supply a previously"
-  puts "               compiled SippyCup file"
+  puts "--compile, -c  Compile the given scenario manifest to XML and PCAP"
+  puts "--run, -r      Run the scenario"
   puts "--help, -h     Print this usage information"
   puts "--version, -V  Print SippyCup version"
 end
@@ -20,16 +19,14 @@ opts = GetoptLong.new(
   ['--version', '-V', GetoptLong::NO_ARGUMENT]
 )
 
-@compile = false
-@run = false
+compile = false
+run = false
 opts.each do |opt, arg|
   case opt
   when '--compile'
-    @compile = true
-    @definition_file = arg
+    compile = true
   when '--run'
-    @run = true
-    @compiled_file = arg
+    run = true
   when '--help'
     usage
     exit 0
@@ -41,38 +38,31 @@ opts.each do |opt, arg|
 end
 
 unless ARGV.count == 1
-  puts "ERROR: Must supply the SippyCup definition file"
+  puts "ERROR: Must supply the SippyCup manifest file"
   puts
   usage
   exit 1
 end
 
-@definition_file = ARGV.shift
+manifest_path = ARGV.shift
 
-unless File.readable? @definition_file
-  puts "ERROR: Unable to read definition file"
+unless File.readable? manifest_path
+  puts "ERROR: Unable to read manifest file"
   puts
   usage
   exit 1
 end
 
-unless @compile || @run
+unless compile || run
   puts "No action (compile or run) specified. Exiting."
   usage
   exit 1
 end
 
-@definition = YAML.load File.read @definition_file
+scenario = SippyCup::Scenario.from_manifest File.read(manifest_path), input_filename: manifest_path
+scenario.compile! if compile
 
-unless @definition.has_key? :scenario
-  @definition[:scenario] = @definition_file.gsub /\.ya?ml$/, ''
+if run
+  runner = SippyCup::Runner.new scenario
+  runner.run
 end
-unless @definition.has_key? :name
-  @definition[:name] = @definition[:scenario]
-end
-
-
-runner = SippyCup::Runner.new @definition
-runner.compile if @compile
-runner.run if @run
-

data/lib/sippy_cup/media.rb

@@ -37,7 +37,7 @@ module SippyCup
 
       @sequence.each do |input|
         action, value = get_step input
-        
+
         case action
         when 'silence'
           # value is the duration in milliseconds
@@ -85,7 +85,9 @@ module SippyCup
       end
       @pcap_file
     end
+
   private
+
     def get_step(input)
       action, value = input.split ':'
       raise "Invalid Sequence: #{input}" unless VALID_STEPS.include? action

data/lib/sippy_cup/runner.rb

@@ -1,75 +1,173 @@
-require 'yaml'
 require 'logger'
-require 'active_support/core_ext/hash'
 
+#
+# Service object to oversee the execution of a Scenario
+#
 module SippyCup
   class Runner
     attr_accessor :sipp_pid
-    attr_accessor :logger
 
-    def initialize(opts = {})
-      @options = ActiveSupport::HashWithIndifferentAccess.new opts
+    #
+    # Create a runner from a scenario
+    #
+    # @param [Scenario, XMLScenario] scenario The scenario to execute
+    # @param [Hash] opts Options to modify the runner
+    # @option opts [optional, true, false] :full_sipp_output Whether or not to copy SIPp's stdout/stderr to the parent process. Defaults to true.
+    # @option opts [optional, Logger] :logger A logger to use in place of the internal logger to STDOUT.
+    # @option opts [optional, String] :command The command to execute. This is mostly available for testing.
+    #
+    def initialize(scenario, opts = {})
+      @scenario = scenario
+      @scenario_options = @scenario.scenario_options
+
+      defaults = { full_sipp_output: true }
+      @options = defaults.merge(opts)
+
+      @command = @options[:command]
       @logger = @options[:logger] || Logger.new(STDOUT)
     end
 
-    def compile
-      raise ArgumentError, "Must provide scenario steps" unless @options[:steps]
-
-      scenario_opts = {source: @options[:source], destination: @options[:destination]}
-      scenario_opts[:filename] = @options[:filename] if @options[:filename]
-      scenario = SippyCup::Scenario.new @options[:name].titleize, scenario_opts
-      @options[:steps].each do |step|
-        instruction, arg = step.split ' ', 2
-        if arg && !arg.empty?
-          # Strip leading/trailing quotes if present
-          arg.gsub!(/^'|^"|'$|"$/, '')
-          scenario.send instruction.to_sym, arg
-        else
-          scenario.send instruction
+    # Runs the loaded scenario using SIPp
+    #
+    # @raises Errno::ENOENT when the SIPp executable cannot be found
+    # @raises SippyCup::ExitOnInternalCommand when SIPp exits on an internal command. Calls may have been processed
+    # @raises SippyCup::NoCallsProcessed when SIPp exit normally, but has processed no calls
+    # @raises SippyCup::FatalError when SIPp encounters a fatal failure
+    # @raises SippyCup::FatalSocketBindingError when SIPp fails to bind to the specified socket
+    # @raises SippyCup::SippGenericError when SIPp encounters another type of error
+    #
+    # @return Boolean true if execution succeeded without any failed calls, false otherwise
+    #
+    def run
+      @input_files = @scenario.to_tmpfiles
+
+      @logger.info "Preparing to run SIPp command: #{command}"
+
+      exit_status, stderr_buffer = execute_with_redirected_streams
+
+      final_result = process_exit_status exit_status, stderr_buffer
+
+      if final_result
+        @logger.info "Test completed successfully!"
+      else
+        @logger.info "Test completed successfully but some calls failed."
+      end
+      @logger.info "Statistics logged at #{File.expand_path @scenario_options[:stats_file]}" if @scenario_options[:stats_file]
+
+      final_result
+    ensure
+      cleanup_input_files
+    end
+
+    #
+    # Tries to stop SIPp by killing the target PID
+    #
+    # @raises Errno::ESRCH when the PID does not correspond to a known process
+    # @raises Errno::EPERM when the process referenced by the PID cannot be killed
+    #
+    def stop
+      Process.kill "KILL", @sipp_pid if @sipp_pid
+    end
+
+  private
+
+    def command
+      @command ||= begin
+        command = "sudo sipp"
+        command_options.each_pair do |key, value|
+          command << (value ? " -#{key} #{value}" : " -#{key}")
         end
+        command << " #{@scenario_options[:destination]}"
       end
-      scenario.compile!
     end
 
-    def prepare_command
-      [:scenario, :source, :destination, :max_concurrent, :calls_per_second, :number_of_calls].each do |arg|
-        raise ArgumentError, "Must provide #{arg}!" unless @options[arg]
+    def command_options
+      options = {
+        i: @scenario_options[:source],
+        p: @scenario_options[:source_port] || '8836',
+        sf: @input_files[:scenario].path,
+        l: @scenario_options[:max_concurrent],
+        m: @scenario_options[:number_of_calls],
+        r: @scenario_options[:calls_per_second],
+        s: @scenario_options[:from_user] || '1'
+      }
+
+      options[:mp] = @scenario_options[:media_port] if @scenario_options[:media_port]
+
+      if @scenario_options[:stats_file]
+        options[:trace_stat] = nil
+        options[:stf] = @scenario_options[:stats_file]
+        options[:fd] = @scenario_options[:stats_interval] || 1
       end
-      command = "sudo sipp"
-      source_port = @options[:source_port] || '8836'
-      sip_user = @options[:sip_user] || '1'
-      command << " -i #{@options[:source]} -p #{source_port} -sf #{File.expand_path @options[:scenario]}.xml"
-      command << " -l #{@options[:max_concurrent]} -m #{@options[:number_of_calls]} -r #{@options[:calls_per_second]}"
-      command << " -s #{sip_user}"
-      if @options[:stats_file]
-        stats_interval = @options[:stats_interval] || 1
-        command << " -trace_stat -stf #{@options[:stats_file]} -fd #{stats_interval}"
+
+      if @scenario_options[:transport_mode]
+        options[:t] = @scenario_options[:transport_mode]
+      end
+
+      if @scenario_options[:scenario_variables]
+        options[:inf] = @scenario_options[:scenario_variables]
       end
-      command << " -inf #{@options[:scenario_variables]}" if @options[:scenario_variables]
-      command << " #{@options[:destination]}"
-      command << " > /dev/null 2>&1" unless @options[:full_sipp_output]
-      command
+
+      options
     end
 
-    def run
-      command = prepare_command
-      @logger.info "Preparing to run SIPp command: #{command}"
+    def execute_with_redirected_streams
+      rd, wr = IO.pipe
+      stdout_target = @options[:full_sipp_output] ? $stdout : '/dev/null'
+
+      @sipp_pid = spawn command, err: wr, out: stdout_target
 
-      begin
-        @sipp_pid = spawn command
-        Process.wait @sipp_pid
-      rescue Exception => e
-        raise RuntimeError, "Command #{command} failed"
+      stderr_buffer = String.new
+
+      Thread.new do
+        wr.close
+        until rd.eof?
+          buffer = rd.readpartial(1024).strip
+          stderr_buffer += buffer
+          $stderr << buffer if @options[:full_sipp_output]
+        end
       end
 
-      @logger.info "Test completed successfully!" 
-      @logger.info "Statistics logged at #{File.expand_path @options[:stats_file]}" if @options[:stats_file]
+      exit_status = Process.wait2 @sipp_pid.to_i
+
+      rd.close
+
+      [exit_status, stderr_buffer]
     end
 
-    def stop
-      Process.kill "KILL", @sipp_pid if @sipp_pid
-    rescue Exception => e
-      raise RuntimeError, "Killing #{@sipp_pid} failed"
+    def process_exit_status(process_status, error_message = nil)
+      exit_code = process_status[1].exitstatus
+      case exit_code
+      when 0
+        true
+      when 1
+        false
+      when 97
+        raise SippyCup::ExitOnInternalCommand, error_message
+      when 99
+        raise SippyCup::NoCallsProcessed, error_message
+      when 255
+        raise SippyCup::FatalError, error_message
+      when 254
+        raise SippyCup::FatalSocketBindingError, error_message
+      else
+        raise SippyCup::SippGenericError, error_message
+      end
+    end
+
+    def cleanup_input_files
+      @input_files.each_pair do |key, value|
+        value.close
+        value.unlink
+      end
     end
   end
+
+  # The corresponding SIPp error code is listed after the exception
+  class Error < StandardError; end
+  class ExitOnInternalCommand < Error; end # 97
+  class NoCallsProcessed < Error; end # 99
+  class FatalError < Error; end # -1
+  class FatalSocketBindingError < Error; end # -2
+  class SippGenericError < Error; end # 255 and undocumented errors
 end