Sipper 1.1.3

data/sipper/README.rb

@@ -0,0 +1,26 @@
+# == Sipper API documentation
+# ----
+# = What is Sipper?
+#
+# SIPr pronounced as Sipper is a SIP application testing framework that enables the developer 
+# and tester write new and complex test cases with extreme ease. 
+# While SIP applications are becoming more and more complex and feature rich the test tools have
+# not been able to keep pace with them. 
+# Sipper was developed out of the necessity to test ever evolving SIP protocol and 
+# multi-faceted applications spanning SIP and Web. 
+# As new APIs for SIP application development made writing SIP applications accessible, we felt that
+# writing tests for them, which are the cornerstone of agile development processes, should be even
+# simpler. Sipper is our solution to that problem.
+# Sipper is ideally suited for for feature, interop, regression, acceptance and field simulation. 
+# It has Servlet style API that ranges from extremely simple to very feature
+# rich and powerful. 
+# While on one hand you can write simple test cases and controllers with very few lines of scripts,
+# you can go further down the API depth and progressively control any aspect of SIP stack. 
+#
+# == Getting started
+# The best place to get started on Sipper is to read the first few chapters of the Sipper book,
+# freely available from the Sipper website, also refer to FAQs when in doubt, if you need help
+# with a test case of Sipper syntax then join the community at Sipper mailing list. All of these
+# are accesible from http://sipper.agnity.com
+#
+ 

data/sipper/b2bua_controller.rb

