quaff 0.5.4 → 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d866d33ec2df619a80a00ee7aaaf04d70643370
+  data.tar.gz: f321221c8da956aef23e74104f1fd48abdd2dc02
+SHA512:
+  metadata.gz: 761d0fc337cf7e29d4e3c10b1c83e126cb9f95e750312f08f5cd37f21205fb01dd953bb51b6c87370d9f2f10cfb565895b9e626fd9fea42fa34be71b8f700c27
+  data.tar.gz: edccac0984f874d1590efdf2ec8bbf6e9142d9ffdd90531fa11f2ee40f3c19887aa38cf14fd68ba7d2c30e0be64fbb78e22dfa43e35092f34fbafa6926e214f7

data/lib/auth.rb

@@ -1,7 +1,7 @@
 require 'base64'
 
 module Quaff
-  module Auth
+  module Auth #:nodoc:
     def Auth.gen_nonce auth_pairs, username, passwd, method, sip_uri
       a1 = username + ":" + auth_pairs["realm"] + ":" + passwd
       a2 = method + ":" + sip_uri

data/lib/call.rb

@@ -1,5 +1,6 @@
 # -*- coding: us-ascii -*-
 require 'securerandom'
+require 'timeout'
 require_relative './utils.rb'
 require_relative './sources.rb'
 require_relative './auth.rb'
@@ -29,7 +30,7 @@ class Call
   def initialize(cxn,
                  cid,
                  instance_id=nil,
-                 uri="sip:5557777888@#{Utils::local_ip}",
+                 uri=nil,
                  destination=nil,
                  target_uri=nil)
     @cxn = cxn
@@ -37,14 +38,11 @@ class Call
     @retrans = nil
     @t1, @t2 = 0.5, 32
     @instance_id = instance_id
-    set_default_headers cid, uri, target_uri
-  end
-
-  def change_cid cid
     @cid = cid
-    @cxn.add_call_id @cid
+    set_default_headers cid, uri, target_uri
   end
 
+  # Changes the branch parameter if the Via header, creating a new transaction
   def update_branch via_hdr=nil
     via_hdr ||= get_new_via_hdr
     @last_Via = via_hdr
@@ -56,10 +54,6 @@ class Call
     "SIP/2.0/#{@cxn.transport} #{Quaff::Utils.local_ip}:#{@cxn.local_port};rport;branch=#{Quaff::Utils::new_branch}"
   end
 
-  def create_dialog msg
-    set_callee msg.first_header("Contact")
-  end
-
   def set_callee uri
     if /<(.*?)>/ =~ uri
       uri = $1
@@ -67,7 +61,39 @@ class Call
 
     @sip_destination = "#{uri}"
   end
+  
+  def create_dialog msg
+    if @in_dialog
+      return
+    end
+
+    @in_dialog = true
+
+    uri = msg.first_header("Contact")
+
+    if /<(.*?)>/ =~ uri
+      uri = $1
+    end
+
+    @sip_destination = uri
+
+    unless msg.all_headers("Record-Route").nil?
+      if msg.type == :request
+        @routeset = msg.all_headers("Record-Route")
+      else
+        @routeset = msg.all_headers("Record-Route").reverse
+      end
+    end
+
+  end
 
+  # Sets the Source where messages in this call should be sent to by
+  # default.
+  #
+  # Options:
+  #    :recv_from_this - if true, also listens for any incoming
+  #    messages over this source's connection. (This is only
+  #    meaningful for connection-oriented transports.)
   def setdest source, options={}
     @src = source
     if options[:recv_from_this] and source.sock
@@ -78,7 +104,7 @@ class Call
   def recv_request(method, dialog_creating=true)
     begin
       msg = recv_something
-    rescue
+    rescue Timeout::Error
       raise "#{ @uri } timed out waiting for #{ method }"
     end
 
@@ -97,20 +123,85 @@ class Call
     end
 
     if dialog_creating
-      @in_dialog = true
+      create_dialog msg
+    end
+    msg
+  end
 
-      set_callee msg.first_header("Contact")
-      unless msg.all_headers("Record-Route").nil?
-        @routeset = msg.all_headers("Record-Route")
+  # Waits until the next message comes in, and handles it if it is one
+  # of possible_messages.
+  #
+  # possible_messages is a list of things that can be received.
+  # Elements can be:
+  # * a string representing the SIP method, e.g. "INVITE"
+  # * a number representing the SIP status code, e.g. 200
+  # * a two-item list, containing one of the above and a boolean
+  # value, which indicates whether this message is dialog-creating. by
+  # default, requests are assumed to be dialog-creating and responses
+  # are not.
+  #
+  # For example, ["INVITE", 301, ["ACK", false], [200, true]] is a
+  # valid value for possible_messages.
+  def recv_any_of(possible_messages)
+    begin
+      msg = recv_something
+    rescue Timeout::Error
+      raise "#{ @uri } timed out waiting for one of these: #{possible_messages}"
+    end
+
+    found_match = false
+    dialog_creating = nil
+    
+    possible_messages.each do
+      | what, this_dialog_creating |
+      type = if (what.class == String) then :request else :response end
+      if this_dialog_creating.nil?
+        this_dialog_creating = (type == :request)
+      end
+
+      found_match =
+        if type == :request 
+          msg.type == :request and what == msg.method
+        else
+          msg.type == :response and what == msg.status_code
+        end
+
+      if found_match
+        dialog_creating = this_dialog_creating
+        break
       end
     end
+
+    unless found_match
+      raise((msg.to_s || "Message is nil!"))
+    end
+
+    if msg.type == :request
+      unless @has_To_tag
+        @has_To_tag = true
+        tospec = ToSpec.new
+        tospec.parse(msg.header("To"))
+        tospec.params['tag'] = generate_random_tag
+        @last_To = tospec.to_s
+        @last_From = msg.header("From")
+      end
+    else
+      if @in_dialog
+        @has_To_tag = true
+        @last_To = msg.header("To")
+      end    
+    end
+
+    if dialog_creating
+      create_dialog msg
+    end
     msg
   end
 
   def recv_response(code, dialog_creating=false)
     begin
       msg = recv_something
-    rescue
+    rescue Timeout::Error
       raise "#{ @uri } timed out waiting for #{ code }"
     end
     unless msg.type == :response \
@@ -119,11 +210,7 @@ class Call
     end
 
     if dialog_creating
-      @in_dialog = true
-      set_callee msg.first_header("Contact")
-      unless msg.all_headers("Record-Route").nil?
-        @routeset = msg.all_headers("Record-Route").reverse
-      end
+      create_dialog msg
     end
 
     if @in_dialog
@@ -238,14 +325,13 @@ class Call
 
   def set_default_headers cid, uri, target_uri
     @cseq_number = 1
-    change_cid cid
     @uri = uri
     @last_From = "<#{uri}>;tag=" + generate_random_tag
     @in_dialog = false
     @has_To_tag = false
     update_branch
     @last_To = "<#{target_uri}>"
-    set_callee target_uri if target_uri
+    @sip_destination = target_uri
     @routeset = []
   end
 

data/lib/endpoint.rb

@@ -3,7 +3,7 @@ require 'socket'
 require 'thread'
 require 'timeout'
 require 'resolv'
-require 'digest/md5'
+require 'securerandom'
 #require 'milenage'
 require_relative './sip_parser.rb'
 require_relative './sources.rb'
@@ -11,53 +11,75 @@ require_relative './sources.rb'
 module Quaff
   class BaseEndpoint
     attr_accessor :msg_trace, :uri, :sdp_port, :sdp_socket, :instance_id
-    attr_reader :msg_log
+    attr_reader :msg_log, :local_port
 