@@ -0,0 +1,163 @@
+require 'base_controller'
+
+module SIP
+
+  class B2buaController < SIP::BaseController
+    
+    # Gets or creates a peer b2bua leg (session). The session passed in as the 
+    # argument becomes the anchor leg which is the main leg. 
+    def get_or_create_peer_session(session, rip=SipperConfigurator[:DefaultRIP], 
+          rp=SipperConfigurator[:DefaultRP] )
+      peer = get_peer_session(session)
+      peer = create_peer_session(session, rip, rp) unless peer
+      session.offer_answer = nil
+      peer.offer_answer = nil
+      peer
+    end
+    
+    def create_peer_session(session, rip=SipperConfigurator[:DefaultRIP], 
+          rp=SipperConfigurator[:DefaultRP] )
+      # todo take care of TCP
+      peer = create_udp_session(rip, rp)
+      session[:_sipper_b2b_peer] = peer
+      peer[:_sipper_b2b_peer] = session
+      peer.use_b2b_session_lock_from(session)
+      peer
+    end
+    
+    def get_peer_session(session)
+      session[:_sipper_b2b_peer]
+    end
+    
+    
+    # While linking the two sessions to create a b2bua the first 
+    # argument is treated as the main or anchor leg. 
+    def link_sessions(session1, session2)
+      unlink_session(session1, session1[:_sipper_b2b_peer]) if session1[:_sipper_b2b_peer]
+      session1[:_sipper_b2b_peer] = session2
+      session2[:_sipper_b2b_peer] = session1
+      session2.use_b2b_session_lock_from(session1)
+    end
+    
+    # Unlinking removes the b2bua association. 
+    def unlink_sessions(session1, session2)
+      if session1.b2b_anchor_leg?
+        anchor_leg = session1
+        peer_leg = session2
+      else
+        anchor_leg = session2
+        peer_leg = session1
+      end
+      anchor_leg[:_sipper_b2b_peer] = nil
+      peer_leg[:_sipper_b2b_peer] = nil
+      peer_leg.revert_to_local_session_lock
+    end
+    
+    
+    # Creates the b2bua request based on the original request. Also creates the 
+    # peer session if it does not already exist. 
+    def create_b2bua_request(session, orig_request=session.irequest, rip=SipperConfigurator[:DefaultRIP], 
+          rp=SipperConfigurator[:DefaultRP])
+      peer_session = get_or_create_peer_session(session, rip, rp)
+      if peer_session.initial_state?
+        r = peer_session.create_initial_request(orig_request.method, orig_request.uri)
+        r.copy_from(orig_request, :from, :to, :route, :content, :content_type)
+        r.from.tag = "3"
+      else
+        if(orig_request.method == "CANCEL")
+          r = peer_session.create_cancel
+        elsif(orig_request.method == "ACK")
+          r = peer_session.create_ack
+        else
+          r = peer_session.create_subsequent_request(orig_request.method)
+        end  
+        r.copy_from(orig_request, :content, :content_type)
+      end  
+      return r
+    end
+    
+    
+    # Creates a b2bua response based on an original response. 
+    # If there is no peer session then this fails. 
+    def create_b2bua_response(session, orig_response=session.iresponse)
+      peer_session = get_peer_session(session)
+      if peer_session
+        r = peer_session.create_response(orig_response.code)
+        r.copy_from(orig_response,  :content, :content_type)
+        return r
+      else
+        logw("No peer session found, cannot create the response")
+        raise "Unable to create response"
+      end 
+    end
+    
+    # Invalidates this b2bua sessions. 
+    def invalidate_sessions(session, flag=true)
+      peer_session = get_peer_session(session)
+      peer_session.invalidate(flag) if peer_session
+      session.invalidate(flag)
+    end
+    
+    
+    # Transparently passes / relays the request given a peer session 
+    # exists. 
+    def relay_request(session)
+      peer_session = get_peer_session(session)
+      if peer_session
+        r = create_b2bua_request(session)
+        peer_session.send(r)
+      else
+        logw("No peer session found, cannot relay the request")
+        raise "Unable to relay the request" 
+      end
+    end
+    
+    # Transparently passes / relays the response given a peer session 
+    # exists. 
+    def relay_response(session)
+      peer_session = get_peer_session(session)
+      if peer_session
+        r = create_b2bua_response(session)
+        peer_session.send(r)
+      else
+        logw("No peer session found, cannot relay the response")
+        raise "Unable to relay the response" 
+      end
+    end
+    
+    
+    # Marks this b2bua as transparent which allows the relaying of requests and 
+    # responses between legs without any controller involvement. 
+    def go_transparent(session, state=true)
+      session[:_sipper_b2b_transparent] = state
+      peer_session = get_peer_session(session)
+      peer_session[:_sipper_b2b_transparent] = state if peer_session
+    end
+    
+    
+    # if there exists a peer session then we transparently send the request as a b2bua
+    # if transparent flag is on. 
+    def on_request(session)
+      peer_session = get_peer_session(session)
+      if peer_session && session[:_sipper_b2b_transparent]
+        peer_session.request_with(session.irequest.method)
+      else
+        super
+      end
+    end
+    
+    
+    # if there exists a peer session then we transparently pass the response as a b2bua
+    # if transparent flag is true 
+    def on_response(session)
+      peer_session = get_peer_session(session)
+      if peer_session && session[:_sipper_b2b_transparent]
+        peer_session.respond_with(session.iresponse.code)
+      else
+        super
+      end
+    end
+    
+    
+  end
+end

data/sipper/b2bua_session_mixin.rb

@@ -0,0 +1,24 @@
+module B2buaSessionMixin
+  # Used exclusively for setting of a common b2bua lock to avoid deadlocks. 
+  def use_b2b_session_lock_from(orig_session)
+    @sq_lock = orig_session._get_sq_lock
+    @non_anchor_leg = true
+  end
+  
+  def revert_to_local_session_lock
+    if @non_anchor_leg
+      @sq_lock = ["free"] 
+      @sq_lock.extend(MonitorMixin) 
+      @non_anchor_leg = false
+    end
+  end  
+  
+  def b2b_anchor_leg?
+    if @non_anchor_leg
+      false
+    else
+      true
+    end
+  end
+  
+end

data/sipper/base_controller.rb