+    # Creates an SDP socket bound to an ephemeral port
     def setup_sdp
       @sdp_socket = UDPSocket.new
       @sdp_socket.bind('0.0.0.0', 0)
       @sdp_port = @sdp_socket.addr[1]
     end
 
-    def generate_call_id
-      digest = Digest::MD5.hexdigest(rand(60000).to_s)
-    end
-
+    # Cleans up the endpoint - designed to be overriden by
+    # per-transport subclasses
     def terminate
     end
 
+    # Adds a socket connection to another UA - designed to be
+    # overriden by per-transport subclasses
     def add_sock sock
     end
 
-    def incoming_call *args
-      call_id ||= get_new_call_id
-      puts "Call-Id for endpoint on #{@lport} is #{call_id}" if @msg_trace
-      Call.new(self, call_id, @instance_id, *args)
+    # Retrieves the next unhandled call for this endpoint and returns
+    # a +Call+ object representing it
+    def incoming_call
+      begin
+        call_id = get_new_call_id
+      rescue Timeout::Error
+        raise "#{ @uri } timed out waiting for new incoming call"
+      end
+      
+      puts "Call-Id for endpoint on #{@local_port} is #{call_id}" if @msg_trace
+      Call.new(self, call_id, @instance_id, @uri)
     end
 
+    # Creates a +Call+ object representing a new outbound call
     def outgoing_call to_uri
       call_id = generate_call_id
-      puts "Call-Id for endpoint on #{@lport} is #{call_id}" if @msg_trace
+      puts "Call-Id for endpoint on #{@local_port} is #{call_id}" if @msg_trace
       Call.new(self, call_id, @instance_id, @uri, @outbound_connection, to_uri)
     end
 
-    def create_client(uri, username, password, outbound_proxy, outbound_port=5060)
+    # Not yet ready for use
+    def create_client(uri, username, password, outbound_proxy, outbound_port=5060) # :nodoc:
     end
 
-    def create_server(uri, local_port=5060, outbound_proxy=nil, outbound_port=5060)
-
+    # Not yet ready for use
+    def create_server(uri, local_port=5060, outbound_proxy=nil, outbound_port=5060) # :nodoc:
     end
 
-    def create_aka_client(uri, username, key, op, outbound_proxy, outbound_port=5060)
+    # Not yet ready for use
+    def create_aka_client(uri, username, key, op, outbound_proxy, outbound_port=5060) # :nodoc:
     end
 
+    # Constructs a new endpoint
+    # Params:
+    # +uri+:: The SIP URI of this endpoint
+    # +username+:: The authentication username of this endpoint
+    # +password+:: The authentication password of this endpoint
+    # +local_port+:: The port this endpoint should bind to. Use
+    # ':anyport' to bind to an ephemeral port.
+    # +outbound_proxy+:: The outbound proxy where all requests should
+    # be directed. Optional, but it only makes sense to omit it when
+    # Quaff is emulating a server rather than a client.
+    # +outbound_port+:: The port of the outbound proxy
     def initialize(uri, username, password, local_port, outbound_proxy=nil, outbound_port=5060)
       @msg_log = Array.new
       @uri = uri
       @resolver = Resolv::DNS.new
       @username = username
       @password = password
-      @lport = local_port
+      @local_port = local_port
       initialize_connection
       if outbound_proxy
         @outbound_connection = new_connection(outbound_proxy, outbound_port)
@@ -66,40 +88,26 @@ module Quaff
       start
     end
 
-    def local_port
-        @lport
-    end
-
-    def add_call_id cid
-        @messages[cid] ||= Queue.new
-    end
-
-    def get_new_call_id time_limit=30
-        Timeout::timeout(time_limit) { @call_ids.deq }
-    end
-
-    def get_new_message(cid, time_limit=30)
-      Timeout::timeout(time_limit) { @messages[cid].deq }
-    end
-
-    def mark_call_dead(cid)
-        @messages.delete cid
-        now = Time.now
-        @dead_calls[cid] = now + 30
-        @dead_calls = @dead_calls.keep_if {|k, v| v > now}
-    end
-
-    def send_msg(data, source)
-      @msg_log.push "Endpoint on #{@lport} sending:\n\n#{data.strip}\n\nto #{source.inspect}"
-      puts "Endpoint on #{@lport} sending #{data} to #{source.inspect}" if @msg_trace
+    def send_msg(data, source) # :nodoc:
+      @msg_log.push "Endpoint on #{@local_port} sending:\n\n#{data.strip}\n\nto #{source.inspect}"
+      puts "Endpoint on #{@local_port} sending #{data} to #{source.inspect}" if @msg_trace
         source.send_msg(@cxn, data)
     end
 
-    def set_aka_credentials key, op
+    # Not yet ready for use
+    def set_aka_credentials key, op # :nodoc:
       @kernel = Milenage.Kernel key
       @kernel.op = op
     end
 
+    # Utility method - handles a REGISTER/200 or
+    # REGISTER/401/REGISTER/200 flow to authenticate the subscriber.
+    # Currently only supports SIP Digest authentication. Re-REGISTERs
+    # are not handled; if you need long-running endpoints you should
+    # create a thread to re-REGISTER them yourself.
+    #
+    # Returns the +Message+ representing the 200 OK, or throws an
+    # exception on failure to authenticate successfully.
     def register expires="3600", aka=false
       @reg_call ||= outgoing_call(@uri)
       auth_hdr = Quaff::Auth.gen_empty_auth_header @username
@@ -125,7 +133,42 @@ module Quaff
       register 0
     end
 
+    # Only designed for use by the Call class. Retrieves a new message
+    # on a particular call. If no new message has been received,
+    # blocks for up to time_limit seconds waiting for one. If nothing
+    # arrives, raises a TimeoutError.
+    def get_new_message(cid, time_limit=30) # :nodoc:
+      Timeout::timeout(time_limit) { @messages[cid].deq }
+    end
+
+
+
+    # Flags that a particular call has ended, and any more messages
+    # using it shold be ignored.
+    def mark_call_dead(cid)
+        @messages.delete cid
+        now = Time.now
+        @dead_calls[cid] = now + 30
+        @dead_calls = @dead_calls.keep_if {|k, v| v > now}
+    end
     private
+
+    # Creates a random Call-ID
+    def generate_call_id
+      call_id = SecureRandom::hex
+      add_call_id call_id
+      return call_id
+    end
+
+    def get_new_call_id time_limit=30
+        Timeout::timeout(time_limit) { @call_ids.deq }
+    end
+
+    # Sets up the internal structures needed to handle calls for a new Call-ID.
+    def add_call_id cid
+        @messages[cid] ||= Queue.new
+    end
+
     def initialize_queues
         @messages = {}
         @call_ids = Queue.new
@@ -142,8 +185,8 @@ module Quaff
     end
 
     def queue_msg(msg, source)
-      @msg_log.push "Endpoint on #{@lport} received:\n\n#{msg.to_s.strip}\n\nfrom #{source.inspect}"
-      puts "Endpoint on #{@lport} received #{msg} from
+      @msg_log.push "Endpoint on #{@local_port} received:\n\n#{msg.to_s.strip}\n\nfrom #{source.inspect}"
+      puts "Endpoint on #{@local_port} received #{msg} from
                           ##{source.inspect}" if @msg_trace
       msg.source = source
       cid = @parser.message_identifier msg
@@ -160,17 +203,6 @@ module Quaff
   class TCPSIPEndpoint < BaseEndpoint
     attr_accessor :sockets
 
-    def initialize_connection
-      if @lport != :anyport
-        @cxn = TCPServer.new(@lport)
-      else
-        @cxn = TCPServer.new(0)
-        @lport = @cxn.addr[1]
-      end
-      @parser = SipParser.new
-      @sockets = []
-    end
-
     def transport
       "TCP"
     end