@@ -0,0 +1,425 @@
+# Here is where a lot of magic will happen, this will enable a lot of 
+# controller functionality
+
+require 'sip_logger'
+require 'util/sipper_util'
+require 'response'
+require 'request'
+require 'session'
+require 'detached_session'
+require 'util/locator'
+
+module SIP
+  class BaseController
+    include SipLogger
+    
+    # civ set for each individual controllers
+    @sol = false
+    @tr_usage = nil
+    @tr_timers = nil
+    @sess_timer = nil
+    @tr_handlers = nil
+    @sess_timer = nil
+    @sess_limit = nil
+    @t2xx_usage = nil
+    @t1xx_retran_usage = nil
+    @t2xx_timers = nil
+    @t1xx_timers = nil
+    @header_order = nil
+    @pre_existing_rs = nil
+    @compact_headers = nil
+    @session_record = nil
+     
+    def self.start_on_load(val)
+      @sol = SipperUtil.boolify(val)  
+    end
+    
+    def self.start_on_load?
+      @sol
+    end
+
+    # The transaction usage hash setting is like a modifier in the 
+    # controller. The setting is exactly same as the configuration setting
+    # eg transaction_usage :use_transactions=>true, :use_ict=>false, :use_nict=>true
+    # 
+    def self.transaction_usage(hash)
+      @tr_usage = hash
+    end
+   
+    def self.get_transaction_usage
+      @tr_usage
+    end
+    
+    # The transaction timers can be set at the controller level which override the 
+    # default timer configuration. Eg. usage
+    #   transaction_timers :t1=>100, :ta=200
+    # Here the modifier is setting the T1 timer value to 100 msec and TimerA to 200 msec. 
+    def self.transaction_timers(hash)
+      @tr_timers = hash
+    end
+    
+    def self.get_transaction_timers
+      @tr_timers
+    end
+    
+    # value can be msg-info or msg-debug
+    def self.session_record(val)
+      @session_record = val.to_s  
+    end
+    
+    def self.get_session_record
+      @session_record
+    end
+    
+    # transaction_handlers :Ict=>MyIctHandler, :Nict=>MyNictHandler, :Base=>CatchAllHandler
+    def self.transaction_handlers(hash)
+      @tr_handlers = hash
+    end
+    
+    def self.get_transaction_handlers
+      @tr_handlers
+    end
+    
+    
+    # The session timer for session invalidation, the default is taken from the configuration
+    # :SessionTimer
+    def self.session_timer(val)
+      @sess_timer = val
+    end
+    
+    def self.get_session_timer
+      @sess_timer
+    end
+    
+    # the upper limit of session lifetime, defaults to :SessionLimit from configuration. 
+    def self.session_limit(val)
+      @sess_limit = val
+    end
+    
+    def self.get_session_limit
+      @sess_limit
+    end
+    
+    def self.t2xx_usage(val)
+      @t2xx_usage = val  
+    end
+    
+    def self.get_t2xx_usage
+      @t2xx_usage
+    end
+    
+    def self.t1xx_retran_usage(val)
+      @t1xx_retran_usage = val  
+    end
+    
+    def self.get_t1xx_retran_usage
+      @t1xx_retran_usage
+    end
+    
+    # the hash of 3 timer values that affect 2xx retransmissions for UAS 
+    # i.e {:Start=>100, :Cap=>400, :Limit=>1600} that roughly 
+    # correspond with T1, T2 and 64*T1 respectively, which are also the
+    # defaults. The argument hash doesnt have to be all the three values 
+    # but any that are required to be overridden.
+    def self.t2xx_timers(hash)
+      @t2xx_timers = hash
+    end
+    
+    def self.get_t2xx_timers
+      @t2xx_timers
+    end
+    
+    def self.t1xx_timers(hash)
+      @t1xx_timers = hash
+    end
+    
+    def self.get_t1xx_timers
+      @t1xx_timers
+    end
+    
+    
+    def self.header_order(*arr)
+      if arr[0].is_a?(Array)
+        @header_order = arr[0] 
+      else
+        @header_order = arr
+      end
+    end
+    
+    def self.get_header_order
+      @header_order
+    end
+    
+    # Directive for setting compact headers for outgoing requests for 
+    # this controller. The headers can be defined by their sipper symbols
+    # like :call_id and :via or you can chose to have :all_possible in which 
+    # Sipper use compact form for all headers that have a compact form. 
+    def self.use_compact_headers(*arr)
+      if arr[0].is_a?(Array)
+        @compact_headers = arr[0] 
+      else
+        @compact_headers = arr
+      end
+    end
+    
+    def self.get_compact_headers
+      @compact_headers
+    end
+    
+    # Directive for setting the prexisting route set at the controller level. 
+    def self.pre_existing_route_set(*arr)
+      if arr[0].is_a?(Array)
+        @pre_existing_rs = arr[0] 
+      else
+        @pre_existing_rs = arr
+      end
+    end
+    
+    def self.get_pre_existing_route_set
+      @pre_existing_rs
+    end
+    #---------------------------------------------------------------------------
+    
+    
+    def name
+      self.class.name
+    end
+    
+    def logi(m)
+      SipLogger['siplog::sip_basecontroller'].info("[#{name}] "+m)
+    end
+    
+    def logd(m)
+      SipLogger['siplog::sip_basecontroller'].debug("[#{name}] "+m)
+    end
+    
+    def logw(m)
+      SipLogger['siplog::sip_basecontroller'].warn("[#{name}] "+m)
+    end
+   
+    def loge(m)
+      SipLogger['siplog::sip_basecontroller'].error("[#{name}] "+m)
+    end
+    
+    def logf(m)
+      SipLogger['siplog::sip_basecontroller'].fatal("[#{name}] "+m)
+    end
+   
+   # start method
+   
+    def start
+      logd("Nothing to start")
+      return false
+    end
+    
+   # Response handling
+   
+    def on_response(session)
+      case session.iresponse.code
+      when 100
+        on_trying_res(session)
+      when 101..199
+        on_provisional_res(session)
+      when 200..299
+        on_success_res(session)
+      when 300..399
+        on_redirect_res(session)
+      when 400..699
+        on_failure_res(session)
+      else
+        unknown_response(code)
+      end    
+    end
+    
+    
+    def on_trying_res(session)
+      request_specific_response_dispatch(session, "on_trying_res")
+    end
+    
+    def on_provisional_res(session)
+      request_specific_response_dispatch(session, "on_provisional_res")
+    end
+    
+    def on_success_res(session)
+      request_specific_response_dispatch(session, "on_success_res")
+    end
+    
+    def on_failure_res(session)
+      request_specific_response_dispatch(session, "on_failure_res")
+    end  
+    
+    def on_redirect_res(session)
+      request_specific_response_dispatch(session, "on_redirect_res")
+    end
+    
+    def on_custom_msg(session, custom_msg)
+    end
+    
+    def unknown_response(code)
+      loge("I do not handle response with code #{code}")
+    end
+   
+    # response_method is the string "on_success_res" etc.
+    def request_specific_response_dispatch(session, response_method)
+      request_m = session.iresponse.get_request_method.downcase
+      handler = (sprintf("%s_for_%s", response_method, request_m)).to_sym
+     
+      self.send(handler, session) if self.respond_to?(handler)
+    end
+    
+    # Request handling
+    # 
+     
+    
+    #- Interestingly the benchmark for direct call, m.call and send are
+    #       user     system      total        real
+    #   4.726000   0.000000   4.726000 (  4.757000)
+    #   6.810000   0.030000   6.840000 (  6.870000)
+    #   5.027000   0.000000   5.027000 (  5.027000)
+    # So I am continuing with send mechanism
+    # But perhaps it is still OK to return a boolean from here as we may use it
+    # for some other purposes.
+    def on_request(session)
+      logd("In base_controller on_request for call #{session.call_id}")
+      m = ("on_" + session.irequest.method.downcase).to_sym
+      return self.send(m, session)
+    end 
+   
+   
+    def on_media_event(session)
+      if session.imedia_event.class == Media::SmReply
+        self.on_media_reply(session)
+      else  
+        case session.imedia_event.event
+        when 'AUDIOSTARTED'
+          self.on_media_audio_started(session)
+        when 'AUDIOSTOPPED'
+          self.on_media_audio_stopped(session)
+        when 'DTMFRECEIVED'
+          self.on_media_dtmf_received(session)
+        end
+      end  
+    end
+    
+    def on_http_res(session)
+    end
+    
+    def on_media_audio_started(session)
+    end
+    
+    def on_media_audio_stopped(session) 
+    end
+    
+    def on_media_dtmf_received(session)
+    end
+    
+    
+    def unknown_request(m)
+      logw("I do not handle request with method #{m}")
+      return false
+    end
+  
+    def method_missing(m, *a)
+      unknown_request( m )
+    end
+    
+    def on_timer(session, task)
+    end
+    
+    # --- Session callbacks -----
+    def no_ack_received(session)
+    end
+    
+    def no_prack_received(session)
+    end
+    
+    def session_being_invalidated_ok_to_proceed?(session)
+      true
+    end
+    # -------------------------
+    
+     
+    def create_session
+      _create_session(DetachedSession, nil, nil, nil)
+    end
+    
+    def create_udp_session(rip=nil, rp=nil, rs=nil)
+      _create_session(UdpSession, rip, rp, rs)
+    end
+    
+    def create_tcp_session(rip, rp)
+    end
+    
+    def create_tls_session(rip, rp)
+    end
+    
+    def create_sctp_session
+    end
+    
+    def _create_session(type, rip, rp, rs)
+      rs ||= self.class.get_pre_existing_route_set
+      s = type.new(rip, rp, rs, self.class.get_session_limit, self.specified_transport)
+      s.controller = self
+      s.set_transaction_usage self.class.get_transaction_usage           #set controller wide usage
+      s.set_transaction_timers(:Base, self.class.get_transaction_timers)  #set controller wide timers
+      s.set_session_timer(self.class.get_session_timer)
+      s.set_session_limit(self.class.get_session_limit)  # redundant as already set in init
+      s.set_transaction_handlers(self.class.get_transaction_handlers)
+      s.set_t2xx_retrans_usage(self.class.get_t2xx_usage)
+      s.set_t1xx_retrans_usage(self.class.get_t1xx_retran_usage)
+      s.set_t2xx_retrans_timers(self.class.get_t2xx_timers)
+      s.set_t1xx_retrans_timers(self.class.get_t1xx_timers)
+      s.set_header_order(self.class.get_header_order)
+      s.set_compact_headers(self.class.get_compact_headers)
+      s.set_session_record(self.class.get_session_record)
+      return s
+    end
+    
+    
+    # enables chaining by detecting interest early
+    def interested?(initial_request)
+       if self.respond_to?(("on_" + initial_request.method.downcase).to_sym)
+         logd("Yes I #{name} is interested")
+         return true
+       else
+         logd("No I #{name} is not interested")
+         return false
+       end
+    end
+    
+    # Returns a transport specified for the controller in the form
+    # [ip, port, transport] where transport is optional and if 
+    #  present can be "UDP" or "TCP". 
+    # While sending the message, this preferred transport will be used
+    # and on receiving the controller will be invoked only if the message
+    # is received on this transport. 
+    # Defining controllers can thus control which transport they are bound 
+    # to. If not present a default transport, based upon the transport 
+    # selection procedure is assigned to the controller. 
+    def specified_transport
+      nil   
+    end
+    
+    # returns an integer indicating the position in order array as used in 
+    # controller selection. -1 indicates to disregard this value. This if present
+    # supercedes the order.yaml. This allows for ordering inline controllers. 
+    def order
+      -1
+    end
+    
+    def registration_store
+      SIP::Locator[:RegistrationStore]
+    end
+    
+    
+    # The dialog info store, keeps track of AOR => ["call_id;local_tag;remote_tag",..]
+    # for the AOR belonging to the UA.
+    def dialog_store
+      SIP::Locator[:DialogInfoStore] 
+    end
+    
+    private :_create_session
+    
+  end
+
+end