@@ -194,7 +226,21 @@ module Quaff
 
 
     alias_method :new_connection, :new_source
+
     private
+
+    def initialize_connection
+      if @local_port != :anyport
+        @cxn = TCPServer.new(@local_port)
+      else
+        @cxn = TCPServer.new(0)
+        @local_port = @cxn.addr[1]
+      end
+      @parser = SipParser.new
+      @sockets = []
+    end
+
+
     def recv_msg
         select_response = IO.select(@sockets, [], [], 0) || [[]]
         readable = select_response[0]
@@ -239,13 +285,14 @@ module Quaff
     alias_method :new_connection, :new_source
 
     private
+
     def initialize_connection
       @cxn = UDPSocket.new
-      if @lport != :anyport
-        @cxn.bind('0.0.0.0', @lport)
+      if @local_port != :anyport
+        @cxn.bind('0.0.0.0', @local_port)
       else
         @cxn.bind('0.0.0.0', 0)
-        @lport = @cxn.addr[1]
+        @local_port = @cxn.addr[1]
       end
       @sockets = []
       @parser = SipParser.new

data/lib/sip_parser.rb

@@ -4,7 +4,7 @@ require 'abnf'
 require_relative './message.rb'
 
 module Quaff
-  class SipParser
+  class SipParser # :nodoc:
     attr_reader :state
     def parse_start
       @buf = ""
@@ -99,7 +99,7 @@ module Quaff
 
   end
 
-  class ABNFSipParser
+  class ABNFSipParser # :nodoc:
     include ABNF
 
     # Rules
@@ -227,7 +227,7 @@ module Quaff
     end
   end
 
-  class ToSpec < ABNFSipParser
+  class ToSpec < ABNFSipParser # :nodoc:
     attr_accessor :params, :uri, :displayname, :is_nameaddr
     def initialize
       super

data/lib/sources.rb

@@ -1,21 +1,15 @@
 require 'socket'
 module Quaff
+  # A Source is an abstraction representing an IP
+  # address/port/transport where a SIP message originates from or can
+  # be sent to. It allows users to abstract over TCP and UDP sockets.
   class Source
-    def remote_ip
-      @ip
-    end
-
-    def remote_port
-      @port
-    end
+    attr_reader :ip, :port, :transport, :sock
 
+    # Designed to be overriden by subclasses
     def close cxn
     end
 
-    def sock
-      nil
-    end
-
     def to_s
       "#{@ip}:#{@port} (#{@transport})"
     end
@@ -41,7 +35,6 @@ module Quaff
 
 
   class TCPSource < Source
-    attr_reader :sock
 
     def initialize ip, port
       @transport = "TCP"

data/lib/utils.rb

@@ -3,7 +3,7 @@ require 'facter'
 
 module Quaff
 
-module Utils
+module Utils #:nodoc:
 def Utils.local_ip
   Facter.value("ipaddress")
 end

metadata

@@ -1,62 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: quaff
 version: !ruby/object:Gem::Version
-  version: 0.5.4
-  prerelease: 
+  version: 0.6.0
 platform: ruby
 authors:
 - Rob Day
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-10 00:00:00.000000000 Z
+date: 2014-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facter
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.7.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.7.3
 - !ruby/object:Gem::Dependency
   name: milenage
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: abnf-parsing
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.2.0
 description: A Ruby library for writing SIP test scenarios
@@ -65,37 +58,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/utils.rb
+- lib/call.rb
 - lib/endpoint.rb
 - lib/message.rb
-- lib/call.rb
-- lib/auth.rb
+- lib/quaff.rb
 - lib/sources.rb
+- lib/utils.rb
 - lib/sip_parser.rb
-- lib/quaff.rb
+- lib/auth.rb
 homepage: http://github.com/rkday/quaff
 licenses:
 - GPL3
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.1.11
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Quaff
 test_files: []